[PATCH 0/8] asciidoc fixups

From: Jeff King <peff@peff.net>
Date: May 13, 2015, 04:56 UTC
Message-ID: <20150513045650.GA6070@peff.net>
In-Reply-To: <20150513021556.GA4160@peff.net>

On Tue, May 12, 2015 at 10:15:56PM -0400, Jeff King wrote:

> You can build with asciidoctor on the command-line. I don't know if it
> would be feasible to diff the asciidoc and asciidoctor output to look
> for gratuitous differences (or if the output is so different due to
> trivial stuff that the diff is unreadable).

So...it kind of works. I had to do unspeakable things with sed, and even then ended up with an 18,000-line "--color-words" diff.

Below are some fixes. The early ones are actual bugs in our sources. The latter ones are changes we could do to make asciidoctor happier. Each patch is independent, so we can take or leave whatever we want.

After this series, the remaining problems are:

  - asciidoctor does not render {litdd}, which is our invention; locally
    this may be because I did not have the right incantation, but it is
    also broken on git-scm.com. I think the right fix is to define that
    attribute for the site renderer (so not a bug in our sources, and
    not an asciidoctor bug)

  - in the '[verse]' section of the SYNOPSIS of each man page, AsciiDoc
    renders 'git add' in the usual way (with emphasis). Whereas
    AsciiDoctor renders it normally, with the literal quotes included.

    In the same [verse] section, AsciiDoctor does not convert literal
    "..." into a fancy ellipsis. So perhaps it treats [verse] as a
    section in which markup is not expanded? This may be related to the
    [verseblock] stuff we have in our config file.

  - We use "{attr? foo}" to display "foo" only when "attr" is set.
    AsciiDoctor does not seem to understand this and renders the whole
    string.

  - Lots of places where we backslash-escape some syntax for AsciiDoc
    ends up rendered by AsciiDoctor with the backslashes included. In
    some cases the quoting is unnecessary and we can drop it (see
    patches 6 and 7 below). But in others it really is necessary, and
    AsciiDoc generates bad output without the backslashes. The major
    ones are "--" surrounded by spaces (which becomes an emdash), and
    things like @\{HEAD}, which needs quoted to tell AsciiDoc that HEAD
    isn't an attribute.

    I'm not sure of the solution (is AsciiDoctor just broken, or
    is there some other syntax we could use that would work in both
    places, or what?).

Here are the patches. They do not include the code-fence fixes from Jean-Noel and myself that were already posted, but could easily go on top.

  [1/8]: doc: fix misrendering due to `single quote'
  [2/8]: doc: fix unquoted use of "{type}"
  [3/8]: doc: fix hanging "+"-continuation
  [4/8]: doc: fix length of underlined section-title
  [5/8]: doc/add: reformat `--edit` option
  [6/8]: doc: convert \--option to --option
  [7/8]: doc: drop backslash quoting of some curly braces
  [8/8]: doc: put example URLs inside literal backticks

-Peff