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. :)
> > - 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=--'"
seems to work OK.
[1] <1413764438-297386-1-git-send-email-sandals@xxxxxxxxxxxxxxxxxxxx>
(sorry no link, gmane seems down)
> > - 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">
— 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"?
> > - 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.
> > - 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
--
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