From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from localhost (fantadrom.bsd.lv [local]) by fantadrom.bsd.lv (OpenSMTPD) with ESMTPA id 8dace753 for ; Sat, 6 Apr 2019 08:30:51 -0500 (EST) Date: Sat, 6 Apr 2019 08:30:51 -0500 (EST) X-Mailinglist: mandoc-source Reply-To: source@mandoc.bsd.lv MIME-Version: 1.0 From: schwarze@mandoc.bsd.lv To: source@mandoc.bsd.lv Subject: docbook2mdoc: update the instructions for adding elements; triggered by X-Mailer: activitymail 1.26, http://search.cpan.org/dist/activitymail/ Content-Type: text/plain; charset=utf-8 Message-ID: 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 source+unsubscribe@mandoc.bsd.lv