$Id: README,v 1.7 2019/04/14 12:38:33 schwarze Exp $ Here's a quick note on how to add new DocBook elements. First, look up the element in the DocBook reference. For element , this is usually: https://tdg.docbook.org/tdg/5.1/foo.html Some elements are no longer defined in DocBook 5. For these, you will have to look at 4.5 documentation instead: https://tdg.docbook.org/tdg/4.5/foo.html Add one "struct alias" initializer to the aliases[] array in the file parse.c *or* one "struct nodeprop" initializer to the properties[] array in the file node.c, but not both. The first struct member is the name of the element as it appears in DocBook documents. There are several special cases: * 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. Use properties[] in node.c and preserve the alphabetic ordering. Add such a constant if only if the code will use it at least at one place. 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. * 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. For historical reasons, 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. prologue and top level structures 7. 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().