[BACK]Return to mdoc.3 CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / mandoc

Diff for /mandoc/Attic/mdoc.3 between version 1.1 and 1.4

version 1.1, 2009/01/16 14:04:26 version 1.4, 2009/01/19 17:51:33
Line 7 
Line 7 
 .Nm mdoc_alloc ,  .Nm mdoc_alloc ,
 .Nm mdoc_parseln ,  .Nm mdoc_parseln ,
 .Nm mdoc_endparse ,  .Nm mdoc_endparse ,
 .Nm mdoc_result ,  .Nm mdoc_node ,
   .Nm mdoc_meta ,
 .Nm mdoc_free  .Nm mdoc_free
 .Nd mdoc macro compiler  .Nd mdoc macro compiler library
 .\"  .\"
 .Sh SYNOPSIS  .Sh SYNOPSIS
 .In mdoc.h  .Fd #include <mdoc.h>
   .Vt extern const char * const * mdoc_macronames;
   .Vt extern const char * const * mdoc_argnames;
 .Ft "struct mdoc *"  .Ft "struct mdoc *"
 .Fn mdoc_alloc "void *data" "const struct mdoc_cb *cb"  .Fn mdoc_alloc "void *data" "const struct mdoc_cb *cb"
 .Ft void  .Ft void
 .Fn mdoc_free "struct mdoc *"  .Fn mdoc_free "struct mdoc *mdoc"
 .Ft int  .Ft int
 .Fn mdoc_parseln "struct mdoc *" "int" "char *buf"  .Fn mdoc_parseln "struct mdoc *mdoc" "int line" "char *buf"
 .Ft "const struct mdoc_node *"  .Ft "const struct mdoc_node *"
 .Fn mdoc_result "struct mdoc *"  .Fn mdoc_node "struct mdoc *mdoc"
   .Ft "const struct mdoc_meta *"
   .Fn mdoc_meta "struct mdoc *mdoc"
 .Ft int  .Ft int
 .Fn mdoc_endparse "struct mdoc *"  .Fn mdoc_endparse "struct mdoc *mdoc"
 .\"  .\"
 .Sh DESCRIPTION  .Sh DESCRIPTION
 The  The
Line 35  parse each line in a document with 
Line 40  parse each line in a document with 
 close the parsing session with  close the parsing session with
 .Fn mdoc_endparse ,  .Fn mdoc_endparse ,
 operate over the syntax tree returned by  operate over the syntax tree returned by
 .Fn mdoc_result ,  .Fn mdoc_node
   and
   .Fn mdoc_meta ,
 then free all allocated memory with  then free all allocated memory with
 .Fn mdoc_free .  .Fn mdoc_free .
 See the  See the
 .Sx EXAMPLES  .Sx EXAMPLES
 section for a full example.  section for a full example.
 .\" The following requests should be uncommented and used where appropriate.  .Pp
 .\" This next request is for sections 2, 3, and 9 function return values only.  .\" Function descriptions.
 .\" .Sh RETURN VALUES  Function descriptions follow:
 .\" .Sh EXAMPLES  .Bl -ohang -offset indent
 .\" The next request is for sections 2, 3, and 9 error and signal handling only.  .It Fn mdoc_alloc
 .\" .Sh ERRORS  Allocates a parsing structure.  The
 .\" .Sh SEE ALSO  .Fa data
 .\" .Xr foobar 1  pointer is passed to callbacks in
 .\" .Sh STANDARDS  .Fa cb ,
 .\" .Sh HISTORY  which are documented further in the header file.  Returns NULL on
 .\" .Sh AUTHORS  failure.  If non-NULL, the pointer must be freed with
 .\" .Sh CAVEATS  .Fn mdoc_free .
 .\" .Sh BUGS  .It Fn mdoc_free
   Free all resources of a parser.  The pointer is no longer valid after
   invocation.
   .It Fn mdoc_parseln
   Parse a nil-terminated line of input.  This line should not contain the
   trailing newline.  Returns 0 on failure, 1 on success.  The input buffer
   .Fa buf
   is modified by this function.
   .It Fn mdoc_endparse
   Signals that the parse is complete.  Note that if
   .Fn mdoc_endparse
   is called subsequent to
   .Fn mdoc_node ,
   the resulting tree is incomplete.  Returns 0 on failure, 1 on success.
   .It Fn mdoc_node
   Returns the first node of the parse.  Note that if
   .Fn mdoc_parseln
   or
   .Fn mdoc_endparse
   return 0, the tree will be incomplete.
   .It Fn mdoc_meta
   Returns the document's parsed meta-data.  If this information has not
   yet been supplied or
   .Fn mdoc_parseln
   or
   .Fn mdoc_endparse
   return 0, the data will be incomplete.
   .El
   .Pp
   .\" Variable descriptions.
   The following variables are also defined:
   .Bl -ohang -offset indent
   .It Va mdoc_macronames
   An array of string-ified token names.
   .It Va mdoc_argnames
   An array of string-ified token argument names.
   .El
   .Pp
   .Nm
   is
   .Ud
   .\"
   .Sh EXAMPLES
   The following example reads lines from stdin and parses them, operating
   on the finished parse tree with
   .Fn parsed .
   Note that, if the last line of the file isn't newline-terminated, this
   will truncate the file's last character (see
   .Xr fgetln 3 ) .
   Further, this example does not error-check nor free memory upon failure.
   .Bd -literal
   struct mdoc *mdoc;
   struct mdoc_node *node;
   char *buf;
   size_t len;
   int line;
   
   line = 1;
   mdoc = mdoc_alloc(NULL, NULL);
   
   while ((buf = fgetln(fp, &len))) {
           buf[len - 1] = '\\0';
           if ( ! mdoc_parseln(mdoc, line, buf))
                   errx(1, "mdoc_parseln");
           line++;
   }
   
   if ( ! mdoc_endparse(mdoc))
           errx(1, "mdoc_endparse");
   if (NULL == (node = mdoc_node(mdoc)))
           errx(1, "mdoc_node");
   
   parsed(mdoc, node);
   mdoc_free(mdoc);
   .Ed
   .\"
   .Sh SEE ALSO
   .Xr mdoc 7 ,
   .Xr mdoc.samples 7 ,
   .Xr groff 1 ,
   .Xr mdocml 1
   .\"
   .\"
   .Sh AUTHORS
   The
   .Nm
   utility was written by
   .An Kristaps Dzonsons Aq kristaps@kth.se .
   .\"
   .\"
   .Sh BUGS
   Bugs, un-implemented macros and incompabilities are documented in this
   section.  The baseline for determining whether macro parsing is
   .Qq incompatible
   is the default
   .Xr groff 1
   system bundled with
   .Ox .
   .Pp
   Un-implemented: the
   .Sq \&Xc
   and
   .Sq \&Xo
   macros aren't handled when used to span lines for the
   .Sq \&It
   macro.  Such usage is specifically discouraged in
   .Xr mdoc.samples 7 .
   .Pp
   Bugs: when
   .Sq \&It \-column
   is invoked, whitespace is not stripped around
   .Sq \&Ta
   or tab-character separators.
   .Pp
   Incompatible: the
   .Sq \&At
   macro only accepts a single parameter.  Furthermore, several macros
   .Pf ( Sq \&Pp ,
   .Sq \&It ,
   and possibly others) accept multiple arguments with a warning.
Legend:
Removed from v.1.1  
changed lines
  Added in v.1.4
CVSweb