Return to README CVS log

Up to [cvsweb.bsd.lv] / docbook2mdoc

Annotation of docbook2mdoc/README, Revision 1.4

1.4     ! schwarze    1: $Id: README,v 1.3 2019/03/22 15:38:09 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.4     ! schwarze   16: Add one "struct element" initializer to the elements[] array in the
        !            17: file parse.c, containing the name of element as it appears in DocBook
        !            18: documents and the "enum nodeid" constant of the node to be generated.
        !            19: There are several special cases:
        !            20:
        !            21:  * If docbook2mdoc(1) never needs to produce any output for the
        !            22:    element nor from any children it may have, specify NODE_DELETE.
        !            23:    If, in addition, finding the element in an input document implies
        !            24:    that the output from the document will likely be incomplete or
        !            25:    otherwise significantly unsatisfactory, use NODE_DELETE_WARN
        !            26:    instead.
        !            27:
        !            28:  * If docbook2mdoc(1) can treat the element as transparent, that
        !            29:    is, if removing the element and inserting its content in its
        !            30:    place would not change the desired formatting, specify NODE_IGNORE.
        !            31:    This does not exclude that in DocBook itself, syntactic requirements
        !            32:    or semantic significance may be attached to the element.
        !            33:
        !            34:  * If docbook2mdoc(1) can handle the element in exactly the same way
        !            35:    as another node that is already handled, reuse the "enum nodeid"
        !            36:    constant for the node that is already handled.  This only requires
        !            37:    identitical handling by docbook2mdoc(1), even when syntax or
        !            38:    semantics differ in DocBook itself.  For example:
        !            39:        { "chapter",            NODE_SECTION },
        !            40:        { "part",               NODE_SECTION },
        !            41:        { "refsect1",           NODE_SECTION },
        !            42:        { "refsect2",           NODE_SECTION },
        !            43:        /* ... */
        !            44:        { "section",            NODE_SECTION },
        !            45:
        !            46:  * Otherwise - that is, when the formatter needs to make at least
        !            47:    one explicit formatting decision based on the presence, absence,
        !            48:    or content of the element - add an enum constant for the new
        !            49:    node to the declaration of "enum nodeid" in the file node.h.
        !            50:    Preserve the alphabetic ordering.
        !            51:    Add such a constant if only if the code will use it at least at
        !            52:    one place in addition to the definition of the elements[] array.
        !            53:
        !            54:
        !            55: In the latter case, implement formatting in the file docbook2mdoc.c.
        !            56: Decide how the new node needs to be handled in the first, bigger
        !            57: switch statement of the function pnode_print().  Typical cases
        !            58: include:
        !            59:
        !            60:  * Nodes to be represented by in-line macros that are parsed and
        !            61:    callable often get away with merely opening a macro scope
        !            62:    with macro_open(), letting the subsequent loop take care of
        !            63:    any children.  In this case, the second, smaller switch
        !            64:    statement often needs to call macro_closepunct() to handle
        !            65:    closing delimiters.
        !            66:
        !            67:  * Nodes to be represented by one single stand-alone macro sometimes
        !            68:    get away with calling macro_line(), or macro_nodeline() if an
        !            69:    argument is required.
        !            70:
        !            71:  * Nodes with complex formatting requirements call their own,
        !            72:    dedicated pnode_print*() formatting functions.
        !            73:    These functions are ordered roughly as follows:
        !            74:     1. paragraphs
        !            75:     2. sections
        !            76:     3. functions and mathematics
        !            77:     4. semantic markup for command line utilities
        !            78:     5. various semantic markup
        !            79:     6. structural markup like lists and tables
        !            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().