git.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: Jeff King <peff@peff.net>
To: "brian m. carlson" <sandals@crustytoothpaste.net>
Cc: git@vger.kernel.org, "Martin Ågren" <martin.agren@gmail.com>,
	"Junio C Hamano" <gitster@pobox.com>
Subject: Re: [PATCH v2] Documentation: fix build with Asciidoctor 2
Date: Fri, 13 Sep 2019 01:06:35 -0400	[thread overview]
Message-ID: <20190913050634.GB21172@sigill.intra.peff.net> (raw)
In-Reply-To: <20190913015240.686522-1-sandals@crustytoothpaste.net>

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):

  --- a/f1d4a28250629ae469fc5dd59ab843cb2fd68e12-asciidoc/home/peff/share/man/man1/git-add.1
  +++ b/6c08635fd1d38c83d3765ff05fabbfbd25ef4943-asciidoctor/home/peff/share/man/man1/git-add.1
  @@ -1,4 +1,4 @@
  -GIT-ADD(1)                        Git Manual                        GIT-ADD(1)
  +GIT-ADD(1)                                                          GIT-ADD(1)
   
   NAME
          git-add - Add file contents to the index
  @@ -356,4 +356,4 @@ SEE ALSO
   GIT
          Part of the git(1) suite
   
  -Git omitted                       01/01/1970                        GIT-ADD(1)
  +  omitted                         1970-01-01                        GIT-ADD(1)


One curiosity is that any ``smart-quotes'' now get two spaces between them
and the period of the last sentence (whereas in asciidoc they got only
one):

  -           <start> and <end> are optional. “-L <start>” or “-L <start>,” spans
  -           from <start> to end of file. “-L ,<end>” spans from start of file
  -           to <end>.
  +           <start> and <end> are optional.  “-L <start>” or “-L <start>,”
  +           spans from <start> to end of file.  “-L ,<end>” spans from start of
  +           file to <end>.

I don't think this is a big deal, but I think most of these should
actually be backticks these days (the text above is from
git-annotate.txt, which hasn't been touched in quite a while).

There are other miscellaneous indentation fixes. Most of them look
better in asciidoctor, IMHO. For example, some lists now wrap more
neatly (it looks like it's usually lists after an indented listing
block? Maybe a continuation thing?):

  -           1. This step and the next one could be combined into a single step
  -           with "checkout -b my2.6.14 v2.6.14".
  +            1. This step and the next one could be combined into a single
  +               step with "checkout -b my2.6.14 v2.6.14".

Another curiosity is that single-quote `smart-quotes' are rendered as
real smart-quotes by asciidoctor:

  -           The following features from ‘svn log’ are supported:
  +           The following features from “svn log” are supported:

The only other case I found was this one, where I think the asciidoctor
version is better (the source has literal backticks, so there shouldn't
be a visible quote; I'm guessing asciidoc got confused by the apostrophe
in "variable's"):

  -           The ‘merge.*.driver` variable’s value is used to construct a
  +           The merge.*.driver variable’s value is used to construct a command

So overall, I think we're getting very close to parity.

-Peff

  reply	other threads:[~2019-09-13  5: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 [this message]
2019-09-13 17:06                     ` Junio C Hamano
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

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20190913050634.GB21172@sigill.intra.peff.net \
    --to=peff@peff.net \
    --cc=git@vger.kernel.org \
    --cc=gitster@pobox.com \
    --cc=martin.agren@gmail.com \
    --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.
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 NNTP newsgroup(s).