[PATCH 00/23] doc: cleanups and asciidoctor direct man pages

[PATCH 00/23] doc: cleanups and asciidoctor direct man pages

[Felipe Contreras]

I already sent the first part of this series separately multiple times,
the last one is 4 simple obviously correct patches [1], but since the
maintainer has admitted he has no problem ignoring valid work
entirely due to personal animus [2], I'm sending the whole chain.

There's no point in carefully selecting multiple series of patches to be
merged one by one when all of them are going to be ignored. So I'm
sending all 3 series at once.

Hopefully by sending it all at once some people will be able to realize
that:

 1. They are valid
 2. They are helpful
 3. They make the code more maintainable
 4. They enable new features
 5. They enable the new features to be easily tested
 6. They reduce the doc-diff of the new feature, as well as others
 7. They are superior to the competing series currently in seen
 8. They include work of multiple contributors

Any fair and impartial maintainer would attempt to pick them up.

Cheers.

[1] https://lore.kernel.org/git/20210618215231.796592-1-felipe.contreras@gmail.com/
[2] https://lore.kernel.org/git/xmqqmtrmjpa8.fsf@gitster.g/

Felipe Contreras (21):
  doc: remove GNU troff workaround
  doc: use --stringparam in xmlto
  doc: simplify version passing
  doc: asciidoc: remove unnecessary attribute
  doc: asciidoctor: remove unnecessary require
  doc: asciidoctor: remove cruft
  doc: asciidoctor: reorganize extensions
  doc: asciidoctor: use html-prefix only for html
  doc: asciidoctor: refactor macro registration
  doc: asciidoctor: improve string handling
  doc: asciidoctor: split the format from the code
  doc: asciidoctor: specify name of our group
  doc: doc-diff: set docdate manually
  doc: use asciidoctor to build man pages directly
  doc: asciidoctor: add linkgit macros in man pages
  doc: add man pages workaround for asciidoctor
  doc: asciidoctor: add hack for xrefs
  doc: asciidoctor: add hack to improve links
  doc: asciidoctor: add support for baseurl
  doc: asciidoctor: cleanup man page hack
  doc: asciidoctor: add hack for old versions

Jeff King (1):
  doc-diff: support asciidoctor man pages

Martin Ågren (1):
  doc-diff: drop --cut-footer switch

 Documentation/.gitignore                |   1 -
 Documentation/Makefile                  |  32 ++++----
 Documentation/asciidoc.conf             |  20 -----
 Documentation/asciidoctor-extensions.rb | 103 +++++++++++++++---------
 Documentation/doc-diff                  |  38 ++++-----
 Documentation/manpage-base-url.xsl.in   |  10 ---
 Documentation/manpage-quote-apos.xsl    |  16 ----
 Makefile                                |   8 +-
 8 files changed, 104 insertions(+), 124 deletions(-)
 delete mode 100644 Documentation/manpage-base-url.xsl.in
 delete mode 100644 Documentation/manpage-quote-apos.xsl

-- 
2.32.0

[PATCH 01/23] doc: remove GNU troff workaround

[Felipe Contreras]

In 2007 the docbook project made the mistake of converting ' to \' for
man pages [1]. It's a problem because groff interprets \' as acute
accent which is rendered as ' in ASCII, but as ´ in utf-8.

This started a cascade of bug reports in git [2], debian [3], Arch Linux
[4], docbook itself [5], and probably many others.

A solution was to use the correct groff character: \(aq, which is always
rendered as ', but the problem is that such character doesn't work in
other troff programs.

A portable solution required the use of a conditional character that is
\(aq in groff, but ' in all others:

  .ie \n(.g .ds Aq \(aq
  .el .ds Aq '

The proper solution took time to be implemented in docbook, but in 2010
they did it [6]. So the docbook man page stylesheets were broken from
1.73 to 1.76.

Unfortunately by that point many workarounds already existed. In the
case of git GNU_ROFF was introduced, and in the case of Arch Linux
a mappig from \' to ' was added to groff's man.local. Other
distributions might have done the same, or similar workarounds.

Since 2010 there is not need for this workaround, which is fixed
elsewhere not just in docbook, but other layers as well.

Let's remove it.

Also, it's GNU troff, not GNU roff.

[1] https://github.com/docbook/xslt10-stylesheets/commit/ea2a0bac56c56eec1892ac3d9254dca89f7c5746
[2] https://lore.kernel.org/git/20091012102926.GA3937@debian.b2j/
[3] https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=507673#65
[4] https://bugs.archlinux.org/task/9643
[5] https://sourceforge.net/p/docbook/bugs/1022/
[6] https://github.com/docbook/xslt10-stylesheets/commit/fb553434265906ed81edc6d5f533d0b08d200046

Inspired-by: brian m. carlson <sandals@crustytoothpaste.net>
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/Makefile               |  8 --------
 Documentation/manpage-quote-apos.xsl | 16 ----------------
 Makefile                             |  4 ----
 3 files changed, 28 deletions(-)
 delete mode 100644 Documentation/manpage-quote-apos.xsl

diff --git a/Documentation/Makefile b/Documentation/Makefile
index f5605b7767..bf1f66b3eb 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -178,14 +178,6 @@ MAN_BASE_URL = file://$(htmldir)/
 endif
 XMLTO_EXTRA += -m manpage-base-url.xsl
 
-# If your target system uses GNU groff, it may try to render
-# apostrophes as a "pretty" apostrophe using unicode.  This breaks
-# cut&paste, so you should set GNU_ROFF to force them to be ASCII
-# apostrophes.  Unfortunately does not work with non-GNU roff.
-ifdef GNU_ROFF
-XMLTO_EXTRA += -m manpage-quote-apos.xsl
-endif
-
 ifdef USE_ASCIIDOCTOR
 ASCIIDOC = asciidoctor
 ASCIIDOC_CONF =
diff --git a/Documentation/manpage-quote-apos.xsl b/Documentation/manpage-quote-apos.xsl
deleted file mode 100644
index aeb8839f33..0000000000
--- a/Documentation/manpage-quote-apos.xsl
+++ /dev/null
@@ -1,16 +0,0 @@
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
-		version="1.0">
-
-<!-- work around newer groff/man setups using a prettier apostrophe
-     that unfortunately does not quote anything when cut&pasting
-     examples to the shell -->
-<xsl:template name="escape.apostrophe">
-  <xsl:param name="content"/>
-  <xsl:call-template name="string.subst">
-    <xsl:with-param name="string" select="$content"/>
-    <xsl:with-param name="target">'</xsl:with-param>
-    <xsl:with-param name="replacement">\(aq</xsl:with-param>
-  </xsl:call-template>
-</xsl:template>
-
-</xsl:stylesheet>
diff --git a/Makefile b/Makefile
index c3565fc0f8..7588c43f05 100644
--- a/Makefile
+++ b/Makefile
@@ -278,10 +278,6 @@ all::
 # Define NO_ST_BLOCKS_IN_STRUCT_STAT if your platform does not have st_blocks
 # field that counts the on-disk footprint in 512-byte blocks.
 #
-# Define GNU_ROFF if your target system uses GNU groff.  This forces
-# apostrophes to be ASCII so that cut&pasting examples to the shell
-# will work.
-#
 # Define USE_ASCIIDOCTOR to use Asciidoctor instead of AsciiDoc to build the
 # documentation.
 #
-- 
2.32.0

[PATCH 02/23] doc: use --stringparam in xmlto

[Felipe Contreras]

Commit 50d9bbba92 (Documentation: Avoid use of xmlto --stringparam,
2009-12-04) introduced manpage-base-url.xsl because ancient versions of
xmlto did not have --stringparam.

However, that was more than ten years ago, no need for that complexity
anymore.

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/.gitignore              |  1 -
 Documentation/Makefile                |  8 ++------
 Documentation/manpage-base-url.xsl.in | 10 ----------
 3 files changed, 2 insertions(+), 17 deletions(-)
 delete mode 100644 Documentation/manpage-base-url.xsl.in

diff --git a/Documentation/.gitignore b/Documentation/.gitignore
index 9022d48355..e9f8d693b1 100644
--- a/Documentation/.gitignore
+++ b/Documentation/.gitignore
@@ -10,7 +10,6 @@ howto-index.txt
 doc.dep
 cmds-*.txt
 mergetools-*.txt
-manpage-base-url.xsl
 SubmittingPatches.txt
 tmp-doc-diff/
 GIT-ASCIIDOCFLAGS
diff --git a/Documentation/Makefile b/Documentation/Makefile
index bf1f66b3eb..84643a34e9 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -176,7 +176,7 @@ endif
 ifndef MAN_BASE_URL
 MAN_BASE_URL = file://$(htmldir)/
 endif
-XMLTO_EXTRA += -m manpage-base-url.xsl
+XMLTO_EXTRA += --stringparam man.base.url.for.relative.links='$(MAN_BASE_URL)'
 
 ifdef USE_ASCIIDOCTOR
 ASCIIDOC = asciidoctor
@@ -342,7 +342,6 @@ clean:
 	$(RM) technical/*.html technical/api-index.txt
 	$(RM) SubmittingPatches.txt
 	$(RM) $(cmds_txt) $(mergetools_txt) *.made
-	$(RM) manpage-base-url.xsl
 	$(RM) GIT-ASCIIDOCFLAGS
 
 $(MAN_HTML): %.html : %.txt $(ASCIIDOC_DEPS)
@@ -351,10 +350,7 @@ $(MAN_HTML): %.html : %.txt $(ASCIIDOC_DEPS)
 $(OBSOLETE_HTML): %.html : %.txto $(ASCIIDOC_DEPS)
 	$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -o $@ $<
 
-manpage-base-url.xsl: manpage-base-url.xsl.in
-	$(QUIET_GEN)sed "s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|" $< > $@
-
-%.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl)
+%.1 %.5 %.7 : %.xml $(wildcard manpage*.xsl)
 	$(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
 
 %.xml : %.txt $(ASCIIDOC_DEPS)
diff --git a/Documentation/manpage-base-url.xsl.in b/Documentation/manpage-base-url.xsl.in
deleted file mode 100644
index e800904df3..0000000000
--- a/Documentation/manpage-base-url.xsl.in
+++ /dev/null
@@ -1,10 +0,0 @@
-<!-- manpage-base-url.xsl:
-     special settings for manpages rendered from newer docbook -->
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
-		version="1.0">
-
-<!-- set a base URL for relative links -->
-<xsl:param name="man.base.url.for.relative.links"
-	>@@MAN_BASE_URL@@</xsl:param>
-
-</xsl:stylesheet>
-- 
2.32.0

[PATCH 03/23] doc: simplify version passing

[Felipe Contreras]

The code to pass the version of the man page comes from 2007:
7ef195ba3e (Documentation: Add version information to man pages,
2007-03-25). However, both asciidoc and asciidoctor already do this by
default.

Asciidoctor doesn't read manversion, but there's no need since both
tools just join mansource and manversion.

Let's do that ourselves and get rid of a bunch of code.

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/Makefile                  |  3 +--
 Documentation/asciidoc.conf             | 19 -------------------
 Documentation/asciidoctor-extensions.rb | 17 -----------------
 3 files changed, 1 insertion(+), 38 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 84643a34e9..47053c78f8 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -137,8 +137,7 @@ ASCIIDOC_HTML = xhtml11
 ASCIIDOC_DOCBOOK = docbook
 ASCIIDOC_CONF = -f asciidoc.conf
 ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \
-		-amanversion=$(GIT_VERSION) \
-		-amanmanual='Git Manual' -amansource='Git'
+		-amanmanual='Git Manual' -amansource='Git $(GIT_VERSION)'
 ASCIIDOC_DEPS = asciidoc.conf GIT-ASCIIDOCFLAGS
 TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML)
 TXT_TO_XML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_DOCBOOK)
diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index 3e4c13971b..60f76f43ed 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf
@@ -51,25 +51,6 @@ ifdef::doctype-manpage[]
 endif::doctype-manpage[]
 endif::backend-docbook[]
 
-ifdef::doctype-manpage[]
-ifdef::backend-docbook[]
-[header]
-template::[header-declarations]
-<refentry>
-<refmeta>
-<refentrytitle>{mantitle}</refentrytitle>
-<manvolnum>{manvolnum}</manvolnum>
-<refmiscinfo class="source">{mansource}</refmiscinfo>
-<refmiscinfo class="version">{manversion}</refmiscinfo>
-<refmiscinfo class="manual">{manmanual}</refmiscinfo>
-</refmeta>
-<refnamediv>
-  <refname>{manname}</refname>
-  <refpurpose>{manpurpose}</refpurpose>
-</refnamediv>
-endif::backend-docbook[]
-endif::doctype-manpage[]
-
 ifdef::backend-xhtml11[]
 [attributes]
 git-relative-html-prefix=
diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index d906a00803..70a0956663 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -23,26 +23,9 @@ module Git
         end
       end
     end
-
-    class DocumentPostProcessor < Asciidoctor::Extensions::Postprocessor
-      def process document, output
-        if document.basebackend? 'docbook'
-          mansource = document.attributes['mansource']
-          manversion = document.attributes['manversion']
-          manmanual = document.attributes['manmanual']
-          new_tags = "" \
-            "<refmiscinfo class=\"source\">#{mansource}</refmiscinfo>\n" \
-            "<refmiscinfo class=\"version\">#{manversion}</refmiscinfo>\n" \
-            "<refmiscinfo class=\"manual\">#{manmanual}</refmiscinfo>\n"
-          output = output.sub(/<\/refmeta>/, new_tags + "</refmeta>")
-        end
-        output
-      end
-    end
   end
 end
 
 Asciidoctor::Extensions.register do
   inline_macro Git::Documentation::LinkGitProcessor, :linkgit
-  postprocessor Git::Documentation::DocumentPostProcessor
 end
-- 
2.32.0

[PATCH 04/23] doc: asciidoc: remove unnecessary attribute

[Felipe Contreras]

It's part of asciidoc global configuration since 2012.

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/asciidoc.conf | 1 -
 1 file changed, 1 deletion(-)

diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf
index 60f76f43ed..f7908f9dea 100644
--- a/Documentation/asciidoc.conf
+++ b/Documentation/asciidoc.conf
@@ -12,7 +12,6 @@
 
 [attributes]
 asterisk=&#42;
-plus=&#43;
 caret=&#94;
 startsb=&#91;
 endsb=&#93;
-- 
2.32.0

[PATCH 05/23] doc: asciidoctor: remove unnecessary require

[Felipe Contreras]

This file is loaded by asciidoctor, the module is already loaded.

In addition to being less redundant this fixes a problem while trying
use a development version of asciidoctor when the gem is available:

  $GEM_HOME/gems/asciidoctor-2.0.15/lib/asciidoctor.rb:51:
    warning: already initialized constant Asciidoctor::RUBY_ENGINE
  $HOME/asciidoctor/lib/asciidoctor.rb:52:
    warning: previous definition of RUBY_ENGINE was here
  ...

That's a bug in asciidoctor, but there's no need to trigger it.

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/asciidoctor-extensions.rb | 1 -
 1 file changed, 1 deletion(-)

diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index 70a0956663..423450392d 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -1,4 +1,3 @@
-require 'asciidoctor'
 require 'asciidoctor/extensions'
 
 module Git
-- 
2.32.0

[PATCH 06/23] doc: asciidoctor: remove cruft

[Felipe Contreras]

These were probably copy-pasted from other extensions. The name is
already defined (:linkgit), and we are not using the DSL mode.

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/asciidoctor-extensions.rb | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index 423450392d..3dea106d00 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -3,10 +3,6 @@ require 'asciidoctor/extensions'
 module Git
   module Documentation
     class LinkGitProcessor < Asciidoctor::Extensions::InlineMacroProcessor
-      use_dsl
-
-      named :chrome
-
       def process(parent, target, attrs)
         prefix = parent.document.attr('git-relative-html-prefix')
         if parent.document.doctype == 'book'
-- 
2.32.0

[PATCH 07/23] doc: asciidoctor: reorganize extensions

[Felipe Contreras]

There's no need to create verbose classes, we can do the same with a
simple block.

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/asciidoctor-extensions.rb | 34 +++++++++++--------------
 1 file changed, 15 insertions(+), 19 deletions(-)

diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index 3dea106d00..f998a42249 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -1,26 +1,22 @@
 require 'asciidoctor/extensions'
 
-module Git
-  module Documentation
-    class LinkGitProcessor < Asciidoctor::Extensions::InlineMacroProcessor
-      def process(parent, target, attrs)
-        prefix = parent.document.attr('git-relative-html-prefix')
-        if parent.document.doctype == 'book'
-          "<ulink url=\"#{prefix}#{target}.html\">" \
-          "#{target}(#{attrs[1]})</ulink>"
-        elsif parent.document.basebackend? 'html'
-          %(<a href="#{prefix}#{target}.html">#{target}(#{attrs[1]})</a>)
-        elsif parent.document.basebackend? 'docbook'
-          "<citerefentry>\n" \
-            "<refentrytitle>#{target}</refentrytitle>" \
-            "<manvolnum>#{attrs[1]}</manvolnum>\n" \
-          "</citerefentry>"
-        end
+Asciidoctor::Extensions.register do
+
+  inline_macro :linkgit do
+    process do |parent, target, attrs|
+      prefix = parent.document.attr('git-relative-html-prefix')
+      if parent.document.doctype == 'book'
+        "<ulink url=\"#{prefix}#{target}.html\">" \
+        "#{target}(#{attrs[1]})</ulink>"
+      elsif parent.document.basebackend? 'html'
+        %(<a href="#{prefix}#{target}.html">#{target}(#{attrs[1]})</a>)
+      elsif parent.document.basebackend? 'docbook'
+        "<citerefentry>\n" \
+          "<refentrytitle>#{target}</refentrytitle>" \
+          "<manvolnum>#{attrs[1]}</manvolnum>\n" \
+        "</citerefentry>"
       end
     end
   end
-end
 
-Asciidoctor::Extensions.register do
-  inline_macro Git::Documentation::LinkGitProcessor, :linkgit
 end
-- 
2.32.0

[PATCH 08/23] doc: asciidoctor: use html-prefix only for html

[Felipe Contreras]

This is what asciidoc.conf does.

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/asciidoctor-extensions.rb | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index f998a42249..c77b6de350 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -4,11 +4,11 @@ Asciidoctor::Extensions.register do
 
   inline_macro :linkgit do
     process do |parent, target, attrs|
-      prefix = parent.document.attr('git-relative-html-prefix')
       if parent.document.doctype == 'book'
-        "<ulink url=\"#{prefix}#{target}.html\">" \
+        "<ulink url=\"#{target}.html\">" \
         "#{target}(#{attrs[1]})</ulink>"
       elsif parent.document.basebackend? 'html'
+        prefix = parent.document.attr('git-relative-html-prefix')
         %(<a href="#{prefix}#{target}.html">#{target}(#{attrs[1]})</a>)
       elsif parent.document.basebackend? 'docbook'
         "<citerefentry>\n" \
-- 
2.32.0

[PATCH 09/23] doc: asciidoctor: refactor macro registration

[Felipe Contreras]

There is no need to execute extra code every time the process block is
called.

In Ruby the lexical scope is shared, so we can define variables in the
register block scope, and all the rest will inherit those variables.

Based on the doctype and basebackend one of three blocks is selected for
the inline_macro. However, the conditionals will be run only once.

In the end Ruby will only run the code between `process do end`, nothing
else.

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/asciidoctor-extensions.rb | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index c77b6de350..a678704e17 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -2,15 +2,21 @@ require 'asciidoctor/extensions'
 
 Asciidoctor::Extensions.register do
 
+  doc = document
+
   inline_macro :linkgit do
-    process do |parent, target, attrs|
-      if parent.document.doctype == 'book'
+    if doc.doctype == 'book'
+      process do |parent, target, attrs|
         "<ulink url=\"#{target}.html\">" \
         "#{target}(#{attrs[1]})</ulink>"
-      elsif parent.document.basebackend? 'html'
-        prefix = parent.document.attr('git-relative-html-prefix')
+      end
+    elsif doc.basebackend? 'html'
+      prefix = doc.attr('git-relative-html-prefix')
+      process do |parent, target, attrs|
         %(<a href="#{prefix}#{target}.html">#{target}(#{attrs[1]})</a>)
-      elsif parent.document.basebackend? 'docbook'
+      end
+    elsif doc.basebackend? 'docbook'
+      process do |parent, target, attrs|
         "<citerefentry>\n" \
           "<refentrytitle>#{target}</refentrytitle>" \
           "<manvolnum>#{attrs[1]}</manvolnum>\n" \
-- 
2.32.0

[PATCH 10/23] doc: asciidoctor: improve string handling

[Felipe Contreras]

Using printf style formatting (more familiar to git developers), and
also here document.

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/asciidoctor-extensions.rb | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index a678704e17..3282d59a48 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -7,20 +7,20 @@ Asciidoctor::Extensions.register do
   inline_macro :linkgit do
     if doc.doctype == 'book'
       process do |parent, target, attrs|
-        "<ulink url=\"#{target}.html\">" \
-        "#{target}(#{attrs[1]})</ulink>"
+        '<ulink url="%1$s.html">%1$s(%2$s)</ulink>' % [target, attrs[1]]
       end
     elsif doc.basebackend? 'html'
       prefix = doc.attr('git-relative-html-prefix')
       process do |parent, target, attrs|
-        %(<a href="#{prefix}#{target}.html">#{target}(#{attrs[1]})</a>)
+        %(<a href="#{prefix}%1$s.html">%1$s(%2$s)</a>) % [target, attrs[1]]
       end
     elsif doc.basebackend? 'docbook'
       process do |parent, target, attrs|
-        "<citerefentry>\n" \
-          "<refentrytitle>#{target}</refentrytitle>" \
-          "<manvolnum>#{attrs[1]}</manvolnum>\n" \
-        "</citerefentry>"
+        <<~EOF.chomp % [target, attrs[1]]
+        <citerefentry>
+        <refentrytitle>%s</refentrytitle><manvolnum>%s</manvolnum>
+        </citerefentry>
+        EOF
       end
     end
   end
-- 
2.32.0

[PATCH 11/23] doc: asciidoctor: split the format from the code

[Felipe Contreras]

This way we don't have to specify the block to execute on every
conditional.

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/asciidoctor-extensions.rb | 26 ++++++++++++-------------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index 3282d59a48..51981af13c 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -6,22 +6,22 @@ Asciidoctor::Extensions.register do
 
   inline_macro :linkgit do
     if doc.doctype == 'book'
-      process do |parent, target, attrs|
-        '<ulink url="%1$s.html">%1$s(%2$s)</ulink>' % [target, attrs[1]]
-      end
+      format = '<ulink url="%1$s.html">%1$s(%2$s)</ulink>'
     elsif doc.basebackend? 'html'
       prefix = doc.attr('git-relative-html-prefix')
-      process do |parent, target, attrs|
-        %(<a href="#{prefix}%1$s.html">%1$s(%2$s)</a>) % [target, attrs[1]]
-      end
+      format = %(<a href="#{prefix}%1$s.html">%1$s(%2$s)</a>)
     elsif doc.basebackend? 'docbook'
-      process do |parent, target, attrs|
-        <<~EOF.chomp % [target, attrs[1]]
-        <citerefentry>
-        <refentrytitle>%s</refentrytitle><manvolnum>%s</manvolnum>
-        </citerefentry>
-        EOF
-      end
+      format = <<~EOF.chomp
+      <citerefentry>
+      <refentrytitle>%s</refentrytitle><manvolnum>%s</manvolnum>
+      </citerefentry>
+      EOF
+    else
+      return
+    end
+
+    process do |_, target, attrs|
+      format % [target, attrs[1]]
     end
   end
 
-- 
2.32.0

[PATCH 12/23] doc: asciidoctor: specify name of our group

[Felipe Contreras]

Doesn't do anything, but otherwise we get a random name.

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/asciidoctor-extensions.rb | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index 51981af13c..b36317e4d2 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -1,6 +1,6 @@
 require 'asciidoctor/extensions'
 
-Asciidoctor::Extensions.register do
+Asciidoctor::Extensions.register :git do
 
   doc = document
 
-- 
2.32.0

[PATCH 13/23] doc: doc-diff: set docdate manually

[Felipe Contreras]

In order to minimize the differences in the footer.

Asciidoc automatically generates a date with format '%Y-%m-%d', while
asciidoctor '%F'.

I personally prefer the latter, so only modify it for diff purposes.

Fixes tons of these:

-Git omitted                       01/01/1970                        GIT-ADD(1)
+Git omitted                       1970-01-01                        GIT-ADD(1)

Note that we have to add quotes when passing around $makemanflags, as it
now may contain whitespace due to multiple arguments (but the
dereference inside render_tree must remain unquoted, because it wants to perform
whitespace splitting to get the individual arguments back).

Comments-by: Jeff King <peff@peff.net>
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/Makefile | 2 +-
 Documentation/doc-diff | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 47053c78f8..b68ab57239 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -136,7 +136,7 @@ ASCIIDOC_EXTRA =
 ASCIIDOC_HTML = xhtml11
 ASCIIDOC_DOCBOOK = docbook
 ASCIIDOC_CONF = -f asciidoc.conf
-ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \
+ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_FLAGS) $(ASCIIDOC_CONF) \
 		-amanmanual='Git Manual' -amansource='Git $(GIT_VERSION)'
 ASCIIDOC_DEPS = asciidoc.conf GIT-ASCIIDOCFLAGS
 TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML)
diff --git a/Documentation/doc-diff b/Documentation/doc-diff
index 1694300e50..c11b90a6ef 100755
--- a/Documentation/doc-diff
+++ b/Documentation/doc-diff
@@ -111,7 +111,7 @@ construct_makemanflags () {
 		echo USE_ASCIIDOCTOR=
 	elif test "$1" = "-asciidoctor"
 	then
-		echo USE_ASCIIDOCTOR=YesPlease
+		echo USE_ASCIIDOCTOR=YesPlease ASCIIDOC_FLAGS='-adocdate="01/01/1970"'
 	fi
 }
 
@@ -181,6 +181,6 @@ render_tree () {
 	fi
 }
 
-render_tree $from_oid $from_dir $from_makemanflags &&
-render_tree $to_oid $to_dir $to_makemanflags &&
+render_tree $from_oid $from_dir "$from_makemanflags" &&
+render_tree $to_oid $to_dir "$to_makemanflags" &&
 git -C $tmp/rendered diff --no-index "$@" $from_dir $to_dir
-- 
2.32.0

[PATCH 14/23] doc-diff: drop --cut-footer switch

[Felipe Contreras]

From: Martin Ågren <martin.agren@gmail.com>

Now that our doc-diff convinces Asciidoctor to insert the exact same
formatted dummy date as AsciiDoc, we can drop the --cut-footer switch.
It has been useful to ignore this difference between the two tools, but
it's effectively a no-op now. Similar to when we repurposed this from
--cut-header-footer in 83b0b8953e ("doc-diff: replace
--cut-header-footer with --cut-footer", 2019-09-16), just drop it
without worrying about any kind of backwards compatibility or user-base.

Signed-off-by: Martin Ågren <martin.agren@gmail.com>
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/doc-diff | 18 ++----------------
 1 file changed, 2 insertions(+), 16 deletions(-)

diff --git a/Documentation/doc-diff b/Documentation/doc-diff
index c11b90a6ef..6b6bb444ac 100755
--- a/Documentation/doc-diff
+++ b/Documentation/doc-diff
@@ -21,7 +21,6 @@ asciidoc		use asciidoc with both commits
 to-asciidoc		use asciidoc with the 'to'-commit
 to-asciidoctor		use asciidoctor with the 'to'-commit
 asciidoctor		use asciidoctor with both commits
-cut-footer		cut away footer
 "
 SUBDIRECTORY_OK=1
 . "$(git --exec-path)/git-sh-setup"
@@ -31,7 +30,6 @@ force=
 clean=
 from_program=
 to_program=
-cut_footer=
 while test $# -gt 0
 do
 	case "$1" in
@@ -55,8 +53,6 @@ do
 	--asciidoc)
 		from_program=-asciidoc
 		to_program=-asciidoc ;;
-	--cut-footer)
-		cut_footer=-cut-footer ;;
 	--)
 		shift; break ;;
 	*)
@@ -118,8 +114,8 @@ construct_makemanflags () {
 from_makemanflags=$(construct_makemanflags "$from_program") &&
 to_makemanflags=$(construct_makemanflags "$to_program") &&
 
-from_dir=$from_oid$from_program$cut_footer &&
-to_dir=$to_oid$to_program$cut_footer &&
+from_dir=$from_oid$from_program &&
+to_dir=$to_oid$to_program &&
 
 # generate_render_makefile <srcdir> <dstdir>
 generate_render_makefile () {
@@ -168,16 +164,6 @@ render_tree () {
 			"$tmp/rendered/$dname+" |
 		make -j$parallel -f - &&
 		mv "$tmp/rendered/$dname+" "$tmp/rendered/$dname"
-
-		if test "$cut_footer" = "-cut-footer"
-		then
-			for f in $(find "$tmp/rendered/$dname" -type f)
-			do
-				head -n -2 "$f" | sed -e '${/^$/d}' >"$f+" &&
-				mv "$f+" "$f" ||
-				return 1
-			done
-		fi
 	fi
 }
 
-- 
2.32.0

[PATCH 15/23] doc: use asciidoctor to build man pages directly

[Felipe Contreras]

There's no need to use xmlto to build the man pages when modern
asciidoctor can do it by itself.

This new mode will be active only when both USE_ASCIIDOCTOR and
USE_ASCIIDOCTOR_MANPAGE are set.

Suggested-by: Bagas Sanjaya <bagasdotme@gmail.com>
Suggestions-by: Jeff King <peff@peff.net>
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/Makefile | 10 +++++++++-
 Makefile               |  4 ++++
 2 files changed, 13 insertions(+), 1 deletion(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index b68ab57239..e6af1848cc 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -189,6 +189,9 @@ ASCIIDOC_DEPS = asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
 DBLATEX_COMMON =
 XMLTO_EXTRA += --skip-validation
 XMLTO_EXTRA += -x manpage.xsl
+ifdef USE_ASCIIDOCTOR_MANPAGE
+TXT_TO_MAN = $(ASCIIDOC_COMMON) -b manpage
+endif
 endif
 
 SHELL_PATH ?= $(SHELL)
@@ -324,7 +327,7 @@ mergetools-list.made: ../git-mergetool--lib.sh $(wildcard ../mergetools/*)
 		show_tool_names can_merge "* " || :' >mergetools-merge.txt && \
 	date >$@
 
-TRACK_ASCIIDOCFLAGS = $(subst ','\'',$(ASCIIDOC_COMMON):$(ASCIIDOC_HTML):$(ASCIIDOC_DOCBOOK))
+TRACK_ASCIIDOCFLAGS = $(subst ','\'',$(ASCIIDOC_COMMON):$(ASCIIDOC_HTML):$(ASCIIDOC_DOCBOOK):$(USE_ASCIIDOCTOR_MANPAGE))
 
 GIT-ASCIIDOCFLAGS: FORCE
 	@FLAGS='$(TRACK_ASCIIDOCFLAGS)'; \
@@ -349,8 +352,13 @@ $(MAN_HTML): %.html : %.txt $(ASCIIDOC_DEPS)
 $(OBSOLETE_HTML): %.html : %.txto $(ASCIIDOC_DEPS)
 	$(QUIET_ASCIIDOC)$(TXT_TO_HTML) -o $@ $<
 
+ifdef TXT_TO_MAN
+%.1 %.5 %.7 : %.txt $(ASCIIDOC_DEPS)
+	$(QUIET_ASCIIDOC)$(TXT_TO_MAN) -o $@ $<
+else
 %.1 %.5 %.7 : %.xml $(wildcard manpage*.xsl)
 	$(QUIET_XMLTO)$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
+endif
 
 %.xml : %.txt $(ASCIIDOC_DEPS)
 	$(QUIET_ASCIIDOC)$(TXT_TO_XML) -d manpage -o $@ $<
diff --git a/Makefile b/Makefile
index 7588c43f05..ab3fa362b7 100644
--- a/Makefile
+++ b/Makefile
@@ -281,6 +281,10 @@ all::
 # Define USE_ASCIIDOCTOR to use Asciidoctor instead of AsciiDoc to build the
 # documentation.
 #
+# Define USE_ASCIIDOCTOR_MANPAGE to use Asciidoctor's manual page backend
+# instead of building manual pages from DocBook (using xmlto). Has no effect
+# unless USE_ASCIIDOCTOR is set.
+#
 # Define ASCIIDOCTOR_EXTENSIONS_LAB to point to the location of the Asciidoctor
 # Extensions Lab if you have it available.
 #
-- 
2.32.0

[PATCH 16/23] doc-diff: support asciidoctor man pages

[Felipe Contreras]

From: Jeff King <peff@peff.net>

The new option enables both asciidoctor as well as its direct-to-manpage
mode that skips xmlto. This lets you view the rendered difference
between the two pipelines with something like:

  ./doc-diff --from-asciidoctor --to-asciidoctor-direct HEAD HEAD

Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/doc-diff | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/Documentation/doc-diff b/Documentation/doc-diff
index 6b6bb444ac..bbfeaa213b 100755
--- a/Documentation/doc-diff
+++ b/Documentation/doc-diff
@@ -17,10 +17,13 @@ f			force rebuild; do not rely on cached results
 c,clean			cleanup temporary working files
 from-asciidoc		use asciidoc with the 'from'-commit
 from-asciidoctor	use asciidoctor with the 'from'-commit
+from-asciidoctor-direct use asciidoctor without xmlto for 'from'-commit
 asciidoc		use asciidoc with both commits
 to-asciidoc		use asciidoc with the 'to'-commit
 to-asciidoctor		use asciidoctor with the 'to'-commit
+to-asciidoctor-direct   use asciidoctor without xmlto for 'to'-commit
 asciidoctor		use asciidoctor with both commits
+asciidoctor-direct      use asciidoctor without xml for both commits
 "
 SUBDIRECTORY_OK=1
 . "$(git --exec-path)/git-sh-setup"
@@ -53,6 +56,13 @@ do
 	--asciidoc)
 		from_program=-asciidoc
 		to_program=-asciidoc ;;
+	--from-asciidoctor-direct)
+		from_program=-asciidoctor-direct ;;
+	--to-asciidoctor-direct)
+		to_program=-asciidoctor-direct ;;
+	--asciidoctor-direct)
+		from_program=-asciidoctor-direct
+		to_program=-asciidoctor-direct ;;
 	--)
 		shift; break ;;
 	*)
@@ -108,6 +118,10 @@ construct_makemanflags () {
 	elif test "$1" = "-asciidoctor"
 	then
 		echo USE_ASCIIDOCTOR=YesPlease ASCIIDOC_FLAGS='-adocdate="01/01/1970"'
+	elif test "$1" = "-asciidoctor-direct"
+	then
+		echo USE_ASCIIDOCTOR=YesPlease ASCIIDOC_FLAGS='-adocdate="01/01/1970"'
+		echo USE_ASCIIDOCTOR_MANPAGE=YesPlease
 	fi
 }
 
-- 
2.32.0

[PATCH 17/23] doc: asciidoctor: add linkgit macros in man pages

[Felipe Contreras]

Fixes the doc-diff:

-       Please see git-commit(1) for alternative ways to add content to a
-       commit.
+       Please see  for alternative ways to add content to a commit.

Comments-by: brian m. carlson <sandals@crustytoothpaste.net>
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/asciidoctor-extensions.rb | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index b36317e4d2..6c4153f628 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -10,6 +10,8 @@ Asciidoctor::Extensions.register :git do
     elsif doc.basebackend? 'html'
       prefix = doc.attr('git-relative-html-prefix')
       format = %(<a href="#{prefix}%1$s.html">%1$s(%2$s)</a>)
+    elsif doc.basebackend? 'manpage'
+      format = "\e\\fB%s\e\\fP(%s)"
     elsif doc.basebackend? 'docbook'
       format = <<~EOF.chomp
       <citerefentry>
-- 
2.32.0

[PATCH 18/23] doc: add man pages workaround for asciidoctor

[Felipe Contreras]

Currently asciidoctor doesn't convert number character references
(&#xx;) correctly for man pages.

This hack fixes the issue with minimum changes elsewhere so it's easy to
remove when fixed.

Fixes doc-diffs like:

            so line count cannot be shown) and there is no difference between
            indexed copy and the working tree version (if the working tree
            version were also different, binary would have been shown in place
-           of nothing). The other file, git-add--interactive.perl, has 403
-           lines added and 35 lines deleted if you commit what is in the
-           index, but working tree file has further modifications (one
+           of nothing). The other file, git-add--interactive.perl,
+           has 403 lines added and 35 lines deleted if you commit what is in
+           the index, but working tree file has further modifications (one
            addition and one deletion).

https://github.com/asciidoctor/asciidoctor/issues/4059

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/asciidoctor-extensions.rb | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index 6c4153f628..954acb3e7d 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -4,6 +4,12 @@ Asciidoctor::Extensions.register :git do
 
   doc = document
 
+  # Override attributes for man pages.
+  # https://github.com/asciidoctor/asciidoctor/issues/4059
+  if doc.backend == 'manpage'
+    doc.attributes.merge!({ 'litdd' => '\--', 'plus' => '+' })
+  end
+
   inline_macro :linkgit do
     if doc.doctype == 'book'
       format = '<ulink url="%1$s.html">%1$s(%2$s)</ulink>'
-- 
2.32.0

[PATCH 19/23] doc: asciidoctor: add hack for xrefs

[Felipe Contreras]

The docbook manpage stylesheets convert cross-references with format the
'section called “%t”'. I personally prefer the asciidoctor version, but
for now add a hack to minimize the diff.

Thanks to the extensibility of Ruby we can override corresponding method
in the man page converter.

This fixes doc-diffs like:

          --worktree-attributes
              Look for attributes in .gitattributes files in the working tree as
  -           well (see the section called “ATTRIBUTES”).
  +           well (see ATTRIBUTES).

This can easily be removed later once we are confortable with the
asciidoctor version.

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/asciidoctor-extensions.rb | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index 954acb3e7d..7561973df6 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -1,4 +1,22 @@
 require 'asciidoctor/extensions'
+require 'asciidoctor/converter/manpage'
+
+module Asciidoctor
+  class Converter::ManPageConverter
+    alias orig_convert_inline_anchor convert_inline_anchor
+    def convert_inline_anchor(node)
+      case node.type
+      when :xref
+        return node.text if node.text
+        refid = node.attributes['refid']
+        'the section called &#8220;%s&#8221;' % refid.gsub('_', ' ')
+      else
+        orig_convert_inline_anchor(node)
+      end
+    end
+    alias inline_anchor convert_inline_anchor # For old versions of asciidoctor
+  end
+end
 
 Asciidoctor::Extensions.register :git do
 
-- 
2.32.0

[PATCH 20/23] doc: asciidoctor: add hack to improve links

[Felipe Contreras]

The way asciidoctor handles links is very primitive compared to docbook.
Links are simply presented in the format "#{text} <#{target}>", which
may not be all that bad for the future, but pollutes the doc-diff.

By adding another modification to convert_inline_anchor() we can present
links in a form very similar to docbook, diminishing the doc-diff.

This significantly reduces the doc-diff:

From:

        abysmal performance). These safety and performance issues cannot be
        backward compatibly fixed and as such, its use is not recommended.
        Please use an alternative history filtering tool such as git
-       filter-repo[1]. If you still need to use git filter-branch, please
-       carefully read the section called “SAFETY” (and the section called
-       “PERFORMANCE”) to learn about the land mines of filter-branch, and then
-       vigilantly avoid as many of the hazards listed there as reasonably
-       possible.
+       <https://github.com/newren/git-filter-repo/> filter-repo" . If you
+       still need to use git filter-branch, please carefully read the section
+       called “SAFETY” (and the section called “PERFORMANCE”) to learn about
+       the land mines of filter-branch, and then vigilantly avoid as many of
+       the hazards listed there as reasonably possible.

-NOTES
-        1. git filter-repo
-           https://github.com/newren/git-filter-repo/
-
-        2. filter-lamely
-           https://github.com/newren/git-filter-repo/blob/master/contrib/filter-repo-demos/filter-lamely
-

To:

 NOTES
-        1. git filter-repo
+       [1]    git filter-repo
               https://github.com/newren/git-filter-repo/

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/asciidoctor-extensions.rb | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index 7561973df6..914e6f64c8 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -10,6 +10,19 @@ module Asciidoctor
         return node.text if node.text
         refid = node.attributes['refid']
         'the section called &#8220;%s&#8221;' % refid.gsub('_', ' ')
+      when :link
+        return node.target if node.text == node.target
+        doc = node.document
+
+        footnote = doc.footnotes.find { |e| e.id == node.target }
+        if !footnote
+          footnote_text = "%s\n\e.RS\n\e\\%%%s\n\e.RE" % [node.text, node.target]
+          index = doc.counter('footnote-number')
+          footnote = Document::Footnote.new(index, node.target, footnote_text)
+          doc.register(:footnotes, footnote)
+        end
+
+        "\e\\fB%s\e\\fR[%d]" % [node.text, footnote.index]
       else
         orig_convert_inline_anchor(node)
       end
-- 
2.32.0

[PATCH 21/23] doc: asciidoctor: add support for baseurl

[Felipe Contreras]

So that we can present relative links correctly.

Reduces the doc-diff:

   NOTES
  -        1. “Understanding history: What is a branch?”
  -           file:///$HOME/share/doc/git-doc/user-manual.html#what-is-a-branch
  +       [1]    “Understanding history: What is a branch?”
  +              user-manual.html#what-is-a-branch

   NOTES
  -        1. “Understanding history: What is a branch?”
  +       [1]    “Understanding history: What is a branch?”
                 file:///$HOME/share/doc/git-doc/user-manual.html#what-is-a-branch

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/Makefile                  | 1 +
 Documentation/asciidoctor-extensions.rb | 4 +++-
 2 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index e6af1848cc..dea0f2d859 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -185,6 +185,7 @@ ASCIIDOC_DOCBOOK = docbook5
 ASCIIDOC_EXTRA += -acompat-mode -atabsize=8
 ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions
 ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;'
+ASCIIDOC_EXTRA += -abaseurl='$(MAN_BASE_URL)'
 ASCIIDOC_DEPS = asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
 DBLATEX_COMMON =
 XMLTO_EXTRA += --skip-validation
diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index 914e6f64c8..8856f2febd 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -16,7 +16,9 @@ module Asciidoctor
 
         footnote = doc.footnotes.find { |e| e.id == node.target }
         if !footnote
-          footnote_text = "%s\n\e.RS\n\e\\%%%s\n\e.RE" % [node.text, node.target]
+          target = node.target
+          target = doc.attributes['baseurl'] + target unless target.include? ':'
+          footnote_text = "%s\n\e.RS\n\e\\%%%s\n\e.RE" % [node.text, target]
           index = doc.counter('footnote-number')
           footnote = Document::Footnote.new(index, node.target, footnote_text)
           doc.register(:footnotes, footnote)
-- 
2.32.0

[PATCH 22/23] doc: asciidoctor: cleanup man page hack

[Felipe Contreras]

There's basically nothing we need from the original
orig_convert_inline_anchor(), so let's remove calls to it.

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/asciidoctor-extensions.rb | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index 8856f2febd..e48a381b8f 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -3,7 +3,6 @@ require 'asciidoctor/converter/manpage'
 
 module Asciidoctor
   class Converter::ManPageConverter
-    alias orig_convert_inline_anchor convert_inline_anchor
     def convert_inline_anchor(node)
       case node.type
       when :xref
@@ -25,8 +24,10 @@ module Asciidoctor
         end
 
         "\e\\fB%s\e\\fR[%d]" % [node.text, footnote.index]
+      when :ref, :bibref
+        ''
       else
-        orig_convert_inline_anchor(node)
+        nil
       end
     end
     alias inline_anchor convert_inline_anchor # For old versions of asciidoctor
-- 
2.32.0

[PATCH 23/23] doc: asciidoctor: add hack for old versions

[Felipe Contreras]

\\ gets converted erroneously.

[1] https://github.com/asciidoctor/asciidoctor/issues/3456

Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/asciidoctor-extensions.rb | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index e48a381b8f..3ab669dad8 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -38,10 +38,19 @@ Asciidoctor::Extensions.register :git do
 
   doc = document
 
-  # Override attributes for man pages.
-  # https://github.com/asciidoctor/asciidoctor/issues/4059
   if doc.backend == 'manpage'
+    # Override attributes for man pages.
+    # https://github.com/asciidoctor/asciidoctor/issues/4059
     doc.attributes.merge!({ 'litdd' => '\--', 'plus' => '+' })
+
+    # Fix bug with \\
+    if Asciidoctor::VERSION < '2.0.11'
+      postprocessor do
+        process do |_, output|
+          output.gsub("\\(rs\\\\", "\\(rs\\(rs\\")
+        end
+      end
+    end
   end
 
   inline_macro :linkgit do
-- 
2.32.0

Re: [PATCH 15/23] doc: use asciidoctor to build man pages directly

[Bagas Sanjaya]

On 21/06/21 23.31, Felipe Contreras wrote:
> +# Define USE_ASCIIDOCTOR_MANPAGE to use Asciidoctor's manual page backend
> +# instead of building manual pages from DocBook (using xmlto). Has no effect
> +# unless USE_ASCIIDOCTOR is set.
> +#

Why not just USE_ASCIIDOCTOR_MANPAGE implies USE_ASCIIDOCTOR?

-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH 00/23] doc: cleanups and asciidoctor direct man pages

[Bagas Sanjaya]

On 21/06/21 23.30, Felipe Contreras wrote:
> I already sent the first part of this series separately multiple times,
> the last one is 4 simple obviously correct patches [1], but since the
> maintainer has admitted he has no problem ignoring valid work
> entirely due to personal animus [2], I'm sending the whole chain.
> 
> There's no point in carefully selecting multiple series of patches to be
> merged one by one when all of them are going to be ignored. So I'm
> sending all 3 series at once.
> 
> Hopefully by sending it all at once some people will be able to realize
> that:
> 
>   1. They are valid
>   2. They are helpful
>   3. They make the code more maintainable
>   4. They enable new features
>   5. They enable the new features to be easily tested
>   6. They reduce the doc-diff of the new feature, as well as others
>   7. They are superior to the competing series currently in seen
>   8. They include work of multiple contributors
> 
> Any fair and impartial maintainer would attempt to pick them up.
> 
> Cheers.
> 

I think the next step after this patch series is to add asciidoctor 
direct man pages generation option to ./configure script (maybe 
--enable-asciidoctor-manpage?). But before that, we need to add 
--enable-asciidoctor option, which sets USE_ASCIIDOCTOR=YesPlease.

-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH 15/23] doc: use asciidoctor to build man pages directly

[Felipe Contreras]

Bagas Sanjaya wrote:
> On 21/06/21 23.31, Felipe Contreras wrote:
> > +# Define USE_ASCIIDOCTOR_MANPAGE to use Asciidoctor's manual page backend
> > +# instead of building manual pages from DocBook (using xmlto). Has no effect
> > +# unless USE_ASCIIDOCTOR is set.
> > +#
> 
> Why not just USE_ASCIIDOCTOR_MANPAGE implies USE_ASCIIDOCTOR?

Personally I don't see the point of USE_ASCIIDOCTOR_MANPAGE at all. The
only reason I added it was because Martin requested it [1].

It would be nice of you and Martin could make a decision about this, and
I would just implement what you decide (or other people willing to
collaborate on this).

I don't have an opinion on this.

If no decision is reached, I'll make USE_ASCIIDOCTOR_MANPAGE imply
USE_ASCIIDOCTOR as you suggest.

Cheers.

[1] https://lore.kernel.org/git/CAN0heSpX53tK8Z4XSx4sp79b+XWKZg5+ABW8pmzBSHPZ+qy+oQ@mail.gmail.com/

-- 
Felipe Contreras

Re: [PATCH 00/23] doc: cleanups and asciidoctor direct man pages

[Felipe Contreras]

Bagas Sanjaya wrote:
> On 21/06/21 23.30, Felipe Contreras wrote:
> > I already sent the first part of this series separately multiple times,
> > the last one is 4 simple obviously correct patches [1], but since the
> > maintainer has admitted he has no problem ignoring valid work
> > entirely due to personal animus [2], I'm sending the whole chain.
> > 
> > There's no point in carefully selecting multiple series of patches to be
> > merged one by one when all of them are going to be ignored. So I'm
> > sending all 3 series at once.
> > 
> > Hopefully by sending it all at once some people will be able to realize
> > that:
> > 
> >   1. They are valid
> >   2. They are helpful
> >   3. They make the code more maintainable
> >   4. They enable new features
> >   5. They enable the new features to be easily tested
> >   6. They reduce the doc-diff of the new feature, as well as others
> >   7. They are superior to the competing series currently in seen
> >   8. They include work of multiple contributors
> > 
> > Any fair and impartial maintainer would attempt to pick them up.
> > 
> > Cheers.
> > 
> 
> I think the next step after this patch series is to add asciidoctor 
> direct man pages generation option to ./configure script (maybe 
> --enable-asciidoctor-manpage?). But before that, we need to add 
> --enable-asciidoctor option, which sets USE_ASCIIDOCTOR=YesPlease.

Maybe. I don't use ./configure, so perhaps somebody that does should
take charge of this.

-- 
Felipe Contreras