Support for badly nested blocks, written around the time of

[mandoc.git] / mdoc.3

diff --git a/mdoc.3 b/mdoc.3
index 17d41fefe4164e3c759d9446b525bff98b7d95ac..f65b4c39e35fc17e6b56c60cea8fcceca60bed31 100644 (file)
--- a/mdoc.3
+++ b/mdoc.3
@@ -1,4 +1,4 @@
-.\"    $Id: mdoc.3,v 1.43 2010/06/27 15:52:41 kristaps Exp $
+.\"    $Id: mdoc.3,v 1.45 2010/06/29 19:20:38 schwarze Exp $

 .\"
 .\" Copyright (c) 2009-2010 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"
 .\"
 .\" Copyright (c) 2009-2010 Kristaps Dzonsons <kristaps@bsd.lv>
 .\"


@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"

-.Dd $Mdocdate: June 27 2010 $
+.Dd $Mdocdate: June 29 2010 $

 .Dt MDOC 3
 .Os
 .Sh NAME
 .Dt MDOC 3
 .Os
 .Sh NAME


@@ -35,7 +35,7 @@
 .Vt extern const char * const * mdoc_argnames;
 .Ft "struct mdoc *"
 .Fo mdoc_alloc
 .Vt extern const char * const * mdoc_argnames;
 .Ft "struct mdoc *"
 .Fo mdoc_alloc

-.Fa "const struct regset *regs"
+.Fa "struct regset *regs"

 .Fa "void *data"
 .Fa "int pflags"
 .Fa "mandocmsg msgs"
 .Fa "void *data"
 .Fa "int pflags"
 .Fa "mandocmsg msgs"


@@ -217,10 +217,14 @@ and
 fields), its position in the tree (the
 .Va parent ,
 .Va child ,
 fields), its position in the tree (the
 .Va parent ,
 .Va child ,

+.Va nchild ,

 .Va next
 and
 .Va prev
 .Va next
 and
 .Va prev

-fields) and some type-specific data.
+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
 The tree itself is arranged according to the following normal form,
 where capitalised non-terminals represent nodes.


@@ -235,11 +239,11 @@ where capitalised non-terminals represent nodes.
 .It ELEMENT
 \(<- TEXT*
 .It HEAD
 .It ELEMENT
 \(<- TEXT*
 .It HEAD

-\(<- mnode+
+\(<- mnode*

 .It BODY
 .It BODY

-\(<- mnode+
+\(<- mnode* [ENDBODY mnode*]

 .It TAIL
 .It TAIL

-\(<- mnode+
+\(<- mnode*

 .It TEXT
 \(<- [[:printable:],0x1e]*
 .El
 .It TEXT
 \(<- [[:printable:],0x1e]*
 .El


@@ -253,20 +257,81 @@ 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.
 Multiple body parts are only found in invocations of
 .Sq \&Bl \-column ,
 where a new body introduces a new phrase.

+.Ss Badly nested blocks
+A special kind of node is available to end the formatting
+associated with a given block before the physical end of that block.
+Such an ENDBODY node 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 Ao block extends from TEXT ao to TEXT ac,
+while the formatting of the Bo block extends from TEXT bo to TEXT bc,
+rendering like this in
+.Fl T Ns Cm ascii
+mode:
+.Dl <ao [bo ac> bc] end
+Support for badly nested blocks is only provided for backward
+compatibility with some older
+.Xr mdoc 7
+implementations.
+Using them in new code is stronly discouraged:
+Some frontends, in particular
+.Fl T Ns Cm html ,
+are unable to render them in any meaningful way,
+many other
+.Xr mdoc 7
+implementations do not support them, and even for those that do,
+the behaviour is not well-defined, in particular 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
 .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;
 
 struct mdoc *mdoc;
 const struct mdoc_node *node;
 char *buf;
 size_t len;
 int line;
 

+bzero(&regs, sizeof(struct regset));

 line = 1;
 line = 1;

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

 buf = NULL;
 alloc_len = 0;
 
 buf = NULL;
 alloc_len = 0;