Annotation of src/usr.bin/mandoc/man.3, Revision 1.22
1.22 ! schwarze 1: .\" $Id: man.3,v 1.21 2011/01/09 13:16:48 schwarze Exp $
1.1 kristaps 2: .\"
1.20 schwarze 3: .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
1.1 kristaps 4: .\"
5: .\" Permission to use, copy, modify, and distribute this software for any
1.2 schwarze 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.22 ! schwarze 17: .Dd $Mdocdate: January 9 2011 $
1.2 schwarze 18: .Dt MAN 3
1.1 kristaps 19: .Os
20: .Sh NAME
1.8 schwarze 21: .Nm man ,
1.22 ! schwarze 22: .Nm man_addeqn ,
! 23: .Nm man_addspan ,
1.1 kristaps 24: .Nm man_alloc ,
25: .Nm man_endparse ,
1.11 schwarze 26: .Nm man_free ,
27: .Nm man_meta ,
1.1 kristaps 28: .Nm man_node ,
1.11 schwarze 29: .Nm man_parseln ,
1.1 kristaps 30: .Nm man_reset
31: .Nd man macro compiler library
32: .Sh SYNOPSIS
1.11 schwarze 33: .In mandoc.h
1.6 schwarze 34: .In man.h
1.1 kristaps 35: .Vt extern const char * const * man_macronames;
1.20 schwarze 36: .Ft int
1.22 ! schwarze 37: .Fo man_addeqn
! 38: .Fa "struct man *man"
! 39: .Fa "const struct eqn *eqn"
! 40: .Fc
! 41: .Ft int
1.20 schwarze 42: .Fo man_addspan
43: .Fa "struct man *man"
44: .Fa "const struct tbl_span *span"
45: .Fc
1.1 kristaps 46: .Ft "struct man *"
1.12 schwarze 47: .Fo man_alloc
48: .Fa "struct regset *regs"
49: .Fa "void *data"
50: .Fa "mandocmsg msgs"
51: .Fc
1.11 schwarze 52: .Ft int
53: .Fn man_endparse "struct man *man"
1.1 kristaps 54: .Ft void
55: .Fn man_free "struct man *man"
1.11 schwarze 56: .Ft "const struct man_meta *"
57: .Fn man_meta "const struct man *man"
1.1 kristaps 58: .Ft "const struct man_node *"
1.3 schwarze 59: .Fn man_node "const struct man *man"
1.1 kristaps 60: .Ft int
1.12 schwarze 61: .Fo man_parseln
62: .Fa "struct man *man"
63: .Fa "int line"
64: .Fa "char *buf"
65: .Fc
1.11 schwarze 66: .Ft void
67: .Fn man_reset "struct man *man"
1.1 kristaps 68: .Sh DESCRIPTION
69: The
1.8 schwarze 70: .Nm
1.4 schwarze 71: library parses lines of
1.1 kristaps 72: .Xr man 7
1.11 schwarze 73: input into an abstract syntax tree (AST).
1.1 kristaps 74: .Pp
75: In general, applications initiate a parsing sequence with
76: .Fn man_alloc ,
1.4 schwarze 77: parse each line in a document with
1.1 kristaps 78: .Fn man_parseln ,
79: close the parsing session with
80: .Fn man_endparse ,
81: operate over the syntax tree returned by
1.4 schwarze 82: .Fn man_node
1.1 kristaps 83: and
84: .Fn man_meta ,
85: then free all allocated memory with
86: .Fn man_free .
87: The
88: .Fn man_reset
89: function may be used in order to reset the parser for another input
1.11 schwarze 90: sequence.
1.8 schwarze 91: .Pp
92: Beyond the full set of macros defined in
93: .Xr man 7 ,
94: the
95: .Nm
1.17 schwarze 96: library also accepts the following macro:
1.1 kristaps 97: .Pp
1.8 schwarze 98: .Bl -tag -width Ds -compact
99: .It PD
1.18 schwarze 100: Has no effect.
101: Handled as a current-scope line macro.
1.8 schwarze 102: .El
1.1 kristaps 103: .Ss Types
1.7 schwarze 104: .Bl -ohang
1.1 kristaps 105: .It Vt struct man
1.16 schwarze 106: An opaque type.
1.1 kristaps 107: Its values are only used privately within the library.
108: .It Vt struct man_node
1.11 schwarze 109: A parsed node.
1.4 schwarze 110: See
1.1 kristaps 111: .Sx Abstract Syntax Tree
112: for details.
113: .El
114: .Ss Functions
1.21 schwarze 115: If
1.22 ! schwarze 116: .Fn man_addeqn ,
1.21 schwarze 117: .Fn man_addspan ,
118: .Fn man_parseln ,
119: or
120: .Fn man_endparse
121: return 0, calls to any function but
122: .Fn man_reset
123: or
124: .Fn man_free
125: will raise an assertion.
1.7 schwarze 126: .Bl -ohang
1.22 ! schwarze 127: .It Fn man_addeqn
! 128: Add an equation to the parsing stream.
! 129: Returns 0 on failure, 1 on success.
1.20 schwarze 130: .It Fn man_addspan
131: Add a table span to the parsing stream.
132: Returns 0 on failure, 1 on success.
1.1 kristaps 133: .It Fn man_alloc
1.11 schwarze 134: Allocates a parsing structure.
135: The
1.1 kristaps 136: .Fa data
1.11 schwarze 137: pointer is passed to
138: .Fa msgs .
1.21 schwarze 139: Always returns a valid pointer.
140: The pointer must be freed with
1.1 kristaps 141: .Fn man_free .
142: .It Fn man_reset
1.11 schwarze 143: Reset the parser for another parse routine.
144: After its use,
1.1 kristaps 145: .Fn man_parseln
146: behaves as if invoked for the first time.
147: .It Fn man_free
1.11 schwarze 148: Free all resources of a parser.
149: The pointer is no longer valid after invocation.
1.1 kristaps 150: .It Fn man_parseln
1.11 schwarze 151: Parse a nil-terminated line of input.
152: This line should not contain the trailing newline.
153: Returns 0 on failure, 1 on success.
154: The input buffer
1.1 kristaps 155: .Fa buf
156: is modified by this function.
157: .It Fn man_endparse
1.11 schwarze 158: Signals that the parse is complete.
159: Returns 0 on failure, 1 on success.
1.1 kristaps 160: .It Fn man_node
1.11 schwarze 161: Returns the first node of the parse.
1.1 kristaps 162: .It Fn man_meta
1.11 schwarze 163: Returns the document's parsed meta-data.
1.1 kristaps 164: .El
165: .Ss Variables
166: The following variables are also defined:
1.7 schwarze 167: .Bl -ohang
1.1 kristaps 168: .It Va man_macronames
169: An array of string-ified token names.
170: .El
171: .Ss Abstract Syntax Tree
1.4 schwarze 172: The
1.1 kristaps 173: .Nm
174: functions produce an abstract syntax tree (AST) describing input in a
1.11 schwarze 175: regular form.
176: It may be reviewed at any time with
1.1 kristaps 177: .Fn man_nodes ;
178: however, if called before
179: .Fn man_endparse ,
180: or after
1.4 schwarze 181: .Fn man_endparse
1.1 kristaps 182: or
183: .Fn man_parseln
1.4 schwarze 184: fail, it may be incomplete.
1.1 kristaps 185: .Pp
1.11 schwarze 186: This AST is governed by the ontological rules dictated in
1.1 kristaps 187: .Xr man 7
1.4 schwarze 188: and derives its terminology accordingly.
1.1 kristaps 189: .Pp
1.4 schwarze 190: The AST is composed of
1.1 kristaps 191: .Vt struct man_node
1.11 schwarze 192: nodes with element, root and text types as declared by the
1.1 kristaps 193: .Va type
1.11 schwarze 194: field.
195: Each node also provides its parse point (the
1.1 kristaps 196: .Va line ,
197: .Va sec ,
198: and
199: .Va pos
200: fields), its position in the tree (the
201: .Va parent ,
202: .Va child ,
1.4 schwarze 203: .Va next
1.1 kristaps 204: and
1.4 schwarze 205: .Va prev
1.1 kristaps 206: fields) and some type-specific data.
207: .Pp
208: The tree itself is arranged according to the following normal form,
209: where capitalised non-terminals represent nodes.
210: .Pp
1.7 schwarze 211: .Bl -tag -width "ELEMENTXX" -compact
1.1 kristaps 212: .It ROOT
213: \(<- mnode+
214: .It mnode
1.5 schwarze 215: \(<- ELEMENT | TEXT | BLOCK
216: .It BLOCK
217: \(<- HEAD BODY
218: .It HEAD
219: \(<- mnode*
220: .It BODY
221: \(<- mnode*
1.1 kristaps 222: .It ELEMENT
223: \(<- ELEMENT | TEXT*
224: .It TEXT
225: \(<- [[:alpha:]]*
226: .El
227: .Pp
228: The only elements capable of nesting other elements are those with
229: next-lint scope as documented in
230: .Xr man 7 .
231: .Sh EXAMPLES
232: The following example reads lines from stdin and parses them, operating
1.4 schwarze 233: on the finished parse tree with
1.1 kristaps 234: .Fn parsed .
1.7 schwarze 235: This example does not error-check nor free memory upon failure.
236: .Bd -literal -offset indent
1.12 schwarze 237: struct regset regs;
1.1 kristaps 238: struct man *man;
239: struct man_node *node;
240: char *buf;
241: size_t len;
242: int line;
243:
1.12 schwarze 244: bzero(®s, sizeof(struct regset));
1.1 kristaps 245: line = 1;
1.15 schwarze 246: man = man_alloc(®s, NULL, NULL);
1.7 schwarze 247: buf = NULL;
248: alloc_len = 0;
1.1 kristaps 249:
1.7 schwarze 250: while ((len = getline(&buf, &alloc_len, stdin)) >= 0) {
251: if (len && buflen[len - 1] = '\en')
252: buf[len - 1] = '\e0';
253: if ( ! man_parseln(man, line, buf))
254: errx(1, "man_parseln");
255: line++;
1.1 kristaps 256: }
257:
1.7 schwarze 258: free(buf);
259:
1.1 kristaps 260: if ( ! man_endparse(man))
1.7 schwarze 261: errx(1, "man_endparse");
1.1 kristaps 262: if (NULL == (node = man_node(man)))
1.7 schwarze 263: errx(1, "man_node");
1.1 kristaps 264:
265: parsed(man, node);
266: man_free(man);
267: .Ed
1.11 schwarze 268: .Pp
1.16 schwarze 269: To compile this, execute
270: .Pp
1.19 schwarze 271: .Dl % cc main.c libman.a libmandoc.a
1.16 schwarze 272: .Pp
273: where
1.11 schwarze 274: .Pa main.c
1.16 schwarze 275: is the example file.
1.1 kristaps 276: .Sh SEE ALSO
277: .Xr mandoc 1 ,
278: .Xr man 7
279: .Sh AUTHORS
280: The
281: .Nm
1.11 schwarze 282: library was written by
1.7 schwarze 283: .An Kristaps Dzonsons Aq kristaps@bsd.lv .
![[BACK]](/icons/back.gif){kind=icon}
Return to man.3 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / mandoc