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
Attachment:
signature.asc
Description: Digital signature