git-log man2html conversion broken: http://git-scm.com/docs/git-log

[Derek Moore]

The HTML for the git-log man page is being misrendered on the official site.

See the placehoders list under "format:<string>" in the PRETTY FORMATS section.

[brian m. carlson]

Neither the AsciiDoc nor the Asciidoctor documentation specify whether
the same number of delimiter characters must be used to end a block as
to begin it, although both sets of documentation show exactly matching
pairs. AsciiDoc allows mismatches, but AsciiDoctor apparently does not.
Adjust the pretty formats documentation to use matching pairs to prevent
a misrendering where the remainder of the document was rendered as a
listing block.

Signed-off-by: brian m. carlson <***@crustytoothpaste.net>
---
Documentation/pretty-formats.txt | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
index eecc39d..dcf7429 100644
--- a/Documentation/pretty-formats.txt
+++ b/Documentation/pretty-formats.txt
@@ -95,7 +95,7 @@ would show something like this:
The author of fe6e0ee was Junio C Hamano, 23 hours ago
The title was >>t4119: test autocomputing -p<n> for traditional diff input.<<

---------
+-------
+
The placeholders are:

[Junio C Hamano]

Post by brian m. carlson
Neither the AsciiDoc nor the Asciidoctor documentation specify whether
the same number of delimiter characters must be used to end a block as
to begin it, although both sets of documentation show exactly matching
pairs. AsciiDoc allows mismatches, but AsciiDoctor apparently does not.
Adjust the pretty formats documentation to use matching pairs to prevent
a misrendering where the remainder of the document was rendered as a
listing block.
---

Thanks, well spotted, well described and well done ;-)

Will queue.

Post by brian m. carlson
Documentation/pretty-formats.txt | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
index eecc39d..dcf7429 100644
--- a/Documentation/pretty-formats.txt
+++ b/Documentation/pretty-formats.txt
The author of fe6e0ee was Junio C Hamano, 23 hours ago
The title was >>t4119: test autocomputing -p<n> for traditional diff input.<<
---------
+-------
+

[Jeff King]

Post by brian m. carlson
Neither the AsciiDoc nor the Asciidoctor documentation specify whether
the same number of delimiter characters must be used to end a block as
to begin it, although both sets of documentation show exactly matching
pairs. AsciiDoc allows mismatches, but AsciiDoctor apparently does not.
Adjust the pretty formats documentation to use matching pairs to prevent
a misrendering where the remainder of the document was rendered as a
listing block.

Argh, I somehow missed your message and just typed an almost-identical
response. Consider that an approval of your patch. :)

I'm still going to report this to the AsciiDoctor folks; they should
probably be shooting for compatibility with vanilla AsciiDoc.

-Peff

[brian m. carlson]

Post by Jeff King
I'm still going to report this to the AsciiDoctor folks; they should
probably be shooting for compatibility with vanilla AsciiDoc.

Please do. I contribute occasionally to Asciidoctor, so I may pick it
up and fix it.

I'm interested in getting git's documentation to work better with
Asciidoctor out of the box, so you may see some patches along that line
sometime soon.

[Jeff King]

Post by Derek Moore
The HTML for the git-log man page is being misrendered on the official site.
See the placehoders list under "format:<string>" in the PRETTY FORMATS section.

Thanks for the report. This renders fine locally with asciidoc, but the
git-scm.com site uses the ruby asciidoctor gem. I think the issue is
that the start and end markers for the code block are not identical:

-------
The author of fe6e0ee was Junio C Hamano, 23 hours ago
The title was >>t4119: test autocomputing -p<n> for traditional diff
input.<<

--------

Note that we start with 7 hyphens, but end with 8.

The git-scm issue was already reported here (the site's issues are
tracked separately from the mailing list):

https://github.com/git/git-scm.com/issues/447

but I doubt if asciidoctor folks have been notified. I'll call their
attention to that issue; they should produce the same output as regular
asciidoc for this case.

In the meantime, I don't know if it is worth us applying this workaround
to the documentation (I'd feel better if I had actually confirmed that
it fixed the problem):

-- >8 --
Subject: docs: use identical start/end lines for code blocks

Some AsciiDoc implementations (like the AsciiDoctor gem) do not
recognize the end of a code block if it does not match the start
line exactly. Those implementations are wrong, but we can work around it
and make our sources look nicer at the same time.

---
diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt
index eecc39d..d3e3d25 100644
--- a/Documentation/pretty-formats.txt
+++ b/Documentation/pretty-formats.txt
@@ -91,7 +91,7 @@ instead of '\n'.
E.g, 'format:"The author of %h was %an, %ar%nThe title was >>%s<<%n"'
would show something like this:
+
--------
+--------
The author of fe6e0ee was Junio C Hamano, 23 hours ago
The title was >>t4119: test autocomputing -p<n> for traditional diff input.<<