[BACK]Return to README CVS log [TXT][DIR] Up to [cvsweb.bsd.lv] / docbook2mdoc

File: [cvsweb.bsd.lv] / docbook2mdoc / README (download)

Revision 1.7, Sun Apr 14 12:38:33 2019 UTC (13 months, 1 week ago) by schwarze
Branch: MAIN
CVS Tags: VERSION_1_1_0, VERSION_1_0_2, VERSION_1_0_1, VERSION_1_0_0, HEAD
Changes since 1.6: +4 -3 lines

Move content from <bookinfo>, <articleinfo>, <refentryinfo>, and <refmeta>
that is not used in the prologue to the AUTHORS section.

$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 <foo>, 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().