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

Diff for /mandoc/Attic/mdoc.3 between version 1.11 and 1.17

version 1.11, 2009/02/25 17:02:47 version 1.17, 2009/03/14 05:21:58
Line 49 
Line 49 
 .Sh DESCRIPTION  .Sh DESCRIPTION
 The  The
 .Nm mdoc  .Nm mdoc
 library parses lines of mdoc input into an abstract syntax tree.  library parses lines of
 .Dq mdoc ,  
 which is used to format BSD manual pages, is a macro package of the  
 .Dq roff  
 language.  The  
 .Nm  
 library implements only those macros documented in the  
 .Xr mdoc 7  .Xr mdoc 7
   input (and
   .Em only
   mdoc) into an abstract syntax tree that generalises the semantic
   annotation of its input.  Common front-ends for
   .Nm
   are
   .Xr mdocterm 1 ,
   .Xr mdoclint 1
 and  and
 .Xr mdoc.samples 7  .Xr mdoctree 1 .
 manuals.  Documents with  
 .Xr refer 1 ,  
 .Xr eqn 1  
 and other pre-processor sections aren't accomodated.  
 .\" PARAGRAPH  .\" PARAGRAPH
 .Pp  .Pp
 .Nm  
 is  
 .Ud  
 .\" PARAGRAPH  
 .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
Line 92  This section further defines the 
Line 85  This section further defines the 
 .Sx Functions  .Sx Functions
 and  and
 .Sx Variables  .Sx Variables
 available to programmers.  Following that,  available to programmers.  Following that, the
 .Sx Character Encoding  .Sx Abstract Syntax Tree
 describes input format.  Lastly,  section documents the output tree.
 .Sx Abstract Syntax Tree ,  
 documents the output tree.  
 .\" SUBSECTION  .\" SUBSECTION
 .Ss Types  .Ss Types
 Both functions (see  Both functions (see
Line 179  An array of string-ified token names.
Line 170  An array of string-ified token names.
 An array of string-ified token argument names.  An array of string-ified token argument names.
 .El  .El
 .\" SUBSECTION  .\" SUBSECTION
 .Ss Character Encoding  
 The  
 .Xr mdoc 3  
 library accepts only printable ASCII characters as defined by  
 .Xr isprint 3 .  
 Non-ASCII character sequences are escaped with an escape character  
 .Sq \\  
 and followed by either an open-parenthesis  
 .Sq \&(  
 for two-character sequences; an open-bracket  
 .Sq \&[  
 for n-character sequences (terminated at a close-bracket  
 .Sq \&] ) ;  
 or one of a small set of single characters for other escapes.  
 .\" SUBSECTION  
 .Ss Abstract Syntax Tree  .Ss Abstract Syntax Tree
 The  The
 .Nm  .Nm
 functions produce an abstract syntax tree (AST) describing the input  functions produce an abstract syntax tree (AST) describing input in a
 lines in a regular form.  It may be reviewed at any time with  regular form.  It may be reviewed at any time with
 .Fn mdoc_nodes ;  .Fn mdoc_nodes ;
 however, if called before  however, if called before
 .Fn mdoc_endparse ,  .Fn mdoc_endparse ,
Line 206  or after
Line 182  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.  This AST is governed by the ontological
   rules dictated in
   .Xr mdoc 7
   and derives its terminology accordingly.
   .Qq In-line
   elements described in
   .Xr mdoc 7
   are described simply as
   .Qq elements .
 .\" PARAGRAPH  .\" PARAGRAPH
 .Pp  .Pp
 The AST is composed of  The AST is composed of
Line 262  although a TEXT node will generally have a non-zero-le
Line 246  although a TEXT node will generally have a non-zero-le
 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.
 .\" PARAGRAPH  
 .Pp  
 The rule-of-thumb for mapping node types to macros follows. In-line  
 elements, such as  
 .Sq \&.Em foo ,  
 are classified as ELEMENT nodes, which can only contain text.  
 Multi-line elements, such as  
 .Sq \&.Sh ,  
 are BLOCK elements, where the HEAD constitutes line contents and the  
 BODY constitutes subsequent lines.  In-line elements with matching  
 pairs, such as  
 .Sq \&.So  
 and  
 .Sq \&.Sc ,  
 are BLOCK elements with no HEAD tag.  The only exception to this is  
 .Sq \&.Eo  
 and  
 .Sq \&.Ec ,  
 which has a HEAD and TAIL node corresponding to the enclosure string.  
 TEXT nodes, obviously, constitute text, and the ROOT node is the  
 document's root.  
 .\" 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
Line 319  mdoc_free(mdoc);
Line 282  mdoc_free(mdoc);
 .Ed  .Ed
 .\" SECTION  .\" SECTION
 .Sh SEE ALSO  .Sh SEE ALSO
 .Xr mdoc 7 ,  .Xr mdocterm 1 ,
 .Xr mdoc.samples 7 ,  .Xr mdoclint 1 ,
 .Xr groff 1 ,  .Xr mdoctree 1 ,
 .Xr mdocml 1  .Xr mdoc 7
 .\" SECTION  .\" SECTION
 .Sh AUTHORS  .Sh AUTHORS
 The  The
Line 330  The
Line 293  The
 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 BUGS  .Sh CAVEATS
 Bugs, un-implemented macros and incompabilities are documented in this  .Bl -dash -compact
 section.  The baseline for determining whether macro parsing is  .\" LIST-ITEM
 .Qq incompatible  .It
 is the default  The
 .Xr groff 1  
 system bundled with  
 .Ox .  
 .\" PARAGRAPH  
 .Pp  
 Un-implemented: 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.  Such usage is specifically discouraged in  macro.
 .Xr mdoc.samples 7 .  .\" LIST-ITEM
 .\" PARAGRAPH  .It
 .Pp  The
 Bugs: when  .Sq \&Bsx
 .Sq \&It \-column  macro doesn't yet understand version arguments.
 is invoked, whitespace is not stripped around  .El
 .Sq \&Ta  
 or tab-character separators.  
 .\" PARAGRAPH  
 .Pp  
 Bugs: elements within columns for  
 .Sq \&It \-column  
 are not yet supported.  
 .\" PARAGRAPH  
 .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.  
 .\" PARAGRAPH  
 .Pp  
 Incompatible: only those macros specified by  
 .Xr mdoc.samples 7  
 and  
 .Xr mdoc 7  
 for  
 .Ox  
 are supported; support for  
 .Nx  
 and other  
 .Bx  
 systems is in progress.  
Legend:
Removed from v.1.11  
changed lines
  Added in v.1.17
CVSweb