diff mbox series

[2/2] doc: remove GNU_ROFF option

Message ID 20210512021138.63598-2-sandals@crustytoothpaste.net (mailing list archive)
State New
Headers show
Series [1/2] doc: add an option to have Asciidoctor build man pages directly | expand

Commit Message

brian m. carlson May 12, 2021, 2:11 a.m. UTC
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 security support for an operating system 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.
---
 Documentation/Makefile               |  8 --------
 Documentation/manpage-quote-apos.xsl | 16 ----------------
 2 files changed, 24 deletions(-)
 delete mode 100644 Documentation/manpage-quote-apos.xsl

Comments

Eric Sunshine May 12, 2021, 2:18 a.m. UTC | #1
On Tue, May 11, 2021 at 10:11 PM brian m. carlson
<sandals@crustytoothpaste.net> wrote:
> 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 security support for an operating system 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.
> ---

Missing sign-off.
brian m. carlson May 12, 2021, 2:28 a.m. UTC | #2
On 2021-05-12 at 02:18:54, Eric Sunshine wrote:
> On Tue, May 11, 2021 at 10:11 PM brian m. carlson
> <sandals@crustytoothpaste.net> wrote:
> > 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 security support for an operating system 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.
> > ---
> 
> Missing sign-off.

Thanks.  I'll add it below and if I do a reroll, I'll send out a fixed
patch.

Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
Felipe Contreras May 12, 2021, 4:45 a.m. UTC | #3
brian m. carlson wrote:
> 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 security support for an operating system 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.

I'm not sure of all that, but my machine uses Arch Linux, it ships with
groff, I've never used GNU_ROFF=1, and I can copy text with apostrophes
from the genrated man pages just fine.

So this is probably fine.
Martin Ă…gren May 13, 2021, 1:11 p.m. UTC | #4
On Wed, 12 May 2021 at 04:11, brian m. carlson
<sandals@crustytoothpaste.net> wrote:
>
> Additionally, this functionality was implemented in 2010.  Since nobody
> is shipping security support for an operating system 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.
> ---
>  Documentation/Makefile               |  8 --------
>  Documentation/manpage-quote-apos.xsl | 16 ----------------
>  2 files changed, 24 deletions(-)

Thanks for dropping this cruft. There's a blurb about GNU_ROFF in the
top-level Makefile as well. We should lose it here.

Martin
brian m. carlson May 14, 2021, 12:11 a.m. UTC | #5
On 2021-05-12 at 04:45:53, Felipe Contreras wrote:
> brian m. carlson wrote:
> > 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 security support for an operating system 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.
> 
> I'm not sure of all that, but my machine uses Arch Linux, it ships with
> groff, I've never used GNU_ROFF=1, and I can copy text with apostrophes
> from the genrated man pages just fine.

I'll rephrase to be clearer.  Solaris 10 is still security supported,
but no major Linux distro is, and I think we'll be both be fine dropping
support for OSes shipped in 2005.

I'm glad to hear confirmation that things work for you, though.
Felipe Contreras May 15, 2021, 1:30 p.m. UTC | #6
brian m. carlson wrote:
> On 2021-05-12 at 04:45:53, Felipe Contreras wrote:
> > I'm not sure of all that, but my machine uses Arch Linux, it ships with
> > groff, I've never used GNU_ROFF=1, and I can copy text with apostrophes
> > from the genrated man pages just fine.
> 
> I'll rephrase to be clearer.  Solaris 10 is still security supported,
> but no major Linux distro is, and I think we'll be both be fine dropping
> support for OSes shipped in 2005.
> 
> I'm glad to hear confirmation that things work for you, though.

I took at deep-dive and it turns Arch Linux configures groff to convert
\' to ', so even if git was doing something wrong, I wouldn't have
noticed.

Docbook fixed their problem in 2010, and I just sent a patch for
asciidoctor to properly fix their code as well. It should work on groff
though.

The configuration is in: `/usr/share/groff/site-tmac/man.local`, if you
want to check what your system is doing.

Cheers.
diff mbox series

Patch

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 536d9a5f3d..f3816772cf 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>