{"thread":{"id":"55752","subject":"[PATCH v2 00/11] doc: asciidoctor: direct man page creation and fixes","startedAt":"2021-05-21T22:44:58Z","lastAt":"2021-06-02T20:12:31Z","messageCount":17,"participants":["Felipe Contreras","Bagas Sanjaya"],"isPatch":true,"patchVersion":2,"patchTotal":11},"messages":[{"id":"425264","messageId":"20210521224452.530852-1-felipe.contreras@gmail.com","threadId":"55752","inReplyTo":null,"subject":"[PATCH v2 00/11] doc: asciidoctor: direct man page creation and fixes","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-21T22:44:41Z","receivedAt":"2021-05-21T22:44:58Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"This patch series enables direct man page creation with asciidoctor, but in addition tries to\nminimize the difference with asciidoc+docbook.\n\nI fixed as many issues as I could, and now the doc-diff looks very sensible. I could not find any\nmajor issues, however, some minor ones still remain.\n\nOn the other hand the asciidoc method has issues as well, so it's not clear which method is superior\nat this point; both have advantages and disadvantages.\n\nAt the very least the man pages with pure asciidoctor should be quite usable now.\n\nThis series builds on top of my previous cleanups [1].\n\n[1] https://lore.kernel.org/git/20210521223701.526547-1-felipe.contreras@gmail.com/\n\nFelipe Contreras (9):\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/Makefile                  | 15 ++++++--\n Documentation/asciidoctor-extensions.rb | 51 +++++++++++++++++++++++++\n Documentation/doc-diff                  | 35 +++++++++--------\n 3 files changed, 82 insertions(+), 19 deletions(-)\n\nRange-diff against v1:\n 1:  de0ecf9c0e <  -:  ---------- doc: allow the user to provide ASCIIDOC_EXTRA\n 2:  22a35efa3f <  -:  ---------- doc: doc-diff: allow more than one flag\n 3:  a8ad5c703a <  -:  ---------- doc: doc-diff: set docdate manually\n 4:  4d0266a3a1 <  -:  ---------- doc: use asciidoctor to build man pages directly\n 5:  5efb19348b <  -:  ---------- doc: asciidoctor: add linkgit macros in man pages\n 6:  d5d006298e <  -:  ---------- doc: join mansource and manversion\n 7:  7c8b502df9 <  -:  ---------- doc: add man pages workaround for asciidoctor\n -:  ---------- >  1:  a2f85f4b05 doc: doc-diff: set docdate manually\n -:  ---------- >  2:  13085a13b6 doc-diff: drop --cut-footer switch\n -:  ---------- >  3:  f0b3576d77 doc: use asciidoctor to build man pages directly\n -:  ---------- >  4:  8b3bb9e9f4 doc-diff: support asciidoctor man pages\n -:  ---------- >  5:  3f9859b223 doc: asciidoctor: add linkgit macros in man pages\n -:  ---------- >  6:  df27fcb9a2 doc: add man pages workaround for asciidoctor\n 8:  5d5e9d99ac !  7:  5f0ae41e3e doc: asciidoctor: add hack for xrefs\n    @@ Commit message\n     \n      ## Documentation/asciidoctor-extensions.rb ##\n     @@\n    - require 'asciidoctor'\n      require 'asciidoctor/extensions'\n     +require 'asciidoctor/converter/manpage'\n     +\n    @@ Documentation/asciidoctor-extensions.rb\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    - module Git\n    -   module Documentation\n    + Asciidoctor::Extensions.register :git do\n    + \n 9:  f4a4f1394e =  8:  a8fb29d893 doc: asciidoctor: add hack to improve links\n10:  894802bfbb !  9:  272e6e8551 doc: asciidoctor: add support for baseurl\n    @@ Commit message\n     \n      ## Documentation/Makefile ##\n     @@ Documentation/Makefile: ASCIIDOC_DOCBOOK = docbook5\n    - override ASCIIDOC_EXTRA += -acompat-mode -atabsize=8\n    - override ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions\n    - override ASCIIDOC_EXTRA += -alitdd='&\\#x2d;&\\#x2d;'\n    -+override ASCIIDOC_EXTRA += -abaseurl='$(MAN_BASE_URL)'\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\n11:  d3b6899ed8 ! 10:  928a632038 doc: asciidoctor: cleanup man page hack\n    @@ Documentation/asciidoctor-extensions.rb: module Asciidoctor\n     +        nil\n            end\n          end\n    -   end\n    +     alias inline_anchor convert_inline_anchor # For old versions of asciidoctor\n -:  ---------- > 11:  758e5be3b7 doc: asciidoctor: add hack for old versions\n-- \n2.32.0.rc0\n\n"},{"id":"425265","messageId":"20210521224452.530852-2-felipe.contreras@gmail.com","threadId":"55752","inReplyTo":"20210521224452.530852-1-felipe.contreras@gmail.com","subject":"[PATCH v2 01/11] doc: doc-diff: set docdate manually","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-21T22:44:42Z","receivedAt":"2021-05-21T22:45:00Z","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 <peff@peff.net>\nSigned-off-by: Felipe Contreras <felipe.contreras@gmail.com>\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.rc0\n\n"},{"id":"425266","messageId":"20210521224452.530852-3-felipe.contreras@gmail.com","threadId":"55752","inReplyTo":"20210521224452.530852-1-felipe.contreras@gmail.com","subject":"[PATCH v2 02/11] doc-diff: drop --cut-footer switch","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-21T22:44:43Z","receivedAt":"2021-05-21T22:45:03Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"From: Martin Ågren <martin.agren@gmail.com>\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 <martin.agren@gmail.com>\nSigned-off-by: Felipe Contreras <felipe.contreras@gmail.com>\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 <srcdir> <dstdir>\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.rc0\n\n"},{"id":"425269","messageId":"20210521224452.530852-4-felipe.contreras@gmail.com","threadId":"55752","inReplyTo":"20210521224452.530852-1-felipe.contreras@gmail.com","subject":"[PATCH v2 03/11] doc: use asciidoctor to build man pages directly","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-21T22:44:44Z","receivedAt":"2021-05-21T22:45:05Z","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 <bagasdotme@gmail.com>\nSigned-off-by: Felipe Contreras <felipe.contreras@gmail.com>\n---\n Documentation/Makefile | 12 ++++++++++--\n 1 file changed, 10 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex b68ab57239..0c654f4ec9 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-%.1 %.5 %.7 : %.xml $(wildcard manpage*.xsl)\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 manpage-base-url.xsl $(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 $@ $<\n-- \n2.32.0.rc0\n\n"},{"id":"425267","messageId":"20210521224452.530852-5-felipe.contreras@gmail.com","threadId":"55752","inReplyTo":"20210521224452.530852-1-felipe.contreras@gmail.com","subject":"[PATCH v2 04/11] doc-diff: support asciidoctor man pages","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-21T22:44:45Z","receivedAt":"2021-05-21T22:45:06Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"From: Jeff King <peff@peff.net>\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 <peff@peff.net>\nSigned-off-by: Felipe Contreras <felipe.contreras@gmail.com>\n---\n Documentation/doc-diff | 17 +++++++++++++++++\n 1 file changed, 17 insertions(+)\n\ndiff --git a/Documentation/doc-diff b/Documentation/doc-diff\nindex 6b6bb444ac..52cf639f4d 100755\n--- a/Documentation/doc-diff\n+++ b/Documentation/doc-diff\n@@ -17,10 +17,14 @@ 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+cut-footer\t\tcut away footer\n \"\n SUBDIRECTORY_OK=1\n . \"$(git --exec-path)/git-sh-setup\"\n@@ -53,6 +57,15 @@ 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--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 +121,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.rc0\n\n"},{"id":"425268","messageId":"20210521224452.530852-6-felipe.contreras@gmail.com","threadId":"55752","inReplyTo":"20210521224452.530852-1-felipe.contreras@gmail.com","subject":"[PATCH v2 05/11] doc: asciidoctor: add linkgit macros in man pages","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-21T22:44:46Z","receivedAt":"2021-05-21T22:45:09Z","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 <sandals@crustytoothpaste.net>\nSigned-off-by: Felipe Contreras <felipe.contreras@gmail.com>\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 = %(<a href=\"#{prefix}%1$s.html\">%1$s(%2$s)</a>)\n+    elsif doc.basebackend? 'manpage'\n+      format = \"\\e\\\\fB%s\\e\\\\fP(%s)\"\n     elsif doc.basebackend? 'docbook'\n       format = <<~EOF.chomp\n       <citerefentry>\n-- \n2.32.0.rc0\n\n"},{"id":"425270","messageId":"20210521224452.530852-7-felipe.contreras@gmail.com","threadId":"55752","inReplyTo":"20210521224452.530852-1-felipe.contreras@gmail.com","subject":"[PATCH v2 06/11] doc: add man pages workaround for asciidoctor","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-21T22:44:47Z","receivedAt":"2021-05-21T22:45:13Z","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&#x2d;&#x2d;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 <felipe.contreras@gmail.com>\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 = '<ulink url=\"%1$s.html\">%1$s(%2$s)</ulink>'\n-- \n2.32.0.rc0\n\n"},{"id":"425271","messageId":"20210521224452.530852-8-felipe.contreras@gmail.com","threadId":"55752","inReplyTo":"20210521224452.530852-1-felipe.contreras@gmail.com","subject":"[PATCH v2 07/11] doc: asciidoctor: add hack for xrefs","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-21T22:44:48Z","receivedAt":"2021-05-21T22:45:16Z","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 <felipe.contreras@gmail.com>\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 &#8220;%s&#8221;' % 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.rc0\n\n"},{"id":"425272","messageId":"20210521224452.530852-9-felipe.contreras@gmail.com","threadId":"55752","inReplyTo":"20210521224452.530852-1-felipe.contreras@gmail.com","subject":"[PATCH v2 08/11] doc: asciidoctor: add hack to improve links","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-21T22:44:49Z","receivedAt":"2021-05-21T22:45:20Z","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+       <https://github.com/newren/git-filter-repo/> 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 <felipe.contreras@gmail.com>\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 &#8220;%s&#8221;' % 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.rc0\n\n"},{"id":"425273","messageId":"20210521224452.530852-10-felipe.contreras@gmail.com","threadId":"55752","inReplyTo":"20210521224452.530852-1-felipe.contreras@gmail.com","subject":"[PATCH v2 09/11] doc: asciidoctor: add support for baseurl","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-21T22:44:50Z","receivedAt":"2021-05-21T22:45:21Z","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 <felipe.contreras@gmail.com>\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 0c654f4ec9..c28c49dd7a 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.rc0\n\n"},{"id":"425274","messageId":"20210521224452.530852-11-felipe.contreras@gmail.com","threadId":"55752","inReplyTo":"20210521224452.530852-1-felipe.contreras@gmail.com","subject":"[PATCH v2 10/11] doc: asciidoctor: cleanup man page hack","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-21T22:44:51Z","receivedAt":"2021-05-21T22:45:22Z","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 <felipe.contreras@gmail.com>\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.rc0\n\n"},{"id":"425275","messageId":"20210521224452.530852-12-felipe.contreras@gmail.com","threadId":"55752","inReplyTo":"20210521224452.530852-1-felipe.contreras@gmail.com","subject":"[PATCH v2 11/11] doc: asciidoctor: add hack for old versions","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-21T22:44:52Z","receivedAt":"2021-05-21T22:45:22Z","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 <felipe.contreras@gmail.com>\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.rc0\n\n"},{"id":"425277","messageId":"60a83956270be_81ac020848@natae.notmuch","threadId":"55752","inReplyTo":"20210521224452.530852-1-felipe.contreras@gmail.com","subject":"RE: [PATCH v2 00/11] doc: asciidoctor: direct man page creation and fixes","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-21T22:51:02Z","receivedAt":"2021-05-21T22:51:05Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Felipe Contreras wrote:\n> This patch series enables direct man page creation with asciidoctor, but in addition tries to\n> minimize the difference with asciidoc+docbook.\n> \n> I fixed as many issues as I could, and now the doc-diff looks very sensible. I could not find any\n> major issues, however, some minor ones still remain.\n> \n> On the other hand the asciidoc method has issues as well, so it's not clear which method is superior\n> at this point; both have advantages and disadvantages.\n> \n> At the very least the man pages with pure asciidoctor should be quite usable now.\n> \n> This series builds on top of my previous cleanups [1].\n\nI forgot to mention what changed since v1:\n\n * The option USE_ASCIIDOCTOR_MANPAGE was added\n * Jeff's patch for *asciidoctor-direct optiosn to doc-diff was added\n * Martin Ågren's patch to remove -cut-footer was added\n * The format of linkgit was updated to be closer to brian's version\n   (though not quite the same)\n * A few tiny cleanups\n\n-- \nFelipe Contreras"},{"id":"425278","messageId":"60a8399b8a0b8_81ac02084c@natae.notmuch","threadId":"55752","inReplyTo":"20210521224452.530852-5-felipe.contreras@gmail.com","subject":"RE: [PATCH v2 04/11] doc-diff: support asciidoctor man pages","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-21T22:52:11Z","receivedAt":"2021-05-21T22:52:18Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Felipe Contreras wrote:\n> From: Jeff King <peff@peff.net>\n> diff --git a/Documentation/doc-diff b/Documentation/doc-diff\n> index 6b6bb444ac..52cf639f4d 100755\n> --- a/Documentation/doc-diff\n> +++ b/Documentation/doc-diff\n> @@ -17,10 +17,14 @@ 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> +cut-footer\t\tcut away footer\n\nOops. This obviously sneaked by; doesn't belong here.\n\n-- \nFelipe Contreras\n"},{"id":"425287","messageId":"0c4ca3b5-7be4-1cdc-fbf1-b7a1541fe4b2@gmail.com","threadId":"55752","inReplyTo":"20210521224452.530852-2-felipe.contreras@gmail.com","subject":"Re: [PATCH v2 01/11] doc: doc-diff: set docdate manually","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-05-22T04:25:11Z","receivedAt":"2021-05-22T04:27:53Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"On 22/05/21 05.44, Felipe Contreras wrote:\n> In order to minimize the differences in the footer.\n> \n> Asciidoc automatically generates a date with format '%Y-%m-%d', while\n> asciidoctor '%F'.\n> \n\n%F is short yyyy-mm-dd date. AFAIK, it is the same effect as `%Y-%m-%d`.\n\n> I personally prefer the latter, so only modify it for diff purposes.\n> \n> Fixes tons of these:\n> \n> -Git omitted                       01/01/1970                        GIT-ADD(1)\n> +Git omitted                       1970-01-01                        GIT-ADD(1)\n>\n  \nSo, the asciidoctor generated date was the bottom one, while the asciidoc\ncounterpart was the above one, right?\n\nThe above one, however, was actually %m/%d/%Y.\n\n-- \nAn old man doll... just what I always wanted! - Clara\n"},{"id":"425349","messageId":"60a9775a494b5_857e9208ca@natae.notmuch","threadId":"55752","inReplyTo":"0c4ca3b5-7be4-1cdc-fbf1-b7a1541fe4b2@gmail.com","subject":"Re: [PATCH v2 01/11] doc: doc-diff: set docdate manually","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-05-22T21:27:54Z","receivedAt":"2021-05-22T21:28:10Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Bagas Sanjaya wrote:\n> On 22/05/21 05.44, Felipe Contreras wrote:\n> > In order to minimize the differences in the footer.\n> > \n> > Asciidoc automatically generates a date with format '%Y-%m-%d', while\n> > asciidoctor '%F'.\n> > \n> \n> %F is short yyyy-mm-dd date. AFAIK, it is the same effect as `%Y-%m-%d`.\n\nRight, I noticed I was wrong when trying to use -adocdate in\nasciidoctor. It's actually ignored.\n\nThe date format probably comes from docbook. The commit message needs to\nbe updated.\n\n> > I personally prefer the latter, so only modify it for diff purposes.\n> > \n> > Fixes tons of these:\n> > \n> > -Git omitted                       01/01/1970                        GIT-ADD(1)\n> > +Git omitted                       1970-01-01                        GIT-ADD(1)\n> >\n>   \n> So, the asciidoctor generated date was the bottom one, while the asciidoc\n> counterpart was the above one, right?\n\nYeap.\n\n> The above one, however, was actually %m/%d/%Y.\n\nIndeed, the commit message is inaccurate.\n\n-- \nFelipe Contreras\n"},{"id":"426258","messageId":"60b7e5e1748a5_1690a3208cb@natae.notmuch","threadId":"55752","inReplyTo":"20210521224452.530852-4-felipe.contreras@gmail.com","subject":"RE: [PATCH v2 03/11] doc: use asciidoctor to build man pages directly","fromName":"Felipe Contreras","fromEmail":"felipe.contreras@gmail.com","sentAt":"2021-06-02T20:11:13Z","receivedAt":"2021-06-02T20:12:31Z","isPatch":true,"sender":{"key":"felipe.contreras@gmail.com","avatar":"https://avatars.githubusercontent.com/u/8358?v=4"},"body":"Felipe Contreras wrote:\n> --- a/Documentation/Makefile\n> +++ b/Documentation/Makefile\n\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> -%.1 %.5 %.7 : %.xml $(wildcard manpage*.xsl)\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 manpage-base-url.xsl $(wildcard manpage*.xsl)\n>  \t$(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<\n> +endif\n\nThis was a conflict mistake, the manpage-base-url.xsl file is not\npresent any more, should be:\n\n+%.1 %.5 %.7 : %.xml $(wildcard manpage*.xsl)\n\nI fixed in my local branch.\n\n-- \nFelipe Contreras\n"}]}