asciidoc fixups
Get series with b4
b4 am [email protected]Versions newest first
- v1 Latest8 patches 20 repliesIn review
Patches in v1 No applies recorded yet
| # | Subject and files | Size | Replies | Applied |
|---|---|---|---|---|
| 1/8 | doc: fix misrendering due to `single quote'Documentation/ Documentation/ | +2 | 0 replies | |
| 2/8 | doc: fix unquoted use of "{type}"Documentation/ | +1 | 0 replies | |
| 3/8 | doc: fix hanging "+"-continuationDocumentation/ | +3 | 0 replies | |
| 4/8 | doc: fix length of underlined section-titleDocumentation/ | +1 | 0 replies | |
| 5/8 | doc/add: reformat `--edit` optionDocumentation/ | +2 | 0 replies | |
| 6/8 | doc: convert \--option to --optionDocumentation/ Documentation/ Documentation/ +8 more | +80 | 3 replies | |
| 7/8 | doc: drop backslash quoting of some curly bracesDocumentation/ | +7 | 0 replies | |
| 8/8 | doc: put example URLs and emails inside literal backticksDocumentation/ Documentation/ Documentation/ | +5 | 0 replies |
Reviews trailers per patch
No Reviewed-by, Acked-by or Tested-by trailers for v1 yet.
Cover letter [PATCH 0/8] asciidoc fixups
Quoted 4 lines · Jeff King
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