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