Annotation of mandoc/mdoc.3, Revision 1.29
1.29 ! kristaps 1: .\" $Id: mdoc.3,v 1.28 2009/04/12 19:45:26 kristaps Exp $
1.6 kristaps 2: .\"
1.29 ! kristaps 3: .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
1.6 kristaps 4: .\"
5: .\" Permission to use, copy, modify, and distribute this software for any
1.28 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.
1.6 kristaps 8: .\"
1.28 kristaps 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.27 kristaps 18: .Dt MDOC 3
1.1 kristaps 19: .Os
1.6 kristaps 20: .\" SECTION
1.1 kristaps 21: .Sh NAME
22: .Nm mdoc_alloc ,
23: .Nm mdoc_parseln ,
24: .Nm mdoc_endparse ,
1.4 kristaps 25: .Nm mdoc_node ,
26: .Nm mdoc_meta ,
1.20 kristaps 27: .Nm mdoc_free ,
28: .Nm mdoc_reset
1.2 kristaps 29: .Nd mdoc macro compiler library
1.6 kristaps 30: .\" SECTION
1.1 kristaps 31: .Sh SYNOPSIS
1.4 kristaps 32: .Fd #include <mdoc.h>
33: .Vt extern const char * const * mdoc_macronames;
34: .Vt extern const char * const * mdoc_argnames;
1.1 kristaps 35: .Ft "struct mdoc *"
1.20 kristaps 36: .Fn mdoc_alloc "void *data" "int pflags" "const struct mdoc_cb *cb"
1.26 kristaps 37: .Ft int
1.20 kristaps 38: .Fn mdoc_reset "struct mdoc *mdoc"
1.1 kristaps 39: .Ft void
1.2 kristaps 40: .Fn mdoc_free "struct mdoc *mdoc"
1.1 kristaps 41: .Ft int
1.2 kristaps 42: .Fn mdoc_parseln "struct mdoc *mdoc" "int line" "char *buf"
1.1 kristaps 43: .Ft "const struct mdoc_node *"
1.4 kristaps 44: .Fn mdoc_node "struct mdoc *mdoc"
45: .Ft "const struct mdoc_meta *"
46: .Fn mdoc_meta "struct mdoc *mdoc"
1.1 kristaps 47: .Ft int
1.2 kristaps 48: .Fn mdoc_endparse "struct mdoc *mdoc"
1.6 kristaps 49: .\" SECTION
1.1 kristaps 50: .Sh DESCRIPTION
51: The
52: .Nm mdoc
1.17 kristaps 53: library parses lines of
54: .Xr mdoc 7
55: input (and
56: .Em only
1.25 kristaps 57: mdoc) into an abstract syntax tree (AST).
1.6 kristaps 58: .\" PARAGRAPH
59: .Pp
1.1 kristaps 60: In general, applications initiate a parsing sequence with
61: .Fn mdoc_alloc ,
62: parse each line in a document with
63: .Fn mdoc_parseln ,
64: close the parsing session with
65: .Fn mdoc_endparse ,
66: operate over the syntax tree returned by
1.4 kristaps 67: .Fn mdoc_node
68: and
69: .Fn mdoc_meta ,
1.1 kristaps 70: then free all allocated memory with
71: .Fn mdoc_free .
1.20 kristaps 72: The
73: .Fn mdoc_reset
74: function may be used in order to reset the parser for another input
75: sequence. See the
1.1 kristaps 76: .Sx EXAMPLES
77: section for a full example.
1.6 kristaps 78: .\" PARAGRAPH
1.2 kristaps 79: .Pp
1.6 kristaps 80: This section further defines the
81: .Sx Types ,
82: .Sx Functions
83: and
84: .Sx Variables
1.17 kristaps 85: available to programmers. Following that, the
86: .Sx Abstract Syntax Tree
87: section documents the output tree.
1.6 kristaps 88: .\" SUBSECTION
89: .Ss Types
90: Both functions (see
91: .Sx Functions )
92: and variables (see
93: .Sx Variables )
94: may use the following types:
1.9 kristaps 95: .Bl -ohang -offset "XXXX"
1.6 kristaps 96: .\" LIST-ITEM
97: .It Vt struct mdoc
98: An opaque type defined in
99: .Pa mdoc.c .
100: Its values are only used privately within the library.
101: .\" LIST-ITEM
102: .It Vt struct mdoc_cb
103: A set of message callbacks defined in
104: .Pa mdoc.h .
105: .\" LIST-ITEM
106: .It Vt struct mdoc_node
107: A parsed node. Defined in
108: .Pa mdoc.h .
109: See
110: .Sx Abstract Syntax Tree
111: for details.
112: .El
113: .\" SUBSECTION
114: .Ss Functions
1.2 kristaps 115: Function descriptions follow:
1.9 kristaps 116: .Bl -ohang -offset "XXXX"
1.6 kristaps 117: .\" LIST-ITEM
1.2 kristaps 118: .It Fn mdoc_alloc
119: Allocates a parsing structure. The
120: .Fa data
121: pointer is passed to callbacks in
122: .Fa cb ,
1.20 kristaps 123: which are documented further in the header file.
124: The
125: .Fa pflags
126: arguments are defined in
127: .Pa mdoc.h .
128: Returns NULL on failure. If non-NULL, the pointer must be freed with
1.2 kristaps 129: .Fn mdoc_free .
1.6 kristaps 130: .\" LIST-ITEM
1.20 kristaps 131: .It Fn mdoc_reset
132: Reset the parser for another parse routine. After its use,
133: .Fn mdoc_parseln
1.26 kristaps 134: behaves as if invoked for the first time. If it returns 0, memory could
135: not be allocated.
1.20 kristaps 136: .\" LIST-ITEM
1.2 kristaps 137: .It Fn mdoc_free
138: Free all resources of a parser. The pointer is no longer valid after
139: invocation.
1.6 kristaps 140: .\" LIST-ITEM
1.2 kristaps 141: .It Fn mdoc_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.
1.6 kristaps 146: .\" LIST-ITEM
1.2 kristaps 147: .It Fn mdoc_endparse
148: Signals that the parse is complete. Note that if
149: .Fn mdoc_endparse
150: is called subsequent to
1.4 kristaps 151: .Fn mdoc_node ,
1.2 kristaps 152: the resulting tree is incomplete. Returns 0 on failure, 1 on success.
1.6 kristaps 153: .\" LIST-ITEM
1.4 kristaps 154: .It Fn mdoc_node
155: Returns the first node of the parse. Note that if
1.2 kristaps 156: .Fn mdoc_parseln
157: or
158: .Fn mdoc_endparse
159: return 0, the tree will be incomplete.
1.4 kristaps 160: .It Fn mdoc_meta
161: Returns the document's parsed meta-data. If this information has not
162: yet been supplied or
163: .Fn mdoc_parseln
164: or
165: .Fn mdoc_endparse
166: return 0, the data will be incomplete.
167: .El
1.6 kristaps 168: .\" SUBSECTION
169: .Ss Variables
1.4 kristaps 170: The following variables are also defined:
1.9 kristaps 171: .Bl -ohang -offset "XXXX"
1.6 kristaps 172: .\" LIST-ITEM
1.4 kristaps 173: .It Va mdoc_macronames
174: An array of string-ified token names.
1.6 kristaps 175: .\" LIST-ITEM
1.4 kristaps 176: .It Va mdoc_argnames
177: An array of string-ified token argument names.
1.2 kristaps 178: .El
1.6 kristaps 179: .\" SUBSECTION
180: .Ss Abstract Syntax Tree
181: The
182: .Nm
1.17 kristaps 183: functions produce an abstract syntax tree (AST) describing input in a
184: regular form. It may be reviewed at any time with
1.6 kristaps 185: .Fn mdoc_nodes ;
186: however, if called before
187: .Fn mdoc_endparse ,
188: or after
189: .Fn mdoc_endparse
190: or
191: .Fn mdoc_parseln
1.18 kristaps 192: fail, it may be incomplete.
193: .\" PARAGRAPH
194: .Pp
195: This AST is governed by the ontological
1.17 kristaps 196: rules dictated in
197: .Xr mdoc 7
198: and derives its terminology accordingly.
199: .Qq In-line
200: elements described in
201: .Xr mdoc 7
202: are described simply as
203: .Qq elements .
1.6 kristaps 204: .\" PARAGRAPH
205: .Pp
206: The AST is composed of
207: .Vt struct mdoc_node
208: nodes with block, head, body, element, root and text types as declared
209: by the
210: .Va type
211: field. Each node also provides its parse point (the
212: .Va line ,
213: .Va sec ,
214: and
215: .Va pos
216: fields), its position in the tree (the
217: .Va parent ,
218: .Va child ,
219: .Va next
220: and
221: .Va prev
1.25 kristaps 222: fields) and some type-specific data.
1.6 kristaps 223: .\" PARAGRAPH
224: .Pp
225: The tree itself is arranged according to the following normal form,
226: where capitalised non-terminals represent nodes.
227: .Pp
1.9 kristaps 228: .Bl -tag -width "ELEMENTXX" -compact -offset "XXXX"
1.6 kristaps 229: .\" LIST-ITEM
230: .It ROOT
231: \(<- mnode+
232: .It mnode
233: \(<- BLOCK | ELEMENT | TEXT
234: .It BLOCK
235: \(<- (HEAD [TEXT])+ [BODY [TEXT]] [TAIL [TEXT]]
236: .It BLOCK
237: \(<- BODY [TEXT] [TAIL [TEXT]]
238: .It ELEMENT
239: \(<- TEXT*
240: .It HEAD
241: \(<- mnode+
242: .It BODY
243: \(<- mnode+
244: .It TAIL
245: \(<- mnode+
246: .It TEXT
247: \(<- [[:alpha:]]*
248: .El
249: .\" PARAGRAPH
1.2 kristaps 250: .Pp
1.6 kristaps 251: Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of
252: the BLOCK production. These refer to punctuation marks. Furthermore,
1.8 kristaps 253: although a TEXT node will generally have a non-zero-length string, in
254: the specific case of
255: .Sq \&.Bd \-literal ,
1.6 kristaps 256: an empty line will produce a zero-length string.
257: .\" SECTION
1.2 kristaps 258: .Sh EXAMPLES
259: The following example reads lines from stdin and parses them, operating
260: on the finished parse tree with
261: .Fn parsed .
262: Note that, if the last line of the file isn't newline-terminated, this
263: will truncate the file's last character (see
264: .Xr fgetln 3 ) .
265: Further, this example does not error-check nor free memory upon failure.
1.9 kristaps 266: .Bd -literal -offset "XXXX"
1.2 kristaps 267: struct mdoc *mdoc;
268: struct mdoc_node *node;
269: char *buf;
270: size_t len;
271: int line;
272:
273: line = 1;
1.25 kristaps 274: mdoc = mdoc_alloc(NULL, 0, NULL);
1.2 kristaps 275:
276: while ((buf = fgetln(fp, &len))) {
277: buf[len - 1] = '\\0';
278: if ( ! mdoc_parseln(mdoc, line, buf))
279: errx(1, "mdoc_parseln");
280: line++;
281: }
282:
283: if ( ! mdoc_endparse(mdoc))
284: errx(1, "mdoc_endparse");
1.4 kristaps 285: if (NULL == (node = mdoc_node(mdoc)))
286: errx(1, "mdoc_node");
1.2 kristaps 287:
288: parsed(mdoc, node);
289: mdoc_free(mdoc);
290: .Ed
1.6 kristaps 291: .\" SECTION
1.17 kristaps 292: .Sh SEE ALSO
1.20 kristaps 293: .Xr mandoc 1 ,
1.14 kristaps 294: .Xr mdoc 7
1.6 kristaps 295: .\" SECTION
1.2 kristaps 296: .Sh AUTHORS
297: The
298: .Nm
299: utility was written by
1.19 kristaps 300: .An Kristaps Dzonsons Aq kristaps@openbsd.org .
1.6 kristaps 301: .\" SECTION
1.14 kristaps 302: .Sh CAVEATS
1.17 kristaps 303: .Bl -dash -compact
1.14 kristaps 304: .\" LIST-ITEM
305: .It
306: The
1.24 kristaps 307: .Sq \&.Xc
1.2 kristaps 308: and
1.24 kristaps 309: .Sq \&.Xo
1.2 kristaps 310: macros aren't handled when used to span lines for the
1.24 kristaps 311: .Sq \&.It
1.17 kristaps 312: macro.
1.16 kristaps 313: .\" LIST-ITEM
314: .It
315: The
1.24 kristaps 316: .Sq \&.Bsx
1.23 kristaps 317: macro family doesn't yet understand version arguments.
1.21 kristaps 318: .\" LIST-ITEM
319: .It
320: If not given a value, the \-offset argument to
1.24 kristaps 321: .Sq \&.Bd
1.21 kristaps 322: and
1.24 kristaps 323: .Sq \&.Bl
1.23 kristaps 324: should be the width of
325: .Qq <string> ;
326: instead, a value of
327: .Li 10n
328: is provided.
1.21 kristaps 329: .\" LIST-ITEM
330: .It
331: Columns widths in
1.24 kristaps 332: .Sq \&.Bl \-column
1.21 kristaps 333: should default to width
334: .Qq <stringx>
335: if not included.
336: .\" LIST-ITEM
337: .It
338: List-width suffix
339: .Qq m
340: isn't handled.
1.22 kristaps 341: .\" LIST-ITEM
342: .It
343: Contents of the SYNOPSIS section aren't checked.
1.14 kristaps 344: .El
CVSweb