mdoc.3

   1 .\" $Id: mdoc.3,v 1.27 2009/04/12 19:19:57 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: April 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 .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 int
  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 (AST).
  60 .\" PARAGRAPH
  61 .Pp
  62 In general, applications initiate a parsing sequence with
  63 .Fn mdoc_alloc ,
  64 parse each line in a document with
  65 .Fn mdoc_parseln ,
  66 close the parsing session with
  67 .Fn mdoc_endparse ,
  68 operate over the syntax tree returned by
  69 .Fn mdoc_node
  70 and
  71 .Fn mdoc_meta ,
  72 then free all allocated memory with
  73 .Fn mdoc_free .
  74 The
  75 .Fn mdoc_reset
  76 function may be used in order to reset the parser for another input
  77 sequence.  See the
  78 .Sx EXAMPLES
  79 section for a full example.
  80 .\" PARAGRAPH
  81 .Pp
  82 This section further defines the
  83 .Sx Types ,
  84 .Sx Functions
  85 and
  86 .Sx Variables
  87 available to programmers.  Following that, the
  88 .Sx Abstract Syntax Tree
  89 section documents the output tree.
  90 .\" SUBSECTION
  91 .Ss Types
  92 Both functions (see
  93 .Sx Functions )
  94 and variables (see
  95 .Sx Variables )
  96 may use the following types:
  97 .Bl -ohang -offset "XXXX"
  98 .\" LIST-ITEM
  99 .It Vt struct mdoc
 100 An opaque type defined in
 101 .Pa mdoc.c .
 102 Its values are only used privately within the library.
 103 .\" LIST-ITEM
 104 .It Vt struct mdoc_cb
 105 A set of message callbacks defined in
 106 .Pa mdoc.h .
 107 .\" LIST-ITEM
 108 .It Vt struct mdoc_node
 109 A parsed node.  Defined in
 110 .Pa mdoc.h .
 111 See
 112 .Sx Abstract Syntax Tree
 113 for details.
 114 .El
 115 .\" SUBSECTION
 116 .Ss Functions
 117 Function descriptions follow:
 118 .Bl -ohang -offset "XXXX"
 119 .\" LIST-ITEM
 120 .It Fn mdoc_alloc
 121 Allocates a parsing structure.  The
 122 .Fa data
 123 pointer is passed to callbacks in
 124 .Fa cb ,
 125 which are documented further in the header file.
 126 The
 127 .Fa pflags
 128 arguments are defined in
 129 .Pa mdoc.h .
 130 Returns NULL on failure.  If non-NULL, the pointer must be freed with
 131 .Fn mdoc_free .
 132 .\" LIST-ITEM
 133 .It Fn mdoc_reset
 134 Reset the parser for another parse routine.  After its use,
 135 .Fn mdoc_parseln
 136 behaves as if invoked for the first time.  If it returns 0, memory could
 137 not be allocated.
 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 Abstract Syntax Tree
 183 The
 184 .Nm
 185 functions produce an abstract syntax tree (AST) describing input in a
 186 regular form.  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 .\" PARAGRAPH
 196 .Pp
 197 This AST is governed by the ontological
 198 rules dictated in
 199 .Xr mdoc 7
 200 and derives its terminology accordingly.
 201 .Qq In-line
 202 elements described in
 203 .Xr mdoc 7
 204 are described simply as
 205 .Qq elements .
 206 .\" PARAGRAPH
 207 .Pp
 208 The AST is composed of
 209 .Vt struct mdoc_node
 210 nodes with block, head, body, element, root and text types as declared
 211 by the
 212 .Va type
 213 field.  Each node also provides its parse point (the
 214 .Va line ,
 215 .Va sec ,
 216 and
 217 .Va pos
 218 fields), its position in the tree (the
 219 .Va parent ,
 220 .Va child ,
 221 .Va next
 222 and
 223 .Va prev
 224 fields) and some type-specific data.
 225 .\" PARAGRAPH
 226 .Pp
 227 The tree itself is arranged according to the following normal form,
 228 where capitalised non-terminals represent nodes.
 229 .Pp
 230 .Bl -tag -width "ELEMENTXX" -compact -offset "XXXX"
 231 .\" LIST-ITEM
 232 .It ROOT
 233 \(<- mnode+
 234 .It mnode
 235 \(<- BLOCK | ELEMENT | TEXT
 236 .It BLOCK
 237 \(<- (HEAD [TEXT])+ [BODY [TEXT]] [TAIL [TEXT]]
 238 .It BLOCK
 239 \(<- BODY [TEXT] [TAIL [TEXT]]
 240 .It ELEMENT
 241 \(<- TEXT*
 242 .It HEAD
 243 \(<- mnode+
 244 .It BODY
 245 \(<- mnode+
 246 .It TAIL
 247 \(<- mnode+
 248 .It TEXT
 249 \(<- [[:alpha:]]*
 250 .El
 251 .\" PARAGRAPH
 252 .Pp
 253 Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of
 254 the BLOCK production.  These refer to punctuation marks.  Furthermore,
 255 although a TEXT node will generally have a non-zero-length string, in
 256 the specific case of
 257 .Sq \&.Bd \-literal ,
 258 an empty line will produce a zero-length string.
 259 .\" SECTION
 260 .Sh EXAMPLES
 261 The following example reads lines from stdin and parses them, operating
 262 on the finished parse tree with
 263 .Fn parsed .
 264 Note that, if the last line of the file isn't newline-terminated, this
 265 will truncate the file's last character (see
 266 .Xr fgetln 3 ) .
 267 Further, this example does not error-check nor free memory upon failure.
 268 .Bd -literal -offset "XXXX"
 269 struct mdoc *mdoc;
 270 struct mdoc_node *node;
 271 char *buf;
 272 size_t len;
 273 int line;
 274
 275 line = 1;
 276 mdoc = mdoc_alloc(NULL, 0, NULL);
 277
 278 while ((buf = fgetln(fp, &len))) {
 279         buf[len - 1] = '\\0';
 280         if ( ! mdoc_parseln(mdoc, line, buf))
 281                 errx(1, "mdoc_parseln");
 282         line++;
 283 }
 284
 285 if ( ! mdoc_endparse(mdoc))
 286         errx(1, "mdoc_endparse");
 287 if (NULL == (node = mdoc_node(mdoc)))
 288         errx(1, "mdoc_node");
 289
 290 parsed(mdoc, node);
 291 mdoc_free(mdoc);
 292 .Ed
 293 .\" SECTION
 294 .Sh SEE ALSO
 295 .Xr mandoc 1 ,
 296 .Xr mdoc 7
 297 .\" SECTION
 298 .Sh AUTHORS
 299 The
 300 .Nm
 301 utility was written by
 302 .An Kristaps Dzonsons Aq kristaps@openbsd.org .
 303 .\" SECTION
 304 .Sh CAVEATS
 305 .Bl -dash -compact
 306 .\" LIST-ITEM
 307 .It
 308 The
 309 .Sq \&.Xc
 310 and
 311 .Sq \&.Xo
 312 macros aren't handled when used to span lines for the
 313 .Sq \&.It
 314 macro.
 315 .\" LIST-ITEM
 316 .It
 317 The
 318 .Sq \&.Bsx
 319 macro family doesn't yet understand version arguments.
 320 .\" LIST-ITEM
 321 .It
 322 If not given a value, the \-offset argument to
 323 .Sq \&.Bd
 324 and
 325 .Sq \&.Bl
 326 should be the width of
 327 .Qq <string> ;
 328 instead, a value of
 329 .Li 10n
 330 is provided.
 331 .\" LIST-ITEM
 332 .It
 333 Columns widths in
 334 .Sq \&.Bl \-column
 335 should default to width
 336 .Qq <stringx>
 337 if not included.
 338 .\" LIST-ITEM
 339 .It
 340 List-width suffix
 341 .Qq m
 342 isn't handled.
 343 .\" LIST-ITEM
 344 .It
 345 Contents of the SYNOPSIS section aren't checked.
 346 .El