man.3

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