git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Re: [PATCH 0/8] asciidoc fixups

From
brian m. carlson <sandals@crustytoothpaste.net>
Date
May 13, 2015, 22:41 UTC
Message-ID
<20150513224131.GC425227@vauxhall.crustytoothpaste.net>
In-Reply-To
<20150513045650.GA6070@peff.net>
On Wed, May 13, 2015 at 12:56:51AM -0400, Jeff King wrote:
Show 13 quoted lines
> 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.

Show 7 quoted lines
> 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.

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

Show 12 quoted lines
>   - 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
Previous: Jeff KingNext: Jeff King
Message 26 of 37 in “doc: fix unmatched code fences”
  1. doc: fix unmatched code fencesJean-Noel Avila, May 12, 2015
  2. Junio C HamanoMay 12, 2015
  3. Jeff KingMay 13, 2015
  4. Junio C HamanoMay 13, 2015
  5. Jeff KingMay 13, 2015
  6. Junio C HamanoMay 13, 2015
  7. Jeff KingMay 13, 2015
  8. brian m. carlsonMay 13, 2015
  9. 0/8 asciidoc fixupsJeff King, May 13, 2015
  10. 1/8 doc: fix misrendering due to `single quote'Jeff King, May 13, 2015
  11. 2/8 doc: fix unquoted use of "{type}"Jeff King, May 13, 2015
  12. 3/8 doc: fix hanging "+"-continuationJeff King, May 13, 2015
  13. 4/8 doc: fix length of underlined section-titleJeff King, May 13, 2015
  14. 5/8 doc/add: reformat `--edit` optionJeff King, May 13, 2015
  15. 6/8 doc: convert \--option to --optionJeff King, May 13, 2015
  16. John KeepingMay 13, 2015
  17. Jeff KingMay 14, 2015
  18. Junio C HamanoMay 17, 2015
  19. 7/8 doc: drop backslash quoting of some curly bracesJeff King, May 13, 2015
  20. 8/8 doc: put example URLs and emails inside literal backticksJeff King, May 13, 2015
  21. Jeff KingMay 13, 2015
  22. Junio C HamanoMay 13, 2015
  23. Jeff KingMay 13, 2015
  24. Johannes SchindelinMay 13, 2015
  25. Jeff KingMay 14, 2015
  26. brian m. carlsonMay 13, 2015
  27. Jeff KingMay 14, 2015
  28. 9/8 doc: convert AsciiDoc {?foo} to ifdef::foo[]Jeff King, May 14, 2015
  29. Johannes SchindelinMay 14, 2015
  30. Jeff KingMay 14, 2015
  31. Johannes SchindelinMay 14, 2015
  32. Junio C HamanoMay 14, 2015
  33. Jeff KingMay 14, 2015
  34. Junio C HamanoMay 14, 2015
  35. David TurnerMay 14, 2015
  36. brian m. carlsonMay 15, 2015
  37. Jeff KingMay 15, 2015

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.