{"thread":{"id":"55977","subject":"[PATCH 01/23] doc: remove GNU troff workaround","startedAt":"2021-06-21T16:58:45Z","lastAt":"2021-06-23T01:37:08Z","messageCount":28,"participants":["Felipe Contreras","Bagas Sanjaya"],"isPatch":true,"patchVersion":1,"patchTotal":23},"messages":[{"id":"428051","messageId":"20210621163110.1074145-2-felipe.contreras@gmail.com","threadId":"55977","inReplyTo":"20210621163110.1074145-1-felipe.contreras@gmail.com","subject":"[PATCH 01/23] doc: remove GNU troff workaround","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-21T16:30:48Z","receivedAt":"2021-06-21T16:58:45Z","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":"428052","messageId":"20210621163110.1074145-4-felipe.contreras@gmail.com","threadId":"55977","inReplyTo":"20210621163110.1074145-1-felipe.contreras@gmail.com","subject":"[PATCH 03/23] doc: simplify version passing","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-21T16:30:50Z","receivedAt":"2021-06-21T16:58:47Z","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":"428053","messageId":"20210621163110.1074145-3-felipe.contreras@gmail.com","threadId":"55977","inReplyTo":"20210621163110.1074145-1-felipe.contreras@gmail.com","subject":"[PATCH 02/23] doc: use --stringparam in xmlto","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-21T16:30:49Z","receivedAt":"2021-06-21T16:58:49Z","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":"428054","messageId":"20210621163110.1074145-1-felipe.contreras@gmail.com","threadId":"55977","inReplyTo":null,"subject":"[PATCH 00/23] doc: cleanups and asciidoctor direct man pages","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-21T16:30:47Z","receivedAt":"2021-06-21T16:58:51Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"I already sent the first part of this series separately multiple times,\nthe last one is 4 simple obviously correct patches [1], but since the\nmaintainer has admitted he has no problem ignoring valid work\nentirely due to personal animus [2], I'm sending the whole chain.\n\nThere's no point in carefully selecting multiple series of patches to be\nmerged one by one when all of them are going to be ignored. So I'm\nsending all 3 series at once.\n\nHopefully by sending it all at once some people will be able to realize\nthat:\n\n 1. They are valid\n 2. They are helpful\n 3. They make the code more maintainable\n 4. They enable new features\n 5. They enable the new features to be easily tested\n 6. They reduce the doc-diff of the new feature, as well as others\n 7. They are superior to the competing series currently in seen\n 8. They include work of multiple contributors\n\nAny fair and impartial maintainer would attempt to pick them up.\n\nCheers.\n\n[1] https://lore.kernel.org/git/20210618215231.796592-1-felipe.contreras@gmail.com/\n[2] https://lore.kernel.org/git/xmqqmtrmjpa8.fsf@gitster.g/\n\nFelipe Contreras (21):\n doc: remove GNU troff workaround\n doc: use --stringparam in xmlto\n doc: simplify version passing\n doc: asciidoc: remove unnecessary attribute\n doc: asciidoctor: remove unnecessary require\n doc: asciidoctor: remove cruft\n doc: asciidoctor: reorganize extensions\n doc: asciidoctor: use html-prefix only for html\n doc: asciidoctor: refactor macro registration\n doc: asciidoctor: improve string handling\n doc: asciidoctor: split the format from the code\n doc: asciidoctor: specify name of our group\n doc: doc-diff: set docdate manually\n doc: use asciidoctor to build man pages directly\n doc: asciidoctor: add linkgit macros in man pages\n doc: add man pages workaround for asciidoctor\n doc: asciidoctor: add hack for xrefs\n doc: asciidoctor: add hack to improve links\n doc: asciidoctor: add support for baseurl\n doc: asciidoctor: cleanup man page hack\n doc: asciidoctor: add hack for old versions\n\nJeff King (1):\n doc-diff: support asciidoctor man pages\n\nMartin Ågren (1):\n doc-diff: drop --cut-footer switch\n\n Documentation/.gitignore | 1 -\n Documentation/Makefile | 32 ++++----\n Documentation/asciidoc.conf | 20 -----\n Documentation/asciidoctor-extensions.rb | 103 +++++++++++++++---------\n Documentation/doc-diff | 38 ++++-----\n Documentation/manpage-base-url.xsl.in | 10 ---\n Documentation/manpage-quote-apos.xsl | 16 ----\n Makefile | 8 +-\n 8 files changed, 104 insertions(+), 124 deletions(-)\n delete mode 100644 Documentation/manpage-base-url.xsl.in\n delete mode 100644 Documentation/manpage-quote-apos.xsl\n\n-- \n2.32.0\n\n"},{"id":"428055","messageId":"20210621163110.1074145-5-felipe.contreras@gmail.com","threadId":"55977","inReplyTo":"20210621163110.1074145-1-felipe.contreras@gmail.com","subject":"[PATCH 04/23] doc: asciidoc: remove unnecessary attribute","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-21T16:30:51Z","receivedAt":"2021-06-21T16:58:53Z","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"},{"id":"428056","messageId":"20210621163110.1074145-6-felipe.contreras@gmail.com","threadId":"55977","inReplyTo":"20210621163110.1074145-1-felipe.contreras@gmail.com","subject":"[PATCH 05/23] doc: asciidoctor: remove unnecessary require","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-21T16:30:52Z","receivedAt":"2021-06-21T16:58:55Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"This file is loaded by asciidoctor, the module is already loaded.\n\nIn addition to being less redundant this fixes a problem while trying\nuse a development version of asciidoctor when the gem is available:\n\n $GEM_HOME/gems/asciidoctor-2.0.15/lib/asciidoctor.rb:51:\n warning: already initialized constant Asciidoctor::RUBY_ENGINE\n $HOME/asciidoctor/lib/asciidoctor.rb:52:\n warning: previous definition of RUBY_ENGINE was here\n ...\n\nThat's a bug in asciidoctor, but there's no need to trigger it.\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/asciidoctor-extensions.rb | 1 -\n 1 file changed, 1 deletion(-)\n\ndiff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb\nindex 70a0956663..423450392d 100644\n--- a/Documentation/asciidoctor-extensions.rb\n+++ b/Documentation/asciidoctor-extensions.rb\n@@ -1,4 +1,3 @@\n-require 'asciidoctor'\n require 'asciidoctor/extensions'\n \n module Git\n-- \n2.32.0\n\n"},{"id":"428057","messageId":"20210621163110.1074145-8-felipe.contreras@gmail.com","threadId":"55977","inReplyTo":"20210621163110.1074145-1-felipe.contreras@gmail.com","subject":"[PATCH 07/23] doc: asciidoctor: reorganize extensions","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-21T16:30:54Z","receivedAt":"2021-06-21T16:59:00Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"There's no need to create verbose classes, we can do the same with a\nsimple block.\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/asciidoctor-extensions.rb | 34 +++++++++++--------------\n 1 file changed, 15 insertions(+), 19 deletions(-)\n\ndiff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb\nindex 3dea106d00..f998a42249 100644\n--- a/Documentation/asciidoctor-extensions.rb\n+++ b/Documentation/asciidoctor-extensions.rb\n@@ -1,26 +1,22 @@\n require 'asciidoctor/extensions'\n \n-module Git\n- module Documentation\n- class LinkGitProcessor < Asciidoctor::Extensions::InlineMacroProcessor\n- def process(parent, target, attrs)\n- prefix = parent.document.attr('git-relative-html-prefix')\n- if parent.document.doctype == 'book'\n- \"\" \\\n- \"#{target}(#{attrs[1]})\"\n- elsif parent.document.basebackend? 'html'\n- %(#{target}(#{attrs[1]}))\n- elsif parent.document.basebackend? 'docbook'\n- \"\\n\" \\\n- \"#{target}\" \\\n- \"#{attrs[1]}\\n\" \\\n- \"\"\n- end\n+Asciidoctor::Extensions.register do\n+\n+ inline_macro :linkgit do\n+ process do |parent, target, attrs|\n+ prefix = parent.document.attr('git-relative-html-prefix')\n+ if parent.document.doctype == 'book'\n+ \"\" \\\n+ \"#{target}(#{attrs[1]})\"\n+ elsif parent.document.basebackend? 'html'\n+ %(#{target}(#{attrs[1]}))\n+ elsif parent.document.basebackend? 'docbook'\n+ \"\\n\" \\\n+ \"#{target}\" \\\n+ \"#{attrs[1]}\\n\" \\\n+ \"\"\n end\n end\n end\n-end\n \n-Asciidoctor::Extensions.register do\n- inline_macro Git::Documentation::LinkGitProcessor, :linkgit\n end\n-- \n2.32.0\n\n"},{"id":"428058","messageId":"20210621163110.1074145-7-felipe.contreras@gmail.com","threadId":"55977","inReplyTo":"20210621163110.1074145-1-felipe.contreras@gmail.com","subject":"[PATCH 06/23] doc: asciidoctor: remove cruft","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-21T16:30:53Z","receivedAt":"2021-06-21T16:59:02Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"These were probably copy-pasted from other extensions. The name is\nalready defined (:linkgit), and we are not using the DSL mode.\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/asciidoctor-extensions.rb | 4 ----\n 1 file changed, 4 deletions(-)\n\ndiff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb\nindex 423450392d..3dea106d00 100644\n--- a/Documentation/asciidoctor-extensions.rb\n+++ b/Documentation/asciidoctor-extensions.rb\n@@ -3,10 +3,6 @@ require 'asciidoctor/extensions'\n module Git\n module Documentation\n class LinkGitProcessor < Asciidoctor::Extensions::InlineMacroProcessor\n- use_dsl\n-\n- named :chrome\n-\n def process(parent, target, attrs)\n prefix = parent.document.attr('git-relative-html-prefix')\n if parent.document.doctype == 'book'\n-- \n2.32.0\n\n"},{"id":"428059","messageId":"20210621163110.1074145-11-felipe.contreras@gmail.com","threadId":"55977","inReplyTo":"20210621163110.1074145-1-felipe.contreras@gmail.com","subject":"[PATCH 10/23] doc: asciidoctor: improve string handling","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-21T16:30:57Z","receivedAt":"2021-06-21T16:59:03Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Using printf style formatting (more familiar to git developers), and\nalso here document.\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/asciidoctor-extensions.rb | 14 +++++++-------\n 1 file changed, 7 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb\nindex a678704e17..3282d59a48 100644\n--- a/Documentation/asciidoctor-extensions.rb\n+++ b/Documentation/asciidoctor-extensions.rb\n@@ -7,20 +7,20 @@ Asciidoctor::Extensions.register do\n inline_macro :linkgit do\n if doc.doctype == 'book'\n process do |parent, target, attrs|\n- \"\" \\\n- \"#{target}(#{attrs[1]})\"\n+ '%1$s(%2$s)' % [target, attrs[1]]\n end\n elsif doc.basebackend? 'html'\n prefix = doc.attr('git-relative-html-prefix')\n process do |parent, target, attrs|\n- %(#{target}(#{attrs[1]}))\n+ %(%1$s(%2$s)) % [target, attrs[1]]\n end\n elsif doc.basebackend? 'docbook'\n process do |parent, target, attrs|\n- \"\\n\" \\\n- \"#{target}\" \\\n- \"#{attrs[1]}\\n\" \\\n- \"\"\n+ <<~EOF.chomp % [target, attrs[1]]\n+ \n+ %s%s\n+ \n+ EOF\n end\n end\n end\n-- \n2.32.0\n\n"},{"id":"428060","messageId":"20210621163110.1074145-12-felipe.contreras@gmail.com","threadId":"55977","inReplyTo":"20210621163110.1074145-1-felipe.contreras@gmail.com","subject":"[PATCH 11/23] doc: asciidoctor: split the format from the code","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-21T16:30:58Z","receivedAt":"2021-06-21T16:59:08Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"This way we don't have to specify the block to execute on every\nconditional.\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/asciidoctor-extensions.rb | 26 ++++++++++++-------------\n 1 file changed, 13 insertions(+), 13 deletions(-)\n\ndiff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb\nindex 3282d59a48..51981af13c 100644\n--- a/Documentation/asciidoctor-extensions.rb\n+++ b/Documentation/asciidoctor-extensions.rb\n@@ -6,22 +6,22 @@ Asciidoctor::Extensions.register do\n \n inline_macro :linkgit do\n if doc.doctype == 'book'\n- process do |parent, target, attrs|\n- '%1$s(%2$s)' % [target, attrs[1]]\n- end\n+ format = '%1$s(%2$s)'\n elsif doc.basebackend? 'html'\n prefix = doc.attr('git-relative-html-prefix')\n- process do |parent, target, attrs|\n- %(%1$s(%2$s)) % [target, attrs[1]]\n- end\n+ format = %(%1$s(%2$s))\n elsif doc.basebackend? 'docbook'\n- process do |parent, target, attrs|\n- <<~EOF.chomp % [target, attrs[1]]\n- \n- %s%s\n- \n- EOF\n- end\n+ format = <<~EOF.chomp\n+ \n+ %s%s\n+ \n+ EOF\n+ else\n+ return\n+ end\n+\n+ process do |_, target, attrs|\n+ format % [target, attrs[1]]\n end\n end\n \n-- \n2.32.0\n\n"},{"id":"428061","messageId":"20210621163110.1074145-10-felipe.contreras@gmail.com","threadId":"55977","inReplyTo":"20210621163110.1074145-1-felipe.contreras@gmail.com","subject":"[PATCH 09/23] doc: asciidoctor: refactor macro registration","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-21T16:30:56Z","receivedAt":"2021-06-21T16:59:08Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"There is no need to execute extra code every time the process block is\ncalled.\n\nIn Ruby the lexical scope is shared, so we can define variables in the\nregister block scope, and all the rest will inherit those variables.\n\nBased on the doctype and basebackend one of three blocks is selected for\nthe inline_macro. However, the conditionals will be run only once.\n\nIn the end Ruby will only run the code between `process do end`, nothing\nelse.\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/asciidoctor-extensions.rb | 16 +++++++++++-----\n 1 file changed, 11 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb\nindex c77b6de350..a678704e17 100644\n--- a/Documentation/asciidoctor-extensions.rb\n+++ b/Documentation/asciidoctor-extensions.rb\n@@ -2,15 +2,21 @@ require 'asciidoctor/extensions'\n \n Asciidoctor::Extensions.register do\n \n+ doc = document\n+\n inline_macro :linkgit do\n- process do |parent, target, attrs|\n- if parent.document.doctype == 'book'\n+ if doc.doctype == 'book'\n+ process do |parent, target, attrs|\n \"\" \\\n \"#{target}(#{attrs[1]})\"\n- elsif parent.document.basebackend? 'html'\n- prefix = parent.document.attr('git-relative-html-prefix')\n+ end\n+ elsif doc.basebackend? 'html'\n+ prefix = doc.attr('git-relative-html-prefix')\n+ process do |parent, target, attrs|\n %(#{target}(#{attrs[1]}))\n- elsif parent.document.basebackend? 'docbook'\n+ end\n+ elsif doc.basebackend? 'docbook'\n+ process do |parent, target, attrs|\n \"\\n\" \\\n \"#{target}\" \\\n \"#{attrs[1]}\\n\" \\\n-- \n2.32.0\n\n"},{"id":"428062","messageId":"20210621163110.1074145-9-felipe.contreras@gmail.com","threadId":"55977","inReplyTo":"20210621163110.1074145-1-felipe.contreras@gmail.com","subject":"[PATCH 08/23] doc: asciidoctor: use html-prefix only for html","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-21T16:30:55Z","receivedAt":"2021-06-21T16:59:12Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"This is what asciidoc.conf does.\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/asciidoctor-extensions.rb | 4 ++--\n 1 file changed, 2 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb\nindex f998a42249..c77b6de350 100644\n--- a/Documentation/asciidoctor-extensions.rb\n+++ b/Documentation/asciidoctor-extensions.rb\n@@ -4,11 +4,11 @@ Asciidoctor::Extensions.register do\n \n inline_macro :linkgit do\n process do |parent, target, attrs|\n- prefix = parent.document.attr('git-relative-html-prefix')\n if parent.document.doctype == 'book'\n- \"\" \\\n+ \"\" \\\n \"#{target}(#{attrs[1]})\"\n elsif parent.document.basebackend? 'html'\n+ prefix = parent.document.attr('git-relative-html-prefix')\n %(#{target}(#{attrs[1]}))\n elsif parent.document.basebackend? 'docbook'\n \"\\n\" \\\n-- \n2.32.0\n\n"},{"id":"428063","messageId":"20210621163110.1074145-13-felipe.contreras@gmail.com","threadId":"55977","inReplyTo":"20210621163110.1074145-1-felipe.contreras@gmail.com","subject":"[PATCH 12/23] doc: asciidoctor: specify name of our group","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-21T16:30:59Z","receivedAt":"2021-06-21T16:59:13Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Doesn't do anything, but otherwise we get a random name.\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/asciidoctor-extensions.rb | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb\nindex 51981af13c..b36317e4d2 100644\n--- a/Documentation/asciidoctor-extensions.rb\n+++ b/Documentation/asciidoctor-extensions.rb\n@@ -1,6 +1,6 @@\n require 'asciidoctor/extensions'\n \n-Asciidoctor::Extensions.register do\n+Asciidoctor::Extensions.register :git do\n \n doc = document\n \n-- \n2.32.0\n\n"},{"id":"428064","messageId":"20210621163110.1074145-14-felipe.contreras@gmail.com","threadId":"55977","inReplyTo":"20210621163110.1074145-1-felipe.contreras@gmail.com","subject":"[PATCH 13/23] doc: doc-diff: set docdate manually","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-21T16:31:00Z","receivedAt":"2021-06-21T16:59:26Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"In order to minimize the differences in the footer.\n\nAsciidoc automatically generates a date with format '%Y-%m-%d', while\nasciidoctor '%F'.\n\nI personally prefer the latter, so only modify it for diff purposes.\n\nFixes tons of these:\n\n-Git omitted 01/01/1970 GIT-ADD(1)\n+Git omitted 1970-01-01 GIT-ADD(1)\n\nNote that we have to add quotes when passing around $makemanflags, as it\nnow may contain whitespace due to multiple arguments (but the\ndereference inside render_tree must remain unquoted, because it wants to perform\nwhitespace splitting to get the individual arguments back).\n\nComments-by: Jeff King \nSigned-off-by: Felipe Contreras \n---\n Documentation/Makefile | 2 +-\n Documentation/doc-diff | 6 +++---\n 2 files changed, 4 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 47053c78f8..b68ab57239 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -136,7 +136,7 @@ ASCIIDOC_EXTRA =\n ASCIIDOC_HTML = xhtml11\n ASCIIDOC_DOCBOOK = docbook\n ASCIIDOC_CONF = -f asciidoc.conf\n-ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \\\n+ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_FLAGS) $(ASCIIDOC_CONF) \\\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)\ndiff --git a/Documentation/doc-diff b/Documentation/doc-diff\nindex 1694300e50..c11b90a6ef 100755\n--- a/Documentation/doc-diff\n+++ b/Documentation/doc-diff\n@@ -111,7 +111,7 @@ construct_makemanflags () {\n \t\techo USE_ASCIIDOCTOR=\n \telif test \"$1\" = \"-asciidoctor\"\n \tthen\n-\t\techo USE_ASCIIDOCTOR=YesPlease\n+\t\techo USE_ASCIIDOCTOR=YesPlease ASCIIDOC_FLAGS='-adocdate=\"01/01/1970\"'\n \tfi\n }\n \n@@ -181,6 +181,6 @@ render_tree () {\n \tfi\n }\n \n-render_tree $from_oid $from_dir $from_makemanflags &&\n-render_tree $to_oid $to_dir $to_makemanflags &&\n+render_tree $from_oid $from_dir \"$from_makemanflags\" &&\n+render_tree $to_oid $to_dir \"$to_makemanflags\" &&\n git -C $tmp/rendered diff --no-index \"$@\" $from_dir $to_dir\n-- \n2.32.0\n\n"},{"id":"428065","messageId":"20210621163110.1074145-15-felipe.contreras@gmail.com","threadId":"55977","inReplyTo":"20210621163110.1074145-1-felipe.contreras@gmail.com","subject":"[PATCH 14/23] doc-diff: drop --cut-footer switch","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-21T16:31:01Z","receivedAt":"2021-06-21T16:59:30Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"From: Martin Ågren \n\nNow that our doc-diff convinces Asciidoctor to insert the exact same\nformatted dummy date as AsciiDoc, we can drop the --cut-footer switch.\nIt has been useful to ignore this difference between the two tools, but\nit's effectively a no-op now. Similar to when we repurposed this from\n--cut-header-footer in 83b0b8953e (\"doc-diff: replace\n--cut-header-footer with --cut-footer\", 2019-09-16), just drop it\nwithout worrying about any kind of backwards compatibility or user-base.\n\nSigned-off-by: Martin Ågren \nSigned-off-by: Felipe Contreras \n---\n Documentation/doc-diff | 18 ++----------------\n 1 file changed, 2 insertions(+), 16 deletions(-)\n\ndiff --git a/Documentation/doc-diff b/Documentation/doc-diff\nindex c11b90a6ef..6b6bb444ac 100755\n--- a/Documentation/doc-diff\n+++ b/Documentation/doc-diff\n@@ -21,7 +21,6 @@ asciidoc\t\tuse asciidoc with both commits\n to-asciidoc\t\tuse asciidoc with the 'to'-commit\n to-asciidoctor\t\tuse asciidoctor with the 'to'-commit\n asciidoctor\t\tuse asciidoctor with both commits\n-cut-footer\t\tcut away footer\n \"\n SUBDIRECTORY_OK=1\n . \"$(git --exec-path)/git-sh-setup\"\n@@ -31,7 +30,6 @@ force=\n clean=\n from_program=\n to_program=\n-cut_footer=\n while test $# -gt 0\n do\n \tcase \"$1\" in\n@@ -55,8 +53,6 @@ do\n \t--asciidoc)\n \t\tfrom_program=-asciidoc\n \t\tto_program=-asciidoc ;;\n-\t--cut-footer)\n-\t\tcut_footer=-cut-footer ;;\n \t--)\n \t\tshift; break ;;\n \t*)\n@@ -118,8 +114,8 @@ construct_makemanflags () {\n from_makemanflags=$(construct_makemanflags \"$from_program\") &&\n to_makemanflags=$(construct_makemanflags \"$to_program\") &&\n \n-from_dir=$from_oid$from_program$cut_footer &&\n-to_dir=$to_oid$to_program$cut_footer &&\n+from_dir=$from_oid$from_program &&\n+to_dir=$to_oid$to_program &&\n \n # generate_render_makefile \n generate_render_makefile () {\n@@ -168,16 +164,6 @@ render_tree () {\n \t\t\t\"$tmp/rendered/$dname+\" |\n \t\tmake -j$parallel -f - &&\n \t\tmv \"$tmp/rendered/$dname+\" \"$tmp/rendered/$dname\"\n-\n-\t\tif test \"$cut_footer\" = \"-cut-footer\"\n-\t\tthen\n-\t\t\tfor f in $(find \"$tmp/rendered/$dname\" -type f)\n-\t\t\tdo\n-\t\t\t\thead -n -2 \"$f\" | sed -e '${/^$/d}' >\"$f+\" &&\n-\t\t\t\tmv \"$f+\" \"$f\" ||\n-\t\t\t\treturn 1\n-\t\t\tdone\n-\t\tfi\n \tfi\n }\n \n-- \n2.32.0\n\n"},{"id":"428066","messageId":"20210621163110.1074145-16-felipe.contreras@gmail.com","threadId":"55977","inReplyTo":"20210621163110.1074145-1-felipe.contreras@gmail.com","subject":"[PATCH 15/23] doc: use asciidoctor to build man pages directly","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-21T16:31:02Z","receivedAt":"2021-06-21T16:59:32Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"There's no need to use xmlto to build the man pages when modern\nasciidoctor can do it by itself.\n\nThis new mode will be active only when both USE_ASCIIDOCTOR and\nUSE_ASCIIDOCTOR_MANPAGE are set.\n\nSuggested-by: Bagas Sanjaya \nSuggestions-by: Jeff King \nSigned-off-by: Felipe Contreras \n---\n Documentation/Makefile | 10 +++++++++-\n Makefile | 4 ++++\n 2 files changed, 13 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex b68ab57239..e6af1848cc 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -189,6 +189,9 @@ ASCIIDOC_DEPS = asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS\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@@ -324,7 +327,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@@ -349,8 +352,13 @@ $(MAN_HTML): %.html : %.txt $(ASCIIDOC_DEPS)\n $(OBSOLETE_HTML): %.html : %.txto $(ASCIIDOC_DEPS)\n \t$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -o $@ $<\n \n+ifdef TXT_TO_MAN\n+%.1 %.5 %.7 : %.txt $(ASCIIDOC_DEPS)\n+\t$(QUIET_ASCIIDOC)$(TXT_TO_MAN) -o $@ $<\n+else\n %.1 %.5 %.7 : %.xml $(wildcard manpage*.xsl)\n \t$(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<\n+endif\n \n %.xml : %.txt $(ASCIIDOC_DEPS)\n \t$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $@ $<\ndiff --git a/Makefile b/Makefile\nindex 7588c43f05..ab3fa362b7 100644\n--- a/Makefile\n+++ b/Makefile\n@@ -281,6 +281,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":"428067","messageId":"20210621163110.1074145-17-felipe.contreras@gmail.com","threadId":"55977","inReplyTo":"20210621163110.1074145-1-felipe.contreras@gmail.com","subject":"[PATCH 16/23] doc-diff: support asciidoctor man pages","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-21T16:31:03Z","receivedAt":"2021-06-21T16:59:32Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"From: Jeff King \n\nThe new option enables both asciidoctor as well as its direct-to-manpage\nmode that skips xmlto. This lets you view the rendered difference\nbetween the two pipelines with something like:\n\n ./doc-diff --from-asciidoctor --to-asciidoctor-direct HEAD HEAD\n\nSigned-off-by: Jeff King \nSigned-off-by: Felipe Contreras \n---\n Documentation/doc-diff | 14 ++++++++++++++\n 1 file changed, 14 insertions(+)\n\ndiff --git a/Documentation/doc-diff b/Documentation/doc-diff\nindex 6b6bb444ac..bbfeaa213b 100755\n--- a/Documentation/doc-diff\n+++ b/Documentation/doc-diff\n@@ -17,10 +17,13 @@ f\t\t\tforce rebuild; do not rely on cached results\n c,clean\t\t\tcleanup temporary working files\n from-asciidoc\t\tuse asciidoc with the 'from'-commit\n from-asciidoctor\tuse asciidoctor with the 'from'-commit\n+from-asciidoctor-direct use asciidoctor without xmlto for 'from'-commit\n asciidoc\t\tuse asciidoc with both commits\n to-asciidoc\t\tuse asciidoc with the 'to'-commit\n to-asciidoctor\t\tuse asciidoctor with the 'to'-commit\n+to-asciidoctor-direct use asciidoctor without xmlto for 'to'-commit\n asciidoctor\t\tuse asciidoctor with both commits\n+asciidoctor-direct use asciidoctor without xml for both commits\n \"\n SUBDIRECTORY_OK=1\n . \"$(git --exec-path)/git-sh-setup\"\n@@ -53,6 +56,13 @@ do\n \t--asciidoc)\n \t\tfrom_program=-asciidoc\n \t\tto_program=-asciidoc ;;\n+\t--from-asciidoctor-direct)\n+\t\tfrom_program=-asciidoctor-direct ;;\n+\t--to-asciidoctor-direct)\n+\t\tto_program=-asciidoctor-direct ;;\n+\t--asciidoctor-direct)\n+\t\tfrom_program=-asciidoctor-direct\n+\t\tto_program=-asciidoctor-direct ;;\n \t--)\n \t\tshift; break ;;\n \t*)\n@@ -108,6 +118,10 @@ construct_makemanflags () {\n \telif test \"$1\" = \"-asciidoctor\"\n \tthen\n \t\techo USE_ASCIIDOCTOR=YesPlease ASCIIDOC_FLAGS='-adocdate=\"01/01/1970\"'\n+\telif test \"$1\" = \"-asciidoctor-direct\"\n+\tthen\n+\t\techo USE_ASCIIDOCTOR=YesPlease ASCIIDOC_FLAGS='-adocdate=\"01/01/1970\"'\n+\t\techo USE_ASCIIDOCTOR_MANPAGE=YesPlease\n \tfi\n }\n \n-- \n2.32.0\n\n"},{"id":"428068","messageId":"20210621163110.1074145-20-felipe.contreras@gmail.com","threadId":"55977","inReplyTo":"20210621163110.1074145-1-felipe.contreras@gmail.com","subject":"[PATCH 19/23] doc: asciidoctor: add hack for xrefs","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-21T16:31:06Z","receivedAt":"2021-06-21T16:59:48Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"The docbook manpage stylesheets convert cross-references with format the\n'section called “%t”'. I personally prefer the asciidoctor version, but\nfor now add a hack to minimize the diff.\n\nThanks to the extensibility of Ruby we can override corresponding method\nin the man page converter.\n\nThis fixes doc-diffs like:\n\n --worktree-attributes\n Look for attributes in .gitattributes files in the working tree as\n - well (see the section called “ATTRIBUTES”).\n + well (see ATTRIBUTES).\n\nThis can easily be removed later once we are confortable with the\nasciidoctor version.\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/asciidoctor-extensions.rb | 18 ++++++++++++++++++\n 1 file changed, 18 insertions(+)\n\ndiff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb\nindex 954acb3e7d..7561973df6 100644\n--- a/Documentation/asciidoctor-extensions.rb\n+++ b/Documentation/asciidoctor-extensions.rb\n@@ -1,4 +1,22 @@\n require 'asciidoctor/extensions'\n+require 'asciidoctor/converter/manpage'\n+\n+module Asciidoctor\n+ class Converter::ManPageConverter\n+ alias orig_convert_inline_anchor convert_inline_anchor\n+ def convert_inline_anchor(node)\n+ case node.type\n+ when :xref\n+ return node.text if node.text\n+ refid = node.attributes['refid']\n+ 'the section called “%s”' % refid.gsub('_', ' ')\n+ else\n+ orig_convert_inline_anchor(node)\n+ end\n+ end\n+ alias inline_anchor convert_inline_anchor # For old versions of asciidoctor\n+ end\n+end\n \n Asciidoctor::Extensions.register :git do\n \n-- \n2.32.0\n\n"},{"id":"428069","messageId":"20210621163110.1074145-21-felipe.contreras@gmail.com","threadId":"55977","inReplyTo":"20210621163110.1074145-1-felipe.contreras@gmail.com","subject":"[PATCH 20/23] doc: asciidoctor: add hack to improve links","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-21T16:31:07Z","receivedAt":"2021-06-21T16:59:49Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"The way asciidoctor handles links is very primitive compared to docbook.\nLinks are simply presented in the format \"#{text} <#{target}>\", which\nmay not be all that bad for the future, but pollutes the doc-diff.\n\nBy adding another modification to convert_inline_anchor() we can present\nlinks in a form very similar to docbook, diminishing the doc-diff.\n\nThis significantly reduces the doc-diff:\n\nFrom:\n\n abysmal performance). These safety and performance issues cannot be\n backward compatibly fixed and as such, its use is not recommended.\n Please use an alternative history filtering tool such as git\n- filter-repo[1]. If you still need to use git filter-branch, please\n- carefully read the section called “SAFETY” (and the section called\n- “PERFORMANCE”) to learn about the land mines of filter-branch, and then\n- vigilantly avoid as many of the hazards listed there as reasonably\n- possible.\n+ filter-repo\" . If you\n+ still need to use git filter-branch, please carefully read the section\n+ called “SAFETY” (and the section called “PERFORMANCE”) to learn about\n+ the land mines of filter-branch, and then vigilantly avoid as many of\n+ the hazards listed there as reasonably possible.\n\n-NOTES\n- 1. git filter-repo\n- https://github.com/newren/git-filter-repo/\n-\n- 2. filter-lamely\n- https://github.com/newren/git-filter-repo/blob/master/contrib/filter-repo-demos/filter-lamely\n-\n\nTo:\n\n NOTES\n- 1. git filter-repo\n+ [1] git filter-repo\n https://github.com/newren/git-filter-repo/\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/asciidoctor-extensions.rb | 13 +++++++++++++\n 1 file changed, 13 insertions(+)\n\ndiff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb\nindex 7561973df6..914e6f64c8 100644\n--- a/Documentation/asciidoctor-extensions.rb\n+++ b/Documentation/asciidoctor-extensions.rb\n@@ -10,6 +10,19 @@ module Asciidoctor\n return node.text if node.text\n refid = node.attributes['refid']\n 'the section called “%s”' % refid.gsub('_', ' ')\n+ when :link\n+ return node.target if node.text == node.target\n+ doc = node.document\n+\n+ footnote = doc.footnotes.find { |e| e.id == node.target }\n+ if !footnote\n+ footnote_text = \"%s\\n\\e.RS\\n\\e\\\\%%%s\\n\\e.RE\" % [node.text, node.target]\n+ index = doc.counter('footnote-number')\n+ footnote = Document::Footnote.new(index, node.target, footnote_text)\n+ doc.register(:footnotes, footnote)\n+ end\n+\n+ \"\\e\\\\fB%s\\e\\\\fR[%d]\" % [node.text, footnote.index]\n else\n orig_convert_inline_anchor(node)\n end\n-- \n2.32.0\n\n"},{"id":"428070","messageId":"20210621163110.1074145-23-felipe.contreras@gmail.com","threadId":"55977","inReplyTo":"20210621163110.1074145-1-felipe.contreras@gmail.com","subject":"[PATCH 22/23] doc: asciidoctor: cleanup man page hack","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-21T16:31:09Z","receivedAt":"2021-06-21T16:59:51Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"There's basically nothing we need from the original\norig_convert_inline_anchor(), so let's remove calls to it.\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/asciidoctor-extensions.rb | 5 +++--\n 1 file changed, 3 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb\nindex 8856f2febd..e48a381b8f 100644\n--- a/Documentation/asciidoctor-extensions.rb\n+++ b/Documentation/asciidoctor-extensions.rb\n@@ -3,7 +3,6 @@ require 'asciidoctor/converter/manpage'\n \n module Asciidoctor\n class Converter::ManPageConverter\n- alias orig_convert_inline_anchor convert_inline_anchor\n def convert_inline_anchor(node)\n case node.type\n when :xref\n@@ -25,8 +24,10 @@ module Asciidoctor\n end\n \n \"\\e\\\\fB%s\\e\\\\fR[%d]\" % [node.text, footnote.index]\n+ when :ref, :bibref\n+ ''\n else\n- orig_convert_inline_anchor(node)\n+ nil\n end\n end\n alias inline_anchor convert_inline_anchor # For old versions of asciidoctor\n-- \n2.32.0\n\n"},{"id":"428071","messageId":"20210621163110.1074145-18-felipe.contreras@gmail.com","threadId":"55977","inReplyTo":"20210621163110.1074145-1-felipe.contreras@gmail.com","subject":"[PATCH 17/23] doc: asciidoctor: add linkgit macros in man pages","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-21T16:31:04Z","receivedAt":"2021-06-21T16:59:53Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Fixes the doc-diff:\n\n- Please see git-commit(1) for alternative ways to add content to a\n- commit.\n+ Please see for alternative ways to add content to a commit.\n\nComments-by: brian m. carlson \nSigned-off-by: Felipe Contreras \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 b36317e4d2..6c4153f628 100644\n--- a/Documentation/asciidoctor-extensions.rb\n+++ b/Documentation/asciidoctor-extensions.rb\n@@ -10,6 +10,8 @@ Asciidoctor::Extensions.register :git do\n elsif doc.basebackend? 'html'\n prefix = doc.attr('git-relative-html-prefix')\n format = %(%1$s(%2$s))\n+ elsif doc.basebackend? 'manpage'\n+ format = \"\\e\\\\fB%s\\e\\\\fP(%s)\"\n elsif doc.basebackend? 'docbook'\n format = <<~EOF.chomp\n \n-- \n2.32.0\n\n"},{"id":"428072","messageId":"20210621163110.1074145-19-felipe.contreras@gmail.com","threadId":"55977","inReplyTo":"20210621163110.1074145-1-felipe.contreras@gmail.com","subject":"[PATCH 18/23] doc: add man pages workaround for asciidoctor","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-21T16:31:05Z","receivedAt":"2021-06-21T16:59:55Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Currently asciidoctor doesn't convert number character references\n(&#xx;) correctly for man pages.\n\nThis hack fixes the issue with minimum changes elsewhere so it's easy to\nremove when fixed.\n\nFixes doc-diffs like:\n\n so line count cannot be shown) and there is no difference between\n indexed copy and the working tree version (if the working tree\n version were also different, binary would have been shown in place\n- of nothing). The other file, git-add--interactive.perl, has 403\n- lines added and 35 lines deleted if you commit what is in the\n- index, but working tree file has further modifications (one\n+ of nothing). The other file, git-add--interactive.perl,\n+ has 403 lines added and 35 lines deleted if you commit what is in\n+ the index, but working tree file has further modifications (one\n addition and one deletion).\n\nhttps://github.com/asciidoctor/asciidoctor/issues/4059\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/asciidoctor-extensions.rb | 6 ++++++\n 1 file changed, 6 insertions(+)\n\ndiff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb\nindex 6c4153f628..954acb3e7d 100644\n--- a/Documentation/asciidoctor-extensions.rb\n+++ b/Documentation/asciidoctor-extensions.rb\n@@ -4,6 +4,12 @@ Asciidoctor::Extensions.register :git do\n \n doc = document\n \n+ # Override attributes for man pages.\n+ # https://github.com/asciidoctor/asciidoctor/issues/4059\n+ if doc.backend == 'manpage'\n+ doc.attributes.merge!({ 'litdd' => '\\--', 'plus' => '+' })\n+ end\n+\n inline_macro :linkgit do\n if doc.doctype == 'book'\n format = '%1$s(%2$s)'\n-- \n2.32.0\n\n"},{"id":"428073","messageId":"20210621163110.1074145-24-felipe.contreras@gmail.com","threadId":"55977","inReplyTo":"20210621163110.1074145-1-felipe.contreras@gmail.com","subject":"[PATCH 23/23] doc: asciidoctor: add hack for old versions","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-21T16:31:10Z","receivedAt":"2021-06-21T16:59:56Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"\\\\ gets converted erroneously.\n\n[1] https://github.com/asciidoctor/asciidoctor/issues/3456\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/asciidoctor-extensions.rb | 13 +++++++++++--\n 1 file changed, 11 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb\nindex e48a381b8f..3ab669dad8 100644\n--- a/Documentation/asciidoctor-extensions.rb\n+++ b/Documentation/asciidoctor-extensions.rb\n@@ -38,10 +38,19 @@ Asciidoctor::Extensions.register :git do\n \n doc = document\n \n- # Override attributes for man pages.\n- # https://github.com/asciidoctor/asciidoctor/issues/4059\n if doc.backend == 'manpage'\n+ # Override attributes for man pages.\n+ # https://github.com/asciidoctor/asciidoctor/issues/4059\n doc.attributes.merge!({ 'litdd' => '\\--', 'plus' => '+' })\n+\n+ # Fix bug with \\\\\n+ if Asciidoctor::VERSION < '2.0.11'\n+ postprocessor do\n+ process do |_, output|\n+ output.gsub(\"\\\\(rs\\\\\\\\\", \"\\\\(rs\\\\(rs\\\\\")\n+ end\n+ end\n+ end\n end\n \n inline_macro :linkgit do\n-- \n2.32.0\n\n"},{"id":"428074","messageId":"20210621163110.1074145-22-felipe.contreras@gmail.com","threadId":"55977","inReplyTo":"20210621163110.1074145-1-felipe.contreras@gmail.com","subject":"[PATCH 21/23] doc: asciidoctor: add support for baseurl","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-21T16:31:08Z","receivedAt":"2021-06-21T17:00:01Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"So that we can present relative links correctly.\n\nReduces the doc-diff:\n\n NOTES\n - 1. “Understanding history: What is a branch?”\n - file:///$HOME/share/doc/git-doc/user-manual.html#what-is-a-branch\n + [1] “Understanding history: What is a branch?”\n + user-manual.html#what-is-a-branch\n\n NOTES\n - 1. “Understanding history: What is a branch?”\n + [1] “Understanding history: What is a branch?”\n file:///$HOME/share/doc/git-doc/user-manual.html#what-is-a-branch\n\nSigned-off-by: Felipe Contreras \n---\n Documentation/Makefile | 1 +\n Documentation/asciidoctor-extensions.rb | 4 +++-\n 2 files changed, 4 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex e6af1848cc..dea0f2d859 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -185,6 +185,7 @@ ASCIIDOC_DOCBOOK = docbook5\n ASCIIDOC_EXTRA += -acompat-mode -atabsize=8\n ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions\n ASCIIDOC_EXTRA += -alitdd='&\\#x2d;&\\#x2d;'\n+ASCIIDOC_EXTRA += -abaseurl='$(MAN_BASE_URL)'\n ASCIIDOC_DEPS = asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS\n DBLATEX_COMMON =\n XMLTO_EXTRA += --skip-validation\ndiff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb\nindex 914e6f64c8..8856f2febd 100644\n--- a/Documentation/asciidoctor-extensions.rb\n+++ b/Documentation/asciidoctor-extensions.rb\n@@ -16,7 +16,9 @@ module Asciidoctor\n \n footnote = doc.footnotes.find { |e| e.id == node.target }\n if !footnote\n- footnote_text = \"%s\\n\\e.RS\\n\\e\\\\%%%s\\n\\e.RE\" % [node.text, node.target]\n+ target = node.target\n+ target = doc.attributes['baseurl'] + target unless target.include? ':'\n+ footnote_text = \"%s\\n\\e.RS\\n\\e\\\\%%%s\\n\\e.RE\" % [node.text, target]\n index = doc.counter('footnote-number')\n footnote = Document::Footnote.new(index, node.target, footnote_text)\n doc.register(:footnotes, footnote)\n-- \n2.32.0\n\n"},{"id":"428175","messageId":"cfa20758-ac40-1fbf-a8f9-411e795c77b7@gmail.com","threadId":"55977","inReplyTo":"20210621163110.1074145-16-felipe.contreras@gmail.com","subject":"Re: [PATCH 15/23] doc: use asciidoctor to build man pages directly","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-06-22T05:23:39Z","receivedAt":"2021-06-22T05:23:53Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"On 21/06/21 23.31, Felipe Contreras wrote:\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\nWhy not just USE_ASCIIDOCTOR_MANPAGE implies USE_ASCIIDOCTOR?\n\n-- \nAn old man doll... just what I always wanted! - Clara\n"},{"id":"428176","messageId":"f660c96f-cc30-6a18-00ba-82a2673aa3bd@gmail.com","threadId":"55977","inReplyTo":"20210621163110.1074145-1-felipe.contreras@gmail.com","subject":"Re: [PATCH 00/23] doc: cleanups and asciidoctor direct man pages","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-06-22T05:35:02Z","receivedAt":"2021-06-22T05:35:17Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"On 21/06/21 23.30, Felipe Contreras wrote:\n> I already sent the first part of this series separately multiple times,\n> the last one is 4 simple obviously correct patches [1], but since the\n> maintainer has admitted he has no problem ignoring valid work\n> entirely due to personal animus [2], I'm sending the whole chain.\n> \n> There's no point in carefully selecting multiple series of patches to be\n> merged one by one when all of them are going to be ignored. So I'm\n> sending all 3 series at once.\n> \n> Hopefully by sending it all at once some people will be able to realize\n> that:\n> \n> 1. They are valid\n> 2. They are helpful\n> 3. They make the code more maintainable\n> 4. They enable new features\n> 5. They enable the new features to be easily tested\n> 6. They reduce the doc-diff of the new feature, as well as others\n> 7. They are superior to the competing series currently in seen\n> 8. They include work of multiple contributors\n> \n> Any fair and impartial maintainer would attempt to pick them up.\n> \n> Cheers.\n> \n\nI think the next step after this patch series is to add asciidoctor \ndirect man pages generation option to ./configure script (maybe \n--enable-asciidoctor-manpage?). But before that, we need to add \n--enable-asciidoctor option, which sets USE_ASCIIDOCTOR=YesPlease.\n\n-- \nAn old man doll... just what I always wanted! - Clara\n"},{"id":"428242","messageId":"60d28fee6e914_3122083f@natae.notmuch","threadId":"55977","inReplyTo":"cfa20758-ac40-1fbf-a8f9-411e795c77b7@gmail.com","subject":"Re: [PATCH 15/23] doc: use asciidoctor to build man pages directly","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-23T01:35:42Z","receivedAt":"2021-06-23T01:35:47Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Bagas Sanjaya wrote:\n> On 21/06/21 23.31, Felipe Contreras wrote:\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> \n> Why not just USE_ASCIIDOCTOR_MANPAGE implies USE_ASCIIDOCTOR?\n\nPersonally I don't see the point of USE_ASCIIDOCTOR_MANPAGE at all. The\nonly reason I added it was because Martin requested it [1].\n\nIt would be nice of you and Martin could make a decision about this, and\nI would just implement what you decide (or other people willing to\ncollaborate on this).\n\nI don't have an opinion on this.\n\nIf no decision is reached, I'll make USE_ASCIIDOCTOR_MANPAGE imply\nUSE_ASCIIDOCTOR as you suggest.\n\nCheers.\n\n[1] https://lore.kernel.org/git/CAN0heSpX53tK8Z4XSx4sp79b+XWKZg5+ABW8pmzBSHPZ+qy+oQ@mail.gmail.com/\n\n-- \nFelipe Contreras\n"},{"id":"428243","messageId":"60d2903f59f39_3122087c@natae.notmuch","threadId":"55977","inReplyTo":"f660c96f-cc30-6a18-00ba-82a2673aa3bd@gmail.com","subject":"Re: [PATCH 00/23] doc: cleanups and asciidoctor direct man pages","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-23T01:37:03Z","receivedAt":"2021-06-23T01:37:08Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Bagas Sanjaya wrote:\n> On 21/06/21 23.30, Felipe Contreras wrote:\n> > I already sent the first part of this series separately multiple times,\n> > the last one is 4 simple obviously correct patches [1], but since the\n> > maintainer has admitted he has no problem ignoring valid work\n> > entirely due to personal animus [2], I'm sending the whole chain.\n> > \n> > There's no point in carefully selecting multiple series of patches to be\n> > merged one by one when all of them are going to be ignored. So I'm\n> > sending all 3 series at once.\n> > \n> > Hopefully by sending it all at once some people will be able to realize\n> > that:\n> > \n> > 1. They are valid\n> > 2. They are helpful\n> > 3. They make the code more maintainable\n> > 4. They enable new features\n> > 5. They enable the new features to be easily tested\n> > 6. They reduce the doc-diff of the new feature, as well as others\n> > 7. They are superior to the competing series currently in seen\n> > 8. They include work of multiple contributors\n> > \n> > Any fair and impartial maintainer would attempt to pick them up.\n> > \n> > Cheers.\n> > \n> \n> I think the next step after this patch series is to add asciidoctor \n> direct man pages generation option to ./configure script (maybe \n> --enable-asciidoctor-manpage?). But before that, we need to add \n> --enable-asciidoctor option, which sets USE_ASCIIDOCTOR=YesPlease.\n\nMaybe. I don't use ./configure, so perhaps somebody that does should\ntake charge of this.\n\n-- \nFelipe Contreras\n"}]}