mdoc.3

   1 .\" $Id: mdoc.3,v 1.20 2009/03/20 15:14:01 kristaps Exp $
   2 .\"
   3 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
   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 20 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 .Nm mdoc_reset
  31 .Nd mdoc macro compiler library
  32 .\" SECTION
  33 .Sh SYNOPSIS
  34 .Fd #include <mdoc.h>
  35 .Vt extern const char * const * mdoc_macronames;
  36 .Vt extern const char * const * mdoc_argnames;
  37 .Ft "struct mdoc *"
  38 .Fn mdoc_alloc "void *data" "int pflags" "const struct mdoc_cb *cb"
  39 .Ft void
  40 .Fn mdoc_reset "struct mdoc *mdoc"
  41 .Ft void
  42 .Fn mdoc_free "struct mdoc *mdoc"
  43 .Ft int
  44 .Fn mdoc_parseln "struct mdoc *mdoc" "int line" "char *buf"
  45 .Ft "const struct mdoc_node *"
  46 .Fn mdoc_node "struct mdoc *mdoc"
  47 .Ft "const struct mdoc_meta *"
  48 .Fn mdoc_meta "struct mdoc *mdoc"
  49 .Ft int
  50 .Fn mdoc_endparse "struct mdoc *mdoc"
  51 .\" SECTION
  52 .Sh DESCRIPTION
  53 The
  54 .Nm mdoc
  55 library parses lines of
  56 .Xr mdoc 7
  57 input (and
  58 .Em only
  59 mdoc) into an abstract syntax tree that generalises the semantic
  60 annotation of its input.  Common front-ends for
  61 .Nm
  62 are
  63 .Xr mdocterm 1 ,
  64 .Xr mdoclint 1
  65 and
  66 .Xr mdoctree 1 .
  67 .\" PARAGRAPH
  68 .Pp
  69 In general, applications initiate a parsing sequence with
  70 .Fn mdoc_alloc ,
  71 parse each line in a document with
  72 .Fn mdoc_parseln ,
  73 close the parsing session with
  74 .Fn mdoc_endparse ,
  75 operate over the syntax tree returned by
  76 .Fn mdoc_node
  77 and
  78 .Fn mdoc_meta ,
  79 then free all allocated memory with
  80 .Fn mdoc_free .
  81 The
  82 .Fn mdoc_reset
  83 function may be used in order to reset the parser for another input
  84 sequence.  See the
  85 .Sx EXAMPLES
  86 section for a full example.
  87 .\" PARAGRAPH
  88 .Pp
  89 This section further defines the
  90 .Sx Types ,
  91 .Sx Functions
  92 and
  93 .Sx Variables
  94 available to programmers.  Following that, the
  95 .Sx Abstract Syntax Tree
  96 section documents the output tree.
  97 .\" SUBSECTION
  98 .Ss Types
  99 Both functions (see
 100 .Sx Functions )
 101 and variables (see
 102 .Sx Variables )
 103 may use the following types:
 104 .Bl -ohang -offset "XXXX"
 105 .\" LIST-ITEM
 106 .It Vt struct mdoc
 107 An opaque type defined in
 108 .Pa mdoc.c .
 109 Its values are only used privately within the library.
 110 .\" LIST-ITEM
 111 .It Vt struct mdoc_cb
 112 A set of message callbacks defined in
 113 .Pa mdoc.h .
 114 .\" LIST-ITEM
 115 .It Vt struct mdoc_node
 116 A parsed node.  Defined in
 117 .Pa mdoc.h .
 118 See
 119 .Sx Abstract Syntax Tree
 120 for details.
 121 .El
 122 .\" SUBSECTION
 123 .Ss Functions
 124 Function descriptions follow:
 125 .Bl -ohang -offset "XXXX"
 126 .\" LIST-ITEM
 127 .It Fn mdoc_alloc
 128 Allocates a parsing structure.  The
 129 .Fa data
 130 pointer is passed to callbacks in
 131 .Fa cb ,
 132 which are documented further in the header file.
 133 The
 134 .Fa pflags
 135 arguments are defined in
 136 .Pa mdoc.h .
 137 Returns NULL on failure.  If non-NULL, the pointer must be freed with
 138 .Fn mdoc_free .
 139 .\" LIST-ITEM
 140 .It Fn mdoc_reset
 141 Reset the parser for another parse routine.  After its use,
 142 .Fn mdoc_parseln
 143 behaves as if invoked for the first time.
 144 .\" LIST-ITEM
 145 .It Fn mdoc_free
 146 Free all resources of a parser.  The pointer is no longer valid after
 147 invocation.
 148 .\" LIST-ITEM
 149 .It Fn mdoc_parseln
 150 Parse a nil-terminated line of input.  This line should not contain the
 151 trailing newline.  Returns 0 on failure, 1 on success.  The input buffer
 152 .Fa buf
 153 is modified by this function.
 154 .\" LIST-ITEM
 155 .It Fn mdoc_endparse
 156 Signals that the parse is complete.  Note that if
 157 .Fn mdoc_endparse
 158 is called subsequent to
 159 .Fn mdoc_node ,
 160 the resulting tree is incomplete.  Returns 0 on failure, 1 on success.
 161 .\" LIST-ITEM
 162 .It Fn mdoc_node
 163 Returns the first node of the parse.  Note that if
 164 .Fn mdoc_parseln
 165 or
 166 .Fn mdoc_endparse
 167 return 0, the tree will be incomplete.
 168 .It Fn mdoc_meta
 169 Returns the document's parsed meta-data.  If this information has not
 170 yet been supplied or
 171 .Fn mdoc_parseln
 172 or
 173 .Fn mdoc_endparse
 174 return 0, the data will be incomplete.
 175 .El
 176 .\" SUBSECTION
 177 .Ss Variables
 178 The following variables are also defined:
 179 .Bl -ohang -offset "XXXX"
 180 .\" LIST-ITEM
 181 .It Va mdoc_macronames
 182 An array of string-ified token names.
 183 .\" LIST-ITEM
 184 .It Va mdoc_argnames
 185 An array of string-ified token argument names.
 186 .El
 187 .\" SUBSECTION
 188 .Ss Abstract Syntax Tree
 189 The
 190 .Nm
 191 functions produce an abstract syntax tree (AST) describing input in a
 192 regular form.  It may be reviewed at any time with
 193 .Fn mdoc_nodes ;
 194 however, if called before
 195 .Fn mdoc_endparse ,
 196 or after
 197 .Fn mdoc_endparse
 198 or
 199 .Fn mdoc_parseln
 200 fail, it may be incomplete.
 201 .\" PARAGRAPH
 202 .Pp
 203 This AST is governed by the ontological
 204 rules dictated in
 205 .Xr mdoc 7
 206 and derives its terminology accordingly.
 207 .Qq In-line
 208 elements described in
 209 .Xr mdoc 7
 210 are described simply as
 211 .Qq elements .
 212 .\" PARAGRAPH
 213 .Pp
 214 The AST is composed of
 215 .Vt struct mdoc_node
 216 nodes with block, head, body, element, root and text types as declared
 217 by the
 218 .Va type
 219 field.  Each node also provides its parse point (the
 220 .Va line ,
 221 .Va sec ,
 222 and
 223 .Va pos
 224 fields), its position in the tree (the
 225 .Va parent ,
 226 .Va child ,
 227 .Va next
 228 and
 229 .Va prev
 230 fields) and type-specific data (the
 231 .Va data
 232 field).
 233 .\" PARAGRAPH
 234 .Pp
 235 The tree itself is arranged according to the following normal form,
 236 where capitalised non-terminals represent nodes.
 237 .Pp
 238 .Bl -tag -width "ELEMENTXX" -compact -offset "XXXX"
 239 .\" LIST-ITEM
 240 .It ROOT
 241 \(<- mnode+
 242 .It mnode
 243 \(<- BLOCK | ELEMENT | TEXT
 244 .It BLOCK
 245 \(<- (HEAD [TEXT])+ [BODY [TEXT]] [TAIL [TEXT]]
 246 .It BLOCK
 247 \(<- BODY [TEXT] [TAIL [TEXT]]
 248 .It ELEMENT
 249 \(<- TEXT*
 250 .It HEAD
 251 \(<- mnode+
 252 .It BODY
 253 \(<- mnode+
 254 .It TAIL
 255 \(<- mnode+
 256 .It TEXT
 257 \(<- [[:alpha:]]*
 258 .El
 259 .\" PARAGRAPH
 260 .Pp
 261 Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of
 262 the BLOCK production.  These refer to punctuation marks.  Furthermore,
 263 although a TEXT node will generally have a non-zero-length string, in
 264 the specific case of
 265 .Sq \&.Bd \-literal ,
 266 an empty line will produce a zero-length string.
 267 .\" SECTION
 268 .Sh EXAMPLES
 269 The following example reads lines from stdin and parses them, operating
 270 on the finished parse tree with
 271 .Fn parsed .
 272 Note that, if the last line of the file isn't newline-terminated, this
 273 will truncate the file's last character (see
 274 .Xr fgetln 3 ) .
 275 Further, this example does not error-check nor free memory upon failure.
 276 .Bd -literal -offset "XXXX"
 277 struct mdoc *mdoc;
 278 struct mdoc_node *node;
 279 char *buf;
 280 size_t len;
 281 int line;
 282
 283 line = 1;
 284 mdoc = mdoc_alloc(NULL, NULL);
 285
 286 while ((buf = fgetln(fp, &len))) {
 287         buf[len - 1] = '\\0';
 288         if ( ! mdoc_parseln(mdoc, line, buf))
 289                 errx(1, "mdoc_parseln");
 290         line++;
 291 }
 292
 293 if ( ! mdoc_endparse(mdoc))
 294         errx(1, "mdoc_endparse");
 295 if (NULL == (node = mdoc_node(mdoc)))
 296         errx(1, "mdoc_node");
 297
 298 parsed(mdoc, node);
 299 mdoc_free(mdoc);
 300 .Ed
 301 .\" SECTION
 302 .Sh SEE ALSO
 303 .Xr mandoc 1 ,
 304 .Xr mdoc 7
 305 .\" SECTION
 306 .Sh AUTHORS
 307 The
 308 .Nm
 309 utility was written by
 310 .An Kristaps Dzonsons Aq kristaps@openbsd.org .
 311 .\" SECTION
 312 .Sh CAVEATS
 313 .Bl -dash -compact
 314 .\" LIST-ITEM
 315 .It
 316 The
 317 .Sq \&Xc
 318 and
 319 .Sq \&Xo
 320 macros aren't handled when used to span lines for the
 321 .Sq \&It
 322 macro.
 323 .\" LIST-ITEM
 324 .It
 325 The
 326 .Sq \&Bsx
 327 macro doesn't yet understand version arguments.
 328 .El