[PATCH] doc: remove GNU troff workaround

[PATCH] doc: remove GNU troff workaround

[Felipe Contreras]

In 2007 the docbook project made the mistake of converting ' to \' for
man pages [1]. It's a problem because groff interprets \' as acute
accent which is rendered as ' in ASCII, but as ´ in utf-8.

This started a cascade of bug reports in git [2], debian [3], Arch Linux
[4], docbook itself [5], and probably many others.

A solution was to use the correct groff character: \(aq, which is always
rendered as ', but the problem is that such character doesn't work in
other troff programs.

A portable solution required the use of a conditional character that is
\(aq in groff, but ' in all others:

  .ie \n(.g .ds Aq \(aq
  .el .ds Aq '

The proper solution took time to be implemented in docbook, but in 2010
they did it [6]. So the docbook man page stylesheets were broken from
1.73 to 1.76.

Unfortunately by that point many workarounds already existed. In the
case of git, GNU_ROFF was introduced, and in the case of Arch Linux
a mapping from \' to ' was added to groff's man.local. Other
distributions might have done the same, or similar workarounds.

Since 2010 there is no need for this workaround, which is fixed
elsewhere, not just in docbook, but other layers as well.

Let's remove it.

[1] https://github.com/docbook/xslt10-stylesheets/commit/ea2a0bac56c56eec1892ac3d9254dca89f7c5746
[2] https://lore.kernel.org/git/20091012102926.GA3937@debian.b2j/
[3] https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=507673#65
[4] https://bugs.archlinux.org/task/9643
[5] https://sourceforge.net/p/docbook/bugs/1022/
[6] https://github.com/docbook/xslt10-stylesheets/commit/fb553434265906ed81edc6d5f533d0b08d200046

Inspired-by: brian m. carlson <sandals@crustytoothpaste.net>
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/Makefile               |  8 --------
 Documentation/manpage-quote-apos.xsl | 16 ----------------
 Makefile                             |  4 ----
 3 files changed, 28 deletions(-)
 delete mode 100644 Documentation/manpage-quote-apos.xsl

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 9c67c3a1c5..a6ba5bd460 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -191,14 +191,6 @@ MAN_BASE_URL = file://$(htmldir)/
 endif
 XMLTO_EXTRA += -m manpage-base-url.xsl
 
-# If your target system uses GNU groff, it may try to render
-# apostrophes as a "pretty" apostrophe using unicode.  This breaks
-# cut&paste, so you should set GNU_ROFF to force them to be ASCII
-# apostrophes.  Unfortunately does not work with non-GNU roff.
-ifdef GNU_ROFF
-XMLTO_EXTRA += -m manpage-quote-apos.xsl
-endif
-
 ifdef USE_ASCIIDOCTOR
 ASCIIDOC = asciidoctor
 ASCIIDOC_CONF =
diff --git a/Documentation/manpage-quote-apos.xsl b/Documentation/manpage-quote-apos.xsl
deleted file mode 100644
index aeb8839f33..0000000000
--- a/Documentation/manpage-quote-apos.xsl
+++ /dev/null
@@ -1,16 +0,0 @@
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
-		version="1.0">
-
-<!-- work around newer groff/man setups using a prettier apostrophe
-     that unfortunately does not quote anything when cut&pasting
-     examples to the shell -->
-<xsl:template name="escape.apostrophe">
-  <xsl:param name="content"/>
-  <xsl:call-template name="string.subst">
-    <xsl:with-param name="string" select="$content"/>
-    <xsl:with-param name="target">'</xsl:with-param>
-    <xsl:with-param name="replacement">\(aq</xsl:with-param>
-  </xsl:call-template>
-</xsl:template>
-
-</xsl:stylesheet>
diff --git a/Makefile b/Makefile
index 50ee51fde3..60ab1a8b4f 100644
--- a/Makefile
+++ b/Makefile
@@ -207,10 +207,6 @@ include shared.mak
 # 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 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.
-#
 # Define USE_ASCIIDOCTOR to use Asciidoctor instead of AsciiDoc to build the
 # documentation.
 #
-- 
2.39.2.13.g1fb56cf030

Re: [PATCH] doc: remove GNU troff workaround

[Jeff King]

On Mon, Mar 20, 2023 at 01:00:47PM -0600, Felipe Contreras wrote:

> Unfortunately by that point many workarounds already existed. In the
> case of git, GNU_ROFF was introduced, and in the case of Arch Linux
> a mapping from \' to ' was added to groff's man.local. Other
> distributions might have done the same, or similar workarounds.
> 
> Since 2010 there is no need for this workaround, which is fixed
> elsewhere, not just in docbook, but other layers as well.
> 
> Let's remove it.

Thanks, it's nice to get rid of old cruft like this when it's no longer
useful.

One thing I wondered about, though: even if docbook fixed it in 2010,
the workaround is still useful for a while, as it takes time for newly
released versions to be available everywhere.

I'd think 13 years is probably long enough, but I was curious about the
versions. You referenced the fix here:

> [6] https://github.com/docbook/xslt10-stylesheets/commit/fb553434265906ed81edc6d5f533d0b08d200046

but the earliest tag in that repository that contains that commit is
1.79.1 from 2016. However, it seems like that repo is oddly missing
older tags. You mentioned 1.76 earlier, and the changelog for the Debian
package of docbook-xsl mentions the 1.76 release fixing it in 2010.

So assuming the fix really was released in 2010, even long-running
distros like CentOS probably would have picked it up within a few years,
and our workaround should definitely be obsolete by now.

-Peff

Re: [PATCH] doc: remove GNU troff workaround

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> I'd think 13 years is probably long enough, but I was curious about the
> versions. You referenced the fix here:
>
>> [6] https://github.com/docbook/xslt10-stylesheets/commit/fb553434265906ed81edc6d5f533d0b08d200046
>
> but the earliest tag in that repository that contains that commit is
> 1.79.1 from 2016. However, it seems like that repo is oddly missing
> older tags. You mentioned 1.76 earlier, and the changelog for the Debian
> package of docbook-xsl mentions the 1.76 release fixing it in 2010.

I wondered about the same thing, and did some digging myself
yesterday.  The commit seems to have been merged to their 'master'
branch with the commit 0418c172 (Merge branch 'master' of
../docbook-fixed, 2015-09-20), which is after a curious 5 year gap.

But ...

> So assuming the fix really was released in 2010, even long-running
> distros like CentOS probably would have picked it up within a few years,
> and our workaround should definitely be obsolete by now.

... even if the fixed release was done in 2016, I would say that it
shouldn't be too recent, especially for documentation where we still
give preformatted ones (which I think about dropping once every few
years).

Re: [PATCH] doc: remove GNU troff workaround

[Jeff King]

On Tue, Mar 21, 2023 at 10:47:56AM -0700, Junio C Hamano wrote:

> Jeff King <peff@peff.net> writes:
> 
> > I'd think 13 years is probably long enough, but I was curious about the
> > versions. You referenced the fix here:
> >
> >> [6] https://github.com/docbook/xslt10-stylesheets/commit/fb553434265906ed81edc6d5f533d0b08d200046
> >
> > but the earliest tag in that repository that contains that commit is
> > 1.79.1 from 2016. However, it seems like that repo is oddly missing
> > older tags. You mentioned 1.76 earlier, and the changelog for the Debian
> > package of docbook-xsl mentions the 1.76 release fixing it in 2010.
> 
> I wondered about the same thing, and did some digging myself
> yesterday.  The commit seems to have been merged to their 'master'
> branch with the commit 0418c172 (Merge branch 'master' of
> ../docbook-fixed, 2015-09-20), which is after a curious 5 year gap.

I suspect they were not using Git back then, and these commits were
later imported, which may have caused some of our confusion (searching
for docbook 1.76 shows releases on SourceForge, which implies a non-Git
VCS).

The announcement of 1.76.0 in 2010 mentions a fix for the apostrophe
issue:

  https://lists.oasis-open.org/archives/docbook-apps/201009/msg00023.html

> > So assuming the fix really was released in 2010, even long-running
> > distros like CentOS probably would have picked it up within a few years,
> > and our workaround should definitely be obsolete by now.
> 
> ... even if the fixed release was done in 2016, I would say that it
> shouldn't be too recent, especially for documentation where we still
> give preformatted ones (which I think about dropping once every few
> years).

I could believe that some people are still stuck on 2016-era versions of
dependencies, but yeah, I agree we can be a little more cavalier with
documentation. Anyway, I think the right date really is 2010, as above.

-Peff

Re: [PATCH] doc: remove GNU troff workaround

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> I could believe that some people are still stuck on 2016-era versions of
> dependencies, but yeah, I agree we can be a little more cavalier with
> documentation. Anyway, I think the right date really is 2010, as above.

Thanks.

Re: [PATCH] doc: remove GNU troff workaround

[Felipe Contreras]

On Tue, Mar 21, 2023 at 12:17 PM Jeff King <peff@peff.net> wrote:

> I suspect they were not using Git back then, and these commits were
> later imported, which may have caused some of our confusion (searching
> for docbook 1.76 shows releases on SourceForge, which implies a non-Git
> VCS).

They were using Subversion:
https://sourceforge.net/p/docbook/code/HEAD/tree/

> The announcement of 1.76.0 in 2010 mentions a fix for the apostrophe
> issue:
>
>   https://lists.oasis-open.org/archives/docbook-apps/201009/msg00023.html

The tarball contains the fix:
https://sourceforge.net/projects/docbook/files/docbook-xsl/1.76.0/

So yeah, it was fixed back in 2010.

-- 
Felipe Contreras

Re: [PATCH] doc: remove GNU troff workaround

[Junio C Hamano]

Felipe Contreras <felipe.contreras@gmail.com> writes:

> So yeah, it was fixed back in 2010.

Thanks, all.  Queued.

Re: [PATCH] doc: remove GNU troff workaround

[Todd Zullinger]

Jeff King wrote:
> I could believe that some people are still stuck on 2016-era versions of
> dependencies, but yeah, I agree we can be a little more cavalier with
> documentation. Anyway, I think the right date really is 2010, as above.

I tested this on with CentOS 7 ( docbook-style-xsl-1.78.1).

I didn't notice any bogus curly quotes in the output.  So
even one of the older OS releases we tend to support
shouldn't be affected by this change.

Happy to see the cruft removed. :)

-- 
Todd

Re: [PATCH] doc: remove GNU troff workaround

[Felipe Contreras]

On Tue, Mar 21, 2023 at 4:07 PM Todd Zullinger <tmz@pobox.com> wrote:
>
> Jeff King wrote:
> > I could believe that some people are still stuck on 2016-era versions of
> > dependencies, but yeah, I agree we can be a little more cavalier with
> > documentation. Anyway, I think the right date really is 2010, as above.
>
> I tested this on with CentOS 7 ( docbook-style-xsl-1.78.1).
>
> I didn't notice any bogus curly quotes in the output.  So
> even one of the older OS releases we tend to support
> shouldn't be affected by this change.
>
> Happy to see the cruft removed. :)

For the record, you can check that the fix is there by opening any of
the manpages:

    .\" http://bugs.debian.org/507673
    .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
    .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    .ie \n(.g .ds Aq \(aq
    .el       .ds Aq '

-- 
Felipe Contreras