On Sat, Sep 07, 2019 at 05:07:46PM +0000, brian m. carlson wrote:
> Our documentation toolchain has traditionally been built around DocBook
> 4.5. This version of DocBook is the last DTD-based version of DocBook.
> In 2009, DocBook 5 was introduced using namespaces and its syntax is
> expressed in RELAX-NG, which is more expressive and allows a wider
> variety of syntax forms.
Wow, this patch turned out to be much simpler than I had feared. And the
explanation turned out to be much longer and more interesting than I
expected. :) Thanks for writing it all down.
The patch worked well for me.
> Fortunately, there's an easy way forward: ask Asciidoctor to use its
> DocBook 5 backend and tell xmlto to skip validation. Asciidoctor has
> supported DocBook 5 since v0.1.4 in 2013 and xmlto has supported
> skipping validation for probably longer than that.
>
> xmlto will still use the non-namespaced DocBook XSL stylesheets (which
> are designed for DocBook 4.5) for building the documentation instead of
> the namespaced ones (which are designed for DocBook 5). This isn't
> really a problem, since both forms are built from the same source and
> can handle both versions, but it does mean that an ugly message about
> the stylesheets stripping the namespace will be printed to standard
> error.
So I think this does introduce the ugly namespace message even for
people who are using older versions of asciidoctor that understand
docbook45. But it's probably sensible to keep all of our asciidoctor
builds using the same technique. We have enough trouble tracking the
minor differences between the variants as it is.
> The differences in output between AsciiDoc 8.6.10 on master and
> Asciidoctor 2.0.10 with this patch are, with one exception, all due to
> whitespace, wrapping, or quoting and do not affect substantive content.
We know already there are a lot of differences between asciidoc and
asciidoctor here. What's more interesting to me is how it changes the
output between two versions of asciidoctor. Of course we can't check for
2.0.10, because it doesn't build at all. But I did do a "doc-diff"
with and without this patch using 1.5.5. There are quite a few
whitespace changes. Some of them seem good or at least neutral, like:
---
a/745f6812895b31c02b29bdfe4ae8e5498f776c26-asciidoctor/home/peff/share/man/man1/git-add.1
+++
b/303729d86b69657777222bf4b3a6f95932e12648-asciidoctor/home/peff/share/man/man1/git-add.1
[...]
@@ -43,6 +43,7 @@ DESCRIPTION
OPTIONS
<pathspec>...
+
Files to add content from. Fileglobs (e.g. *.c) can be given to
add all matching files. Also a leading directory name (e.g. dir
to
add dir/file1 and dir/file2) can be given to update the index to
Some of them seem bad, though:
---
a/745f6812895b31c02b29bdfe4ae8e5498f776c26-asciidoctor/home/peff/share/man/man1/git-am.1
+++
b/303729d86b69657777222bf4b3a6f95932e12648-asciidoctor/home/peff/share/man/man1/git-am.1
[...]
@@ -175,10 +201,10 @@ DISCUSSION
to process. Upon seeing the first patch that does not apply, it aborts
in the middle. You can recover from this in one of two ways:
- 1. skip the current patch by re-running the command with the --skip
+ 1. skip the current patch by re-running the command with the --skip
option.
- 2. hand resolve the conflict in the working directory, and update the
+ 2. hand resolve the conflict in the working directory, and update
the
index file to bring it into a state that the patch should have
produced. Then run the command with the --continue option.
I tricked doc-diff into doing a comparison against 1.5.5 without the
patch and 2.0.10 with the patch, and the diff is similar.
-Peff
