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

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

[Chris Johnsen]

I had a go at wrangling with the documentation generation tools
to fix a couple of issues that I had noticed.

First, I could never get reasonable output for generated
manpages.  I have asciidoc 8.3.1 and docbook-xsl 1.74.0 on my
system. They chew through the documentation OK, but I was never
sure which flags I should use with them.

ASCIIDOC8 never seemed to do much (I was probably not looking in
the right places), but I decided to leave it enabled since it is
entirely outside the scope of the git code/configuration.

The other variable was DOCBOOK_XSL_172, and no matter which way I
turned it, I always got flawed output. If I set it, I would get
funky characters in the callout sections. If I unset it, I would
get ".ft C" and ".ft" bracketing literal blocks.

Second, the inline literal text of both the official and my
generated manpages was indistinguishable from the surrounding
text when viewing manpages in a terminal. It turns out the
official manpages end up with no markup for inline literal
text. The ones I generated did have some markup, but it was
flagged as monospace text, which is not all that distinguishable
from the normal, roman text when viewing through a terminal.

So I set about trying to solve these problems along with the
meta-problem of code duplication between callouts.xsl and
manpage-1.72.xsl.

The following series is my attempt to

  eliminate the XSLT code duplication,

  tease apart the uses of the "1.72" label that apply only to
    docbook-xsl 1.72 and those that also apply to some other
    versions of docbook-xsl,

  unify some of the items that look like they were applied to
    only one side of various "1.72" configurations but still
    seemed applicable to the other,

  fix a mostly unrelated, small, latent bug in asciidoc.conf,

  and provide an option to differentiate inline literal text when
    viewed on a terminal.

  Documentation/Makefile                 |   37 ++++++++++++++++++++++--
  Documentation/asciidoc.conf            |   15 +++++----
  Documentation/callouts.xsl             |   30 --------------------
  Documentation/manpage-1.72.xsl         |   28 ++++++------------
  Documentation/manpage-base.xsl         |   48 ++++++++++++++++++++++++++++++++
  Documentation/manpage-bold-literal.xsl |   17 +++++++++++
  Documentation/manpage-normal.xsl       |   12 ++++++++
  7 files changed, 129 insertions(+), 58 deletions(-)

-- 
Chris

[PATCH 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       |   30 ------------------------------
 Documentation/manpage-base.xsl   |   30 ++++++++++++++++++++++++++++++
 Documentation/manpage-normal.xsl |   30 ++++++++++++++++++++++++++++++
 4 files changed, 61 insertions(+), 31 deletions(-)
 delete mode 100644 Documentation/callouts.xsl
 create mode 100644 Documentation/manpage-base.xsl
 create mode 100644 Documentation/manpage-normal.xsl

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/callouts.xsl
deleted file mode 100644
index 6a361a2..0000000
--- a/Documentation/callouts.xsl
+++ /dev/null
@@ -1,30 +0,0 @@
-<!-- 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>
-
-<!-- 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:template>
-
-</xsl:stylesheet>
diff --git a/Documentation/manpage-base.xsl b/Documentation/manpage-base.xsl
new file mode 100644
index 0000000..6a361a2
--- /dev/null
+++ b/Documentation/manpage-base.xsl
@@ -0,0 +1,30 @@
+<!-- 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>
+
+<!-- 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:template>
+
+</xsl:stylesheet>
diff --git a/Documentation/manpage-normal.xsl b/Documentation/manpage-normal.xsl
new file mode 100644
index 0000000..6a361a2
--- /dev/null
+++ b/Documentation/manpage-normal.xsl
@@ -0,0 +1,30 @@
+<!-- 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>
+
+<!-- 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:template>
+
+</xsl:stylesheet>
-- 
1.6.2.1.214.ge986c

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

[Jeff King]

On Tue, Mar 24, 2009 at 03:04:19AM -0500, Chris Johnsen wrote:

>  Documentation/Makefile           |    2 +-
>  Documentation/callouts.xsl       |   30 ------------------------------
>  Documentation/manpage-base.xsl   |   30 ++++++++++++++++++++++++++++++
>  Documentation/manpage-normal.xsl |   30 ++++++++++++++++++++++++++++++
>  4 files changed, 61 insertions(+), 31 deletions(-)
>  delete mode 100644 Documentation/callouts.xsl
>  create mode 100644 Documentation/manpage-base.xsl
>  create mode 100644 Documentation/manpage-normal.xsl

This is definitely a good change, though it would also be fine to
actually munge the contents in the same patch rather than duplicate them
(i.e., actually _split_ callouts.xsl instead of copying it to two
places).

I think it would have been much easier to read, though, by turning on
rename detection in format-patch (i.e., "-M"). That yields:

---
 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.459.g5b99e

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

[Chris Johnsen]

On 2009 Mar 24, at 03:51, Jeff King wrote:
> On Tue, Mar 24, 2009 at 03:04:19AM -0500, Chris Johnsen wrote:
>
>>  Documentation/Makefile           |    2 +-
>>  Documentation/callouts.xsl       |   30  
>> ------------------------------
>>  Documentation/manpage-base.xsl   |   30 ++++++++++++++++++++++++++ 
>> ++++
>>  Documentation/manpage-normal.xsl |   30 ++++++++++++++++++++++++++ 
>> ++++
>>  4 files changed, 61 insertions(+), 31 deletions(-)
>>  delete mode 100644 Documentation/callouts.xsl
>>  create mode 100644 Documentation/manpage-base.xsl
>>  create mode 100644 Documentation/manpage-normal.xsl
>
> This is definitely a good change, though it would also be fine to
> actually munge the contents in the same patch rather than duplicate  
> them
> (i.e., actually _split_ callouts.xsl instead of copying it to two
> places).
>
> I think it would have been much easier to read, though, by turning on
> rename detection in format-patch (i.e., "-M"). That yields:


Thank you for looking at these. I will incorporate your feedback and  
resend in a couple of days.

I used -C -M in some early diffs to make sure it would "compress"  
like that, but I failed to do so for the final send-email.

-- 
Chris

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

[Jeff King]

On Tue, Mar 24, 2009 at 02:36:52PM -0500, Chris Johnsen wrote:

> Thank you for looking at these. I will incorporate your feedback and  
> resend in a couple of days.

Great, thanks.

> I used -C -M in some early diffs to make sure it would "compress" like 
> that, but I failed to do so for the final send-email.

FWIW, I just set diff.renames in my git repo so I don't have to remember
(the only reason not to generate renames for format-patch is if the
recipient is not using git to apply -- but it is a pretty safe
assumption that people here are using git).

-Peff

[PATCH 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.

The code reuse is achieved through the Makefile's invocation of
xmlto, where the -base and either -normal or -1.72 "modules" are
combined to render the manpages. xmlto's module system works by
constructing a temporary XSLT stylesheet that <xsl:import>s the
main docbook-xsl file and then <xsl:includes> all the modules
specified on the command line. Because of a technical detail of
XSLT (<http://www.w3.org/TR/xslt#top-level-variables>), we need
to be sure that each param is bound only once across all the
modules that will be used in a single xmlto invocation.

The initial implementation used an explicit <xsl:import> to
achieve a layering effect that allowed default param values and
override param values. That worked fine until one of the final
features of this series needed to supply override param values
via  the --stringparam option of xmlto. It turns out that
--stringparam is broken in all but the pre-release version of
xmlto. Since xmlto is a shell script the patch to fix it is
simple enough, but I instead opted to use xmlto's "module"
functionality to achieve the XSLT stylesheet reuse.

Testing done with asciidoc 8.3.1 and docbook-xsl 1.74.0.

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

---

Still no change in behavior. Just refactoring here.
---
 Documentation/Makefile           |    2 +-
 Documentation/manpage-1.72.xsl   |   28 +++++++++++---------------
 Documentation/manpage-base.xsl   |   39 +++++++++++++++++++------------------
 Documentation/manpage-normal.xsl |   29 +++++++++++----------------
 4 files changed, 45 insertions(+), 53 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index e1562e3..1b5ff36 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -165,7 +165,7 @@ $(MAN_HTML): %.html : %.txt
 
 %.1 %.5 %.7 : %.xml
 	$(RM) $@
-	xmlto -m $(MANPAGE_XSL) man $<
+	xmlto -m $(MANPAGE_XSL) -m manpage-base.xsl man $<
 
 %.xml : %.txt
 	$(RM) $@+ $@
diff --git a/Documentation/manpage-1.72.xsl b/Documentation/manpage-1.72.xsl
index 4065a3a..06d4485 100644
--- a/Documentation/manpage-1.72.xsl
+++ b/Documentation/manpage-1.72.xsl
@@ -1,21 +1,17 @@
-<!-- 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
+     must be used with manpage-base.xsl
+     handles peculiarities in docbook-xsl 1.72.0 -->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+		version="1.0">
 
+<!-- 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..be0afc9 100644
--- a/Documentation/manpage-normal.xsl
+++ b/Documentation/manpage-normal.xsl
@@ -1,21 +1,16 @@
-<!-- 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
+     must be used with manpage-base.xsl
+     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">
+
+<!-- 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.214.ge986c

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

[Jeff King]

On Tue, Mar 24, 2009 at 03:04:20AM -0500, Chris Johnsen wrote:

> +<!-- manpage-1.72.xsl:
> +     special settings for manpages rendered from asciidoc+docbook
> +     must be used with manpage-base.xsl
> +     handles peculiarities in docbook-xsl 1.72.0 -->

Hmm. I'm not sure I understood all of the issues you ran into that you
mentioned in the commit message (but trust me, having tried to do
anything with docbook, I can sympathize with the frustration you
probably felt), so maybe I am missing something. But is it not possible
to <xsl:include> manpage-base here, rather than a comment saying "Make
sure you have already included it"?

-Peff

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

[Chris Johnsen]

On 2009 Mar 24, at 03:57, Jeff King wrote:
> On Tue, Mar 24, 2009 at 03:04:20AM -0500, Chris Johnsen wrote:
>
>> +<!-- manpage-1.72.xsl:
>> +     special settings for manpages rendered from asciidoc+docbook
>> +     must be used with manpage-base.xsl
>> +     handles peculiarities in docbook-xsl 1.72.0 -->
>
> Hmm. I'm not sure I understood all of the issues you ran into that you
> mentioned in the commit message (but trust me, having tried to do
> anything with docbook, I can sympathize with the frustration you
> probably felt), so maybe I am missing something. But is it not  
> possible
> to <xsl:include> manpage-base here, rather than a comment saying "Make
> sure you have already included it"?


Right. I went overboard with reworking the XSLT into "modules" for  
xmlto.

-- 
Chris

[PATCH 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 1b5ff36..11b26aa 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.214.ge986c

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

[Jeff King]

On Tue, Mar 24, 2009 at 03:04:21AM -0500, Chris Johnsen wrote:

> 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.

Great, this looks like a definite improvement. Should we be respecting
more DOCBOOK_XSL_* variables than just 172, then? I.e.,:

> +# 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

DOCBOOK_XSL_173, etc?

I don't know that we need to cover _every_ version, but if we can have
specific knobs for individual features (like ASCIIDOC_NO_ROFF), then
maybe it makes sense to aggregate the settings for those knobs for a few
common versions.

-Peff

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

[Chris Johnsen]

On 2009 Mar 24, at 04:04, Jeff King wrote:
> On Tue, Mar 24, 2009 at 03:04:21AM -0500, Chris Johnsen wrote:
>
>> 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.
>
> Great, this looks like a definite improvement. Should we be respecting
> more DOCBOOK_XSL_* variables than just 172, then? I.e.,:
>
>> +# 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
>
> DOCBOOK_XSL_173, etc?
>
> I don't know that we need to cover _every_ version, but if we can have
> specific knobs for individual features (like ASCIIDOC_NO_ROFF), then
> maybe it makes sense to aggregate the settings for those knobs for  
> a few
> common versions.


I am not opposed to providing more version-specific controls, but I  
am not sure which versions are important enough to justify their own  
variables. Are you indicating that 1.73 is important enough because  
it was a "return to sanity" after 1.72?

The versions I listed in the comments were just the ones that the  
tools' documentation described as needing one adjustment or another.  
I thought the comments would be an easy way to start tracking which  
versions were "interesting".

-- 
Chris

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

[Jeff King]

On Tue, Mar 24, 2009 at 02:48:52PM -0500, Chris Johnsen wrote:

> I am not opposed to providing more version-specific controls, but I am not 
> sure which versions are important enough to justify their own variables. 
> Are you indicating that 1.73 is important enough because it was a "return 
> to sanity" after 1.72?

No, mainly because it is what is shipped in the last version of Debian,
which means it is a major enough version that there will be a lot of
people using it.

But let's just start with adding the tweakable knobs (which your series
is already doing), and see in what ways they need to be tweaked for
popular platforms before going overboard.

-Peff

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

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> On Tue, Mar 24, 2009 at 02:48:52PM -0500, Chris Johnsen wrote:
>
>> I am not opposed to providing more version-specific controls, but I am not 
>> sure which versions are important enough to justify their own variables. 
>> Are you indicating that 1.73 is important enough because it was a "return 
>> to sanity" after 1.72?
>
> No, mainly because it is what is shipped in the last version of Debian,
> which means it is a major enough version that there will be a lot of
> people using it.
>
> But let's just start with adding the tweakable knobs (which your series
> is already doing), and see in what ways they need to be tweaked for
> popular platforms before going overboard.

When I was trying out the series yesterday, I was wondering if this is
something we can autodetect.

Output from "asciidoc --version" is easily machine parsable for giving
asciidoc7compatible aka ASCIIDOC8, but I couldn't come up with anything
simpler than probing a few hardcoded paths under /usr/share/sgml; that
approach is unacceptable because would not work if your stylesheets are in
somewhere we do not know about.  Ideally, we should be able to ask the
tools we invoke (e.g. xmlto) to get that information.

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

[Michael J Gruber]

Junio C Hamano venit, vidit, dixit 26.03.2009 17:47:
> Jeff King <peff@peff.net> writes:
> 
>> On Tue, Mar 24, 2009 at 02:48:52PM -0500, Chris Johnsen wrote:
>>
>>> I am not opposed to providing more version-specific controls, but I am not 
>>> sure which versions are important enough to justify their own variables. 
>>> Are you indicating that 1.73 is important enough because it was a "return 
>>> to sanity" after 1.72?
>>
>> No, mainly because it is what is shipped in the last version of Debian,
>> which means it is a major enough version that there will be a lot of
>> people using it.
>>
>> But let's just start with adding the tweakable knobs (which your series
>> is already doing), and see in what ways they need to be tweaked for
>> popular platforms before going overboard.
> 
> When I was trying out the series yesterday, I was wondering if this is
> something we can autodetect.
> 
> Output from "asciidoc --version" is easily machine parsable for giving
> asciidoc7compatible aka ASCIIDOC8, but I couldn't come up with anything
> simpler than probing a few hardcoded paths under /usr/share/sgml; that
> approach is unacceptable because would not work if your stylesheets are in
> somewhere we do not know about.  Ideally, we should be able to ask the
> tools we invoke (e.g. xmlto) to get that information.

Maybe run asciidoc/xmlto on a minimal test file and check the output?
"autoconf lite", so to say.

Michael

[PATCH 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 06d4485..8b815cd 100644
--- a/Documentation/manpage-1.72.xsl
+++ b/Documentation/manpage-1.72.xsl
@@ -10,8 +10,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.214.ge986c

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

[Jeff King]

On Tue, Mar 24, 2009 at 03:04:22AM -0500, Chris Johnsen wrote:

> 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.

Digging through the archive, it is hard to say. The original patch
mentions DOCBOOK_XSL_172 as if callouts.xsl were already doing this, but
I don't see any evidence that it ever did.

Definitely an improvement, IMHO. I wonder if we also want to consider
making the "make" output a little nicer to Documentation/Makefile,
similar to how the main Makefiles just prints "CC".

-Peff

[PATCH 1/2] Documentation/Makefile: make most operations "quiet"

[Chris Johnsen]

This adapts the "quiet make" implementation from the main
Makefile.

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

There is a small conflict if this is applied on top of my
"docbook-xsl/asciidoc" cleanup. Just add the $(XMLTO_EXTRAS) back
into the command line given in this version.
---
 Documentation/Makefile |   81 +++++++++++++++++++++++++++++++----------------
 1 files changed, 53 insertions(+), 28 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 144ec32..3f9bc01 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -76,6 +76,31 @@ endif
 # yourself - yes, all 6 characters of it!
 #
 
+QUIET_SUBDIR0  = +$(MAKE) -C # space to separate -C and subdir
+QUIET_SUBDIR1  =
+
+ifneq ($(findstring $(MAKEFLAGS),w),w)
+PRINT_DIR = --no-print-directory
+else # "make -w"
+NO_SUBDIR = :
+endif
+
+ifneq ($(findstring $(MAKEFLAGS),s),s)
+ifndef V
+	QUIET_ASCIIDOC	= @echo '   ' ASCIIDOC $@;
+	QUIET_XMLTO	= @echo '   ' XMLTO $@;
+	QUIET_DB2TEXI	= @echo '   ' DB2TEXI $@;
+	QUIET_MAKEINFO	= @echo '   ' MAKEINFO $@;
+	QUIET_DBLATEX	= @echo '   ' DBLATEX $@;
+	QUIET_GEN	= @echo '   ' GEN $@;
+	QUIET_STDERR	= 2> /dev/null
+	QUIET_SUBDIR0	= +@subdir=
+	QUIET_SUBDIR1	= ;$(NO_SUBDIR) echo '   ' SUBDIR $$subdir; \
+			  $(MAKE) $(PRINT_DIR) -C $$subdir
+	export V
+endif
+endif
+
 all: html man
 
 html: $(DOC_HTML)
@@ -119,7 +144,7 @@ install-html: html
 	sh ./install-webdoc.sh $(DESTDIR)$(htmldir)
 
 ../GIT-VERSION-FILE: .FORCE-GIT-VERSION-FILE
-	$(MAKE) -C ../ GIT-VERSION-FILE
+	$(QUIET_SUBDIR0)../ $(QUIET_SUBDIR1) GIT-VERSION-FILE
 
 -include ../GIT-VERSION-FILE
 
@@ -127,8 +152,8 @@ install-html: html
 # Determine "include::" file references in asciidoc files.
 #
 doc.dep : $(wildcard *.txt) build-docdep.perl
-	$(RM) $@+ $@
-	$(PERL_PATH) ./build-docdep.perl >$@+
+	$(QUIET_GEN)$(RM) $@+ $@ && \
+	$(PERL_PATH) ./build-docdep.perl >$@+ $(QUIET_STDERR) && \
 	mv $@+ $@
 
 -include doc.dep
@@ -146,8 +171,8 @@ cmds_txt = cmds-ancillaryinterrogators.txt \
 $(cmds_txt): cmd-list.made
 
 cmd-list.made: cmd-list.perl ../command-list.txt $(MAN1_TXT)
-	$(RM) $@
-	$(PERL_PATH) ./cmd-list.perl ../command-list.txt
+	$(QUIET_GEN)$(RM) $@ && \
+	$(PERL_PATH) ./cmd-list.perl ../command-list.txt $(QUIET_STDERR) && \
 	date >$@
 
 clean:
@@ -158,30 +183,30 @@ clean:
 	$(RM) $(cmds_txt) *.made
 
 $(MAN_HTML): %.html : %.txt
-	$(RM) $@+ $@
+	$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
 	$(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf \
-		$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $<
+		$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \
 	mv $@+ $@
 
 %.1 %.5 %.7 : %.xml
-	$(RM) $@
+	$(QUIET_XMLTO)$(RM) $@ && \
 	xmlto -m $(MANPAGE_XSL) man $<
 
 %.xml : %.txt
-	$(RM) $@+ $@
+	$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
 	$(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf \
-		$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $<
+		$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \
 	mv $@+ $@
 
 user-manual.xml: user-manual.txt user-manual.conf
-	$(ASCIIDOC) -b docbook -d book $<
+	$(QUIET_ASCIIDOC)$(ASCIIDOC) -b docbook -d book $<
 
 technical/api-index.txt: technical/api-index-skel.txt \
-	technical/api-index.sh $(patsubst %,%.txt,$(API_DOCS))
+	$(QUIET_GEN)technical/api-index.sh $(patsubst %,%.txt,$(API_DOCS)) && \
 	cd technical && sh ./api-index.sh
 
 $(patsubst %,%.html,$(API_DOCS) technical/api-index): %.html : %.txt
-	$(ASCIIDOC) -b xhtml11 -f asciidoc.conf \
+	$(QUIET_ASCIIDOC)$(ASCIIDOC) -b xhtml11 -f asciidoc.conf \
 		$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) $*.txt
 
 XSLT = docbook.xsl
@@ -191,46 +216,46 @@ user-manual.html: user-manual.xml
 	xsltproc $(XSLTOPTS) -o $@ $(XSLT) $<
 
 git.info: user-manual.texi
-	$(MAKEINFO) --no-split -o $@ user-manual.texi
+	$(QUIET_MAKEINFO)$(MAKEINFO) --no-split -o $@ user-manual.texi
 
 user-manual.texi: user-manual.xml
-	$(RM) $@+ $@
+	$(QUIET_DB2TEXI)$(RM) $@+ $@ && \
 	$(DOCBOOK2X_TEXI) user-manual.xml --encoding=UTF-8 --to-stdout | \
-		$(PERL_PATH) fix-texi.perl >$@+
+		$(PERL_PATH) fix-texi.perl >$@+ && \
 	mv $@+ $@
 
 user-manual.pdf: user-manual.xml
-	$(RM) $@+ $@
-	$(DBLATEX) -o $@+ -p /etc/asciidoc/dblatex/asciidoc-dblatex.xsl -s /etc/asciidoc/dblatex/asciidoc-dblatex.sty $<
+	$(QUIET_DBLATEX)$(RM) $@+ $@ && \
+	$(DBLATEX) -o $@+ -p /etc/asciidoc/dblatex/asciidoc-dblatex.xsl -s /etc/asciidoc/dblatex/asciidoc-dblatex.sty $< && \
 	mv $@+ $@
 
 gitman.texi: $(MAN_XML) cat-texi.perl
-	$(RM) $@+ $@
+	$(QUIET_DB2TEXI)$(RM) $@+ $@ && \
 	($(foreach xml,$(MAN_XML),$(DOCBOOK2X_TEXI) --encoding=UTF-8 \
-		--to-stdout $(xml);)) | $(PERL_PATH) cat-texi.perl $@ >$@+
+		--to-stdout $(xml);)) | $(PERL_PATH) cat-texi.perl $@ >$@+ && \
 	mv $@+ $@
 
 gitman.info: gitman.texi
-	$(MAKEINFO) --no-split --no-validate $*.texi
+	$(QUIET_MAKEINFO)$(MAKEINFO) --no-split --no-validate $*.texi
 
 $(patsubst %.txt,%.texi,$(MAN_TXT)): %.texi : %.xml
-	$(RM) $@+ $@
-	$(DOCBOOK2X_TEXI) --to-stdout $*.xml >$@+
+	$(QUIET_DB2TEXI)$(RM) $@+ $@ && \
+	$(DOCBOOK2X_TEXI) --to-stdout $*.xml >$@+ && \
 	mv $@+ $@
 
 howto-index.txt: howto-index.sh $(wildcard howto/*.txt)
-	$(RM) $@+ $@
-	sh ./howto-index.sh $(wildcard howto/*.txt) >$@+
+	$(QUIET_GEN)$(RM) $@+ $@ && \
+	sh ./howto-index.sh $(wildcard howto/*.txt) >$@+ && \
 	mv $@+ $@
 
 $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt
-	$(ASCIIDOC) -b xhtml11 $*.txt
+	$(QUIET_ASCIIDOC)$(ASCIIDOC) -b xhtml11 $*.txt
 
 WEBDOC_DEST = /pub/software/scm/git/docs
 
 $(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt
-	$(RM) $@+ $@
-	sed -e '1,/^$$/d' $< | $(ASCIIDOC) -b xhtml11 - >$@+
+	$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
+	sed -e '1,/^$$/d' $< | $(ASCIIDOC) -b xhtml11 - >$@+ && \
 	mv $@+ $@
 
 install-webdoc : html
-- 
1.6.2.1.315.g33192

[PATCH 2/2] Documentation/Makefile: break up texi pipeline

[Chris Johnsen]

Most shells define the exit value of a pipeline as the exit value
of the last process. For each texi rule, run the DOCBOOK2X_TEXI
tool and the "fixup" script in their own non-pipeline commands so
that make will notice an error exit code.

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

---

This textually depends on my "quiet doc gen" patch as it modifies
a couple of the same lines.
---
 Documentation/Makefile |   11 +++++++----
 1 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 3f9bc01..372a2cc 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -177,7 +177,7 @@ cmd-list.made: cmd-list.perl ../command-list.txt $(MAN1_TXT)
 
 clean:
 	$(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7
-	$(RM) *.texi *.texi+ git.info gitman.info
+	$(RM) *.texi *.texi+ *.texi++ git.info gitman.info
 	$(RM) howto-index.txt howto/*.html doc.dep
 	$(RM) technical/api-*.html technical/api-index.txt
 	$(RM) $(cmds_txt) *.made
@@ -220,8 +220,9 @@ git.info: user-manual.texi
 
 user-manual.texi: user-manual.xml
 	$(QUIET_DB2TEXI)$(RM) $@+ $@ && \
-	$(DOCBOOK2X_TEXI) user-manual.xml --encoding=UTF-8 --to-stdout | \
-		$(PERL_PATH) fix-texi.perl >$@+ && \
+	$(DOCBOOK2X_TEXI) user-manual.xml --encoding=UTF-8 --to-stdout >$@++ && \
+	$(PERL_PATH) fix-texi.perl <$@++ >$@+ && \
+	rm $@++ && \
 	mv $@+ $@
 
 user-manual.pdf: user-manual.xml
@@ -232,7 +233,9 @@ user-manual.pdf: user-manual.xml
 gitman.texi: $(MAN_XML) cat-texi.perl
 	$(QUIET_DB2TEXI)$(RM) $@+ $@ && \
 	($(foreach xml,$(MAN_XML),$(DOCBOOK2X_TEXI) --encoding=UTF-8 \
-		--to-stdout $(xml);)) | $(PERL_PATH) cat-texi.perl $@ >$@+ && \
+		--to-stdout $(xml) &&) true) > $@++
+	$(PERL_PATH) cat-texi.perl $@ <$@++ >$@+ && \
+	rm $@++ && \
 	mv $@+ $@
 
 gitman.info: gitman.texi
-- 
1.6.2.1.315.g33192

Re: [PATCH 1/2] Documentation/Makefile: make most operations "quiet"

[Jeff King]

On Tue, Mar 24, 2009 at 11:21:39PM -0500, Chris Johnsen wrote:

>  technical/api-index.txt: technical/api-index-skel.txt \
> -	technical/api-index.sh $(patsubst %,%.txt,$(API_DOCS))
> +	$(QUIET_GEN)technical/api-index.sh $(patsubst %,%.txt,$(API_DOCS)) && \
>  	cd technical && sh ./api-index.sh

What's going on here? The line you remove is part of the dependencies,
but you replace it with a line of build instructions (and make barfs, of
course).

-Peff

Re: [PATCH 1/2] Documentation/Makefile: make most operations "quiet"

[Chris Johnsen]

On 2009 Mar 24, at 23:28, Jeff King wrote:
> On Tue, Mar 24, 2009 at 11:21:39PM -0500, Chris Johnsen wrote:
>
> >  technical/api-index.txt: technical/api-index-skel.txt \
> > -	technical/api-index.sh $(patsubst %,%.txt,$(API_DOCS))
> > +	$(QUIET_GEN)technical/api-index.sh $(patsubst %,%.txt,$(API_DOCS)) && \
> >  	cd technical && sh ./api-index.sh
>
> What's going on here? The line you remove is part of the dependencies,
> but you replace it with a line of build instructions (and make barfs, of
> course).

Yes, I botched that one. The QUIET_GEN should have been on the
next line. Thanks for catching it. I fixed it along with error
propagation and initially-also-botched "&& chaining" for
gitman.texi. I also added QUIET_XSLTPROC for user-manual.html.

I tested the man, html, info, and git-add.texi targets
(previously I only ran man and info targets; git-add.texi
exercises a rule not otherwise used in the usual targets).

An interdiff from "v1" to what I have now follows (it include
parts that would be in 1/2 and 2/2 from "v1").

-- >8 --
 Documentation/Makefile |    9 +++++----
 1 files changed, 5 insertions(+), 4 deletions(-)

diff --git c/Documentation/Makefile w/Documentation/Makefile
index 373a2cc..d145372 100644
--- c/Documentation/Makefile
+++ w/Documentation/Makefile
@@ -92,6 +92,7 @@ ifndef V
 	QUIET_DB2TEXI	= @echo '   ' DB2TEXI $@;
 	QUIET_MAKEINFO	= @echo '   ' MAKEINFO $@;
 	QUIET_DBLATEX	= @echo '   ' DBLATEX $@;
+	QUIET_XSLTPROC	= @echo '   ' XSLTPROC $@;
 	QUIET_GEN	= @echo '   ' GEN $@;
 	QUIET_STDERR	= 2> /dev/null
 	QUIET_SUBDIR0	= +@subdir=
@@ -202,8 +203,8 @@ user-manual.xml: user-manual.txt user-manual.conf
 	$(QUIET_ASCIIDOC)$(ASCIIDOC) -b docbook -d book $<
 
 technical/api-index.txt: technical/api-index-skel.txt \
-	$(QUIET_GEN)technical/api-index.sh $(patsubst %,%.txt,$(API_DOCS)) && \
-	cd technical && sh ./api-index.sh
+	technical/api-index.sh $(patsubst %,%.txt,$(API_DOCS))
+	$(QUIET_GEN)cd technical && sh ./api-index.sh
 
 $(patsubst %,%.html,$(API_DOCS) technical/api-index): %.html : %.txt
 	$(QUIET_ASCIIDOC)$(ASCIIDOC) -b xhtml11 -f asciidoc.conf \
@@ -213,7 +214,7 @@ XSLT = docbook.xsl
 XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css
 
 user-manual.html: user-manual.xml
-	xsltproc $(XSLTOPTS) -o $@ $(XSLT) $<
+	$(QUIET_XSLTPROC)xsltproc $(XSLTOPTS) -o $@ $(XSLT) $<
 
 git.info: user-manual.texi
 	$(QUIET_MAKEINFO)$(MAKEINFO) --no-split -o $@ user-manual.texi
@@ -233,7 +234,7 @@ user-manual.pdf: user-manual.xml
 gitman.texi: $(MAN_XML) cat-texi.perl
 	$(QUIET_DB2TEXI)$(RM) $@+ $@ && \
 	($(foreach xml,$(MAN_XML),$(DOCBOOK2X_TEXI) --encoding=UTF-8 \
-		--to-stdout $(xml) &&) true) > $@++
+		--to-stdout $(xml) &&) true) > $@++ && \
 	$(PERL_PATH) cat-texi.perl $@ <$@++ >$@+ && \
 	rm $@++ && \
 	mv $@+ $@

[PATCH 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 be0afc9..0412722 100644
--- a/Documentation/manpage-normal.xsl
+++ b/Documentation/manpage-normal.xsl
@@ -9,17 +9,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.214.ge986c

[PATCH 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.214.ge986c

[PATCH 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.214.ge986c

[PATCH 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.

Testing done with asciidoc 8.3.1 and docbook-xsl 1.74.0.

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

---

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 11b26aa..238ff83 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) -m manpage-base.xsl man $<
+	xmlto -m $(MANPAGE_XSL) $(XMLTO_EXTRA) -m manpage-base.xsl 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.214.ge986c

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

[Junio C Hamano]

Chris Johnsen <chris_johnsen@pobox.com> writes:

> I had a go at wrangling with the documentation generation tools
> to fix a couple of issues that I had noticed.

Thanks.  I noticed that between you and Jeff there were some more
improvements discussed, but I tried this round (queued in 'pu') and the
results lost those infamous ".ft", which is very good ;-)

I also noticed you have a two-patch series to quiet the documentation
building procedure, but didn't queue after seeing you had "oops".

I am looking forward to seeing v2 of both series.  Thanks.

And thanks, Jeff, for helping to get these series into shape.