docs: monospace listings in docbook output
commitc2a7f5d43843d16850a460e7f202affb0d24dc48
authorJeff King <peff@peff.net>
Tue, 7 Aug 2012 20:07:38 +0000 (7 16:07 -0400)
committerJunio C Hamano <gitster@pobox.com>
Tue, 7 Aug 2012 21:30:52 +0000 (7 14:30 -0700)
tree0984c211ca17b6d68eb51245d56179ed8d86388c
parent828ea97de486c1693d6e4f2c7347acb50235a85d
docs: monospace listings in docbook output

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 <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Documentation/asciidoc.conf
Documentation/user-manual.conf