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

Annotation of docbook2mdoc/README, Revision 1.7

1.7     ! schwarze    1: $Id: README,v 1.6 2019/04/12 16:40:53 schwarze Exp $
1.1       kristaps    2:
                      3: Here's a quick note on how to add new DocBook elements.
                      4:
1.2       schwarze    5: First, look up the element in the DocBook reference.
                      6: For element <foo>, this is usually:
1.1       kristaps    7:
1.2       schwarze    8:  https://tdg.docbook.org/tdg/5.1/foo.html
                      9:
                     10: Some elements are no longer defined in DocBook 5.
                     11: For these, you will have to look at 4.5 documentation instead:
                     12:
                     13:  https://tdg.docbook.org/tdg/4.5/foo.html
1.1       kristaps   14:
                     15:
1.6       schwarze   16: Add one "struct alias" initializer to the aliases[] array in the
                     17: file parse.c *or* one "struct nodeprop" initializer to the properties[]
                     18: array in the file node.c, but not both.  The first struct member is
                     19: the name of the element as it appears in DocBook documents.
1.4       schwarze   20: There are several special cases:
                     21:
                     22:  * If docbook2mdoc(1) never needs to produce any output for the
                     23:    element nor from any children it may have, specify NODE_DELETE.
                     24:    If, in addition, finding the element in an input document implies
                     25:    that the output from the document will likely be incomplete or
                     26:    otherwise significantly unsatisfactory, use NODE_DELETE_WARN
                     27:    instead.
                     28:
                     29:  * If docbook2mdoc(1) can treat the element as transparent, that
                     30:    is, if removing the element and inserting its content in its
                     31:    place would not change the desired formatting, specify NODE_IGNORE.
                     32:    This does not exclude that in DocBook itself, syntactic requirements
                     33:    or semantic significance may be attached to the element.
                     34:
                     35:  * If docbook2mdoc(1) can handle the element in exactly the same way
                     36:    as another node that is already handled, reuse the "enum nodeid"
                     37:    constant for the node that is already handled.  This only requires
                     38:    identitical handling by docbook2mdoc(1), even when syntax or
                     39:    semantics differ in DocBook itself.  For example:
                     40:        { "chapter",            NODE_SECTION },
                     41:        { "part",               NODE_SECTION },
                     42:        { "refsect1",           NODE_SECTION },
                     43:        { "refsect2",           NODE_SECTION },
                     44:        /* ... */
                     45:        { "section",            NODE_SECTION },
                     46:
                     47:  * Otherwise - that is, when the formatter needs to make at least
                     48:    one explicit formatting decision based on the presence, absence,
                     49:    or content of the element - add an enum constant for the new
                     50:    node to the declaration of "enum nodeid" in the file node.h.
1.6       schwarze   51:    Use properties[] in node.c and preserve the alphabetic ordering.
1.4       schwarze   52:    Add such a constant if only if the code will use it at least at
1.6       schwarze   53:    one place.
1.4       schwarze   54:
                     55:
                     56: In the latter case, implement formatting in the file docbook2mdoc.c.
                     57: Decide how the new node needs to be handled in the first, bigger
                     58: switch statement of the function pnode_print().  Typical cases
                     59: include:
                     60:
                     61:  * Nodes to be represented by in-line macros that are parsed and
                     62:    callable often get away with merely opening a macro scope
                     63:    with macro_open(), letting the subsequent loop take care of
1.5       schwarze   64:    any children.
1.4       schwarze   65:
                     66:  * Nodes to be represented by one single stand-alone macro sometimes
                     67:    get away with calling macro_line(), or macro_nodeline() if an
                     68:    argument is required.
                     69:
                     70:  * Nodes with complex formatting requirements call their own,
                     71:    dedicated pnode_print*() formatting functions.
1.7     ! schwarze   72:    For historical reasons, these functions are ordered roughly as follows:
1.4       schwarze   73:     1. paragraphs
                     74:     2. sections
                     75:     3. functions and mathematics
                     76:     4. semantic markup for command line utilities
                     77:     5. various semantic markup
1.7     ! schwarze   78:     6. prologue and top level structures
        !            79:     7. structural markup like lists and tables
1.4       schwarze   80:    Such functions often contain their own loops over children and
                     81:    remove the children with pnode_unlinksub() at the end.  But in
                     82:    some cases, it is alternatively possible to let the common loop
                     83:    in the middle of pnode_print() handle the children.
                     84:
                     85:
                     86: Always keep the distinction between the two main ways to handle
                     87: children in mind: by default and by the common loop in the middle
                     88: of pnode_print(), children are formatted recursively with pnode_print(),
                     89: potentially resulting in complex, nested formatting.  By contrast,
                     90: children can be reduced to just one string containing their their
                     91: bare text content, ignoring any further markup that may be contained
                     92: inside, by calling macro_addnode(), macro_nodeline(), or print_textnode().

CVSweb