man.3

   1 .\"     $Id: man.3,v 1.15 2010/03/31 06:37:57 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 $Mdocdate: March 31 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 .Pp
 131 Furthermore, the following escapes are accepted to allow
 132 .Xr pod2man 1
 133 documents to be correctly formatted:
 134 \e*(-- (dash),
 135 \e*(PI (pi),
 136 \e*(L" (left double-quote),
 137 \e*(R" (right double-quote),
 138 \e*(C+ (C++),
 139 \e*(C` (left single-quote),
 140 \e*(C' (right single-quote),
 141 \e*(Aq (apostrophe),
 142 \e*^ (hat),
 143 \e*, (comma),
 144 \e*~ (tilde),
 145 \e*/ (forward slash),
 146 \e*: (umlaut),
 147 \e*8 (beta),
 148 \e*o (degree),
 149 \e*(D- (Eth),
 150 \e*(d- (eth),
 151 \e*(Th (Thorn),
 152 and
 153 \e*(th (thorn).
 154 .
 155 .
 156 .Sh REFERENCE
 157 This section further defines the
 158 .Sx Types ,
 159 .Sx Functions
 160 and
 161 .Sx Variables
 162 available to programmers.  Following that, the
 163 .Sx Abstract Syntax Tree
 164 section documents the output tree.
 165 .
 166 .
 167 .Ss Types
 168 Both functions (see
 169 .Sx Functions )
 170 and variables (see
 171 .Sx Variables )
 172 may use the following types:
 173 .Bl -ohang
 174 .
 175 .It Vt struct man
 176 An opaque type defined in
 177 .Pa man.c .
 178 Its values are only used privately within the library.
 179 .
 180 .It Vt struct man_cb
 181 A set of message callbacks defined in
 182 .Pa man.h .
 183 .
 184 .It Vt struct man_node
 185 A parsed node.  Defined in
 186 .Pa man.h .
 187 See
 188 .Sx Abstract Syntax Tree
 189 for details.
 190 .El
 191 .
 192 .
 193 .Ss Functions
 194 Function descriptions follow:
 195 .Bl -ohang
 196 .
 197 .It Fn man_alloc
 198 Allocates a parsing structure.  The
 199 .Fa data
 200 pointer is passed to callbacks in
 201 .Fa cb ,
 202 which are documented further in the header file.
 203 The
 204 .Fa pflags
 205 arguments are defined in
 206 .Pa man.h .
 207 Returns NULL on failure.  If non-NULL, the pointer must be freed with
 208 .Fn man_free .
 209 .
 210 .It Fn man_reset
 211 Reset the parser for another parse routine.  After its use,
 212 .Fn man_parseln
 213 behaves as if invoked for the first time.
 214 .
 215 .It Fn man_free
 216 Free all resources of a parser.  The pointer is no longer valid after
 217 invocation.
 218 .
 219 .It Fn man_parseln
 220 Parse a nil-terminated line of input.  This line should not contain the
 221 trailing newline.  Returns 0 on failure, 1 on success.  The input buffer
 222 .Fa buf
 223 is modified by this function.
 224 .
 225 .It Fn man_endparse
 226 Signals that the parse is complete.  Note that if
 227 .Fn man_endparse
 228 is called subsequent to
 229 .Fn man_node ,
 230 the resulting tree is incomplete.  Returns 0 on failure, 1 on success.
 231 .
 232 .It Fn man_node
 233 Returns the first node of the parse.  Note that if
 234 .Fn man_parseln
 235 or
 236 .Fn man_endparse
 237 return 0, the tree will be incomplete.
 238 .It Fn man_meta
 239 Returns the document's parsed meta-data.  If this information has not
 240 yet been supplied or
 241 .Fn man_parseln
 242 or
 243 .Fn man_endparse
 244 return 0, the data will be incomplete.
 245 .El
 246 .
 247 .
 248 .Ss Variables
 249 The following variables are also defined:
 250 .Bl -ohang
 251 .
 252 .It Va man_macronames
 253 An array of string-ified token names.
 254 .El
 255 .
 256 .
 257 .Ss Abstract Syntax Tree
 258 The
 259 .Nm
 260 functions produce an abstract syntax tree (AST) describing input in a
 261 regular form.  It may be reviewed at any time with
 262 .Fn man_nodes ;
 263 however, if called before
 264 .Fn man_endparse ,
 265 or after
 266 .Fn man_endparse
 267 or
 268 .Fn man_parseln
 269 fail, it may be incomplete.
 270 .
 271 .Pp
 272 This AST is governed by the ontological
 273 rules dictated in
 274 .Xr man 7
 275 and derives its terminology accordingly.
 276 .
 277 .Pp
 278 The AST is composed of
 279 .Vt struct man_node
 280 nodes with element, root and text types as declared
 281 by the
 282 .Va type
 283 field.  Each node also provides its parse point (the
 284 .Va line ,
 285 .Va sec ,
 286 and
 287 .Va pos
 288 fields), its position in the tree (the
 289 .Va parent ,
 290 .Va child ,
 291 .Va next
 292 and
 293 .Va prev
 294 fields) and some type-specific data.
 295 .
 296 .Pp
 297 The tree itself is arranged according to the following normal form,
 298 where capitalised non-terminals represent nodes.
 299 .Pp
 300 .Bl -tag -width "ELEMENTXX" -compact
 301 .It ROOT
 302 \(<- mnode+
 303 .It mnode
 304 \(<- ELEMENT | TEXT | BLOCK
 305 .It BLOCK
 306 \(<- HEAD BODY
 307 .It HEAD
 308 \(<- mnode*
 309 .It BODY
 310 \(<- mnode*
 311 .It ELEMENT
 312 \(<- ELEMENT | TEXT*
 313 .It TEXT
 314 \(<- [[:alpha:]]*
 315 .El
 316 .
 317 .Pp
 318 The only elements capable of nesting other elements are those with
 319 next-lint scope as documented in
 320 .Xr man 7 .
 321 .
 322 .
 323 .Sh EXAMPLES
 324 The following example reads lines from stdin and parses them, operating
 325 on the finished parse tree with
 326 .Fn parsed .
 327 This example does not error-check nor free memory upon failure.
 328 .Bd -literal -offset indent
 329 struct man *man;
 330 struct man_node *node;
 331 char *buf;
 332 size_t len;
 333 int line;
 334
 335 line = 1;
 336 man = man_alloc(NULL, 0, NULL);
 337 buf = NULL;
 338 alloc_len = 0;
 339
 340 while ((len = getline(&buf, &alloc_len, stdin)) >= 0) {
 341     if (len && buflen[len - 1] = '\en')
 342         buf[len - 1] = '\e0';
 343     if ( ! man_parseln(man, line, buf))
 344         errx(1, "man_parseln");
 345     line++;
 346 }
 347
 348 free(buf);
 349
 350 if ( ! man_endparse(man))
 351     errx(1, "man_endparse");
 352 if (NULL == (node = man_node(man)))
 353     errx(1, "man_node");
 354
 355 parsed(man, node);
 356 man_free(man);
 357 .Ed
 358 .
 359 .
 360 .Sh SEE ALSO
 361 .Xr mandoc 1 ,
 362 .Xr man 7
 363 .
 364 .
 365 .Sh AUTHORS
 366 The
 367 .Nm
 368 utility was written by
 369 .An Kristaps Dzonsons Aq kristaps@bsd.lv .