Re: [PATCH 0/8] asciidoc fixups

From: Jeff King <peff@peff.net>
Date: May 14, 2015, 04:25 UTC
Message-ID: <20150514042544.GA9351@peff.net>
In-Reply-To: <20150513224131.GC425227@vauxhall.crustytoothpaste.net>

On Wed, May 13, 2015 at 10:41:31PM +0000, brian m. carlson wrote:

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

Thanks. I was hoping you would get involved. :)

Show 9 quoted lines

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

Yeah, I tried what you wrote earlier in [1], but it didn't work. But I just realized it has misplaced quotes. Doing:

  make ... ASCIIDOC_EXTRA="-a 'litdd=&#45;&#45;'"

seems to work OK.

[1] <1413764438-297386-1-git-send-email-sandals@crustytoothpaste.net>
    (sorry no link, gmane seems down)

Show 8 quoted lines

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

That does work for AsciiDoctor, but sadly it seems to break rendering for AsciiDoc, where it puts:

    <div class="attribution">
    &#8212; subs=normal
    </div>

in the middle of the SYNOPSIS. Yuck. Is there a way to make it work under both? Or a way to configure AsciiDoctor verses to always use "subs=normal"?

Show 8 quoted lines

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

I think they're already attributes, and it's just a magic syntax; I have a trivial patch I'll send in a moment.

Show 9 quoted lines

> >   - Lots of places where we backslash-escape some syntax for AsciiDoc
> >     ends up rendered by AsciiDoctor with the backslashes included.
> [...]
> 
> 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.

I actually prefer backticks in many cases, but they do come with their own formatting. Surely there is a way in AsciiDoctor to say "do not interpret this magically, but also do not format it as monospace"?

I guess the nuclear option is using attributes like {litdd} everywhere to avoid quoting. But it makes the source so ugly and hard to read.

-Peff