Annotation of mandoc/man.3, Revision 1.11
1.11 ! kristaps 1: .\" $Id: man.3,v 1.10 2009/10/03 16:36:06 kristaps Exp $
1.1 kristaps 2: .\"
1.4 kristaps 3: .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
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: .\"
17: .Dd $Mdocdate$
1.2 kristaps 18: .Dt MAN 3
1.1 kristaps 19: .Os
20: .\" SECTION
21: .Sh NAME
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: .\" SECTION
31: .Sh SYNOPSIS
1.10 kristaps 32: .In man.h
1.1 kristaps 33: .Vt extern const char * const * man_macronames;
34: .Ft "struct man *"
35: .Fn man_alloc "void *data" "int pflags" "const struct man_cb *cb"
36: .Ft void
37: .Fn man_reset "struct man *man"
38: .Ft void
39: .Fn man_free "struct man *man"
40: .Ft int
41: .Fn man_parseln "struct man *man" "int line" "char *buf"
42: .Ft "const struct man_node *"
1.6 kristaps 43: .Fn man_node "const struct man *man"
1.1 kristaps 44: .Ft "const struct man_meta *"
1.6 kristaps 45: .Fn man_meta "const struct man *man"
1.1 kristaps 46: .Ft int
47: .Fn man_endparse "struct man *man"
48: .\" SECTION
49: .Sh DESCRIPTION
50: The
51: .Nm man
1.7 kristaps 52: library parses lines of
1.1 kristaps 53: .Xr man 7
54: input (and
55: .Em only
56: man) into an abstract syntax tree (AST).
57: .\" PARAGRAPH
58: .Pp
59: In general, applications initiate a parsing sequence with
60: .Fn man_alloc ,
1.7 kristaps 61: parse each line in a document with
1.1 kristaps 62: .Fn man_parseln ,
63: close the parsing session with
64: .Fn man_endparse ,
65: operate over the syntax tree returned by
1.7 kristaps 66: .Fn man_node
1.1 kristaps 67: and
68: .Fn man_meta ,
69: then free all allocated memory with
70: .Fn man_free .
71: The
72: .Fn man_reset
73: function may be used in order to reset the parser for another input
74: sequence. See the
75: .Sx EXAMPLES
76: section for a full example.
77: .\" PARAGRAPH
78: .Pp
1.7 kristaps 79: This section further defines the
1.1 kristaps 80: .Sx Types ,
1.7 kristaps 81: .Sx Functions
1.1 kristaps 82: and
83: .Sx Variables
84: available to programmers. Following that, the
1.7 kristaps 85: .Sx Abstract Syntax Tree
1.1 kristaps 86: section documents the output tree.
87: .\" SUBSECTION
88: .Ss Types
89: Both functions (see
90: .Sx Functions )
91: and variables (see
92: .Sx Variables )
93: may use the following types:
94: .Bl -ohang -offset "XXXX"
95: .\" LIST-ITEM
96: .It Vt struct man
97: An opaque type defined in
98: .Pa man.c .
99: Its values are only used privately within the library.
100: .\" LIST-ITEM
101: .It Vt struct man_cb
102: A set of message callbacks defined in
103: .Pa man.h .
104: .\" LIST-ITEM
105: .It Vt struct man_node
106: A parsed node. Defined in
107: .Pa man.h .
1.7 kristaps 108: See
1.1 kristaps 109: .Sx Abstract Syntax Tree
110: for details.
111: .El
112: .\" SUBSECTION
113: .Ss Functions
114: Function descriptions follow:
115: .Bl -ohang -offset "XXXX"
116: .\" LIST-ITEM
117: .It Fn man_alloc
118: Allocates a parsing structure. The
119: .Fa data
120: pointer is passed to callbacks in
1.7 kristaps 121: .Fa cb ,
122: which are documented further in the header file.
1.1 kristaps 123: The
124: .Fa pflags
125: arguments are defined in
126: .Pa man.h .
127: Returns NULL on failure. If non-NULL, the pointer must be freed with
128: .Fn man_free .
129: .\" LIST-ITEM
130: .It Fn man_reset
1.7 kristaps 131: Reset the parser for another parse routine. After its use,
1.1 kristaps 132: .Fn man_parseln
133: behaves as if invoked for the first time.
134: .\" LIST-ITEM
135: .It Fn man_free
136: Free all resources of a parser. The pointer is no longer valid after
137: invocation.
138: .\" LIST-ITEM
139: .It Fn man_parseln
140: Parse a nil-terminated line of input. This line should not contain the
1.7 kristaps 141: trailing newline. Returns 0 on failure, 1 on success. The input buffer
1.1 kristaps 142: .Fa buf
143: is modified by this function.
144: .\" LIST-ITEM
145: .It Fn man_endparse
1.7 kristaps 146: Signals that the parse is complete. Note that if
1.1 kristaps 147: .Fn man_endparse
148: is called subsequent to
149: .Fn man_node ,
150: the resulting tree is incomplete. Returns 0 on failure, 1 on success.
151: .\" LIST-ITEM
152: .It Fn man_node
1.7 kristaps 153: Returns the first node of the parse. Note that if
1.1 kristaps 154: .Fn man_parseln
155: or
156: .Fn man_endparse
157: return 0, the tree will be incomplete.
158: .It Fn man_meta
159: Returns the document's parsed meta-data. If this information has not
1.7 kristaps 160: yet been supplied or
1.1 kristaps 161: .Fn man_parseln
162: or
163: .Fn man_endparse
164: return 0, the data will be incomplete.
165: .El
166: .\" SUBSECTION
167: .Ss Variables
168: The following variables are also defined:
169: .Bl -ohang -offset "XXXX"
170: .\" LIST-ITEM
171: .It Va man_macronames
172: An array of string-ified token names.
173: .El
174: .\" SUBSECTION
175: .Ss Abstract Syntax Tree
1.7 kristaps 176: The
1.1 kristaps 177: .Nm
178: functions produce an abstract syntax tree (AST) describing input in a
179: regular form. It may be reviewed at any time with
180: .Fn man_nodes ;
181: however, if called before
182: .Fn man_endparse ,
183: or after
1.7 kristaps 184: .Fn man_endparse
1.1 kristaps 185: or
186: .Fn man_parseln
1.7 kristaps 187: fail, it may be incomplete.
1.1 kristaps 188: .\" PARAGRAPH
189: .Pp
190: This AST is governed by the ontological
191: rules dictated in
192: .Xr man 7
1.7 kristaps 193: and derives its terminology accordingly.
1.1 kristaps 194: .\" PARAGRAPH
195: .Pp
1.7 kristaps 196: The AST is composed of
1.1 kristaps 197: .Vt struct man_node
198: nodes with element, root and text types as declared
199: by the
200: .Va type
201: field. Each node also provides its parse point (the
202: .Va line ,
203: .Va sec ,
204: and
205: .Va pos
206: fields), its position in the tree (the
207: .Va parent ,
208: .Va child ,
1.7 kristaps 209: .Va next
1.1 kristaps 210: and
1.7 kristaps 211: .Va prev
1.1 kristaps 212: fields) and some type-specific data.
213: .\" PARAGRAPH
214: .Pp
215: The tree itself is arranged according to the following normal form,
216: where capitalised non-terminals represent nodes.
217: .Pp
218: .Bl -tag -width "ELEMENTXX" -compact -offset "XXXX"
219: .\" LIST-ITEM
220: .It ROOT
221: \(<- mnode+
222: .It mnode
1.8 kristaps 223: \(<- ELEMENT | TEXT | BLOCK
224: .It BLOCK
225: \(<- HEAD BODY
226: .It HEAD
227: \(<- mnode*
228: .It BODY
229: \(<- mnode*
1.1 kristaps 230: .It ELEMENT
231: \(<- ELEMENT | TEXT*
232: .It TEXT
233: \(<- [[:alpha:]]*
234: .El
235: .\" PARAGRAPH
236: .Pp
237: The only elements capable of nesting other elements are those with
238: next-lint scope as documented in
239: .Xr man 7 .
240: .\" SECTION
241: .Sh EXAMPLES
242: The following example reads lines from stdin and parses them, operating
1.7 kristaps 243: on the finished parse tree with
1.1 kristaps 244: .Fn parsed .
245: Note that, if the last line of the file isn't newline-terminated, this
1.7 kristaps 246: will truncate the file's last character (see
1.1 kristaps 247: .Xr fgetln 3 ) .
248: Further, this example does not error-check nor free memory upon failure.
249: .Bd -literal -offset "XXXX"
250: struct man *man;
251: struct man_node *node;
252: char *buf;
253: size_t len;
254: int line;
255:
256: line = 1;
257: man = man_alloc(NULL, 0, NULL);
258:
259: while ((buf = fgetln(fp, &len))) {
1.11 ! kristaps 260: buf[len - 1] = '\e0';
1.1 kristaps 261: if ( ! man_parseln(man, line, buf))
262: errx(1, "man_parseln");
263: line++;
264: }
265:
266: if ( ! man_endparse(man))
267: errx(1, "man_endparse");
268: if (NULL == (node = man_node(man)))
269: errx(1, "man_node");
270:
271: parsed(man, node);
272: man_free(man);
273: .Ed
274: .\" SECTION
275: .Sh SEE ALSO
276: .Xr mandoc 1 ,
277: .Xr man 7
278: .\" SECTION
279: .Sh AUTHORS
280: The
281: .Nm
1.7 kristaps 282: utility was written by
1.5 kristaps 283: .An Kristaps Dzonsons Aq kristaps@kth.se .
CVSweb