Annotation of mandoc/man.3, Revision 1.24
1.24 ! schwarze 1: .\" $Id: man.3,v 1.23 2010/08/16 09:51:17 kristaps Exp $
1.1 kristaps 2: .\"
1.12 kristaps 3: .\" Copyright (c) 2009-2010 Kristaps Dzonsons <kristaps@bsd.lv>
1.1 kristaps 4: .\"
5: .\" Permission to use, copy, modify, and distribute this software for any
1.3 kristaps 6: .\" purpose with or without fee is hereby granted, provided that the above
7: .\" copyright notice and this permission notice appear in all copies.
8: .\"
9: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
1.1 kristaps 16: .\"
1.24 ! schwarze 17: .Dd $Mdocdate: August 16 2010 $
1.2 kristaps 18: .Dt MAN 3
1.1 kristaps 19: .Os
20: .Sh NAME
1.13 kristaps 21: .Nm man ,
1.1 kristaps 22: .Nm man_alloc ,
23: .Nm man_endparse ,
1.17 kristaps 24: .Nm man_free ,
25: .Nm man_meta ,
1.1 kristaps 26: .Nm man_node ,
1.17 kristaps 27: .Nm man_parseln ,
1.1 kristaps 28: .Nm man_reset
29: .Nd man macro compiler library
30: .Sh SYNOPSIS
1.17 kristaps 31: .In mandoc.h
1.10 kristaps 32: .In man.h
1.1 kristaps 33: .Vt extern const char * const * man_macronames;
34: .Ft "struct man *"
1.20 kristaps 35: .Fo man_alloc
1.21 kristaps 36: .Fa "struct regset *regs"
1.20 kristaps 37: .Fa "void *data"
38: .Fa "mandocmsg msgs"
39: .Fc
1.17 kristaps 40: .Ft int
41: .Fn man_endparse "struct man *man"
1.1 kristaps 42: .Ft void
43: .Fn man_free "struct man *man"
1.17 kristaps 44: .Ft "const struct man_meta *"
45: .Fn man_meta "const struct man *man"
1.1 kristaps 46: .Ft "const struct man_node *"
1.6 kristaps 47: .Fn man_node "const struct man *man"
1.1 kristaps 48: .Ft int
1.19 kristaps 49: .Fo man_parseln
50: .Fa "struct man *man"
51: .Fa "int line"
52: .Fa "char *buf"
53: .Fc
1.17 kristaps 54: .Ft void
55: .Fn man_reset "struct man *man"
1.1 kristaps 56: .Sh DESCRIPTION
57: The
1.13 kristaps 58: .Nm
1.7 kristaps 59: library parses lines of
1.1 kristaps 60: .Xr man 7
1.17 kristaps 61: input into an abstract syntax tree (AST).
1.1 kristaps 62: .Pp
63: In general, applications initiate a parsing sequence with
64: .Fn man_alloc ,
1.7 kristaps 65: parse each line in a document with
1.1 kristaps 66: .Fn man_parseln ,
67: close the parsing session with
68: .Fn man_endparse ,
69: operate over the syntax tree returned by
1.7 kristaps 70: .Fn man_node
1.1 kristaps 71: and
72: .Fn man_meta ,
73: then free all allocated memory with
74: .Fn man_free .
75: The
76: .Fn man_reset
77: function may be used in order to reset the parser for another input
1.17 kristaps 78: sequence.
79: See the
1.1 kristaps 80: .Sx EXAMPLES
81: section for a full example.
1.13 kristaps 82: .Pp
83: Beyond the full set of macros defined in
84: .Xr man 7 ,
85: the
86: .Nm
87: library also accepts the following macros:
1.1 kristaps 88: .Pp
1.13 kristaps 89: .Bl -tag -width Ds -compact
90: .It PD
91: Has no effect. Handled as a current-scope line macro.
92: .It Sp
93: A synonym for
94: .Sq sp 0.5v
95: .Pq part of the standard preamble for Perl documentation .
96: Handled as a line macro.
97: .It Vb
98: A synonym for
99: .Sq nf
100: .Pq part of the standard preamble for Perl documentation .
101: Handled as a current-scope line macro.
102: .It Ve
103: A synonym for
104: .Sq fi ,
105: closing
106: .Sq Vb
107: .Pq part of the standard preamble for Perl documentation .
108: Handled as a current-scope line macro.
109: .El
1.14 kristaps 110: .Pp
111: Furthermore, the following escapes are accepted to allow
112: .Xr pod2man 1
1.15 kristaps 113: documents to be correctly formatted:
1.14 kristaps 114: \e*(-- (dash),
115: \e*(PI (pi),
116: \e*(L" (left double-quote),
117: \e*(R" (right double-quote),
118: \e*(C` (left single-quote),
119: \e*(C' (right single-quote),
120: \e*(Aq (apostrophe),
121: \e*^ (hat),
122: \e*, (comma),
123: \e*~ (tilde),
124: \e*/ (forward slash),
125: \e*: (umlaut),
126: \e*8 (beta),
127: \e*o (degree),
128: \e*(D- (Eth),
129: \e*(d- (eth),
130: \e*(Th (Thorn),
131: and
132: \e*(th (thorn).
1.13 kristaps 133: .Sh REFERENCE
1.7 kristaps 134: This section further defines the
1.1 kristaps 135: .Sx Types ,
1.7 kristaps 136: .Sx Functions
1.1 kristaps 137: and
138: .Sx Variables
1.17 kristaps 139: available to programmers.
140: Following that, the
1.7 kristaps 141: .Sx Abstract Syntax Tree
1.1 kristaps 142: section documents the output tree.
143: .Ss Types
144: Both functions (see
145: .Sx Functions )
146: and variables (see
147: .Sx Variables )
148: may use the following types:
1.12 kristaps 149: .Bl -ohang
1.1 kristaps 150: .It Vt struct man
151: An opaque type defined in
152: .Pa man.c .
153: Its values are only used privately within the library.
1.17 kristaps 154: .It Vt mandocmsg
155: A function callback type defined in
156: .Pa mandoc.h .
1.1 kristaps 157: .It Vt struct man_node
1.17 kristaps 158: A parsed node.
159: Defined in
1.1 kristaps 160: .Pa man.h .
1.7 kristaps 161: See
1.1 kristaps 162: .Sx Abstract Syntax Tree
163: for details.
164: .El
165: .Ss Functions
166: Function descriptions follow:
1.12 kristaps 167: .Bl -ohang
1.1 kristaps 168: .It Fn man_alloc
1.17 kristaps 169: Allocates a parsing structure.
170: The
1.1 kristaps 171: .Fa data
1.18 kristaps 172: pointer is passed to
173: .Fa msgs .
1.17 kristaps 174: Returns NULL on failure.
175: If non-NULL, the pointer must be freed with
1.1 kristaps 176: .Fn man_free .
177: .It Fn man_reset
1.17 kristaps 178: Reset the parser for another parse routine.
179: After its use,
1.1 kristaps 180: .Fn man_parseln
181: behaves as if invoked for the first time.
182: .It Fn man_free
1.17 kristaps 183: Free all resources of a parser.
184: The pointer is no longer valid after invocation.
1.1 kristaps 185: .It Fn man_parseln
1.17 kristaps 186: Parse a nil-terminated line of input.
187: This line should not contain the trailing newline.
188: Returns 0 on failure, 1 on success.
189: The input buffer
1.1 kristaps 190: .Fa buf
191: is modified by this function.
192: .It Fn man_endparse
1.17 kristaps 193: Signals that the parse is complete.
194: Note that if
1.1 kristaps 195: .Fn man_endparse
196: is called subsequent to
197: .Fn man_node ,
1.17 kristaps 198: the resulting tree is incomplete.
199: Returns 0 on failure, 1 on success.
1.1 kristaps 200: .It Fn man_node
1.17 kristaps 201: Returns the first node of the parse.
202: Note that if
1.1 kristaps 203: .Fn man_parseln
204: or
205: .Fn man_endparse
206: return 0, the tree will be incomplete.
207: .It Fn man_meta
1.17 kristaps 208: Returns the document's parsed meta-data.
209: If this information has not yet been supplied or
1.1 kristaps 210: .Fn man_parseln
211: or
212: .Fn man_endparse
213: return 0, the data will be incomplete.
214: .El
215: .Ss Variables
216: The following variables are also defined:
1.12 kristaps 217: .Bl -ohang
1.1 kristaps 218: .It Va man_macronames
219: An array of string-ified token names.
220: .El
221: .Ss Abstract Syntax Tree
1.7 kristaps 222: The
1.1 kristaps 223: .Nm
224: functions produce an abstract syntax tree (AST) describing input in a
1.17 kristaps 225: regular form.
226: It may be reviewed at any time with
1.1 kristaps 227: .Fn man_nodes ;
228: however, if called before
229: .Fn man_endparse ,
230: or after
1.7 kristaps 231: .Fn man_endparse
1.1 kristaps 232: or
233: .Fn man_parseln
1.7 kristaps 234: fail, it may be incomplete.
1.1 kristaps 235: .Pp
1.17 kristaps 236: This AST is governed by the ontological rules dictated in
1.1 kristaps 237: .Xr man 7
1.7 kristaps 238: and derives its terminology accordingly.
1.1 kristaps 239: .Pp
1.7 kristaps 240: The AST is composed of
1.1 kristaps 241: .Vt struct man_node
1.17 kristaps 242: nodes with element, root and text types as declared by the
1.1 kristaps 243: .Va type
1.17 kristaps 244: field.
245: Each node also provides its parse point (the
1.1 kristaps 246: .Va line ,
247: .Va sec ,
248: and
249: .Va pos
250: fields), its position in the tree (the
251: .Va parent ,
252: .Va child ,
1.7 kristaps 253: .Va next
1.1 kristaps 254: and
1.7 kristaps 255: .Va prev
1.1 kristaps 256: fields) and some type-specific data.
257: .Pp
258: The tree itself is arranged according to the following normal form,
259: where capitalised non-terminals represent nodes.
260: .Pp
1.12 kristaps 261: .Bl -tag -width "ELEMENTXX" -compact
1.1 kristaps 262: .It ROOT
263: \(<- mnode+
264: .It mnode
1.8 kristaps 265: \(<- ELEMENT | TEXT | BLOCK
266: .It BLOCK
267: \(<- HEAD BODY
268: .It HEAD
269: \(<- mnode*
270: .It BODY
271: \(<- mnode*
1.1 kristaps 272: .It ELEMENT
273: \(<- ELEMENT | TEXT*
274: .It TEXT
275: \(<- [[:alpha:]]*
276: .El
277: .Pp
278: The only elements capable of nesting other elements are those with
279: next-lint scope as documented in
280: .Xr man 7 .
281: .Sh EXAMPLES
282: The following example reads lines from stdin and parses them, operating
1.7 kristaps 283: on the finished parse tree with
1.1 kristaps 284: .Fn parsed .
1.12 kristaps 285: This example does not error-check nor free memory upon failure.
286: .Bd -literal -offset indent
1.21 kristaps 287: struct regset regs;
1.1 kristaps 288: struct man *man;
289: struct man_node *node;
290: char *buf;
291: size_t len;
292: int line;
293:
1.21 kristaps 294: bzero(®s, sizeof(struct regset));
1.1 kristaps 295: line = 1;
1.24 ! schwarze 296: man = man_alloc(®s, NULL, NULL);
1.12 kristaps 297: buf = NULL;
298: alloc_len = 0;
1.1 kristaps 299:
1.12 kristaps 300: while ((len = getline(&buf, &alloc_len, stdin)) >= 0) {
301: if (len && buflen[len - 1] = '\en')
302: buf[len - 1] = '\e0';
303: if ( ! man_parseln(man, line, buf))
304: errx(1, "man_parseln");
305: line++;
1.1 kristaps 306: }
307:
1.12 kristaps 308: free(buf);
309:
1.1 kristaps 310: if ( ! man_endparse(man))
1.12 kristaps 311: errx(1, "man_endparse");
1.1 kristaps 312: if (NULL == (node = man_node(man)))
1.12 kristaps 313: errx(1, "man_node");
1.1 kristaps 314:
315: parsed(man, node);
316: man_free(man);
317: .Ed
1.17 kristaps 318: .Pp
319: Please see
320: .Pa main.c
321: in the source archive for a rigorous reference.
1.1 kristaps 322: .Sh SEE ALSO
323: .Xr mandoc 1 ,
324: .Xr man 7
325: .Sh AUTHORS
326: The
327: .Nm
1.17 kristaps 328: library was written by
1.12 kristaps 329: .An Kristaps Dzonsons Aq kristaps@bsd.lv .
CVSweb