patchdoc: remove GNU troff workaround

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

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

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:

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

Jeff King <peff@peff.net> writes:

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

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

On Tue, Mar 21, 2023 at 10:47:56AM -0700, Junio C Hamano 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).

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

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

Jeff King <peff@peff.net> writes:

Thanks.

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

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

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 <felipe.contreras@gmail.com> writes:

Thanks, all.  Queued.

Jeff King wrote:

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

On Tue, Mar 21, 2023 at 4:07 PM Todd Zullinger <tmz@pobox.com> wrote:

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 '