Re: [PATCH docbook2mdoc] Add NODE_CONTRIB, NODE_PRODUCTNAME

[Ingo Schwarze <schwarze@usta.de>]

Hi Stephen,

Stephen Gregoratto wrote on Wed, Mar 27, 2019 at 02:52:24PM +1100:

> Here are some nodes I found in the wild.

Thank you for the information about the two nodes.  I wasn't aware
of them yet and have added the information to my TODO list.

Regarding the patch, you are no longer up to date.  ;-)

Unless you want to make at least one explicit formatting decision
based on the presence of an element, adding it to "node.h" is no
longer required.  Elements can now be explicitly ignored, in the
sense that they generate no node and that their content appears in
their stead as children of their parent, with a line like

  { "productname", NODE_IGNORE },

in parse.c, elements[].

Yes, i know that "nohe.h" still contains enum constants for various
nodes that are correctly not doing any formatting.  I tend to remove
those that are unlikely to ever require formatting, but i tend to
keep those that are likely to require some handling when the program
becomes better in the future.  But for new nodes, i only add them
when i start actually using them for formatting purposes.

Regarding the additions to parse.c, even those are no longer needed.
Elements with unknown names are now automatically ignored (in the
above sense), except that they emit a warning with -W.  So, a
NODE_IGNORE line in parse.c as shown above is only needed to suppress
the warning, which may be useful in two cases: (1) if it is unlikely
that the element will ever need formatting (examples: <acronym>,
<phrase>, <trademark>) or (2) if the element occurs so frequently
that the warnings would be too noisy, making it hard to find warnings
that actually matter (no examples currently).  It seems to me neither
applies here.

> Technically <productname> is used to markup text as 
> copyright/trademark/registered,

In that capacity, NODE_IGNORE is probably right, like for <acronym>.

> but the Systemd and GTK manuals use it to set the "source" argument
> of TH in man(7).  We have no need for it.

So in that capacity, it would be NODE_DELETE.

However, each element name can only have one enum constant attached
to it.  If requirements conflict depending on context, like in this
case, one could make it NODE_PRODUCTNAME and then explicitly treat
it as transparent in normal text (which needs no explicit code at
all, nodes are transparent by default) and skip it in other contexts
(which does need explicit code).  But i'd prefer adding the
NODE_PRODUCTNAME enum constant when the skipping code is implemented,
not earlier: we are not really sure yet such skipping code will
ever be needed, or are we?

> <contrib> is a bit odd case. It classifies an <author>'s contributions 
> to the program/manual/code etc. Here's an example from GTK:
> 
>   <authorgroup>
>     <author>
>       <contrib>Developer</contrib>
>       <firstname>Matthias</firstname>
>       <surname>Clasen</surname>
>     </author>
>   </authorgroup>

Right, handling <author> properly is a challenge that is on my TODO
list.  There are three things to do that i'm aware of: (1) in normal
text, stop skipping children like <affiliation>; (2) below
<refentryinfo>, <articleinfo>, <bookinfo> and the like, move the
information down to the AUTHORS section (a slightly tricky task);
(3) handle <contrib>.

Currently (and dto. with your patch), the above example is formatted as:

  .An Developer Matthias Clasen

Instead, it should be:

  Developer:
  .An Matthias Clasen

That's somewhat tricky (but still straightforward enough to implement
with the recent improvements in the codebase) because NODE_AUTHOR
has to print a NODE_CONTRIB child *before* calling macro_open("An").
It is sufficient to add the NODE_CONTRIB enum constant when that
is implemented.

> I'm setting it to be skipped for now, but if we ever start recording
> <author>s we could probably include this.

Err, right now, <author> elements *are* handled, and <contrib> -
with or without your patch - is *ignored* (in the sense explained
above), not *skipped*; see <anchor> and <indexterm> as examples of
elements that are skipped (more formally, "deleted").

Yours,
  Ingo
--
 To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv