man.3

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