Added default print of `~' with empty `Pa' (not documented with OpenBSD, but still...

[mandoc.git] / mdoc.3

diff --git a/mdoc.3 b/mdoc.3
index 8dd79ffd3bd674710e0cd7a79403b79bbde9650b..948ae4ca79edc984173df14875d0aee873a3f588 100644 (file)
--- a/mdoc.3
+++ b/mdoc.3
@@ -1,124 +1,277 @@
-.\" 
-.Dd $Mdocdate: January 20 2009 $
-.Dt mdoc 3
-.Os
+.\"    $Id: mdoc.3,v 1.33 2009/07/20 13:45:11 kristaps Exp $
+.\"
+.\" 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.

 .\"
 .\"

+.\" 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: July 20 2009 $
+.Dt MDOC 3
+.Os
+.\" SECTION

 .Sh NAME
 .Nm mdoc_alloc ,
 .Nm mdoc_parseln ,
 .Nm mdoc_endparse ,
 .Nm mdoc_node ,
 .Nm mdoc_meta ,
 .Sh NAME
 .Nm mdoc_alloc ,
 .Nm mdoc_parseln ,
 .Nm mdoc_endparse ,
 .Nm mdoc_node ,
 .Nm mdoc_meta ,

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

 .Nd mdoc macro compiler library
 .Nd mdoc macro compiler library

-.\"
+.\" SECTION

 .Sh SYNOPSIS
 .Fd #include <mdoc.h>
 .Vt extern const char * const * mdoc_macronames;
 .Vt extern const char * const * mdoc_argnames;
 .Ft "struct mdoc *"
 .Sh SYNOPSIS
 .Fd #include <mdoc.h>
 .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"
 .Ft int
 .Fn mdoc_endparse "struct mdoc *mdoc"

-.\"
+.\" SECTION

 .Sh DESCRIPTION
 The
 .Nm mdoc
 .Sh DESCRIPTION
 The
 .Nm mdoc

-library parses lines of mdoc-macro text into an abstract syntax tree.
+library parses lines of
+.Xr mdoc 7
+input (and
+.Em only
+mdoc) into an abstract syntax tree (AST).
+.\" PARAGRAPH
+.Pp

 In general, applications initiate a parsing sequence with
 .Fn mdoc_alloc ,
 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.
 .Sx EXAMPLES
 section for a full example.

+.\" PARAGRAPH

 .Pp
 .Pp

-.\" Function descriptions.
+This section further defines the
+.Sx Types ,
+.Sx Functions
+and
+.Sx Variables
+available to programmers.  Following that, the
+.Sx Abstract Syntax Tree
+section documents the output tree.
+.\" SUBSECTION
+.Ss Types
+Both functions (see
+.Sx Functions )
+and variables (see
+.Sx Variables )
+may use the following types:
+.Bl -ohang -offset "XXXX"
+.\" LIST-ITEM
+.It Vt struct mdoc
+An opaque type defined in
+.Pa mdoc.c .
+Its values are only used privately within the library.
+.\" LIST-ITEM
+.It Vt struct mdoc_cb
+A set of message callbacks defined in
+.Pa mdoc.h .
+.\" LIST-ITEM
+.It Vt struct mdoc_node
+A parsed node.  Defined in
+.Pa mdoc.h .
+See
+.Sx Abstract Syntax Tree
+for details.
+.El
+.\" SUBSECTION
+.Ss Functions

 Function descriptions follow:
 Function descriptions follow:

-.Bl -ohang -offset indent
+.Bl -ohang -offset "XXXX"
+.\" LIST-ITEM

 .It Fn mdoc_alloc
 Allocates a parsing structure.  The
 .Fa data
 pointer is passed to callbacks in
 .It Fn mdoc_alloc
 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 .
 .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.
 .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_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.
 .Fa buf
 is modified by this function.

+.\" LIST-ITEM

 .It Fn mdoc_endparse
 .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.
 .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
 .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
 return 0, the data will be incomplete.
 .El
 .Fn mdoc_parseln
 or
 .Fn mdoc_endparse
 return 0, the data will be incomplete.
 .El

-.Pp
-.\" Variable descriptions.
+.\" SUBSECTION
+.Ss Variables

 The following variables are also defined:
 The following variables are also defined:

-.Bl -ohang -offset indent
+.Bl -ohang -offset "XXXX"
+.\" LIST-ITEM

 .It Va mdoc_macronames
 An array of string-ified token names.
 .It Va mdoc_macronames
 An array of string-ified token names.

+.\" LIST-ITEM

 .It Va mdoc_argnames
 An array of string-ified token argument names.
 .El
 .It Va mdoc_argnames
 An array of string-ified token argument names.
 .El

-.Pp
+.\" SUBSECTION
+.Ss Abstract Syntax Tree
+The

 .Nm
 .Nm

-is
-.Ud
-.\" 
+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_endparse
+or
+.Fn mdoc_parseln
+fail, it may be incomplete.
+.\" PARAGRAPH
+.Pp
+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
+.Va type
+field.  Each node also provides its parse point (the
+.Va line ,
+.Va sec ,
+and
+.Va pos
+fields), its position in the tree (the
+.Va parent ,
+.Va child ,
+.Va next
+and
+.Va prev
+fields) and some type-specific data.
+.\" PARAGRAPH
+.Pp
+The tree itself is arranged according to the following normal form,
+where capitalised non-terminals represent nodes.
+.Pp
+.Bl -tag -width "ELEMENTXX" -compact -offset "XXXX"
+.\" LIST-ITEM
+.It ROOT
+\(<- mnode+
+.It mnode
+\(<- BLOCK | ELEMENT | TEXT
+.It BLOCK
+\(<- (HEAD [TEXT])+ [BODY [TEXT]] [TAIL [TEXT]]
+.It BLOCK
+\(<- BODY [TEXT] [TAIL [TEXT]]
+.It ELEMENT
+\(<- TEXT*
+.It HEAD
+\(<- mnode+
+.It BODY
+\(<- mnode+
+.It TAIL
+\(<- mnode+
+.It TEXT
+\(<- [[:alpha:]]*
+.El
+.\" PARAGRAPH
+.Pp
+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
+.Sq \&.Bd \-literal ,
+an empty line will produce a zero-length string.
+.\" SECTION

 .Sh EXAMPLES
 The following example reads lines from stdin and parses them, operating
 .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.
 .Xr fgetln 3 ) .
 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;
+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';


@@ -135,58 +288,49 @@ if (NULL == (node = mdoc_node(mdoc)))
 parsed(mdoc, node);
 mdoc_free(mdoc);
 .Ed
 parsed(mdoc, node);
 mdoc_free(mdoc);
 .Ed

-.\"
+.\" 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
 .Sh AUTHORS
 The
 .Nm

-utility was written by 
+utility was written by

 .An Kristaps Dzonsons Aq kristaps@kth.se .
 .An Kristaps Dzonsons Aq kristaps@kth.se .

-.\"
-.\"
-.Sh BUGS
-Bugs, un-implemented macros and incompabilities are documented in this
-section.  The baseline for determining whether macro parsing is 
-.Qq incompatible
-is the default
-.Xr groff 1
-system bundled with 
-.Ox .
-.Pp
-Un-implemented: the 
-.Sq \&Xc
+.\" SECTION
+.Sh CAVEATS
+.Bl -dash -compact
+.\" LIST-ITEM
+.It
+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 .
-.Pp
-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
+.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
 and

-.Xr mdoc 7
-for
-.Ox
-are supported; support for
-.Nx
-and other BSD systems is in progress.
+.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