man.3

   1 .\"     $Id: man.3,v 1.24 2010/08/20 01:02:07 schwarze 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: August 20 2010 $
  18 .Dt MAN 3
  19 .Os
  20 .Sh NAME
  21 .Nm man ,
  22 .Nm man_alloc ,
  23 .Nm man_endparse ,
  24 .Nm man_free ,
  25 .Nm man_meta ,
  26 .Nm man_node ,
  27 .Nm man_parseln ,
  28 .Nm man_reset
  29 .Nd man macro compiler library
  30 .Sh SYNOPSIS
  31 .In mandoc.h
  32 .In man.h
  33 .Vt extern const char * const * man_macronames;
  34 .Ft "struct man *"
  35 .Fo man_alloc
  36 .Fa "struct regset *regs"
  37 .Fa "void *data"
  38 .Fa "mandocmsg msgs"
  39 .Fc
  40 .Ft int
  41 .Fn man_endparse "struct man *man"
  42 .Ft void
  43 .Fn man_free "struct man *man"
  44 .Ft "const struct man_meta *"
  45 .Fn man_meta "const struct man *man"
  46 .Ft "const struct man_node *"
  47 .Fn man_node "const struct man *man"
  48 .Ft int
  49 .Fo man_parseln
  50 .Fa "struct man *man"
  51 .Fa "int line"
  52 .Fa "char *buf"
  53 .Fc
  54 .Ft void
  55 .Fn man_reset "struct man *man"
  56 .Sh DESCRIPTION
  57 The
  58 .Nm
  59 library parses lines of
  60 .Xr man 7
  61 input into an abstract syntax tree (AST).
  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.
  79 See the
  80 .Sx EXAMPLES
  81 section for a full example.
  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 .Pp
  89 .Bl -tag -width Ds -compact
  90 .It PD
  91 Has no effect.  Handled as a current-scope line macro.
  92 .It Sp
  93 A synonym for
  94 .Sq sp 0.5v
  95 .Pq part of the standard preamble for Perl documentation .
  96 Handled as a line macro.
  97 .It Vb
  98 A synonym for
  99 .Sq nf
 100 .Pq part of the standard preamble for Perl documentation .
 101 Handled as a current-scope line macro.
 102 .It Ve
 103 A synonym for
 104 .Sq fi ,
 105 closing
 106 .Sq Vb
 107 .Pq part of the standard preamble for Perl documentation .
 108 Handled as a current-scope line macro.
 109 .El
 110 .Pp
 111 Furthermore, the following escapes are accepted to allow
 112 .Xr pod2man 1
 113 documents to be correctly formatted:
 114 \e*(-- (dash),
 115 \e*(PI (pi),
 116 \e*(L" (left double-quote),
 117 \e*(R" (right double-quote),
 118 \e*(C` (left single-quote),
 119 \e*(C' (right single-quote),
 120 \e*(Aq (apostrophe),
 121 \e*^ (hat),
 122 \e*, (comma),
 123 \e*~ (tilde),
 124 \e*/ (forward slash),
 125 \e*: (umlaut),
 126 \e*8 (beta),
 127 \e*o (degree),
 128 \e*(D- (Eth),
 129 \e*(d- (eth),
 130 \e*(Th (Thorn),
 131 and
 132 \e*(th (thorn).
 133 .Sh REFERENCE
 134 This section further defines the
 135 .Sx Types ,
 136 .Sx Functions
 137 and
 138 .Sx Variables
 139 available to programmers.
 140 Following that, the
 141 .Sx Abstract Syntax Tree
 142 section documents the output tree.
 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 .It Vt struct man
 151 An opaque type defined in
 152 .Pa man.c .
 153 Its values are only used privately within the library.
 154 .It Vt mandocmsg
 155 A function callback type defined in
 156 .Pa mandoc.h .
 157 .It Vt struct man_node
 158 A parsed node.
 159 Defined in
 160 .Pa man.h .
 161 See
 162 .Sx Abstract Syntax Tree
 163 for details.
 164 .El
 165 .Ss Functions
 166 Function descriptions follow:
 167 .Bl -ohang
 168 .It Fn man_alloc
 169 Allocates a parsing structure.
 170 The
 171 .Fa data
 172 pointer is passed to
 173 .Fa msgs .
 174 Returns NULL on failure.
 175 If non-NULL, the pointer must be freed with
 176 .Fn man_free .
 177 .It Fn man_reset
 178 Reset the parser for another parse routine.
 179 After its use,
 180 .Fn man_parseln
 181 behaves as if invoked for the first time.
 182 .It Fn man_free
 183 Free all resources of a parser.
 184 The pointer is no longer valid after invocation.
 185 .It Fn man_parseln
 186 Parse a nil-terminated line of input.
 187 This line should not contain the trailing newline.
 188 Returns 0 on failure, 1 on success.
 189 The input buffer
 190 .Fa buf
 191 is modified by this function.
 192 .It Fn man_endparse
 193 Signals that the parse is complete.
 194 Note that if
 195 .Fn man_endparse
 196 is called subsequent to
 197 .Fn man_node ,
 198 the resulting tree is incomplete.
 199 Returns 0 on failure, 1 on success.
 200 .It Fn man_node
 201 Returns the first node of the parse.
 202 Note that if
 203 .Fn man_parseln
 204 or
 205 .Fn man_endparse
 206 return 0, the tree will be incomplete.
 207 .It Fn man_meta
 208 Returns the document's parsed meta-data.
 209 If this information has not yet been supplied or
 210 .Fn man_parseln
 211 or
 212 .Fn man_endparse
 213 return 0, the data will be incomplete.
 214 .El
 215 .Ss Variables
 216 The following variables are also defined:
 217 .Bl -ohang
 218 .It Va man_macronames
 219 An array of string-ified token names.
 220 .El
 221 .Ss Abstract Syntax Tree
 222 The
 223 .Nm
 224 functions produce an abstract syntax tree (AST) describing input in a
 225 regular form.
 226 It may be reviewed at any time with
 227 .Fn man_nodes ;
 228 however, if called before
 229 .Fn man_endparse ,
 230 or after
 231 .Fn man_endparse
 232 or
 233 .Fn man_parseln
 234 fail, it may be incomplete.
 235 .Pp
 236 This AST is governed by the ontological rules dictated in
 237 .Xr man 7
 238 and derives its terminology accordingly.
 239 .Pp
 240 The AST is composed of
 241 .Vt struct man_node
 242 nodes with element, root and text types as declared by the
 243 .Va type
 244 field.
 245 Each node also provides its parse point (the
 246 .Va line ,
 247 .Va sec ,
 248 and
 249 .Va pos
 250 fields), its position in the tree (the
 251 .Va parent ,
 252 .Va child ,
 253 .Va next
 254 and
 255 .Va prev
 256 fields) and some type-specific data.
 257 .Pp
 258 The tree itself is arranged according to the following normal form,
 259 where capitalised non-terminals represent nodes.
 260 .Pp
 261 .Bl -tag -width "ELEMENTXX" -compact
 262 .It ROOT
 263 \(<- mnode+
 264 .It mnode
 265 \(<- ELEMENT | TEXT | BLOCK
 266 .It BLOCK
 267 \(<- HEAD BODY
 268 .It HEAD
 269 \(<- mnode*
 270 .It BODY
 271 \(<- mnode*
 272 .It ELEMENT
 273 \(<- ELEMENT | TEXT*
 274 .It TEXT
 275 \(<- [[:alpha:]]*
 276 .El
 277 .Pp
 278 The only elements capable of nesting other elements are those with
 279 next-lint scope as documented in
 280 .Xr man 7 .
 281 .Sh EXAMPLES
 282 The following example reads lines from stdin and parses them, operating
 283 on the finished parse tree with
 284 .Fn parsed .
 285 This example does not error-check nor free memory upon failure.
 286 .Bd -literal -offset indent
 287 struct regset regs;
 288 struct man *man;
 289 struct man_node *node;
 290 char *buf;
 291 size_t len;
 292 int line;
 293
 294 bzero(&regs, sizeof(struct regset));
 295 line = 1;
 296 man = man_alloc(&regs, NULL, 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 .Pp
 319 Please see
 320 .Pa main.c
 321 in the source archive for a rigorous reference.
 322 .Sh SEE ALSO
 323 .Xr mandoc 1 ,
 324 .Xr man 7
 325 .Sh AUTHORS
 326 The
 327 .Nm
 328 library was written by
 329 .An Kristaps Dzonsons Aq kristaps@bsd.lv .