man.3

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