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

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

version 1.16, 2009/03/12 23:05:21 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 delimited in various ways.  All are  
 preceeded by 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 \&] ) ;  
 an asterisk and open-parenthesis  
 .Sq \&*(  
 for two-character sequences;  
 an asterisk and non-open-parenthesis  
 .Sq \&*  
 for single-character sequences; or one of a small set of standalone  
 single characters for other escapes.  
 .\" PARAGRAPH  
 .Pp  
 Examples:  
 .Pp  
 .Bl -tag -width "XXXXXXXX" -offset "XXXX" -compact  
 .\" LIST-ITEM  
 .It \\*(<=  
 prints  
 .Dq \*(<=  
 .Pq greater-equal  
 .\" LIST-ITEM  
 .It \\(<-  
 prints  
 .Dq \(<-  
 .Pq left-arrow  
 .\" LIST-ITEM  
 .It \\[<-]  
 also prints  
 .Dq \(<-  
 .Pq left-arrow  
 .\" LIST-ITEM  
 .It \\*(Ba  
 prints  
 .Dq \*(Ba  
 .Pq bar  
 .\" LIST-ITEM  
 .It \\*q  
 prints  
 .Dq \*q  
 .Pq double-quote  
 .El  
 .\" PARAGRAPH  
 .Pp  
 All escaped sequences are syntax-checked, but it's up to the front-end  
 system to correctly render them to the output device.  
 .\" 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 248  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 304  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 360  parsed(mdoc, node);
Line 281  parsed(mdoc, node);
 mdoc_free(mdoc);  mdoc_free(mdoc);
 .Ed  .Ed
 .\" SECTION  .\" SECTION
 .Sh COMPATIBILITY  .Sh SEE ALSO
 In general, only those macros specified by  .Xr mdocterm 1 ,
 .Xr mdoc.samples 7  .Xr mdoclint 1 ,
 and  .Xr mdoctree 1 ,
 .Xr mdoc 7  .Xr mdoc 7
 for  
 .Ox  
 and  
 .Nx  
 are supported; support for other  
 .Bx  
 systems is in progress.  
 .Bl -bullet  
 .\" LIST-ITEM  
 .It  
 .Sq \&Cd  
 isn't labelled as callable but is.  
 .\" LIST-ITEM  
 .It  
 NetBSD  
 .Sq \&It \-nested  
 is assumed for all lists: any list may be nested and  
 .Sq \-enum  
 lists will restart the sequence only for the sub-list.  
 .\" LIST-ITEM  
 .It  
 Newer NetBSD-style  
 .Sq \&It \-column  
 syntax, where column widths may be preceeded by other arguments (instead  
 of proceeded), is not supported.  
 .\" LIST-ITEM  
 .It  
 The  
 .Sq \&At  
 macro only accepts a single parameter.  
 .\" LIST-ITEM  
 .It  
 Some manuals use  
 .Sq \&Li  
 incorrectly by following it with a delimeter (see  
 .Xr mdoc.samples 7 )  
 and expecting the delimiter to render.  This is not supported.  
 .\" LIST-ITEM  
 .It  
 The system-name macros (  
 .Ns Sq \&At ,  
 .Sq \&Bsx ,  
 .Sq \&Bx ,  
 .Sq \&Fx ,  
 .Sq \&Nx ,  
 .Sq \&Ox ,  
 and  
 .Sq \&Ux )  
 are callable.  
 .El  
 .\" SECTION  .\" SECTION
 .Sh SEE ALSO  
 .Xr mdoc 7 ,  
 .Xr mdoc.samples 7 ,  
 .Xr groff 1 ,  
 .Xr mdocml 1  
 .\" SECTION  
 .Sh AUTHORS  .Sh AUTHORS
 The  The
 .Nm  .Nm
Line 429  utility was written by 
Line 294  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 -bullet  .Bl -dash -compact
 .\" LIST-ITEM  .\" LIST-ITEM
 .It  .It
 The  The
Line 438  and
Line 303  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  .\" LIST-ITEM
 .It  .It
 The  The
 .Sq \&Bsx  .Sq \&Bsx
 macro doesn't understand yet the arguments as dictated for  macro doesn't yet understand version arguments.
 .Nx .  
 .El  .El
Legend:
Removed from v.1.16  
changed lines
  Added in v.1.17
CVSweb