usr.bin/mandoc/man.3

   1 .\"     $Id: man.3,v 1.13 2010/03/27 10:04:56 kristaps 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 March 27, 2010
  18 .Dt MAN 3
  19 .Os
  20 .
  21 .
  22 .Sh NAME
  23 .Nm man ,
  24 .Nm man_alloc ,
  25 .Nm man_parseln ,
  26 .Nm man_endparse ,
  27 .Nm man_node ,
  28 .Nm man_meta ,
  29 .Nm man_free ,
  30 .Nm man_reset
  31 .Nd man macro compiler library
  32 .
  33 .
  34 .Sh SYNOPSIS
  35 .In man.h
  36 .Vt extern const char * const * man_macronames;
  37 .Ft "struct man *"
  38 .Fn man_alloc "void *data" "int pflags" "const struct man_cb *cb"
  39 .Ft void
  40 .Fn man_reset "struct man *man"
  41 .Ft void
  42 .Fn man_free "struct man *man"
  43 .Ft int
  44 .Fn man_parseln "struct man *man" "int line" "char *buf"
  45 .Ft "const struct man_node *"
  46 .Fn man_node "const struct man *man"
  47 .Ft "const struct man_meta *"
  48 .Fn man_meta "const struct man *man"
  49 .Ft int
  50 .Fn man_endparse "struct man *man"
  51 .
  52 .
  53 .Sh DESCRIPTION
  54 The
  55 .Nm
  56 library parses lines of
  57 .Xr man 7
  58 input (and
  59 .Em only
  60 man) into an abstract syntax tree (AST).
  61 .
  62 .Pp
  63 In general, applications initiate a parsing sequence with
  64 .Fn man_alloc ,
  65 parse each line in a document with
  66 .Fn man_parseln ,
  67 close the parsing session with
  68 .Fn man_endparse ,
  69 operate over the syntax tree returned by
  70 .Fn man_node
  71 and
  72 .Fn man_meta ,
  73 then free all allocated memory with
  74 .Fn man_free .
  75 The
  76 .Fn man_reset
  77 function may be used in order to reset the parser for another input
  78 sequence.  See the
  79 .Sx EXAMPLES
  80 section for a full example.
  81 .
  82 .Pp
  83 Beyond the full set of macros defined in
  84 .Xr man 7 ,
  85 the
  86 .Nm
  87 library also accepts the following macros:
  88 .
  89 .Pp
  90 .Bl -tag -width Ds -compact
  91 .It am
  92 .It ami
  93 .It de
  94 .It dei
  95 .It ig
  96 Instructional macros in the original roff language.  Blocks begun by
  97 these macros end with
  98 .Sq ..
  99 and may begin anywhere, although they may not break the next-line
 100 scoping rules specified in
 101 .Xr man 7 .
 102 These blocks are discarded.
 103 .
 104 .It PD
 105 Has no effect.  Handled as a current-scope line macro.
 106 .
 107 .It Sp
 108 A synonym for
 109 .Sq sp 0.5v
 110 .Pq part of the standard preamble for Perl documentation .
 111 Handled as a line macro.
 112 .
 113 .It UC
 114 Has no effect.  Handled as a current-scope line macro.
 115 .
 116 .It Vb
 117 A synonym for
 118 .Sq nf
 119 .Pq part of the standard preamble for Perl documentation .
 120 Handled as a current-scope line macro.
 121 .
 122 .It Ve
 123 A synonym for
 124 .Sq fi ,
 125 closing
 126 .Sq Vb
 127 .Pq part of the standard preamble for Perl documentation .
 128 Handled as a current-scope line macro.
 129 .El
 130 .
 131 .
 132 .Sh REFERENCE
 133 This section further defines the
 134 .Sx Types ,
 135 .Sx Functions
 136 and
 137 .Sx Variables
 138 available to programmers.  Following that, the
 139 .Sx Abstract Syntax Tree
 140 section documents the output tree.
 141 .
 142 .
 143 .Ss Types
 144 Both functions (see
 145 .Sx Functions )
 146 and variables (see
 147 .Sx Variables )
 148 may use the following types:
 149 .Bl -ohang
 150 .
 151 .It Vt struct man
 152 An opaque type defined in
 153 .Pa man.c .
 154 Its values are only used privately within the library.
 155 .
 156 .It Vt struct man_cb
 157 A set of message callbacks defined in
 158 .Pa man.h .
 159 .
 160 .It Vt struct man_node
 161 A parsed node.  Defined in
 162 .Pa man.h .
 163 See
 164 .Sx Abstract Syntax Tree
 165 for details.
 166 .El
 167 .
 168 .
 169 .Ss Functions
 170 Function descriptions follow:
 171 .Bl -ohang
 172 .
 173 .It Fn man_alloc
 174 Allocates a parsing structure.  The
 175 .Fa data
 176 pointer is passed to callbacks in
 177 .Fa cb ,
 178 which are documented further in the header file.
 179 The
 180 .Fa pflags
 181 arguments are defined in
 182 .Pa man.h .
 183 Returns NULL on failure.  If non-NULL, the pointer must be freed with
 184 .Fn man_free .
 185 .
 186 .It Fn man_reset
 187 Reset the parser for another parse routine.  After its use,
 188 .Fn man_parseln
 189 behaves as if invoked for the first time.
 190 .
 191 .It Fn man_free
 192 Free all resources of a parser.  The pointer is no longer valid after
 193 invocation.
 194 .
 195 .It Fn man_parseln
 196 Parse a nil-terminated line of input.  This line should not contain the
 197 trailing newline.  Returns 0 on failure, 1 on success.  The input buffer
 198 .Fa buf
 199 is modified by this function.
 200 .
 201 .It Fn man_endparse
 202 Signals that the parse is complete.  Note that if
 203 .Fn man_endparse
 204 is called subsequent to
 205 .Fn man_node ,
 206 the resulting tree is incomplete.  Returns 0 on failure, 1 on success.
 207 .
 208 .It Fn man_node
 209 Returns the first node of the parse.  Note that if
 210 .Fn man_parseln
 211 or
 212 .Fn man_endparse
 213 return 0, the tree will be incomplete.
 214 .It Fn man_meta
 215 Returns the document's parsed meta-data.  If this information has not
 216 yet been supplied or
 217 .Fn man_parseln
 218 or
 219 .Fn man_endparse
 220 return 0, the data will be incomplete.
 221 .El
 222 .
 223 .
 224 .Ss Variables
 225 The following variables are also defined:
 226 .Bl -ohang
 227 .
 228 .It Va man_macronames
 229 An array of string-ified token names.
 230 .El
 231 .
 232 .
 233 .Ss Abstract Syntax Tree
 234 The
 235 .Nm
 236 functions produce an abstract syntax tree (AST) describing input in a
 237 regular form.  It may be reviewed at any time with
 238 .Fn man_nodes ;
 239 however, if called before
 240 .Fn man_endparse ,
 241 or after
 242 .Fn man_endparse
 243 or
 244 .Fn man_parseln
 245 fail, it may be incomplete.
 246 .
 247 .Pp
 248 This AST is governed by the ontological
 249 rules dictated in
 250 .Xr man 7
 251 and derives its terminology accordingly.
 252 .
 253 .Pp
 254 The AST is composed of
 255 .Vt struct man_node
 256 nodes with 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 some type-specific data.
 271 .
 272 .Pp
 273 The tree itself is arranged according to the following normal form,
 274 where capitalised non-terminals represent nodes.
 275 .Pp
 276 .Bl -tag -width "ELEMENTXX" -compact
 277 .It ROOT
 278 \(<- mnode+
 279 .It mnode
 280 \(<- ELEMENT | TEXT | BLOCK
 281 .It BLOCK
 282 \(<- HEAD BODY
 283 .It HEAD
 284 \(<- mnode*
 285 .It BODY
 286 \(<- mnode*
 287 .It ELEMENT
 288 \(<- ELEMENT | TEXT*
 289 .It TEXT
 290 \(<- [[:alpha:]]*
 291 .El
 292 .
 293 .Pp
 294 The only elements capable of nesting other elements are those with
 295 next-lint scope as documented in
 296 .Xr man 7 .
 297 .
 298 .
 299 .Sh EXAMPLES
 300 The following example reads lines from stdin and parses them, operating
 301 on the finished parse tree with
 302 .Fn parsed .
 303 This example does not error-check nor free memory upon failure.
 304 .Bd -literal -offset indent
 305 struct man *man;
 306 struct man_node *node;
 307 char *buf;
 308 size_t len;
 309 int line;
 310
 311 line = 1;
 312 man = man_alloc(NULL, 0, NULL);
 313 buf = NULL;
 314 alloc_len = 0;
 315
 316 while ((len = getline(&buf, &alloc_len, stdin)) >= 0) {
 317     if (len && buflen[len - 1] = '\en')
 318         buf[len - 1] = '\e0';
 319     if ( ! man_parseln(man, line, buf))
 320         errx(1, "man_parseln");
 321     line++;
 322 }
 323
 324 free(buf);
 325
 326 if ( ! man_endparse(man))
 327     errx(1, "man_endparse");
 328 if (NULL == (node = man_node(man)))
 329     errx(1, "man_node");
 330
 331 parsed(man, node);
 332 man_free(man);
 333 .Ed
 334 .
 335 .
 336 .Sh SEE ALSO
 337 .Xr mandoc 1 ,
 338 .Xr man 7
 339 .
 340 .
 341 .Sh AUTHORS
 342 The
 343 .Nm
 344 utility was written by
 345 .An Kristaps Dzonsons Aq kristaps@bsd.lv .