From: Felipe Contreras <felipe.contreras@gmail.com> To: git@vger.kernel.org Cc: "Junio C Hamano" <gitster@pobox.com>, "Martin Ågren" <martin.agren@gmail.com>, "brian m . carlson" <sandals@crustytoothpaste.net>, "Felipe Contreras" <felipe.contreras@gmail.com> Subject: [PATCH 01/12] doc: remove GNU troff workaround Date: Sat, 15 May 2021 06:56:42 -0500 [thread overview] Message-ID: <20210515115653.922902-2-felipe.contreras@gmail.com> (raw) In-Reply-To: <20210515115653.922902-1-felipe.contreras@gmail.com> 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 mappig from \' to ' was added to groff's man.local. Other distributions might have done the same, or similar workarounds. Since 2010 there is not need for this workaround, which is fixed elsewhere not just in docbook, but other layers as well. Let's remove it. Also, it's GNU troff, not GNU roff. [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 f5605b7767..bf1f66b3eb 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -178,14 +178,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 diff --git a/Makefile b/Makefile index 93664d6714..2a94cef62f 100644 --- a/Makefile +++ b/Makefile @@ -278,10 +278,6 @@ all:: # 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.31.1
next prev parent reply other threads:[~2021-05-15 11:57 UTC|newest] Thread overview: 13+ messages / expand[flat|nested] mbox.gz Atom feed top 2021-05-15 11:56 [PATCH 00/12] doc: cleanup old cruft and asciidoctor revamp Felipe Contreras 2021-05-15 11:56 ` Felipe Contreras [this message] 2021-05-15 11:56 ` [PATCH 02/12] doc: use --stringparam in xmlto Felipe Contreras 2021-05-15 11:56 ` [PATCH 03/12] doc: simplify version passing Felipe Contreras 2021-05-15 11:56 ` [PATCH 04/12] doc: asciidoc: remove unnecessary attribute Felipe Contreras 2021-05-15 11:56 ` [PATCH 05/12] doc: asciidoctor: remove unnecessary require Felipe Contreras 2021-05-15 11:56 ` [PATCH 06/12] doc: asciidoctor: remove cruft Felipe Contreras 2021-05-15 11:56 ` [PATCH 07/12] doc: asciidoctor: reorganize extensions Felipe Contreras 2021-05-15 11:56 ` [PATCH 08/12] doc: asciidoctor: use html-prefix only for html Felipe Contreras 2021-05-15 11:56 ` [PATCH 09/12] doc: asciidoctor: refactor macro registration Felipe Contreras 2021-05-15 11:56 ` [PATCH 10/12] doc: asciidoctor: improve string handling Felipe Contreras 2021-05-15 11:56 ` [PATCH 11/12] doc: asciidoctor: split the format from the code Felipe Contreras 2021-05-15 11:56 ` [PATCH 12/12] doc: asciidoctor: specify name of our group Felipe Contreras
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to=20210515115653.922902-2-felipe.contreras@gmail.com \ --to=felipe.contreras@gmail.com \ --cc=git@vger.kernel.org \ --cc=gitster@pobox.com \ --cc=martin.agren@gmail.com \ --cc=sandals@crustytoothpaste.net \ --subject='Re: [PATCH 01/12] doc: remove GNU troff workaround' \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: link
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).