man.3

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