mandoc.3

   1 .\"     $Id: mandoc.3,v 1.1 2011/03/22 10:02:50 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: March 22 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 .