Annotation of mandoc/man.3, Revision 1.17
1.17 ! kristaps 1: .\" $Id: man.3,v 1.16 2010/04/13 05:26:49 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.17 ! kristaps 17: .Dd $Mdocdate: April 13 2010 $
1.2 kristaps 18: .Dt MAN 3
1.1 kristaps 19: .Os
20: .Sh NAME
1.13 kristaps 21: .Nm man ,
1.1 kristaps 22: .Nm man_alloc ,
23: .Nm man_endparse ,
1.17 ! kristaps 24: .Nm man_free ,
! 25: .Nm man_meta ,
1.1 kristaps 26: .Nm man_node ,
1.17 ! kristaps 27: .Nm man_parseln ,
1.1 kristaps 28: .Nm man_reset
29: .Nd man macro compiler library
30: .Sh SYNOPSIS
1.17 ! kristaps 31: .In mandoc.h
1.10 kristaps 32: .In man.h
1.1 kristaps 33: .Vt extern const char * const * man_macronames;
34: .Ft "struct man *"
1.17 ! kristaps 35: .Fn man_alloc "void *data" "int pflags" "mandocmsg msgs"
! 36: .Ft int
! 37: .Fn man_endparse "struct man *man"
1.1 kristaps 38: .Ft void
39: .Fn man_free "struct man *man"
1.17 ! kristaps 40: .Ft "const struct man_meta *"
! 41: .Fn man_meta "const struct man *man"
1.1 kristaps 42: .Ft "const struct man_node *"
1.6 kristaps 43: .Fn man_node "const struct man *man"
1.1 kristaps 44: .Ft int
1.17 ! kristaps 45: .Fn man_parseln "struct man *man" "int line" "char *buf"
! 46: .Ft void
! 47: .Fn man_reset "struct man *man"
1.1 kristaps 48: .Sh DESCRIPTION
49: The
1.13 kristaps 50: .Nm
1.7 kristaps 51: library parses lines of
1.1 kristaps 52: .Xr man 7
1.17 ! kristaps 53: input into an abstract syntax tree (AST).
1.1 kristaps 54: .Pp
55: In general, applications initiate a parsing sequence with
56: .Fn man_alloc ,
1.7 kristaps 57: parse each line in a document with
1.1 kristaps 58: .Fn man_parseln ,
59: close the parsing session with
60: .Fn man_endparse ,
61: operate over the syntax tree returned by
1.7 kristaps 62: .Fn man_node
1.1 kristaps 63: and
64: .Fn man_meta ,
65: then free all allocated memory with
66: .Fn man_free .
67: The
68: .Fn man_reset
69: function may be used in order to reset the parser for another input
1.17 ! kristaps 70: sequence.
! 71: See the
1.1 kristaps 72: .Sx EXAMPLES
73: section for a full example.
1.13 kristaps 74: .Pp
75: Beyond the full set of macros defined in
76: .Xr man 7 ,
77: the
78: .Nm
79: library also accepts the following macros:
1.1 kristaps 80: .Pp
1.13 kristaps 81: .Bl -tag -width Ds -compact
82: .It PD
83: Has no effect. Handled as a current-scope line macro.
84: .It Sp
85: A synonym for
86: .Sq sp 0.5v
87: .Pq part of the standard preamble for Perl documentation .
88: Handled as a line macro.
89: .It Vb
90: A synonym for
91: .Sq nf
92: .Pq part of the standard preamble for Perl documentation .
93: Handled as a current-scope line macro.
94: .It Ve
95: A synonym for
96: .Sq fi ,
97: closing
98: .Sq Vb
99: .Pq part of the standard preamble for Perl documentation .
100: Handled as a current-scope line macro.
101: .El
1.14 kristaps 102: .Pp
103: Furthermore, the following escapes are accepted to allow
104: .Xr pod2man 1
1.15 kristaps 105: documents to be correctly formatted:
1.14 kristaps 106: \e*(-- (dash),
107: \e*(PI (pi),
108: \e*(L" (left double-quote),
109: \e*(R" (right double-quote),
110: \e*(C+ (C++),
111: \e*(C` (left single-quote),
112: \e*(C' (right single-quote),
113: \e*(Aq (apostrophe),
114: \e*^ (hat),
115: \e*, (comma),
116: \e*~ (tilde),
117: \e*/ (forward slash),
118: \e*: (umlaut),
119: \e*8 (beta),
120: \e*o (degree),
121: \e*(D- (Eth),
122: \e*(d- (eth),
123: \e*(Th (Thorn),
124: and
125: \e*(th (thorn).
1.13 kristaps 126: .Sh REFERENCE
1.7 kristaps 127: This section further defines the
1.1 kristaps 128: .Sx Types ,
1.7 kristaps 129: .Sx Functions
1.1 kristaps 130: and
131: .Sx Variables
1.17 ! kristaps 132: available to programmers.
! 133: Following that, the
1.7 kristaps 134: .Sx Abstract Syntax Tree
1.1 kristaps 135: section documents the output tree.
136: .Ss Types
137: Both functions (see
138: .Sx Functions )
139: and variables (see
140: .Sx Variables )
141: may use the following types:
1.12 kristaps 142: .Bl -ohang
1.1 kristaps 143: .It Vt struct man
144: An opaque type defined in
145: .Pa man.c .
146: Its values are only used privately within the library.
1.17 ! kristaps 147: .It Vt mandocmsg
! 148: A function callback type defined in
! 149: .Pa mandoc.h .
1.1 kristaps 150: .It Vt struct man_node
1.17 ! kristaps 151: A parsed node.
! 152: Defined in
1.1 kristaps 153: .Pa man.h .
1.7 kristaps 154: See
1.1 kristaps 155: .Sx Abstract Syntax Tree
156: for details.
157: .El
158: .Ss Functions
159: Function descriptions follow:
1.12 kristaps 160: .Bl -ohang
1.1 kristaps 161: .It Fn man_alloc
1.17 ! kristaps 162: Allocates a parsing structure.
! 163: The
1.1 kristaps 164: .Fa data
165: pointer is passed to callbacks in
1.7 kristaps 166: .Fa cb ,
167: which are documented further in the header file.
1.1 kristaps 168: The
169: .Fa pflags
170: arguments are defined in
171: .Pa man.h .
1.17 ! kristaps 172: Returns NULL on failure.
! 173: If non-NULL, the pointer must be freed with
1.1 kristaps 174: .Fn man_free .
175: .It Fn man_reset
1.17 ! kristaps 176: Reset the parser for another parse routine.
! 177: After its use,
1.1 kristaps 178: .Fn man_parseln
179: behaves as if invoked for the first time.
180: .It Fn man_free
1.17 ! kristaps 181: Free all resources of a parser.
! 182: The pointer is no longer valid after invocation.
1.1 kristaps 183: .It Fn man_parseln
1.17 ! kristaps 184: Parse a nil-terminated line of input.
! 185: This line should not contain the trailing newline.
! 186: Returns 0 on failure, 1 on success.
! 187: The input buffer
1.1 kristaps 188: .Fa buf
189: is modified by this function.
190: .It Fn man_endparse
1.17 ! kristaps 191: Signals that the parse is complete.
! 192: Note that if
1.1 kristaps 193: .Fn man_endparse
194: is called subsequent to
195: .Fn man_node ,
1.17 ! kristaps 196: the resulting tree is incomplete.
! 197: Returns 0 on failure, 1 on success.
1.1 kristaps 198: .It Fn man_node
1.17 ! kristaps 199: Returns the first node of the parse.
! 200: Note that if
1.1 kristaps 201: .Fn man_parseln
202: or
203: .Fn man_endparse
204: return 0, the tree will be incomplete.
205: .It Fn man_meta
1.17 ! kristaps 206: Returns the document's parsed meta-data.
! 207: If this information has not yet been supplied or
1.1 kristaps 208: .Fn man_parseln
209: or
210: .Fn man_endparse
211: return 0, the data will be incomplete.
212: .El
213: .Ss Variables
214: The following variables are also defined:
1.12 kristaps 215: .Bl -ohang
1.1 kristaps 216: .It Va man_macronames
217: An array of string-ified token names.
218: .El
219: .Ss Abstract Syntax Tree
1.7 kristaps 220: The
1.1 kristaps 221: .Nm
222: functions produce an abstract syntax tree (AST) describing input in a
1.17 ! kristaps 223: regular form.
! 224: It may be reviewed at any time with
1.1 kristaps 225: .Fn man_nodes ;
226: however, if called before
227: .Fn man_endparse ,
228: or after
1.7 kristaps 229: .Fn man_endparse
1.1 kristaps 230: or
231: .Fn man_parseln
1.7 kristaps 232: fail, it may be incomplete.
1.1 kristaps 233: .Pp
1.17 ! kristaps 234: This AST is governed by the ontological rules dictated in
1.1 kristaps 235: .Xr man 7
1.7 kristaps 236: and derives its terminology accordingly.
1.1 kristaps 237: .Pp
1.7 kristaps 238: The AST is composed of
1.1 kristaps 239: .Vt struct man_node
1.17 ! kristaps 240: nodes with element, root and text types as declared by the
1.1 kristaps 241: .Va type
1.17 ! kristaps 242: field.
! 243: Each node also provides its parse point (the
1.1 kristaps 244: .Va line ,
245: .Va sec ,
246: and
247: .Va pos
248: fields), its position in the tree (the
249: .Va parent ,
250: .Va child ,
1.7 kristaps 251: .Va next
1.1 kristaps 252: and
1.7 kristaps 253: .Va prev
1.1 kristaps 254: fields) and some type-specific data.
255: .Pp
256: The tree itself is arranged according to the following normal form,
257: where capitalised non-terminals represent nodes.
258: .Pp
1.12 kristaps 259: .Bl -tag -width "ELEMENTXX" -compact
1.1 kristaps 260: .It ROOT
261: \(<- mnode+
262: .It mnode
1.8 kristaps 263: \(<- ELEMENT | TEXT | BLOCK
264: .It BLOCK
265: \(<- HEAD BODY
266: .It HEAD
267: \(<- mnode*
268: .It BODY
269: \(<- mnode*
1.1 kristaps 270: .It ELEMENT
271: \(<- ELEMENT | TEXT*
272: .It TEXT
273: \(<- [[:alpha:]]*
274: .El
275: .Pp
276: The only elements capable of nesting other elements are those with
277: next-lint scope as documented in
278: .Xr man 7 .
279: .Sh EXAMPLES
280: The following example reads lines from stdin and parses them, operating
1.7 kristaps 281: on the finished parse tree with
1.1 kristaps 282: .Fn parsed .
1.12 kristaps 283: This example does not error-check nor free memory upon failure.
284: .Bd -literal -offset indent
1.1 kristaps 285: struct man *man;
286: struct man_node *node;
287: char *buf;
288: size_t len;
289: int line;
290:
291: line = 1;
292: man = man_alloc(NULL, 0, NULL);
1.12 kristaps 293: buf = NULL;
294: alloc_len = 0;
1.1 kristaps 295:
1.12 kristaps 296: while ((len = getline(&buf, &alloc_len, stdin)) >= 0) {
297: if (len && buflen[len - 1] = '\en')
298: buf[len - 1] = '\e0';
299: if ( ! man_parseln(man, line, buf))
300: errx(1, "man_parseln");
301: line++;
1.1 kristaps 302: }
303:
1.12 kristaps 304: free(buf);
305:
1.1 kristaps 306: if ( ! man_endparse(man))
1.12 kristaps 307: errx(1, "man_endparse");
1.1 kristaps 308: if (NULL == (node = man_node(man)))
1.12 kristaps 309: errx(1, "man_node");
1.1 kristaps 310:
311: parsed(man, node);
312: man_free(man);
313: .Ed
1.17 ! kristaps 314: .Pp
! 315: Please see
! 316: .Pa main.c
! 317: in the source archive for a rigorous reference.
1.1 kristaps 318: .Sh SEE ALSO
319: .Xr mandoc 1 ,
320: .Xr man 7
321: .Sh AUTHORS
322: The
323: .Nm
1.17 ! kristaps 324: library was written by
1.12 kristaps 325: .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