contrib/mdocml/mandoc.3

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