man.3

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