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