Annotation of mandoc/mdoc.3, Revision 1.13
1.13 ! kristaps 1: .\" $Id: mdoc.3,v 1.12 2009/02/27 08:20:15 kristaps Exp $
1.6 kristaps 2: .\"
3: .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
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.
1.1 kristaps 18: .\"
19: .Dd $Mdocdate$
20: .Dt mdoc 3
21: .Os
1.6 kristaps 22: .\" SECTION
1.1 kristaps 23: .Sh NAME
24: .Nm mdoc_alloc ,
25: .Nm mdoc_parseln ,
26: .Nm mdoc_endparse ,
1.4 kristaps 27: .Nm mdoc_node ,
28: .Nm mdoc_meta ,
1.1 kristaps 29: .Nm mdoc_free
1.2 kristaps 30: .Nd mdoc macro compiler library
1.6 kristaps 31: .\" SECTION
1.1 kristaps 32: .Sh SYNOPSIS
1.4 kristaps 33: .Fd #include <mdoc.h>
34: .Vt extern const char * const * mdoc_macronames;
35: .Vt extern const char * const * mdoc_argnames;
1.1 kristaps 36: .Ft "struct mdoc *"
37: .Fn mdoc_alloc "void *data" "const struct mdoc_cb *cb"
38: .Ft void
1.2 kristaps 39: .Fn mdoc_free "struct mdoc *mdoc"
1.1 kristaps 40: .Ft int
1.2 kristaps 41: .Fn mdoc_parseln "struct mdoc *mdoc" "int line" "char *buf"
1.1 kristaps 42: .Ft "const struct mdoc_node *"
1.4 kristaps 43: .Fn mdoc_node "struct mdoc *mdoc"
44: .Ft "const struct mdoc_meta *"
45: .Fn mdoc_meta "struct mdoc *mdoc"
1.1 kristaps 46: .Ft int
1.2 kristaps 47: .Fn mdoc_endparse "struct mdoc *mdoc"
1.6 kristaps 48: .\" SECTION
1.1 kristaps 49: .Sh DESCRIPTION
50: The
51: .Nm mdoc
1.6 kristaps 52: library parses lines of mdoc input into an abstract syntax tree.
1.7 kristaps 53: .Dq mdoc ,
54: which is used to format BSD manual pages, is a macro package of the
1.6 kristaps 55: .Dq roff
1.7 kristaps 56: language. The
1.6 kristaps 57: .Nm
58: library implements only those macros documented in the
59: .Xr mdoc 7
60: and
61: .Xr mdoc.samples 7
1.11 kristaps 62: manuals. Documents with
63: .Xr refer 1 ,
64: .Xr eqn 1
65: and other pre-processor sections aren't accomodated.
1.6 kristaps 66: .\" PARAGRAPH
67: .Pp
68: .Nm
69: is
70: .Ud
71: .\" PARAGRAPH
72: .Pp
1.1 kristaps 73: In general, applications initiate a parsing sequence with
74: .Fn mdoc_alloc ,
75: parse each line in a document with
76: .Fn mdoc_parseln ,
77: close the parsing session with
78: .Fn mdoc_endparse ,
79: operate over the syntax tree returned by
1.4 kristaps 80: .Fn mdoc_node
81: and
82: .Fn mdoc_meta ,
1.1 kristaps 83: then free all allocated memory with
84: .Fn mdoc_free .
85: See the
86: .Sx EXAMPLES
87: section for a full example.
1.6 kristaps 88: .\" PARAGRAPH
1.2 kristaps 89: .Pp
1.6 kristaps 90: This section further defines the
91: .Sx Types ,
92: .Sx Functions
93: and
94: .Sx Variables
1.10 kristaps 95: available to programmers. Following that,
96: .Sx Character Encoding
97: describes input format. Lastly,
1.6 kristaps 98: .Sx Abstract Syntax Tree ,
99: documents the output tree.
100: .\" SUBSECTION
101: .Ss Types
102: Both functions (see
103: .Sx Functions )
104: and variables (see
105: .Sx Variables )
106: may use the following types:
1.9 kristaps 107: .Bl -ohang -offset "XXXX"
1.6 kristaps 108: .\" LIST-ITEM
109: .It Vt struct mdoc
110: An opaque type defined in
111: .Pa mdoc.c .
112: Its values are only used privately within the library.
113: .\" LIST-ITEM
114: .It Vt struct mdoc_cb
115: A set of message callbacks defined in
116: .Pa mdoc.h .
117: .\" LIST-ITEM
118: .It Vt struct mdoc_node
119: A parsed node. Defined in
120: .Pa mdoc.h .
121: See
122: .Sx Abstract Syntax Tree
123: for details.
124: .El
125: .\" SUBSECTION
126: .Ss Functions
1.2 kristaps 127: Function descriptions follow:
1.9 kristaps 128: .Bl -ohang -offset "XXXX"
1.6 kristaps 129: .\" LIST-ITEM
1.2 kristaps 130: .It Fn mdoc_alloc
131: Allocates a parsing structure. The
132: .Fa data
133: pointer is passed to callbacks in
134: .Fa cb ,
135: which are documented further in the header file. Returns NULL on
136: failure. If non-NULL, the pointer must be freed with
137: .Fn mdoc_free .
1.6 kristaps 138: .\" LIST-ITEM
1.2 kristaps 139: .It Fn mdoc_free
140: Free all resources of a parser. The pointer is no longer valid after
141: invocation.
1.6 kristaps 142: .\" LIST-ITEM
1.2 kristaps 143: .It Fn mdoc_parseln
144: Parse a nil-terminated line of input. This line should not contain the
145: trailing newline. Returns 0 on failure, 1 on success. The input buffer
146: .Fa buf
147: is modified by this function.
1.6 kristaps 148: .\" LIST-ITEM
1.2 kristaps 149: .It Fn mdoc_endparse
150: Signals that the parse is complete. Note that if
151: .Fn mdoc_endparse
152: is called subsequent to
1.4 kristaps 153: .Fn mdoc_node ,
1.2 kristaps 154: the resulting tree is incomplete. Returns 0 on failure, 1 on success.
1.6 kristaps 155: .\" LIST-ITEM
1.4 kristaps 156: .It Fn mdoc_node
157: Returns the first node of the parse. Note that if
1.2 kristaps 158: .Fn mdoc_parseln
159: or
160: .Fn mdoc_endparse
161: return 0, the tree will be incomplete.
1.4 kristaps 162: .It Fn mdoc_meta
163: Returns the document's parsed meta-data. If this information has not
164: yet been supplied or
165: .Fn mdoc_parseln
166: or
167: .Fn mdoc_endparse
168: return 0, the data will be incomplete.
169: .El
1.6 kristaps 170: .\" SUBSECTION
171: .Ss Variables
1.4 kristaps 172: The following variables are also defined:
1.9 kristaps 173: .Bl -ohang -offset "XXXX"
1.6 kristaps 174: .\" LIST-ITEM
1.4 kristaps 175: .It Va mdoc_macronames
176: An array of string-ified token names.
1.6 kristaps 177: .\" LIST-ITEM
1.4 kristaps 178: .It Va mdoc_argnames
179: An array of string-ified token argument names.
1.2 kristaps 180: .El
1.6 kristaps 181: .\" SUBSECTION
1.10 kristaps 182: .Ss Character Encoding
183: The
184: .Xr mdoc 3
185: library accepts only printable ASCII characters as defined by
186: .Xr isprint 3 .
1.12 kristaps 187: Non-ASCII character sequences are delimited in various ways. All are
188: preceeded by an escape character
1.10 kristaps 189: .Sq \\
190: and followed by either an open-parenthesis
191: .Sq \&(
192: for two-character sequences; an open-bracket
193: .Sq \&[
194: for n-character sequences (terminated at a close-bracket
195: .Sq \&] ) ;
1.12 kristaps 196: an asterisk and open-parenthesis
197: .Sq \&*(
198: for two-character sequences;
199: an asterisk and non-open-parenthesis
200: .Sq \&*
201: for single-character sequences; or one of a small set of standalone
202: single characters for other escapes.
1.13 ! kristaps 203: .\" PARAGRAPH
1.12 kristaps 204: .Pp
205: Examples:
206: .Pp
207: .Bl -tag -width "XXXXXXXX" -offset "XXXX" -compact
208: .\" LIST-ITEM
209: .It \\*(<=
210: prints
211: .Dq \*(<=
212: .Pq greater-equal
213: .\" LIST-ITEM
214: .It \\(<-
215: prints
216: .Dq \(<-
217: .Pq left-arrow
218: .\" LIST-ITEM
219: .It \\[<-]
220: also prints
221: .Dq \(<-
222: .Pq left-arrow
223: .\" LIST-ITEM
224: .It \\*(Ba
225: prints
226: .Dq \*(Ba
227: .Pq bar
228: .\" LIST-ITEM
229: .It \\*q
230: prints
231: .Dq \*q
232: .Pq double-quote
233: .El
1.13 ! kristaps 234: .\" PARAGRAPH
! 235: .Pp
! 236: All escaped sequences are syntax-checked, but it's up to the front-end
! 237: system to correctly render them to the output device.
1.10 kristaps 238: .\" SUBSECTION
1.6 kristaps 239: .Ss Abstract Syntax Tree
240: The
241: .Nm
242: functions produce an abstract syntax tree (AST) describing the input
243: lines in a regular form. It may be reviewed at any time with
244: .Fn mdoc_nodes ;
245: however, if called before
246: .Fn mdoc_endparse ,
247: or after
248: .Fn mdoc_endparse
249: or
250: .Fn mdoc_parseln
251: fail, it may be incomplete.
252: .\" PARAGRAPH
253: .Pp
254: The AST is composed of
255: .Vt struct mdoc_node
256: nodes with block, head, body, element, root and text types as declared
257: by the
258: .Va type
259: field. Each node also provides its parse point (the
260: .Va line ,
261: .Va sec ,
262: and
263: .Va pos
264: fields), its position in the tree (the
265: .Va parent ,
266: .Va child ,
267: .Va next
268: and
269: .Va prev
270: fields) and type-specific data (the
271: .Va data
272: field).
273: .\" PARAGRAPH
274: .Pp
275: The tree itself is arranged according to the following normal form,
276: where capitalised non-terminals represent nodes.
277: .Pp
1.9 kristaps 278: .Bl -tag -width "ELEMENTXX" -compact -offset "XXXX"
1.6 kristaps 279: .\" LIST-ITEM
280: .It ROOT
281: \(<- mnode+
282: .It mnode
283: \(<- BLOCK | ELEMENT | TEXT
284: .It BLOCK
285: \(<- (HEAD [TEXT])+ [BODY [TEXT]] [TAIL [TEXT]]
286: .It BLOCK
287: \(<- BODY [TEXT] [TAIL [TEXT]]
288: .It ELEMENT
289: \(<- TEXT*
290: .It HEAD
291: \(<- mnode+
292: .It BODY
293: \(<- mnode+
294: .It TAIL
295: \(<- mnode+
296: .It TEXT
297: \(<- [[:alpha:]]*
298: .El
299: .\" PARAGRAPH
1.2 kristaps 300: .Pp
1.6 kristaps 301: Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of
302: the BLOCK production. These refer to punctuation marks. Furthermore,
1.8 kristaps 303: although a TEXT node will generally have a non-zero-length string, in
304: the specific case of
305: .Sq \&.Bd \-literal ,
1.6 kristaps 306: an empty line will produce a zero-length string.
307: .\" PARAGRAPH
308: .Pp
1.8 kristaps 309: The rule-of-thumb for mapping node types to macros follows. In-line
1.6 kristaps 310: elements, such as
1.8 kristaps 311: .Sq \&.Em foo ,
1.6 kristaps 312: are classified as ELEMENT nodes, which can only contain text.
1.8 kristaps 313: Multi-line elements, such as
314: .Sq \&.Sh ,
1.6 kristaps 315: are BLOCK elements, where the HEAD constitutes line contents and the
316: BODY constitutes subsequent lines. In-line elements with matching
317: pairs, such as
1.8 kristaps 318: .Sq \&.So
1.6 kristaps 319: and
1.8 kristaps 320: .Sq \&.Sc ,
1.6 kristaps 321: are BLOCK elements with no HEAD tag. The only exception to this is
1.8 kristaps 322: .Sq \&.Eo
1.6 kristaps 323: and
1.8 kristaps 324: .Sq \&.Ec ,
1.6 kristaps 325: which has a HEAD and TAIL node corresponding to the enclosure string.
1.8 kristaps 326: TEXT nodes, obviously, constitute text, and the ROOT node is the
327: document's root.
1.6 kristaps 328: .\" SECTION
1.2 kristaps 329: .Sh EXAMPLES
330: The following example reads lines from stdin and parses them, operating
331: on the finished parse tree with
332: .Fn parsed .
333: Note that, if the last line of the file isn't newline-terminated, this
334: will truncate the file's last character (see
335: .Xr fgetln 3 ) .
336: Further, this example does not error-check nor free memory upon failure.
1.9 kristaps 337: .Bd -literal -offset "XXXX"
1.2 kristaps 338: struct mdoc *mdoc;
339: struct mdoc_node *node;
340: char *buf;
341: size_t len;
342: int line;
343:
344: line = 1;
345: mdoc = mdoc_alloc(NULL, NULL);
346:
347: while ((buf = fgetln(fp, &len))) {
348: buf[len - 1] = '\\0';
349: if ( ! mdoc_parseln(mdoc, line, buf))
350: errx(1, "mdoc_parseln");
351: line++;
352: }
353:
354: if ( ! mdoc_endparse(mdoc))
355: errx(1, "mdoc_endparse");
1.4 kristaps 356: if (NULL == (node = mdoc_node(mdoc)))
357: errx(1, "mdoc_node");
1.2 kristaps 358:
359: parsed(mdoc, node);
360: mdoc_free(mdoc);
361: .Ed
1.6 kristaps 362: .\" SECTION
1.2 kristaps 363: .Sh SEE ALSO
364: .Xr mdoc 7 ,
365: .Xr mdoc.samples 7 ,
366: .Xr groff 1 ,
367: .Xr mdocml 1
1.6 kristaps 368: .\" SECTION
1.2 kristaps 369: .Sh AUTHORS
370: The
371: .Nm
372: utility was written by
373: .An Kristaps Dzonsons Aq kristaps@kth.se .
1.6 kristaps 374: .\" SECTION
1.2 kristaps 375: .Sh BUGS
1.4 kristaps 376: Bugs, un-implemented macros and incompabilities are documented in this
377: section. The baseline for determining whether macro parsing is
378: .Qq incompatible
379: is the default
1.3 kristaps 380: .Xr groff 1
381: system bundled with
382: .Ox .
1.9 kristaps 383: .\" PARAGRAPH
1.3 kristaps 384: .Pp
1.4 kristaps 385: Un-implemented: the
1.2 kristaps 386: .Sq \&Xc
387: and
388: .Sq \&Xo
389: macros aren't handled when used to span lines for the
390: .Sq \&It
391: macro. Such usage is specifically discouraged in
392: .Xr mdoc.samples 7 .
1.9 kristaps 393: .\" PARAGRAPH
1.2 kristaps 394: .Pp
1.4 kristaps 395: Bugs: when
1.2 kristaps 396: .Sq \&It \-column
397: is invoked, whitespace is not stripped around
398: .Sq \&Ta
399: or tab-character separators.
1.9 kristaps 400: .\" PARAGRAPH
401: .Pp
402: Bugs: elements within columns for
403: .Sq \&It \-column
404: are not yet supported.
405: .\" PARAGRAPH
1.3 kristaps 406: .Pp
1.4 kristaps 407: Incompatible: the
1.3 kristaps 408: .Sq \&At
1.4 kristaps 409: macro only accepts a single parameter. Furthermore, several macros
410: .Pf ( Sq \&Pp ,
411: .Sq \&It ,
412: and possibly others) accept multiple arguments with a warning.
1.9 kristaps 413: .\" PARAGRAPH
1.5 kristaps 414: .Pp
415: Incompatible: only those macros specified by
416: .Xr mdoc.samples 7
417: and
418: .Xr mdoc 7
419: for
420: .Ox
421: are supported; support for
422: .Nx
1.6 kristaps 423: and other
424: .Bx
425: systems is in progress.
CVSweb
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to mdoc.3 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [cvsweb.bsd.lv] / mandoc