[PATCH v2 0/8] Documentation: XSLT/asciidoc.conf cleanup; tty literals

[PATCH v2 0/8] Documentation: XSLT/asciidoc.conf cleanup; tty literals

[Chris Johnsen]

"v1" of this series can be found here: <http://thread.gmane.org/gmane.comp.version-control.git/114417>.

Change since "v1":

  1/8: No content change from "v1". This time -C -M was used to
       show copy/rename of callouts.xsl (thanks to Peff for
       pointing to diff.renames config option).

  2/8: Use <xsl:import> instead of xmlto command line to reuse
       manpage-base.xsl. In commit message, move discussion of
       --stringparm to 8/8.

  8/8: No content change from "v1" (though context is changed due
       to content change in 2/8). In commit message, add some of
       --stringparm discussion from "v1" 2/8.

-- 
Chris

[PATCH v2 1/8] Documentation: move callouts.xsl to manpage-{base,normal}.xsl

[Chris Johnsen]

Each of manpage-base.xsl and manpage-normal.xsl gets a copy of
the contents of callouts.xsl and the original is removed. The
Makefile is adjusted to refer to manpage-normal.xsl instead of
callouts.xsl. manpage-base.xsl will be later made into a common
base for -normal and -1.72.

Testing done with asciidoc 8.3.1 and docbook-xsl 1.74.0.

Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com>

---

This duplication is in preparation for refactoring. It should
make it easier to keep track of the source of the various XSL
constructs while reviewing.
---
 Documentation/Makefile                             |    2 +-
 Documentation/{callouts.xsl => manpage-base.xsl}   |    0
 Documentation/{callouts.xsl => manpage-normal.xsl} |    0
 3 files changed, 1 insertions(+), 1 deletions(-)
 copy Documentation/{callouts.xsl => manpage-base.xsl} (100%)
 rename Documentation/{callouts.xsl => manpage-normal.xsl} (100%)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 144ec32..e1562e3 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -41,7 +41,7 @@ man7dir=$(mandir)/man7
 
 ASCIIDOC=asciidoc
 ASCIIDOC_EXTRA =
-MANPAGE_XSL = callouts.xsl
+MANPAGE_XSL = manpage-normal.xsl
 INSTALL?=install
 RM ?= rm -f
 DOC_REF = origin/man
diff --git a/Documentation/callouts.xsl b/Documentation/manpage-base.xsl
similarity index 100%
copy from Documentation/callouts.xsl
copy to Documentation/manpage-base.xsl
diff --git a/Documentation/callouts.xsl b/Documentation/manpage-normal.xsl
similarity index 100%
rename from Documentation/callouts.xsl
rename to Documentation/manpage-normal.xsl
-- 
1.6.2.1.401.gc048

[PATCH v2 2/8] Documentation: use parametrized manpage-base.xsl with manpage-{1.72,normal}.xsl

[Chris Johnsen]

Parametrize the backslash and dot characters that are used to
generate roff control sequences in manpage-base.xsl.

Testing done with asciidoc 8.3.1 and docbook-xsl 1.74.0.

Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com>

---

Changes since "v1": In manpage-{normal,1.72}.xsl, use
  <xsl:import> to incorporate manpage-base.xsl. Take
  manpage-base.xsl off the xmlto commandline. Thanks, Peff!

  Implementation details in the commit message have been moved to
  the last patch.

---

Still no change in behavior. Just refactoring here.
---
 Documentation/manpage-1.72.xsl   |   29 ++++++++++++---------------
 Documentation/manpage-base.xsl   |   39 +++++++++++++++++++------------------
 Documentation/manpage-normal.xsl |   30 ++++++++++++----------------
 3 files changed, 46 insertions(+), 52 deletions(-)

diff --git a/Documentation/manpage-1.72.xsl b/Documentation/manpage-1.72.xsl
index 4065a3a..e24d26c 100644
--- a/Documentation/manpage-1.72.xsl
+++ b/Documentation/manpage-1.72.xsl
@@ -1,21 +1,18 @@
-<!-- Based on callouts.xsl. Fixes man page callouts for DocBook 1.72 XSL -->
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+<!-- manpage-1.72.xsl:
+     special settings for manpages rendered from asciidoc+docbook
+     handles peculiarities in docbook-xsl 1.72.0 -->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+		version="1.0">
 
+<xsl:import href="manpage-base.xsl"/>
+
+<!-- these are the special values for the roff control characters
+     needed for docbook-xsl 1.72.0 -->
+<xsl:param name="git.docbook.backslash">&#x2593;</xsl:param>
+<xsl:param name="git.docbook.dot"      >&#x2302;</xsl:param>
+
+<!-- these params silence some output from xmlto -->
 <xsl:param name="man.output.quietly" select="1"/>
 <xsl:param name="refentry.meta.get.quietly" select="1"/>
 
-<xsl:template match="co">
-	<xsl:value-of select="concat('&#x2593;fB(',substring-after(@id,'-'),')&#x2593;fR')"/>
-</xsl:template>
-<xsl:template match="calloutlist">
-	<xsl:text>&#x2302;sp&#10;</xsl:text>
-	<xsl:apply-templates/>
-	<xsl:text>&#10;</xsl:text>
-</xsl:template>
-<xsl:template match="callout">
-	<xsl:value-of select="concat('&#x2593;fB',substring-after(@arearefs,'-'),'. &#x2593;fR')"/>
-	<xsl:apply-templates/>
-	<xsl:text>&#x2302;br&#10;</xsl:text>
-</xsl:template>
-
 </xsl:stylesheet>
diff --git a/Documentation/manpage-base.xsl b/Documentation/manpage-base.xsl
index 6a361a2..6d3eb19 100644
--- a/Documentation/manpage-base.xsl
+++ b/Documentation/manpage-base.xsl
@@ -1,30 +1,31 @@
-<!-- callout.xsl: converts asciidoc callouts to man page format -->
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
+<!-- manpage-base.xsl:
+     special formatting for manpages rendered from asciidoc+docbook -->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+		version="1.0">
+
+<!-- convert asciidoc callouts to man page format;
+     git.docbook.backslash and git.docbook.dot params
+     must be supplied by another XSL file or other means -->
 <xsl:template match="co">
-	<xsl:value-of select="concat('\fB(',substring-after(@id,'-'),')\fR')"/>
+	<xsl:value-of select="concat(
+			      $git.docbook.backslash,'fB(',
+			      substring-after(@id,'-'),')',
+			      $git.docbook.backslash,'fR')"/>
 </xsl:template>
 <xsl:template match="calloutlist">
-	<xsl:text>.sp&#10;</xsl:text>
+	<xsl:value-of select="$git.docbook.dot"/>
+	<xsl:text>sp&#10;</xsl:text>
 	<xsl:apply-templates/>
 	<xsl:text>&#10;</xsl:text>
 </xsl:template>
 <xsl:template match="callout">
-	<xsl:value-of select="concat('\fB',substring-after(@arearefs,'-'),'. \fR')"/>
+	<xsl:value-of select="concat(
+			      $git.docbook.backslash,'fB',
+			      substring-after(@arearefs,'-'),
+			      '. ',$git.docbook.backslash,'fR')"/>
 	<xsl:apply-templates/>
-	<xsl:text>.br&#10;</xsl:text>
-</xsl:template>
-
-<!-- sorry, this is not about callouts, but attempts to work around
- spurious .sp at the tail of the line docbook stylesheets seem to add -->
-<xsl:template match="simpara">
-  <xsl:variable name="content">
-    <xsl:apply-templates/>
-  </xsl:variable>
-  <xsl:value-of select="normalize-space($content)"/>
-  <xsl:if test="not(ancestor::authorblurb) and
-                not(ancestor::personblurb)">
-    <xsl:text>&#10;&#10;</xsl:text>
-  </xsl:if>
+	<xsl:value-of select="$git.docbook.dot"/>
+	<xsl:text>br&#10;</xsl:text>
 </xsl:template>
 
 </xsl:stylesheet>
diff --git a/Documentation/manpage-normal.xsl b/Documentation/manpage-normal.xsl
index 6a361a2..e36472f 100644
--- a/Documentation/manpage-normal.xsl
+++ b/Documentation/manpage-normal.xsl
@@ -1,21 +1,17 @@
-<!-- callout.xsl: converts asciidoc callouts to man page format -->
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
-<xsl:template match="co">
-	<xsl:value-of select="concat('\fB(',substring-after(@id,'-'),')\fR')"/>
-</xsl:template>
-<xsl:template match="calloutlist">
-	<xsl:text>.sp&#10;</xsl:text>
-	<xsl:apply-templates/>
-	<xsl:text>&#10;</xsl:text>
-</xsl:template>
-<xsl:template match="callout">
-	<xsl:value-of select="concat('\fB',substring-after(@arearefs,'-'),'. \fR')"/>
-	<xsl:apply-templates/>
-	<xsl:text>.br&#10;</xsl:text>
-</xsl:template>
+<!-- manpage-normal.xsl:
+     special settings for manpages rendered from asciidoc+docbook
+     handles anything we want to keep away from docbook-xsl 1.72.0 -->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+		version="1.0">
+
+<xsl:import href="manpage-base.xsl"/>
+
+<!-- these are the normal values for the roff control characters -->
+<xsl:param name="git.docbook.backslash">\</xsl:param>
+<xsl:param name="git.docbook.dot"	>.</xsl:param>
 
-<!-- sorry, this is not about callouts, but attempts to work around
- spurious .sp at the tail of the line docbook stylesheets seem to add -->
+<!-- attempt to work around spurious .sp at the tail of the line
+     that docbook stylesheets seem to add -->
 <xsl:template match="simpara">
   <xsl:variable name="content">
     <xsl:apply-templates/>
-- 
1.6.2.1.401.gc048

[PATCH v2 3/8] Documentation: rename docbook-xsl-172 attribute to git-asciidoc-no-roff

[Chris Johnsen]

It seems that the ability to use raw roff codes in asciidoc.conf
was eliminated by docbook-xsl 1.72.0 _and later_. Unlike the
1.72.0-specific XSLT problem, this behavior was not reverted in
later releases.

This patch aims to make it clear that the affected asciidoc
attribute (flag) can be reasonably used with docbook-xsl versions
other than 1.72.0.

Also, document which make variables should be set for various
versions of asciidoc and docbook-xsl.

Testing done with asciidoc 8.3.1 and docbook-xsl 1.74.0.

Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com>

---

This has no behavior changes for existing uses (make
DOCBOOK_XSL_172=Yes), but it enables new functionality
(ASCIIDOC_NO_ROFF=Yes) by divorcing the roff-avoiding parts of
asciidoc.conf from the label docbook-xsl-172.

I like the idea of including "tested with asciidoc/docbook-xsl
version info" in the commit message. It would have been very
helpful if all the previous commits to the core documentation
generation infrastructure carried such information.
---
 Documentation/Makefile      |   29 ++++++++++++++++++++++++++++-
 Documentation/asciidoc.conf |    8 ++++----
 2 files changed, 32 insertions(+), 5 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index e1562e3..d71760b 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -59,12 +59,39 @@ endif
 -include ../config.mak.autogen
 -include ../config.mak
 
+#
+# For asciidoc ...
+#	-7.1.2,	no extra settings are needed.
+#	8.0-,	set ASCIIDOC8.
+#
+
+#
+# For docbook-xsl ...
+#	-1.68.1,	set ASCIIDOC_NO_ROFF? (based on changelog from 1.73.0)
+#	1.69.0-1.71.1,	no extra settings are needed?
+#	1.72.0,		set DOCBOOK_XSL_172.
+#	1.73.0-,	set ASCIIDOC_NO_ROFF
+#
+
+#
+# If you had been using DOCBOOK_XSL_172 in an attempt to get rid
+# of 'the ".ft C" problem' in your generated manpages, and you
+# instead ended up with weird characters around callouts, try
+# using ASCIIDOC_NO_ROFF instead (it works fine with ASCIIDOC8).
+#
+
 ifdef ASCIIDOC8
 ASCIIDOC_EXTRA += -a asciidoc7compatible
 endif
 ifdef DOCBOOK_XSL_172
-ASCIIDOC_EXTRA += -a docbook-xsl-172
+ASCIIDOC_EXTRA += -a git-asciidoc-no-roff
 MANPAGE_XSL = manpage-1.72.xsl
+else
+	ifdef ASCIIDOC_NO_ROFF
+	# docbook-xsl after 1.72 needs the regular XSL, but will not
+	# pass-thru raw roff codes from asciidoc.conf, so turn them off.
+	ASCIIDOC_EXTRA += -a git-asciidoc-no-roff
+	endif
 endif
 
 #
diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index 1e735df..ce1b175 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf
@@ -27,7 +27,7 @@ ifdef::backend-docbook[]
 endif::backend-docbook[]
 
 ifdef::backend-docbook[]
-ifndef::docbook-xsl-172[]
+ifndef::git-asciidoc-no-roff[]
 # "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this.
 # v1.72 breaks with this because it replaces dots not in roff requests.
 [listingblock]
@@ -42,9 +42,9 @@ ifdef::doctype-manpage[]
 endif::doctype-manpage[]
 </literallayout>
 {title#}</example>
-endif::docbook-xsl-172[]
+endif::git-asciidoc-no-roff[]
 
-ifdef::docbook-xsl-172[]
+ifdef::git-asciidoc-no-roff[]
 ifdef::doctype-manpage[]
 # The following two small workarounds insert a simple paragraph after screen
 [listingblock]
@@ -62,7 +62,7 @@ ifdef::doctype-manpage[]
 </literallayout><simpara></simpara>
 {title#}</para></formalpara>
 endif::doctype-manpage[]
-endif::docbook-xsl-172[]
+endif::git-asciidoc-no-roff[]
 endif::backend-docbook[]
 
 ifdef::doctype-manpage[]
-- 
1.6.2.1.401.gc048

[PATCH v2 4/8] Documentation: move quieting params into manpage-base.xsl

[Chris Johnsen]

Move a couple of XSL parameters that act to silence
informational/warning messages generated when running xmlto from
manpage-1.72.xsl to manpage-base.xsl.

Since unused parameters are silently ignored, there is no problem
if some version of docbook-xsl does not know about these
parameters. The only problem might be if a version of docbook-xsl
uses the parameters for alternate functionality. Since both
parameters have fairly specific names such a situation is
unlikely.

Testing done with asciidoc 8.3.1 and docbook-xsl 1.74.0.

Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com>

---

I am not sure why these were only in the -1.72 variant. They
should probably be in -base (done by this patch) or in neither
variant. If there is a good reason for having it only in -1.72,
this patch can be dropped entirely, the rest do not depend on it.
---
 Documentation/manpage-1.72.xsl |    4 ----
 Documentation/manpage-base.xsl |    4 ++++
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/manpage-1.72.xsl b/Documentation/manpage-1.72.xsl
index e24d26c..b4d315c 100644
--- a/Documentation/manpage-1.72.xsl
+++ b/Documentation/manpage-1.72.xsl
@@ -11,8 +11,4 @@
 <xsl:param name="git.docbook.backslash">&#x2593;</xsl:param>
 <xsl:param name="git.docbook.dot"      >&#x2302;</xsl:param>
 
-<!-- these params silence some output from xmlto -->
-<xsl:param name="man.output.quietly" select="1"/>
-<xsl:param name="refentry.meta.get.quietly" select="1"/>
-
 </xsl:stylesheet>
diff --git a/Documentation/manpage-base.xsl b/Documentation/manpage-base.xsl
index 6d3eb19..a264fa6 100644
--- a/Documentation/manpage-base.xsl
+++ b/Documentation/manpage-base.xsl
@@ -3,6 +3,10 @@
 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
 		version="1.0">
 
+<!-- these params silence some output from xmlto -->
+<xsl:param name="man.output.quietly" select="1"/>
+<xsl:param name="refentry.meta.get.quietly" select="1"/>
+
 <!-- convert asciidoc callouts to man page format;
      git.docbook.backslash and git.docbook.dot params
      must be supplied by another XSL file or other means -->
-- 
1.6.2.1.401.gc048

[PATCH v2 5/8] Documentation: move "spurious .sp" code into manpage-base.xsl

[Chris Johnsen]

The "spurious .sp" code should be independent of docbook-xsl
versions.

Testing done with asciidoc 8.3.1 and docbook-xsl 1.74.0.

Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com>

---

I do not know why this was only in the non-1.72 variant. Maybe
docbook-xsl 1.72.0 did not need it. But it does not seem like it
would hurt to push it into the shared XSLT. As before, if there
is a good reason to keep it out of the -1.72 processing, then
just drop this patch, none of the rest depend on it.
---
 Documentation/manpage-base.xsl   |   13 +++++++++++++
 Documentation/manpage-normal.xsl |   13 -------------
 2 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/Documentation/manpage-base.xsl b/Documentation/manpage-base.xsl
index a264fa6..16e2e40 100644
--- a/Documentation/manpage-base.xsl
+++ b/Documentation/manpage-base.xsl
@@ -32,4 +32,17 @@
 	<xsl:text>br&#10;</xsl:text>
 </xsl:template>
 
+<!-- attempt to work around spurious .sp at the tail of the line
+     that docbook stylesheets seem to add -->
+<xsl:template match="simpara">
+  <xsl:variable name="content">
+    <xsl:apply-templates/>
+  </xsl:variable>
+  <xsl:value-of select="normalize-space($content)"/>
+  <xsl:if test="not(ancestor::authorblurb) and
+                not(ancestor::personblurb)">
+    <xsl:text>&#10;&#10;</xsl:text>
+  </xsl:if>
+</xsl:template>
+
 </xsl:stylesheet>
diff --git a/Documentation/manpage-normal.xsl b/Documentation/manpage-normal.xsl
index e36472f..a48f5b1 100644
--- a/Documentation/manpage-normal.xsl
+++ b/Documentation/manpage-normal.xsl
@@ -10,17 +10,4 @@
 <xsl:param name="git.docbook.backslash">\</xsl:param>
 <xsl:param name="git.docbook.dot"	>.</xsl:param>
 
-<!-- attempt to work around spurious .sp at the tail of the line
-     that docbook stylesheets seem to add -->
-<xsl:template match="simpara">
-  <xsl:variable name="content">
-    <xsl:apply-templates/>
-  </xsl:variable>
-  <xsl:value-of select="normalize-space($content)"/>
-  <xsl:if test="not(ancestor::authorblurb) and
-                not(ancestor::personblurb)">
-    <xsl:text>&#10;&#10;</xsl:text>
-  </xsl:if>
-</xsl:template>
-
 </xsl:stylesheet>
-- 
1.6.2.1.401.gc048

[PATCH v2 6/8] Documentation: asciidoc.conf: always use <literallayout> for [blocktext]

[Chris Johnsen]

Make the docbook-xsl-no-raw-roff variant match the
no-docbook-xsl-no-raw-roff variant in terms of which XML tag is
used to wrap listing block text (delimited with lines of dashes).

e920b56 (Tweak asciidoc output to work with broken docbook-xsl,
2006-03-05) says docbook-xsl 1.68 needs <literallayout>. This
<screen> usages was in the old, 1.72-only section. But since it
is now the "roff-less" section, it probably makes sense to make it
symmetric with the "roff-ful" section.

Testing done with asciidoc 8.3.1 and docbook-xsl 1.74.0.

Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com>

---

This is another cleanup to make the two conditional sections more
symmetric.

The only large, remaining asymmetry in the asciidoc.conf
roff/non-roff parts is the [verseblock] in the non-roff
section. Should [verseblock] be pulled out of the
roff-conditional parts?  Should a [verseblock] section be added
to the roff-using part?
---
 Documentation/asciidoc.conf |    4 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index ce1b175..9963f2d 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf
@@ -49,9 +49,9 @@ ifdef::doctype-manpage[]
 # The following two small workarounds insert a simple paragraph after screen
 [listingblock]
 <example><title>{title}</title>
-<screen>
+<literallayout>
 |
-</screen><simpara></simpara>
+</literallayout><simpara></simpara>
 {title#}</example>
 
 [verseblock]
-- 
1.6.2.1.401.gc048

[PATCH v2 7/8] Documentation: asciidoc.conf: fix verse block with block titles

[Chris Johnsen]

No files use the variant of block-title with verse-block, but
such a case would have generated broken docbook XML (<simpara> is
not allowed inside <para>). This fixes the potential deviation from
valid docbook XML.

Testing done with asciidoc 8.3.1 and docbook-xsl 1.74.0.

Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com>

---

This is a bugfix for a bug that the documentation currently does
not trigger. Drop this patch if this is unwarranted.
---
 Documentation/asciidoc.conf |    3 ++-
 1 files changed, 2 insertions(+), 1 deletions(-)

diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index 9963f2d..dc76e7f 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf
@@ -59,8 +59,9 @@ ifdef::doctype-manpage[]
 {title%}<literallayout{id? id="{id}"}>
 {title#}<literallayout>
 |
-</literallayout><simpara></simpara>
+</literallayout>
 {title#}</para></formalpara>
+{title%}<simpara></simpara>
 endif::doctype-manpage[]
 endif::git-asciidoc-no-roff[]
 endif::backend-docbook[]
-- 
1.6.2.1.401.gc048

[PATCH v2 8/8] Documentation: option to render literal text as bold for manpages

[Chris Johnsen]

This allows manpages viewed on a tty to render inline literal
text in a manner that is distinct from the surrounding text.

The initial implementation (pre-mailing-list) of this patch
included a conditional variant of the XSLT code in
manpage-base.xsl and use xmlto's --stringparam option to
optionally enable the functionality. It turns out that
--stringparam is broken in all versions of xmlto except for the
pre-release, SVN version. Since xmlto is a shell script the patch
to fix it is simple enough, but I instead opted to use xmlto's
"module" functionality.

Testing done with asciidoc 8.3.1 and docbook-xsl 1.74.0.

Signed-off-by: Chris Johnsen <chris_johnsen@pobox.com>

---

Change since "v1": Move dicussion of --stringparam from patch 2
  to this patch. Deleted a bunch of it in the process. No content
  changes from the first version.

---

Since dobcook-xsl 1.74.0 seems to introduce using a monospace
font for literal text (asciidoc backticks), this patch may not be
so important for end users that can install their own
docbook-xsl.

But this patch, or something like it, might be useful for
introducing some kind of typesetting for literal text in the
official manpages (since it would not require upgrading
docbook-xsl). It could probably even be changed/extended to
provide monospacing without using a new docbook-xsl.

The functionality is optional and defaults to "off", so there
probably is not too much harm in including it, even if it is not
used for the official manpages.
---
 Documentation/Makefile                 |    6 +++++-
 Documentation/manpage-bold-literal.xsl |   17 +++++++++++++++++
 2 files changed, 22 insertions(+), 1 deletions(-)
 create mode 100644 Documentation/manpage-bold-literal.xsl

diff --git a/Documentation/Makefile b/Documentation/Makefile
index d71760b..1c94531 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -42,6 +42,7 @@ man7dir=$(mandir)/man7
 ASCIIDOC=asciidoc
 ASCIIDOC_EXTRA =
 MANPAGE_XSL = manpage-normal.xsl
+XMLTO_EXTRA =
 INSTALL?=install
 RM ?= rm -f
 DOC_REF = origin/man
@@ -93,6 +94,9 @@ else
 	ASCIIDOC_EXTRA += -a git-asciidoc-no-roff
 	endif
 endif
+ifdef MAN_BOLD_LITERAL
+XMLTO_EXTRA += -m manpage-bold-literal.xsl
+endif
 
 #
 # Please note that there is a minor bug in asciidoc.
@@ -192,7 +196,7 @@ $(MAN_HTML): %.html : %.txt
 
 %.1 %.5 %.7 : %.xml
 	$(RM) $@
-	xmlto -m $(MANPAGE_XSL) man $<
+	xmlto -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
 
 %.xml : %.txt
 	$(RM) $@+ $@
diff --git a/Documentation/manpage-bold-literal.xsl b/Documentation/manpage-bold-literal.xsl
new file mode 100644
index 0000000..608eb5d
--- /dev/null
+++ b/Documentation/manpage-bold-literal.xsl
@@ -0,0 +1,17 @@
+<!-- manpage-bold-literal.xsl:
+     special formatting for manpages rendered from asciidoc+docbook -->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+		version="1.0">
+
+<!-- render literal text as bold (instead of plain or monospace);
+     this makes literal text easier to distinguish in manpages
+     viewed on a tty -->
+<xsl:template match="literal">
+	<xsl:value-of select="$git.docbook.backslash"/>
+	<xsl:text>fB</xsl:text>
+	<xsl:apply-templates/>
+	<xsl:value-of select="$git.docbook.backslash"/>
+	<xsl:text>fR</xsl:text>
+</xsl:template>
+
+</xsl:stylesheet>
-- 
1.6.2.1.401.gc048

Re: [PATCH v2 0/8] Documentation: XSLT/asciidoc.conf cleanup; tty literals

[Jeff King]

On Fri, Mar 27, 2009 at 01:43:57AM -0500, Chris Johnsen wrote:

> "v1" of this series can be found here: <http://thread.gmane.org/gmane.comp.version-control.git/114417>.
> 
> Change since "v1":
> 
>   1/8: No content change from "v1". This time -C -M was used to
>        show copy/rename of callouts.xsl (thanks to Peff for
>        pointing to diff.renames config option).
> 
>   2/8: Use <xsl:import> instead of xmlto command line to reuse
>        manpage-base.xsl. In commit message, move discussion of
>        --stringparm to 8/8.
> 
>   8/8: No content change from "v1" (though context is changed due
>        to content change in 2/8). In commit message, add some of
>        --stringparm discussion from "v1" 2/8.

Thanks. This version (and its output) look sane to me (I am now building
with ASCIIDOC_NO_ROFF).

-Peff