mdoc.3

   1 .\" $Id: mdoc.3,v 1.14 2009/03/12 15:55:11 kristaps Exp $
   2 .\"
   3 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
   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
   7 .\" above copyright notice and this permission notice appear in all
   8 .\" copies.
   9 .\"
  10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
  11 .\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
  12 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
  13 .\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
  14 .\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
  15 .\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
  16 .\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  17 .\" PERFORMANCE OF THIS SOFTWARE.
  18 .\"
  19 .Dd $Mdocdate: March 12 2009 $
  20 .Dt mdoc 3
  21 .Os
  22 .\" SECTION
  23 .Sh NAME
  24 .Nm mdoc_alloc ,
  25 .Nm mdoc_parseln ,
  26 .Nm mdoc_endparse ,
  27 .Nm mdoc_node ,
  28 .Nm mdoc_meta ,
  29 .Nm mdoc_free
  30 .Nd mdoc macro compiler library
  31 .\" SECTION
  32 .Sh SYNOPSIS
  33 .Fd #include <mdoc.h>
  34 .Vt extern const char * const * mdoc_macronames;
  35 .Vt extern const char * const * mdoc_argnames;
  36 .Ft "struct mdoc *"
  37 .Fn mdoc_alloc "void *data" "const struct mdoc_cb *cb"
  38 .Ft void
  39 .Fn mdoc_free "struct mdoc *mdoc"
  40 .Ft int
  41 .Fn mdoc_parseln "struct mdoc *mdoc" "int line" "char *buf"
  42 .Ft "const struct mdoc_node *"
  43 .Fn mdoc_node "struct mdoc *mdoc"
  44 .Ft "const struct mdoc_meta *"
  45 .Fn mdoc_meta "struct mdoc *mdoc"
  46 .Ft int
  47 .Fn mdoc_endparse "struct mdoc *mdoc"
  48 .\" SECTION
  49 .Sh DESCRIPTION
  50 The
  51 .Nm mdoc
  52 library parses lines of mdoc input into an abstract syntax tree.
  53 .Dq mdoc ,
  54 which is used to format BSD manual pages, is a macro package of the
  55 .Dq roff
  56 language.  The
  57 .Nm
  58 library implements only those macros documented in the
  59 .Xr mdoc 7
  60 and
  61 .Xr mdoc.samples 7
  62 manuals.  Documents with
  63 .Xr refer 1 ,
  64 .Xr eqn 1
  65 and other pre-processor sections aren't accomodated.
  66 .\" PARAGRAPH
  67 .Pp
  68 .Nm
  69 is
  70 .Ud
  71 .\" PARAGRAPH
  72 .Pp
  73 In general, applications initiate a parsing sequence with
  74 .Fn mdoc_alloc ,
  75 parse each line in a document with
  76 .Fn mdoc_parseln ,
  77 close the parsing session with
  78 .Fn mdoc_endparse ,
  79 operate over the syntax tree returned by
  80 .Fn mdoc_node
  81 and
  82 .Fn mdoc_meta ,
  83 then free all allocated memory with
  84 .Fn mdoc_free .
  85 See the
  86 .Sx EXAMPLES
  87 section for a full example.
  88 .\" PARAGRAPH
  89 .Pp
  90 This section further defines the
  91 .Sx Types ,
  92 .Sx Functions
  93 and
  94 .Sx Variables
  95 available to programmers.  Following that,
  96 .Sx Character Encoding
  97 describes input format.  Lastly,
  98 .Sx Abstract Syntax Tree ,
  99 documents the output tree.
 100 .\" SUBSECTION
 101 .Ss Types
 102 Both functions (see
 103 .Sx Functions )
 104 and variables (see
 105 .Sx Variables )
 106 may use the following types:
 107 .Bl -ohang -offset "XXXX"
 108 .\" LIST-ITEM
 109 .It Vt struct mdoc
 110 An opaque type defined in
 111 .Pa mdoc.c .
 112 Its values are only used privately within the library.
 113 .\" LIST-ITEM
 114 .It Vt struct mdoc_cb
 115 A set of message callbacks defined in
 116 .Pa mdoc.h .
 117 .\" LIST-ITEM
 118 .It Vt struct mdoc_node
 119 A parsed node.  Defined in
 120 .Pa mdoc.h .
 121 See
 122 .Sx Abstract Syntax Tree
 123 for details.
 124 .El
 125 .\" SUBSECTION
 126 .Ss Functions
 127 Function descriptions follow:
 128 .Bl -ohang -offset "XXXX"
 129 .\" LIST-ITEM
 130 .It Fn mdoc_alloc
 131 Allocates a parsing structure.  The
 132 .Fa data
 133 pointer is passed to callbacks in
 134 .Fa cb ,
 135 which are documented further in the header file.  Returns NULL on
 136 failure.  If non-NULL, the pointer must be freed with
 137 .Fn mdoc_free .
 138 .\" LIST-ITEM
 139 .It Fn mdoc_free
 140 Free all resources of a parser.  The pointer is no longer valid after
 141 invocation.
 142 .\" LIST-ITEM
 143 .It Fn mdoc_parseln
 144 Parse a nil-terminated line of input.  This line should not contain the
 145 trailing newline.  Returns 0 on failure, 1 on success.  The input buffer
 146 .Fa buf
 147 is modified by this function.
 148 .\" LIST-ITEM
 149 .It Fn mdoc_endparse
 150 Signals that the parse is complete.  Note that if
 151 .Fn mdoc_endparse
 152 is called subsequent to
 153 .Fn mdoc_node ,
 154 the resulting tree is incomplete.  Returns 0 on failure, 1 on success.
 155 .\" LIST-ITEM
 156 .It Fn mdoc_node
 157 Returns the first node of the parse.  Note that if
 158 .Fn mdoc_parseln
 159 or
 160 .Fn mdoc_endparse
 161 return 0, the tree will be incomplete.
 162 .It Fn mdoc_meta
 163 Returns the document's parsed meta-data.  If this information has not
 164 yet been supplied or
 165 .Fn mdoc_parseln
 166 or
 167 .Fn mdoc_endparse
 168 return 0, the data will be incomplete.
 169 .El
 170 .\" SUBSECTION
 171 .Ss Variables
 172 The following variables are also defined:
 173 .Bl -ohang -offset "XXXX"
 174 .\" LIST-ITEM
 175 .It Va mdoc_macronames
 176 An array of string-ified token names.
 177 .\" LIST-ITEM
 178 .It Va mdoc_argnames
 179 An array of string-ified token argument names.
 180 .El
 181 .\" SUBSECTION
 182 .Ss Character Encoding
 183 The
 184 .Xr mdoc 3
 185 library accepts only printable ASCII characters as defined by
 186 .Xr isprint 3 .
 187 Non-ASCII character sequences are delimited in various ways.  All are
 188 preceeded by an escape character
 189 .Sq \\
 190 and followed by either an open-parenthesis
 191 .Sq \&(
 192 for two-character sequences; an open-bracket
 193 .Sq \&[
 194 for n-character sequences (terminated at a close-bracket
 195 .Sq \&] ) ;
 196 an asterisk and open-parenthesis
 197 .Sq \&*(
 198 for two-character sequences;
 199 an asterisk and non-open-parenthesis
 200 .Sq \&*
 201 for single-character sequences; or one of a small set of standalone
 202 single characters for other escapes.
 203 .\" PARAGRAPH
 204 .Pp
 205 Examples:
 206 .Pp
 207 .Bl -tag -width "XXXXXXXX" -offset "XXXX" -compact
 208 .\" LIST-ITEM
 209 .It \\*(<=
 210 prints
 211 .Dq \*(<=
 212 .Pq greater-equal
 213 .\" LIST-ITEM
 214 .It \\(<-
 215 prints
 216 .Dq \(<-
 217 .Pq left-arrow
 218 .\" LIST-ITEM
 219 .It \\[<-]
 220 also prints
 221 .Dq \(<-
 222 .Pq left-arrow
 223 .\" LIST-ITEM
 224 .It \\*(Ba
 225 prints
 226 .Dq \*(Ba
 227 .Pq bar
 228 .\" LIST-ITEM
 229 .It \\*q
 230 prints
 231 .Dq \*q
 232 .Pq double-quote
 233 .El
 234 .\" PARAGRAPH
 235 .Pp
 236 All escaped sequences are syntax-checked, but it's up to the front-end
 237 system to correctly render them to the output device.
 238 .\" SUBSECTION
 239 .Ss Abstract Syntax Tree
 240 The
 241 .Nm
 242 functions produce an abstract syntax tree (AST) describing the input
 243 lines in a regular form.  It may be reviewed at any time with
 244 .Fn mdoc_nodes ;
 245 however, if called before
 246 .Fn mdoc_endparse ,
 247 or after
 248 .Fn mdoc_endparse
 249 or
 250 .Fn mdoc_parseln
 251 fail, it may be incomplete.
 252 .\" PARAGRAPH
 253 .Pp
 254 The AST is composed of
 255 .Vt struct mdoc_node
 256 nodes with block, head, body, element, root and text types as declared
 257 by the
 258 .Va type
 259 field.  Each node also provides its parse point (the
 260 .Va line ,
 261 .Va sec ,
 262 and
 263 .Va pos
 264 fields), its position in the tree (the
 265 .Va parent ,
 266 .Va child ,
 267 .Va next
 268 and
 269 .Va prev
 270 fields) and type-specific data (the
 271 .Va data
 272 field).
 273 .\" PARAGRAPH
 274 .Pp
 275 The tree itself is arranged according to the following normal form,
 276 where capitalised non-terminals represent nodes.
 277 .Pp
 278 .Bl -tag -width "ELEMENTXX" -compact -offset "XXXX"
 279 .\" LIST-ITEM
 280 .It ROOT
 281 \(<- mnode+
 282 .It mnode
 283 \(<- BLOCK | ELEMENT | TEXT
 284 .It BLOCK
 285 \(<- (HEAD [TEXT])+ [BODY [TEXT]] [TAIL [TEXT]]
 286 .It BLOCK
 287 \(<- BODY [TEXT] [TAIL [TEXT]]
 288 .It ELEMENT
 289 \(<- TEXT*
 290 .It HEAD
 291 \(<- mnode+
 292 .It BODY
 293 \(<- mnode+
 294 .It TAIL
 295 \(<- mnode+
 296 .It TEXT
 297 \(<- [[:alpha:]]*
 298 .El
 299 .\" PARAGRAPH
 300 .Pp
 301 Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of
 302 the BLOCK production.  These refer to punctuation marks.  Furthermore,
 303 although a TEXT node will generally have a non-zero-length string, in
 304 the specific case of
 305 .Sq \&.Bd \-literal ,
 306 an empty line will produce a zero-length string.
 307 .\" PARAGRAPH
 308 .Pp
 309 The rule-of-thumb for mapping node types to macros follows. In-line
 310 elements, such as
 311 .Sq \&.Em foo ,
 312 are classified as ELEMENT nodes, which can only contain text.
 313 Multi-line elements, such as
 314 .Sq \&.Sh ,
 315 are BLOCK elements, where the HEAD constitutes line contents and the
 316 BODY constitutes subsequent lines.  In-line elements with matching
 317 pairs, such as
 318 .Sq \&.So
 319 and
 320 .Sq \&.Sc ,
 321 are BLOCK elements with no HEAD tag.  The only exception to this is
 322 .Sq \&.Eo
 323 and
 324 .Sq \&.Ec ,
 325 which has a HEAD and TAIL node corresponding to the enclosure string.
 326 TEXT nodes, obviously, constitute text, and the ROOT node is the
 327 document's root.
 328 .\" SECTION
 329 .Sh EXAMPLES
 330 The following example reads lines from stdin and parses them, operating
 331 on the finished parse tree with
 332 .Fn parsed .
 333 Note that, if the last line of the file isn't newline-terminated, this
 334 will truncate the file's last character (see
 335 .Xr fgetln 3 ) .
 336 Further, this example does not error-check nor free memory upon failure.
 337 .Bd -literal -offset "XXXX"
 338 struct mdoc *mdoc;
 339 struct mdoc_node *node;
 340 char *buf;
 341 size_t len;
 342 int line;
 343
 344 line = 1;
 345 mdoc = mdoc_alloc(NULL, NULL);
 346
 347 while ((buf = fgetln(fp, &len))) {
 348         buf[len - 1] = '\\0';
 349         if ( ! mdoc_parseln(mdoc, line, buf))
 350                 errx(1, "mdoc_parseln");
 351         line++;
 352 }
 353
 354 if ( ! mdoc_endparse(mdoc))
 355         errx(1, "mdoc_endparse");
 356 if (NULL == (node = mdoc_node(mdoc)))
 357         errx(1, "mdoc_node");
 358
 359 parsed(mdoc, node);
 360 mdoc_free(mdoc);
 361 .Ed
 362 .\" SECTION
 363 .Sh COMPATIBILITY
 364 In general, only those macros specified by
 365 .Xr mdoc.samples 7
 366 and
 367 .Xr mdoc 7
 368 for
 369 .Ox
 370 and
 371 .Nx
 372 are supported; support for other
 373 .Bx
 374 systems is in progress.
 375 .Bl -bullet
 376 .\" LIST-ITEM
 377 .It
 378 NetBSD
 379 .Sq \&It \-nested
 380 is assumed for all lists: any list may be nested and
 381 .Sq \-enum
 382 lists will restart the sequence only for the sub-list.
 383 .\" LIST-ITEM
 384 .It
 385 Newer NetBSD-style
 386 .Sq \&It \-column
 387 syntax, where column widths may be preceeded by other arguments (instead
 388 of proceeded), is not supported.
 389 .\" LIST-ITEM
 390 .It
 391 The
 392 .Sq \&At
 393 macro only accepts a single parameter.
 394 .El
 395 .\" SECTION
 396 .Sh SEE ALSO
 397 .Xr mdoc 7 ,
 398 .Xr mdoc.samples 7 ,
 399 .Xr groff 1 ,
 400 .Xr mdocml 1
 401 .\" SECTION
 402 .Sh AUTHORS
 403 The
 404 .Nm
 405 utility was written by
 406 .An Kristaps Dzonsons Aq kristaps@kth.se .
 407 .\" SECTION
 408 .Sh CAVEATS
 409 .Bl -bullet
 410 .\" LIST-ITEM
 411 .It
 412 The
 413 .Sq \&Xc
 414 and
 415 .Sq \&Xo
 416 macros aren't handled when used to span lines for the
 417 .Sq \&It
 418 macro.  Such usage is specifically discouraged in
 419 .Xr mdoc.samples 7 .
 420 .El