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