From: Ingo Schwarze <schwarze@usta.de>
To: Stephen Gregoratto <dev@sgregoratto.me>
Cc: tech@mandoc.bsd.lv
Subject: Re: [PATCH docbook2mdoc] Update README
Date: Sat, 6 Apr 2019 15:37:04 +0200 [thread overview]
Message-ID: <20190406133704.GA31475@athene.usta.de> (raw)
In-Reply-To: <20190406094424.f2zz5tzr5mkq6xsa@BlackBox>
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
prev parent reply other threads:[~2019-04-06 13:37 UTC|newest]
Thread overview: 2+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-04-06 9:44 Stephen Gregoratto
2019-04-06 13:37 ` Ingo Schwarze [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20190406133704.GA31475@athene.usta.de \
--to=schwarze@usta.de \
--cc=dev@sgregoratto.me \
--cc=tech@mandoc.bsd.lv \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).