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