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