{"thread":{"id":"55964","subject":"[PATCH v5 0/4] doc: cleanup old cruft","startedAt":"2021-06-18T21:52:36Z","lastAt":"2021-06-18T21:52:44Z","messageCount":5,"participants":["Felipe Contreras"],"isPatch":true,"patchVersion":5,"patchTotal":4},"messages":[{"id":"427913","messageId":"20210618215231.796592-1-felipe.contreras@gmail.com","threadId":"55964","inReplyTo":null,"subject":"[PATCH v5 0/4] doc: cleanup old cruft","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-18T21:52:27Z","receivedAt":"2021-06-18T21:52:36Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"This patch series gets rid of old unnecessary workarounds and convoluted\nsolutions.\n\nI've dropped all the asciidoctor improvements in order to smooth the\nlanding of this series.\n\nThis conflicts with bc/doc-asciidoctor-to-man-wo-xmlto which in my\nopinion should be dropped since I have better proposals for pretty much\nall the changes there, and doesn't even apply on top of master anymore.\n\nFelipe Contreras (4):\n doc: remove GNU troff workaround\n doc: use --stringparam in xmlto\n doc: simplify version passing\n doc: asciidoc: remove unnecessary attribute\n\n Documentation/.gitignore | 1 -\n Documentation/Makefile | 19 +++----------------\n Documentation/asciidoc.conf | 20 --------------------\n Documentation/asciidoctor-extensions.rb | 17 -----------------\n Documentation/manpage-base-url.xsl.in | 10 ----------\n Documentation/manpage-quote-apos.xsl | 16 ----------------\n Makefile | 4 ----\n 7 files changed, 3 insertions(+), 84 deletions(-)\n delete mode 100644 Documentation/manpage-base-url.xsl.in\n delete mode 100644 Documentation/manpage-quote-apos.xsl\n\nRange-diff against v4:\n 1: 2a93d8774a = 1: ec9f46892c doc: remove GNU troff workaround\n 2: 774603b50c = 2: f496a2ddda doc: use --stringparam in xmlto\n 3: 8e92e10b10 = 3: 10216673c1 doc: simplify version passing\n 4: 230b5c8ae0 = 4: 4f2e3456cd doc: asciidoc: remove unnecessary attribute\n 5: 2d1f79d642 < -: ---------- doc: asciidoctor: remove unnecessary require\n 6: e0b662986a < -: ---------- doc: asciidoctor: remove cruft\n 7: 1bdf72a856 < -: ---------- doc: asciidoctor: reorganize extensions\n 8: 8612b428ce < -: ---------- doc: asciidoctor: use html-prefix only for html\n 9: 9cd9f3f317 < -: ---------- doc: asciidoctor: refactor macro registration\n10: 96bd66784f < -: ---------- doc: asciidoctor: improve string handling\n11: 5e293a15fc < -: ---------- doc: asciidoctor: split the format from the code\n12: 7fd97fc089 < -: ---------- doc: asciidoctor: specify name of our group\n-- \n2.32.0\n\n"},{"id":"427914","messageId":"20210618215231.796592-2-felipe.contreras@gmail.com","threadId":"55964","inReplyTo":"20210618215231.796592-1-felipe.contreras@gmail.com","subject":"[PATCH v5 1/4] doc: remove GNU troff workaround","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-18T21:52:28Z","receivedAt":"2021-06-18T21:52:38Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"In 2007 the docbook project made the mistake of converting ' to \\' for\nman pages [1]. It's a problem because groff interprets \\' as acute\naccent which is rendered as ' in ASCII, but as ยด in utf-8.\n\nThis started a cascade of bug reports in git [2], debian [3], Arch Linux\n[4], docbook itself [5], and probably many others.\n\nA solution was to use the correct groff character: \\(aq, which is always\nrendered as ', but the problem is that such character doesn't work in\nother troff programs.\n\nA portable solution required the use of a conditional character that is\n\\(aq in groff, but ' in all others:\n\n .ie \\n(.g .ds Aq \\(aq\n .el .ds Aq '\n\nThe proper solution took time to be implemented in docbook, but in 2010\nthey did it [6]. So the docbook man page stylesheets were broken from\n1.73 to 1.76.\n\nUnfortunately by that point many workarounds already existed. In the\ncase of git GNU_ROFF was introduced, and in the case of Arch Linux\na mappig from \\' to ' was added to groff's man.local. Other\ndistributions might have done the same, or similar workarounds.\n\nSince 2010 there is not need for this workaround, which is fixed\nelsewhere not just in docbook, but other layers as well.\n\nLet's remove it.\n\nAlso, it's GNU troff, not GNU roff.\n\n[1] https://github.com/docbook/xslt10-stylesheets/commit/ea2a0bac56c56eec1892ac3d9254dca89f7c5746\n[2] https://lore.kernel.org/git/20091012102926.GA3937@debian.b2j/\n[3] https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=507673#65\n[4] https://bugs.archlinux.org/task/9643\n[5] https://sourceforge.net/p/docbook/bugs/1022/\n[6] https://github.com/docbook/xslt10-stylesheets/commit/fb553434265906ed81edc6d5f533d0b08d200046\n\nInspired-by: brian m. carlson \nSigned-off-by: Felipe Contreras \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 f5605b7767..bf1f66b3eb 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -178,14 +178,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-\n-\n-\n-\n- \n- \n- \n- '\n- \\(aq\n- \n-\n-\n-\ndiff --git a/Makefile b/Makefile\nindex c3565fc0f8..7588c43f05 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":"427915","messageId":"20210618215231.796592-3-felipe.contreras@gmail.com","threadId":"55964","inReplyTo":"20210618215231.796592-1-felipe.contreras@gmail.com","subject":"[PATCH v5 2/4] doc: use --stringparam in xmlto","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-18T21:52:29Z","receivedAt":"2021-06-18T21:52:40Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Commit 50d9bbba92 (Documentation: Avoid use of xmlto --stringparam,\n2009-12-04) introduced manpage-base-url.xsl because ancient versions of\nxmlto did not have --stringparam.\n\nHowever, that was more than ten years ago, no need for that complexity\nanymore.\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/.gitignore | 1 -\n Documentation/Makefile | 8 ++------\n Documentation/manpage-base-url.xsl.in | 10 ----------\n 3 files changed, 2 insertions(+), 17 deletions(-)\n delete mode 100644 Documentation/manpage-base-url.xsl.in\n\ndiff --git a/Documentation/.gitignore b/Documentation/.gitignore\nindex 9022d48355..e9f8d693b1 100644\n--- a/Documentation/.gitignore\n+++ b/Documentation/.gitignore\n@@ -10,7 +10,6 @@ howto-index.txt\n doc.dep\n cmds-*.txt\n mergetools-*.txt\n-manpage-base-url.xsl\n SubmittingPatches.txt\n tmp-doc-diff/\n GIT-ASCIIDOCFLAGS\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex bf1f66b3eb..84643a34e9 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -176,7 +176,7 @@ endif\n ifndef MAN_BASE_URL\n MAN_BASE_URL = file://$(htmldir)/\n endif\n-XMLTO_EXTRA += -m manpage-base-url.xsl\n+XMLTO_EXTRA += --stringparam man.base.url.for.relative.links='$(MAN_BASE_URL)'\n \n ifdef USE_ASCIIDOCTOR\n ASCIIDOC = asciidoctor\n@@ -342,7 +342,6 @@ clean:\n \t$(RM) technical/*.html technical/api-index.txt\n \t$(RM) SubmittingPatches.txt\n \t$(RM) $(cmds_txt) $(mergetools_txt) *.made\n-\t$(RM) manpage-base-url.xsl\n \t$(RM) GIT-ASCIIDOCFLAGS\n \n $(MAN_HTML): %.html : %.txt $(ASCIIDOC_DEPS)\n@@ -351,10 +350,7 @@ $(MAN_HTML): %.html : %.txt $(ASCIIDOC_DEPS)\n $(OBSOLETE_HTML): %.html : %.txto $(ASCIIDOC_DEPS)\n \t$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -o $@ $<\n \n-manpage-base-url.xsl: manpage-base-url.xsl.in\n-\t$(QUIET_GEN)sed \"s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|\" $< > $@\n-\n-%.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl)\n+%.1 %.5 %.7 : %.xml $(wildcard manpage*.xsl)\n \t$(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<\n \n %.xml : %.txt $(ASCIIDOC_DEPS)\ndiff --git a/Documentation/manpage-base-url.xsl.in b/Documentation/manpage-base-url.xsl.in\ndeleted file mode 100644\nindex e800904df3..0000000000\n--- a/Documentation/manpage-base-url.xsl.in\n+++ /dev/null\n@@ -1,10 +0,0 @@\n-\n-\n-\n-\n-@@MAN_BASE_URL@@\n-\n-\n-- \n2.32.0\n\n"},{"id":"427916","messageId":"20210618215231.796592-4-felipe.contreras@gmail.com","threadId":"55964","inReplyTo":"20210618215231.796592-1-felipe.contreras@gmail.com","subject":"[PATCH v5 3/4] doc: simplify version passing","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-18T21:52:30Z","receivedAt":"2021-06-18T21:52:41Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"The code to pass the version of the man page comes from 2007:\n7ef195ba3e (Documentation: Add version information to man pages,\n2007-03-25). However, both asciidoc and asciidoctor already do this by\ndefault.\n\nAsciidoctor doesn't read manversion, but there's no need since both\ntools just join mansource and manversion.\n\nLet's do that ourselves and get rid of a bunch of code.\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/Makefile | 3 +--\n Documentation/asciidoc.conf | 19 -------------------\n Documentation/asciidoctor-extensions.rb | 17 -----------------\n 3 files changed, 1 insertion(+), 38 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 84643a34e9..47053c78f8 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -137,8 +137,7 @@ ASCIIDOC_HTML = xhtml11\n ASCIIDOC_DOCBOOK = docbook\n ASCIIDOC_CONF = -f asciidoc.conf\n ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \\\n-\t\t-amanversion=$(GIT_VERSION) \\\n-\t\t-amanmanual='Git Manual' -amansource='Git'\n+\t\t-amanmanual='Git Manual' -amansource='Git $(GIT_VERSION)'\n ASCIIDOC_DEPS = asciidoc.conf GIT-ASCIIDOCFLAGS\n TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML)\n TXT_TO_XML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_DOCBOOK)\ndiff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf\nindex 3e4c13971b..60f76f43ed 100644\n--- a/Documentation/asciidoc.conf\n+++ b/Documentation/asciidoc.conf\n@@ -51,25 +51,6 @@ ifdef::doctype-manpage[]\n endif::doctype-manpage[]\n endif::backend-docbook[]\n \n-ifdef::doctype-manpage[]\n-ifdef::backend-docbook[]\n-[header]\n-template::[header-declarations]\n-\n-\n-{mantitle}\n-{manvolnum}\n-{mansource}\n-{manversion}\n-{manmanual}\n-\n-\n- {manname}\n- {manpurpose}\n-\n-endif::backend-docbook[]\n-endif::doctype-manpage[]\n-\n ifdef::backend-xhtml11[]\n [attributes]\n git-relative-html-prefix=\ndiff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb\nindex d906a00803..70a0956663 100644\n--- a/Documentation/asciidoctor-extensions.rb\n+++ b/Documentation/asciidoctor-extensions.rb\n@@ -23,26 +23,9 @@ module Git\n end\n end\n end\n-\n- class DocumentPostProcessor < Asciidoctor::Extensions::Postprocessor\n- def process document, output\n- if document.basebackend? 'docbook'\n- mansource = document.attributes['mansource']\n- manversion = document.attributes['manversion']\n- manmanual = document.attributes['manmanual']\n- new_tags = \"\" \\\n- \"#{mansource}\\n\" \\\n- \"#{manversion}\\n\" \\\n- \"#{manmanual}\\n\"\n- output = output.sub(/<\\/refmeta>/, new_tags + \"\")\n- end\n- output\n- end\n- end\n end\n end\n \n Asciidoctor::Extensions.register do\n inline_macro Git::Documentation::LinkGitProcessor, :linkgit\n- postprocessor Git::Documentation::DocumentPostProcessor\n end\n-- \n2.32.0\n\n"},{"id":"427917","messageId":"20210618215231.796592-5-felipe.contreras@gmail.com","threadId":"55964","inReplyTo":"20210618215231.796592-1-felipe.contreras@gmail.com","subject":"[PATCH v5 4/4] doc: asciidoc: remove unnecessary attribute","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-18T21:52:31Z","receivedAt":"2021-06-18T21:52:44Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"It's part of asciidoc global configuration since 2012.\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/asciidoc.conf | 1 -\n 1 file changed, 1 deletion(-)\n\ndiff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf\nindex 60f76f43ed..f7908f9dea 100644\n--- a/Documentation/asciidoc.conf\n+++ b/Documentation/asciidoc.conf\n@@ -12,7 +12,6 @@\n \n [attributes]\n asterisk=*\n-plus=+\n caret=^\n startsb=[\n endsb=]\n-- \n2.32.0\n\n"}]}