Re: [PATCH docbook2mdoc] Add NODE_EMAIL

[Ingo Schwarze <schwarze@usta.de>]

Hi Stephen,

Stephen Gregoratto wrote on Fri, Mar 22, 2019 at 09:33:57PM +1100:

> Add support for the <email> node.

In the future, it might be useful to mention in which real-world
document(s) you found a given feature used.  There is no desire
to completely implement everything specified by DocBook.  Rather,
it is enough to implement parts actually used in practice.

> The official XSL stylesheets enclose the address in angle brackets,
> and so shall we.

In general, do not try to reproduce the *presentation* chosen by the
DocBook formatter by translating to mdoc(7) markup that results in
similar presentation.  Instead, find out what the DocBook markup is
intended to mean, then translate the *meaning* to mdoc(7) markup,
even if the resulting presentation differs that way.

In the case at hand, marking up an email address with ".Aq Mt" is
indeed conventional in mdoc(7).

> While we're at it, add a missing return statement for NODE_REFENTRYTITLE.

Rejoice: the file rules.c no longer exists.
Much less work to do in the future!

> I intend to add more nodes in the future

Thank you, help working on docbook2mdoc(1) is certainly welcome!

Just out of curiosity: What are you using docbook2mdoc(1) for?

[...]
> I hope to add <author> node soon, so we can generate a full `.An` block.

I had already done that some time ago, and i just committed lots
of patches i had in my tree.

> For example:
> 
>   <author>
>     <personname>
>       <firstname>Joe</firstname>
>       <othername>Bloggo</othername>
>       <surname>Bloggs</surname>
>     </personname>
>     <email>joe@foo.net</email>
>   </author>
> 
> Would transform into:
> 
>   .An Joe So Bloggo Sq Bloggs Aq Mt joe@foo.net

I assume you mean s/Sq/Sc/?

> The othername part may be overkill right now.

Possibly overkill, yes.  Or is it used a lot in practice?

> Not sure if this would require it's own function
> like pnode_printrefsect().

Off the top of my head, i can't say yet.
Macro nesting is certainly not among the easiest tasks in
docbook2mdoc(1), and the codebase is likely still fragile in that
respect.

I rebased your patch such that it applied to HEAD and committed it
in the following form.

Test results:
   $ cat tmp.txt
  <author>
    <personname>
      <firstname>Joe</firstname>
      <othername>Bloggo</othername>
      <surname>Bloggs</surname>
    </personname>
    <email>joe@foo.net</email>
  </author>
   $ ./docbook2mdoc tmp.txt | man -lc
UNKNOWN(1)                  General Commands Manual                 UNKNOWN(1)

Joe Bloggo Bloggs <joe@foo.net>

OpenBSD 6.4                     March 22, 2019                     OpenBSD 6.4

Thanks,
  Ingo


Log Message:
-----------
support <personname> and <email>;
based on a patch from Stephen Gregoratto <dev at sgregoratto dot me>

Modified Files:
--------------
    docbook2mdoc:
        docbook2mdoc.c
        extern.h

Revision Data
-------------
Index: extern.h
===================================================================
RCS file: /home/cvs/mdocml/docbook2mdoc/extern.h,v
retrieving revision 1.31
retrieving revision 1.32
diff -Lextern.h -Lextern.h -u -p -r1.31 -r1.32
--- extern.h
+++ extern.h
@@ -43,6 +43,7 @@ enum	nodeid {
 	NODE_COPYRIGHT,
 	NODE_DATE,
 	NODE_EDITOR,
+	NODE_EMAIL,
 	NODE_EMPHASIS,
 	NODE_ENTRY,
 	NODE_ENVAR,
@@ -92,6 +93,7 @@ enum	nodeid {
 	NODE_PARA,
 	NODE_PARAMDEF,
 	NODE_PARAMETER,
+	NODE_PERSONNAME,
 	NODE_PHRASE,
 	NODE_PREFACE,
 	NODE_PRIMARY,
Index: docbook2mdoc.c
===================================================================
RCS file: /home/cvs/mdocml/docbook2mdoc/docbook2mdoc.c,v
retrieving revision 1.64
retrieving revision 1.65
diff -Ldocbook2mdoc.c -Ldocbook2mdoc.c -u -p -r1.64 -r1.65
--- docbook2mdoc.c
+++ docbook2mdoc.c
@@ -117,6 +117,7 @@ static	const struct node nodes[] = {
 	{ "copyright",		NODE_COPYRIGHT },
 	{ "date",		NODE_DATE },
 	{ "editor",		NODE_EDITOR },
+	{ "email",		NODE_EMAIL },
 	{ "emphasis",		NODE_EMPHASIS },
 	{ "entry",		NODE_ENTRY },
 	{ "envar",		NODE_ENVAR },
@@ -167,6 +168,7 @@ static	const struct node nodes[] = {
 	{ "paramdef",		NODE_PARAMDEF },
 	{ "parameter",		NODE_PARAMETER },
 	{ "part",		NODE_SECTION },
+	{ "personname",		NODE_PERSONNAME },
 	{ "phrase",		NODE_PHRASE },
 	{ "preface",		NODE_PREFACE },
 	{ "primary",		NODE_PRIMARY },
@@ -1317,6 +1319,10 @@ pnode_print(struct parse *p, struct pnod
 		pnode_printmopen(p);
 		fputs("An", stdout);
 		break;
+	case NODE_EMAIL:
+		pnode_printmopen(p);
+		fputs("Aq Mt", stdout);
+		break;
 	case NODE_EMPHASIS:
 	case NODE_FIRSTTERM:
 		pnode_printmopen(p);
@@ -1600,6 +1606,7 @@ pnode_print(struct parse *p, struct pnod
 	case NODE_COMMAND:
 	case NODE_CONSTANT:
 	case NODE_EDITOR:
+	case NODE_EMAIL:
 	case NODE_EMPHASIS:
 	case NODE_ENVAR:
 	case NODE_FILENAME:
--
 To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv