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
--
2.40.0+fc1
