[v2,00/11] doc: asciidoctor: direct man page creation and fixes

Message

Felipe Contreras May 21, 2021, 10:44 p.m. UTC

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/[e-mail]/

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

Comments

Felipe Contreras May 21, 2021, 10:51 p.m. UTC | #1

Felipe Contreras wrote:
> 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].

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