diff mbox series

[RFC/NOPATCHv3,4/4] doc: remove GNU_ROFF option

Message ID 20210618203057.790320-5-felipe.contreras@gmail.com (mailing list archive)
State New
Headers show
Series doc: asciidoctor: direct man page creation and fixes (brian's version) | expand

Commit Message

Felipe Contreras June 18, 2021, 8:30 p.m. UTC
From: "brian m. carlson" <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>
Signed-off-by: Junio C Hamano <gitster@pobox.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

Comments

Felipe Contreras June 18, 2021, 9:34 p.m. UTC | #1
Felipe Contreras wrote:
> From: "brian m. carlson" <sandals@crustytoothpaste.net>
> 
> By default, groff converts apostrophes in troff source to Unicode
> apostrophes.

This has nothing to do with the actual problem. As stated in groff(7)
the apostrophe ' is converted to single closing quote \(cq.

Our problem was with acute accent \(aa, not \(cq.

And it was due to docbook doing \' where it shouldn't, not groff.

> 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.

manpages should use \(aq if they want an apostrophe quote '.

> 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.

Once again nothing to do with the issue.

The only way in troff source to specify an apostrophe quote is using
\(aq, but that only works in groff. Since there's no better way to
describe the same for other troff programs ' should be used for
portability.

Doing this:

  .ie \n(.g .ds Aq \(aq
  .el .ds Aq '

is not a workaround: it's a proper implementation of a generic apostrophee
quote that works correctly everywhere.

> As a result, the DocBook stylesheets handle all cases correctly
> automatically, whether the user is using groff or not, unlike our
> GNU_ROFF code.

Yes, but you are not mentioning where it was broken, and when it was
fixed.

> 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.

Correct, but my version [1] goes into much more detail with less text,
it's actually acurate, and points exactly where docbook got broken,
where it was fixed, and how other projects worked around the issue.

Cheers.

[1] https://lore.kernel.org/git/20210608090026.1737348-2-felipe.contreras@gmail.com/
diff mbox series

Patch

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 53ef100a7a..53a8fa9fd3 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -168,14 +168,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 48547e2c3b..98484ee88c 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.
 #