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