doc: 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> Reviewed-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Felipe Contreras committed Mar 20, 2023 at 13:00 UTC ee6ad78260e75bd803f87c371db5912490a0d788
3 files changed -28
Documentation/Makefile
-8
@@ -191,14 +191,6 @@ MAN_BASE_URL = file://$(htmldir)/
191 endif
192 XMLTO_EXTRA += -m manpage-base-url.xsl
193
194 -# If your target system uses GNU groff, it may try to render
195 -# apostrophes as a "pretty" apostrophe using unicode. This breaks
196 -# cut&paste, so you should set GNU_ROFF to force them to be ASCII
197 -# apostrophes. Unfortunately does not work with non-GNU roff.
198 -ifdef GNU_ROFF
199 -XMLTO_EXTRA += -m manpage-quote-apos.xsl
200 -endif
201 -
194 ifdef USE_ASCIIDOCTOR
195 ASCIIDOC = asciidoctor
196 ASCIIDOC_CONF =
Documentation/manpage-quote-apos.xsl deleted
-16
@@ -1,16 +0,0 @@
1 -<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
2 - version="1.0">
3 -
4 -<!-- work around newer groff/man setups using a prettier apostrophe
5 - that unfortunately does not quote anything when cut&pasting
6 - examples to the shell -->
7 -<xsl:template name="escape.apostrophe">
8 - <xsl:param name="content"/>
9 - <xsl:call-template name="string.subst">
10 - <xsl:with-param name="string" select="$content"/>
11 - <xsl:with-param name="target">'</xsl:with-param>
12 - <xsl:with-param name="replacement">\(aq</xsl:with-param>
13 - </xsl:call-template>
14 -</xsl:template>
15 -
16 -</xsl:stylesheet>
Makefile
-4
@@ -207,10 +207,6 @@ include shared.mak
207 # Define NO_ST_BLOCKS_IN_STRUCT_STAT if your platform does not have st_blocks
208 # field that counts the on-disk footprint in 512-byte blocks.
209 #
210 -# Define GNU_ROFF if your target system uses GNU groff. This forces
211 -# apostrophes to be ASCII so that cut&pasting examples to the shell
212 -# will work.
213 -#
210 # Define USE_ASCIIDOCTOR to use Asciidoctor instead of AsciiDoc to build the
211 # documentation.
212 #