When asciidoc converts a listing block like:
----------------------
$ git log --merge
----------------------
it marks it to be displayed in a monospace font. This works
fine when generating HTML output. However, when generating
docbook output, we override the expansion of a listingblock
to work around bugs in some versions of the docbook
toolchain. Our override did not mark the listingblock with
the "monospaced" class.
The main output that uses docbook as an intermediate format
is the manpages. We didn't notice any issue there because
the monospaced class seems to be ignored when generating
roff from the docbook manpages.
However, when generating texinfo to make info pages, docbook
does respect this class. The resulting texinfo output
properly uses "@example" blocks to display the listing in
this case. Besides possibly looking prettier in some texinfo
backends, one important effect is that the monospace font
suppresses texinfo's expansion of "--" and "---" into
en-dashes and em-dashes. With the current code, the example
above ends up looking like "git log -merge", which is
confusing and wrong.
Signed-off-by: Jeff King <p...@peff.net>
---
I wonder if we can maybe just rip out our custom overrides entirely.
They date back to versions of docbook from 2006. I'm not sure I entirely
understand their purpose, though (they seem to also be about inserting
extra line breaks, and handling manual additions of roff).
This cleans up many of the problems with the info result. However, there
are still lots of places that use "--" outside of a listing block or a
backtick literal. Those still look bad in the generated info page.
Documentation/asciidoc.conf | 4 ++--
Documentation/user-manual.conf | 2 +-
2 files changed, 3 insertions(+), 3 deletions(-)
diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index a26d245..1273a85 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf
@@ -36,7 +36,7 @@ ifndef::git-asciidoc-no-roff[]
# v1.72 breaks with this because it replaces dots not in roff requests.
[listingblock]
<example><title>{title}</title>
-<literallayout>
+<literallayout class="monospaced">
ifdef::doctype-manpage[]
.ft C
endif::doctype-manpage[]
@@ -53,7 +53,7 @@ ifdef::doctype-manpage[]
# The following two small workarounds insert a simple paragraph after screen
[listingblock]
<example><title>{title}</title>
-<literallayout>
+<literallayout class="monospaced">
|
</literallayout><simpara></simpara>
{title#}</example>
diff --git a/Documentation/user-manual.conf b/Documentation/user-manual.conf
index 339b309..d87294d 100644
--- a/Documentation/user-manual.conf
+++ b/Documentation/user-manual.conf
@@ -14,7 +14,7 @@ ifdef::backend-docbook[]
# "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this.
[listingblock]
<example><title>{title}</title>
-<literallayout>
+<literallayout class="monospaced">
|
</literallayout>
{title#}</example>
--
1.7.12.rc1.12.g5eaae48
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
