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

Diff for /mandoc/Attic/man.3 between version 1.6 and 1.7

version 1.6, 2009/07/05 19:30:49 version 1.7, 2009/07/20 13:45:11
Line 49 
Line 49 
 .Sh DESCRIPTION  .Sh DESCRIPTION
 The  The
 .Nm man  .Nm man
 library parses lines of  library parses lines of
 .Xr man 7  .Xr man 7
 input (and  input (and
 .Em only  .Em only
Line 58  man) into an abstract syntax tree (AST).
Line 58  man) 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 man_alloc ,  .Fn man_alloc ,
 parse each line in a document with  parse each line in a document with
 .Fn man_parseln ,  .Fn man_parseln ,
 close the parsing session with  close the parsing session with
 .Fn man_endparse ,  .Fn man_endparse ,
 operate over the syntax tree returned by  operate over the syntax tree returned by
 .Fn man_node  .Fn man_node
 and  and
 .Fn man_meta ,  .Fn man_meta ,
 then free all allocated memory with  then free all allocated memory with
Line 76  sequence.  See the
Line 76  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 105  A set of message callbacks defined in
Line 105  A set of message callbacks defined in
 .It Vt struct man_node  .It Vt struct man_node
 A parsed node.  Defined in  A parsed node.  Defined in
 .Pa man.h .  .Pa man.h .
 See  See
 .Sx Abstract Syntax Tree  .Sx Abstract Syntax Tree
 for details.  for details.
 .El  .El
Line 118  Function descriptions follow:
Line 118  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 128  Returns NULL on failure.  If non-NULL, the pointer mus
Line 128  Returns NULL on failure.  If non-NULL, the pointer mus
 .Fn man_free .  .Fn man_free .
 .\" LIST-ITEM  .\" LIST-ITEM
 .It Fn man_reset  .It Fn man_reset
 Reset the parser for another parse routine.  After its use,  Reset the parser for another parse routine.  After its use,
 .Fn man_parseln  .Fn man_parseln
 behaves as if invoked for the first time.  behaves as if invoked for the first time.
 .\" LIST-ITEM  .\" LIST-ITEM
Line 138  invocation.
Line 138  invocation.
 .\" LIST-ITEM  .\" LIST-ITEM
 .It Fn man_parseln  .It Fn man_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 man_endparse  .It Fn man_endparse
 Signals that the parse is complete.  Note that if  Signals that the parse is complete.  Note that if
 .Fn man_endparse  .Fn man_endparse
 is called subsequent to  is called subsequent to
 .Fn man_node ,  .Fn man_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 man_node  .It Fn man_node
 Returns the first node of the parse.  Note that if  Returns the first node of the parse.  Note that if
 .Fn man_parseln  .Fn man_parseln
 or  or
 .Fn man_endparse  .Fn man_endparse
 return 0, the tree will be incomplete.  return 0, the tree will be incomplete.
 .It Fn man_meta  .It Fn man_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 man_parseln  .Fn man_parseln
 or  or
 .Fn man_endparse  .Fn man_endparse
Line 173  An array of string-ified token names.
Line 173  An array of string-ified token 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 181  regular form.  It may be reviewed at any time with
Line 181  regular form.  It may be reviewed at any time with
 however, if called before  however, if called before
 .Fn man_endparse ,  .Fn man_endparse ,
 or after  or after
 .Fn man_endparse  .Fn man_endparse
 or  or
 .Fn man_parseln  .Fn man_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 man 7  .Xr man 7
 and derives its terminology accordingly.  and derives its terminology accordingly.
 .\" PARAGRAPH  .\" PARAGRAPH
 .Pp  .Pp
 The AST is composed of  The AST is composed of
 .Vt struct man_node  .Vt struct man_node
 nodes with element, root and text types as declared  nodes with element, root and text types as declared
 by the  by the
Line 206  and
Line 206  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 234  next-lint scope as documented in
Line 234  next-lint scope as documented in
 .\" 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 273  man_free(man);
Line 273  man_free(man);
 .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 .

Legend:
Removed from v.1.6  
changed lines
  Added in v.1.7

CVSweb