git.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
* [PATCH 0/6] Doc: drop support for docbook-xsl before 1.74
@ 2020-03-29 13:18 Martin Ågren
  2020-03-29 13:18 ` [PATCH 1/6] Doc: drop support for docbook-xsl before 1.71.1 Martin Ågren
                   ` (8 more replies)
  0 siblings, 9 replies; 16+ messages in thread
From: Martin Ågren @ 2020-03-29 13:18 UTC (permalink / raw)
  To: git; +Cc: Jeff King

In the documentation Makefile and a few helper conf and xsl files, we
carry various workarounds to make the docs build at all or to look
better with older docbook-xsl versions. Let's see if we can't just drop
that support. All of this seems to have been useful at one point, but I
doubt that anyone needs this nowadays. This was also suggested in [1].

The final commit in this series bumps the minimum required version of
docbook-xsl to 1.74.0, which is from June 2008. The whole series should
be a no-op unless you're on an older release than that. That said, I've
only tested this with the version that comes with my OS, 1.79.1.

After this series, user-manual.conf still refers to older docbook-xsl
versions. The proper fix there might be to actually be a bit more
aggressive and drop that hunk, making the rendered docs prettier.
There's some history there, including mentions of texinfo, which is
outside my comfort zone. I've got work in progress there, but I'd rather
submit that separately from these "expected no-op" patches.

Martin

[1] https://lore.kernel.org/git/20191030212422.GE29013@sigill.intra.peff.net/

Martin Ågren (6):
  Doc: drop support for docbook-xsl before 1.71.1
  Doc: drop support for docbook-xsl before 1.72.0
  Doc: drop support for docbook-xsl before 1.73.0
  manpage-bold-literal.xsl: stop using git.docbook.backslash
  manpage-normal.xsl: fold in manpage-base.xsl
  INSTALL: drop support for docbook-xsl before 1.74

 Documentation/Makefile                 | 23 -----------------
 Documentation/asciidoc.conf            | 19 --------------
 Documentation/manpage-1.72.xsl         | 14 -----------
 Documentation/manpage-base.xsl         | 35 --------------------------
 Documentation/manpage-bold-literal.xsl |  6 ++---
 Documentation/manpage-normal.xsl       | 25 +++++++++++++-----
 Documentation/manpage-suppress-sp.xsl  | 21 ----------------
 Makefile                               |  6 -----
 INSTALL                                |  4 +--
 9 files changed, 22 insertions(+), 131 deletions(-)
 delete mode 100644 Documentation/manpage-1.72.xsl
 delete mode 100644 Documentation/manpage-base.xsl
 delete mode 100644 Documentation/manpage-suppress-sp.xsl

-- 
2.26.0


^ permalink raw reply	[flat|nested] 16+ messages in thread

* [PATCH 1/6] Doc: drop support for docbook-xsl before 1.71.1
  2020-03-29 13:18 [PATCH 0/6] Doc: drop support for docbook-xsl before 1.74 Martin Ågren
@ 2020-03-29 13:18 ` Martin Ågren
  2020-03-29 13:18 ` [PATCH 2/6] Doc: drop support for docbook-xsl before 1.72.0 Martin Ågren
                   ` (7 subsequent siblings)
  8 siblings, 0 replies; 16+ messages in thread
From: Martin Ågren @ 2020-03-29 13:18 UTC (permalink / raw)
  To: git; +Cc: Jeff King

Drop the DOCBOOK_SUPPRESS_SP mechanism, which needs to be used with
docbook-xsl versions 1.69.1 through 1.71.0.

We probably broke this for Asciidoctor builds in f6461b82b9
("Documentation: fix build with Asciidoctor 2", 2019-09-15). That is, we
should/could fix this similar to 55aca515eb ("manpage-bold-literal.xsl:
match for namespaced "d:literal" in template", 2019-10-31). But rather
than digging out such an old version of docbook-xsl to test that, let's
just use this as an excuse for dropping this decade-old workaround.

DOCBOOK_SUPPRESS_SP was not needed with docbook-xsl 1.69.0 and older.
Maybe such old versions still work fine on our docs, or maybe not. Let's
just refer to everything before 1.71.1 as "not supported". The next
commit will increase the required/assumed version further.

Signed-off-by: Martin Ågren <martin.agren@gmail.com>
---
 Documentation/Makefile                |  7 +------
 Documentation/manpage-suppress-sp.xsl | 21 ---------------------
 INSTALL                               |  1 +
 3 files changed, 2 insertions(+), 27 deletions(-)
 delete mode 100644 Documentation/manpage-suppress-sp.xsl

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 8fe829cc1b..c7b805d1ee 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -151,9 +151,7 @@ endif
 
 #
 # For docbook-xsl ...
-#	-1.68.1,	no extra settings are needed?
-#	1.69.0,		set ASCIIDOC_ROFF?
-#	1.69.1-1.71.0,	set DOCBOOK_SUPPRESS_SP?
+#	-1.71.0,	not supported
 #	1.71.1,		set ASCIIDOC_ROFF?
 #	1.72.0,		set DOCBOOK_XSL_172.
 #	1.73.0-,	no extra settings are needed
@@ -172,9 +170,6 @@ endif
 ifndef NO_MAN_BOLD_LITERAL
 XMLTO_EXTRA += -m manpage-bold-literal.xsl
 endif
-ifdef DOCBOOK_SUPPRESS_SP
-XMLTO_EXTRA += -m manpage-suppress-sp.xsl
-endif
 
 # Newer DocBook stylesheet emits warning cruft in the output when
 # this is not set, and if set it shows an absolute link.  Older
diff --git a/Documentation/manpage-suppress-sp.xsl b/Documentation/manpage-suppress-sp.xsl
deleted file mode 100644
index a63c7632a8..0000000000
--- a/Documentation/manpage-suppress-sp.xsl
+++ /dev/null
@@ -1,21 +0,0 @@
-<!-- manpage-suppress-sp.xsl:
-     special settings for manpages rendered from asciidoc+docbook
-     handles erroneous, inline .sp in manpage output of some
-     versions of docbook-xsl -->
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
-		version="1.0">
-
-<!-- attempt to work around spurious .sp at the tail of the line
-     that some versions of 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/INSTALL b/INSTALL
index 22c364f34f..7647ce1320 100644
--- a/INSTALL
+++ b/INSTALL
@@ -206,6 +206,7 @@ Issues of note:
    clone two separate git-htmldocs and git-manpages repositories next
    to the clone of git itself.
 
+   The minimum supported version of docbook-xsl is 1.71.1.
    It has been reported that docbook-xsl version 1.72 and 1.73 are
    buggy; 1.72 misformats manual pages for callouts, and 1.73 needs
    the patch in contrib/patches/docbook-xsl-manpages-charmap.patch
-- 
2.26.0


^ permalink raw reply	[flat|nested] 16+ messages in thread

* [PATCH 2/6] Doc: drop support for docbook-xsl before 1.72.0
  2020-03-29 13:18 [PATCH 0/6] Doc: drop support for docbook-xsl before 1.74 Martin Ågren
  2020-03-29 13:18 ` [PATCH 1/6] Doc: drop support for docbook-xsl before 1.71.1 Martin Ågren
@ 2020-03-29 13:18 ` Martin Ågren
  2020-03-29 13:18 ` [PATCH 3/6] Doc: drop support for docbook-xsl before 1.73.0 Martin Ågren
                   ` (6 subsequent siblings)
  8 siblings, 0 replies; 16+ messages in thread
From: Martin Ågren @ 2020-03-29 13:18 UTC (permalink / raw)
  To: git; +Cc: Jeff King

docbook-xsl 1.72.0 is thirteen years old. Drop the ASCIIDOC_ROFF knob
which was needed to support 1.68.1 - 1.71.1. The next commit will
increase the required/assumed version further.

Signed-off-by: Martin Ågren <martin.agren@gmail.com>
---
 Documentation/Makefile      | 10 +---------
 Documentation/asciidoc.conf | 19 -------------------
 Makefile                    |  3 ---
 INSTALL                     |  2 +-
 4 files changed, 2 insertions(+), 32 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index c7b805d1ee..c7a8fc99cf 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -151,21 +151,13 @@ endif
 
 #
 # For docbook-xsl ...
-#	-1.71.0,	not supported
-#	1.71.1,		set ASCIIDOC_ROFF?
+#	-1.71.1,	not supported
 #	1.72.0,		set DOCBOOK_XSL_172.
 #	1.73.0-,	no extra settings are needed
 #
 
 ifdef DOCBOOK_XSL_172
-ASCIIDOC_EXTRA += -a git-asciidoc-no-roff
 MANPAGE_XSL = manpage-1.72.xsl
-else
-	ifndef ASCIIDOC_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
 ifndef NO_MAN_BOLD_LITERAL
 XMLTO_EXTRA += -m manpage-bold-literal.xsl
diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index 8fc4b67081..3e4c13971b 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf
@@ -31,24 +31,6 @@ ifdef::backend-docbook[]
 endif::backend-docbook[]
 
 ifdef::backend-docbook[]
-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]
-<example><title>{title}</title>
-<literallayout class="monospaced">
-ifdef::doctype-manpage[]
-&#10;.ft C&#10;
-endif::doctype-manpage[]
-|
-ifdef::doctype-manpage[]
-&#10;.ft&#10;
-endif::doctype-manpage[]
-</literallayout>
-{title#}</example>
-endif::git-asciidoc-no-roff[]
-
-ifdef::git-asciidoc-no-roff[]
 ifdef::doctype-manpage[]
 # The following two small workarounds insert a simple paragraph after screen
 [listingblock]
@@ -67,7 +49,6 @@ ifdef::doctype-manpage[]
 {title#}</para></formalpara>
 {title%}<simpara></simpara>
 endif::doctype-manpage[]
-endif::git-asciidoc-no-roff[]
 endif::backend-docbook[]
 
 ifdef::doctype-manpage[]
diff --git a/Makefile b/Makefile
index ef1ff2228f..0e0a6badc1 100644
--- a/Makefile
+++ b/Makefile
@@ -285,9 +285,6 @@ all::
 # Define DOCBOOK_XSL_172 if you want to format man pages with DocBook XSL v1.72
 # (not v1.73 or v1.71).
 #
-# Define ASCIIDOC_ROFF if your DocBook XSL does not escape raw roff directives
-# (versions 1.68.1 through v1.72).
-#
 # Define GNU_ROFF if your target system uses GNU groff.  This forces
 # apostrophes to be ASCII so that cut&pasting examples to the shell
 # will work.
diff --git a/INSTALL b/INSTALL
index 7647ce1320..07a283fcf2 100644
--- a/INSTALL
+++ b/INSTALL
@@ -206,7 +206,7 @@ Issues of note:
    clone two separate git-htmldocs and git-manpages repositories next
    to the clone of git itself.
 
-   The minimum supported version of docbook-xsl is 1.71.1.
+   The minimum supported version of docbook-xsl is 1.72.
    It has been reported that docbook-xsl version 1.72 and 1.73 are
    buggy; 1.72 misformats manual pages for callouts, and 1.73 needs
    the patch in contrib/patches/docbook-xsl-manpages-charmap.patch
-- 
2.26.0


^ permalink raw reply	[flat|nested] 16+ messages in thread

* [PATCH 3/6] Doc: drop support for docbook-xsl before 1.73.0
  2020-03-29 13:18 [PATCH 0/6] Doc: drop support for docbook-xsl before 1.74 Martin Ågren
  2020-03-29 13:18 ` [PATCH 1/6] Doc: drop support for docbook-xsl before 1.71.1 Martin Ågren
  2020-03-29 13:18 ` [PATCH 2/6] Doc: drop support for docbook-xsl before 1.72.0 Martin Ågren
@ 2020-03-29 13:18 ` Martin Ågren
  2020-03-29 13:18 ` [PATCH 4/6] manpage-bold-literal.xsl: stop using git.docbook.backslash Martin Ågren
                   ` (5 subsequent siblings)
  8 siblings, 0 replies; 16+ messages in thread
From: Martin Ågren @ 2020-03-29 13:18 UTC (permalink / raw)
  To: git; +Cc: Jeff King

Drop the DOCBOOK_XSL_172 config knob, which was needed with docbook-xsl
1.72 (but neither 1.71 nor 1.73). Version 1.73.0 is more than twelve
years old.

Together with the last few commits, we are now at a point where we don't
have any Makefile knobs to cater to old/broken versions of docbook-xsl.

Signed-off-by: Martin Ågren <martin.agren@gmail.com>
---
 Documentation/Makefile           | 10 ----------
 Documentation/manpage-1.72.xsl   | 14 --------------
 Documentation/manpage-normal.xsl |  3 +--
 Makefile                         |  3 ---
 INSTALL                          |  5 ++---
 5 files changed, 3 insertions(+), 32 deletions(-)
 delete mode 100644 Documentation/manpage-1.72.xsl

diff --git a/Documentation/Makefile b/Documentation/Makefile
index c7a8fc99cf..e235c54344 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -149,16 +149,6 @@ endif
 -include ../config.mak.autogen
 -include ../config.mak
 
-#
-# For docbook-xsl ...
-#	-1.71.1,	not supported
-#	1.72.0,		set DOCBOOK_XSL_172.
-#	1.73.0-,	no extra settings are needed
-#
-
-ifdef DOCBOOK_XSL_172
-MANPAGE_XSL = manpage-1.72.xsl
-endif
 ifndef NO_MAN_BOLD_LITERAL
 XMLTO_EXTRA += -m manpage-bold-literal.xsl
 endif
diff --git a/Documentation/manpage-1.72.xsl b/Documentation/manpage-1.72.xsl
deleted file mode 100644
index b4d315cb8c..0000000000
--- a/Documentation/manpage-1.72.xsl
+++ /dev/null
@@ -1,14 +0,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>
-
-</xsl:stylesheet>
diff --git a/Documentation/manpage-normal.xsl b/Documentation/manpage-normal.xsl
index a48f5b11f3..c9c68a0542 100644
--- a/Documentation/manpage-normal.xsl
+++ b/Documentation/manpage-normal.xsl
@@ -1,6 +1,5 @@
 <!-- manpage-normal.xsl:
-     special settings for manpages rendered from asciidoc+docbook
-     handles anything we want to keep away from docbook-xsl 1.72.0 -->
+     special settings for manpages rendered from asciidoc+docbook -->
 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
 		version="1.0">
 
diff --git a/Makefile b/Makefile
index 0e0a6badc1..b596691a12 100644
--- a/Makefile
+++ b/Makefile
@@ -282,9 +282,6 @@ all::
 # Define NO_ST_BLOCKS_IN_STRUCT_STAT if your platform does not have st_blocks
 # field that counts the on-disk footprint in 512-byte blocks.
 #
-# Define DOCBOOK_XSL_172 if you want to format man pages with DocBook XSL v1.72
-# (not v1.73 or v1.71).
-#
 # Define GNU_ROFF if your target system uses GNU groff.  This forces
 # apostrophes to be ASCII so that cut&pasting examples to the shell
 # will work.
diff --git a/INSTALL b/INSTALL
index 07a283fcf2..b244949615 100644
--- a/INSTALL
+++ b/INSTALL
@@ -206,9 +206,8 @@ Issues of note:
    clone two separate git-htmldocs and git-manpages repositories next
    to the clone of git itself.
 
-   The minimum supported version of docbook-xsl is 1.72.
-   It has been reported that docbook-xsl version 1.72 and 1.73 are
-   buggy; 1.72 misformats manual pages for callouts, and 1.73 needs
+   The minimum supported version of docbook-xsl is 1.73.
+   It has been reported that docbook-xsl version 1.73 is buggy; it needs
    the patch in contrib/patches/docbook-xsl-manpages-charmap.patch
 
    Users attempting to build the documentation on Cygwin may need to ensure
-- 
2.26.0


^ permalink raw reply	[flat|nested] 16+ messages in thread

* [PATCH 4/6] manpage-bold-literal.xsl: stop using git.docbook.backslash
  2020-03-29 13:18 [PATCH 0/6] Doc: drop support for docbook-xsl before 1.74 Martin Ågren
                   ` (2 preceding siblings ...)
  2020-03-29 13:18 ` [PATCH 3/6] Doc: drop support for docbook-xsl before 1.73.0 Martin Ågren
@ 2020-03-29 13:18 ` Martin Ågren
  2020-03-29 13:18 ` [PATCH 5/6] manpage-normal.xsl: fold in manpage-base.xsl Martin Ågren
                   ` (4 subsequent siblings)
  8 siblings, 0 replies; 16+ messages in thread
From: Martin Ågren @ 2020-03-29 13:18 UTC (permalink / raw)
  To: git; +Cc: Jeff King

We used to assign git.docbook.backslash one of two different values --
one "normal" and one for working around a problem with docbook-xsl 1.72.
After the previous commit, we don't support that version anymore and
always use the "normal" value, a literal backslash.

Just explicitly use a backslash instead of using git.docbook.backslash.
The next commit will drop the definition of git.docbook.backslash
entirely.

Signed-off-by: Martin Ågren <martin.agren@gmail.com>
---
 Documentation/manpage-bold-literal.xsl | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/Documentation/manpage-bold-literal.xsl b/Documentation/manpage-bold-literal.xsl
index 94d6c1b545..e13db85693 100644
--- a/Documentation/manpage-bold-literal.xsl
+++ b/Documentation/manpage-bold-literal.xsl
@@ -8,11 +8,9 @@
      this makes literal text easier to distinguish in manpages
      viewed on a tty -->
 <xsl:template match="literal|d:literal">
-	<xsl:value-of select="$git.docbook.backslash"/>
-	<xsl:text>fB</xsl:text>
+	<xsl:text>\fB</xsl:text>
 	<xsl:apply-templates/>
-	<xsl:value-of select="$git.docbook.backslash"/>
-	<xsl:text>fR</xsl:text>
+	<xsl:text>\fR</xsl:text>
 </xsl:template>
 
 </xsl:stylesheet>
-- 
2.26.0


^ permalink raw reply	[flat|nested] 16+ messages in thread

* [PATCH 5/6] manpage-normal.xsl: fold in manpage-base.xsl
  2020-03-29 13:18 [PATCH 0/6] Doc: drop support for docbook-xsl before 1.74 Martin Ågren
                   ` (3 preceding siblings ...)
  2020-03-29 13:18 ` [PATCH 4/6] manpage-bold-literal.xsl: stop using git.docbook.backslash Martin Ågren
@ 2020-03-29 13:18 ` Martin Ågren
  2020-03-29 13:18 ` [PATCH 6/6] INSTALL: drop support for docbook-xsl before 1.74 Martin Ågren
                   ` (3 subsequent siblings)
  8 siblings, 0 replies; 16+ messages in thread
From: Martin Ågren @ 2020-03-29 13:18 UTC (permalink / raw)
  To: git; +Cc: Jeff King

After an earlier commit, we only include manpage-base.xsl from a single
file, manpage-normal.xsl. Fold the former into the latter.

We only ever needed the "base, normal and non-normal" construct to
support a single non-normal case, namely to work around issues with
docbook-xsl 1.72 handling backslashes and dots. If we ever need
something like this again, we can re-introduce manpage-base.xsl and
friends. Whatever issue we'd be trying to work around, it probably
wouldn't involve dots and backslashes like this, anyway.

Signed-off-by: Martin Ågren <martin.agren@gmail.com>
---
 Documentation/manpage-base.xsl   | 35 --------------------------------
 Documentation/manpage-normal.xsl | 22 ++++++++++++++++----
 2 files changed, 18 insertions(+), 39 deletions(-)
 delete mode 100644 Documentation/manpage-base.xsl

diff --git a/Documentation/manpage-base.xsl b/Documentation/manpage-base.xsl
deleted file mode 100644
index a264fa6160..0000000000
--- a/Documentation/manpage-base.xsl
+++ /dev/null
@@ -1,35 +0,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">
-
-<!-- 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 -->
-<xsl:template match="co">
-	<xsl:value-of select="concat(
-			      $git.docbook.backslash,'fB(',
-			      substring-after(@id,'-'),')',
-			      $git.docbook.backslash,'fR')"/>
-</xsl:template>
-<xsl:template match="calloutlist">
-	<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(
-			      $git.docbook.backslash,'fB',
-			      substring-after(@arearefs,'-'),
-			      '. ',$git.docbook.backslash,'fR')"/>
-	<xsl:apply-templates/>
-	<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 c9c68a0542..a9c7ec69f4 100644
--- a/Documentation/manpage-normal.xsl
+++ b/Documentation/manpage-normal.xsl
@@ -3,10 +3,24 @@
 <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>
+<!-- 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 -->
+<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>
 
 </xsl:stylesheet>
-- 
2.26.0


^ permalink raw reply	[flat|nested] 16+ messages in thread

* [PATCH 6/6] INSTALL: drop support for docbook-xsl before 1.74
  2020-03-29 13:18 [PATCH 0/6] Doc: drop support for docbook-xsl before 1.74 Martin Ågren
                   ` (4 preceding siblings ...)
  2020-03-29 13:18 ` [PATCH 5/6] manpage-normal.xsl: fold in manpage-base.xsl Martin Ågren
@ 2020-03-29 13:18 ` Martin Ågren
  2020-03-30  9:26   ` Jeff King
  2020-03-29 16:27 ` [PATCH 0/6] Doc: " Junio C Hamano
                   ` (2 subsequent siblings)
  8 siblings, 1 reply; 16+ messages in thread
From: Martin Ågren @ 2020-03-29 13:18 UTC (permalink / raw)
  To: git; +Cc: Jeff King

Several of the previous commits have been bumping the minimum supported
version of docbook-xsl and dropping various workarounds. Most recently,
we made the minimum be 1.73.0.

In INSTALL, we claim that with 1.73, one needs a certain patch in
contrib/patches/. There is no such patch. It was added in 2ec39edad9
("INSTALL: add warning on docbook-xsl 1.72 and 1.73", 2007-08-03) and
dropped in 9721ac9010 ("contrib: remove continuous/ and patches/",
2013-06-03).

Rather than resurrecting version 1.73 and the patch and testing them,
just raise our minimum supported docbook-xsl version to 1.74.

Signed-off-by: Martin Ågren <martin.agren@gmail.com>
---
 INSTALL | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/INSTALL b/INSTALL
index b244949615..9ba33e6a14 100644
--- a/INSTALL
+++ b/INSTALL
@@ -206,9 +206,7 @@ Issues of note:
    clone two separate git-htmldocs and git-manpages repositories next
    to the clone of git itself.
 
-   The minimum supported version of docbook-xsl is 1.73.
-   It has been reported that docbook-xsl version 1.73 is buggy; it needs
-   the patch in contrib/patches/docbook-xsl-manpages-charmap.patch
+   The minimum supported version of docbook-xsl is 1.74.
 
    Users attempting to build the documentation on Cygwin may need to ensure
    that the /etc/xml/catalog file looks something like this:
-- 
2.26.0


^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [PATCH 0/6] Doc: drop support for docbook-xsl before 1.74
  2020-03-29 13:18 [PATCH 0/6] Doc: drop support for docbook-xsl before 1.74 Martin Ågren
                   ` (5 preceding siblings ...)
  2020-03-29 13:18 ` [PATCH 6/6] INSTALL: drop support for docbook-xsl before 1.74 Martin Ågren
@ 2020-03-29 16:27 ` Junio C Hamano
  2020-03-30  9:45 ` Jeff King
  2020-03-30 10:46 ` brian m. carlson
  8 siblings, 0 replies; 16+ messages in thread
From: Junio C Hamano @ 2020-03-29 16:27 UTC (permalink / raw)
  To: Martin Ågren; +Cc: git, Jeff King

Martin Ågren <martin.agren@gmail.com> writes:

> After this series, user-manual.conf still refers to older docbook-xsl
> versions. The proper fix there might be to actually be a bit more
> aggressive and drop that hunk, making the rendered docs prettier.
> There's some history there, including mentions of texinfo, which is
> outside my comfort zone. I've got work in progress there, but I'd rather
> submit that separately from these "expected no-op" patches.

It certainly is long overdue to write off these versions as too old
to matter.

Thanks.  Will queue.


^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [PATCH 6/6] INSTALL: drop support for docbook-xsl before 1.74
  2020-03-29 13:18 ` [PATCH 6/6] INSTALL: drop support for docbook-xsl before 1.74 Martin Ågren
@ 2020-03-30  9:26   ` Jeff King
  0 siblings, 0 replies; 16+ messages in thread
From: Jeff King @ 2020-03-30  9:26 UTC (permalink / raw)
  To: Martin Ågren; +Cc: git

On Sun, Mar 29, 2020 at 03:18:10PM +0200, Martin Ågren wrote:

> Several of the previous commits have been bumping the minimum supported
> version of docbook-xsl and dropping various workarounds. Most recently,
> we made the minimum be 1.73.0.
> 
> In INSTALL, we claim that with 1.73, one needs a certain patch in
> contrib/patches/. There is no such patch. It was added in 2ec39edad9
> ("INSTALL: add warning on docbook-xsl 1.72 and 1.73", 2007-08-03) and
> dropped in 9721ac9010 ("contrib: remove continuous/ and patches/",
> 2013-06-03).

Perhaps nobody asking about the missing patch since 2013 should be a
hint that nobody cares about these old versions. :)

> Rather than resurrecting version 1.73 and the patch and testing them,
> just raise our minimum supported docbook-xsl version to 1.74.

Makes sense.

-Peff

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [PATCH 0/6] Doc: drop support for docbook-xsl before 1.74
  2020-03-29 13:18 [PATCH 0/6] Doc: drop support for docbook-xsl before 1.74 Martin Ågren
                   ` (6 preceding siblings ...)
  2020-03-29 16:27 ` [PATCH 0/6] Doc: " Junio C Hamano
@ 2020-03-30  9:45 ` Jeff King
  2020-03-31 19:26   ` Martin Ågren
  2020-03-30 10:46 ` brian m. carlson
  8 siblings, 1 reply; 16+ messages in thread
From: Jeff King @ 2020-03-30  9:45 UTC (permalink / raw)
  To: Martin Ågren; +Cc: git

On Sun, Mar 29, 2020 at 03:18:04PM +0200, Martin Ågren wrote:

> In the documentation Makefile and a few helper conf and xsl files, we
> carry various workarounds to make the docs build at all or to look
> better with older docbook-xsl versions. Let's see if we can't just drop
> that support. All of this seems to have been useful at one point, but I
> doubt that anyone needs this nowadays. This was also suggested in [1].

Yay, I'm very happy to see this series. I'd be happy to go even further
if there's some benefit, but I think this removes the last of the
Makefile knobs.

Thanks for splitting each version bump into its own patch. That made it
a lot easier to see what we we're gaining from each one.

I double-checked that there's no difference with doc-diff when using a
modern asciidoc/docbook combo, though I'm sure you did as well.

> After this series, user-manual.conf still refers to older docbook-xsl
> versions. The proper fix there might be to actually be a bit more
> aggressive and drop that hunk, making the rendered docs prettier.
> There's some history there, including mentions of texinfo, which is
> outside my comfort zone. I've got work in progress there, but I'd rather
> submit that separately from these "expected no-op" patches.

Yeah, dropping that bit from user-manual.conf seems reasonable. That
shouldn't show anything in doc-diff because it's not installed with the
manpages. And the HTML build wouldn't use docbook. I installed the
zillion packages needed to build user-manual.pdf. The behavior without
that block looks significantly nicer (the example blocks are actually
shaded).

The very first example block in section 1.1 has some funny indentation,
but that's true before or after.

Anyway, that was just for my own curiosity. If you've got further work
in that area and prefer to do it as a separate series, that's fine by
me.

-Peff

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [PATCH 0/6] Doc: drop support for docbook-xsl before 1.74
  2020-03-29 13:18 [PATCH 0/6] Doc: drop support for docbook-xsl before 1.74 Martin Ågren
                   ` (7 preceding siblings ...)
  2020-03-30  9:45 ` Jeff King
@ 2020-03-30 10:46 ` brian m. carlson
  8 siblings, 0 replies; 16+ messages in thread
From: brian m. carlson @ 2020-03-30 10:46 UTC (permalink / raw)
  To: Martin Ågren; +Cc: git, Jeff King

[-- Attachment #1: Type: text/plain, Size: 1462 bytes --]

On 2020-03-29 at 13:18:04, Martin Ågren wrote:
> In the documentation Makefile and a few helper conf and xsl files, we
> carry various workarounds to make the docs build at all or to look
> better with older docbook-xsl versions. Let's see if we can't just drop
> that support. All of this seems to have been useful at one point, but I
> doubt that anyone needs this nowadays. This was also suggested in [1].
> 
> The final commit in this series bumps the minimum required version of
> docbook-xsl to 1.74.0, which is from June 2008. The whole series should
> be a no-op unless you're on an older release than that. That said, I've
> only tested this with the version that comes with my OS, 1.79.1.
> 
> After this series, user-manual.conf still refers to older docbook-xsl
> versions. The proper fix there might be to actually be a bit more
> aggressive and drop that hunk, making the rendered docs prettier.
> There's some history there, including mentions of texinfo, which is
> outside my comfort zone. I've got work in progress there, but I'd rather
> submit that separately from these "expected no-op" patches.

This seems sane to me and I'm all for dropping support for a
twelve-year-old version of the DocBook XSL stylesheets.  On the odd
chance that someone did need to download a newer version, this is a
dependency that's easy to set up and build.
-- 
brian m. carlson: Houston, Texas, US
OpenPGP: https://keybase.io/bk2204

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 263 bytes --]

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [PATCH 0/6] Doc: drop support for docbook-xsl before 1.74
  2020-03-30  9:45 ` Jeff King
@ 2020-03-31 19:26   ` Martin Ågren
  2020-04-01 10:17     ` Jeff King
  0 siblings, 1 reply; 16+ messages in thread
From: Martin Ågren @ 2020-03-31 19:26 UTC (permalink / raw)
  To: Jeff King; +Cc: git

On Mon, 30 Mar 2020 at 11:45, Jeff King <peff@peff.net> wrote:
>
> On Sun, Mar 29, 2020 at 03:18:04PM +0200, Martin Ågren wrote:
>
> Yay, I'm very happy to see this series. I'd be happy to go even further
> if there's some benefit, but I think this removes the last of the
> Makefile knobs.

Yes, I should have been clear about that: This does remove the last
Makefile knob. At least I couldn't find any more with some browsing and
grepping.

> > After this series, user-manual.conf still refers to older docbook-xsl
> > versions. The proper fix there might be to actually be a bit more
> > aggressive and drop that hunk, making the rendered docs prettier.
> > There's some history there, including mentions of texinfo, which is
> > outside my comfort zone. I've got work in progress there, but I'd rather
> > submit that separately from these "expected no-op" patches.
>
> Yeah, dropping that bit from user-manual.conf seems reasonable. That
> shouldn't show anything in doc-diff because it's not installed with the
> manpages. And the HTML build wouldn't use docbook. I installed the
> zillion packages needed to build user-manual.pdf. The behavior without
> that block looks significantly nicer (the example blocks are actually
> shaded).

This matches what I've seen.

> Anyway, that was just for my own curiosity. If you've got further work
> in that area and prefer to do it as a separate series, that's fine by
> me.

Not sure about "further work" really. I'm pretty sure you tried out the
exact same diff that I have, and I'm glad you agree it looks prettier /
"significantly nicer". A small part of why I didn't submit it is that
it's user manual vs man pages. Another part is that it's an intentional
change as opposed to an intended no-op.

But most importantly: When I looked into the history, I came upon
c2a7f5d438 ("docs: monospace listings in docbook output", 2012-08-07),
which made me worry about breaking "make info". On second thought, I
might have broken it many times already over the past few years, since
I've never built the info. So maybe worrying about that all of a sudden
is a bit unfounded in a way. :-/

(I tried to build "info" while working on this. It works in the sense
that it doesn't error out, but I don't get anything that looks remotely
useful. I've never used info at all though, to be honest, so could be
missing something fundamental.)

Here's what I have. I suppose it could be framed as a patch 1/7 instead.

Martin

-- >8 --
Subject: [PATCH 7/6?] user-manual.conf: don't specify [listingblock]

This is the config file we use when we build the user manual with
AsciiDoc. The comment at the top of this chunk that we're removing says
the following:

  "unbreak" docbook-xsl v1.68 for manpages (sic!). v1.69 works with or
  without this.

This comes from d19fbc3c17 ("Documentation: add git user's manual",
2007-01-07), where it looks like this conf file in general and this
snippet in particular was copy-pasted from asciidoc.conf.

This chunk is very similar to something we just got rid of for the
manpages, and because this appears to be aimed at v1.68 -- which we no
longer support for the manpages as of a few commits ago --, it's
tempting to get rid of this. That reveals an interesting aspect of
"works with or without this": it turns out it actually works /better/
without!

Dropping this makes us render code snippets and shell listings using
<screen> rather than <literallayout>, just like Asciidoctor does. In
user-manual.pdf, this puts the contents into dimmed-background,
easy-to-distinguish-from-the-surrounding-text boxes, as opposed to
white-background (transparent) boxes.

Signed-off-by: Martin Ågren <martin.agren@gmail.com>
---
 Documentation/user-manual.conf | 10 ----------
 1 file changed, 10 deletions(-)

diff --git a/Documentation/user-manual.conf b/Documentation/user-manual.conf
index d87294de2f..0148f126dc 100644
--- a/Documentation/user-manual.conf
+++ b/Documentation/user-manual.conf
@@ -9,13 +9,3 @@ tilde=&#126;
 
 [linkgit-inlinemacro]
 <ulink url="{target}.html">{target}{0?({0})}</ulink>
-
-ifdef::backend-docbook[]
-# "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this.
-[listingblock]
-<example><title>{title}</title>
-<literallayout class="monospaced">
-|
-</literallayout>
-{title#}</example>
-endif::backend-docbook[]


^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [PATCH 0/6] Doc: drop support for docbook-xsl before 1.74
  2020-03-31 19:26   ` Martin Ågren
@ 2020-04-01 10:17     ` Jeff King
  2020-04-01 16:59       ` Junio C Hamano
  2020-04-02  0:45       ` brian m. carlson
  0 siblings, 2 replies; 16+ messages in thread
From: Jeff King @ 2020-04-01 10:17 UTC (permalink / raw)
  To: Martin Ågren; +Cc: brian m. carlson, git

On Tue, Mar 31, 2020 at 09:26:00PM +0200, Martin Ågren wrote:

> But most importantly: When I looked into the history, I came upon
> c2a7f5d438 ("docs: monospace listings in docbook output", 2012-08-07),
> which made me worry about breaking "make info". On second thought, I
> might have broken it many times already over the past few years, since
> I've never built the info. So maybe worrying about that all of a sudden
> is a bit unfounded in a way. :-/
> 
> (I tried to build "info" while working on this. It works in the sense
> that it doesn't error out, but I don't get anything that looks remotely
> useful. I've never used info at all though, to be honest, so could be
> missing something fundamental.)

I don't find "info" useful, either. The big thing it offers over "man"
is actual hyperlinks, but linkgit attributes (the only thing we actually
bother annotating) don't seem to actually become links! These days I'd
expect most people interested in hyperlinking to just use HTML.  I
wouldn't be surprised if there's some emacs integration with info,
though, so maybe people use it there. I dunno. I'd be happy to see all
of the info bits go away.

I've add brian to the cc, since he was the last person to touch texi
stuff (though he may have just been doing it out of a sense of
cleanup/duty).

The .texi generated for the user-manual is the same before and after
your patch, so I think it's OK to do.

There _is_ an older regression in the user-manual, though. After commit
03920ac69b (asciidoctor: fix user-manual to be built by `asciidoctor`,
2017-01-02), the whole front-matter is missing from the generated
"git.info" file, and there's a funky ": idm4" node. Nobody seems to have
noticed or complained since then (though perhaps people are more likely
to look at the manpages than the user manual).

> -- >8 --
> Subject: [PATCH 7/6?] user-manual.conf: don't specify [listingblock]

Yeah, this looks good to me (and it looks like Junio already picked it
up on top of your series).

-Peff

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [PATCH 0/6] Doc: drop support for docbook-xsl before 1.74
  2020-04-01 10:17     ` Jeff King
@ 2020-04-01 16:59       ` Junio C Hamano
  2020-04-02  0:45       ` brian m. carlson
  1 sibling, 0 replies; 16+ messages in thread
From: Junio C Hamano @ 2020-04-01 16:59 UTC (permalink / raw)
  To: Jeff King; +Cc: Martin Ågren, brian m. carlson, git

Jeff King <peff@peff.net> writes:

>> Subject: [PATCH 7/6?] user-manual.conf: don't specify [listingblock]
>
> Yeah, this looks good to me (and it looks like Junio already picked it
> up on top of your series).

Yup, thanks, both.

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [PATCH 0/6] Doc: drop support for docbook-xsl before 1.74
  2020-04-01 10:17     ` Jeff King
  2020-04-01 16:59       ` Junio C Hamano
@ 2020-04-02  0:45       ` brian m. carlson
  2020-04-02 16:48         ` Junio C Hamano
  1 sibling, 1 reply; 16+ messages in thread
From: brian m. carlson @ 2020-04-02  0:45 UTC (permalink / raw)
  To: Jeff King; +Cc: Martin Ågren, git, Junio C Hamano

[-- Attachment #1: Type: text/plain, Size: 2900 bytes --]

On 2020-04-01 at 10:17:16, Jeff King wrote:
> On Tue, Mar 31, 2020 at 09:26:00PM +0200, Martin Ågren wrote:
> 
> > But most importantly: When I looked into the history, I came upon
> > c2a7f5d438 ("docs: monospace listings in docbook output", 2012-08-07),
> > which made me worry about breaking "make info". On second thought, I
> > might have broken it many times already over the past few years, since
> > I've never built the info. So maybe worrying about that all of a sudden
> > is a bit unfounded in a way. :-/
> > 
> > (I tried to build "info" while working on this. It works in the sense
> > that it doesn't error out, but I don't get anything that looks remotely
> > useful. I've never used info at all though, to be honest, so could be
> > missing something fundamental.)
> 
> I don't find "info" useful, either. The big thing it offers over "man"
> is actual hyperlinks, but linkgit attributes (the only thing we actually
> bother annotating) don't seem to actually become links! These days I'd
> expect most people interested in hyperlinking to just use HTML.  I
> wouldn't be surprised if there's some emacs integration with info,
> though, so maybe people use it there. I dunno. I'd be happy to see all
> of the info bits go away.

I believe Emacs does have good integration with the info format.  I
personally prefer documentation in almost any other format and would
also be happy to see it go away, but Emacs users may find it convenient.

Junio, I believe you use Emacs.  Do you have an opinion on whether, on
the whole, Emacs users are likely to make good use of the info
documentation?

> I've add brian to the cc, since he was the last person to touch texi
> stuff (though he may have just been doing it out of a sense of
> cleanup/duty).

I clearly see the commit in the history with my name on it and the
explanation seems like something I might have written, but I have no
recollection of touching that code or writing the patch at all.  I very
likely only touched it because I felt compelled not to introduce a
regression (although, as you mentioned, I failed).

> The .texi generated for the user-manual is the same before and after
> your patch, so I think it's OK to do.
> 
> There _is_ an older regression in the user-manual, though. After commit
> 03920ac69b (asciidoctor: fix user-manual to be built by `asciidoctor`,
> 2017-01-02), the whole front-matter is missing from the generated
> "git.info" file, and there's a funky ": idm4" node. Nobody seems to have
> noticed or complained since then (though perhaps people are more likely
> to look at the manpages than the user manual).

If nobody seems to care very much for the info documentation, we could
drop it.  I've put a query out on Twitter to see if anyone I know is
using it.
-- 
brian m. carlson: Houston, Texas, US
OpenPGP: https://keybase.io/bk2204

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 263 bytes --]

^ permalink raw reply	[flat|nested] 16+ messages in thread

* Re: [PATCH 0/6] Doc: drop support for docbook-xsl before 1.74
  2020-04-02  0:45       ` brian m. carlson
@ 2020-04-02 16:48         ` Junio C Hamano
  0 siblings, 0 replies; 16+ messages in thread
From: Junio C Hamano @ 2020-04-02 16:48 UTC (permalink / raw)
  To: brian m. carlson; +Cc: Jeff King, Martin Ågren, git

"brian m. carlson" <sandals@crustytoothpaste.net> writes:

> I believe Emacs does have good integration with the info format.  I
> personally prefer documentation in almost any other format and would
> also be happy to see it go away, but Emacs users may find it convenient.
>
> Junio, I believe you use Emacs.  Do you have an opinion on whether, on
> the whole, Emacs users are likely to make good use of the info
> documentation?

I probably am very atypical; I used to read even system manuals via
info in Emacs, but for the last 10 years or more, I don't.  Another
reason that makes me a bad judge is because I do not use our doc in
any formatted form---"git grep -e ... Documentation/" is easier and
faster.  So, no, I have no opinion.

> If nobody seems to care very much for the info documentation, we could
> drop it.  I've put a query out on Twitter to see if anyone I know is
> using it.

Thanks.

^ permalink raw reply	[flat|nested] 16+ messages in thread

end of thread, other threads:[~2020-04-02 16:49 UTC | newest]

Thread overview: 16+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-03-29 13:18 [PATCH 0/6] Doc: drop support for docbook-xsl before 1.74 Martin Ågren
2020-03-29 13:18 ` [PATCH 1/6] Doc: drop support for docbook-xsl before 1.71.1 Martin Ågren
2020-03-29 13:18 ` [PATCH 2/6] Doc: drop support for docbook-xsl before 1.72.0 Martin Ågren
2020-03-29 13:18 ` [PATCH 3/6] Doc: drop support for docbook-xsl before 1.73.0 Martin Ågren
2020-03-29 13:18 ` [PATCH 4/6] manpage-bold-literal.xsl: stop using git.docbook.backslash Martin Ågren
2020-03-29 13:18 ` [PATCH 5/6] manpage-normal.xsl: fold in manpage-base.xsl Martin Ågren
2020-03-29 13:18 ` [PATCH 6/6] INSTALL: drop support for docbook-xsl before 1.74 Martin Ågren
2020-03-30  9:26   ` Jeff King
2020-03-29 16:27 ` [PATCH 0/6] Doc: " Junio C Hamano
2020-03-30  9:45 ` Jeff King
2020-03-31 19:26   ` Martin Ågren
2020-04-01 10:17     ` Jeff King
2020-04-01 16:59       ` Junio C Hamano
2020-04-02  0:45       ` brian m. carlson
2020-04-02 16:48         ` Junio C Hamano
2020-03-30 10:46 ` brian m. carlson

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).