On Wed, May 13, 2015 at 12:56:51AM -0400, Jeff King wrote:
> 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.

I've been in contact with Dan Allen, the lead on the Asciidoctor
project.  There are a few things that he pointed out.

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

I passed this as a command-line argument when using asciidoctor to
generate the docs: -a litdd=--.  For the site, I would recommend just
defining it there, as you suggested.

>   - 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.

What you want here is [verse,subs=normal].  As of Asciidoctor 1.5.0,
this allows substitutions and markup within verse blocks.  I believe old
versions of AsciiDoc did not render substitutions and markup in verse
blocks, despite claiming to, and Asciidoctor picked up that behavior.

The set of patches I put in for Asciidoctor require at least 1.5.1
anyway in order to build man pages properly.

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

Yes, currently Asciidoctor doesn't support this.  Outside of
asciidoc.conf, which Asciidoctor doesn't read, it looks like there's
exactly two uses in diff-options.txt.  We could probably rewrite those
using an attribute.

>   - 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?).

This is an under-defined area.  AsciiDoc and Asciidoctor both use
regexes instead of real parsers, and apparently there's some
disagreement on how these should be interpreted.  (The real solution is
to use a grammar and parser.) I think in some cases it might be
sufficient to use backticks, as those prevent further interpretation.
-- 
brian m. carlson / brian with sandals: Houston, Texas, US
+1 832 623 2791 | http://www.crustytoothpaste.net/~bmc | My opinion only
OpenPGP: RSA v4 4096b: 88AC E9B2 9196 305B A994 7552 F1BA 225C 0223 B187