From: "brian m. carlson" <sandals@crustytoothpaste.net>
To: <git@vger.kernel.org>
Cc: "Felipe Contreras" <felipe.contreras@gmail.com>,
"Martin Ågren" <martin.agren@gmail.com>,
"Bagas Sanjaya" <bagasdotme@gmail.com>,
"Jeff King" <peff@peff.net>
Subject: [PATCH v2 2/2] doc: remove GNU_ROFF option
Date: Fri, 14 May 2021 00:31:04 +0000 [thread overview]
Message-ID: <20210514003104.94644-3-sandals@crustytoothpaste.net> (raw)
In-Reply-To: <20210514003104.94644-1-sandals@crustytoothpaste.net>
By default, groff converts apostrophes in troff source to Unicode
apostrophes. This is helpful and desirable when being used as a
typesetter, since it makes the output much cleaner and more readable,
but it is a problem in manual pages, since apostrophes are often used
around shell commands and these should remain in their ASCII form for
compatibility with the shell.
Fortunately, the DocBook stylesheets contain a workaround for this case:
they detect the special .g number register, which is set only when using
groff, and they define a special macro for apostrophes based on whether
or not it is set and use that macro to write out the proper character.
As a result, the DocBook stylesheets handle all cases correctly
automatically, whether the user is using groff or not, unlike our
GNU_ROFF code.
Additionally, this functionality was implemented in 2010. Since nobody
is shipping a mainstream Linux distribution with security support that
old anymore, we can just safely assume that the user has upgraded their
system in the past decade and remove the GNU_ROFF option and its
corresponding stylesheet altogether.
Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
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 891181c0f3..19dc5a2974 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -177,14 +177,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 e499152ba2..f186fd4753 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.
#
next prev parent reply other threads:[~2021-05-14 0:31 UTC|newest]
Thread overview: 45+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-05-11 22:27 [PATCH] doc: use asciidoctor to build man pages directly Felipe Contreras
2021-05-11 23:26 ` brian m. carlson
2021-05-12 0:58 ` Felipe Contreras
2021-05-12 2:11 ` [PATCH 1/2] doc: add an option to have Asciidoctor " brian m. carlson
2021-05-12 2:11 ` [PATCH 2/2] doc: remove GNU_ROFF option brian m. carlson
2021-05-12 2:18 ` Eric Sunshine
2021-05-12 2:28 ` brian m. carlson
2021-05-12 4:45 ` Felipe Contreras
2021-05-14 0:11 ` brian m. carlson
2021-05-15 13:30 ` Felipe Contreras
2021-05-13 13:11 ` Martin Ågren
2021-05-12 2:48 ` [PATCH 1/2] doc: add an option to have Asciidoctor build man pages directly Bagas Sanjaya
2021-05-12 5:03 ` Felipe Contreras
2021-05-13 23:24 ` brian m. carlson
2021-05-14 12:58 ` Felipe Contreras
2021-05-15 13:25 ` Felipe Contreras
2021-05-12 4:41 ` Felipe Contreras
2021-05-13 23:38 ` brian m. carlson
2021-05-14 19:02 ` Felipe Contreras
2021-05-12 4:43 ` Bagas Sanjaya
2021-05-13 23:54 ` brian m. carlson
2021-05-12 6:22 ` Jeff King
2021-05-12 6:30 ` Jeff King
2021-05-12 6:59 ` Jeff King
2021-05-12 19:29 ` Felipe Contreras
2021-05-13 17:30 ` Martin Ågren
2021-05-13 22:37 ` Felipe Contreras
2021-05-12 19:53 ` Eric Sunshine
2021-05-12 22:37 ` Jeff King
2021-05-14 15:34 ` Martin Ågren
2021-05-14 0:31 ` [PATCH v2 0/2] Asciidoctor native manpage builds brian m. carlson
2021-05-14 0:31 ` [PATCH v2 1/2] doc: add an option to have Asciidoctor build man pages directly brian m. carlson
2021-05-14 3:58 ` Junio C Hamano
2021-05-14 5:27 ` Jeff King
2021-05-14 20:00 ` Felipe Contreras
2021-05-14 19:55 ` brian m. carlson
2021-05-14 20:52 ` Felipe Contreras
2021-05-14 19:57 ` Felipe Contreras
2021-05-14 19:53 ` Felipe Contreras
2021-05-14 20:17 ` brian m. carlson
2021-05-14 23:31 ` Felipe Contreras
2021-05-14 0:31 ` brian m. carlson [this message]
2021-05-14 19:07 ` [PATCH v2 0/2] Asciidoctor native manpage builds Felipe Contreras
2021-05-14 20:00 ` brian m. carlson
2021-05-14 21:21 ` 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=20210514003104.94644-3-sandals@crustytoothpaste.net \
--to=sandals@crustytoothpaste.net \
--cc=bagasdotme@gmail.com \
--cc=felipe.contreras@gmail.com \
--cc=git@vger.kernel.org \
--cc=martin.agren@gmail.com \
--cc=peff@peff.net \
/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
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).