Annotation of mandoc/mdoc.3, Revision 1.17
1.17 ! kristaps 1: .\" $Id: mdoc.3,v 1.16 2009/03/12 23:05:21 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.17 ! kristaps 185: fail, it may be incomplete. This AST is governed by the ontological
! 186: rules dictated in
! 187: .Xr mdoc 7
! 188: and derives its terminology accordingly.
! 189: .Qq In-line
! 190: elements described in
! 191: .Xr mdoc 7
! 192: are described simply as
! 193: .Qq elements .
1.6 kristaps 194: .\" PARAGRAPH
195: .Pp
196: The AST is composed of
197: .Vt struct mdoc_node
198: nodes with block, head, body, element, root and text types as declared
199: by the
200: .Va type
201: field. Each node also provides its parse point (the
202: .Va line ,
203: .Va sec ,
204: and
205: .Va pos
206: fields), its position in the tree (the
207: .Va parent ,
208: .Va child ,
209: .Va next
210: and
211: .Va prev
212: fields) and type-specific data (the
213: .Va data
214: field).
215: .\" PARAGRAPH
216: .Pp
217: The tree itself is arranged according to the following normal form,
218: where capitalised non-terminals represent nodes.
219: .Pp
1.9 kristaps 220: .Bl -tag -width "ELEMENTXX" -compact -offset "XXXX"
1.6 kristaps 221: .\" LIST-ITEM
222: .It ROOT
223: \(<- mnode+
224: .It mnode
225: \(<- BLOCK | ELEMENT | TEXT
226: .It BLOCK
227: \(<- (HEAD [TEXT])+ [BODY [TEXT]] [TAIL [TEXT]]
228: .It BLOCK
229: \(<- BODY [TEXT] [TAIL [TEXT]]
230: .It ELEMENT
231: \(<- TEXT*
232: .It HEAD
233: \(<- mnode+
234: .It BODY
235: \(<- mnode+
236: .It TAIL
237: \(<- mnode+
238: .It TEXT
239: \(<- [[:alpha:]]*
240: .El
241: .\" PARAGRAPH
1.2 kristaps 242: .Pp
1.6 kristaps 243: Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of
244: the BLOCK production. These refer to punctuation marks. Furthermore,
1.8 kristaps 245: although a TEXT node will generally have a non-zero-length string, in
246: the specific case of
247: .Sq \&.Bd \-literal ,
1.6 kristaps 248: an empty line will produce a zero-length string.
249: .\" SECTION
1.2 kristaps 250: .Sh EXAMPLES
251: The following example reads lines from stdin and parses them, operating
252: on the finished parse tree with
253: .Fn parsed .
254: Note that, if the last line of the file isn't newline-terminated, this
255: will truncate the file's last character (see
256: .Xr fgetln 3 ) .
257: Further, this example does not error-check nor free memory upon failure.
1.9 kristaps 258: .Bd -literal -offset "XXXX"
1.2 kristaps 259: struct mdoc *mdoc;
260: struct mdoc_node *node;
261: char *buf;
262: size_t len;
263: int line;
264:
265: line = 1;
266: mdoc = mdoc_alloc(NULL, NULL);
267:
268: while ((buf = fgetln(fp, &len))) {
269: buf[len - 1] = '\\0';
270: if ( ! mdoc_parseln(mdoc, line, buf))
271: errx(1, "mdoc_parseln");
272: line++;
273: }
274:
275: if ( ! mdoc_endparse(mdoc))
276: errx(1, "mdoc_endparse");
1.4 kristaps 277: if (NULL == (node = mdoc_node(mdoc)))
278: errx(1, "mdoc_node");
1.2 kristaps 279:
280: parsed(mdoc, node);
281: mdoc_free(mdoc);
282: .Ed
1.6 kristaps 283: .\" SECTION
1.17 ! kristaps 284: .Sh SEE ALSO
! 285: .Xr mdocterm 1 ,
! 286: .Xr mdoclint 1 ,
! 287: .Xr mdoctree 1 ,
1.14 kristaps 288: .Xr mdoc 7
1.6 kristaps 289: .\" SECTION
1.2 kristaps 290: .Sh AUTHORS
291: The
292: .Nm
293: utility was written by
294: .An Kristaps Dzonsons Aq kristaps@kth.se .
1.6 kristaps 295: .\" SECTION
1.14 kristaps 296: .Sh CAVEATS
1.17 ! kristaps 297: .Bl -dash -compact
1.14 kristaps 298: .\" LIST-ITEM
299: .It
300: The
1.2 kristaps 301: .Sq \&Xc
302: and
303: .Sq \&Xo
304: macros aren't handled when used to span lines for the
305: .Sq \&It
1.17 ! kristaps 306: macro.
1.16 kristaps 307: .\" LIST-ITEM
308: .It
309: The
310: .Sq \&Bsx
1.17 ! kristaps 311: macro doesn't yet understand version arguments.
1.14 kristaps 312: .El
CVSweb