mdoc.3

   1 .\"     $Id: mdoc.3,v 1.48 2010/07/07 15:04:54 kristaps Exp $
   2 .\"
   3 .\" Copyright (c) 2009, 2010 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: July 7 2010 $
  19 .Dt MDOC 3
  20 .Os
  21 .Sh NAME
  22 .Nm mdoc ,
  23 .Nm mdoc_alloc ,
  24 .Nm mdoc_endparse ,
  25 .Nm mdoc_free ,
  26 .Nm mdoc_meta ,
  27 .Nm mdoc_node ,
  28 .Nm mdoc_parseln ,
  29 .Nm mdoc_reset
  30 .Nd mdoc macro compiler library
  31 .Sh SYNOPSIS
  32 .In mandoc.h
  33 .In mdoc.h
  34 .Vt extern const char * const * mdoc_macronames;
  35 .Vt extern const char * const * mdoc_argnames;
  36 .Ft "struct mdoc *"
  37 .Fo mdoc_alloc
  38 .Fa "struct regset *regs"
  39 .Fa "void *data"
  40 .Fa "int pflags"
  41 .Fa "mandocmsg msgs"
  42 .Fc
  43 .Ft int
  44 .Fn mdoc_endparse "struct mdoc *mdoc"
  45 .Ft void
  46 .Fn mdoc_free "struct mdoc *mdoc"
  47 .Ft "const struct mdoc_meta *"
  48 .Fn mdoc_meta "const struct mdoc *mdoc"
  49 .Ft "const struct mdoc_node *"
  50 .Fn mdoc_node "const struct mdoc *mdoc"
  51 .Ft int
  52 .Fo mdoc_parseln
  53 .Fa "struct mdoc *mdoc"
  54 .Fa "int line"
  55 .Fa "char *buf"
  56 .Fc
  57 .Ft int
  58 .Fn mdoc_reset "struct mdoc *mdoc"
  59 .Sh DESCRIPTION
  60 The
  61 .Nm mdoc
  62 library parses lines of
  63 .Xr mdoc 7
  64 input
  65 into an abstract syntax tree (AST).
  66 .Pp
  67 In general, applications initiate a parsing sequence with
  68 .Fn mdoc_alloc ,
  69 parse each line in a document with
  70 .Fn mdoc_parseln ,
  71 close the parsing session with
  72 .Fn mdoc_endparse ,
  73 operate over the syntax tree returned by
  74 .Fn mdoc_node
  75 and
  76 .Fn mdoc_meta ,
  77 then free all allocated memory with
  78 .Fn mdoc_free .
  79 The
  80 .Fn mdoc_reset
  81 function may be used in order to reset the parser for another input
  82 sequence.
  83 See the
  84 .Sx EXAMPLES
  85 section for a simple example.
  86 .Pp
  87 This section further defines the
  88 .Sx Types ,
  89 .Sx Functions
  90 and
  91 .Sx Variables
  92 available to programmers.
  93 Following that, the
  94 .Sx Abstract Syntax Tree
  95 section documents the output tree.
  96 .Ss Types
  97 Both functions (see
  98 .Sx Functions )
  99 and variables (see
 100 .Sx Variables )
 101 may use the following types:
 102 .Bl -ohang
 103 .It Vt struct mdoc
 104 An opaque type defined in
 105 .Pa mdoc.c .
 106 Its values are only used privately within the library.
 107 .It Vt struct mdoc_node
 108 A parsed node.
 109 Defined in
 110 .Pa mdoc.h .
 111 See
 112 .Sx Abstract Syntax Tree
 113 for details.
 114 .It Vt mandocmsg
 115 A function callback type defined in
 116 .Pa mandoc.h .
 117 .El
 118 .Ss Functions
 119 Function descriptions follow:
 120 .Bl -ohang
 121 .It Fn mdoc_alloc
 122 Allocates a parsing structure.
 123 The
 124 .Fa data
 125 pointer is passed to
 126 .Fa msgs .
 127 The
 128 .Fa pflags
 129 arguments are defined in
 130 .Pa mdoc.h .
 131 Returns NULL on failure.
 132 If non-NULL, the pointer must be freed with
 133 .Fn mdoc_free .
 134 .It Fn mdoc_reset
 135 Reset the parser for another parse routine.
 136 After its use,
 137 .Fn mdoc_parseln
 138 behaves as if invoked for the first time.
 139 If it returns 0, memory could not be allocated.
 140 .It Fn mdoc_free
 141 Free all resources of a parser.
 142 The pointer is no longer valid after invocation.
 143 .It Fn mdoc_parseln
 144 Parse a nil-terminated line of input.
 145 This line should not contain the trailing newline.
 146 Returns 0 on failure, 1 on success.
 147 The input buffer
 148 .Fa buf
 149 is modified by this function.
 150 .It Fn mdoc_endparse
 151 Signals that the parse is complete.
 152 Note that if
 153 .Fn mdoc_endparse
 154 is called subsequent to
 155 .Fn mdoc_node ,
 156 the resulting tree is incomplete.
 157 Returns 0 on failure, 1 on success.
 158 .It Fn mdoc_node
 159 Returns the first node of the parse.
 160 Note that if
 161 .Fn mdoc_parseln
 162 or
 163 .Fn mdoc_endparse
 164 return 0, the tree will be incomplete.
 165 .It Fn mdoc_meta
 166 Returns the document's parsed meta-data.
 167 If this information has not yet been supplied or
 168 .Fn mdoc_parseln
 169 or
 170 .Fn mdoc_endparse
 171 return 0, the data will be incomplete.
 172 .El
 173 .Ss Variables
 174 The following variables are also defined:
 175 .Bl -ohang
 176 .It Va mdoc_macronames
 177 An array of string-ified token names.
 178 .It Va mdoc_argnames
 179 An array of string-ified token argument names.
 180 .El
 181 .Ss Abstract Syntax Tree
 182 The
 183 .Nm
 184 functions produce an abstract syntax tree (AST) describing input in a
 185 regular form.
 186 It may be reviewed at any time with
 187 .Fn mdoc_nodes ;
 188 however, if called before
 189 .Fn mdoc_endparse ,
 190 or after
 191 .Fn mdoc_endparse
 192 or
 193 .Fn mdoc_parseln
 194 fail, it may be incomplete.
 195 .Pp
 196 This AST is governed by the ontological
 197 rules dictated in
 198 .Xr mdoc 7
 199 and derives its terminology accordingly.
 200 .Qq In-line
 201 elements described in
 202 .Xr mdoc 7
 203 are described simply as
 204 .Qq elements .
 205 .Pp
 206 The AST is composed of
 207 .Vt struct mdoc_node
 208 nodes with block, head, body, element, root and text types as declared
 209 by the
 210 .Va type
 211 field.
 212 Each node also provides its parse point (the
 213 .Va line ,
 214 .Va sec ,
 215 and
 216 .Va pos
 217 fields), its position in the tree (the
 218 .Va parent ,
 219 .Va child ,
 220 .Va nchild ,
 221 .Va next
 222 and
 223 .Va prev
 224 fields) and some type-specific data, in particular, for nodes generated
 225 from macros, the generating macro in the
 226 .Va tok
 227 field.
 228 .Pp
 229 The tree itself is arranged according to the following normal form,
 230 where capitalised non-terminals represent nodes.
 231 .Pp
 232 .Bl -tag -width "ELEMENTXX" -compact
 233 .It ROOT
 234 \(<- mnode+
 235 .It mnode
 236 \(<- BLOCK | ELEMENT | TEXT
 237 .It BLOCK
 238 \(<- HEAD [TEXT] (BODY [TEXT])+ [TAIL [TEXT]]
 239 .It ELEMENT
 240 \(<- TEXT*
 241 .It HEAD
 242 \(<- mnode*
 243 .It BODY
 244 \(<- mnode* [ENDBODY mnode*]
 245 .It TAIL
 246 \(<- mnode*
 247 .It TEXT
 248 \(<- [[:printable:],0x1e]*
 249 .El
 250 .Pp
 251 Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of
 252 the BLOCK production: these refer to punctuation marks.
 253 Furthermore, although a TEXT node will generally have a non-zero-length
 254 string, in the specific case of
 255 .Sq \&.Bd \-literal ,
 256 an empty line will produce a zero-length string.
 257 Multiple body parts are only found in invocations of
 258 .Sq \&Bl \-column ,
 259 where a new body introduces a new phrase.
 260 .Ss Badly-nested Blocks
 261 The ENDBODY node is available to end the formatting associated
 262 with a given block before the physical end of that block.
 263 It has a non-null
 264 .Va end
 265 field, is of the BODY
 266 .Va type ,
 267 has the same
 268 .Va tok
 269 as the BLOCK it is ending, and has a
 270 .Va pending
 271 field pointing to that BLOCK's BODY node.
 272 It is an indirect child of that BODY node
 273 and has no children of its own.
 274 .Pp
 275 An ENDBODY node is generated when a block ends while one of its child
 276 blocks is still open, like in the following example:
 277 .Bd -literal -offset indent
 278 \&.Ao ao
 279 \&.Bo bo ac
 280 \&.Ac bc
 281 \&.Bc end
 282 .Ed
 283 .Pp
 284 This example results in the following block structure:
 285 .Bd -literal -offset indent
 286 BLOCK Ao
 287         HEAD Ao
 288         BODY Ao
 289                 TEXT ao
 290                 BLOCK Bo, pending -> Ao
 291                         HEAD Bo
 292                         BODY Bo
 293                                 TEXT bo
 294                                 TEXT ac
 295                                 ENDBODY Ao, pending -> Ao
 296                                 TEXT bc
 297 TEXT end
 298 .Ed
 299 .Pp
 300 Here, the formatting of the
 301 .Sq \&Ao
 302 block extends from TEXT ao to TEXT ac,
 303 while the formatting of the
 304 .Sq \&Bo
 305 block extends from TEXT bo to TEXT bc.
 306 It renders as follows in
 307 .Fl T Ns Cm ascii
 308 mode:
 309 .Pp
 310 .Dl <ao [bo ac> bc] end
 311 .Pp
 312 Support for badly-nested blocks is only provided for backward
 313 compatibility with some older
 314 .Xr mdoc 7
 315 implementations.
 316 Using badly-nested blocks is
 317 .Em strongly discouraged :
 318 the
 319 .Fl T Ns Cm html
 320 and
 321 .Fl T Ns Cm xhtml
 322 front-ends are unable to render them in any meaningful way.
 323 Furthermore, behaviour when encountering badly-nested blocks is not
 324 consistent across troff implementations, especially when using  multiple
 325 levels of badly-nested blocks.
 326 .Sh EXAMPLES
 327 The following example reads lines from stdin and parses them, operating
 328 on the finished parse tree with
 329 .Fn parsed .
 330 This example does not error-check nor free memory upon failure.
 331 .Bd -literal -offset indent
 332 struct regset regs;
 333 struct mdoc *mdoc;
 334 const struct mdoc_node *node;
 335 char *buf;
 336 size_t len;
 337 int line;
 338
 339 bzero(&regs, sizeof(struct regset));
 340 line = 1;
 341 mdoc = mdoc_alloc(&regs, NULL, 0, NULL);
 342 buf = NULL;
 343 alloc_len = 0;
 344
 345 while ((len = getline(&buf, &alloc_len, stdin)) >= 0) {
 346     if (len && buflen[len - 1] = '\en')
 347         buf[len - 1] = '\e0';
 348     if ( ! mdoc_parseln(mdoc, line, buf))
 349         errx(1, "mdoc_parseln");
 350     line++;
 351 }
 352
 353 if ( ! mdoc_endparse(mdoc))
 354     errx(1, "mdoc_endparse");
 355 if (NULL == (node = mdoc_node(mdoc)))
 356     errx(1, "mdoc_node");
 357
 358 parsed(mdoc, node);
 359 mdoc_free(mdoc);
 360 .Ed
 361 .Pp
 362 Please see
 363 .Pa main.c
 364 in the source archive for a rigorous reference.
 365 .Sh SEE ALSO
 366 .Xr mandoc 1 ,
 367 .Xr mdoc 7
 368 .Sh AUTHORS
 369 The
 370 .Nm
 371 library was written by
 372 .An Kristaps Dzonsons Aq kristaps@bsd.lv .