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