contrib/mdocml/mandoc.3

   1 .\"     $Id: mandoc.3,v 1.20 2013/09/16 22:54:38 schwarze 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: September 16 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 mandoc
  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 Declared in
 260 .In mandoc.h ,
 261 implemented in
 262 .Pa mandoc.c .
 263 .It Fn man_meta
 264 Obtain the meta-data of a successful parse.
 265 This may only be used on a pointer returned by
 266 .Fn mparse_result .
 267 Declared in
 268 .In man.h ,
 269 implemented in
 270 .Pa man.c .
 271 .It Fn man_mparse
 272 Get the parser used for the current output.
 273 Declared in
 274 .In man.h ,
 275 implemented in
 276 .Pa man.c .
 277 .It Fn man_node
 278 Obtain the root node of a successful parse.
 279 This may only be used on a pointer returned by
 280 .Fn mparse_result .
 281 Declared in
 282 .In man.h ,
 283 implemented in
 284 .Pa man.c .
 285 .It Fn mchars_alloc
 286 Allocate an
 287 .Vt "struct mchars *"
 288 object for translating special characters into glyphs.
 289 See
 290 .Xr mandoc_char 7
 291 for an overview of special characters.
 292 The object must be freed with
 293 .Fn mchars_free .
 294 Declared in
 295 .In mandoc.h ,
 296 implemented in
 297 .Pa chars.c .
 298 .It Fn mchars_free
 299 Free an object created with
 300 .Fn mchars_alloc .
 301 Declared in
 302 .In mandoc.h ,
 303 implemented in
 304 .Pa chars.c .
 305 .It Fn mchars_num2char
 306 Convert a character index (e.g., the \eN\(aq\(aq escape) into a
 307 printable ASCII character.
 308 Returns \e0 (the nil character) if the input sequence is malformed.
 309 Declared in
 310 .In mandoc.h ,
 311 implemented in
 312 .Pa chars.c .
 313 .It Fn mchars_num2uc
 314 Convert a hexadecimal character index (e.g., the \e[uNNNN] escape) into
 315 a Unicode codepoint.
 316 Returns \e0 (the nil character) if the input sequence is malformed.
 317 Declared in
 318 .In mandoc.h ,
 319 implemented in
 320 .Pa chars.c .
 321 .It Fn mchars_spec2cp
 322 Convert a special character into a valid Unicode codepoint.
 323 Returns \-1 on failure or a non-zero Unicode codepoint on success.
 324 Declared in
 325 .In mandoc.h ,
 326 implemented in
 327 .Pa chars.c .
 328 .It Fn mchars_spec2str
 329 Convert a special character into an ASCII string.
 330 Returns
 331 .Dv NULL
 332 on failure.
 333 Declared in
 334 .In mandoc.h ,
 335 implemented in
 336 .Pa chars.c .
 337 .It Fn mdoc_meta
 338 Obtain the meta-data of a successful parse.
 339 This may only be used on a pointer returned by
 340 .Fn mparse_result .
 341 Declared in
 342 .In mdoc.h ,
 343 implemented in
 344 .Pa mdoc.c .
 345 .It Fn mdoc_node
 346 Obtain the root node of a successful parse.
 347 This may only be used on a pointer returned by
 348 .Fn mparse_result .
 349 Declared in
 350 .In mdoc.h ,
 351 implemented in
 352 .Pa mdoc.c .
 353 .It Fn mparse_alloc
 354 Allocate a parser.
 355 The same parser may be used for multiple files so long as
 356 .Fn mparse_reset
 357 is called between parses.
 358 .Fn mparse_free
 359 must be called to free the memory allocated by this function.
 360 Declared in
 361 .In mandoc.h ,
 362 implemented in
 363 .Pa read.c .
 364 .It Fn mparse_free
 365 Free all memory allocated by
 366 .Fn mparse_alloc .
 367 Declared in
 368 .In mandoc.h ,
 369 implemented in
 370 .Pa read.c .
 371 .It Fn mparse_getkeep
 372 Acquire the keep buffer.
 373 Must follow a call of
 374 .Fn mparse_keep .
 375 Declared in
 376 .In mandoc.h ,
 377 implemented in
 378 .Pa read.c .
 379 .It Fn mparse_keep
 380 Instruct the parser to retain a copy of its parsed input.
 381 This can be acquired with subsequent
 382 .Fn mparse_getkeep
 383 calls.
 384 Declared in
 385 .In mandoc.h ,
 386 implemented in
 387 .Pa read.c .
 388 .It Fn mparse_readfd
 389 Parse a file or file descriptor.
 390 If
 391 .Va fd
 392 is -1,
 393 .Va fname
 394 is opened for reading.
 395 Otherwise,
 396 .Va fname
 397 is assumed to be the name associated with
 398 .Va fd .
 399 This may be called multiple times with different parameters; however,
 400 .Fn mparse_reset
 401 should be invoked between parses.
 402 Declared in
 403 .In mandoc.h ,
 404 implemented in
 405 .Pa read.c .
 406 .It Fn mparse_reset
 407 Reset a parser so that
 408 .Fn mparse_readfd
 409 may be used again.
 410 Declared in
 411 .In mandoc.h ,
 412 implemented in
 413 .Pa read.c .
 414 .It Fn mparse_result
 415 Obtain the result of a parse.
 416 Only successful parses
 417 .Po
 418 i.e., those where
 419 .Fn mparse_readfd
 420 returned less than MANDOCLEVEL_FATAL
 421 .Pc
 422 should invoke this function, in which case one of the two pointers will
 423 be filled in.
 424 Declared in
 425 .In mandoc.h ,
 426 implemented in
 427 .Pa read.c .
 428 .It Fn mparse_strerror
 429 Return a statically-allocated string representation of an error code.
 430 Declared in
 431 .In mandoc.h ,
 432 implemented in
 433 .Pa read.c .
 434 .It Fn mparse_strlevel
 435 Return a statically-allocated string representation of a level code.
 436 Declared in
 437 .In mandoc.h ,
 438 implemented in
 439 .Pa read.c .
 440 .El
 441 .Ss Variables
 442 .Bl -ohang
 443 .It Va man_macronames
 444 The string representation of a man macro as indexed by
 445 .Vt "enum mant" .
 446 .It Va mdoc_argnames
 447 The string representation of a mdoc macro argument as indexed by
 448 .Vt "enum mdocargt" .
 449 .It Va mdoc_macronames
 450 The string representation of a mdoc macro as indexed by
 451 .Vt "enum mdoct" .
 452 .El
 453 .Sh IMPLEMENTATION NOTES
 454 This section consists of structural documentation for
 455 .Xr mdoc 7
 456 and
 457 .Xr man 7
 458 syntax trees and strings.
 459 .Ss Man and Mdoc Strings
 460 Strings may be extracted from mdoc and man meta-data, or from text
 461 nodes (MDOC_TEXT and MAN_TEXT, respectively).
 462 These strings have special non-printing formatting cues embedded in the
 463 text itself, as well as
 464 .Xr roff 7
 465 escapes preserved from input.
 466 Implementing systems will need to handle both situations to produce
 467 human-readable text.
 468 In general, strings may be assumed to consist of 7-bit ASCII characters.
 469 .Pp
 470 The following non-printing characters may be embedded in text strings:
 471 .Bl -tag -width Ds
 472 .It Dv ASCII_NBRSP
 473 A non-breaking space character.
 474 .It Dv ASCII_HYPH
 475 A soft hyphen.
 476 .El
 477 .Pp
 478 Escape characters are also passed verbatim into text strings.
 479 An escape character is a sequence of characters beginning with the
 480 backslash
 481 .Pq Sq \e .
 482 To construct human-readable text, these should be intercepted with
 483 .Fn mandoc_escape
 484 and converted with one of
 485 .Fn mchars_num2char ,
 486 .Fn mchars_spec2str ,
 487 and so on.
 488 .Ss Man Abstract Syntax Tree
 489 This AST is governed by the ontological rules dictated in
 490 .Xr man 7
 491 and derives its terminology accordingly.
 492 .Pp
 493 The AST is composed of
 494 .Vt struct man_node
 495 nodes with element, root and text types as declared by the
 496 .Va type
 497 field.
 498 Each node also provides its parse point (the
 499 .Va line ,
 500 .Va sec ,
 501 and
 502 .Va pos
 503 fields), its position in the tree (the
 504 .Va parent ,
 505 .Va child ,
 506 .Va next
 507 and
 508 .Va prev
 509 fields) and some type-specific data.
 510 .Pp
 511 The tree itself is arranged according to the following normal form,
 512 where capitalised non-terminals represent nodes.
 513 .Pp
 514 .Bl -tag -width "ELEMENTXX" -compact
 515 .It ROOT
 516 \(<- mnode+
 517 .It mnode
 518 \(<- ELEMENT | TEXT | BLOCK
 519 .It BLOCK
 520 \(<- HEAD BODY
 521 .It HEAD
 522 \(<- mnode*
 523 .It BODY
 524 \(<- mnode*
 525 .It ELEMENT
 526 \(<- ELEMENT | TEXT*
 527 .It TEXT
 528 \(<- [[:ascii:]]*
 529 .El
 530 .Pp
 531 The only elements capable of nesting other elements are those with
 532 next-lint scope as documented in
 533 .Xr man 7 .
 534 .Ss Mdoc Abstract Syntax Tree
 535 This AST is governed by the ontological
 536 rules dictated in
 537 .Xr mdoc 7
 538 and derives its terminology accordingly.
 539 .Qq In-line
 540 elements described in
 541 .Xr mdoc 7
 542 are described simply as
 543 .Qq elements .
 544 .Pp
 545 The AST is composed of
 546 .Vt struct mdoc_node
 547 nodes with block, head, body, element, root and text types as declared
 548 by the
 549 .Va type
 550 field.
 551 Each node also provides its parse point (the
 552 .Va line ,
 553 .Va sec ,
 554 and
 555 .Va pos
 556 fields), its position in the tree (the
 557 .Va parent ,
 558 .Va child ,
 559 .Va nchild ,
 560 .Va next
 561 and
 562 .Va prev
 563 fields) and some type-specific data, in particular, for nodes generated
 564 from macros, the generating macro in the
 565 .Va tok
 566 field.
 567 .Pp
 568 The tree itself is arranged according to the following normal form,
 569 where capitalised non-terminals represent nodes.
 570 .Pp
 571 .Bl -tag -width "ELEMENTXX" -compact
 572 .It ROOT
 573 \(<- mnode+
 574 .It mnode
 575 \(<- BLOCK | ELEMENT | TEXT
 576 .It BLOCK
 577 \(<- HEAD [TEXT] (BODY [TEXT])+ [TAIL [TEXT]]
 578 .It ELEMENT
 579 \(<- TEXT*
 580 .It HEAD
 581 \(<- mnode*
 582 .It BODY
 583 \(<- mnode* [ENDBODY mnode*]
 584 .It TAIL
 585 \(<- mnode*
 586 .It TEXT
 587 \(<- [[:ascii:]]*
 588 .El
 589 .Pp
 590 Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of
 591 the BLOCK production: these refer to punctuation marks.
 592 Furthermore, although a TEXT node will generally have a non-zero-length
 593 string, in the specific case of
 594 .Sq \&.Bd \-literal ,
 595 an empty line will produce a zero-length string.
 596 Multiple body parts are only found in invocations of
 597 .Sq \&Bl \-column ,
 598 where a new body introduces a new phrase.
 599 .Pp
 600 The
 601 .Xr mdoc 7
 602 syntax tree accommodates for broken block structures as well.
 603 The ENDBODY node is available to end the formatting associated
 604 with a given block before the physical end of that block.
 605 It has a non-null
 606 .Va end
 607 field, is of the BODY
 608 .Va type ,
 609 has the same
 610 .Va tok
 611 as the BLOCK it is ending, and has a
 612 .Va pending
 613 field pointing to that BLOCK's BODY node.
 614 It is an indirect child of that BODY node
 615 and has no children of its own.
 616 .Pp
 617 An ENDBODY node is generated when a block ends while one of its child
 618 blocks is still open, like in the following example:
 619 .Bd -literal -offset indent
 620 \&.Ao ao
 621 \&.Bo bo ac
 622 \&.Ac bc
 623 \&.Bc end
 624 .Ed
 625 .Pp
 626 This example results in the following block structure:
 627 .Bd -literal -offset indent
 628 BLOCK Ao
 629     HEAD Ao
 630     BODY Ao
 631         TEXT ao
 632         BLOCK Bo, pending -> Ao
 633             HEAD Bo
 634             BODY Bo
 635                 TEXT bo
 636                 TEXT ac
 637                 ENDBODY Ao, pending -> Ao
 638                 TEXT bc
 639 TEXT end
 640 .Ed
 641 .Pp
 642 Here, the formatting of the
 643 .Sq \&Ao
 644 block extends from TEXT ao to TEXT ac,
 645 while the formatting of the
 646 .Sq \&Bo
 647 block extends from TEXT bo to TEXT bc.
 648 It renders as follows in
 649 .Fl T Ns Cm ascii
 650 mode:
 651 .Pp
 652 .Dl <ao [bo ac> bc] end
 653 .Pp
 654 Support for badly-nested blocks is only provided for backward
 655 compatibility with some older
 656 .Xr mdoc 7
 657 implementations.
 658 Using badly-nested blocks is
 659 .Em strongly discouraged ;
 660 for example, the
 661 .Fl T Ns Cm html
 662 and
 663 .Fl T Ns Cm xhtml
 664 front-ends to
 665 .Xr mandoc 1
 666 are unable to render them in any meaningful way.
 667 Furthermore, behaviour when encountering badly-nested blocks is not
 668 consistent across troff implementations, especially when using  multiple
 669 levels of badly-nested blocks.
 670 .Sh SEE ALSO
 671 .Xr mandoc 1 ,
 672 .Xr eqn 7 ,
 673 .Xr man 7 ,
 674 .Xr mandoc_char 7 ,
 675 .Xr mdoc 7 ,
 676 .Xr roff 7 ,
 677 .Xr tbl 7
 678 .Sh AUTHORS
 679 The
 680 .Nm
 681 library was written by
 682 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .