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