mdoc.3

   1 .\"
   2 .Dd $Mdocdate: January 20 2009 $
   3 .Dt mdoc 3
   4 .Os
   5 .\"
   6 .Sh NAME
   7 .Nm mdoc_alloc ,
   8 .Nm mdoc_parseln ,
   9 .Nm mdoc_endparse ,
  10 .Nm mdoc_node ,
  11 .Nm mdoc_meta ,
  12 .Nm mdoc_free
  13 .Nd mdoc macro compiler library
  14 .\"
  15 .Sh SYNOPSIS
  16 .Fd #include <mdoc.h>
  17 .Vt extern const char * const * mdoc_macronames;
  18 .Vt extern const char * const * mdoc_argnames;
  19 .Ft "struct mdoc *"
  20 .Fn mdoc_alloc "void *data" "const struct mdoc_cb *cb"
  21 .Ft void
  22 .Fn mdoc_free "struct mdoc *mdoc"
  23 .Ft int
  24 .Fn mdoc_parseln "struct mdoc *mdoc" "int line" "char *buf"
  25 .Ft "const struct mdoc_node *"
  26 .Fn mdoc_node "struct mdoc *mdoc"
  27 .Ft "const struct mdoc_meta *"
  28 .Fn mdoc_meta "struct mdoc *mdoc"
  29 .Ft int
  30 .Fn mdoc_endparse "struct mdoc *mdoc"
  31 .\"
  32 .Sh DESCRIPTION
  33 The
  34 .Nm mdoc
  35 library parses lines of mdoc-macro text into an abstract syntax tree.
  36 In general, applications initiate a parsing sequence with
  37 .Fn mdoc_alloc ,
  38 parse each line in a document with
  39 .Fn mdoc_parseln ,
  40 close the parsing session with
  41 .Fn mdoc_endparse ,
  42 operate over the syntax tree returned by
  43 .Fn mdoc_node
  44 and
  45 .Fn mdoc_meta ,
  46 then free all allocated memory with
  47 .Fn mdoc_free .
  48 See the
  49 .Sx EXAMPLES
  50 section for a full example.
  51 .Pp
  52 .\" Function descriptions.
  53 Function descriptions follow:
  54 .Bl -ohang -offset indent
  55 .It Fn mdoc_alloc
  56 Allocates a parsing structure.  The
  57 .Fa data
  58 pointer is passed to callbacks in
  59 .Fa cb ,
  60 which are documented further in the header file.  Returns NULL on
  61 failure.  If non-NULL, the pointer must be freed with
  62 .Fn mdoc_free .
  63 .It Fn mdoc_free
  64 Free all resources of a parser.  The pointer is no longer valid after
  65 invocation.
  66 .It Fn mdoc_parseln
  67 Parse a nil-terminated line of input.  This line should not contain the
  68 trailing newline.  Returns 0 on failure, 1 on success.  The input buffer
  69 .Fa buf
  70 is modified by this function.
  71 .It Fn mdoc_endparse
  72 Signals that the parse is complete.  Note that if
  73 .Fn mdoc_endparse
  74 is called subsequent to
  75 .Fn mdoc_node ,
  76 the resulting tree is incomplete.  Returns 0 on failure, 1 on success.
  77 .It Fn mdoc_node
  78 Returns the first node of the parse.  Note that if
  79 .Fn mdoc_parseln
  80 or
  81 .Fn mdoc_endparse
  82 return 0, the tree will be incomplete.
  83 .It Fn mdoc_meta
  84 Returns the document's parsed meta-data.  If this information has not
  85 yet been supplied or
  86 .Fn mdoc_parseln
  87 or
  88 .Fn mdoc_endparse
  89 return 0, the data will be incomplete.
  90 .El
  91 .Pp
  92 .\" Variable descriptions.
  93 The following variables are also defined:
  94 .Bl -ohang -offset indent
  95 .It Va mdoc_macronames
  96 An array of string-ified token names.
  97 .It Va mdoc_argnames
  98 An array of string-ified token argument names.
  99 .El
 100 .Pp
 101 .Nm
 102 is
 103 .Ud
 104 .\"
 105 .Sh EXAMPLES
 106 The following example reads lines from stdin and parses them, operating
 107 on the finished parse tree with
 108 .Fn parsed .
 109 Note that, if the last line of the file isn't newline-terminated, this
 110 will truncate the file's last character (see
 111 .Xr fgetln 3 ) .
 112 Further, this example does not error-check nor free memory upon failure.
 113 .Bd -literal
 114 struct mdoc *mdoc;
 115 struct mdoc_node *node;
 116 char *buf;
 117 size_t len;
 118 int line;
 119
 120 line = 1;
 121 mdoc = mdoc_alloc(NULL, NULL);
 122
 123 while ((buf = fgetln(fp, &len))) {
 124         buf[len - 1] = '\\0';
 125         if ( ! mdoc_parseln(mdoc, line, buf))
 126                 errx(1, "mdoc_parseln");
 127         line++;
 128 }
 129
 130 if ( ! mdoc_endparse(mdoc))
 131         errx(1, "mdoc_endparse");
 132 if (NULL == (node = mdoc_node(mdoc)))
 133         errx(1, "mdoc_node");
 134
 135 parsed(mdoc, node);
 136 mdoc_free(mdoc);
 137 .Ed
 138 .\"
 139 .Sh SEE ALSO
 140 .Xr mdoc 7 ,
 141 .Xr mdoc.samples 7 ,
 142 .Xr groff 1 ,
 143 .Xr mdocml 1
 144 .\"
 145 .\"
 146 .Sh AUTHORS
 147 The
 148 .Nm
 149 utility was written by
 150 .An Kristaps Dzonsons Aq kristaps@kth.se .
 151 .\"
 152 .\"
 153 .Sh BUGS
 154 Bugs, un-implemented macros and incompabilities are documented in this
 155 section.  The baseline for determining whether macro parsing is
 156 .Qq incompatible
 157 is the default
 158 .Xr groff 1
 159 system bundled with
 160 .Ox .
 161 .Pp
 162 Un-implemented: the
 163 .Sq \&Xc
 164 and
 165 .Sq \&Xo
 166 macros aren't handled when used to span lines for the
 167 .Sq \&It
 168 macro.  Such usage is specifically discouraged in
 169 .Xr mdoc.samples 7 .
 170 .Pp
 171 Bugs: when
 172 .Sq \&It \-column
 173 is invoked, whitespace is not stripped around
 174 .Sq \&Ta
 175 or tab-character separators.
 176 .Pp
 177 Incompatible: the
 178 .Sq \&At
 179 macro only accepts a single parameter.  Furthermore, several macros
 180 .Pf ( Sq \&Pp ,
 181 .Sq \&It ,
 182 and possibly others) accept multiple arguments with a warning.
 183 .Pp
 184 Incompatible: only those macros specified by
 185 .Xr mdoc.samples 7
 186 and
 187 .Xr mdoc 7
 188 for
 189 .Ox
 190 are supported; support for
 191 .Nx
 192 and other BSD systems is in progress.