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