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