usr.bin/mandoc/man.3

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