Annotation of mandoc/man.3, Revision 1.25
1.25 ! kristaps 1: .\" $Id: man.3,v 1.24 2010/08/20 01:02:07 schwarze 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.25 ! kristaps 17: .Dd $Mdocdate: August 20 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 "mandocmsg msgs"
39: .Fc
1.17 kristaps 40: .Ft int
41: .Fn man_endparse "struct man *man"
1.1 kristaps 42: .Ft void
43: .Fn man_free "struct man *man"
1.17 kristaps 44: .Ft "const struct man_meta *"
45: .Fn man_meta "const struct man *man"
1.1 kristaps 46: .Ft "const struct man_node *"
1.6 kristaps 47: .Fn man_node "const struct man *man"
1.1 kristaps 48: .Ft int
1.19 kristaps 49: .Fo man_parseln
50: .Fa "struct man *man"
51: .Fa "int line"
52: .Fa "char *buf"
53: .Fc
1.17 kristaps 54: .Ft void
55: .Fn man_reset "struct man *man"
1.1 kristaps 56: .Sh DESCRIPTION
57: The
1.13 kristaps 58: .Nm
1.7 kristaps 59: library parses lines of
1.1 kristaps 60: .Xr man 7
1.17 kristaps 61: input into an abstract syntax tree (AST).
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
1.17 kristaps 78: sequence.
1.13 kristaps 79: .Pp
80: Beyond the full set of macros defined in
81: .Xr man 7 ,
82: the
83: .Nm
84: library also accepts the following macros:
1.1 kristaps 85: .Pp
1.13 kristaps 86: .Bl -tag -width Ds -compact
87: .It PD
88: Has no effect. Handled as a current-scope line macro.
89: .It Sp
90: A synonym for
91: .Sq sp 0.5v
92: .Pq part of the standard preamble for Perl documentation .
93: Handled as a line macro.
94: .It Vb
95: A synonym for
96: .Sq nf
97: .Pq part of the standard preamble for Perl documentation .
98: Handled as a current-scope line macro.
99: .It Ve
100: A synonym for
101: .Sq fi ,
102: closing
103: .Sq Vb
104: .Pq part of the standard preamble for Perl documentation .
105: Handled as a current-scope line macro.
106: .El
1.1 kristaps 107: .Ss Types
1.12 kristaps 108: .Bl -ohang
1.1 kristaps 109: .It Vt struct man
1.25 ! kristaps 110: An opaque type.
1.1 kristaps 111: Its values are only used privately within the library.
112: .It Vt struct man_node
1.17 kristaps 113: A parsed node.
1.7 kristaps 114: See
1.1 kristaps 115: .Sx Abstract Syntax Tree
116: for details.
117: .El
118: .Ss Functions
1.12 kristaps 119: .Bl -ohang
1.1 kristaps 120: .It Fn man_alloc
1.17 kristaps 121: Allocates a parsing structure.
122: The
1.1 kristaps 123: .Fa data
1.18 kristaps 124: pointer is passed to
125: .Fa msgs .
1.17 kristaps 126: Returns NULL on failure.
127: If non-NULL, the pointer must be freed with
1.1 kristaps 128: .Fn man_free .
129: .It Fn man_reset
1.17 kristaps 130: Reset the parser for another parse routine.
131: After its use,
1.1 kristaps 132: .Fn man_parseln
133: behaves as if invoked for the first time.
134: .It Fn man_free
1.17 kristaps 135: Free all resources of a parser.
136: The pointer is no longer valid after invocation.
1.1 kristaps 137: .It Fn man_parseln
1.17 kristaps 138: Parse a nil-terminated line of input.
139: This line should not contain the trailing newline.
140: Returns 0 on failure, 1 on success.
141: The input buffer
1.1 kristaps 142: .Fa buf
143: is modified by this function.
144: .It Fn man_endparse
1.17 kristaps 145: Signals that the parse is complete.
146: Note that if
1.1 kristaps 147: .Fn man_endparse
148: is called subsequent to
149: .Fn man_node ,
1.17 kristaps 150: the resulting tree is incomplete.
151: Returns 0 on failure, 1 on success.
1.1 kristaps 152: .It Fn man_node
1.17 kristaps 153: Returns the first node of the parse.
154: Note that if
1.1 kristaps 155: .Fn man_parseln
156: or
157: .Fn man_endparse
158: return 0, the tree will be incomplete.
159: .It Fn man_meta
1.17 kristaps 160: Returns the document's parsed meta-data.
161: If this information has not yet been supplied or
1.1 kristaps 162: .Fn man_parseln
163: or
164: .Fn man_endparse
165: return 0, the data will be incomplete.
166: .El
167: .Ss Variables
168: The following variables are also defined:
1.12 kristaps 169: .Bl -ohang
1.1 kristaps 170: .It Va man_macronames
171: An array of string-ified token names.
172: .El
173: .Ss Abstract Syntax Tree
1.7 kristaps 174: The
1.1 kristaps 175: .Nm
176: functions produce an abstract syntax tree (AST) describing input in a
1.17 kristaps 177: regular form.
178: It may be reviewed at any time with
1.1 kristaps 179: .Fn man_nodes ;
180: however, if called before
181: .Fn man_endparse ,
182: or after
1.7 kristaps 183: .Fn man_endparse
1.1 kristaps 184: or
185: .Fn man_parseln
1.7 kristaps 186: fail, it may be incomplete.
1.1 kristaps 187: .Pp
1.17 kristaps 188: This AST is governed by the ontological rules dictated in
1.1 kristaps 189: .Xr man 7
1.7 kristaps 190: and derives its terminology accordingly.
1.1 kristaps 191: .Pp
1.7 kristaps 192: The AST is composed of
1.1 kristaps 193: .Vt struct man_node
1.17 kristaps 194: nodes with element, root and text types as declared by the
1.1 kristaps 195: .Va type
1.17 kristaps 196: field.
197: Each node also provides its parse point (the
1.1 kristaps 198: .Va line ,
199: .Va sec ,
200: and
201: .Va pos
202: fields), its position in the tree (the
203: .Va parent ,
204: .Va child ,
1.7 kristaps 205: .Va next
1.1 kristaps 206: and
1.7 kristaps 207: .Va prev
1.1 kristaps 208: fields) and some type-specific data.
209: .Pp
210: The tree itself is arranged according to the following normal form,
211: where capitalised non-terminals represent nodes.
212: .Pp
1.12 kristaps 213: .Bl -tag -width "ELEMENTXX" -compact
1.1 kristaps 214: .It ROOT
215: \(<- mnode+
216: .It mnode
1.8 kristaps 217: \(<- ELEMENT | TEXT | BLOCK
218: .It BLOCK
219: \(<- HEAD BODY
220: .It HEAD
221: \(<- mnode*
222: .It BODY
223: \(<- mnode*
1.1 kristaps 224: .It ELEMENT
225: \(<- ELEMENT | TEXT*
226: .It TEXT
227: \(<- [[:alpha:]]*
228: .El
229: .Pp
230: The only elements capable of nesting other elements are those with
231: next-lint scope as documented in
232: .Xr man 7 .
233: .Sh EXAMPLES
234: The following example reads lines from stdin and parses them, operating
1.7 kristaps 235: on the finished parse tree with
1.1 kristaps 236: .Fn parsed .
1.12 kristaps 237: This example does not error-check nor free memory upon failure.
238: .Bd -literal -offset indent
1.21 kristaps 239: struct regset regs;
1.1 kristaps 240: struct man *man;
241: struct man_node *node;
242: char *buf;
243: size_t len;
244: int line;
245:
1.21 kristaps 246: bzero(®s, sizeof(struct regset));
1.1 kristaps 247: line = 1;
1.24 schwarze 248: man = man_alloc(®s, NULL, NULL);
1.12 kristaps 249: buf = NULL;
250: alloc_len = 0;
1.1 kristaps 251:
1.12 kristaps 252: while ((len = getline(&buf, &alloc_len, stdin)) >= 0) {
253: if (len && buflen[len - 1] = '\en')
254: buf[len - 1] = '\e0';
255: if ( ! man_parseln(man, line, buf))
256: errx(1, "man_parseln");
257: line++;
1.1 kristaps 258: }
259:
1.12 kristaps 260: free(buf);
261:
1.1 kristaps 262: if ( ! man_endparse(man))
1.12 kristaps 263: errx(1, "man_endparse");
1.1 kristaps 264: if (NULL == (node = man_node(man)))
1.12 kristaps 265: errx(1, "man_node");
1.1 kristaps 266:
267: parsed(man, node);
268: man_free(man);
269: .Ed
1.17 kristaps 270: .Pp
1.25 ! kristaps 271: To compile this, execute
! 272: .Pp
! 273: .D1 % cc main.c libman.a libmandoc.a
! 274: .Pp
! 275: where
1.17 kristaps 276: .Pa main.c
1.25 ! kristaps 277: is the example file.
1.1 kristaps 278: .Sh SEE ALSO
279: .Xr mandoc 1 ,
280: .Xr man 7
281: .Sh AUTHORS
282: The
283: .Nm
1.17 kristaps 284: library was written by
1.12 kristaps 285: .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