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().
CVSweb