{"thread":{"id":"55963","subject":"[RFC/NOPATCHv3 0/4] doc: asciidoctor: direct man page creation and fixes (brian's version)","startedAt":"2021-06-18T20:31:04Z","lastAt":"2021-06-18T21:35:01Z","messageCount":9,"participants":["Felipe Contreras"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"427898","messageId":"20210618203057.790320-1-felipe.contreras@gmail.com","threadId":"55963","inReplyTo":null,"subject":"[RFC/NOPATCHv3 0/4] doc: asciidoctor: direct man page creation and fixes (brian's version)","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-18T20:30:53Z","receivedAt":"2021-06-18T20:31:04Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"I'm sending this stub series because 1. it's still in 'seen' [1], 2. my\nconflicting version is not in 'seen' [2], and 3. brian has not responded\nto my constructive criticism of his version [3].\n\nThis is exactly the same as what brian sent and is in\nbc/doc-asciidoctor-to-man-wo-xmlto, except I have split the first patch\ninto three logically separate changes, which I did suggest him to do,\nbut he didn't.\n\nTo be crystal clear: I am *NOT* proposing these patches to be merged,\nthat's why I'm marking them RFC/NOPATCH so there's no confusion.\n\nI think these should be dropped, as my series contains these changes\nalready, but split logically, with better commit messages, more fixes\nwhich reduce the doc-diff, and contains patches from both Martin Ågren\nand Jeff King, as well as many cleanups.\n\nMy version has 837 less lines of doc-diff (plus has the\n--to-asciidoctor-direct option), and also applies cleanly to master.\n\nOn top of these patches I'm going to comment all my objections (again).\n\n[1] https://lore.kernel.org/git/YMvhoXVBoO08ziI1@camp.crustytoothpaste.net/\n[2] https://lore.kernel.org/git/20210608090026.1737348-1-felipe.contreras@gmail.com/\n[3] https://lore.kernel.org/git/609ed529e2306_431272087@natae.notmuch/\n\nbrian m. carlson (4):\n  doc: add an option to have Asciidoctor build man pages directly\n  doc: add linkgit macros for asciidoctor\n  doc: use XML-style escapes only for HTML and XML\n  doc: remove GNU_ROFF option\n\n Documentation/Makefile                  | 25 +++++++++++++++----------\n Documentation/asciidoctor-extensions.rb |  2 ++\n Documentation/manpage-quote-apos.xsl    | 16 ----------------\n Makefile                                |  8 ++++----\n 4 files changed, 21 insertions(+), 30 deletions(-)\n delete mode 100644 Documentation/manpage-quote-apos.xsl\n\n-- \n2.32.0\n\n"},{"id":"427899","messageId":"20210618203057.790320-3-felipe.contreras@gmail.com","threadId":"55963","inReplyTo":"20210618203057.790320-1-felipe.contreras@gmail.com","subject":"[RFC/NOPATCHv3 2/4] doc: add linkgit macros for asciidoctor","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-18T20:30:55Z","receivedAt":"2021-06-18T20:31:07Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"From: \"brian m. carlson\" <sandals@crustytoothpaste.net>\n\nWe also need to update the code that tells Asciidoctor how to format our\nlinkgit macros so that it can output proper code for man pages.  Be\ncareful to reset the font to the previous after the change.  In order to\ndo so, we must reset to the previous after each font change so the\nprevious state at the end is the state before our inserted text, since\ntroff only remembers one previous font.  We insert \\e before each\nfont-change backslash so Asciidoctor doesn't convert them into \\*(rs,\nthe reverse solidus character, and instead leaves them as we wanted\nthem.\n\nSigned-off-by: brian m. carlson <sandals@crustytoothpaste.net>\n---\n Documentation/asciidoctor-extensions.rb | 2 ++\n 1 file changed, 2 insertions(+)\n\ndiff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb\nindex d906a00803..620b3d7a88 100644\n--- a/Documentation/asciidoctor-extensions.rb\n+++ b/Documentation/asciidoctor-extensions.rb\n@@ -15,6 +15,8 @@ module Git\n           \"#{target}(#{attrs[1]})</ulink>\"\n         elsif parent.document.basebackend? 'html'\n           %(<a href=\"#{prefix}#{target}.html\">#{target}(#{attrs[1]})</a>)\n+        elsif parent.document.basebackend? 'manpage'\n+          %(\\e\\\\fB#{target}\\e\\\\fP\\e\\\\fR(#{attrs[1]})\\e\\\\fP)\n         elsif parent.document.basebackend? 'docbook'\n           \"<citerefentry>\\n\" \\\n             \"<refentrytitle>#{target}</refentrytitle>\" \\\n-- \n2.32.0\n\n"},{"id":"427900","messageId":"20210618203057.790320-2-felipe.contreras@gmail.com","threadId":"55963","inReplyTo":"20210618203057.790320-1-felipe.contreras@gmail.com","subject":"[RFC/NOPATCHv3 1/4] doc: add an option to have Asciidoctor build man pages directly","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-18T20:30:54Z","receivedAt":"2021-06-18T20:31:08Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"From: \"brian m. carlson\" <sandals@crustytoothpaste.net>\n\nAsciidoctor contains a converter to generate man pages.  In some\nenvironments, where building only the manual pages and not the other\ndocumentation is desired, installing a toolchain for building\nDocBook-based manual pages may be burdensome, and using Asciidoctor\ndirectly may be easier, so let's add an option to build manual pages\nusing Asciidoctor without the DocBook toolchain.\n\nWe generally require Asciidoctor 1.5, but versions before 1.5.3 didn't\ncontain proper handling of the apostrophe, which is controlled normally\nby the GNU_ROFF option.  This option for the DocBook toolchain, as well\nas newer versions of Asciidoctor, makes groff output an ASCII apostrophe\ninstead of a Unicode apostrophe in text, so as to make copy and pasting\ncommands easier.  These newer versions of Asciidoctor (1.5.3 and above)\ndetect groff and do the right thing in all cases, so the GNU_ROFF option\nis obsolete in this case.\n\nBecause Asciidoctor versions before 2.0 had a few problems with man page\noutput, let's default this to off for now, since some common distros are\nstill on 1.5.  If users are using a more modern toolchain or don't care\nabout the rendering issues, they can enable the option.\n\nSuggested-by: Bagas Sanjaya <bagasdotme@gmail.com>\nOriginal-patch-by: Felipe Contreras <felipe.contreras@gmail.com>\nSigned-off-by: brian m. carlson <sandals@crustytoothpaste.net>\nSigned-off-by: Junio C Hamano <gitster@pobox.com>\n---\n Documentation/Makefile | 12 +++++++++++-\n Makefile               |  4 ++++\n 2 files changed, 15 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 81d1bf7a04..d3103c3dde 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -187,6 +187,9 @@ ASCIIDOC_EXTRA += -alitdd='&\\#x2d;&\\#x2d;'\n DBLATEX_COMMON =\n XMLTO_EXTRA += --skip-validation\n XMLTO_EXTRA += -x manpage.xsl\n+ifdef USE_ASCIIDOCTOR_MANPAGE\n+TXT_TO_MAN = $(ASCIIDOC_COMMON) -b manpage\n+endif\n endif\n \n SHELL_PATH ?= $(SHELL)\n@@ -325,7 +328,7 @@ mergetools-list.made: ../git-mergetool--lib.sh $(wildcard ../mergetools/*)\n \t\tshow_tool_names can_merge \"* \" || :' >mergetools-merge.txt && \\\n \tdate >$@\n \n-TRACK_ASCIIDOCFLAGS = $(subst ','\\'',$(ASCIIDOC_COMMON):$(ASCIIDOC_HTML):$(ASCIIDOC_DOCBOOK))\n+TRACK_ASCIIDOCFLAGS = $(subst ','\\'',$(ASCIIDOC_COMMON):$(ASCIIDOC_HTML):$(ASCIIDOC_DOCBOOK):$(USE_ASCIIDOCTOR_MANPAGE))\n \n GIT-ASCIIDOCFLAGS: FORCE\n \t@FLAGS='$(TRACK_ASCIIDOCFLAGS)'; \\\n@@ -358,9 +361,16 @@ $(OBSOLETE_HTML): %.html : %.txto asciidoc.conf asciidoctor-extensions.rb GIT-AS\n manpage-base-url.xsl: manpage-base-url.xsl.in\n \t$(QUIET_GEN)sed \"s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|\" $< > $@\n \n+ifdef TXT_TO_MAN\n+%.1 %.5 %.7 : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS\n+\t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\n+\t$(TXT_TO_MAN) -o $@+ $< && \\\n+\tmv $@+ $@\n+else\n %.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl)\n \t$(QUIET_XMLTO)$(RM) $@ && \\\n \t$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<\n+endif\n \n %.xml : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS\n \t$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \\\ndiff --git a/Makefile b/Makefile\nindex f3dc217832..48547e2c3b 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -285,6 +285,10 @@ all::\n # Define USE_ASCIIDOCTOR to use Asciidoctor instead of AsciiDoc to build the\n # documentation.\n #\n+# Define USE_ASCIIDOCTOR_MANPAGE to use Asciidoctor's manual page backend\n+# instead of building manual pages from DocBook (using xmlto).  Has no effect\n+# unless USE_ASCIIDOCTOR is set.\n+#\n # Define ASCIIDOCTOR_EXTENSIONS_LAB to point to the location of the Asciidoctor\n # Extensions Lab if you have it available.\n #\n-- \n2.32.0\n\n"},{"id":"427901","messageId":"20210618203057.790320-4-felipe.contreras@gmail.com","threadId":"55963","inReplyTo":"20210618203057.790320-1-felipe.contreras@gmail.com","subject":"[RFC/NOPATCHv3 3/4] doc: use XML-style escapes only for HTML and XML","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-18T20:30:56Z","receivedAt":"2021-06-18T20:31:09Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"From: \"brian m. carlson\" <sandals@crustytoothpaste.net>\n\nAdditionally, we don't want to use XML-style escapes for the litdd and\nplus macros, so let's only use the XML-style escapes in HTML and XML and\nuse something different for our man pages.\n\nSigned-off-by: brian m. carlson <sandals@crustytoothpaste.net>\n---\n Documentation/Makefile | 5 ++++-\n 1 file changed, 4 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex d3103c3dde..53ef100a7a 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -183,12 +183,15 @@ ASCIIDOC_HTML = xhtml5\n ASCIIDOC_DOCBOOK = docbook5\n ASCIIDOC_EXTRA += -acompat-mode -atabsize=8\n ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions\n-ASCIIDOC_EXTRA += -alitdd='&\\#x2d;&\\#x2d;'\n+TXT_TO_HTML += -alitdd='&\\#x2d;&\\#x2d;'\n+TXT_TO_XML  += -alitdd='&\\#x2d;&\\#x2d;'\n DBLATEX_COMMON =\n XMLTO_EXTRA += --skip-validation\n XMLTO_EXTRA += -x manpage.xsl\n ifdef USE_ASCIIDOCTOR_MANPAGE\n TXT_TO_MAN = $(ASCIIDOC_COMMON) -b manpage\n+TXT_TO_MAN += -aplus='+'\n+TXT_TO_MAN += -alitdd='\\--'\n endif\n endif\n \n-- \n2.32.0\n\n"},{"id":"427902","messageId":"20210618203057.790320-5-felipe.contreras@gmail.com","threadId":"55963","inReplyTo":"20210618203057.790320-1-felipe.contreras@gmail.com","subject":"[RFC/NOPATCHv3 4/4] doc: remove GNU_ROFF option","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-18T20:30:57Z","receivedAt":"2021-06-18T20:31:10Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"From: \"brian m. carlson\" <sandals@crustytoothpaste.net>\n\nBy default, groff converts apostrophes in troff source to Unicode\napostrophes.  This is helpful and desirable when being used as a\ntypesetter, since it makes the output much cleaner and more readable,\nbut it is a problem in manual pages, since apostrophes are often used\naround shell commands and these should remain in their ASCII form for\ncompatibility with the shell.\n\nFortunately, the DocBook stylesheets contain a workaround for this case:\nthey detect the special .g number register, which is set only when using\ngroff, and they define a special macro for apostrophes based on whether\nor not it is set and use that macro to write out the proper character.\nAs a result, the DocBook stylesheets handle all cases correctly\nautomatically, whether the user is using groff or not, unlike our\nGNU_ROFF code.\n\nAdditionally, this functionality was implemented in 2010.  Since nobody\nis shipping a mainstream Linux distribution with security support that\nold anymore, we can just safely assume that the user has upgraded their\nsystem in the past decade and remove the GNU_ROFF option and its\ncorresponding stylesheet altogether.\n\nSigned-off-by: brian m. carlson <sandals@crustytoothpaste.net>\nSigned-off-by: Junio C Hamano <gitster@pobox.com>\n---\n Documentation/Makefile               |  8 --------\n Documentation/manpage-quote-apos.xsl | 16 ----------------\n Makefile                             |  4 ----\n 3 files changed, 28 deletions(-)\n delete mode 100644 Documentation/manpage-quote-apos.xsl\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 53ef100a7a..53a8fa9fd3 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -168,14 +168,6 @@ MAN_BASE_URL = file://$(htmldir)/\n endif\n XMLTO_EXTRA += -m manpage-base-url.xsl\n \n-# If your target system uses GNU groff, it may try to render\n-# apostrophes as a \"pretty\" apostrophe using unicode.  This breaks\n-# cut&paste, so you should set GNU_ROFF to force them to be ASCII\n-# apostrophes.  Unfortunately does not work with non-GNU roff.\n-ifdef GNU_ROFF\n-XMLTO_EXTRA += -m manpage-quote-apos.xsl\n-endif\n-\n ifdef USE_ASCIIDOCTOR\n ASCIIDOC = asciidoctor\n ASCIIDOC_CONF =\ndiff --git a/Documentation/manpage-quote-apos.xsl b/Documentation/manpage-quote-apos.xsl\ndeleted file mode 100644\nindex aeb8839f33..0000000000\n--- a/Documentation/manpage-quote-apos.xsl\n+++ /dev/null\n@@ -1,16 +0,0 @@\n-<xsl:stylesheet xmlns:xsl=\"http://www.w3.org/1999/XSL/Transform\"\n-\t\tversion=\"1.0\">\n-\n-<!-- work around newer groff/man setups using a prettier apostrophe\n-     that unfortunately does not quote anything when cut&pasting\n-     examples to the shell -->\n-<xsl:template name=\"escape.apostrophe\">\n-  <xsl:param name=\"content\"/>\n-  <xsl:call-template name=\"string.subst\">\n-    <xsl:with-param name=\"string\" select=\"$content\"/>\n-    <xsl:with-param name=\"target\">'</xsl:with-param>\n-    <xsl:with-param name=\"replacement\">\\(aq</xsl:with-param>\n-  </xsl:call-template>\n-</xsl:template>\n-\n-</xsl:stylesheet>\ndiff --git a/Makefile b/Makefile\nindex 48547e2c3b..98484ee88c 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -278,10 +278,6 @@ all::\n # Define NO_ST_BLOCKS_IN_STRUCT_STAT if your platform does not have st_blocks\n # field that counts the on-disk footprint in 512-byte blocks.\n #\n-# Define GNU_ROFF if your target system uses GNU groff.  This forces\n-# apostrophes to be ASCII so that cut&pasting examples to the shell\n-# will work.\n-#\n # Define USE_ASCIIDOCTOR to use Asciidoctor instead of AsciiDoc to build the\n # documentation.\n #\n-- \n2.32.0\n\n"},{"id":"427905","messageId":"60cd08a716873_c0ff9208c4@natae.notmuch","threadId":"55963","inReplyTo":"20210618203057.790320-2-felipe.contreras@gmail.com","subject":"RE: [RFC/NOPATCHv3 1/4] doc: add an option to have Asciidoctor build man pages directly","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-18T20:57:11Z","receivedAt":"2021-06-18T20:57:25Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Felipe Contreras wrote:\n> From: \"brian m. carlson\" <sandals@crustytoothpaste.net>\n> \n> Asciidoctor contains a converter to generate man pages.  In some\n> environments, where building only the manual pages and not the other\n> documentation is desired, installing a toolchain for building\n> DocBook-based manual pages may be burdensome, and using Asciidoctor\n> directly may be easier, so let's add an option to build manual pages\n> using Asciidoctor without the DocBook toolchain.\n\nThis suffices:\n\n  There's no need to use xmlto to build the man pages when modern\n  asciidoctor can do it by itself.\n\n> We generally require Asciidoctor 1.5, but versions before 1.5.3 didn't\n> contain proper handling of the apostrophe, which is controlled normally\n> by the GNU_ROFF option.\n\nThis isn't true. There's no difference from 1.5, 1.5.3, 2.0.0 or even 2.0.15.\n\nThe only fix regarding apostrophes was done by me [1], it's in the\nmaster branch, but not in any release yet.\n\n> This option for the DocBook toolchain, as well\n> as newer versions of Asciidoctor, makes groff output an ASCII apostrophe\n> instead of a Unicode apostrophe in text, so as to make copy and pasting\n> commands easier.\n\nThat isn't true. GNU_ROFF is only for docbook and doesn't affect\nasciidoctor in any way.\n\n> These newer versions of Asciidoctor (1.5.3 and above)\n> detect groff and do the right thing in all cases, so the GNU_ROFF option\n> is obsolete in this case.\n\nNot true. There's nothing in 1.5.3 or any version that detects groff,\nor have anything to do with GNU_ROFF.\n\n> Because Asciidoctor versions before 2.0 had a few problems with man page\n> output, let's default this to off for now, since some common distros are\n> still on 1.5.\n\nThere's nothing from 1.5.8 to 2.0.0 that should be of interest to the\ngit project.\n\nWhat are these \"few problems\"?\n\n\nThe diff is correct, but 1) the original patch was done by me, and 2) I\nalready have the exact same version here [2].\n\nCheers.\n\n[1] https://github.com/asciidoctor/asciidoctor/commit/af0ef59538fccfbdec053b82e102a240b15cdda6\n[2] https://lore.kernel.org/git/20210521224452.530852-4-felipe.contreras@gmail.com/\n\n-- \nFelipe Contreras\n"},{"id":"427907","messageId":"60cd0a3cb4058_c0ff920813@natae.notmuch","threadId":"55963","inReplyTo":"20210618203057.790320-3-felipe.contreras@gmail.com","subject":"RE: [RFC/NOPATCHv3 2/4] doc: add linkgit macros for asciidoctor","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-18T21:03:56Z","receivedAt":"2021-06-18T21:04:01Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Felipe Contreras wrote:\n> From: \"brian m. carlson\" <sandals@crustytoothpaste.net>\n\n> --- a/Documentation/asciidoctor-extensions.rb\n> +++ b/Documentation/asciidoctor-extensions.rb\n> @@ -15,6 +15,8 @@ module Git\n>            \"#{target}(#{attrs[1]})</ulink>\"\n>          elsif parent.document.basebackend? 'html'\n>            %(<a href=\"#{prefix}#{target}.html\">#{target}(#{attrs[1]})</a>)\n> +        elsif parent.document.basebackend? 'manpage'\n> +          %(\\e\\\\fB#{target}\\e\\\\fP\\e\\\\fR(#{attrs[1]})\\e\\\\fP)\n\nThis is the same as my version [1]:\n\n  format = \"\\e\\\\fB%s\\e\\\\fP(%s)\"\n\nExcept my version is cleaner, I don't see the point in doing \\fR \\fP.\nWhat do we gain by that?\n\n[1] https://lore.kernel.org/git/20210521224452.530852-6-felipe.contreras@gmail.com/\n\n-- \nFelipe Contreras\n"},{"id":"427908","messageId":"60cd0b255b8b0_c0ff920870@natae.notmuch","threadId":"55963","inReplyTo":"20210618203057.790320-4-felipe.contreras@gmail.com","subject":"RE: [RFC/NOPATCHv3 3/4] doc: use XML-style escapes only for HTML and XML","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-18T21:07:49Z","receivedAt":"2021-06-18T21:07:54Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Felipe Contreras wrote:\n> From: \"brian m. carlson\" <sandals@crustytoothpaste.net>\n\n> --- a/Documentation/Makefile\n> +++ b/Documentation/Makefile\n> @@ -183,12 +183,15 @@ ASCIIDOC_HTML = xhtml5\n>  ASCIIDOC_DOCBOOK = docbook5\n>  ASCIIDOC_EXTRA += -acompat-mode -atabsize=8\n>  ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions\n> -ASCIIDOC_EXTRA += -alitdd='&\\#x2d;&\\#x2d;'\n> +TXT_TO_HTML += -alitdd='&\\#x2d;&\\#x2d;'\n> +TXT_TO_XML  += -alitdd='&\\#x2d;&\\#x2d;'\n>  DBLATEX_COMMON =\n>  XMLTO_EXTRA += --skip-validation\n>  XMLTO_EXTRA += -x manpage.xsl\n>  ifdef USE_ASCIIDOCTOR_MANPAGE\n>  TXT_TO_MAN = $(ASCIIDOC_COMMON) -b manpage\n> +TXT_TO_MAN += -aplus='+'\n> +TXT_TO_MAN += -alitdd='\\--'\n>  endif\n>  endif\n>  \n\nMy version of the workaround [1] is much cleaner, and doesn't mess with\nthe build system:\n\n  if doc.backend == 'manpage'\n    doc.attributes.merge!({ 'litdd' => '\\--', 'plus' => '+' })\n  end\n\nOnce asciidoctor issue #4059 is fixed [2] and in widespread use the\nabove workaround can be removed.\n\n[1] https://lore.kernel.org/git/20210521224452.530852-7-felipe.contreras@gmail.com/\n[2] https://github.com/asciidoctor/asciidoctor/issues/4059\n\n-- \nFelipe Contreras\n"},{"id":"427910","messageId":"60cd118096008_c0ff92085b@natae.notmuch","threadId":"55963","inReplyTo":"20210618203057.790320-5-felipe.contreras@gmail.com","subject":"RE: [RFC/NOPATCHv3 4/4] doc: remove GNU_ROFF option","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-18T21:34:56Z","receivedAt":"2021-06-18T21:35:01Z","isPatch":false,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Felipe Contreras wrote:\n> From: \"brian m. carlson\" <sandals@crustytoothpaste.net>\n> \n> By default, groff converts apostrophes in troff source to Unicode\n> apostrophes.\n\nThis has nothing to do with the actual problem. As stated in groff(7)\nthe apostrophe ' is converted to single closing quote \\(cq.\n\nOur problem was with acute accent \\(aa, not \\(cq.\n\nAnd it was due to docbook doing \\' where it shouldn't, not groff.\n\n> This is helpful and desirable when being used as a\n> typesetter, since it makes the output much cleaner and more readable,\n> but it is a problem in manual pages, since apostrophes are often used\n> around shell commands and these should remain in their ASCII form for\n> compatibility with the shell.\n\nmanpages should use \\(aq if they want an apostrophe quote '.\n\n> Fortunately, the DocBook stylesheets contain a workaround for this case:\n> they detect the special .g number register, which is set only when using\n> groff, and they define a special macro for apostrophes based on whether\n> or not it is set and use that macro to write out the proper character.\n\nOnce again nothing to do with the issue.\n\nThe only way in troff source to specify an apostrophe quote is using\n\\(aq, but that only works in groff. Since there's no better way to\ndescribe the same for other troff programs ' should be used for\nportability.\n\nDoing this:\n\n  .ie \\n(.g .ds Aq \\(aq\n  .el .ds Aq '\n\nis not a workaround: it's a proper implementation of a generic apostrophee\nquote that works correctly everywhere.\n\n> As a result, the DocBook stylesheets handle all cases correctly\n> automatically, whether the user is using groff or not, unlike our\n> GNU_ROFF code.\n\nYes, but you are not mentioning where it was broken, and when it was\nfixed.\n\n> Additionally, this functionality was implemented in 2010.  Since nobody\n> is shipping a mainstream Linux distribution with security support that\n> old anymore, we can just safely assume that the user has upgraded their\n> system in the past decade and remove the GNU_ROFF option and its\n> corresponding stylesheet altogether.\n\nCorrect, but my version [1] goes into much more detail with less text,\nit's actually acurate, and points exactly where docbook got broken,\nwhere it was fixed, and how other projects worked around the issue.\n\nCheers.\n\n[1] https://lore.kernel.org/git/20210608090026.1737348-2-felipe.contreras@gmail.com/\n\n-- \nFelipe Contreras\n"}]}