v2, 11 partsdoc: asciidoctor: direct man page creation and fixes

This patch series enables direct man page creation with asciidoctor, but in addition tries to minimize the difference with asciidoc+docbook.

I fixed as many issues as I could, and now the doc-diff looks very sensible. I could not find any major issues, however, some minor ones still remain.

On the other hand the asciidoc method has issues as well, so it's not clear which method is superior at this point; both have advantages and disadvantages.

At the very least the man pages with pure asciidoctor should be quite usable now.

This series builds on top of my previous cleanups [1].

[1] https://lore.kernel.org/git/20210521223701.526547-1-felipe.contreras@gmail.com/

Felipe Contreras (9):
  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/Makefile                  | 15 ++++++--
 Documentation/asciidoctor-extensions.rb | 51 +++++++++++++++++++++++++
 Documentation/doc-diff                  | 35 +++++++++--------
 3 files changed, 82 insertions(+), 19 deletions(-)

Range-diff against v1:
 1:  de0ecf9c0e <  -:  ---------- doc: allow the user to provide ASCIIDOC_EXTRA
 2:  22a35efa3f <  -:  ---------- doc: doc-diff: allow more than one flag
 3:  a8ad5c703a <  -:  ---------- doc: doc-diff: set docdate manually
 4:  4d0266a3a1 <  -:  ---------- doc: use asciidoctor to build man pages directly
 5:  5efb19348b <  -:  ---------- doc: asciidoctor: add linkgit macros in man pages
 6:  d5d006298e <  -:  ---------- doc: join mansource and manversion
 7:  7c8b502df9 <  -:  ---------- doc: add man pages workaround for asciidoctor
 -:  ---------- >  1:  a2f85f4b05 doc: doc-diff: set docdate manually
 -:  ---------- >  2:  13085a13b6 doc-diff: drop --cut-footer switch
 -:  ---------- >  3:  f0b3576d77 doc: use asciidoctor to build man pages directly
 -:  ---------- >  4:  8b3bb9e9f4 doc-diff: support asciidoctor man pages
 -:  ---------- >  5:  3f9859b223 doc: asciidoctor: add linkgit macros in man pages
 -:  ---------- >  6:  df27fcb9a2 doc: add man pages workaround for asciidoctor
 8:  5d5e9d99ac !  7:  5f0ae41e3e doc: asciidoctor: add hack for xrefs
    @@ Commit message
     
      ## Documentation/asciidoctor-extensions.rb ##
     @@
    - require 'asciidoctor'
      require 'asciidoctor/extensions'
     +require 'asciidoctor/converter/manpage'
     +
    @@ Documentation/asciidoctor-extensions.rb
     +        orig_convert_inline_anchor(node)
     +      end
     +    end
    ++    alias inline_anchor convert_inline_anchor # For old versions of asciidoctor
     +  end
     +end
      
    - module Git
    -   module Documentation
    + Asciidoctor::Extensions.register :git do
    + 
 9:  f4a4f1394e =  8:  a8fb29d893 doc: asciidoctor: add hack to improve links
10:  894802bfbb !  9:  272e6e8551 doc: asciidoctor: add support for baseurl
    @@ Commit message
     
      ## Documentation/Makefile ##
     @@ Documentation/Makefile: ASCIIDOC_DOCBOOK = docbook5
    - override ASCIIDOC_EXTRA += -acompat-mode -atabsize=8
    - override ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions
    - override ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;'
    -+override ASCIIDOC_EXTRA += -abaseurl='$(MAN_BASE_URL)'
    + 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
11:  d3b6899ed8 ! 10:  928a632038 doc: asciidoctor: cleanup man page hack
    @@ Documentation/asciidoctor-extensions.rb: module Asciidoctor
     +        nil
            end
          end
    -   end
    +     alias inline_anchor convert_inline_anchor # For old versions of asciidoctor
 -:  ---------- > 11:  758e5be3b7 doc: asciidoctor: add hack for old versions

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(-)

On 22/05/21 05.44, Felipe Contreras wrote:

%F is short yyyy-mm-dd date. AFAIK, it is the same effect as `%Y-%m-%d`.

  
So, the asciidoctor generated date was the bottom one, while the asciidoc
counterpart was the above one, right?

The above one, however, was actually %m/%d/%Y.

Bagas Sanjaya wrote:

Right, I noticed I was wrong when trying to use -adocdate in asciidoctor. It's actually ignored.

The date format probably comes from docbook. The commit message needs to be updated.

Yeap.

Indeed, the commit message is inaccurate.

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(-)

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>
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
---
 Documentation/Makefile | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

Felipe Contreras wrote:

This was a conflict mistake, the manpage-base-url.xsl file is not present any more, should be:

+%.1 %.5 %.7 : %.xml $(wildcard manpage*.xsl)

I fixed in my local branch.

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 | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

Felipe Contreras wrote:

Oops. This obviously sneaked by; doesn't belong here.

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(+)

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(+)

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(+)

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(+)

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(-)

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(-)

\\ 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(-)

Felipe Contreras wrote:

I forgot to mention what changed since v1:

 * The option USE_ASCIIDOCTOR_MANPAGE was added
 * Jeff's patch for *asciidoctor-direct optiosn to doc-diff was added
 * Martin Ågren's patch to remove -cut-footer was added
 * The format of linkgit was updated to be closer to brian's version
   (though not quite the same)
 * A few tiny cleanups