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