Annotation of mandoc/man.3, Revision 1.15
1.15 ! kristaps 1: .\" $Id: man.3,v 1.14 2010/03/30 19:20:33 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.15 ! kristaps 17: .Dd $Mdocdate: March 30 2010 $
1.2 kristaps 18: .Dt MAN 3
1.1 kristaps 19: .Os
1.13 kristaps 20: .
21: .
1.1 kristaps 22: .Sh NAME
1.13 kristaps 23: .Nm man ,
1.1 kristaps 24: .Nm man_alloc ,
25: .Nm man_parseln ,
26: .Nm man_endparse ,
27: .Nm man_node ,
28: .Nm man_meta ,
29: .Nm man_free ,
30: .Nm man_reset
31: .Nd man macro compiler library
1.13 kristaps 32: .
33: .
1.1 kristaps 34: .Sh SYNOPSIS
1.10 kristaps 35: .In man.h
1.1 kristaps 36: .Vt extern const char * const * man_macronames;
37: .Ft "struct man *"
38: .Fn man_alloc "void *data" "int pflags" "const struct man_cb *cb"
39: .Ft void
40: .Fn man_reset "struct man *man"
41: .Ft void
42: .Fn man_free "struct man *man"
43: .Ft int
44: .Fn man_parseln "struct man *man" "int line" "char *buf"
45: .Ft "const struct man_node *"
1.6 kristaps 46: .Fn man_node "const struct man *man"
1.1 kristaps 47: .Ft "const struct man_meta *"
1.6 kristaps 48: .Fn man_meta "const struct man *man"
1.1 kristaps 49: .Ft int
50: .Fn man_endparse "struct man *man"
1.13 kristaps 51: .
52: .
1.1 kristaps 53: .Sh DESCRIPTION
54: The
1.13 kristaps 55: .Nm
1.7 kristaps 56: library parses lines of
1.1 kristaps 57: .Xr man 7
58: input (and
59: .Em only
60: man) into an abstract syntax tree (AST).
1.13 kristaps 61: .
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
78: sequence. See the
79: .Sx EXAMPLES
80: section for a full example.
1.13 kristaps 81: .
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:
88: .
1.1 kristaps 89: .Pp
1.13 kristaps 90: .Bl -tag -width Ds -compact
91: .It am
92: .It ami
93: .It de
94: .It dei
95: .It ig
96: Instructional macros in the original roff language. Blocks begun by
97: these macros end with
98: .Sq ..
99: and may begin anywhere, although they may not break the next-line
100: scoping rules specified in
101: .Xr man 7 .
102: These blocks are discarded.
103: .
104: .It PD
105: Has no effect. Handled as a current-scope line macro.
106: .
107: .It Sp
108: A synonym for
109: .Sq sp 0.5v
110: .Pq part of the standard preamble for Perl documentation .
111: Handled as a line macro.
112: .
113: .It UC
114: Has no effect. Handled as a current-scope line macro.
115: .
116: .It Vb
117: A synonym for
118: .Sq nf
119: .Pq part of the standard preamble for Perl documentation .
120: Handled as a current-scope line macro.
121: .
122: .It Ve
123: A synonym for
124: .Sq fi ,
125: closing
126: .Sq Vb
127: .Pq part of the standard preamble for Perl documentation .
128: Handled as a current-scope line macro.
129: .El
1.14 kristaps 130: .Pp
131: Furthermore, the following escapes are accepted to allow
132: .Xr pod2man 1
1.15 ! kristaps 133: documents to be correctly formatted:
1.14 kristaps 134: \e*(-- (dash),
135: \e*(PI (pi),
136: \e*(L" (left double-quote),
137: \e*(R" (right double-quote),
138: \e*(C+ (C++),
139: \e*(C` (left single-quote),
140: \e*(C' (right single-quote),
141: \e*(Aq (apostrophe),
142: \e*^ (hat),
143: \e*, (comma),
144: \e*~ (tilde),
145: \e*/ (forward slash),
146: \e*: (umlaut),
147: \e*8 (beta),
148: \e*o (degree),
149: \e*(D- (Eth),
150: \e*(d- (eth),
151: \e*(Th (Thorn),
152: and
153: \e*(th (thorn).
1.13 kristaps 154: .
155: .
156: .Sh REFERENCE
1.7 kristaps 157: This section further defines the
1.1 kristaps 158: .Sx Types ,
1.7 kristaps 159: .Sx Functions
1.1 kristaps 160: and
161: .Sx Variables
162: available to programmers. Following that, the
1.7 kristaps 163: .Sx Abstract Syntax Tree
1.1 kristaps 164: section documents the output tree.
1.13 kristaps 165: .
166: .
1.1 kristaps 167: .Ss Types
168: Both functions (see
169: .Sx Functions )
170: and variables (see
171: .Sx Variables )
172: may use the following types:
1.12 kristaps 173: .Bl -ohang
1.13 kristaps 174: .
1.1 kristaps 175: .It Vt struct man
176: An opaque type defined in
177: .Pa man.c .
178: Its values are only used privately within the library.
1.13 kristaps 179: .
1.1 kristaps 180: .It Vt struct man_cb
181: A set of message callbacks defined in
182: .Pa man.h .
1.13 kristaps 183: .
1.1 kristaps 184: .It Vt struct man_node
185: A parsed node. Defined in
186: .Pa man.h .
1.7 kristaps 187: See
1.1 kristaps 188: .Sx Abstract Syntax Tree
189: for details.
190: .El
1.13 kristaps 191: .
192: .
1.1 kristaps 193: .Ss Functions
194: Function descriptions follow:
1.12 kristaps 195: .Bl -ohang
1.13 kristaps 196: .
1.1 kristaps 197: .It Fn man_alloc
198: Allocates a parsing structure. The
199: .Fa data
200: pointer is passed to callbacks in
1.7 kristaps 201: .Fa cb ,
202: which are documented further in the header file.
1.1 kristaps 203: The
204: .Fa pflags
205: arguments are defined in
206: .Pa man.h .
207: Returns NULL on failure. If non-NULL, the pointer must be freed with
208: .Fn man_free .
1.13 kristaps 209: .
1.1 kristaps 210: .It Fn man_reset
1.7 kristaps 211: Reset the parser for another parse routine. After its use,
1.1 kristaps 212: .Fn man_parseln
213: behaves as if invoked for the first time.
1.13 kristaps 214: .
1.1 kristaps 215: .It Fn man_free
216: Free all resources of a parser. The pointer is no longer valid after
217: invocation.
1.13 kristaps 218: .
1.1 kristaps 219: .It Fn man_parseln
220: Parse a nil-terminated line of input. This line should not contain the
1.7 kristaps 221: trailing newline. Returns 0 on failure, 1 on success. The input buffer
1.1 kristaps 222: .Fa buf
223: is modified by this function.
1.13 kristaps 224: .
1.1 kristaps 225: .It Fn man_endparse
1.7 kristaps 226: Signals that the parse is complete. Note that if
1.1 kristaps 227: .Fn man_endparse
228: is called subsequent to
229: .Fn man_node ,
230: the resulting tree is incomplete. Returns 0 on failure, 1 on success.
1.13 kristaps 231: .
1.1 kristaps 232: .It Fn man_node
1.7 kristaps 233: Returns the first node of the parse. Note that if
1.1 kristaps 234: .Fn man_parseln
235: or
236: .Fn man_endparse
237: return 0, the tree will be incomplete.
238: .It Fn man_meta
239: Returns the document's parsed meta-data. If this information has not
1.7 kristaps 240: yet been supplied or
1.1 kristaps 241: .Fn man_parseln
242: or
243: .Fn man_endparse
244: return 0, the data will be incomplete.
245: .El
1.13 kristaps 246: .
247: .
1.1 kristaps 248: .Ss Variables
249: The following variables are also defined:
1.12 kristaps 250: .Bl -ohang
1.13 kristaps 251: .
1.1 kristaps 252: .It Va man_macronames
253: An array of string-ified token names.
254: .El
1.13 kristaps 255: .
256: .
1.1 kristaps 257: .Ss Abstract Syntax Tree
1.7 kristaps 258: The
1.1 kristaps 259: .Nm
260: functions produce an abstract syntax tree (AST) describing input in a
261: regular form. It may be reviewed at any time with
262: .Fn man_nodes ;
263: however, if called before
264: .Fn man_endparse ,
265: or after
1.7 kristaps 266: .Fn man_endparse
1.1 kristaps 267: or
268: .Fn man_parseln
1.7 kristaps 269: fail, it may be incomplete.
1.13 kristaps 270: .
1.1 kristaps 271: .Pp
272: This AST is governed by the ontological
273: rules dictated in
274: .Xr man 7
1.7 kristaps 275: and derives its terminology accordingly.
1.13 kristaps 276: .
1.1 kristaps 277: .Pp
1.7 kristaps 278: The AST is composed of
1.1 kristaps 279: .Vt struct man_node
280: nodes with element, root and text types as declared
281: by the
282: .Va type
283: field. Each node also provides its parse point (the
284: .Va line ,
285: .Va sec ,
286: and
287: .Va pos
288: fields), its position in the tree (the
289: .Va parent ,
290: .Va child ,
1.7 kristaps 291: .Va next
1.1 kristaps 292: and
1.7 kristaps 293: .Va prev
1.1 kristaps 294: fields) and some type-specific data.
1.13 kristaps 295: .
1.1 kristaps 296: .Pp
297: The tree itself is arranged according to the following normal form,
298: where capitalised non-terminals represent nodes.
299: .Pp
1.12 kristaps 300: .Bl -tag -width "ELEMENTXX" -compact
1.1 kristaps 301: .It ROOT
302: \(<- mnode+
303: .It mnode
1.8 kristaps 304: \(<- ELEMENT | TEXT | BLOCK
305: .It BLOCK
306: \(<- HEAD BODY
307: .It HEAD
308: \(<- mnode*
309: .It BODY
310: \(<- mnode*
1.1 kristaps 311: .It ELEMENT
312: \(<- ELEMENT | TEXT*
313: .It TEXT
314: \(<- [[:alpha:]]*
315: .El
1.13 kristaps 316: .
1.1 kristaps 317: .Pp
318: The only elements capable of nesting other elements are those with
319: next-lint scope as documented in
320: .Xr man 7 .
1.13 kristaps 321: .
322: .
1.1 kristaps 323: .Sh EXAMPLES
324: The following example reads lines from stdin and parses them, operating
1.7 kristaps 325: on the finished parse tree with
1.1 kristaps 326: .Fn parsed .
1.12 kristaps 327: This example does not error-check nor free memory upon failure.
328: .Bd -literal -offset indent
1.1 kristaps 329: struct man *man;
330: struct man_node *node;
331: char *buf;
332: size_t len;
333: int line;
334:
335: line = 1;
336: man = man_alloc(NULL, 0, NULL);
1.12 kristaps 337: buf = NULL;
338: alloc_len = 0;
1.1 kristaps 339:
1.12 kristaps 340: while ((len = getline(&buf, &alloc_len, stdin)) >= 0) {
341: if (len && buflen[len - 1] = '\en')
342: buf[len - 1] = '\e0';
343: if ( ! man_parseln(man, line, buf))
344: errx(1, "man_parseln");
345: line++;
1.1 kristaps 346: }
347:
1.12 kristaps 348: free(buf);
349:
1.1 kristaps 350: if ( ! man_endparse(man))
1.12 kristaps 351: errx(1, "man_endparse");
1.1 kristaps 352: if (NULL == (node = man_node(man)))
1.12 kristaps 353: errx(1, "man_node");
1.1 kristaps 354:
355: parsed(man, node);
356: man_free(man);
357: .Ed
1.13 kristaps 358: .
359: .
1.1 kristaps 360: .Sh SEE ALSO
361: .Xr mandoc 1 ,
362: .Xr man 7
1.13 kristaps 363: .
364: .
1.1 kristaps 365: .Sh AUTHORS
366: The
367: .Nm
1.7 kristaps 368: utility was written by
1.12 kristaps 369: .An Kristaps Dzonsons Aq kristaps@bsd.lv .
CVSweb