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