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

Diff for /docbook2mdoc/README between version 1.3 and 1.4

version 1.3, 2019/03/22 15:38:09 version 1.4, 2019/04/06 13:30:21
Line 12  For these, you will have to look at 4.5 documentation 
Line 12  For these, you will have to look at 4.5 documentation 
   
  https://tdg.docbook.org/tdg/4.5/foo.html   https://tdg.docbook.org/tdg/4.5/foo.html
   
 Add the alpha-ordered node (NODE_FOO) to extern.h.  
   
 Next, add the name and whether it admits text to docbook2mdoc.c's  Add one "struct element" initializer to the elements[] array in the
 "nodes" structure array.  file parse.c, containing the name of element as it appears in DocBook
   documents and the "enum nodeid" constant of the node to be generated.
   There are several special cases:
   
 Finally, modify pnode_print() with your new entry.  Use similar nodes as   * If docbook2mdoc(1) never needs to produce any output for the
 a reference.  (NOTE: if it's an inline like, say, NODE_EMPHASIS, then     element nor from any children it may have, specify NODE_DELETE.
 remember to add the node to the postfix switch statement!)     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.
      Preserve the alphabetic ordering.
      Add such a constant if only if the code will use it at least at
      one place in addition to the definition of the elements[] array.
   
   
   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.  In this case, the second, smaller switch
      statement often needs to call macro_closepunct() to handle
      closing delimiters.
   
    * 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.
      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. 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().

Legend:
Removed from v.1.3  
changed lines
  Added in v.1.4

CVSweb