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

Diff for /mandoc/Attic/mdoc.3 between version 1.32 and 1.33

version 1.32, 2009/07/19 08:34:59 version 1.33, 2009/07/20 13:45:11
Line 13 
Line 13 
 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN  .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF  .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.  .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"  .\"
 .Dd $Mdocdate$  .Dd $Mdocdate$
 .Dt MDOC 3  .Dt MDOC 3
 .Os  .Os
Line 50 
Line 50 
 .Sh DESCRIPTION  .Sh DESCRIPTION
 The  The
 .Nm mdoc  .Nm mdoc
 library parses lines of  library parses lines of
 .Xr mdoc 7  .Xr mdoc 7
 input (and  input (and
 .Em only  .Em only
Line 59  mdoc) into an abstract syntax tree (AST).
Line 59  mdoc) into an abstract syntax tree (AST).
 .Pp  .Pp
 In general, applications initiate a parsing sequence with  In general, applications initiate a parsing sequence with
 .Fn mdoc_alloc ,  .Fn mdoc_alloc ,
 parse each line in a document with  parse each line in a document with
 .Fn mdoc_parseln ,  .Fn mdoc_parseln ,
 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_node  .Fn mdoc_node
 and  and
 .Fn mdoc_meta ,  .Fn mdoc_meta ,
 then free all allocated memory with  then free all allocated memory with
Line 77  sequence.  See the
Line 77  sequence.  See the
 section for a full example.  section for a full example.
 .\" PARAGRAPH  .\" PARAGRAPH
 .Pp  .Pp
 This section further defines the  This section further defines the
 .Sx Types ,  .Sx Types ,
 .Sx Functions  .Sx Functions
 and  and
 .Sx Variables  .Sx Variables
 available to programmers.  Following that, the  available to programmers.  Following that, the
 .Sx Abstract Syntax Tree  .Sx Abstract Syntax Tree
 section documents the output tree.  section documents the output tree.
 .\" SUBSECTION  .\" SUBSECTION
 .Ss Types  .Ss Types
Line 106  A set of message callbacks defined in
Line 106  A set of message callbacks defined in
 .It Vt struct mdoc_node  .It Vt struct mdoc_node
 A parsed node.  Defined in  A parsed node.  Defined in
 .Pa mdoc.h .  .Pa mdoc.h .
 See  See
 .Sx Abstract Syntax Tree  .Sx Abstract Syntax Tree
 for details.  for details.
 .El  .El
Line 119  Function descriptions follow:
Line 119  Function descriptions follow:
 Allocates a parsing structure.  The  Allocates a parsing structure.  The
 .Fa data  .Fa data
 pointer is passed to callbacks in  pointer is passed to callbacks in
 .Fa cb ,  .Fa cb ,
 which are documented further in the header file.  which are documented further in the header file.
 The  The
 .Fa pflags  .Fa pflags
 arguments are defined in  arguments are defined in
Line 129  Returns NULL on failure.  If non-NULL, the pointer mus
Line 129  Returns NULL on failure.  If non-NULL, the pointer mus
 .Fn mdoc_free .  .Fn mdoc_free .
 .\" LIST-ITEM  .\" LIST-ITEM
 .It Fn mdoc_reset  .It Fn mdoc_reset
 Reset the parser for another parse routine.  After its use,  Reset the parser for another parse routine.  After its use,
 .Fn mdoc_parseln  .Fn mdoc_parseln
 behaves as if invoked for the first time.  If it returns 0, memory could  behaves as if invoked for the first time.  If it returns 0, memory could
 not be allocated.  not be allocated.
Line 140  invocation.
Line 140  invocation.
 .\" LIST-ITEM  .\" LIST-ITEM
 .It Fn mdoc_parseln  .It Fn mdoc_parseln
 Parse a nil-terminated line of input.  This line should not contain the  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  trailing newline.  Returns 0 on failure, 1 on success.  The input buffer
 .Fa buf  .Fa buf
 is modified by this function.  is modified by this function.
 .\" LIST-ITEM  .\" LIST-ITEM
 .It Fn mdoc_endparse  .It Fn mdoc_endparse
 Signals that the parse is complete.  Note that if  Signals that the parse is complete.  Note that if
 .Fn mdoc_endparse  .Fn mdoc_endparse
 is called subsequent to  is called subsequent to
 .Fn mdoc_node ,  .Fn mdoc_node ,
 the resulting tree is incomplete.  Returns 0 on failure, 1 on success.  the resulting tree is incomplete.  Returns 0 on failure, 1 on success.
 .\" LIST-ITEM  .\" LIST-ITEM
 .It Fn mdoc_node  .It Fn mdoc_node
 Returns the first node of the parse.  Note that if  Returns the first node of the parse.  Note that if
 .Fn mdoc_parseln  .Fn mdoc_parseln
 or  or
 .Fn mdoc_endparse  .Fn mdoc_endparse
 return 0, the tree will be incomplete.  return 0, the tree will be incomplete.
 .It Fn mdoc_meta  .It Fn mdoc_meta
 Returns the document's parsed meta-data.  If this information has not  Returns the document's parsed meta-data.  If this information has not
 yet been supplied or  yet been supplied or
 .Fn mdoc_parseln  .Fn mdoc_parseln
 or  or
 .Fn mdoc_endparse  .Fn mdoc_endparse
Line 178  An array of string-ified token argument names.
Line 178  An array of string-ified token argument names.
 .El  .El
 .\" SUBSECTION  .\" SUBSECTION
 .Ss Abstract Syntax Tree  .Ss Abstract Syntax Tree
 The  The
 .Nm  .Nm
 functions produce an abstract syntax tree (AST) describing input in a  functions produce an abstract syntax tree (AST) describing input in a
 regular form.  It may be reviewed at any time with  regular form.  It may be reviewed at any time with
Line 186  regular form.  It may be reviewed at any time with
Line 186  regular form.  It may be reviewed at any time with
 however, if called before  however, if called before
 .Fn mdoc_endparse ,  .Fn mdoc_endparse ,
 or after  or after
 .Fn mdoc_endparse  .Fn mdoc_endparse
 or  or
 .Fn mdoc_parseln  .Fn mdoc_parseln
 fail, it may be incomplete.  fail, it may be incomplete.
 .\" PARAGRAPH  .\" PARAGRAPH
 .Pp  .Pp
 This AST is governed by the ontological  This AST is governed by the ontological
 rules dictated in  rules dictated in
 .Xr mdoc 7  .Xr mdoc 7
 and derives its terminology accordingly.  and derives its terminology accordingly.
 .Qq In-line  .Qq In-line
 elements described in  elements described in
 .Xr mdoc 7  .Xr mdoc 7
 are described simply as  are described simply as
 .Qq elements .  .Qq elements .
 .\" PARAGRAPH  .\" PARAGRAPH
 .Pp  .Pp
 The AST is composed of  The AST is composed of
 .Vt struct mdoc_node  .Vt struct mdoc_node
 nodes with block, head, body, element, root and text types as declared  nodes with block, head, body, element, root and text types as declared
 by the  by the
Line 216  and
Line 216  and
 fields), its position in the tree (the  fields), its position in the tree (the
 .Va parent ,  .Va parent ,
 .Va child ,  .Va child ,
 .Va next  .Va next
 and  and
 .Va prev  .Va prev
 fields) and some type-specific data.  fields) and some type-specific data.
 .\" PARAGRAPH  .\" PARAGRAPH
 .Pp  .Pp
Line 251  where capitalised non-terminals represent nodes.
Line 251  where capitalised non-terminals represent nodes.
 Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of  Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of
 the BLOCK production.  These refer to punctuation marks.  Furthermore,  the BLOCK production.  These refer to punctuation marks.  Furthermore,
 although a TEXT node will generally have a non-zero-length string, in  although a TEXT node will generally have a non-zero-length string, in
 the specific case of  the specific case of
 .Sq \&.Bd \-literal ,  .Sq \&.Bd \-literal ,
 an empty line will produce a zero-length string.  an empty line will produce a zero-length string.
 .\" SECTION  .\" SECTION
 .Sh EXAMPLES  .Sh EXAMPLES
 The following example reads lines from stdin and parses them, operating  The following example reads lines from stdin and parses them, operating
 on the finished parse tree with  on the finished parse tree with
 .Fn parsed .  .Fn parsed .
 Note that, if the last line of the file isn't newline-terminated, this  Note that, if the last line of the file isn't newline-terminated, this
 will truncate the file's last character (see  will truncate the file's last character (see
 .Xr fgetln 3 ) .  .Xr fgetln 3 ) .
 Further, this example does not error-check nor free memory upon failure.  Further, this example does not error-check nor free memory upon failure.
 .Bd -literal -offset "XXXX"  .Bd -literal -offset "XXXX"
Line 296  mdoc_free(mdoc);
Line 296  mdoc_free(mdoc);
 .Sh AUTHORS  .Sh AUTHORS
 The  The
 .Nm  .Nm
 utility was written by  utility was written by
 .An Kristaps Dzonsons Aq kristaps@kth.se .  .An Kristaps Dzonsons Aq kristaps@kth.se .
 .\" SECTION  .\" SECTION
 .Sh CAVEATS  .Sh CAVEATS
 .Bl -dash -compact  .Bl -dash -compact
 .\" LIST-ITEM  .\" LIST-ITEM
 .It  .It
 The  The
 .Sq \&.Xc  .Sq \&.Xc
 and  and
 .Sq \&.Xo  .Sq \&.Xo
 macros aren't handled when used to span lines for the  macros aren't handled when used to span lines for the
 .Sq \&.It  .Sq \&.It
 macro.  macro.
 .\" LIST-ITEM  .\" LIST-ITEM
 .It  .It
 The  The
 .Sq \&.Bsx  .Sq \&.Bsx
 macro family doesn't yet understand version arguments.  macro family doesn't yet understand version arguments.
 .\" LIST-ITEM  .\" LIST-ITEM
Line 321  If not given a value, the \-offset argument to
Line 321  If not given a value, the \-offset argument to
 .Sq \&.Bd  .Sq \&.Bd
 and  and
 .Sq \&.Bl  .Sq \&.Bl
 should be the width of  should be the width of
 .Qq <string> ;  .Qq <string> ;
 instead, a value of  instead, a value of
 .Li 10n  .Li 10n
 is provided.  is provided.
 .\" LIST-ITEM  .\" LIST-ITEM

Legend:
Removed from v.1.32  
changed lines
  Added in v.1.33

CVSweb