man.3

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