Tentative addition of front-end utility functions (out.h) (not sure if it's necessary).

[mandoc.git] / mdoc.3

diff --git a/mdoc.3 b/mdoc.3
index d6e6d30df65726b17c23efb5db4f9919f841b48c..1f68e5a780c2dae72dcf50ed0ff1b7a6be0da254 100644 (file)
--- a/mdoc.3
+++ b/mdoc.3
@@ -1,23 +1,21 @@
-.\" $Id: mdoc.3,v 1.14 2009/03/12 15:55:11 kristaps Exp $
+.\"    $Id: mdoc.3,v 1.34 2009/09/16 09:41:24 kristaps Exp $

 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any
 .\"
 .\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@kth.se>
 .\"
 .\" Permission to use, copy, modify, and distribute this software for any

-.\" purpose with or without fee is hereby granted, provided that the
-.\" above copyright notice and this permission notice appear in all
-.\" copies.
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.

 .\"
 .\"

-.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
-.\" WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
-.\" WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
-.\" AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
-.\" DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
-.\" PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
-.\" TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
-.\" PERFORMANCE OF THIS SOFTWARE.
-.\" 
-.Dd $Mdocdate: March 12 2009 $
-.Dt mdoc 3
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: September 16 2009 $
+.Dt MDOC 3

 .Os
 .\" SECTION
 .Sh NAME
 .Os
 .\" SECTION
 .Sh NAME


@@ -26,77 +24,67 @@
 .Nm mdoc_endparse ,
 .Nm mdoc_node ,
 .Nm mdoc_meta ,
 .Nm mdoc_endparse ,
 .Nm mdoc_node ,
 .Nm mdoc_meta ,

-.Nm mdoc_free
+.Nm mdoc_free ,
+.Nm mdoc_reset

 .Nd mdoc macro compiler library
 .\" SECTION
 .Sh SYNOPSIS
 .Nd mdoc macro compiler library
 .\" SECTION
 .Sh SYNOPSIS

-.Fd #include <mdoc.h>
+.Fd #include "mdoc.h"

 .Vt extern const char * const * mdoc_macronames;
 .Vt extern const char * const * mdoc_argnames;
 .Ft "struct mdoc *"
 .Vt extern const char * const * mdoc_macronames;
 .Vt extern const char * const * mdoc_argnames;
 .Ft "struct mdoc *"

-.Fn mdoc_alloc "void *data" "const struct mdoc_cb *cb"
+.Fn mdoc_alloc "void *data" "int pflags" "const struct mdoc_cb *cb"
+.Ft int
+.Fn mdoc_reset "struct mdoc *mdoc"

 .Ft void
 .Fn mdoc_free "struct mdoc *mdoc"
 .Ft int
 .Fn mdoc_parseln "struct mdoc *mdoc" "int line" "char *buf"
 .Ft "const struct mdoc_node *"
 .Ft void
 .Fn mdoc_free "struct mdoc *mdoc"
 .Ft int
 .Fn mdoc_parseln "struct mdoc *mdoc" "int line" "char *buf"
 .Ft "const struct mdoc_node *"

-.Fn mdoc_node "struct mdoc *mdoc"
+.Fn mdoc_node "const struct mdoc *mdoc"

 .Ft "const struct mdoc_meta *"
 .Ft "const struct mdoc_meta *"

-.Fn mdoc_meta "struct mdoc *mdoc"
+.Fn mdoc_meta "const struct mdoc *mdoc"

 .Ft int
 .Fn mdoc_endparse "struct mdoc *mdoc"
 .\" SECTION
 .Sh DESCRIPTION
 The
 .Nm mdoc
 .Ft int
 .Fn mdoc_endparse "struct mdoc *mdoc"
 .\" SECTION
 .Sh DESCRIPTION
 The
 .Nm mdoc

-library parses lines of mdoc input into an abstract syntax tree.  
-.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
+library parses lines of

 .Xr mdoc 7
 .Xr mdoc 7

-and
-.Xr mdoc.samples 7
-manuals.  Documents with 
-.Xr refer 1 ,
-.Xr eqn 1
-and other pre-processor sections aren't accomodated.
-.\" PARAGRAPH
-.Pp
-.Nm
-is
-.Ud
+input (and
+.Em only
+mdoc) into an abstract syntax tree (AST).

 .\" PARAGRAPH
 .Pp
 In general, applications initiate a parsing sequence with
 .Fn mdoc_alloc ,
 .\" PARAGRAPH
 .Pp
 In general, applications initiate a parsing sequence with
 .Fn mdoc_alloc ,

-parse each line in a document with 
+parse each line in a document with

 .Fn mdoc_parseln ,
 close the parsing session with
 .Fn mdoc_endparse ,
 operate over the syntax tree returned by
 .Fn mdoc_parseln ,
 close the parsing session with
 .Fn mdoc_endparse ,
 operate over the syntax tree returned by

-.Fn mdoc_node 
+.Fn mdoc_node

 and
 .Fn mdoc_meta ,
 then free all allocated memory with
 .Fn mdoc_free .
 and
 .Fn mdoc_meta ,
 then free all allocated memory with
 .Fn mdoc_free .

-See the
+The
+.Fn mdoc_reset
+function may be used in order to reset the parser for another input
+sequence.  See the

 .Sx EXAMPLES
 section for a full example.
 .\" PARAGRAPH
 .Pp
 .Sx EXAMPLES
 section for a full example.
 .\" PARAGRAPH
 .Pp

-This section further defines the 
+This section further defines the

 .Sx Types ,
 .Sx Types ,

-.Sx Functions 
+.Sx Functions

 and
 .Sx Variables
 and
 .Sx Variables

-available to programmers.  Following that,
-.Sx Character Encoding
-describes input format.  Lastly, 
-.Sx Abstract Syntax Tree ,
-documents the output tree.
+available to programmers.  Following that, the
+.Sx Abstract Syntax Tree
+section documents the output tree.

 .\" SUBSECTION
 .Ss Types
 Both functions (see
 .\" SUBSECTION
 .Ss Types
 Both functions (see


@@ -118,7 +106,7 @@ A set of message callbacks defined in
 .It Vt struct mdoc_node
 A parsed node.  Defined in
 .Pa mdoc.h .
 .It Vt struct mdoc_node
 A parsed node.  Defined in
 .Pa mdoc.h .

-See 
+See

 .Sx Abstract Syntax Tree
 for details.
 .El
 .Sx Abstract Syntax Tree
 for details.
 .El


@@ -131,37 +119,47 @@ Function descriptions follow:
 Allocates a parsing structure.  The
 .Fa data
 pointer is passed to callbacks in
 Allocates a parsing structure.  The
 .Fa data
 pointer is passed to callbacks in

-.Fa cb , 
-which are documented further in the header file.  Returns NULL on
-failure.  If non-NULL, the pointer must be freed with
+.Fa cb ,
+which are documented further in the header file.
+The
+.Fa pflags
+arguments are defined in
+.Pa mdoc.h .
+Returns NULL on failure.  If non-NULL, the pointer must be freed with

 .Fn mdoc_free .
 .\" LIST-ITEM
 .Fn mdoc_free .
 .\" LIST-ITEM

+.It Fn mdoc_reset
+Reset the parser for another parse routine.  After its use,
+.Fn mdoc_parseln
+behaves as if invoked for the first time.  If it returns 0, memory could
+not be allocated.
+.\" LIST-ITEM

 .It Fn mdoc_free
 Free all resources of a parser.  The pointer is no longer valid after
 invocation.
 .\" LIST-ITEM
 .It Fn mdoc_parseln
 Parse a nil-terminated line of input.  This line should not contain the
 .It Fn mdoc_free
 Free all resources of a parser.  The pointer is no longer valid after
 invocation.
 .\" LIST-ITEM
 .It Fn mdoc_parseln
 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
 is modified by this function.
 .\" LIST-ITEM
 .It Fn mdoc_endparse
 .Fa buf
 is modified by this function.
 .\" LIST-ITEM
 .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
 is called subsequent to
 .Fn mdoc_node ,
 the resulting tree is incomplete.  Returns 0 on failure, 1 on success.
 .\" LIST-ITEM
 .It Fn mdoc_node
 .Fn mdoc_endparse
 is called subsequent to
 .Fn mdoc_node ,
 the resulting tree is incomplete.  Returns 0 on failure, 1 on success.
 .\" LIST-ITEM
 .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
 or
 .Fn mdoc_endparse
 return 0, the tree will be incomplete.
 .It Fn mdoc_meta
 Returns the document's parsed meta-data.  If this information has not
 .Fn mdoc_parseln
 or
 .Fn mdoc_endparse
 return 0, the tree will be incomplete.
 .It Fn mdoc_meta
 Returns the document's parsed meta-data.  If this information has not

-yet been supplied or 
+yet been supplied or

 .Fn mdoc_parseln
 or
 .Fn mdoc_endparse
 .Fn mdoc_parseln
 or
 .Fn mdoc_endparse


@@ -179,79 +177,33 @@ An array of string-ified token names.
 An array of string-ified token argument names.
 .El
 .\" SUBSECTION
 An array of string-ified token argument names.
 .El
 .\" 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
-lines in a regular form.  It may be reviewed at any time with
+functions produce an abstract syntax tree (AST) describing input in a
+regular form.  It may be reviewed at any time with

 .Fn mdoc_nodes ;
 however, if called before
 .Fn mdoc_endparse ,
 or after
 .Fn mdoc_nodes ;
 however, if called before
 .Fn mdoc_endparse ,
 or after

-.Fn mdoc_endparse 
+.Fn mdoc_endparse

 or
 .Fn mdoc_parseln
 fail, it may be incomplete.
 .\" PARAGRAPH
 .Pp
 or
 .Fn mdoc_parseln
 fail, it may be incomplete.
 .\" PARAGRAPH
 .Pp

-The AST is composed of 
+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
+.Pp
+The AST is composed of

 .Vt struct mdoc_node
 nodes with block, head, body, element, root and text types as declared
 by the
 .Vt struct mdoc_node
 nodes with block, head, body, element, root and text types as declared
 by the


@@ -264,12 +216,10 @@ and
 fields), its position in the tree (the
 .Va parent ,
 .Va child ,
 fields), its position in the tree (the
 .Va parent ,
 .Va child ,

-.Va next 
+.Va next

 and
 and

-.Va prev 
-fields) and type-specific data (the
-.Va data
-field).
+.Va prev
+fields) and some type-specific data.

 .\" PARAGRAPH
 .Pp
 The tree itself is arranged according to the following normal form,
 .\" PARAGRAPH
 .Pp
 The tree itself is arranged according to the following normal form,


@@ -301,48 +251,27 @@ where capitalised non-terminals represent nodes.
 Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of
 the BLOCK production.  These refer to punctuation marks.  Furthermore,
 although a TEXT node will generally have a non-zero-length string, in
 Of note are the TEXT nodes following the HEAD, BODY and TAIL nodes of
 the BLOCK production.  These refer to punctuation marks.  Furthermore,
 although a TEXT node will generally have a non-zero-length string, in

-the specific case of 
+the specific case of

 .Sq \&.Bd \-literal ,
 an empty line will produce a zero-length string.
 .Sq \&.Bd \-literal ,
 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
 .Sh EXAMPLES
 The following example reads lines from stdin and parses them, operating
 .\" SECTION
 .Sh EXAMPLES
 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 .
 Note that, if the last line of the file isn't newline-terminated, this
 .Fn parsed .
 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 ) .
 Further, this example does not error-check nor free memory upon failure.
 .Bd -literal -offset "XXXX"
 struct mdoc *mdoc;
 .Xr fgetln 3 ) .
 Further, this example does not error-check nor free memory upon failure.
 .Bd -literal -offset "XXXX"
 struct mdoc *mdoc;

-struct mdoc_node *node;
+const struct mdoc_node *node;

 char *buf;
 size_t len;
 int line;
 
 line = 1;
 char *buf;
 size_t len;
 int line;
 
 line = 1;

-mdoc = mdoc_alloc(NULL, NULL);
+mdoc = mdoc_alloc(NULL, 0, NULL);

 
 while ((buf = fgetln(fp, &len))) {
        buf[len - 1] = '\\0';
 
 while ((buf = fgetln(fp, &len))) {
        buf[len - 1] = '\\0';


@@ -360,61 +289,48 @@ parsed(mdoc, node);
 mdoc_free(mdoc);
 .Ed
 .\" SECTION
 mdoc_free(mdoc);
 .Ed
 .\" 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
-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.
-.El
-.\" SECTION

 .Sh SEE ALSO
 .Sh SEE ALSO

-.Xr mdoc 7 ,
-.Xr mdoc.samples 7 ,
-.Xr groff 1 ,
-.Xr mdocml 1
+.Xr mandoc 1 ,
+.Xr mdoc 7

 .\" SECTION
 .Sh AUTHORS
 The
 .Nm
 .\" SECTION
 .Sh AUTHORS
 The
 .Nm

-utility was written by 
+utility was written by

 .An Kristaps Dzonsons Aq kristaps@kth.se .
 .\" SECTION
 .Sh CAVEATS
 .An Kristaps Dzonsons Aq kristaps@kth.se .
 .\" SECTION
 .Sh CAVEATS

-.Bl -bullet
+.Bl -dash -compact

 .\" LIST-ITEM
 .It
 .\" LIST-ITEM
 .It

-The 
-.Sq \&Xc
+The
+.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
-macro.  Such usage is specifically discouraged in
-.Xr mdoc.samples 7 .
+.Sq \&.It
+macro.
+.\" LIST-ITEM
+.It
+The
+.Sq \&.Bsx
+macro family doesn't yet understand version arguments.
+.\" LIST-ITEM
+.It
+If not given a value, the \-offset argument to
+.Sq \&.Bd
+and
+.Sq \&.Bl
+should be the width of
+.Qq <string> ;
+instead, a value of
+.Li 10n
+is provided.
+.\" LIST-ITEM
+.It
+Columns widths in
+.Sq \&.Bl \-column
+should default to width
+.Qq <stringx>
+if not included.

 .El
 .El