Annotation of mandoc/man.3, Revision 1.13
1.13 ! kristaps 1: .\" $Id: man.3,v 1.12 2010/02/17 19:22:01 kristaps Exp $
1.1 kristaps 2: .\"
1.12 kristaps 3: .\" Copyright (c) 2009-2010 Kristaps Dzonsons <kristaps@bsd.lv>
1.1 kristaps 4: .\"
5: .\" Permission to use, copy, modify, and distribute this software for any
1.3 kristaps 6: .\" purpose with or without fee is hereby granted, provided that the above
7: .\" copyright notice and this permission notice appear in all copies.
8: .\"
9: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
1.1 kristaps 16: .\"
1.13 ! kristaps 17: .Dd $Mdocdate: February 17 2010 $
1.2 kristaps 18: .Dt MAN 3
1.1 kristaps 19: .Os
1.13 ! kristaps 20: .
! 21: .
1.1 kristaps 22: .Sh NAME
1.13 ! kristaps 23: .Nm man ,
1.1 kristaps 24: .Nm man_alloc ,
25: .Nm man_parseln ,
26: .Nm man_endparse ,
27: .Nm man_node ,
28: .Nm man_meta ,
29: .Nm man_free ,
30: .Nm man_reset
31: .Nd man macro compiler library
1.13 ! kristaps 32: .
! 33: .
1.1 kristaps 34: .Sh SYNOPSIS
1.10 kristaps 35: .In man.h
1.1 kristaps 36: .Vt extern const char * const * man_macronames;
37: .Ft "struct man *"
38: .Fn man_alloc "void *data" "int pflags" "const struct man_cb *cb"
39: .Ft void
40: .Fn man_reset "struct man *man"
41: .Ft void
42: .Fn man_free "struct man *man"
43: .Ft int
44: .Fn man_parseln "struct man *man" "int line" "char *buf"
45: .Ft "const struct man_node *"
1.6 kristaps 46: .Fn man_node "const struct man *man"
1.1 kristaps 47: .Ft "const struct man_meta *"
1.6 kristaps 48: .Fn man_meta "const struct man *man"
1.1 kristaps 49: .Ft int
50: .Fn man_endparse "struct man *man"
1.13 ! kristaps 51: .
! 52: .
1.1 kristaps 53: .Sh DESCRIPTION
54: The
1.13 ! kristaps 55: .Nm
1.7 kristaps 56: library parses lines of
1.1 kristaps 57: .Xr man 7
58: input (and
59: .Em only
60: man) into an abstract syntax tree (AST).
1.13 ! kristaps 61: .
1.1 kristaps 62: .Pp
63: In general, applications initiate a parsing sequence with
64: .Fn man_alloc ,
1.7 kristaps 65: parse each line in a document with
1.1 kristaps 66: .Fn man_parseln ,
67: close the parsing session with
68: .Fn man_endparse ,
69: operate over the syntax tree returned by
1.7 kristaps 70: .Fn man_node
1.1 kristaps 71: and
72: .Fn man_meta ,
73: then free all allocated memory with
74: .Fn man_free .
75: The
76: .Fn man_reset
77: function may be used in order to reset the parser for another input
78: sequence. See the
79: .Sx EXAMPLES
80: section for a full example.
1.13 ! kristaps 81: .
! 82: .Pp
! 83: Beyond the full set of macros defined in
! 84: .Xr man 7 ,
! 85: the
! 86: .Nm
! 87: library also accepts the following macros:
! 88: .
1.1 kristaps 89: .Pp
1.13 ! kristaps 90: .Bl -tag -width Ds -compact
! 91: .It am
! 92: .It ami
! 93: .It de
! 94: .It dei
! 95: .It ig
! 96: Instructional macros in the original roff language. Blocks begun by
! 97: these macros end with
! 98: .Sq ..
! 99: and may begin anywhere, although they may not break the next-line
! 100: scoping rules specified in
! 101: .Xr man 7 .
! 102: These blocks are discarded.
! 103: .
! 104: .It PD
! 105: Has no effect. Handled as a current-scope line macro.
! 106: .
! 107: .It Sp
! 108: A synonym for
! 109: .Sq sp 0.5v
! 110: .Pq part of the standard preamble for Perl documentation .
! 111: Handled as a line macro.
! 112: .
! 113: .It UC
! 114: Has no effect. Handled as a current-scope line macro.
! 115: .
! 116: .It Vb
! 117: A synonym for
! 118: .Sq nf
! 119: .Pq part of the standard preamble for Perl documentation .
! 120: Handled as a current-scope line macro.
! 121: .
! 122: .It Ve
! 123: A synonym for
! 124: .Sq fi ,
! 125: closing
! 126: .Sq Vb
! 127: .Pq part of the standard preamble for Perl documentation .
! 128: Handled as a current-scope line macro.
! 129: .El
! 130: .
! 131: .
! 132: .Sh REFERENCE
1.7 kristaps 133: This section further defines the
1.1 kristaps 134: .Sx Types ,
1.7 kristaps 135: .Sx Functions
1.1 kristaps 136: and
137: .Sx Variables
138: available to programmers. Following that, the
1.7 kristaps 139: .Sx Abstract Syntax Tree
1.1 kristaps 140: section documents the output tree.
1.13 ! kristaps 141: .
! 142: .
1.1 kristaps 143: .Ss Types
144: Both functions (see
145: .Sx Functions )
146: and variables (see
147: .Sx Variables )
148: may use the following types:
1.12 kristaps 149: .Bl -ohang
1.13 ! kristaps 150: .
1.1 kristaps 151: .It Vt struct man
152: An opaque type defined in
153: .Pa man.c .
154: Its values are only used privately within the library.
1.13 ! kristaps 155: .
1.1 kristaps 156: .It Vt struct man_cb
157: A set of message callbacks defined in
158: .Pa man.h .
1.13 ! kristaps 159: .
1.1 kristaps 160: .It Vt struct man_node
161: A parsed node. Defined in
162: .Pa man.h .
1.7 kristaps 163: See
1.1 kristaps 164: .Sx Abstract Syntax Tree
165: for details.
166: .El
1.13 ! kristaps 167: .
! 168: .
1.1 kristaps 169: .Ss Functions
170: Function descriptions follow:
1.12 kristaps 171: .Bl -ohang
1.13 ! kristaps 172: .
1.1 kristaps 173: .It Fn man_alloc
174: Allocates a parsing structure. The
175: .Fa data
176: pointer is passed to callbacks in
1.7 kristaps 177: .Fa cb ,
178: which are documented further in the header file.
1.1 kristaps 179: The
180: .Fa pflags
181: arguments are defined in
182: .Pa man.h .
183: Returns NULL on failure. If non-NULL, the pointer must be freed with
184: .Fn man_free .
1.13 ! kristaps 185: .
1.1 kristaps 186: .It Fn man_reset
1.7 kristaps 187: Reset the parser for another parse routine. After its use,
1.1 kristaps 188: .Fn man_parseln
189: behaves as if invoked for the first time.
1.13 ! kristaps 190: .
1.1 kristaps 191: .It Fn man_free
192: Free all resources of a parser. The pointer is no longer valid after
193: invocation.
1.13 ! kristaps 194: .
1.1 kristaps 195: .It Fn man_parseln
196: Parse a nil-terminated line of input. This line should not contain the
1.7 kristaps 197: trailing newline. Returns 0 on failure, 1 on success. The input buffer
1.1 kristaps 198: .Fa buf
199: is modified by this function.
1.13 ! kristaps 200: .
1.1 kristaps 201: .It Fn man_endparse
1.7 kristaps 202: Signals that the parse is complete. Note that if
1.1 kristaps 203: .Fn man_endparse
204: is called subsequent to
205: .Fn man_node ,
206: the resulting tree is incomplete. Returns 0 on failure, 1 on success.
1.13 ! kristaps 207: .
1.1 kristaps 208: .It Fn man_node
1.7 kristaps 209: Returns the first node of the parse. Note that if
1.1 kristaps 210: .Fn man_parseln
211: or
212: .Fn man_endparse
213: return 0, the tree will be incomplete.
214: .It Fn man_meta
215: Returns the document's parsed meta-data. If this information has not
1.7 kristaps 216: yet been supplied or
1.1 kristaps 217: .Fn man_parseln
218: or
219: .Fn man_endparse
220: return 0, the data will be incomplete.
221: .El
1.13 ! kristaps 222: .
! 223: .
1.1 kristaps 224: .Ss Variables
225: The following variables are also defined:
1.12 kristaps 226: .Bl -ohang
1.13 ! kristaps 227: .
1.1 kristaps 228: .It Va man_macronames
229: An array of string-ified token names.
230: .El
1.13 ! kristaps 231: .
! 232: .
1.1 kristaps 233: .Ss Abstract Syntax Tree
1.7 kristaps 234: The
1.1 kristaps 235: .Nm
236: functions produce an abstract syntax tree (AST) describing input in a
237: regular form. It may be reviewed at any time with
238: .Fn man_nodes ;
239: however, if called before
240: .Fn man_endparse ,
241: or after
1.7 kristaps 242: .Fn man_endparse
1.1 kristaps 243: or
244: .Fn man_parseln
1.7 kristaps 245: fail, it may be incomplete.
1.13 ! kristaps 246: .
1.1 kristaps 247: .Pp
248: This AST is governed by the ontological
249: rules dictated in
250: .Xr man 7
1.7 kristaps 251: and derives its terminology accordingly.
1.13 ! kristaps 252: .
1.1 kristaps 253: .Pp
1.7 kristaps 254: The AST is composed of
1.1 kristaps 255: .Vt struct man_node
256: nodes with element, root and text types as declared
257: by the
258: .Va type
259: field. Each node also provides its parse point (the
260: .Va line ,
261: .Va sec ,
262: and
263: .Va pos
264: fields), its position in the tree (the
265: .Va parent ,
266: .Va child ,
1.7 kristaps 267: .Va next
1.1 kristaps 268: and
1.7 kristaps 269: .Va prev
1.1 kristaps 270: fields) and some type-specific data.
1.13 ! kristaps 271: .
1.1 kristaps 272: .Pp
273: The tree itself is arranged according to the following normal form,
274: where capitalised non-terminals represent nodes.
275: .Pp
1.12 kristaps 276: .Bl -tag -width "ELEMENTXX" -compact
1.1 kristaps 277: .It ROOT
278: \(<- mnode+
279: .It mnode
1.8 kristaps 280: \(<- ELEMENT | TEXT | BLOCK
281: .It BLOCK
282: \(<- HEAD BODY
283: .It HEAD
284: \(<- mnode*
285: .It BODY
286: \(<- mnode*
1.1 kristaps 287: .It ELEMENT
288: \(<- ELEMENT | TEXT*
289: .It TEXT
290: \(<- [[:alpha:]]*
291: .El
1.13 ! kristaps 292: .
1.1 kristaps 293: .Pp
294: The only elements capable of nesting other elements are those with
295: next-lint scope as documented in
296: .Xr man 7 .
1.13 ! kristaps 297: .
! 298: .
1.1 kristaps 299: .Sh EXAMPLES
300: The following example reads lines from stdin and parses them, operating
1.7 kristaps 301: on the finished parse tree with
1.1 kristaps 302: .Fn parsed .
1.12 kristaps 303: This example does not error-check nor free memory upon failure.
304: .Bd -literal -offset indent
1.1 kristaps 305: struct man *man;
306: struct man_node *node;
307: char *buf;
308: size_t len;
309: int line;
310:
311: line = 1;
312: man = man_alloc(NULL, 0, NULL);
1.12 kristaps 313: buf = NULL;
314: alloc_len = 0;
1.1 kristaps 315:
1.12 kristaps 316: while ((len = getline(&buf, &alloc_len, stdin)) >= 0) {
317: if (len && buflen[len - 1] = '\en')
318: buf[len - 1] = '\e0';
319: if ( ! man_parseln(man, line, buf))
320: errx(1, "man_parseln");
321: line++;
1.1 kristaps 322: }
323:
1.12 kristaps 324: free(buf);
325:
1.1 kristaps 326: if ( ! man_endparse(man))
1.12 kristaps 327: errx(1, "man_endparse");
1.1 kristaps 328: if (NULL == (node = man_node(man)))
1.12 kristaps 329: errx(1, "man_node");
1.1 kristaps 330:
331: parsed(man, node);
332: man_free(man);
333: .Ed
1.13 ! kristaps 334: .
! 335: .
1.1 kristaps 336: .Sh SEE ALSO
337: .Xr mandoc 1 ,
338: .Xr man 7
1.13 ! kristaps 339: .
! 340: .
1.1 kristaps 341: .Sh AUTHORS
342: The
343: .Nm
1.7 kristaps 344: utility was written by
1.12 kristaps 345: .An Kristaps Dzonsons Aq kristaps@bsd.lv .
CVSweb
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to man.3 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [cvsweb.bsd.lv] / mandoc