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

Diff for /mandoc/Attic/mdoc.3 between version 1.8 and 1.15

version 1.8, 2009/02/23 12:45:19 version 1.15, 2009/03/12 16:30:50
Line 59  library implements only those macros documented in the
Line 59  library implements only those macros documented in the
 .Xr mdoc 7  .Xr mdoc 7
 and  and
 .Xr mdoc.samples 7  .Xr mdoc.samples 7
 manuals.  manuals.  Documents with
   .Xr refer 1 ,
   .Xr eqn 1
   and other pre-processor sections aren't accomodated.
 .\" PARAGRAPH  .\" PARAGRAPH
 .Pp  .Pp
 .Nm  .Nm
Line 89  This section further defines the 
Line 92  This section further defines the 
 .Sx Functions  .Sx Functions
 and  and
 .Sx Variables  .Sx Variables
 available to programmers.  The last sub-section,  available to programmers.  Following that,
   .Sx Character Encoding
   describes input format.  Lastly,
 .Sx Abstract Syntax Tree ,  .Sx Abstract Syntax Tree ,
 documents the output tree.  documents the output tree.
 .\" SUBSECTION  .\" SUBSECTION
Line 99  Both functions (see
Line 104  Both functions (see
 and variables (see  and variables (see
 .Sx Variables )  .Sx Variables )
 may use the following types:  may use the following types:
 .Bl -ohang  .Bl -ohang -offset "XXXX"
 .\" LIST-ITEM  .\" LIST-ITEM
 .It Vt struct mdoc  .It Vt struct mdoc
 An opaque type defined in  An opaque type defined in
Line 120  for details.
Line 125  for details.
 .\" SUBSECTION  .\" SUBSECTION
 .Ss Functions  .Ss Functions
 Function descriptions follow:  Function descriptions follow:
 .Bl -ohang  .Bl -ohang -offset "XXXX"
 .\" LIST-ITEM  .\" LIST-ITEM
 .It Fn mdoc_alloc  .It Fn mdoc_alloc
 Allocates a parsing structure.  The  Allocates a parsing structure.  The
Line 165  return 0, the data will be incomplete.
Line 170  return 0, the data will be incomplete.
 .\" SUBSECTION  .\" SUBSECTION
 .Ss Variables  .Ss Variables
 The following variables are also defined:  The following variables are also defined:
 .Bl -ohang  .Bl -ohang -offset "XXXX"
 .\" LIST-ITEM  .\" LIST-ITEM
 .It Va mdoc_macronames  .It Va mdoc_macronames
 An array of string-ified token names.  An array of string-ified token names.
Line 174  An array of string-ified token names.
Line 179  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
Line 213  field).
Line 275  field).
 The tree itself is arranged according to the following normal form,  The tree itself is arranged according to the following normal form,
 where capitalised non-terminals represent nodes.  where capitalised non-terminals represent nodes.
 .Pp  .Pp
 .Bl -tag -width "ELEMENTXX" -compact  .Bl -tag -width "ELEMENTXX" -compact -offset "XXXX"
 .\" LIST-ITEM  .\" LIST-ITEM
 .It ROOT  .It ROOT
 \(<- mnode+  \(<- mnode+
Line 272  Note that, if the last line of the file isn't newline-
Line 334  Note that, if the last line of the file isn't newline-
 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  .Bd -literal -offset "XXXX"
 struct mdoc *mdoc;  struct mdoc *mdoc;
 struct mdoc_node *node;  struct mdoc_node *node;
 char *buf;  char *buf;
Line 298  parsed(mdoc, node);
Line 360  parsed(mdoc, node);
 mdoc_free(mdoc);  mdoc_free(mdoc);
 .Ed  .Ed
 .\" SECTION  .\" SECTION
   .Sh COMPATIBILITY
   In general, only those macros specified by
   .Xr mdoc.samples 7
   and
   .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
   .Sq Bx
   family of macros (
   .Sq Ux ,
   .Sq Nx
   and so on) are not callable as they are in NetBSD.
   .El
   .\" SECTION
 .Sh SEE ALSO  .Sh SEE ALSO
 .Xr mdoc 7 ,  .Xr mdoc 7 ,
 .Xr mdoc.samples 7 ,  .Xr mdoc.samples 7 ,
Line 310  The
Line 424  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 -bullet
 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 .  
 .Pp  
 Un-implemented: the  
 .Sq \&Xc  .Sq \&Xc
 and  and
 .Sq \&Xo  .Sq \&Xo
Line 327  macros aren't handled when used to span lines for the
Line 436  macros aren't handled when used to span lines for the
 .Sq \&It  .Sq \&It
 macro.  Such usage is specifically discouraged in  macro.  Such usage is specifically discouraged in
 .Xr mdoc.samples 7 .  .Xr mdoc.samples 7 .
 .Pp  .El
 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.  
 .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.8  
changed lines
  Added in v.1.15
CVSweb