[PATCH docbook2mdoc] Update README

[PATCH docbook2mdoc] Update README

[Stephen Gregoratto]

The README still references moved/removed/renamed files/structures. This 
simple patch updates the steps.

Index: README
===================================================================
RCS file: /cvs/docbook2mdoc/README,v
retrieving revision 1.3
diff -u -p -r1.3 README
--- README	22 Mar 2019 15:38:09 -0000	1.3
+++ README	6 Apr 2019 09:43:58 -0000
@@ -12,11 +12,12 @@ For these, you will have to look at 4.5 
 
  https://tdg.docbook.org/tdg/4.5/foo.html
 
-Add the alpha-ordered node (NODE_FOO) to extern.h.
+Add the alpha-ordered node (NODE_FOO) to node.h.
 
-Next, add the name and whether it admits text to docbook2mdoc.c's
-"nodes" structure array.
+Next, add the node and whether it admits text to parse.c's
+"elements" structure array.
 
-Finally, modify pnode_print() with your new entry.  Use similar nodes as
-a reference.  (NOTE: if it's an inline like, say, NODE_EMPHASIS, then
-remember to add the node to the postfix switch statement!)
+Finally, modify docbook2mdoc.c's pnode_print() with your new entry.
+Use similar nodes as a reference.
+If it's an inline like, say, NODE_EMPHASIS, then remember to add the
+node to the postfix switch statement!
--
 To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv

Re: [PATCH docbook2mdoc] Update README

[Ingo Schwarze]

Hi Stephen,

Stephen Gregoratto wrote on Sat, Apr 06, 2019 at 08:44:24PM +1100:

> The README still references moved/removed/renamed files/structures.

You are correct, it was outdated.

> This simple patch updates the steps.

Your patch was correct, but i chose to explain the topic in a more
detailed way, see the commit below.

Yours,
  Ingo


Log Message:
-----------
update the instructions for adding elements; triggered by
a smaller patch from Stephen Gregoratto <dev at sgregoratto dot me>

Modified Files:
--------------
    docbook2mdoc:
        README

Revision Data
-------------
Index: README
===================================================================
RCS file: /home/cvs/mdocml/docbook2mdoc/README,v
retrieving revision 1.3
retrieving revision 1.4
diff -LREADME -LREADME -u -p -r1.3 -r1.4
--- README
+++ README
@@ -12,11 +12,81 @@ For these, you will have to look at 4.5 
 
  https://tdg.docbook.org/tdg/4.5/foo.html
 
-Add the alpha-ordered node (NODE_FOO) to extern.h.
 
-Next, add the name and whether it admits text to docbook2mdoc.c's
-"nodes" structure array.
+Add one "struct element" initializer to the elements[] array in the
+file parse.c, containing the name of element as it appears in DocBook
+documents and the "enum nodeid" constant of the node to be generated.
+There are several special cases:
 
-Finally, modify pnode_print() with your new entry.  Use similar nodes as
-a reference.  (NOTE: if it's an inline like, say, NODE_EMPHASIS, then
-remember to add the node to the postfix switch statement!)
+ * If docbook2mdoc(1) never needs to produce any output for the
+   element nor from any children it may have, specify NODE_DELETE.
+   If, in addition, finding the element in an input document implies
+   that the output from the document will likely be incomplete or
+   otherwise significantly unsatisfactory, use NODE_DELETE_WARN
+   instead.
+
+ * If docbook2mdoc(1) can treat the element as transparent, that
+   is, if removing the element and inserting its content in its
+   place would not change the desired formatting, specify NODE_IGNORE.
+   This does not exclude that in DocBook itself, syntactic requirements
+   or semantic significance may be attached to the element.
+
+ * If docbook2mdoc(1) can handle the element in exactly the same way
+   as another node that is already handled, reuse the "enum nodeid"
+   constant for the node that is already handled.  This only requires
+   identitical handling by docbook2mdoc(1), even when syntax or
+   semantics differ in DocBook itself.  For example:
+	{ "chapter",		NODE_SECTION },
+	{ "part",		NODE_SECTION },
+	{ "refsect1",		NODE_SECTION },
+	{ "refsect2",		NODE_SECTION },
+	/* ... */
+	{ "section",		NODE_SECTION },
+
+ * Otherwise - that is, when the formatter needs to make at least
+   one explicit formatting decision based on the presence, absence,
+   or content of the element - add an enum constant for the new
+   node to the declaration of "enum nodeid" in the file node.h.
+   Preserve the alphabetic ordering.
+   Add such a constant if only if the code will use it at least at
+   one place in addition to the definition of the elements[] array.
+
+
+In the latter case, implement formatting in the file docbook2mdoc.c.
+Decide how the new node needs to be handled in the first, bigger
+switch statement of the function pnode_print().  Typical cases
+include:
+
+ * Nodes to be represented by in-line macros that are parsed and
+   callable often get away with merely opening a macro scope
+   with macro_open(), letting the subsequent loop take care of
+   any children.  In this case, the second, smaller switch
+   statement often needs to call macro_closepunct() to handle
+   closing delimiters.
+
+ * Nodes to be represented by one single stand-alone macro sometimes
+   get away with calling macro_line(), or macro_nodeline() if an
+   argument is required.
+
+ * Nodes with complex formatting requirements call their own,
+   dedicated pnode_print*() formatting functions.
+   These functions are ordered roughly as follows:
+    1. paragraphs
+    2. sections
+    3. functions and mathematics
+    4. semantic markup for command line utilities
+    5. various semantic markup
+    6. structural markup like lists and tables
+   Such functions often contain their own loops over children and
+   remove the children with pnode_unlinksub() at the end.  But in
+   some cases, it is alternatively possible to let the common loop
+   in the middle of pnode_print() handle the children.
+
+
+Always keep the distinction between the two main ways to handle
+children in mind: by default and by the common loop in the middle
+of pnode_print(), children are formatted recursively with pnode_print(),
+potentially resulting in complex, nested formatting.  By contrast,
+children can be reduced to just one string containing their their
+bare text content, ignoring any further markup that may be contained
+inside, by calling macro_addnode(), macro_nodeline(), or print_textnode().
--
 To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv