[RFC,00/12] doc: add tests and reimplement xmlto

Message

Felipe Contreras April 13, 2023, 11:57 a.m. UTC

It's never clear what a single change does in the myriad of
{asciidoc.py,asciidoctor}{docbook45,docbook5,manpage} tools, not to mention
xmlto and docbook-xsl.

So I decided to create a very simple test to generate a manpage in different
tools, and the result is that nothing works correctly.

Once the test was running correctly I decided to investigate why xmlto wasn't
able to verify docbook5 documents, and it turns out it's just not supported,
and neither it is in xmllint.

While doing so I realized xmlto doesn't do anything for us, so I wrote a simple
script that does the same thing.

Moving all the old hacks to this gen-stylesheet script, I realized a hack from
2006 is not necessary anymore, and DocBook Stylesheets already generate much
better output.

Getting rid of this generates nice aligment for callouts:

     $ git diff            (1)
     $ git diff --cached   (2)
     $ git diff HEAD       (3)

  1. Changes in the working tree not yet staged for the next
     commit.
  2. Changes between the index and your last commit; what you
     would be committing if you run git commit without -a
     option.
  3. Changes in the working tree since your last commit; what
     you would be committing if you run git commit -a

There's a lot of changes not explored in detail, so this is only an RFC but I
think it's clear something like this is the direction to go.

Felipe Contreras (12):
  doc: add test for doc tools output
  doc: add missing manpage docinfo
  doc: remove unnecessary hack for asciidoctor
  test: doc: add test for docbook5
  doc: fix support for multiple docbook backends
  doc: add gen-stylesheet helper
  doc: get rid of xmlto dependency
  test: doc: use temporary stylesheet
  doc: remove references to xmlto
  doc: stylesheet: move all the xslt templates
  test: doc: add check for callouts
  doc: manpage: remove callout hack

 Documentation/.gitignore               |   1 +
 Documentation/Makefile                 |  19 ++--
 Documentation/asciidoc.conf            |  15 +--
 Documentation/gen-stylesheet           |  28 +++++
 Documentation/manpage-bold-literal.xsl |  16 ---
 Documentation/manpage-normal.xsl       |  26 -----
 Documentation/manpage.xsl              |   3 -
 INSTALL                                |   4 +-
 ci/install-dependencies.sh             |   2 +-
 shared.mak                             |   3 +-
 t/t0600-doc-tools.sh                   | 135 +++++++++++++++++++++++++
 11 files changed, 184 insertions(+), 68 deletions(-)
 create mode 100755 Documentation/gen-stylesheet
 delete mode 100644 Documentation/manpage-bold-literal.xsl
 delete mode 100644 Documentation/manpage-normal.xsl
 delete mode 100644 Documentation/manpage.xsl
 create mode 100755 t/t0600-doc-tools.sh