From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from scc-mailout-kit-01.scc.kit.edu (scc-mailout-kit-01.scc.kit.edu [129.13.231.81]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTP id 5d35c208 for ; Sat, 6 Apr 2019 08:37:08 -0500 (EST) Received: from asta-nat.asta.uni-karlsruhe.de ([172.22.63.82] helo=hekate.usta.de) by scc-mailout-kit-01.scc.kit.edu with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (envelope-from ) id 1hClVK-00005M-JH; Sat, 06 Apr 2019 15:37:08 +0200 Received: from donnerwolke.usta.de ([172.24.96.3]) by hekate.usta.de with esmtp (Exim 4.77) (envelope-from ) id 1hClVJ-0004gx-5o; Sat, 06 Apr 2019 15:37:05 +0200 Received: from athene.usta.de ([172.24.96.10]) by donnerwolke.usta.de with esmtp (Exim 4.84_2) (envelope-from ) id 1hClVJ-0005PY-1Q; Sat, 06 Apr 2019 15:37:05 +0200 Received: from localhost (athene.usta.de [local]) by athene.usta.de (OpenSMTPD) with ESMTPA id 24dcd967; Sat, 6 Apr 2019 15:37:05 +0200 (CEST) Date: Sat, 6 Apr 2019 15:37:04 +0200 From: Ingo Schwarze To: Stephen Gregoratto Cc: tech@mandoc.bsd.lv Subject: Re: [PATCH docbook2mdoc] Update README Message-ID: <20190406133704.GA31475@athene.usta.de> References: <20190406094424.f2zz5tzr5mkq6xsa@BlackBox> X-Mailinglist: mandoc-tech Reply-To: tech@mandoc.bsd.lv MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20190406094424.f2zz5tzr5mkq6xsa@BlackBox> User-Agent: Mutt/1.8.0 (2017-02-23) 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 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