mandoc.3

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