[BACK]Return to mandoc.3 CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / mandoc

Annotation of mandoc/mandoc.3, Revision 1.11

1.11    ! kristaps    1: .\"    $Id: mandoc.3,v 1.10 2011/05/24 21:41:11 kristaps Exp $
1.1       kristaps    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: .\"
1.10      kristaps   18: .Dd $Mdocdate: May 24 2011 $
1.1       kristaps   19: .Dt MANDOC 3
                     20: .Os
                     21: .Sh NAME
                     22: .Nm mandoc ,
1.3       kristaps   23: .Nm mandoc_escape ,
1.1       kristaps   24: .Nm man_meta ,
                     25: .Nm man_node ,
1.6       kristaps   26: .Nm mchars_alloc ,
                     27: .Nm mchars_free ,
                     28: .Nm mchars_num2char ,
1.7       kristaps   29: .Nm mchars_num2uc ,
1.6       kristaps   30: .Nm mchars_spec2cp ,
                     31: .Nm mchars_spec2str ,
1.1       kristaps   32: .Nm mdoc_meta ,
                     33: .Nm mdoc_node ,
                     34: .Nm mparse_alloc ,
                     35: .Nm mparse_free ,
                     36: .Nm mparse_readfd ,
                     37: .Nm mparse_reset ,
1.2       kristaps   38: .Nm mparse_result ,
                     39: .Nm mparse_strerror ,
                     40: .Nm mparse_strlevel
1.1       kristaps   41: .Nd mandoc macro compiler library
1.8       kristaps   42: .Sh LIBRARY
                     43: .Lb mandoc
1.1       kristaps   44: .Sh SYNOPSIS
                     45: .In man.h
                     46: .In mdoc.h
                     47: .In mandoc.h
1.3       kristaps   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
1.1       kristaps   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
1.6       kristaps   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"
1.7       kristaps   68: .Ft int
                     69: .Fn mchars_num2uc "const char *cp" "size_t sz"
1.6       kristaps   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
1.1       kristaps   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"
1.2       kristaps  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"
1.1       kristaps  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;
1.4       kristaps  130: .Fd "#define ASCII_NBRSP"
                    131: .Fd "#define ASCII_HYPH"
1.1       kristaps  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.
1.3       kristaps  172: .El
1.6       kristaps  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 .
1.3       kristaps  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"
1.11    ! kristaps  187: An escape sequence classification.
1.3       kristaps  188: .It Vt "enum mandocerr"
1.11    ! kristaps  189: A fatal error, error, or warning message during parsing.
1.3       kristaps  190: .It Vt "enum mandoclevel"
1.11    ! kristaps  191: A classification of an
        !           192: .Vt "enum mandoclevel"
        !           193: as regards system operation.
1.6       kristaps  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 .
1.3       kristaps  199: .It Vt "enum mparset"
1.11    ! kristaps  200: The type of parser when reading input.
        !           201: This should usually be
        !           202: .Va MPARSE_AUTO
        !           203: for auto-detection.
1.3       kristaps  204: .It Vt "struct mparse"
1.11    ! kristaps  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.
1.3       kristaps  213: .It Vt "mandocmsg"
1.11    ! kristaps  214: A prototype for a function to handle fatal error, error, and warning
        !           215: messages emitted by the parser.
1.3       kristaps  216: .El
                    217: .Ss Functions
                    218: .Bl -ohang
                    219: .It Fn mandoc_escape
1.4       kristaps  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.
1.3       kristaps  237: .It Fn man_meta
1.4       kristaps  238: Obtain the meta-data of a successful parse.
                    239: This may only be used on a pointer returned by
                    240: .Fn mparse_result .
1.3       kristaps  241: .It Fn man_node
1.4       kristaps  242: Obtain the root node of a successful parse.
                    243: This may only be used on a pointer returned by
                    244: .Fn mparse_result .
1.6       kristaps  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
1.7       kristaps  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.
1.6       kristaps  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.
1.10      kristaps  267: Returns \-1 on failure or a non-zero Unicode codepoint on success.
1.6       kristaps  268: .It Fn mchars_spec2str
                    269: Convert a special character into an ASCII string.
                    270: Returns NULL on failure.
1.3       kristaps  271: .It Fn mdoc_meta
1.4       kristaps  272: Obtain the meta-data of a successful parse.
                    273: This may only be used on a pointer returned by
                    274: .Fn mparse_result .
1.3       kristaps  275: .It Fn mdoc_node
1.4       kristaps  276: Obtain the root node of a successful parse.
                    277: This may only be used on a pointer returned by
                    278: .Fn mparse_result .
1.3       kristaps  279: .It Fn mparse_alloc
1.4       kristaps  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.
1.3       kristaps  286: .It Fn mparse_free
1.4       kristaps  287: Free all memory allocated by
                    288: .Fn mparse_alloc .
1.3       kristaps  289: .It Fn mparse_readfd
1.4       kristaps  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.
1.3       kristaps  303: .It Fn mparse_reset
1.4       kristaps  304: Reset a parser so that
                    305: .Fn mparse_readfd
                    306: may be used again.
1.3       kristaps  307: .It Fn mparse_result
1.4       kristaps  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.
1.3       kristaps  317: .It Fn mparse_strerror
1.4       kristaps  318: Return a statically-allocated string representation of an error code.
1.3       kristaps  319: .It Fn mparse_strlevel
1.4       kristaps  320: Return a statically-allocated string representation of a level code.
1.3       kristaps  321: .El
                    322: .Ss Variables
                    323: .Bl -ohang
                    324: .It Va man_macronames
1.4       kristaps  325: The string representation of a man macro as indexed by
                    326: .Vt "enum mant" .
1.3       kristaps  327: .It Va mdoc_argnames
1.4       kristaps  328: The string representation of a mdoc macro argument as indexed by
                    329: .Vt "enum mdocargt" .
1.3       kristaps  330: .It Va mdoc_macronames
1.4       kristaps  331: The string representation of a mdoc macro as indexed by
                    332: .Vt "enum mdoct" .
1.1       kristaps  333: .El
                    334: .Sh IMPLEMENTATION NOTES
                    335: This section consists of structural documentation for
                    336: .Xr mdoc 7
                    337: and
                    338: .Xr man 7
1.11    ! kristaps  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.
1.1       kristaps  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
1.11    ! kristaps  409: \(<- [[:ascii:]]*
1.1       kristaps  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
1.11    ! kristaps  468: \(<- [[:ascii:]]*
1.1       kristaps  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
1.5       kristaps  483: syntax tree accommodates for broken block structures as well.
1.1       kristaps  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 ,
1.6       kristaps  555: .Xr mandoc_char 7 ,
1.1       kristaps  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 .

CVSweb