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

Annotation of mandoc/mandoc.3, Revision 1.1

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

CVSweb