| Message ID | 20230320190047.79836-1-felipe.contreras@gmail.com (mailing list archive) |
|---|---|
| State | Accepted |
| Commit | ee6ad78260e75bd803f87c371db5912490a0d788 |
| Headers | show |
| Series | doc: remove GNU troff workaround | expand |
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
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).
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
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.
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 <felipe.contreras@gmail.com> writes:
> So yeah, it was fixed back in 2010.
Thanks, all. Queued.
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. :)
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 '
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. #
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