contrib/mdocml/mandoc.3

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