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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html