Re: [PATCH docbook2mdoc] Add void, tag

[Ingo Schwarze <schwarze@usta.de>]

Hi Stephen,

Stephen Gregoratto wrote on Sun, Apr 21, 2019 at 01:48:45AM +1000:

> This patch adds the <void> and <tag> nodes.
> First off, <void>. From the docs:

>> The void element produces generated text that indicates the function 
>> has no arguments (or returns nothing). The exact generated text may 
>> vary. One common result is void.

Sigh.  DocBook is so inconsistent.

Yes, it says "(or returns nothing)".  But apparently, that only applies
to <methodsynopsis> and similar elements.  The <funcdef> element does
not appear to allow a <void> child, and indeed, there is none in
Xenocara - even though allowing and using it would be quite logical.

> Found this in the xenocara tree. Output as .Ft void in an .Fo block

Xenocara only uses <void> as a child of <funcprototype>, not <funcdef>,
which agrees with the DocBook specification.  So i decided to change
pnode_printfuncprototype() instead, see the commit below.

Also, i marked <void> as CLASS_TEXT rather than CLASS_LINE,
i marked it as self-closing in xml_elem_start()/xml_elem_end(),
and i added a simple stand-alone handler to pnode_print(),
in case it ever occurs outside <funcprototype>.

> <sgmltag> morphed into <tag> in DocBook 5.*, and so it should be 
> formatted the same. Found this when using the official db4-upgrade 
> stylesheet on some files.

Yeah, that seems right.

Thanks,
  Ingo


Log Message:
-----------
Implement <void> child of <funcprototype>.
Also treat <tag> just like <sgmltag> and <markup>.
Some small parts of this patch were sent in by
Stephen Gregoratto <dev at sgregoratto dot me>.

Modified Files:
--------------
    docbook2mdoc:
        docbook2mdoc.c
        node.c
        node.h
        parse.c
        tree.c

Revision Data
-------------
Index: docbook2mdoc.c
===================================================================
RCS file: /home/cvs/mdocml/docbook2mdoc/docbook2mdoc.c,v
retrieving revision 1.131
retrieving revision 1.132
diff -Ldocbook2mdoc.c -Ldocbook2mdoc.c -u -p -r1.131 -r1.132
--- docbook2mdoc.c
+++ docbook2mdoc.c
@@ -315,20 +315,6 @@ pnode_printciterefentry(struct format *f
 	pnode_unlinksub(n);
 }
 
-static void
-pnode_printfuncdef(struct format *f, struct pnode *n)
-{
-	struct pnode	*nc;
-
-	nc = TAILQ_FIRST(&n->childq);
-	if (nc != NULL && nc->node == NODE_TEXT) {
-		macro_argline(f, "Ft", nc->b);
-		pnode_unlink(nc);
-	}
-	macro_nodeline(f, "Fo", n, ARG_SINGLE);
-	pnode_unlinksub(n);
-}
-
 /*
  * The <mml:mfenced> node is a little peculiar.
  * First, it can have arbitrary open and closing tokens, which default
@@ -389,23 +375,65 @@ pnode_printmath(struct format *f, struct
 static void
 pnode_printfuncprototype(struct format *f, struct pnode *n)
 {
-	struct pnode	*nc, *fdef;
+	struct pnode	*fdef, *ftype, *nc, *nn;
 
-	TAILQ_FOREACH(fdef, &n->childq, child)
-		if (fdef->node == NODE_FUNCDEF)
+	/*
+	 * Extract <funcdef> child and ignore <void> child.
+	 * Leave other children in place, to be treated as parameters.
+	 */
+
+	fdef = NULL;
+	TAILQ_FOREACH_SAFE(nc, &n->childq, child, nn) {
+		switch (nc->node) {
+		case NODE_FUNCDEF:
+			if (fdef == NULL) {
+				fdef = nc;
+				TAILQ_REMOVE(&n->childq, nc, child);
+				nc->parent = NULL;
+			}
+			break;
+		case NODE_VOID:
+			pnode_unlink(nc);
 			break;
+		default:
+			break;
+		}
+	}
 
+	/*
+	 * If no children are left, the function is void; use .Fn.
+	 * Otherwise, use .Fo.
+	 */
+
+	nc = TAILQ_FIRST(&n->childq);
 	if (fdef != NULL) {
-		pnode_printfuncdef(f, fdef);
+		ftype = TAILQ_FIRST(&fdef->childq);
+		if (ftype != NULL && ftype->node == NODE_TEXT) {
+			macro_argline(f, "Ft", ftype->b);
+			pnode_unlink(ftype);
+		}
+		if (nc == NULL) {
+			macro_open(f, "Fn");
+			macro_addnode(f, fdef, ARG_SPACE | ARG_SINGLE);
+			macro_addarg(f, "void", ARG_SPACE);
+			macro_close(f);
+		} else
+			macro_nodeline(f, "Fo", fdef, ARG_SINGLE);
 		pnode_unlink(fdef);
-	} else
+	} else if (nc == NULL)
+		macro_line(f, "Fn UNKNOWN void");
+	else
 		macro_line(f, "Fo UNKNOWN");
 
-	TAILQ_FOREACH(nc, &n->childq, child)
-		macro_nodeline(f, "Fa", nc, ARG_SINGLE);
+	if (nc == NULL)
+		return;
 
+	while (nc != NULL) {
+		macro_nodeline(f, "Fa", nc, ARG_SINGLE);
+		pnode_unlink(nc);
+		nc = TAILQ_FIRST(&n->childq);
+	}
 	macro_line(f, "Fc");
-	pnode_unlinksub(n);
 }
 
 /*
@@ -1340,6 +1368,9 @@ pnode_print(struct format *f, struct pno
 		break;
 	case NODE_VARNAME:
 		macro_open(f, "Va");
+		break;
+	case NODE_VOID:
+		print_text(f, "void", ARG_SPACE);
 		break;
 	case NODE_XREF:
 		pnode_printxref(f, n);
Index: node.c
===================================================================
RCS file: /home/cvs/mdocml/docbook2mdoc/node.c,v
retrieving revision 1.22
retrieving revision 1.23
diff -Lnode.c -Lnode.c -u -p -r1.22 -r1.23
--- node.c
+++ node.c
@@ -143,6 +143,7 @@ static	const struct nodeprop properties[
 	{ "variablelist",	CLASS_BLOCK },
 	{ "varlistentry",	CLASS_BLOCK },
 	{ "varname",		CLASS_LINE },
+	{ "void",		CLASS_TEXT },
 	{ "warning",		CLASS_BLOCK },
 	{ "wordasword",		CLASS_TRANS },
 	{ "xref",		CLASS_LINE },
Index: node.h
===================================================================
RCS file: /home/cvs/mdocml/docbook2mdoc/node.h,v
retrieving revision 1.31
retrieving revision 1.32
diff -Lnode.h -Lnode.h -u -p -r1.31 -r1.32
--- node.h
+++ node.h
@@ -152,6 +152,7 @@ enum	nodeid {
 	NODE_VARIABLELIST,
 	NODE_VARLISTENTRY,
 	NODE_VARNAME,
+	NODE_VOID,
 	NODE_WARNING,
 	NODE_WORDASWORD,
 	NODE_XREF,
Index: parse.c
===================================================================
RCS file: /home/cvs/mdocml/docbook2mdoc/parse.c,v
retrieving revision 1.47
retrieving revision 1.48
diff -Lparse.c -Lparse.c -u -p -r1.47 -r1.48
--- parse.c
+++ parse.c
@@ -120,6 +120,7 @@ static	const struct alias aliases[] = {
 	{ "structname",		NODE_TYPE },
 	{ "surname",		NODE_PERSONNAME },
 	{ "symbol",		NODE_CONSTANT },
+	{ "tag",		NODE_MARKUP },
 	{ "trademark",		NODE_IGNORE },
 	{ "ulink",		NODE_LINK },
 	{ "userinput",		NODE_LITERAL },
@@ -519,6 +520,7 @@ xml_elem_start(struct parse *p, const ch
 	case NODE_DOCTYPE:
 	case NODE_ENTITY:
 	case NODE_SBR:
+	case NODE_VOID:
 		p->flags |= PFLAG_EEND;
 		break;
 	default:
@@ -649,6 +651,7 @@ xml_elem_end(struct parse *p, const char
 		break;
 	case NODE_DOCTYPE:
 	case NODE_SBR:
+	case NODE_VOID:
 		p->flags &= ~PFLAG_EEND;
 		/* FALLTHROUGH */
 	default:
Index: tree.c
===================================================================
RCS file: /home/cvs/mdocml/docbook2mdoc/tree.c,v
retrieving revision 1.1
retrieving revision 1.2
diff -Ltree.c -Ltree.c -u -p -r1.1 -r1.2
--- tree.c
+++ tree.c
@@ -31,7 +31,7 @@ print_node(struct pnode *n, int indent)
 
 	printf("%*s%c%s", indent, "", n->spc ? ' ' : '-',
 	    pnode_name(n->node));
-	if (pnode_class(n->node) == CLASS_TEXT) {
+	if (n->b != NULL) {
 		putchar(' ');
 		fputs(n->b, stdout);
 	}
--
 To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv