{"thread":{"id":"59423","subject":"[PATCH] doc: remove GNU troff workaround","startedAt":"2023-03-20T19:09:17Z","lastAt":"2023-03-21T22:18:10Z","messageCount":9,"participants":["Felipe Contreras","Jeff King","Junio C Hamano","Todd Zullinger"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"473798","messageId":"20230320190047.79836-1-felipe.contreras@gmail.com","threadId":"59423","inReplyTo":null,"subject":"[PATCH] doc: remove GNU troff workaround","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2023-03-20T19:00:47Z","receivedAt":"2023-03-20T19:09:17Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"In 2007 the docbook project made the mistake of converting ' to \\' for\nman pages [1]. It's a problem because groff interprets \\' as acute\naccent which is rendered as ' in ASCII, but as ´ in utf-8.\n\nThis started a cascade of bug reports in git [2], debian [3], Arch Linux\n[4], docbook itself [5], and probably many others.\n\nA solution was to use the correct groff character: \\(aq, which is always\nrendered as ', but the problem is that such character doesn't work in\nother troff programs.\n\nA portable solution required the use of a conditional character that is\n\\(aq in groff, but ' in all others:\n\n .ie \\n(.g .ds Aq \\(aq\n .el .ds Aq '\n\nThe proper solution took time to be implemented in docbook, but in 2010\nthey did it [6]. So the docbook man page stylesheets were broken from\n1.73 to 1.76.\n\nUnfortunately by that point many workarounds already existed. In the\ncase of git, GNU_ROFF was introduced, and in the case of Arch Linux\na mapping from \\' to ' was added to groff's man.local. Other\ndistributions might have done the same, or similar workarounds.\n\nSince 2010 there is no need for this workaround, which is fixed\nelsewhere, not just in docbook, but other layers as well.\n\nLet's remove it.\n\n[1] https://github.com/docbook/xslt10-stylesheets/commit/ea2a0bac56c56eec1892ac3d9254dca89f7c5746\n[2] https://lore.kernel.org/git/20091012102926.GA3937@debian.b2j/\n[3] https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=507673#65\n[4] https://bugs.archlinux.org/task/9643\n[5] https://sourceforge.net/p/docbook/bugs/1022/\n[6] https://github.com/docbook/xslt10-stylesheets/commit/fb553434265906ed81edc6d5f533d0b08d200046\n\nInspired-by: brian m. carlson \nSigned-off-by: Felipe Contreras \n---\n Documentation/Makefile | 8 --------\n Documentation/manpage-quote-apos.xsl | 16 ----------------\n Makefile | 4 ----\n 3 files changed, 28 deletions(-)\n delete mode 100644 Documentation/manpage-quote-apos.xsl\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 9c67c3a1c5..a6ba5bd460 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -191,14 +191,6 @@ MAN_BASE_URL = file://$(htmldir)/\n endif\n XMLTO_EXTRA += -m manpage-base-url.xsl\n \n-# If your target system uses GNU groff, it may try to render\n-# apostrophes as a \"pretty\" apostrophe using unicode. This breaks\n-# cut&paste, so you should set GNU_ROFF to force them to be ASCII\n-# apostrophes. Unfortunately does not work with non-GNU roff.\n-ifdef GNU_ROFF\n-XMLTO_EXTRA += -m manpage-quote-apos.xsl\n-endif\n-\n ifdef USE_ASCIIDOCTOR\n ASCIIDOC = asciidoctor\n ASCIIDOC_CONF =\ndiff --git a/Documentation/manpage-quote-apos.xsl b/Documentation/manpage-quote-apos.xsl\ndeleted file mode 100644\nindex aeb8839f33..0000000000\n--- a/Documentation/manpage-quote-apos.xsl\n+++ /dev/null\n@@ -1,16 +0,0 @@\n-\n-\n-\n-\n- \n- \n- \n- '\n- \\(aq\n- \n-\n-\n-\ndiff --git a/Makefile b/Makefile\nindex 50ee51fde3..60ab1a8b4f 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -207,10 +207,6 @@ include shared.mak\n # Define NO_ST_BLOCKS_IN_STRUCT_STAT if your platform does not have st_blocks\n # field that counts the on-disk footprint in 512-byte blocks.\n #\n-# Define GNU_ROFF if your target system uses GNU groff. This forces\n-# apostrophes to be ASCII so that cut&pasting examples to the shell\n-# will work.\n-#\n # Define USE_ASCIIDOCTOR to use Asciidoctor instead of AsciiDoc to build the\n # documentation.\n #\n-- \n2.39.2.13.g1fb56cf030\n\n"},{"id":"473855","messageId":"20230321173206.GC3119834@coredump.intra.peff.net","threadId":"59423","inReplyTo":"20230320190047.79836-1-felipe.contreras@gmail.com","subject":"Re: [PATCH] doc: remove GNU troff workaround","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2023-03-21T17:32:06Z","receivedAt":"2023-03-21T17:32:13Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Mon, Mar 20, 2023 at 01:00:47PM -0600, Felipe Contreras wrote:\n\n> Unfortunately by that point many workarounds already existed. In the\n> case of git, GNU_ROFF was introduced, and in the case of Arch Linux\n> a mapping from \\' to ' was added to groff's man.local. Other\n> distributions might have done the same, or similar workarounds.\n> \n> Since 2010 there is no need for this workaround, which is fixed\n> elsewhere, not just in docbook, but other layers as well.\n> \n> Let's remove it.\n\nThanks, it's nice to get rid of old cruft like this when it's no longer\nuseful.\n\nOne thing I wondered about, though: even if docbook fixed it in 2010,\nthe workaround is still useful for a while, as it takes time for newly\nreleased versions to be available everywhere.\n\nI'd think 13 years is probably long enough, but I was curious about the\nversions. You referenced the fix here:\n\n> [6] https://github.com/docbook/xslt10-stylesheets/commit/fb553434265906ed81edc6d5f533d0b08d200046\n\nbut the earliest tag in that repository that contains that commit is\n1.79.1 from 2016. However, it seems like that repo is oddly missing\nolder tags. You mentioned 1.76 earlier, and the changelog for the Debian\npackage of docbook-xsl mentions the 1.76 release fixing it in 2010.\n\nSo assuming the fix really was released in 2010, even long-running\ndistros like CentOS probably would have picked it up within a few years,\nand our workaround should definitely be obsolete by now.\n\n-Peff\n"},{"id":"473861","messageId":"xmqqcz52hu7n.fsf@gitster.g","threadId":"59423","inReplyTo":"20230321173206.GC3119834@coredump.intra.peff.net","subject":"Re: [PATCH] doc: remove GNU troff workaround","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-03-21T17:47:56Z","receivedAt":"2023-03-21T17:48:17Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> I'd think 13 years is probably long enough, but I was curious about the\n> versions. You referenced the fix here:\n>\n>> [6] https://github.com/docbook/xslt10-stylesheets/commit/fb553434265906ed81edc6d5f533d0b08d200046\n>\n> but the earliest tag in that repository that contains that commit is\n> 1.79.1 from 2016. However, it seems like that repo is oddly missing\n> older tags. You mentioned 1.76 earlier, and the changelog for the Debian\n> package of docbook-xsl mentions the 1.76 release fixing it in 2010.\n\nI wondered about the same thing, and did some digging myself\nyesterday. The commit seems to have been merged to their 'master'\nbranch with the commit 0418c172 (Merge branch 'master' of\n../docbook-fixed, 2015-09-20), which is after a curious 5 year gap.\n\nBut ...\n\n> So assuming the fix really was released in 2010, even long-running\n> distros like CentOS probably would have picked it up within a few years,\n> and our workaround should definitely be obsolete by now.\n\n... even if the fixed release was done in 2016, I would say that it\nshouldn't be too recent, especially for documentation where we still\ngive preformatted ones (which I think about dropping once every few\nyears).\n\n"},{"id":"473867","messageId":"20230321181702.GI3119834@coredump.intra.peff.net","threadId":"59423","inReplyTo":"xmqqcz52hu7n.fsf@gitster.g","subject":"Re: [PATCH] doc: remove GNU troff workaround","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2023-03-21T18:17:02Z","receivedAt":"2023-03-21T18:17:11Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, Mar 21, 2023 at 10:47:56AM -0700, Junio C Hamano wrote:\n\n> Jeff King writes:\n> \n> > I'd think 13 years is probably long enough, but I was curious about the\n> > versions. You referenced the fix here:\n> >\n> >> [6] https://github.com/docbook/xslt10-stylesheets/commit/fb553434265906ed81edc6d5f533d0b08d200046\n> >\n> > but the earliest tag in that repository that contains that commit is\n> > 1.79.1 from 2016. However, it seems like that repo is oddly missing\n> > older tags. You mentioned 1.76 earlier, and the changelog for the Debian\n> > package of docbook-xsl mentions the 1.76 release fixing it in 2010.\n> \n> I wondered about the same thing, and did some digging myself\n> yesterday. The commit seems to have been merged to their 'master'\n> branch with the commit 0418c172 (Merge branch 'master' of\n> ../docbook-fixed, 2015-09-20), which is after a curious 5 year gap.\n\nI suspect they were not using Git back then, and these commits were\nlater imported, which may have caused some of our confusion (searching\nfor docbook 1.76 shows releases on SourceForge, which implies a non-Git\nVCS).\n\nThe announcement of 1.76.0 in 2010 mentions a fix for the apostrophe\nissue:\n\n https://lists.oasis-open.org/archives/docbook-apps/201009/msg00023.html\n\n> > So assuming the fix really was released in 2010, even long-running\n> > distros like CentOS probably would have picked it up within a few years,\n> > and our workaround should definitely be obsolete by now.\n> \n> ... even if the fixed release was done in 2016, I would say that it\n> shouldn't be too recent, especially for documentation where we still\n> give preformatted ones (which I think about dropping once every few\n> years).\n\nI could believe that some people are still stuck on 2016-era versions of\ndependencies, but yeah, I agree we can be a little more cavalier with\ndocumentation. Anyway, I think the right date really is 2010, as above.\n\n-Peff\n"},{"id":"473870","messageId":"xmqq4jqehseb.fsf@gitster.g","threadId":"59423","inReplyTo":"20230321181702.GI3119834@coredump.intra.peff.net","subject":"Re: [PATCH] doc: remove GNU troff workaround","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-03-21T18:27:08Z","receivedAt":"2023-03-21T18:27:15Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> I could believe that some people are still stuck on 2016-era versions of\n> dependencies, but yeah, I agree we can be a little more cavalier with\n> documentation. Anyway, I think the right date really is 2010, as above.\n\nThanks.\n"},{"id":"473873","messageId":"CAMP44s22GzW6rFEEbNo8Bx3oKhf6occ6+Y8hP+vcp8bid-kqWw@mail.gmail.com","threadId":"59423","inReplyTo":"20230321181702.GI3119834@coredump.intra.peff.net","subject":"Re: [PATCH] doc: remove GNU troff workaround","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2023-03-21T18:34:51Z","receivedAt":"2023-03-21T18:35:08Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Tue, Mar 21, 2023 at 12:17 PM Jeff King wrote:\n\n> I suspect they were not using Git back then, and these commits were\n> later imported, which may have caused some of our confusion (searching\n> for docbook 1.76 shows releases on SourceForge, which implies a non-Git\n> VCS).\n\nThey were using Subversion:\nhttps://sourceforge.net/p/docbook/code/HEAD/tree/\n\n> The announcement of 1.76.0 in 2010 mentions a fix for the apostrophe\n> issue:\n>\n> https://lists.oasis-open.org/archives/docbook-apps/201009/msg00023.html\n\nThe tarball contains the fix:\nhttps://sourceforge.net/projects/docbook/files/docbook-xsl/1.76.0/\n\nSo yeah, it was fixed back in 2010.\n\n-- \nFelipe Contreras\n"},{"id":"473881","messageId":"xmqqcz51hmay.fsf@gitster.g","threadId":"59423","inReplyTo":"CAMP44s22GzW6rFEEbNo8Bx3oKhf6occ6+Y8hP+vcp8bid-kqWw@mail.gmail.com","subject":"Re: [PATCH] doc: remove GNU troff workaround","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2023-03-21T20:38:45Z","receivedAt":"2023-03-21T20:38:56Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Felipe Contreras writes:\n\n> So yeah, it was fixed back in 2010.\n\nThanks, all. Queued.\n"},{"id":"473889","messageId":"ZBoqpba+z+/lsTZC@pobox.com","threadId":"59423","inReplyTo":"20230321181702.GI3119834@coredump.intra.peff.net","subject":"Re: [PATCH] doc: remove GNU troff workaround","fromName":"Todd Zullinger","fromEmail":"tmz@pobox.com","sentAt":"2023-03-21T22:07:33Z","receivedAt":"2023-03-21T22:07:49Z","isPatch":true,"sender":{"key":"tmz@pobox.com","avatar":"https://avatars.githubusercontent.com/u/806319?v=4"},"body":"Jeff King wrote:\n> I could believe that some people are still stuck on 2016-era versions of\n> dependencies, but yeah, I agree we can be a little more cavalier with\n> documentation. Anyway, I think the right date really is 2010, as above.\n\nI tested this on with CentOS 7 ( docbook-style-xsl-1.78.1).\n\nI didn't notice any bogus curly quotes in the output. So\neven one of the older OS releases we tend to support\nshouldn't be affected by this change.\n\nHappy to see the cruft removed. :)\n\n-- \nTodd\n"},{"id":"473890","messageId":"CAMP44s38Hnhb-FjAYBQtHVRBcW7wDhd6ah3veemGSw+XdeamaA@mail.gmail.com","threadId":"59423","inReplyTo":"ZBoqpba+z+/lsTZC@pobox.com","subject":"Re: [PATCH] doc: remove GNU troff workaround","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2023-03-21T22:17:55Z","receivedAt":"2023-03-21T22:18:10Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"On Tue, Mar 21, 2023 at 4:07 PM Todd Zullinger wrote:\n>\n> Jeff King wrote:\n> > I could believe that some people are still stuck on 2016-era versions of\n> > dependencies, but yeah, I agree we can be a little more cavalier with\n> > documentation. Anyway, I think the right date really is 2010, as above.\n>\n> I tested this on with CentOS 7 ( docbook-style-xsl-1.78.1).\n>\n> I didn't notice any bogus curly quotes in the output. So\n> even one of the older OS releases we tend to support\n> shouldn't be affected by this change.\n>\n> Happy to see the cruft removed. :)\n\nFor the record, you can check that the fix is there by opening any of\nthe manpages:\n\n .\\\" http://bugs.debian.org/507673\n .\\\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html\n .\\\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n .ie \\n(.g .ds Aq \\(aq\n .el .ds Aq '\n\n-- \nFelipe Contreras\n"}]}