1.\" $Vendor-Id: mandoc.3,v 1.2 2011/03/28 21:49:42 kristaps Exp $ 2.\" 3.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> 4.\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org> 5.\" 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. 9.\" 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. 17.\" 18.Dd March 28, 2011 19.Dt MANDOC 3 20.Os 21.Sh NAME 22.Nm mandoc , 23.Nm man_meta , 24.Nm man_node , 25.Nm mdoc_meta , 26.Nm mdoc_node , 27.Nm mparse_alloc , 28.Nm mparse_free , 29.Nm mparse_readfd , 30.Nm mparse_reset , 31.Nm mparse_result , 32.Nm mparse_strerror , 33.Nm mparse_strlevel 34.Nd mandoc macro compiler library 35.Sh SYNOPSIS 36.In man.h 37.In mdoc.h 38.In mandoc.h 39.Ft "const struct man_meta *" 40.Fo man_meta 41.Fa "const struct man *man" 42.Fc 43.Ft "const struct man_node *" 44.Fo man_node 45.Fa "const struct man *man" 46.Fc 47.Ft "const struct mdoc_meta *" 48.Fo mdoc_meta 49.Fa "const struct mdoc *mdoc" 50.Fc 51.Ft "const struct mdoc_node *" 52.Fo mdoc_node 53.Fa "const struct mdoc *mdoc" 54.Fc 55.Ft void 56.Fo mparse_alloc 57.Fa "enum mparset type" 58.Fa "enum mandoclevel wlevel" 59.Fa "mandocmsg msg" 60.Fa "void *msgarg" 61.Fc 62.Ft void 63.Fo mparse_free 64.Fa "struct mparse *parse" 65.Fc 66.Ft "enum mandoclevel" 67.Fo mparse_readfd 68.Fa "struct mparse *parse" 69.Fa "int fd" 70.Fa "const char *fname" 71.Fc 72.Ft void 73.Fo mparse_reset 74.Fa "struct mparse *parse" 75.Fc 76.Ft void 77.Fo mparse_result 78.Fa "struct mparse *parse" 79.Fa "struct mdoc **mdoc" 80.Fa "struct man **man" 81.Fc 82.Ft "const char *" 83.Fo mparse_strerror 84.Fa "enum mandocerr" 85.Fc 86.Ft "const char *" 87.Fo mparse_strlevel 88.Fa "enum mandoclevel" 89.Fc 90.Vt extern const char * const * man_macronames; 91.Vt extern const char * const * mdoc_argnames; 92.Vt extern const char * const * mdoc_macronames; 93.Sh DESCRIPTION 94The 95.Nm mandoc 96library parses a 97.Ux 98manual into an abstract syntax tree (AST). 99.Ux 100manuals are composed of 101.Xr mdoc 7 102or 103.Xr man 7 , 104and may be mixed with 105.Xr roff 7 , 106.Xr tbl 7 , 107and 108.Xr eqn 7 109invocations. 110.Pp 111The following describes a general parse sequence: 112.Bl -enum 113.It 114initiate a parsing sequence with 115.Fn mparse_alloc ; 116.It 117parse files or file descriptors with 118.Fn mparse_readfd ; 119.It 120retrieve a parsed syntax tree, if the parse was successful, with 121.Fn mparse_result ; 122.It 123iterate over parse nodes with 124.Fn mdoc_node 125or 126.Fn man_node ; 127.It 128free all allocated memory with 129.Fn mparse_free , 130or invoke 131.Fn mparse_reset 132and parse new files. 133.El 134.Sh IMPLEMENTATION NOTES 135This section consists of structural documentation for 136.Xr mdoc 7 137and 138.Xr man 7 139syntax trees. 140.Ss Man Abstract Syntax Tree 141This AST is governed by the ontological rules dictated in 142.Xr man 7 143and derives its terminology accordingly. 144.Pp 145The AST is composed of 146.Vt struct man_node 147nodes with element, root and text types as declared by the 148.Va type 149field. 150Each node also provides its parse point (the 151.Va line , 152.Va sec , 153and 154.Va pos 155fields), its position in the tree (the 156.Va parent , 157.Va child , 158.Va next 159and 160.Va prev 161fields) and some type-specific data. 162.Pp 163The tree itself is arranged according to the following normal form, 164where capitalised non-terminals represent nodes. 165.Pp 166.Bl -tag -width "ELEMENTXX" -compact 167.It ROOT 168\(<- mnode+ 169.It mnode 170\(<- ELEMENT | TEXT | BLOCK 171.It BLOCK 172\(<- HEAD BODY 173.It HEAD 174\(<- mnode* 175.It BODY 176\(<- mnode* 177.It ELEMENT 178\(<- ELEMENT | TEXT* 179.It TEXT 180\(<- [[:alpha:]]* 181.El 182.Pp 183The only elements capable of nesting other elements are those with 184next-lint scope as documented in 185.Xr man 7 . 186.Ss Mdoc Abstract Syntax Tree 187This AST is governed by the ontological 188rules dictated in 189.Xr mdoc 7 190and derives its terminology accordingly. 191.Qq In-line 192elements described in 193.Xr mdoc 7 194are described simply as 195.Qq elements . 196.Pp 197The AST is composed of 198.Vt struct mdoc_node 199nodes with block, head, body, element, root and text types as declared 200by the 201.Va type 202field. 203Each node also provides its parse point (the 204.Va line , 205.Va sec , 206and 207.Va pos 208fields), its position in the tree (the 209.Va parent , 210.Va child , 211.Va nchild , 212.Va next 213and 214.Va prev 215fields) and some type-specific data, in particular, for nodes generated 216from macros, the generating macro in the 217.Va tok 218field. 219.Pp 220The tree itself is arranged according to the following normal form, 221where capitalised non-terminals represent nodes. 222.Pp 223.Bl -tag -width "ELEMENTXX" -compact 224.It ROOT 225\(<- mnode+ 226.It mnode 227\(<- BLOCK | ELEMENT | TEXT 228.It BLOCK 229\(<- HEAD [TEXT] (BODY [TEXT])+ [TAIL [TEXT]] 230.It ELEMENT 231\(<- TEXT* 232.It HEAD 233\(<- mnode* 234.It BODY 235\(<- mnode* [ENDBODY mnode*] 236.It TAIL 237\(<- mnode* 238.It TEXT 239\(<- [[:printable:],0x1e]* 240.El 241.Pp 242Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of 243the BLOCK production: these refer to punctuation marks. 244Furthermore, although a TEXT node will generally have a non-zero-length 245string, in the specific case of 246.Sq \&.Bd \-literal , 247an empty line will produce a zero-length string. 248Multiple body parts are only found in invocations of 249.Sq \&Bl \-column , 250where a new body introduces a new phrase. 251.Pp 252The 253.Xr mdoc 7 254syntax tree accomodates for broken block structures as well. 255The ENDBODY node is available to end the formatting associated 256with a given block before the physical end of that block. 257It has a non-null 258.Va end 259field, is of the BODY 260.Va type , 261has the same 262.Va tok 263as the BLOCK it is ending, and has a 264.Va pending 265field pointing to that BLOCK's BODY node. 266It is an indirect child of that BODY node 267and has no children of its own. 268.Pp 269An ENDBODY node is generated when a block ends while one of its child 270blocks is still open, like in the following example: 271.Bd -literal -offset indent 272\&.Ao ao 273\&.Bo bo ac 274\&.Ac bc 275\&.Bc end 276.Ed 277.Pp 278This example results in the following block structure: 279.Bd -literal -offset indent 280BLOCK Ao 281 HEAD Ao 282 BODY Ao 283 TEXT ao 284 BLOCK Bo, pending -> Ao 285 HEAD Bo 286 BODY Bo 287 TEXT bo 288 TEXT ac 289 ENDBODY Ao, pending -> Ao 290 TEXT bc 291TEXT end 292.Ed 293.Pp 294Here, the formatting of the 295.Sq \&Ao 296block extends from TEXT ao to TEXT ac, 297while the formatting of the 298.Sq \&Bo 299block extends from TEXT bo to TEXT bc. 300It renders as follows in 301.Fl T Ns Cm ascii 302mode: 303.Pp 304.Dl <ao [bo ac> bc] end 305.Pp 306Support for badly-nested blocks is only provided for backward 307compatibility with some older 308.Xr mdoc 7 309implementations. 310Using badly-nested blocks is 311.Em strongly discouraged ; 312for example, the 313.Fl T Ns Cm html 314and 315.Fl T Ns Cm xhtml 316front-ends to 317.Xr mandoc 1 318are unable to render them in any meaningful way. 319Furthermore, behaviour when encountering badly-nested blocks is not 320consistent across troff implementations, especially when using multiple 321levels of badly-nested blocks. 322.Sh SEE ALSO 323.Xr mandoc 1 , 324.Xr eqn 7 , 325.Xr man 7 , 326.Xr mdoc 7 , 327.Xr roff 7 , 328.Xr tbl 7 329.Sh AUTHORS 330The 331.Nm 332library was written by 333.An Kristaps Dzonsons Aq kristaps@bsd.lv . 334