man.3

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