From def3ce00aebc3d30df34393518a38f334875a4c3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Martin=20=C3=85gren?= Date: Sun, 29 Mar 2020 15:18:05 +0200 Subject: [PATCH 1/7] Doc: drop support for docbook-xsl before 1.71.1 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Signed-off-by: Junio C Hamano --- 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 @@ - - - - - - - - - - - - - - - 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 From 40b970078b3037c647fe8975724f55bbf63b8e9a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Martin=20=C3=85gren?= Date: Sun, 29 Mar 2020 15:18:06 +0200 Subject: [PATCH 2/7] Doc: drop support for docbook-xsl before 1.72.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Signed-off-by: Junio C Hamano --- Documentation/Makefile | 10 +--------- Documentation/asciidoc.conf | 19 ------------------- INSTALL | 2 +- Makefile | 3 --- 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] -{title} - -ifdef::doctype-manpage[] - .ft C -endif::doctype-manpage[] -| -ifdef::doctype-manpage[] - .ft -endif::doctype-manpage[] - -{title#} -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#} {title%} endif::doctype-manpage[] -endif::git-asciidoc-no-roff[] endif::backend-docbook[] ifdef::doctype-manpage[] 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 diff --git a/Makefile b/Makefile index 9804a0758b..504d24a1a6 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. From 388f5b52b0093f83957f1b4f42718d3adb0e6f72 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Martin=20=C3=85gren?= Date: Sun, 29 Mar 2020 15:18:07 +0200 Subject: [PATCH 3/7] Doc: drop support for docbook-xsl before 1.73.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Signed-off-by: Junio C Hamano --- Documentation/Makefile | 10 ---------- Documentation/manpage-1.72.xsl | 14 -------------- Documentation/manpage-normal.xsl | 3 +-- INSTALL | 5 ++--- Makefile | 3 --- 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 @@ - - - - - - -▓ -⌂ - - 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 @@ + special settings for manpages rendered from asciidoc+docbook --> 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 diff --git a/Makefile b/Makefile index 504d24a1a6..2a4da89941 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. From 4344be057e1f7175476b367e66c87b32d56de050 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Martin=20=C3=85gren?= Date: Sun, 29 Mar 2020 15:18:08 +0200 Subject: [PATCH 4/7] manpage-bold-literal.xsl: stop using git.docbook.backslash MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Signed-off-by: Junio C Hamano --- 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 --> - - fB + \fB - - fR + \fR From f7421a14387e4d4e45e2ce579dc941f33e4ff8d9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Martin=20=C3=85gren?= Date: Sun, 29 Mar 2020 15:18:09 +0200 Subject: [PATCH 5/7] manpage-normal.xsl: fold in manpage-base.xsl MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Signed-off-by: Junio C Hamano --- 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 @@ - - - - - - - - - - - - - - sp - - - - - - - - br - - - 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 @@ - - -\ -. + + + + + + + + + + .sp + + + + + + + .br + From 5a80d85bbe00cdaf4fc6d58ac26216090f5eac7a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Martin=20=C3=85gren?= Date: Sun, 29 Mar 2020 15:18:10 +0200 Subject: [PATCH 6/7] INSTALL: drop support for docbook-xsl before 1.74 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Signed-off-by: Junio C Hamano --- 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: From 3c255ad660b03c7bb372b01b6dcaf67023fb2886 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Martin=20=C3=85gren?= Date: Tue, 31 Mar 2020 21:26:00 +0200 Subject: [PATCH 7/7] user-manual.conf: don't specify [listingblock] MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 rather than , 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 Signed-off-by: Junio C Hamano --- 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=~ [linkgit-inlinemacro] {target}{0?({0})} - -ifdef::backend-docbook[] -# "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this. -[listingblock] -{title} - -| - -{title#} -endif::backend-docbook[]