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