| Message ID | 20181215112742.1475882-2-martin.agren@gmail.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | A few Asciidoctor-fixes | expand |
On Sat, Dec 15, 2018 at 12:27:39PM +0100, Martin Ågren wrote: > We have too few dashes under "Examples", which causes Asciidoctor to not > pick it up as a section header, but to instead just render the dashes > literally. This also seems to confuse Asciidoctor about dashes in > general around here. It misinterprets the listing blocks in this > section, again rendering the dashes literally. > > Make sure we have as many dashes as we have characters in "Examples". > This fixes the section-issue and, somehow, makes the listing blocks > render correctly. Yeah, the mis-matched title-and-dashes thing has bitten us several times. I think this one just post-dates the last round of fixing. The "somehow" here is that the mismatched dashes appear to be the start of a code listing block, making the whole example section into one big listing (which isn't properly closed, generating a warning). And that's why in the context: > EXAMPLES > ------- > +-------- > > Format data by columns: > ------------ We _don't_ need to match up the dashes for "Format data...". That is meant to be a listing block (and arguably should use a shorter string of dashes to make that intent more obvious). -Peff
On Sun, 16 Dec 2018 at 11:51, Jeff King <peff@peff.net> wrote: > > On Sat, Dec 15, 2018 at 12:27:39PM +0100, Martin Ågren wrote: > > > We have too few dashes under "Examples", which causes Asciidoctor to not > > pick it up as a section header, but to instead just render the dashes > > literally. This also seems to confuse Asciidoctor about dashes in > > general around here. It misinterprets the listing blocks in this > > section, again rendering the dashes literally. > > > > Make sure we have as many dashes as we have characters in "Examples". > > This fixes the section-issue and, somehow, makes the listing blocks > > render correctly. > > The "somehow" here is that the mismatched dashes appear to be the start > of a code listing block, making the whole example section into one big > listing (which isn't properly closed, generating a warning). Of course. Thanks for pointing it out. I now realize that when I wrote "render the dashes literally", I was wrong. This should be improved in v2. Martin
diff --git a/Documentation/git-column.txt b/Documentation/git-column.txt index 763afabb6d..f58e9c43e6 100644 --- a/Documentation/git-column.txt +++ b/Documentation/git-column.txt @@ -47,7 +47,7 @@ OPTIONS The number of spaces between columns. One space by default. EXAMPLES ------- +-------- Format data by columns: ------------
We have too few dashes under "Examples", which causes Asciidoctor to not pick it up as a section header, but to instead just render the dashes literally. This also seems to confuse Asciidoctor about dashes in general around here. It misinterprets the listing blocks in this section, again rendering the dashes literally. Make sure we have as many dashes as we have characters in "Examples". This fixes the section-issue and, somehow, makes the listing blocks render correctly. Asciidoc renders identically before and after this patch, both man-page and html. Signed-off-by: Martin Ågren <martin.agren@gmail.com> --- See https://git-scm.com/docs/git-column Documentation/git-column.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)