Skip to content
  • brian m. carlson's avatar
    Documentation: add XSLT to fix DocBook for Texinfo · 95e5efc6
    brian m. carlson authored and Junio C Hamano's avatar Junio C Hamano committed
    
    
    There are two ways to create a section in a reference document (i.e.,
    manpage) in DocBook 4: refsection elements and refsect, refsect2, and
    refsect3 elements.  Either form is acceptable as of DocBook 4.2, but
    they cannot be mixed.  Prior to DocBook 4.2, only the numbered forms
    were acceptable.
    
    docbook2texi only accepts the numbered forms, and this has not generally
    been a problem, since AsciiDoc produces the numbered forms.
    Asciidoctor, on the other hand, uses a shared backend for DocBook 4 and
    5, and uses the unnumbered refsection elements instead.
    
    If we don't convert the unnumbered form to the numbered form,
    docbook2texi omits section headings, which is undesirable.  Add an XSLT
    stylesheet to transform the unnumbered forms to the numbered forms
    automatically, and preprocess the DocBook XML as part of the
    transformation to Texinfo format.
    
    Note that this transformation is only necessary for Texinfo, since
    docbook2texi provides its own stylesheets.  The DocBook stylesheets,
    which we use for other formats, provide the full range of DocBook 4 and
    5 compatibility, and don't have this issue.
    
    Signed-off-by: default avatarbrian m. carlson <sandals@crustytoothpaste.net>
    Signed-off-by: default avatarJunio C Hamano <gitster@pobox.com>
    95e5efc6