1 .\" $Id: mandoc.3,v 1.2 2011/03/28 21:49:42 kristaps Exp $
3 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
4 .\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>
6 .\" Permission to use, copy, modify, and distribute this software for any
7 .\" purpose with or without fee is hereby granted, provided that the above
8 .\" copyright notice and this permission notice appear in all copies.
10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
18 .Dd $Mdocdate: March 28 2011 $
34 .Nd mandoc macro compiler library
39 .Ft "const struct man_meta *"
41 .Fa "const struct man *man"
43 .Ft "const struct man_node *"
45 .Fa "const struct man *man"
47 .Ft "const struct mdoc_meta *"
49 .Fa "const struct mdoc *mdoc"
51 .Ft "const struct mdoc_node *"
53 .Fa "const struct mdoc *mdoc"
57 .Fa "enum mparset type"
58 .Fa "enum mandoclevel wlevel"
64 .Fa "struct mparse *parse"
66 .Ft "enum mandoclevel"
68 .Fa "struct mparse *parse"
70 .Fa "const char *fname"
74 .Fa "struct mparse *parse"
78 .Fa "struct mparse *parse"
79 .Fa "struct mdoc **mdoc"
80 .Fa "struct man **man"
88 .Fa "enum mandoclevel"
90 .Vt extern const char * const * man_macronames;
91 .Vt extern const char * const * mdoc_argnames;
92 .Vt extern const char * const * mdoc_macronames;
98 manual into an abstract syntax tree (AST).
100 manuals are composed of
104 and may be mixed with
111 The following describes a general parse sequence:
114 initiate a parsing sequence with
117 parse files or file descriptors with
120 retrieve a parsed syntax tree, if the parse was successful, with
123 iterate over parse nodes with
128 free all allocated memory with
134 .Sh IMPLEMENTATION NOTES
135 This section consists of structural documentation for
140 .Ss Man Abstract Syntax Tree
141 This AST is governed by the ontological rules dictated in
143 and derives its terminology accordingly.
145 The AST is composed of
147 nodes with element, root and text types as declared by the
150 Each node also provides its parse point (the
155 fields), its position in the tree (the
161 fields) and some type-specific data.
163 The tree itself is arranged according to the following normal form,
164 where capitalised non-terminals represent nodes.
166 .Bl -tag -width "ELEMENTXX" -compact
170 \(<- ELEMENT | TEXT | BLOCK
183 The only elements capable of nesting other elements are those with
184 next-lint scope as documented in
186 .Ss Mdoc Abstract Syntax Tree
187 This AST is governed by the ontological
190 and derives its terminology accordingly.
192 elements described in
194 are described simply as
197 The AST is composed of
199 nodes with block, head, body, element, root and text types as declared
203 Each node also provides its parse point (the
208 fields), its position in the tree (the
215 fields) and some type-specific data, in particular, for nodes generated
216 from macros, the generating macro in the
220 The tree itself is arranged according to the following normal form,
221 where capitalised non-terminals represent nodes.
223 .Bl -tag -width "ELEMENTXX" -compact
227 \(<- BLOCK | ELEMENT | TEXT
229 \(<- HEAD [TEXT] (BODY [TEXT])+ [TAIL [TEXT]]
235 \(<- mnode* [ENDBODY mnode*]
239 \(<- [[:printable:],0x1e]*
242 Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of
243 the BLOCK production: these refer to punctuation marks.
244 Furthermore, although a TEXT node will generally have a non-zero-length
245 string, in the specific case of
246 .Sq \&.Bd \-literal ,
247 an empty line will produce a zero-length string.
248 Multiple body parts are only found in invocations of
250 where a new body introduces a new phrase.
254 syntax tree accomodates for broken block structures as well.
255 The ENDBODY node is available to end the formatting associated
256 with a given block before the physical end of that block.
259 field, is of the BODY
263 as the BLOCK it is ending, and has a
265 field pointing to that BLOCK's BODY node.
266 It is an indirect child of that BODY node
267 and has no children of its own.
269 An ENDBODY node is generated when a block ends while one of its child
270 blocks is still open, like in the following example:
271 .Bd -literal -offset indent
278 This example results in the following block structure:
279 .Bd -literal -offset indent
284 BLOCK Bo, pending -> Ao
289 ENDBODY Ao, pending -> Ao
294 Here, the formatting of the
296 block extends from TEXT ao to TEXT ac,
297 while the formatting of the
299 block extends from TEXT bo to TEXT bc.
300 It renders as follows in
304 .Dl <ao [bo ac> bc] end
306 Support for badly-nested blocks is only provided for backward
307 compatibility with some older
310 Using badly-nested blocks is
311 .Em strongly discouraged ;
318 are unable to render them in any meaningful way.
319 Furthermore, behaviour when encountering badly-nested blocks is not
320 consistent across troff implementations, especially when using multiple
321 levels of badly-nested blocks.
332 library was written by
333 .An Kristaps Dzonsons Aq kristaps@bsd.lv .