* mdocml: Step 3: consolidate manuals.
@ 2011-03-22 10:02 kristaps
0 siblings, 0 replies; only message in thread
From: kristaps @ 2011-03-22 10:02 UTC (permalink / raw)
To: source
Log Message:
-----------
Step 3: consolidate manuals. The parse functions in mdoc.h, roff.h, and
man.h are now part of libmandoc.h, so remove these from their respective
manuals (they're no longer public-facing and we don't need a libmandoc.3
(yet?)). Before that, move the juicy data (parse tree syntax) into
new-born mandoc.3. Peck around in Makefile and index.sgml to reflect
reality.
Modified Files:
--------------
mdocml:
Makefile
index.sgml
libmandoc.h
Added Files:
-----------
mdocml:
mandoc.3
Removed Files:
-------------
mdocml:
man.3
mdoc.3
roff.3
Revision Data
-------------
--- roff.3
+++ /dev/null
@@ -1,177 +0,0 @@
-.\" $Id: roff.3,v 1.10 2011/01/01 16:18:39 kristaps Exp $
-.\"
-.\" Copyright (c) 2010 Kristaps Dzonsons <kristaps@bsd.lv>
-.\"
-.\" 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: January 1 2011 $
-.Dt ROFF 3
-.Os
-.Sh NAME
-.Nm roff ,
-.Nm roff_alloc ,
-.Nm roff_endparse ,
-.Nm roff_free ,
-.Nm roff_parseln ,
-.Nm roff_reset ,
-.Nm roff_span
-.Nd roff macro compiler library
-.Sh SYNOPSIS
-.In mandoc.h
-.In roff.h
-.Ft "struct roff *"
-.Fo roff_alloc
-.Fa "struct regset *regs"
-.Fa "void *data"
-.Fa "mandocmsg msgs"
-.Fc
-.Ft void
-.Fn roff_endparse "struct roff *roff"
-.Ft void
-.Fn roff_free "struct roff *roff"
-.Ft "enum rofferr"
-.Fo roff_parseln
-.Fa "struct roff *roff"
-.Fa "int line"
-.Fa "char **bufp"
-.Fa "size_t *bufsz"
-.Fa "int pos"
-.Fa "int *offs"
-.Fc
-.Ft void
-.Fn roff_reset "struct roff *roff"
-.Ft "const struct tbl_span *"
-.Fn roff_span "const struct roff *roff"
-.Sh DESCRIPTION
-The
-.Nm
-library processes lines of
-.Xr roff 7
-input.
-.Pp
-In general, applications initiate a parsing sequence with
-.Fn roff_alloc ,
-parse each line in a document with
-.Fn roff_parseln ,
-close the parsing session with
-.Fn roff_endparse ,
-and finally free all allocated memory with
-.Fn roff_free .
-The
-.Fn roff_reset
-function may be used in order to reset the parser for another input
-sequence.
-.Pp
-The
-.Fn roff_parseln
-function should be invoked before passing a line into the
-.Xr mdoc 3
-or
-.Xr man 3
-libraries.
-.Pp
-See the
-.Sx EXAMPLES
-section for a full example.
-.Sh REFERENCE
-This section further defines the
-.Sx Types
-and
-.Sx Functions
-available to programmers.
-.Ss Types
-Functions (see
-.Sx Functions )
-may use the following types:
-.Bl -ohang
-.It Vt "enum rofferr"
-Instructions for further processing to the caller of
-.Fn roff_parseln .
-.It Vt struct roff
-An opaque type defined in
-.Pa roff.c .
-Its values are only used privately within the library.
-.It Vt mandocmsg
-A function callback type defined in
-.Pa mandoc.h .
-.El
-.Ss Functions
-Function descriptions follow:
-.Bl -ohang
-.It Fn roff_alloc
-Allocates a parsing structure.
-The
-.Fa data
-pointer is passed to
-.Fa msgs .
-Returns NULL on failure.
-If non-NULL, the pointer must be freed with
-.Fn roff_free .
-.It Fn roff_reset
-Reset the parser for another parse routine.
-After its use,
-.Fn roff_parseln
-behaves as if invoked for the first time.
-.It Fn roff_free
-Free all resources of a parser.
-The pointer is no longer valid after invocation.
-.It Fn roff_parseln
-Parse a nil-terminated line of input.
-The character array
-.Fa bufp
-may be modified or reallocated within this function.
-In the latter case,
-.Fa bufsz
-will be modified accordingly.
-The
-.Fa offs
-pointer will be modified if the line start during subsequent processing
-of the line is not at the zeroth index.
-This line should not contain the trailing newline.
-Returns 0 on failure, 1 on success.
-.It Fn roff_endparse
-Signals that the parse is complete.
-.It Fn roff_span
-If
-.Fn roff_parseln
-returned
-.Va ROFF_TBL ,
-return the last parsed table row.
-Returns NULL otherwise.
-.El
-.Sh EXAMPLES
-See
-.Pa main.c
-in the source distribution for an example of usage.
-.Sh SEE ALSO
-.Xr mandoc 1 ,
-.Xr man 3 ,
-.Xr mdoc 3 ,
-.Xr roff 7
-.Sh AUTHORS
-The
-.Nm
-library was written by
-.An Kristaps Dzonsons Aq kristaps@bsd.lv .
-.Sh BUGS
-The implementation of user-defined strings needs improvement:
-.Bl -dash
-.It
-String values are taken literally and are not interpreted.
-.It
-Parsing of quoted strings is incomplete.
-.It
-The stings are stored internally using a singly linked list,
-which is fine for small numbers of strings,
-but ineffient when handling many strings.
-.El
--- /dev/null
+++ mandoc.3
@@ -0,0 +1,323 @@
+.\" $Id: mandoc.3,v 1.1 2011/03/22 10:02:50 kristaps Exp $
+.\"
+.\" Copyright (c) 2009, 2010, 2011 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.
+.\"
+.\" 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 22 2011 $
+.Dt MANDOC 3
+.Os
+.Sh NAME
+.Nm mandoc ,
+.Nm man_meta ,
+.Nm man_node ,
+.Nm mdoc_meta ,
+.Nm mdoc_node ,
+.Nm mparse_alloc ,
+.Nm mparse_free ,
+.Nm mparse_readfd ,
+.Nm mparse_reset ,
+.Nm mparse_result
+.Nd mandoc macro compiler library
+.Sh SYNOPSIS
+.In man.h
+.In mdoc.h
+.In mandoc.h
+.Ft "const struct man_meta *"
+.Fo man_meta
+.Fa "const struct man *man"
+.Fc
+.Ft "const struct man_node *"
+.Fo man_node
+.Fa "const struct man *man"
+.Fc
+.Ft "const struct mdoc_meta *"
+.Fo mdoc_meta
+.Fa "const struct mdoc *mdoc"
+.Fc
+.Ft "const struct mdoc_node *"
+.Fo mdoc_node
+.Fa "const struct mdoc *mdoc"
+.Fc
+.Ft void
+.Fo mparse_alloc
+.Fa "enum mparset type"
+.Fa "enum mandoclevel wlevel"
+.Fa "mandocmsg msg"
+.Fa "void *msgarg"
+.Fc
+.Ft void
+.Fo mparse_free
+.Fa "struct mparse *parse"
+.Fc
+.Ft "enum mandoclevel"
+.Fo mparse_readfd
+.Fa "struct mparse *parse"
+.Fa "int fd"
+.Fa "const char *fname"
+.Fc
+.Ft void
+.Fo mparse_reset
+.Fa "struct mparse *parse"
+.Fc
+.Ft void
+.Fo mparse_result
+.Fa "struct mparse *parse"
+.Fa "struct mdoc **mdoc"
+.Fa "struct man **man"
+.Fc
+.Vt extern const char * const * man_macronames;
+.Vt extern const char * const * mdoc_argnames;
+.Vt extern const char * const * mdoc_macronames;
+.Sh DESCRIPTION
+The
+.Nm mandoc
+library parses a
+.Ux
+manual into an abstract syntax tree (AST).
+.Ux
+manuals are composed of
+.Xr mdoc 7
+or
+.Xr man 7 ,
+and may be mixed with
+.Xr roff 7 ,
+.Xr tbl 7 ,
+and
+.Xr eqn 7
+invocations.
+.Pp
+The following describes a general parse sequence:
+.Bl -enum
+.It
+initiate a parsing sequence with
+.Fn mparse_alloc ;
+.It
+parse files or file descriptors with
+.Fn mparse_readfd ;
+.It
+retrieve a parsed syntax tree, if the parse was successful, with
+.Fn mparse_result ;
+.It
+iterate over parse nodes with
+.Fn mdoc_node
+or
+.Fn man_node ;
+.It
+free all allocated memory with
+.Fn mparse_free ,
+or invoke
+.Fn mparse_reset
+and parse new files.
+.El
+.Sh IMPLEMENTATION NOTES
+This section consists of structural documentation for
+.Xr mdoc 7
+and
+.Xr man 7
+syntax trees.
+.Ss Man Abstract Syntax Tree
+This AST is governed by the ontological rules dictated in
+.Xr man 7
+and derives its terminology accordingly.
+.Pp
+The AST is composed of
+.Vt struct man_node
+nodes with 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.
+.Pp
+The tree itself is arranged according to the following normal form,
+where capitalised non-terminals represent nodes.
+.Pp
+.Bl -tag -width "ELEMENTXX" -compact
+.It ROOT
+\(<- mnode+
+.It mnode
+\(<- ELEMENT | TEXT | BLOCK
+.It BLOCK
+\(<- HEAD BODY
+.It HEAD
+\(<- mnode*
+.It BODY
+\(<- mnode*
+.It ELEMENT
+\(<- ELEMENT | TEXT*
+.It TEXT
+\(<- [[:alpha:]]*
+.El
+.Pp
+The only elements capable of nesting other elements are those with
+next-lint scope as documented in
+.Xr man 7 .
+.Ss Mdoc Abstract Syntax Tree
+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 .
+.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 nchild ,
+.Va next
+and
+.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
+.It ROOT
+\(<- mnode+
+.It mnode
+\(<- BLOCK | ELEMENT | TEXT
+.It BLOCK
+\(<- HEAD [TEXT] (BODY [TEXT])+ [TAIL [TEXT]]
+.It ELEMENT
+\(<- TEXT*
+.It HEAD
+\(<- mnode*
+.It BODY
+\(<- mnode* [ENDBODY mnode*]
+.It TAIL
+\(<- mnode*
+.It TEXT
+\(<- [[:printable:],0x1e]*
+.El
+.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.
+Multiple body parts are only found in invocations of
+.Sq \&Bl \-column ,
+where a new body introduces a new phrase.
+.Pp
+The
+.Xr mdoc 7
+syntax tree accomodates for broken block structures as well.
+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 ;
+for example, the
+.Fl T Ns Cm html
+and
+.Fl T Ns Cm xhtml
+front-ends to
+.Xr mandoc 1
+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 SEE ALSO
+.Xr mandoc 1 ,
+.Xr eqn 7 ,
+.Xr man 7 ,
+.Xr mdoc 7 ,
+.Xr roff 7 ,
+.Xr tbl 7
+.Sh AUTHORS
+The
+.Nm
+library was written by
+.An Kristaps Dzonsons Aq kristaps@bsd.lv .
--- mdoc.3
+++ /dev/null
@@ -1,359 +0,0 @@
-.\" $Id: mdoc.3,v 1.57 2011/02/09 09:18:15 kristaps Exp $
-.\"
-.\" 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.
-.\"
-.\" 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: February 9 2011 $
-.Dt MDOC 3
-.Os
-.Sh NAME
-.Nm mdoc ,
-.Nm mdoc_addeqn ,
-.Nm mdoc_addspan ,
-.Nm mdoc_alloc ,
-.Nm mdoc_endparse ,
-.Nm mdoc_free ,
-.Nm mdoc_meta ,
-.Nm mdoc_node ,
-.Nm mdoc_parseln ,
-.Nm mdoc_reset
-.Nd mdoc macro compiler library
-.Sh SYNOPSIS
-.In mandoc.h
-.In mdoc.h
-.Vt extern const char * const * mdoc_macronames;
-.Vt extern const char * const * mdoc_argnames;
-.Ft int
-.Fo mdoc_addeqn
-.Fa "struct mdoc *mdoc"
-.Fa "const struct eqn *eqn"
-.Fc
-.Ft int
-.Fo mdoc_addspan
-.Fa "struct mdoc *mdoc"
-.Fa "const struct tbl_span *span"
-.Fc
-.Ft "struct 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 "const struct mdoc_meta *"
-.Fn mdoc_meta "const struct mdoc *mdoc"
-.Ft "const struct mdoc_node *"
-.Fn mdoc_node "const struct mdoc *mdoc"
-.Ft int
-.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
-.Xr mdoc 7
-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
-.Fn mdoc_parseln ,
-close the parsing session with
-.Fn mdoc_endparse ,
-operate over the syntax tree returned by
-.Fn mdoc_node
-and
-.Fn mdoc_meta ,
-then free all allocated memory with
-.Fn mdoc_free .
-The
-.Fn mdoc_reset
-function may be used in order to reset the parser for another input
-sequence.
-.Ss Types
-.Bl -ohang
-.It Vt struct mdoc
-An opaque type.
-Its values are only used privately within the library.
-.It Vt struct mdoc_node
-A parsed node.
-See
-.Sx Abstract Syntax Tree
-for details.
-.El
-.Ss Functions
-If
-.Fn mdoc_addeqn ,
-.Fn mdoc_addspan ,
-.Fn mdoc_parseln ,
-or
-.Fn mdoc_endparse
-return 0, calls to any function but
-.Fn mdoc_reset
-or
-.Fn mdoc_free
-will raise an assertion.
-.Bl -ohang
-.It Fn mdoc_addeqn
-Add an equation to the parsing stream.
-Returns 0 on failure, 1 on success.
-.It Fn mdoc_addspan
-Add a table span to the parsing stream.
-Returns 0 on failure, 1 on success.
-.It Fn mdoc_alloc
-Allocates a parsing structure.
-The
-.Fa data
-pointer is passed to
-.Fa msgs .
-Always returns a valid pointer.
-The pointer must be freed with
-.Fn mdoc_free .
-.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.
-.It Fn mdoc_free
-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
-.Fa buf
-is modified by this function.
-.It Fn mdoc_endparse
-Signals that the parse is complete.
-Returns 0 on failure, 1 on success.
-.It Fn mdoc_node
-Returns the first node of the parse.
-.It Fn mdoc_meta
-Returns the document's parsed meta-data.
-.El
-.Ss Variables
-.Bl -ohang
-.It Va mdoc_macronames
-An array of string-ified token names.
-.It Va mdoc_argnames
-An array of string-ified token argument names.
-.El
-.Ss Abstract Syntax Tree
-The
-.Nm
-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.
-.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 .
-.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 nchild ,
-.Va next
-and
-.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
-.It ROOT
-\(<- mnode+
-.It mnode
-\(<- BLOCK | ELEMENT | TEXT
-.It BLOCK
-\(<- HEAD [TEXT] (BODY [TEXT])+ [TAIL [TEXT]]
-.It ELEMENT
-\(<- TEXT*
-.It HEAD
-\(<- mnode*
-.It BODY
-\(<- mnode* [ENDBODY mnode*]
-.It TAIL
-\(<- mnode*
-.It TEXT
-\(<- [[:printable:],0x1e]*
-.El
-.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.
-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
-.Fn parsed .
-This example does not error-check nor free memory upon failure.
-.Bd -literal -offset indent
-struct regset regs;
-struct mdoc *mdoc;
-const struct mdoc_node *node;
-char *buf;
-size_t len;
-int line;
-
-bzero(®s, sizeof(struct regset));
-line = 1;
-mdoc = mdoc_alloc(®s, NULL, NULL);
-buf = NULL;
-alloc_len = 0;
-
-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");
-if (NULL == (node = mdoc_node(mdoc)))
- errx(1, "mdoc_node");
-
-parsed(mdoc, node);
-mdoc_free(mdoc);
-.Ed
-.Pp
-To compile this, execute
-.Pp
-.Dl % cc main.c libmdoc.a libmandoc.a
-.Pp
-where
-.Pa main.c
-is the example file.
-.Sh SEE ALSO
-.Xr mandoc 1 ,
-.Xr mdoc 7
-.Sh AUTHORS
-The
-.Nm
-library was written by
-.An Kristaps Dzonsons Aq kristaps@bsd.lv .
Index: index.sgml
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/index.sgml,v
retrieving revision 1.105
retrieving revision 1.106
diff -Lindex.sgml -Lindex.sgml -u -p -r1.105 -r1.106
--- index.sgml
+++ index.sgml
@@ -39,10 +39,9 @@
</P>
<P>
- <SPAN CLASS="nm">mdocml</SPAN> consists of the <A HREF="mdoc.3.html">libmdoc</A>, <A
- HREF="man.3.html">libman</A>, and <A HREF="roff.3.html">libroff</A> validating compilers; and <A
- HREF="mandoc.1.html">mandoc</A>, which interfaces with the compiler libraries to format output for UNIX
- terminals, XHTML, HTML, PostScript, and PDF. It is a <A CLASS="external"
+ <SPAN CLASS="nm">mdocml</SPAN> consists of the <A HREF="mandoc.3.html">libmandoc</A> validating
+ compilers and <A HREF="mandoc.1.html">mandoc</A>, which interfaces with the compiler library to format
+ output for UNIX terminals, XHTML, HTML, PostScript, and PDF. It is a <A CLASS="external"
HREF="http://bsd.lv/">BSD.lv</A> project.
</P>
@@ -60,8 +59,7 @@
<P>
<SPAN CLASS="nm">mdocml</SPAN> is architecture- and system-neutral, written in plain-old C. The most
- current version is <SPAN CLASS="attn">@VERSION@</SPAN>, dated <SPAN class="attn">@VDATE@</SPAN>. A full
- <A HREF="ChangeLog.html">ChangeLog</A> (<A HREF="ChangeLog.txt">txt</A>) is written with each release.
+ current version is <SPAN CLASS="attn">@VERSION@</SPAN>, dated <SPAN class="attn">@VDATE@</SPAN>.
</P>
<H2>
@@ -172,38 +170,14 @@
</TD>
</TR>
<TR>
- <TD VALIGN="top"><A HREF="man.3.html">man(3)</A></TD>
+ <TD VALIGN="top"><A HREF="mandoc.3.html">mandoc(3)</A></TD>
<TD VALIGN="top">
- man macro compiler library
+ mandoc macro compiler library
<SPAN STYLE="font-size: smaller;">
- (<A HREF="man.3.txt">text</A> |
- <A HREF="man.3.xhtml">xhtml</A> |
- <A HREF="man.3.pdf">pdf</A> |
- <A HREF="man.3.ps">postscript</A>)
- </SPAN>
- </TD>
- </TR>
- <TR>
- <TD VALIGN="top"><A HREF="mdoc.3.html">mdoc(3)</A></TD>
- <TD VALIGN="top">
- mdoc macro compiler library
- <SPAN STYLE="font-size: smaller;">
- (<A HREF="mdoc.3.txt">text</A> |
- <A HREF="mdoc.3.xhtml">xhtml</A> |
- <A HREF="mdoc.3.pdf">pdf</A> |
- <A HREF="mdoc.3.ps">postscript</A>)
- </SPAN>
- </TD>
- </TR>
- <TR>
- <TD VALIGN="top"><A HREF="roff.3.html">roff(3)</A></TD>
- <TD VALIGN="top">
- roff macro compiler library
- <SPAN STYLE="font-size: smaller;">
- (<A HREF="roff.3.txt">text</A> |
- <A HREF="roff.3.xhtml">xhtml</A> |
- <A HREF="roff.3.pdf">pdf</A> |
- <A HREF="roff.3.ps">postscript</A>)
+ (<A HREF="mandoc.3.txt">text</A> |
+ <A HREF="mandoc.3.xhtml">xhtml</A> |
+ <A HREF="mandoc.3.pdf">pdf</A> |
+ <A HREF="mandoc.3.ps">postscript</A>)
</SPAN>
</TD>
</TR>
@@ -220,6 +194,18 @@
</TD>
</TR>
<TR>
+ <TD VALIGN="top"><A HREF="eqn.7.html">eqn(7)</A></TD>
+ <TD VALIGN="top">
+ eqn-mandoc language reference
+ <SPAN STYLE="font-size: smaller;">
+ (<A HREF="eqn.7.txt">text</A> |
+ <A HREF="eqn.7.xhtml">xhtml</A> |
+ <A HREF="eqn.7.pdf">pdf</A> |
+ <A HREF="eqn.7.ps">postscript</A>)
+ </SPAN>
+ </TD>
+ </TR>
+ <TR>
<TD VALIGN="top"><A HREF="mandoc_char.7.html">mandoc_char(7)</A></TD>
<TD VALIGN="top">
mandoc special characters
@@ -348,7 +334,7 @@
still minimal, especially for <SPAN CLASS="flag">-Thtml</SPAN> and <SPAN
CLASS="flag">-Txhtml</SPAN>, but manages to at least display data. This means that <A
HREF="mandoc.1.html">mandoc</A> now has built-in support for two troff preprocessors via
- <A HREF="roff.3.html">libroff</A>: soelim and tbl.
+ <DEL>libroff</DEL>: soelim and tbl.
</P>
</DIV>
<DIV CLASS="news">
@@ -375,7 +361,7 @@
HREF="#documentation">DOCUMENTATION</A> section for examples. <SPAN
CLASS="attn">Attention: available style-sheet classes have been considerably
changed!</SPAN> See the <SPAN CLASS="file">example.style.css</SPAN> file for details.
- Lastly, <A HREF="mdoc.3.html">libmdoc</A> and <A HREF="man.3.html">libman</A> have been
+ Lastly, <DEL>libmdoc</DEL> and <DEL>libman</DEL> have been
cleaned up and reduced in size and complexity.
</P>
</DIV>
Index: Makefile
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/Makefile,v
retrieving revision 1.316
retrieving revision 1.317
diff -LMakefile -LMakefile -u -p -r1.316 -r1.317
--- Makefile
+++ Makefile
@@ -97,32 +97,32 @@ HEADS = mdoc.h libmdoc.h man.h libman
libmandoc.h html.h chars.h out.h main.h \
mandoc.h libroff.h
-GSGMLS = mandoc.1.sgml mdoc.3.sgml mdoc.7.sgml \
- mandoc_char.7.sgml man.7.sgml man.3.sgml roff.7.sgml \
- roff.3.sgml tbl.7.sgml eqn.7.sgml
+GSGMLS = mandoc.1.sgml mdoc.7.sgml \
+ mandoc_char.7.sgml man.7.sgml mandoc.3.sgml roff.7.sgml \
+ tbl.7.sgml eqn.7.sgml
SGMLS = index.sgml
-XHTMLS = mandoc.1.xhtml mdoc.3.xhtml \
- man.3.xhtml mdoc.7.xhtml man.7.xhtml mandoc_char.7.xhtml \
- roff.7.xhtml roff.3.xhtml tbl.7.xhtml eqn.7.xhtml
+XHTMLS = mandoc.1.xhtml \
+ mandoc.3.xhtml mdoc.7.xhtml man.7.xhtml mandoc_char.7.xhtml \
+ roff.7.xhtml tbl.7.xhtml eqn.7.xhtml
HTMLS = ChangeLog.html index.html man.h.html mdoc.h.html \
- mandoc.h.html mandoc.1.html mdoc.3.html \
- man.3.html mdoc.7.html man.7.html mandoc_char.7.html \
- roff.7.html roff.3.html tbl.7.html eqn.7.html
+ mandoc.h.html mandoc.1.html \
+ mandoc.3.html mdoc.7.html man.7.html mandoc_char.7.html \
+ roff.7.html tbl.7.html eqn.7.html
-PSS = mandoc.1.ps mdoc.3.ps man.3.ps mdoc.7.ps man.7.ps \
- mandoc_char.7.ps roff.7.ps roff.3.ps tbl.7.ps eqn.7.ps
+PSS = mandoc.1.ps mandoc.3.ps mdoc.7.ps man.7.ps \
+ mandoc_char.7.ps roff.7.ps tbl.7.ps eqn.7.ps
-PDFS = mandoc.1.pdf mdoc.3.pdf man.3.pdf mdoc.7.pdf man.7.pdf \
- mandoc_char.7.pdf roff.7.pdf roff.3.pdf tbl.7.pdf eqn.7.pdf
+PDFS = mandoc.1.pdf mandoc.3.pdf mdoc.7.pdf man.7.pdf \
+ mandoc_char.7.pdf roff.7.pdf tbl.7.pdf eqn.7.pdf
XSLS = ChangeLog.xsl
-TEXTS = mandoc.1.txt mdoc.3.txt man.3.txt mdoc.7.txt man.7.txt \
+TEXTS = mandoc.1.txt mandoc.3.txt mdoc.7.txt man.7.txt \
mandoc_char.7.txt ChangeLog.txt \
- roff.7.txt roff.3.txt tbl.7.txt eqn.7.txt
+ roff.7.txt tbl.7.txt eqn.7.txt
EXAMPLES = example.style.css
@@ -134,8 +134,8 @@ MD5S = mdocml-$(VERSION).md5
TARGZS = mdocml-$(VERSION).tar.gz
-MANS = mandoc.1 mdoc.3 mdoc.7 mandoc_char.7 man.7 \
- man.3 roff.7 roff.3 tbl.7 eqn.7
+MANS = mandoc.1 mdoc.7 mandoc_char.7 man.7 \
+ mandoc.3 roff.7 tbl.7 eqn.7
BINS = mandoc
--- man.3
+++ /dev/null
@@ -1,283 +0,0 @@
-.\" $Id: man.3,v 1.30 2011/02/09 09:18:15 kristaps Exp $
-.\"
-.\" Copyright (c) 2009-2010 Kristaps Dzonsons <kristaps@bsd.lv>
-.\"
-.\" 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: February 9 2011 $
-.Dt MAN 3
-.Os
-.Sh NAME
-.Nm man ,
-.Nm man_addeqn ,
-.Nm man_addspan ,
-.Nm man_alloc ,
-.Nm man_endparse ,
-.Nm man_free ,
-.Nm man_meta ,
-.Nm man_node ,
-.Nm man_parseln ,
-.Nm man_reset
-.Nd man macro compiler library
-.Sh SYNOPSIS
-.In mandoc.h
-.In man.h
-.Vt extern const char * const * man_macronames;
-.Ft int
-.Fo man_addeqn
-.Fa "struct man *man"
-.Fa "const struct eqn *eqn"
-.Fc
-.Ft int
-.Fo man_addspan
-.Fa "struct man *man"
-.Fa "const struct tbl_span *span"
-.Fc
-.Ft "struct man *"
-.Fo man_alloc
-.Fa "struct regset *regs"
-.Fa "void *data"
-.Fa "mandocmsg msgs"
-.Fc
-.Ft int
-.Fn man_endparse "struct man *man"
-.Ft void
-.Fn man_free "struct man *man"
-.Ft "const struct man_meta *"
-.Fn man_meta "const struct man *man"
-.Ft "const struct man_node *"
-.Fn man_node "const struct man *man"
-.Ft int
-.Fo man_parseln
-.Fa "struct man *man"
-.Fa "int line"
-.Fa "char *buf"
-.Fc
-.Ft void
-.Fn man_reset "struct man *man"
-.Sh DESCRIPTION
-The
-.Nm
-library parses lines of
-.Xr man 7
-input into an abstract syntax tree (AST).
-.Pp
-In general, applications initiate a parsing sequence with
-.Fn man_alloc ,
-parse each line in a document with
-.Fn man_parseln ,
-close the parsing session with
-.Fn man_endparse ,
-operate over the syntax tree returned by
-.Fn man_node
-and
-.Fn man_meta ,
-then free all allocated memory with
-.Fn man_free .
-The
-.Fn man_reset
-function may be used in order to reset the parser for another input
-sequence.
-.Pp
-Beyond the full set of macros defined in
-.Xr man 7 ,
-the
-.Nm
-library also accepts the following macro:
-.Pp
-.Bl -tag -width Ds -compact
-.It PD
-Has no effect.
-Handled as a current-scope line macro.
-.El
-.Ss Types
-.Bl -ohang
-.It Vt struct man
-An opaque type.
-Its values are only used privately within the library.
-.It Vt struct man_node
-A parsed node.
-See
-.Sx Abstract Syntax Tree
-for details.
-.El
-.Ss Functions
-If
-.Fn man_addeqn ,
-.Fn man_addspan ,
-.Fn man_parseln ,
-or
-.Fn man_endparse
-return 0, calls to any function but
-.Fn man_reset
-or
-.Fn man_free
-will raise an assertion.
-.Bl -ohang
-.It Fn man_addeqn
-Add an equation to the parsing stream.
-Returns 0 on failure, 1 on success.
-.It Fn man_addspan
-Add a table span to the parsing stream.
-Returns 0 on failure, 1 on success.
-.It Fn man_alloc
-Allocates a parsing structure.
-The
-.Fa data
-pointer is passed to
-.Fa msgs .
-Always returns a valid pointer.
-The pointer must be freed with
-.Fn man_free .
-.It Fn man_reset
-Reset the parser for another parse routine.
-After its use,
-.Fn man_parseln
-behaves as if invoked for the first time.
-.It Fn man_free
-Free all resources of a parser.
-The pointer is no longer valid after invocation.
-.It Fn man_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
-.Fa buf
-is modified by this function.
-.It Fn man_endparse
-Signals that the parse is complete.
-Returns 0 on failure, 1 on success.
-.It Fn man_node
-Returns the first node of the parse.
-.It Fn man_meta
-Returns the document's parsed meta-data.
-.El
-.Ss Variables
-The following variables are also defined:
-.Bl -ohang
-.It Va man_macronames
-An array of string-ified token names.
-.El
-.Ss Abstract Syntax Tree
-The
-.Nm
-functions produce an abstract syntax tree (AST) describing input in a
-regular form.
-It may be reviewed at any time with
-.Fn man_nodes ;
-however, if called before
-.Fn man_endparse ,
-or after
-.Fn man_endparse
-or
-.Fn man_parseln
-fail, it may be incomplete.
-.Pp
-This AST is governed by the ontological rules dictated in
-.Xr man 7
-and derives its terminology accordingly.
-.Pp
-The AST is composed of
-.Vt struct man_node
-nodes with 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.
-.Pp
-The tree itself is arranged according to the following normal form,
-where capitalised non-terminals represent nodes.
-.Pp
-.Bl -tag -width "ELEMENTXX" -compact
-.It ROOT
-\(<- mnode+
-.It mnode
-\(<- ELEMENT | TEXT | BLOCK
-.It BLOCK
-\(<- HEAD BODY
-.It HEAD
-\(<- mnode*
-.It BODY
-\(<- mnode*
-.It ELEMENT
-\(<- ELEMENT | TEXT*
-.It TEXT
-\(<- [[:alpha:]]*
-.El
-.Pp
-The only elements capable of nesting other elements are those with
-next-lint scope as documented in
-.Xr man 7 .
-.Sh EXAMPLES
-The following example reads lines from stdin and parses them, operating
-on the finished parse tree with
-.Fn parsed .
-This example does not error-check nor free memory upon failure.
-.Bd -literal -offset indent
-struct regset regs;
-struct man *man;
-struct man_node *node;
-char *buf;
-size_t len;
-int line;
-
-bzero(®s, sizeof(struct regset));
-line = 1;
-man = man_alloc(®s, NULL, NULL);
-buf = NULL;
-alloc_len = 0;
-
-while ((len = getline(&buf, &alloc_len, stdin)) >= 0) {
- if (len && buflen[len - 1] = '\en')
- buf[len - 1] = '\e0';
- if ( ! man_parseln(man, line, buf))
- errx(1, "man_parseln");
- line++;
-}
-
-free(buf);
-
-if ( ! man_endparse(man))
- errx(1, "man_endparse");
-if (NULL == (node = man_node(man)))
- errx(1, "man_node");
-
-parsed(man, node);
-man_free(man);
-.Ed
-.Pp
-To compile this, execute
-.Pp
-.Dl % cc main.c libman.a libmandoc.a
-.Pp
-where
-.Pa main.c
-is the example file.
-.Sh SEE ALSO
-.Xr mandoc 1 ,
-.Xr man 7
-.Sh AUTHORS
-The
-.Nm
-library was written by
-.An Kristaps Dzonsons Aq kristaps@bsd.lv .
Index: libmandoc.h
===================================================================
RCS file: /usr/vhosts/mdocml.bsd.lv/cvs/mdocml/libmandoc.h,v
retrieving revision 1.14
retrieving revision 1.15
diff -Llibmandoc.h -Llibmandoc.h -u -p -r1.14 -r1.15
--- libmandoc.h
+++ libmandoc.h
@@ -1,6 +1,6 @@
/* $Id$ */
/*
- * Copyright (c) 2009, 2010 Kristaps Dzonsons <kristaps@bsd.lv>
+ * Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
*
* Permission to use, copy, modify, and distribute this software for any
* purpose with or without fee is hereby granted, provided that the above
--
To unsubscribe send an email to source+unsubscribe@mdocml.bsd.lv
^ permalink raw reply [flat|nested] only message in thread
only message in thread, other threads:[~2011-03-22 10:02 UTC | newest]
Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2011-03-22 10:02 mdocml: Step 3: consolidate manuals kristaps
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).