Annotation of mandoc/mdoc.3, Revision 1.6
1.6 ! kristaps 1: .\" $Id: mdocterm.1,v 1.2 2009/02/22 11:23:19 kristaps Exp $
! 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.
! 53: .Dq mdoc
! 54: is a macro package of the
! 55: .Dq roff
! 56: language, which is used to format BSD manual pages. The
! 57: .Nm
! 58: library implements only those macros documented in the
! 59: .Xr mdoc 7
! 60: and
! 61: .Xr mdoc.samples 7
! 62: manuals.
! 63: .\" PARAGRAPH
! 64: .Pp
! 65: .Nm
! 66: is
! 67: .Ud
! 68: .\" PARAGRAPH
! 69: .Pp
1.1 kristaps 70: In general, applications initiate a parsing sequence with
71: .Fn mdoc_alloc ,
72: parse each line in a document with
73: .Fn mdoc_parseln ,
74: close the parsing session with
75: .Fn mdoc_endparse ,
76: operate over the syntax tree returned by
1.4 kristaps 77: .Fn mdoc_node
78: and
79: .Fn mdoc_meta ,
1.1 kristaps 80: then free all allocated memory with
81: .Fn mdoc_free .
82: See the
83: .Sx EXAMPLES
84: section for a full example.
1.6 ! kristaps 85: .\" PARAGRAPH
1.2 kristaps 86: .Pp
1.6 ! kristaps 87: This section further defines the
! 88: .Sx Types ,
! 89: .Sx Functions
! 90: and
! 91: .Sx Variables
! 92: available to programmers. The last sub-section,
! 93: .Sx Abstract Syntax Tree ,
! 94: documents the output tree.
! 95: .\" SUBSECTION
! 96: .Ss Types
! 97: Both functions (see
! 98: .Sx Functions )
! 99: and variables (see
! 100: .Sx Variables )
! 101: may use the following types:
! 102: .Bl -ohang
! 103: .\" LIST-ITEM
! 104: .It Vt struct mdoc
! 105: An opaque type defined in
! 106: .Pa mdoc.c .
! 107: Its values are only used privately within the library.
! 108: .\" LIST-ITEM
! 109: .It Vt struct mdoc_cb
! 110: A set of message callbacks defined in
! 111: .Pa mdoc.h .
! 112: .\" LIST-ITEM
! 113: .It Vt struct mdoc_node
! 114: A parsed node. Defined in
! 115: .Pa mdoc.h .
! 116: See
! 117: .Sx Abstract Syntax Tree
! 118: for details.
! 119: .El
! 120: .\" SUBSECTION
! 121: .Ss Functions
1.2 kristaps 122: Function descriptions follow:
1.6 ! kristaps 123: .Bl -ohang
! 124: .\" LIST-ITEM
1.2 kristaps 125: .It Fn mdoc_alloc
126: Allocates a parsing structure. The
127: .Fa data
128: pointer is passed to callbacks in
129: .Fa cb ,
130: which are documented further in the header file. Returns NULL on
131: failure. If non-NULL, the pointer must be freed with
132: .Fn mdoc_free .
1.6 ! kristaps 133: .\" LIST-ITEM
1.2 kristaps 134: .It Fn mdoc_free
135: Free all resources of a parser. The pointer is no longer valid after
136: invocation.
1.6 ! kristaps 137: .\" LIST-ITEM
1.2 kristaps 138: .It Fn mdoc_parseln
139: Parse a nil-terminated line of input. This line should not contain the
140: trailing newline. Returns 0 on failure, 1 on success. The input buffer
141: .Fa buf
142: is modified by this function.
1.6 ! kristaps 143: .\" LIST-ITEM
1.2 kristaps 144: .It Fn mdoc_endparse
145: Signals that the parse is complete. Note that if
146: .Fn mdoc_endparse
147: is called subsequent to
1.4 kristaps 148: .Fn mdoc_node ,
1.2 kristaps 149: the resulting tree is incomplete. Returns 0 on failure, 1 on success.
1.6 ! kristaps 150: .\" LIST-ITEM
1.4 kristaps 151: .It Fn mdoc_node
152: Returns the first node of the parse. Note that if
1.2 kristaps 153: .Fn mdoc_parseln
154: or
155: .Fn mdoc_endparse
156: return 0, the tree will be incomplete.
1.4 kristaps 157: .It Fn mdoc_meta
158: Returns the document's parsed meta-data. If this information has not
159: yet been supplied or
160: .Fn mdoc_parseln
161: or
162: .Fn mdoc_endparse
163: return 0, the data will be incomplete.
164: .El
1.6 ! kristaps 165: .\" SUBSECTION
! 166: .Ss Variables
1.4 kristaps 167: The following variables are also defined:
1.6 ! kristaps 168: .Bl -ohang
! 169: .\" LIST-ITEM
1.4 kristaps 170: .It Va mdoc_macronames
171: An array of string-ified token names.
1.6 ! kristaps 172: .\" LIST-ITEM
1.4 kristaps 173: .It Va mdoc_argnames
174: An array of string-ified token argument names.
1.2 kristaps 175: .El
1.6 ! kristaps 176: .\" SUBSECTION
! 177: .Ss Abstract Syntax Tree
! 178: The
! 179: .Nm
! 180: functions produce an abstract syntax tree (AST) describing the input
! 181: lines in a regular form. It may be reviewed at any time with
! 182: .Fn mdoc_nodes ;
! 183: however, if called before
! 184: .Fn mdoc_endparse ,
! 185: or after
! 186: .Fn mdoc_endparse
! 187: or
! 188: .Fn mdoc_parseln
! 189: fail, it may be incomplete.
! 190: .\" PARAGRAPH
! 191: .Pp
! 192: The AST is composed of
! 193: .Vt struct mdoc_node
! 194: nodes with block, head, body, element, root and text types as declared
! 195: by the
! 196: .Va type
! 197: field. Each node also provides its parse point (the
! 198: .Va line ,
! 199: .Va sec ,
! 200: and
! 201: .Va pos
! 202: fields), its position in the tree (the
! 203: .Va parent ,
! 204: .Va child ,
! 205: .Va next
! 206: and
! 207: .Va prev
! 208: fields) and type-specific data (the
! 209: .Va data
! 210: field).
! 211: .\" PARAGRAPH
! 212: .Pp
! 213: The tree itself is arranged according to the following normal form,
! 214: where capitalised non-terminals represent nodes.
! 215: .Pp
! 216: .Bl -tag -width "ELEMENTXX" -compact
! 217: .\" LIST-ITEM
! 218: .It ROOT
! 219: \(<- mnode+
! 220: .It mnode
! 221: \(<- BLOCK | ELEMENT | TEXT
! 222: .It BLOCK
! 223: \(<- (HEAD [TEXT])+ [BODY [TEXT]] [TAIL [TEXT]]
! 224: .It BLOCK
! 225: \(<- BODY [TEXT] [TAIL [TEXT]]
! 226: .It ELEMENT
! 227: \(<- TEXT*
! 228: .It HEAD
! 229: \(<- mnode+
! 230: .It BODY
! 231: \(<- mnode+
! 232: .It TAIL
! 233: \(<- mnode+
! 234: .It TEXT
! 235: \(<- [[:alpha:]]*
! 236: .El
! 237: .\" PARAGRAPH
1.2 kristaps 238: .Pp
1.6 ! kristaps 239: Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of
! 240: the BLOCK production. These refer to punctuation marks. Furthermore,
! 241: although a TEXT node will generally have a non-zero-length string, it
! 242: certain cases, such as
! 243: .Dq \&.Bd \-literal ,
! 244: an empty line will produce a zero-length string.
! 245: .\" PARAGRAPH
! 246: .Pp
! 247: The rule-of-thumb for mapping node types to macros follows: in-line
! 248: elements, such as
! 249: .Dq \&.Em foo ,
! 250: are classified as ELEMENT nodes, which can only contain text.
! 251: Multi-line elements such as
! 252: .Dq \&.Sh
! 253: are BLOCK elements, where the HEAD constitutes line contents and the
! 254: BODY constitutes subsequent lines. In-line elements with matching
! 255: pairs, such as
! 256: .Dq \&.So
! 257: and
! 258: .Dq \&.Sc ,
! 259: are BLOCK elements with no HEAD tag. The only exception to this is
! 260: .Dq \&.Eo
! 261: and
! 262: .Dq \&.Ec ,
! 263: which has a HEAD and TAIL node corresponding to the enclosure string.
! 264: TEXT nodes, obviously, constitute text; the ROOT node is the document's
! 265: root.
! 266: .\" SECTION
1.2 kristaps 267: .Sh EXAMPLES
268: The following example reads lines from stdin and parses them, operating
269: on the finished parse tree with
270: .Fn parsed .
271: Note that, if the last line of the file isn't newline-terminated, this
272: will truncate the file's last character (see
273: .Xr fgetln 3 ) .
274: Further, this example does not error-check nor free memory upon failure.
275: .Bd -literal
276: struct mdoc *mdoc;
277: struct mdoc_node *node;
278: char *buf;
279: size_t len;
280: int line;
281:
282: line = 1;
283: mdoc = mdoc_alloc(NULL, NULL);
284:
285: while ((buf = fgetln(fp, &len))) {
286: buf[len - 1] = '\\0';
287: if ( ! mdoc_parseln(mdoc, line, buf))
288: errx(1, "mdoc_parseln");
289: line++;
290: }
291:
292: if ( ! mdoc_endparse(mdoc))
293: errx(1, "mdoc_endparse");
1.4 kristaps 294: if (NULL == (node = mdoc_node(mdoc)))
295: errx(1, "mdoc_node");
1.2 kristaps 296:
297: parsed(mdoc, node);
298: mdoc_free(mdoc);
299: .Ed
1.6 ! kristaps 300: .\" SECTION
1.2 kristaps 301: .Sh SEE ALSO
302: .Xr mdoc 7 ,
303: .Xr mdoc.samples 7 ,
304: .Xr groff 1 ,
305: .Xr mdocml 1
1.6 ! kristaps 306: .\" SECTION
1.2 kristaps 307: .Sh AUTHORS
308: The
309: .Nm
310: utility was written by
311: .An Kristaps Dzonsons Aq kristaps@kth.se .
1.6 ! kristaps 312: .\" SECTION
1.2 kristaps 313: .Sh BUGS
1.4 kristaps 314: Bugs, un-implemented macros and incompabilities are documented in this
315: section. The baseline for determining whether macro parsing is
316: .Qq incompatible
317: is the default
1.3 kristaps 318: .Xr groff 1
319: system bundled with
320: .Ox .
321: .Pp
1.4 kristaps 322: Un-implemented: the
1.2 kristaps 323: .Sq \&Xc
324: and
325: .Sq \&Xo
326: macros aren't handled when used to span lines for the
327: .Sq \&It
328: macro. Such usage is specifically discouraged in
329: .Xr mdoc.samples 7 .
330: .Pp
1.4 kristaps 331: Bugs: when
1.2 kristaps 332: .Sq \&It \-column
333: is invoked, whitespace is not stripped around
334: .Sq \&Ta
335: or tab-character separators.
1.3 kristaps 336: .Pp
1.4 kristaps 337: Incompatible: the
1.3 kristaps 338: .Sq \&At
1.4 kristaps 339: macro only accepts a single parameter. Furthermore, several macros
340: .Pf ( Sq \&Pp ,
341: .Sq \&It ,
342: and possibly others) accept multiple arguments with a warning.
1.5 kristaps 343: .Pp
344: Incompatible: only those macros specified by
345: .Xr mdoc.samples 7
346: and
347: .Xr mdoc 7
348: for
349: .Ox
350: are supported; support for
351: .Nx
1.6 ! kristaps 352: and other
! 353: .Bx
! 354: 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