[0/7] Fix more AsciiDoc/tor differences

Message

Martin Ågren Sept. 7, 2019, 2:12 p.m. UTC

This series roughly halves the line count of `./doc-diff --from-asciidoc
--to-asciidoctor --cut-header-footer HEAD HEAD`. Together with my recent
(independent) mini-series [1], I claim that Asciidoctor 1.5.5 now
processes the manpages better than AsciiDoc 8.6.10 does.

Patch 6/7 actually changes the rendering with both engines, so that they
look nice and the same. The other patches are all no-ops with one engine
while fixing things with the other -- they all improve the situation
with Asciidoctor (which is what I care most about) except patch 1/7
which goes the other way (it reduces the doc-diff, which helps).

Patch 7/7 has an element of black magic to it. I wouldn't be too
surprised if I've managed to appease my particular versions of these
tools while not fixing -- or maybe even breaking? -- some other versions
[that people actually use]. That's where I think a quick test would be
the most valuable.

I've based this on maint on the assumption that these are bugfixes. (I
know I've been bad on basing similar work off of maint.) This causes a
conflict with master and pu in config.txt, which has learned about
"includeIf onbranch:foo-branch" in the meantime. Maybe I've made the
wrong call here -- Junio, if you'd rather have me submit this on master,
just let me know.

[1] https://public-inbox.org/git/[e-mail]/

Martin Ågren (7):
  Documentation: wrap blocks with "--"
  git-merge-base.txt: render indentations correctly under Asciidoctor
  Documentation: wrap config listings in "----"
  git-ls-remote.txt: wrap shell listing in "----"
  git-receive-pack.txt: wrap shell [script] listing in "----"
  git-merge-index.txt: wrap shell listing in "----"
  gitweb.conf.txt: switch pluses to backticks to help Asciidoctor

 Documentation/config.txt           | 84 ++++++++++++-------------
 Documentation/git-commit.txt       |  8 ++-
 Documentation/git-config.txt       | 56 +++++++++--------
 Documentation/git-ls-remote.txt    | 32 +++++-----
 Documentation/git-merge-base.txt   | 98 +++++++++++++++++-------------
 Documentation/git-merge-index.txt  | 26 ++++----
 Documentation/git-receive-pack.txt | 52 ++++++++--------
 Documentation/git-send-email.txt   | 12 ++--
 Documentation/git-status.txt       | 18 +++---
 Documentation/gitmodules.txt       | 15 ++---
 Documentation/gitweb.conf.txt      |  6 +-
 11 files changed, 223 insertions(+), 184 deletions(-)

Comments

Jeff King Sept. 13, 2019, 4:48 a.m. UTC | #1

On Sat, Sep 07, 2019 at 04:12:46PM +0200, Martin Ågren wrote:

> This series roughly halves the line count of `./doc-diff --from-asciidoc
> --to-asciidoctor --cut-header-footer HEAD HEAD`. Together with my recent
> (independent) mini-series [1], I claim that Asciidoctor 1.5.5 now
> processes the manpages better than AsciiDoc 8.6.10 does.

I looked these over, both source and rendered output (both with asciidoc
and with asciidoctor 2.0.10), and they all look good to me.

I think the delimited literal blocks are _slightly_ less pretty than the
indented ones, but this is the solution we've been using for cross-tool
compatibility (and I think it's intentional in asciidoctor to deprecate
the indented blocks, because there are just too many corner cases). The
delimited ones are also easier to write correctly.

> Patch 6/7 actually changes the rendering with both engines, so that they
> look nice and the same. The other patches are all no-ops with one engine
> while fixing things with the other -- they all improve the situation
> with Asciidoctor (which is what I care most about) except patch 1/7
> which goes the other way (it reduces the doc-diff, which helps).

Yeah, I agree that the change in 6/7 is an improvement (and 1/7 is an
obvious bugfix looking at the doc-diff using just asciidoc).

> Patch 7/7 has an element of black magic to it. I wouldn't be too
> surprised if I've managed to appease my particular versions of these
> tools while not fixing -- or maybe even breaking? -- some other versions
> [that people actually use]. That's where I think a quick test would be
> the most valuable.

I can confirm that asciidoctor 2.0.10 has the same bogus output there
before your patches, and that 7/7 fixes it.

-Peff

Martin Ågren Sept. 13, 2019, 12:21 p.m. UTC | #2

On Fri, 13 Sep 2019 at 06:48, Jeff King <[e-mail]> wrote:
>
> On Sat, Sep 07, 2019 at 04:12:46PM +0200, Martin Ågren wrote:
>
> > This series roughly halves the line count of `./doc-diff --from-asciidoc
> > --to-asciidoctor --cut-header-footer HEAD HEAD`. Together with my recent
> > (independent) mini-series [1], I claim that Asciidoctor 1.5.5 now
> > processes the manpages better than AsciiDoc 8.6.10 does.
>
> I looked these over, both source and rendered output (both with asciidoc
> and with asciidoctor 2.0.10), and they all look good to me.

Thanks.

> I think the delimited literal blocks are _slightly_ less pretty than the
> indented ones, but this is the solution we've been using for cross-tool
> compatibility (and I think it's intentional in asciidoctor to deprecate
> the indented blocks, because there are just too many corner cases). The
> delimited ones are also easier to write correctly.

Agreed on all of this.

> > Patch 7/7 has an element of black magic to it. I wouldn't be too
> > surprised if I've managed to appease my particular versions of these
> > tools while not fixing -- or maybe even breaking? -- some other versions
> > [that people actually use]. That's where I think a quick test would be
> > the most valuable.
>
> I can confirm that asciidoctor 2.0.10 has the same bogus output there
> before your patches, and that 7/7 fixes it.

Cool. Thanks for testing it.

Martin