-.\" $Id: mdoc.3,v 1.21 2009/03/21 21:09:00 kristaps Exp $
+.\" $Id: mdoc.3,v 1.49 2010/08/20 01:02:07 schwarze Exp $
.\"
-.\" Copyright (c) 2009 Kristaps Dzonsons <kristaps@openbsd.org>
+.\" Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
+.\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" 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 21 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: August 20 2010 $
+.Dt MDOC 3
.Os
-.\" SECTION
.Sh NAME
+.Nm mdoc ,
.Nm mdoc_alloc ,
-.Nm mdoc_parseln ,
.Nm mdoc_endparse ,
-.Nm mdoc_node ,
-.Nm mdoc_meta ,
.Nm mdoc_free ,
+.Nm mdoc_meta ,
+.Nm mdoc_node ,
+.Nm mdoc_parseln ,
.Nm mdoc_reset
.Nd mdoc macro compiler library
-.\" SECTION
.Sh SYNOPSIS
-.Fd #include <mdoc.h>
+.In mandoc.h
+.In mdoc.h
.Vt extern const char * const * mdoc_macronames;
.Vt extern const char * const * mdoc_argnames;
.Ft "struct mdoc *"
-.Fn mdoc_alloc "void *data" "int pflags" "const struct mdoc_cb *cb"
-.Ft void
-.Fn mdoc_reset "struct mdoc *mdoc"
+.Fo mdoc_alloc
+.Fa "struct regset *regs"
+.Fa "void *data"
+.Fa "mandocmsg msgs"
+.Fc
+.Ft int
+.Fn mdoc_endparse "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 *"
-.Fn mdoc_node "struct mdoc *mdoc"
.Ft "const struct mdoc_meta *"
-.Fn mdoc_meta "struct mdoc *mdoc"
+.Fn mdoc_meta "const struct mdoc *mdoc"
+.Ft "const struct mdoc_node *"
+.Fn mdoc_node "const struct mdoc *mdoc"
.Ft int
-.Fn mdoc_endparse "struct mdoc *mdoc"
-.\" SECTION
+.Fo mdoc_parseln
+.Fa "struct mdoc *mdoc"
+.Fa "int line"
+.Fa "char *buf"
+.Fc
+.Ft int
+.Fn mdoc_reset "struct mdoc *mdoc"
.Sh DESCRIPTION
The
.Nm mdoc
-library parses lines of
+library parses lines of
.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
-.Xr mdoctree 1 .
-.\" PARAGRAPH
+input
+into an abstract syntax tree (AST).
.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_node
+.Fn mdoc_node
and
.Fn mdoc_meta ,
then free all allocated memory with
The
.Fn mdoc_reset
function may be used in order to reset the parser for another input
-sequence. See the
+sequence.
+See the
.Sx EXAMPLES
-section for a full example.
-.\" PARAGRAPH
+section for a simple example.
.Pp
-This section further defines the
+This section further defines the
.Sx Types ,
-.Sx Functions
+.Sx Functions
and
.Sx Variables
-available to programmers. Following that, the
-.Sx Abstract Syntax Tree
+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
+.Bl -ohang
.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
+A parsed node.
+Defined in
.Pa mdoc.h .
-See
+See
.Sx Abstract Syntax Tree
for details.
+.It Vt mandocmsg
+A function callback type defined in
+.Pa mandoc.h .
.El
-.\" SUBSECTION
.Ss Functions
Function descriptions follow:
-.Bl -ohang -offset "XXXX"
-.\" LIST-ITEM
+.Bl -ohang
.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.
+Allocates a parsing structure.
The
-.Fa pflags
-arguments are defined in
-.Pa mdoc.h .
-Returns NULL on failure. If non-NULL, the pointer must be freed with
+.Fa data
+pointer is passed to
+.Fa msgs .
+Returns NULL on failure.
+If non-NULL, the pointer must be freed with
.Fn mdoc_free .
-.\" LIST-ITEM
.It Fn mdoc_reset
-Reset the parser for another parse routine. After its use,
+Reset the parser for another parse routine.
+After its use,
.Fn mdoc_parseln
behaves as if invoked for the first time.
-.\" LIST-ITEM
+If it returns 0, memory could not be allocated.
.It Fn mdoc_free
-Free all resources of a parser. The pointer is no longer valid after
-invocation.
-.\" LIST-ITEM
+Free all resources of a parser.
+The pointer is no longer valid after invocation.
.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
+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
.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
+the resulting tree is incomplete.
+Returns 0 on failure, 1 on success.
.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
-yet been supplied or
+Returns the document's parsed meta-data.
+If this information has not yet been supplied or
.Fn mdoc_parseln
or
.Fn mdoc_endparse
return 0, the data will be incomplete.
.El
-.\" SUBSECTION
.Ss Variables
The following variables are also defined:
-.Bl -ohang -offset "XXXX"
-.\" LIST-ITEM
+.Bl -ohang
.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
-.\" SUBSECTION
.Ss Abstract Syntax Tree
-The
+The
.Nm
functions produce an abstract syntax tree (AST) describing input 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 ;
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
+fail, it may be incomplete.
.Pp
This AST is governed by the ontological
rules dictated in
.Xr mdoc 7
-and derives its terminology accordingly.
+and derives its terminology accordingly.
.Qq In-line
elements described in
.Xr mdoc 7
-are described simply as
+are described simply as
.Qq elements .
-.\" PARAGRAPH
.Pp
-The AST is composed of
+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
+field.
+Each node also provides its parse point (the
.Va line ,
.Va sec ,
and
fields), its position in the tree (the
.Va parent ,
.Va child ,
-.Va next
+.Va nchild ,
+.Va next
and
-.Va prev
-fields) and type-specific data (the
-.Va data
-field).
-.\" PARAGRAPH
+.Va prev
+fields) and some type-specific data, in particular, for nodes generated
+from macros, the generating macro in the
+.Va tok
+field.
.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
+.Bl -tag -width "ELEMENTXX" -compact
.It ROOT
\(<- mnode+
.It mnode
\(<- BLOCK | ELEMENT | TEXT
.It BLOCK
-\(<- (HEAD [TEXT])+ [BODY [TEXT]] [TAIL [TEXT]]
-.It BLOCK
-\(<- BODY [TEXT] [TAIL [TEXT]]
+\(<- HEAD [TEXT] (BODY [TEXT])+ [TAIL [TEXT]]
.It ELEMENT
\(<- TEXT*
.It HEAD
-\(<- mnode+
+\(<- mnode*
.It BODY
-\(<- mnode+
+\(<- mnode* [ENDBODY mnode*]
.It TAIL
-\(<- mnode+
+\(<- mnode*
.It TEXT
-\(<- [[:alpha:]]*
+\(<- [[:printable:],0x1e]*
.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
+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
+Multiple body parts are only found in invocations of
+.Sq \&Bl \-column ,
+where a new body introduces a new phrase.
+.Ss Badly-nested Blocks
+The ENDBODY node is available to end the formatting associated
+with a given block before the physical end of that block.
+It has a non-null
+.Va end
+field, is of the BODY
+.Va type ,
+has the same
+.Va tok
+as the BLOCK it is ending, and has a
+.Va pending
+field pointing to that BLOCK's BODY node.
+It is an indirect child of that BODY node
+and has no children of its own.
+.Pp
+An ENDBODY node is generated when a block ends while one of its child
+blocks is still open, like in the following example:
+.Bd -literal -offset indent
+\&.Ao ao
+\&.Bo bo ac
+\&.Ac bc
+\&.Bc end
+.Ed
+.Pp
+This example results in the following block structure:
+.Bd -literal -offset indent
+BLOCK Ao
+ HEAD Ao
+ BODY Ao
+ TEXT ao
+ BLOCK Bo, pending -> Ao
+ HEAD Bo
+ BODY Bo
+ TEXT bo
+ TEXT ac
+ ENDBODY Ao, pending -> Ao
+ TEXT bc
+TEXT end
+.Ed
+.Pp
+Here, the formatting of the
+.Sq \&Ao
+block extends from TEXT ao to TEXT ac,
+while the formatting of the
+.Sq \&Bo
+block extends from TEXT bo to TEXT bc.
+It renders as follows in
+.Fl T Ns Cm ascii
+mode:
+.Pp
+.Dl <ao [bo ac> bc] end
+.Pp
+Support for badly-nested blocks is only provided for backward
+compatibility with some older
+.Xr mdoc 7
+implementations.
+Using badly-nested blocks is
+.Em strongly discouraged :
+the
+.Fl T Ns Cm html
+and
+.Fl T Ns Cm xhtml
+front-ends are unable to render them in any meaningful way.
+Furthermore, behaviour when encountering badly-nested blocks is not
+consistent across troff implementations, especially when using multiple
+levels of badly-nested blocks.
.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
-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"
+This example does not error-check nor free memory upon failure.
+.Bd -literal -offset indent
+struct regset regs;
struct mdoc *mdoc;
-struct mdoc_node *node;
+const struct mdoc_node *node;
char *buf;
size_t len;
int line;
+bzero(®s, sizeof(struct regset));
line = 1;
-mdoc = mdoc_alloc(NULL, NULL);
+mdoc = mdoc_alloc(®s, NULL, NULL);
+buf = NULL;
+alloc_len = 0;
-while ((buf = fgetln(fp, &len))) {
- buf[len - 1] = '\\0';
- if ( ! mdoc_parseln(mdoc, line, buf))
- errx(1, "mdoc_parseln");
- line++;
+while ((len = getline(&buf, &alloc_len, stdin)) >= 0) {
+ if (len && buflen[len - 1] = '\en')
+ buf[len - 1] = '\e0';
+ if ( ! mdoc_parseln(mdoc, line, buf))
+ errx(1, "mdoc_parseln");
+ line++;
}
if ( ! mdoc_endparse(mdoc))
- errx(1, "mdoc_endparse");
+ errx(1, "mdoc_endparse");
if (NULL == (node = mdoc_node(mdoc)))
- errx(1, "mdoc_node");
+ errx(1, "mdoc_node");
parsed(mdoc, node);
mdoc_free(mdoc);
.Ed
-.\" SECTION
+.Pp
+Please see
+.Pa main.c
+in the source archive for a rigorous reference.
.Sh SEE ALSO
.Xr mandoc 1 ,
.Xr mdoc 7
-.\" SECTION
.Sh AUTHORS
The
.Nm
-utility was written by
-.An Kristaps Dzonsons Aq kristaps@openbsd.org .
-.\" SECTION
-.Sh CAVEATS
-.Bl -dash -compact
-.\" LIST-ITEM
-.It
-The
-.Sq \&Xc
-and
-.Sq \&Xo
-macros aren't handled when used to span lines for the
-.Sq \&It
-macro.
-.\" LIST-ITEM
-.It
-The
-.Sq \&Bsx
-macro doesn't yet understand version arguments.
-.\" LIST-ITEM
-.It
-If not given a value, the \-offset argument to
-.Sq \&Bd
-and
-.Sq \&Bl
-should by the width of
-.Qq <string> .
-.\" LIST-ITEM
-.It
-Columns widths in
-.Sq \&Bl -column
-should default to width
-.Qq <stringx>
-if not included.
-.\" LIST-ITEM
-.It
-List-width suffix
-.Qq m
-isn't handled.
-.El
+library was written by
+.An Kristaps Dzonsons Aq kristaps@bsd.lv .
git.ckatri.com / mandoc.git / blobdiff