mandoc.3

   1 .\"     $Id: mandoc.3,v 1.11 2011/06/22 22:10:02 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: June 22 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 mchars_alloc ,
  27 .Nm mchars_free ,
  28 .Nm mchars_num2char ,
  29 .Nm mchars_num2uc ,
  30 .Nm mchars_spec2cp ,
  31 .Nm mchars_spec2str ,
  32 .Nm mdoc_meta ,
  33 .Nm mdoc_node ,
  34 .Nm mparse_alloc ,
  35 .Nm mparse_free ,
  36 .Nm mparse_readfd ,
  37 .Nm mparse_reset ,
  38 .Nm mparse_result ,
  39 .Nm mparse_strerror ,
  40 .Nm mparse_strlevel
  41 .Nd mandoc macro compiler library
  42 .Sh LIBRARY
  43 .Lb mandoc
  44 .Sh SYNOPSIS
  45 .In man.h
  46 .In mdoc.h
  47 .In mandoc.h
  48 .Ft "enum mandoc_esc"
  49 .Fo mandoc_escape
  50 .Fa "const char **in"
  51 .Fa "const char **seq"
  52 .Fa "int *len"
  53 .Fc
  54 .Ft "const struct man_meta *"
  55 .Fo man_meta
  56 .Fa "const struct man *man"
  57 .Fc
  58 .Ft "const struct man_node *"
  59 .Fo man_node
  60 .Fa "const struct man *man"
  61 .Fc
  62 .Ft "struct mchars *"
  63 .Fn mchars_alloc
  64 .Ft void
  65 .Fn mchars_free "struct mchars *p"
  66 .Ft char
  67 .Fn mchars_num2char "const char *cp" "size_t sz"
  68 .Ft int
  69 .Fn mchars_num2uc "const char *cp" "size_t sz"
  70 .Ft "const char *"
  71 .Fo mchars_spec2str
  72 .Fa "struct mchars *p"
  73 .Fa "const char *cp"
  74 .Fa "size_t sz"
  75 .Fa "size_t *rsz"
  76 .Fc
  77 .Ft int
  78 .Fo mchars_spec2cp
  79 .Fa "struct mchars *p"
  80 .Fa "const char *cp"
  81 .Fa "size_t sz"
  82 .Ft "const char *"
  83 .Fc
  84 .Ft "const struct mdoc_meta *"
  85 .Fo mdoc_meta
  86 .Fa "const struct mdoc *mdoc"
  87 .Fc
  88 .Ft "const struct mdoc_node *"
  89 .Fo mdoc_node
  90 .Fa "const struct mdoc *mdoc"
  91 .Fc
  92 .Ft void
  93 .Fo mparse_alloc
  94 .Fa "enum mparset type"
  95 .Fa "enum mandoclevel wlevel"
  96 .Fa "mandocmsg msg"
  97 .Fa "void *msgarg"
  98 .Fc
  99 .Ft void
 100 .Fo mparse_free
 101 .Fa "struct mparse *parse"
 102 .Fc
 103 .Ft "enum mandoclevel"
 104 .Fo mparse_readfd
 105 .Fa "struct mparse *parse"
 106 .Fa "int fd"
 107 .Fa "const char *fname"
 108 .Fc
 109 .Ft void
 110 .Fo mparse_reset
 111 .Fa "struct mparse *parse"
 112 .Fc
 113 .Ft void
 114 .Fo mparse_result
 115 .Fa "struct mparse *parse"
 116 .Fa "struct mdoc **mdoc"
 117 .Fa "struct man **man"
 118 .Fc
 119 .Ft "const char *"
 120 .Fo mparse_strerror
 121 .Fa "enum mandocerr"
 122 .Fc
 123 .Ft "const char *"
 124 .Fo mparse_strlevel
 125 .Fa "enum mandoclevel"
 126 .Fc
 127 .Vt extern const char * const * man_macronames;
 128 .Vt extern const char * const * mdoc_argnames;
 129 .Vt extern const char * const * mdoc_macronames;
 130 .Fd "#define ASCII_NBRSP"
 131 .Fd "#define ASCII_HYPH"
 132 .Sh DESCRIPTION
 133 The
 134 .Nm mandoc
 135 library parses a
 136 .Ux
 137 manual into an abstract syntax tree (AST).
 138 .Ux
 139 manuals are composed of
 140 .Xr mdoc 7
 141 or
 142 .Xr man 7 ,
 143 and may be mixed with
 144 .Xr roff 7 ,
 145 .Xr tbl 7 ,
 146 and
 147 .Xr eqn 7
 148 invocations.
 149 .Pp
 150 The following describes a general parse sequence:
 151 .Bl -enum
 152 .It
 153 initiate a parsing sequence with
 154 .Fn mparse_alloc ;
 155 .It
 156 parse files or file descriptors with
 157 .Fn mparse_readfd ;
 158 .It
 159 retrieve a parsed syntax tree, if the parse was successful, with
 160 .Fn mparse_result ;
 161 .It
 162 iterate over parse nodes with
 163 .Fn mdoc_node
 164 or
 165 .Fn man_node ;
 166 .It
 167 free all allocated memory with
 168 .Fn mparse_free ,
 169 or invoke
 170 .Fn mparse_reset
 171 and parse new files.
 172 .El
 173 .Pp
 174 The
 175 .Nm
 176 library also contains routines for translating character strings into glyphs
 177 .Pq see Fn mchars_alloc
 178 and parsing escape sequences from strings
 179 .Pq see Fn mandoc_escape .
 180 .Sh REFERENCE
 181 This section documents the functions, types, and variables available
 182 via
 183 .In mandoc.h .
 184 .Ss Types
 185 .Bl -ohang
 186 .It Vt "enum mandoc_esc"
 187 An escape sequence classification.
 188 .It Vt "enum mandocerr"
 189 A fatal error, error, or warning message during parsing.
 190 .It Vt "enum mandoclevel"
 191 A classification of an
 192 .Vt "enum mandoclevel"
 193 as regards system operation.
 194 .It Vt "struct mchars"
 195 An opaque pointer to an object allowing for translation between
 196 character strings and glyphs.
 197 See
 198 .Fn mchars_alloc .
 199 .It Vt "enum mparset"
 200 The type of parser when reading input.
 201 This should usually be
 202 .Va MPARSE_AUTO
 203 for auto-detection.
 204 .It Vt "struct mparse"
 205 An opaque pointer to a running parse sequence.
 206 Created with
 207 .Fn mparse_alloc
 208 and freed with
 209 .Fn mparse_free .
 210 This may be used across parsed input if
 211 .Fn mparse_reset
 212 is called between parses.
 213 .It Vt "mandocmsg"
 214 A prototype for a function to handle fatal error, error, and warning
 215 messages emitted by the parser.
 216 .El
 217 .Ss Functions
 218 .Bl -ohang
 219 .It Fn mandoc_escape
 220 Scan an escape sequence, i.e., a character string beginning with
 221 .Sq \e .
 222 Pass a pointer to this string as
 223 .Va end ;
 224 it will be set to the supremum of the parsed escape sequence unless
 225 returning ESCAPE_ERROR, in which case the string is bogus and should be
 226 thrown away.
 227 If not ESCAPE_ERROR or ESCAPE_IGNORE,
 228 .Va start
 229 is set to the first relevant character of the substring (font, glyph,
 230 whatever) of length
 231 .Va sz .
 232 Both
 233 .Va start
 234 and
 235 .Va sz
 236 may be NULL.
 237 .It Fn man_meta
 238 Obtain the meta-data of a successful parse.
 239 This may only be used on a pointer returned by
 240 .Fn mparse_result .
 241 .It Fn man_node
 242 Obtain the root node of a successful parse.
 243 This may only be used on a pointer returned by
 244 .Fn mparse_result .
 245 .It Fn mchars_alloc
 246 Allocate an
 247 .Vt "struct mchars *"
 248 object for translating special characters into glyphs.
 249 See
 250 .Xr mandoc_char 7
 251 for an overview of special characters.
 252 The object must be freed with
 253 .Fn mchars_free .
 254 .It Fn mchars_free
 255 Free an object created with
 256 .Fn mchars_alloc .
 257 .It Fn mchars_num2char
 258 Convert a character index (e.g., the \eN\(aq\(aq escape) into a
 259 printable ASCII character.
 260 Returns \e0 (the nil character) if the input sequence is malformed.
 261 .It Fn mchars_num2uc
 262 Convert a hexadecimal character index (e.g., the \e[uNNNN] escape) into
 263 a Unicode codepoint.
 264 Returns \e0 (the nil character) if the input sequence is malformed.
 265 .It Fn mchars_spec2cp
 266 Convert a special character into a valid Unicode codepoint.
 267 Returns \-1 on failure or a non-zero Unicode codepoint on success.
 268 .It Fn mchars_spec2str
 269 Convert a special character into an ASCII string.
 270 Returns NULL on failure.
 271 .It Fn mdoc_meta
 272 Obtain the meta-data of a successful parse.
 273 This may only be used on a pointer returned by
 274 .Fn mparse_result .
 275 .It Fn mdoc_node
 276 Obtain the root node of a successful parse.
 277 This may only be used on a pointer returned by
 278 .Fn mparse_result .
 279 .It Fn mparse_alloc
 280 Allocate a parser.
 281 The same parser may be used for multiple files so long as
 282 .Fn mparse_reset
 283 is called between parses.
 284 .Fn mparse_free
 285 must be called to free the memory allocated by this function.
 286 .It Fn mparse_free
 287 Free all memory allocated by
 288 .Fn mparse_alloc .
 289 .It Fn mparse_readfd
 290 Parse a file or file descriptor.
 291 If
 292 .Va fd
 293 is -1,
 294 .Va fname
 295 is opened for reading.
 296 Otherwise,
 297 .Va fname
 298 is assumed to be the name associated with
 299 .Va fd .
 300 This may be called multiple times with different parameters; however,
 301 .Fn mparse_reset
 302 should be invoked between parses.
 303 .It Fn mparse_reset
 304 Reset a parser so that
 305 .Fn mparse_readfd
 306 may be used again.
 307 .It Fn mparse_result
 308 Obtain the result of a parse.
 309 Only successful parses
 310 .Po
 311 i.e., those where
 312 .Fn mparse_readfd
 313 returned less than MANDOCLEVEL_FATAL
 314 .Pc
 315 should invoke this function, in which case one of the two pointers will
 316 be filled in.
 317 .It Fn mparse_strerror
 318 Return a statically-allocated string representation of an error code.
 319 .It Fn mparse_strlevel
 320 Return a statically-allocated string representation of a level code.
 321 .El
 322 .Ss Variables
 323 .Bl -ohang
 324 .It Va man_macronames
 325 The string representation of a man macro as indexed by
 326 .Vt "enum mant" .
 327 .It Va mdoc_argnames
 328 The string representation of a mdoc macro argument as indexed by
 329 .Vt "enum mdocargt" .
 330 .It Va mdoc_macronames
 331 The string representation of a mdoc macro as indexed by
 332 .Vt "enum mdoct" .
 333 .El
 334 .Sh IMPLEMENTATION NOTES
 335 This section consists of structural documentation for
 336 .Xr mdoc 7
 337 and
 338 .Xr man 7
 339 syntax trees and strings.
 340 .Ss Man and Mdoc Strings
 341 Strings may be extracted from mdoc and man meta-data, or from text
 342 nodes (MDOC_TEXT and MAN_TEXT, respectively).
 343 These strings have special non-printing formatting cues embedded in the
 344 text itself, as well as
 345 .Xr roff 7
 346 escapes preserved from input.
 347 Implementing systems will need to handle both situations to produce
 348 human-readable text.
 349 In general, strings may be assumed to consist of 7-bit ASCII characters.
 350 .Pp
 351 The following non-printing characters may be embedded in text strings:
 352 .Bl -tag -width Ds
 353 .It Dv ASCII_NBRSP
 354 A non-breaking space character.
 355 .It Dv ASCII_HYPH
 356 A soft hyphen.
 357 .El
 358 .Pp
 359 Escape characters are also passed verbatim into text strings.
 360 An escape character is a sequence of characters beginning with the
 361 backslash
 362 .Pq Sq \e .
 363 To construct human-readable text, these should be intercepted with
 364 .Fn mandoc_escape
 365 and converted with one of
 366 .Fn mchars_num2char ,
 367 .Fn mchars_spec2str ,
 368 and so on.
 369 .Ss Man Abstract Syntax Tree
 370 This AST is governed by the ontological rules dictated in
 371 .Xr man 7
 372 and derives its terminology accordingly.
 373 .Pp
 374 The AST is composed of
 375 .Vt struct man_node
 376 nodes with element, root and text types as declared by the
 377 .Va type
 378 field.
 379 Each node also provides its parse point (the
 380 .Va line ,
 381 .Va sec ,
 382 and
 383 .Va pos
 384 fields), its position in the tree (the
 385 .Va parent ,
 386 .Va child ,
 387 .Va next
 388 and
 389 .Va prev
 390 fields) and some type-specific data.
 391 .Pp
 392 The tree itself is arranged according to the following normal form,
 393 where capitalised non-terminals represent nodes.
 394 .Pp
 395 .Bl -tag -width "ELEMENTXX" -compact
 396 .It ROOT
 397 \(<- mnode+
 398 .It mnode
 399 \(<- ELEMENT | TEXT | BLOCK
 400 .It BLOCK
 401 \(<- HEAD BODY
 402 .It HEAD
 403 \(<- mnode*
 404 .It BODY
 405 \(<- mnode*
 406 .It ELEMENT
 407 \(<- ELEMENT | TEXT*
 408 .It TEXT
 409 \(<- [[:ascii:]]*
 410 .El
 411 .Pp
 412 The only elements capable of nesting other elements are those with
 413 next-lint scope as documented in
 414 .Xr man 7 .
 415 .Ss Mdoc Abstract Syntax Tree
 416 This AST is governed by the ontological
 417 rules dictated in
 418 .Xr mdoc 7
 419 and derives its terminology accordingly.
 420 .Qq In-line
 421 elements described in
 422 .Xr mdoc 7
 423 are described simply as
 424 .Qq elements .
 425 .Pp
 426 The AST is composed of
 427 .Vt struct mdoc_node
 428 nodes with block, head, body, element, root and text types as declared
 429 by the
 430 .Va type
 431 field.
 432 Each node also provides its parse point (the
 433 .Va line ,
 434 .Va sec ,
 435 and
 436 .Va pos
 437 fields), its position in the tree (the
 438 .Va parent ,
 439 .Va child ,
 440 .Va nchild ,
 441 .Va next
 442 and
 443 .Va prev
 444 fields) and some type-specific data, in particular, for nodes generated
 445 from macros, the generating macro in the
 446 .Va tok
 447 field.
 448 .Pp
 449 The tree itself is arranged according to the following normal form,
 450 where capitalised non-terminals represent nodes.
 451 .Pp
 452 .Bl -tag -width "ELEMENTXX" -compact
 453 .It ROOT
 454 \(<- mnode+
 455 .It mnode
 456 \(<- BLOCK | ELEMENT | TEXT
 457 .It BLOCK
 458 \(<- HEAD [TEXT] (BODY [TEXT])+ [TAIL [TEXT]]
 459 .It ELEMENT
 460 \(<- TEXT*
 461 .It HEAD
 462 \(<- mnode*
 463 .It BODY
 464 \(<- mnode* [ENDBODY mnode*]
 465 .It TAIL
 466 \(<- mnode*
 467 .It TEXT
 468 \(<- [[:ascii:]]*
 469 .El
 470 .Pp
 471 Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of
 472 the BLOCK production: these refer to punctuation marks.
 473 Furthermore, although a TEXT node will generally have a non-zero-length
 474 string, in the specific case of
 475 .Sq \&.Bd \-literal ,
 476 an empty line will produce a zero-length string.
 477 Multiple body parts are only found in invocations of
 478 .Sq \&Bl \-column ,
 479 where a new body introduces a new phrase.
 480 .Pp
 481 The
 482 .Xr mdoc 7
 483 syntax tree accommodates for broken block structures as well.
 484 The ENDBODY node is available to end the formatting associated
 485 with a given block before the physical end of that block.
 486 It has a non-null
 487 .Va end
 488 field, is of the BODY
 489 .Va type ,
 490 has the same
 491 .Va tok
 492 as the BLOCK it is ending, and has a
 493 .Va pending
 494 field pointing to that BLOCK's BODY node.
 495 It is an indirect child of that BODY node
 496 and has no children of its own.
 497 .Pp
 498 An ENDBODY node is generated when a block ends while one of its child
 499 blocks is still open, like in the following example:
 500 .Bd -literal -offset indent
 501 \&.Ao ao
 502 \&.Bo bo ac
 503 \&.Ac bc
 504 \&.Bc end
 505 .Ed
 506 .Pp
 507 This example results in the following block structure:
 508 .Bd -literal -offset indent
 509 BLOCK Ao
 510     HEAD Ao
 511     BODY Ao
 512         TEXT ao
 513         BLOCK Bo, pending -> Ao
 514             HEAD Bo
 515             BODY Bo
 516                 TEXT bo
 517                 TEXT ac
 518                 ENDBODY Ao, pending -> Ao
 519                 TEXT bc
 520 TEXT end
 521 .Ed
 522 .Pp
 523 Here, the formatting of the
 524 .Sq \&Ao
 525 block extends from TEXT ao to TEXT ac,
 526 while the formatting of the
 527 .Sq \&Bo
 528 block extends from TEXT bo to TEXT bc.
 529 It renders as follows in
 530 .Fl T Ns Cm ascii
 531 mode:
 532 .Pp
 533 .Dl <ao [bo ac> bc] end
 534 .Pp
 535 Support for badly-nested blocks is only provided for backward
 536 compatibility with some older
 537 .Xr mdoc 7
 538 implementations.
 539 Using badly-nested blocks is
 540 .Em strongly discouraged ;
 541 for example, the
 542 .Fl T Ns Cm html
 543 and
 544 .Fl T Ns Cm xhtml
 545 front-ends to
 546 .Xr mandoc 1
 547 are unable to render them in any meaningful way.
 548 Furthermore, behaviour when encountering badly-nested blocks is not
 549 consistent across troff implementations, especially when using  multiple
 550 levels of badly-nested blocks.
 551 .Sh SEE ALSO
 552 .Xr mandoc 1 ,
 553 .Xr eqn 7 ,
 554 .Xr man 7 ,
 555 .Xr mandoc_char 7 ,
 556 .Xr mdoc 7 ,
 557 .Xr roff 7 ,
 558 .Xr tbl 7
 559 .Sh AUTHORS
 560 The
 561 .Nm
 562 library was written by
 563 .An Kristaps Dzonsons Aq kristaps@bsd.lv .