From: Junio C Hamano <gitster@pobox.com>
To: Jeff King <peff@peff.net>
Cc: "brian m. carlson" <sandals@crustytoothpaste.net>,
git@vger.kernel.org, "Martin Ågren" <martin.agren@gmail.com>
Subject: Re: [PATCH v2] Documentation: fix build with Asciidoctor 2
Date: Fri, 13 Sep 2019 10:06:33 -0700 [thread overview]
Message-ID: <xmqq1rwkf7mu.fsf@gitster-ct.c.googlers.com> (raw)
In-Reply-To: <20190913050634.GB21172@sigill.intra.peff.net> (Jeff King's message of "Fri, 13 Sep 2019 01:06:35 -0400")
Jeff King <peff@peff.net> writes:
> On Fri, Sep 13, 2019 at 01:52:40AM +0000, brian m. carlson wrote:
>
>> We also need to teach xmlto how to use the namespaced DocBook XSLT
>> stylesheets instead of the non-namespaced ones it usually uses.
>> Normally these stylesheets are interchangeable, but the non-namespaced
>> ones have a bug that causes them not to strip whitespace automatically
>> from certain elements when namespaces are in use. This results in
>> additional whitespace at the beginning of list elements, which is
>> jarring and unsightly.
>
> Thanks, this fixed most of the rendering problems I saw from the earlier
> patch.
>
>> We can do this by passing a custom stylesheet with the -x option that
>> simply imports the namespaced stylesheets via a URL. Any system with
>> support for XML catalogs will automatically look this URL up and
>> reference a local copy instead without us having to know where this
>> local copy is located. We know that anyone using xmlto will already
>> have catalogs set up properly since the DocBook 4.5 DTD used during
>> validation is also looked up via catalogs. All major Linux
>> distributions distribute the necessary stylesheets and have built-in
>> catalog support, and Homebrew does as well, albeit with a requirement to
>> set an environment variable to enable catalog support.
>
> This did give me one minor hiccup: I had the debian docbook-xsl package
> installed, but not docbook-xsl-ns. The error message was pretty standard
> for XML: obvious if you know what catalogs are, and utterly confusing
> otherwise. :)
>
> Everything worked fine after installing docbook-xsl-ns. I wonder if
> could/should provide some guidance somewhere (maybe in INSTALL, which
> discusses some catalog issues?).
>
>> Finally, we need to filter out some messages from other stylesheets that
>> when invoking dblatex in the CI job. This tool strips namespaces much
>
> s/that/that occur/ or something?
>
>> like the unnamespaced DocBook stylesheets and prints similar messages.
>> If we permit these messages to be printed to standard error, our
>> documentation CI job will because we check standard error for unexpected
>
> s/will/will fail/?
>
>> ---
>> Documentation/Makefile | 4 +++-
>> Documentation/manpage.xsl | 3 +++
>> ci/test-documentation.sh | 2 ++
>> 3 files changed, 8 insertions(+), 1 deletion(-)
>> create mode 100644 Documentation/manpage.xsl
>
> Running with this patch on asciidoctor 2.0.10, plus Martin's recent
> literal-block cleanups, plus his refmiscinfo fix, I get pretty decent
> output from:
>
> ./doc-diff --from-asciidoc --to-asciidoctor origin HEAD
>
> The header/footer are still a little funny (but I think Martin said that
> he needs to update the refmiscinfo patches for later versions of
> asciidoctor, which is probably what's going on here):
> ...
> So overall, I think we're getting very close to parity.
Thanks, both. Have queued with your log message typofixes.
next prev parent reply other threads:[~2019-09-13 17:06 UTC|newest]
Thread overview: 71+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-03-17 14:47 [PATCH] asciidoctor-extensions: provide `<refmiscinfo/>` Martin Ågren
2019-03-17 19:44 ` Todd Zullinger
2019-03-17 20:03 ` Martin Ågren
2019-03-19 7:02 ` Martin Ågren
2019-03-20 18:17 ` Todd Zullinger
2019-03-22 21:01 ` Martin Ågren
2019-03-23 19:27 ` Todd Zullinger
2019-03-24 12:16 ` Jeff King
2019-03-24 16:21 ` Todd Zullinger
2019-03-25 15:06 ` Jeff King
2019-03-25 19:00 ` Todd Zullinger
2019-03-27 1:06 ` Todd Zullinger
2019-03-27 10:05 ` SZEDER Gábor
2019-03-28 0:06 ` brian m. carlson
2019-03-30 18:00 ` Todd Zullinger
2019-03-30 21:04 ` brian m. carlson
2019-04-05 2:17 ` Todd Zullinger
2019-04-05 18:46 ` Jeff King
2019-03-28 2:54 ` Jeff King
2019-03-28 3:33 ` Jeff King
2019-03-19 2:46 ` Jeff King
2019-03-19 2:59 ` Jeff King
2019-03-19 3:55 ` Junio C Hamano
2019-03-19 7:33 ` Martin Ågren
2019-03-19 7:36 ` Martin Ågren
2019-09-03 18:51 ` [PATCH v2 0/2] " Martin Ågren
2019-09-03 18:51 ` [PATCH v2 1/2] " Martin Ågren
2019-09-03 18:51 ` [PATCH v2 2/2] doc-diff: replace --cut-header-footer with --cut-footer Martin Ågren
2019-09-03 23:16 ` [PATCH v2 0/2] asciidoctor-extensions: provide `<refmiscinfo/>` brian m. carlson
2019-09-05 19:28 ` Martin Ågren
2019-09-04 3:26 ` Jeff King
2019-09-05 19:35 ` Martin Ågren
2019-09-07 6:45 ` Jeff King
2019-09-07 14:06 ` Martin Ågren
2019-09-08 21:30 ` Jeff King
2019-09-06 23:29 ` brian m. carlson
2019-09-07 4:40 ` Jeff King
2019-09-07 16:53 ` brian m. carlson
2019-09-07 17:07 ` [PATCH] Documentation: fix build with Asciidoctor 2 brian m. carlson
2019-09-08 10:48 ` Jeff King
2019-09-08 17:18 ` brian m. carlson
2019-09-08 21:21 ` Jeff King
2019-09-08 22:24 ` brian m. carlson
2019-09-09 17:37 ` Junio C Hamano
2019-09-10 18:44 ` Jeff King
2019-09-11 23:19 ` brian m. carlson
2019-09-08 14:13 ` SZEDER Gábor
2019-09-08 21:32 ` Jeff King
2019-09-13 1:52 ` [PATCH v2] " brian m. carlson
2019-09-13 5:06 ` Jeff King
2019-09-13 17:06 ` Junio C Hamano [this message]
2019-09-16 10:47 ` Martin Ågren
2019-09-16 17:43 ` Junio C Hamano
2019-09-14 7:53 ` SZEDER Gábor
2019-09-14 19:44 ` brian m. carlson
2019-09-14 19:49 ` [PATCH v3] " brian m. carlson
2019-09-15 9:59 ` SZEDER Gábor
2019-09-15 21:26 ` brian m. carlson
2019-09-15 22:05 ` SZEDER Gábor
2019-09-15 22:14 ` brian m. carlson
2019-09-16 10:51 ` Martin Ågren
2019-09-15 22:43 ` [PATCH v4] " brian m. carlson
2019-09-16 19:00 ` [PATCH v3 0/3] asciidoctor-extensions: provide `<refmiscinfo/>` Martin Ågren
2019-09-16 19:00 ` [PATCH v3 1/3] Doc/Makefile: give mansource/-version/-manual attributes Martin Ågren
2019-09-16 19:00 ` [PATCH v3 2/3] asciidoctor-extensions: provide `<refmiscinfo/>` Martin Ågren
2019-09-16 19:00 ` [PATCH v3 3/3] doc-diff: replace --cut-header-footer with --cut-footer Martin Ågren
2019-03-19 3:30 ` [PATCH] asciidoctor-extensions: provide `<refmiscinfo/>` Jeff King
2019-03-19 7:12 ` Martin Ågren
2019-03-19 7:43 ` Jeff King
2019-03-20 18:32 ` Todd Zullinger
2019-03-19 7:10 ` Martin Ågren
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=xmqq1rwkf7mu.fsf@gitster-ct.c.googlers.com \
--to=gitster@pobox.com \
--cc=git@vger.kernel.org \
--cc=martin.agren@gmail.com \
--cc=peff@peff.net \
--cc=sandals@crustytoothpaste.net \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).