mdoc.3

   1 .\"     $Id: mdoc.3,v 1.45 2010/06/29 19:20:38 schwarze Exp $
   2 .\"
   3 .\" Copyright (c) 2009-2010 Kristaps Dzonsons <kristaps@bsd.lv>
   4 .\"
   5 .\" Permission to use, copy, modify, and distribute this software for any
   6 .\" purpose with or without fee is hereby granted, provided that the above
   7 .\" copyright notice and this permission notice appear in all copies.
   8 .\"
   9 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  10 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  11 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  12 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  13 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  14 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  15 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  16 .\"
  17 .Dd $Mdocdate: June 29 2010 $
  18 .Dt MDOC 3
  19 .Os
  20 .Sh NAME
  21 .Nm mdoc ,
  22 .Nm mdoc_alloc ,
  23 .Nm mdoc_endparse ,
  24 .Nm mdoc_free ,
  25 .Nm mdoc_meta ,
  26 .Nm mdoc_node ,
  27 .Nm mdoc_parseln ,
  28 .Nm mdoc_reset
  29 .Nd mdoc macro compiler library
  30 .Sh SYNOPSIS
  31 .In mandoc.h
  32 .In regs.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 A special kind of node is available to end the formatting
 262 associated with a given block before the physical end of that block.
 263 Such an ENDBODY node 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 Ao block extends from TEXT ao to TEXT ac,
 301 while the formatting of the Bo block extends from TEXT bo to TEXT bc,
 302 rendering like this in
 303 .Fl T Ns Cm ascii
 304 mode:
 305 .Dl <ao [bo ac> bc] end
 306 Support for badly nested blocks is only provided for backward
 307 compatibility with some older
 308 .Xr mdoc 7
 309 implementations.
 310 Using them in new code is stronly discouraged:
 311 Some frontends, in particular
 312 .Fl T Ns Cm html ,
 313 are unable to render them in any meaningful way,
 314 many other
 315 .Xr mdoc 7
 316 implementations do not support them, and even for those that do,
 317 the behaviour is not well-defined, in particular when using multiple
 318 levels of badly nested blocks.
 319 .Sh EXAMPLES
 320 The following example reads lines from stdin and parses them, operating
 321 on the finished parse tree with
 322 .Fn parsed .
 323 This example does not error-check nor free memory upon failure.
 324 .Bd -literal -offset indent
 325 struct regset regs;
 326 struct mdoc *mdoc;
 327 const struct mdoc_node *node;
 328 char *buf;
 329 size_t len;
 330 int line;
 331
 332 bzero(&regs, sizeof(struct regset));
 333 line = 1;
 334 mdoc = mdoc_alloc(&regs, NULL, 0, NULL);
 335 buf = NULL;
 336 alloc_len = 0;
 337
 338 while ((len = getline(&buf, &alloc_len, stdin)) >= 0) {
 339     if (len && buflen[len - 1] = '\en')
 340         buf[len - 1] = '\e0';
 341     if ( ! mdoc_parseln(mdoc, line, buf))
 342         errx(1, "mdoc_parseln");
 343     line++;
 344 }
 345
 346 if ( ! mdoc_endparse(mdoc))
 347     errx(1, "mdoc_endparse");
 348 if (NULL == (node = mdoc_node(mdoc)))
 349     errx(1, "mdoc_node");
 350
 351 parsed(mdoc, node);
 352 mdoc_free(mdoc);
 353 .Ed
 354 .Pp
 355 Please see
 356 .Pa main.c
 357 in the source archive for a rigorous reference.
 358 .Sh SEE ALSO
 359 .Xr mandoc 1 ,
 360 .Xr mdoc 7
 361 .Sh AUTHORS
 362 The
 363 .Nm
 364 library was written by
 365 .An Kristaps Dzonsons Aq kristaps@bsd.lv .