mdoc.3

   1 .\" $Id: mdoc.3,v 1.11 2009/02/25 17:02:47 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: February 25 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 escaped with an escape character
 188 .Sq \\
 189 and followed by either an open-parenthesis
 190 .Sq \&(
 191 for two-character sequences; an open-bracket
 192 .Sq \&[
 193 for n-character sequences (terminated at a close-bracket
 194 .Sq \&] ) ;
 195 or one of a small set of single characters for other escapes.
 196 .\" SUBSECTION
 197 .Ss Abstract Syntax Tree
 198 The
 199 .Nm
 200 functions produce an abstract syntax tree (AST) describing the input
 201 lines in a regular form.  It may be reviewed at any time with
 202 .Fn mdoc_nodes ;
 203 however, if called before
 204 .Fn mdoc_endparse ,
 205 or after
 206 .Fn mdoc_endparse
 207 or
 208 .Fn mdoc_parseln
 209 fail, it may be incomplete.
 210 .\" PARAGRAPH
 211 .Pp
 212 The AST is composed of
 213 .Vt struct mdoc_node
 214 nodes with block, head, body, element, root and text types as declared
 215 by the
 216 .Va type
 217 field.  Each node also provides its parse point (the
 218 .Va line ,
 219 .Va sec ,
 220 and
 221 .Va pos
 222 fields), its position in the tree (the
 223 .Va parent ,
 224 .Va child ,
 225 .Va next
 226 and
 227 .Va prev
 228 fields) and type-specific data (the
 229 .Va data
 230 field).
 231 .\" PARAGRAPH
 232 .Pp
 233 The tree itself is arranged according to the following normal form,
 234 where capitalised non-terminals represent nodes.
 235 .Pp
 236 .Bl -tag -width "ELEMENTXX" -compact -offset "XXXX"
 237 .\" LIST-ITEM
 238 .It ROOT
 239 \(<- mnode+
 240 .It mnode
 241 \(<- BLOCK | ELEMENT | TEXT
 242 .It BLOCK
 243 \(<- (HEAD [TEXT])+ [BODY [TEXT]] [TAIL [TEXT]]
 244 .It BLOCK
 245 \(<- BODY [TEXT] [TAIL [TEXT]]
 246 .It ELEMENT
 247 \(<- TEXT*
 248 .It HEAD
 249 \(<- mnode+
 250 .It BODY
 251 \(<- mnode+
 252 .It TAIL
 253 \(<- mnode+
 254 .It TEXT
 255 \(<- [[:alpha:]]*
 256 .El
 257 .\" PARAGRAPH
 258 .Pp
 259 Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of
 260 the BLOCK production.  These refer to punctuation marks.  Furthermore,
 261 although a TEXT node will generally have a non-zero-length string, in
 262 the specific case of
 263 .Sq \&.Bd \-literal ,
 264 an empty line will produce a zero-length string.
 265 .\" PARAGRAPH
 266 .Pp
 267 The rule-of-thumb for mapping node types to macros follows. In-line
 268 elements, such as
 269 .Sq \&.Em foo ,
 270 are classified as ELEMENT nodes, which can only contain text.
 271 Multi-line elements, such as
 272 .Sq \&.Sh ,
 273 are BLOCK elements, where the HEAD constitutes line contents and the
 274 BODY constitutes subsequent lines.  In-line elements with matching
 275 pairs, such as
 276 .Sq \&.So
 277 and
 278 .Sq \&.Sc ,
 279 are BLOCK elements with no HEAD tag.  The only exception to this is
 280 .Sq \&.Eo
 281 and
 282 .Sq \&.Ec ,
 283 which has a HEAD and TAIL node corresponding to the enclosure string.
 284 TEXT nodes, obviously, constitute text, and the ROOT node is the
 285 document's root.
 286 .\" SECTION
 287 .Sh EXAMPLES
 288 The following example reads lines from stdin and parses them, operating
 289 on the finished parse tree with
 290 .Fn parsed .
 291 Note that, if the last line of the file isn't newline-terminated, this
 292 will truncate the file's last character (see
 293 .Xr fgetln 3 ) .
 294 Further, this example does not error-check nor free memory upon failure.
 295 .Bd -literal -offset "XXXX"
 296 struct mdoc *mdoc;
 297 struct mdoc_node *node;
 298 char *buf;
 299 size_t len;
 300 int line;
 301
 302 line = 1;
 303 mdoc = mdoc_alloc(NULL, NULL);
 304
 305 while ((buf = fgetln(fp, &len))) {
 306         buf[len - 1] = '\\0';
 307         if ( ! mdoc_parseln(mdoc, line, buf))
 308                 errx(1, "mdoc_parseln");
 309         line++;
 310 }
 311
 312 if ( ! mdoc_endparse(mdoc))
 313         errx(1, "mdoc_endparse");
 314 if (NULL == (node = mdoc_node(mdoc)))
 315         errx(1, "mdoc_node");
 316
 317 parsed(mdoc, node);
 318 mdoc_free(mdoc);
 319 .Ed
 320 .\" SECTION
 321 .Sh SEE ALSO
 322 .Xr mdoc 7 ,
 323 .Xr mdoc.samples 7 ,
 324 .Xr groff 1 ,
 325 .Xr mdocml 1
 326 .\" SECTION
 327 .Sh AUTHORS
 328 The
 329 .Nm
 330 utility was written by
 331 .An Kristaps Dzonsons Aq kristaps@kth.se .
 332 .\" SECTION
 333 .Sh BUGS
 334 Bugs, un-implemented macros and incompabilities are documented in this
 335 section.  The baseline for determining whether macro parsing is
 336 .Qq incompatible
 337 is the default
 338 .Xr groff 1
 339 system bundled with
 340 .Ox .
 341 .\" PARAGRAPH
 342 .Pp
 343 Un-implemented: the
 344 .Sq \&Xc
 345 and
 346 .Sq \&Xo
 347 macros aren't handled when used to span lines for the
 348 .Sq \&It
 349 macro.  Such usage is specifically discouraged in
 350 .Xr mdoc.samples 7 .
 351 .\" PARAGRAPH
 352 .Pp
 353 Bugs: when
 354 .Sq \&It \-column
 355 is invoked, whitespace is not stripped around
 356 .Sq \&Ta
 357 or tab-character separators.
 358 .\" PARAGRAPH
 359 .Pp
 360 Bugs: elements within columns for
 361 .Sq \&It \-column
 362 are not yet supported.
 363 .\" PARAGRAPH
 364 .Pp
 365 Incompatible: the
 366 .Sq \&At
 367 macro only accepts a single parameter.  Furthermore, several macros
 368 .Pf ( Sq \&Pp ,
 369 .Sq \&It ,
 370 and possibly others) accept multiple arguments with a warning.
 371 .\" PARAGRAPH
 372 .Pp
 373 Incompatible: only those macros specified by
 374 .Xr mdoc.samples 7
 375 and
 376 .Xr mdoc 7
 377 for
 378 .Ox
 379 are supported; support for
 380 .Nx
 381 and other
 382 .Bx
 383 systems is in progress.