[PATCH v2 0/2] Asciidoctor native manpage builds

["brian m. carlson" <sandals@crustytoothpaste.net>]

This series introduces native support for building manual pages with
Asciidoctor, which is faster and somewhat easier than building with the
DocBook toolchain.

The first patch in the series is based on one by Felipe Contreras but
differs from his in that we default to the old behavior, in addition to
some additional functionality and a more verbose commit message.

The second patch drops support for GNU_ROFF, which is now supported in a
more robust way by both the Asciidoctor and DocBook toolchains.

Changes from v1:
* Rephrase commit messages and Makefile text for both patches to clarify
  and avoid ambiguity.
* Avoid using XML-style escapes in man pages, which are not XML- or
  HTML-based.
* Clarify that USE_ASCIIDOCTOR_MANPAGE requires USE_ASCIIDOCTOR to be
  functional.
* Escape linkgit macro output to avoid backslashes being needlessly
  converted.
* Remove leftover reference to GNU_ROFF.

brian m. carlson (2):
  doc: add an option to have Asciidoctor build man pages directly
  doc: remove GNU_ROFF option

 Documentation/Makefile                  | 25 +++++++++++++++----------
 Documentation/asciidoctor-extensions.rb |  2 ++
 Documentation/manpage-quote-apos.xsl    | 16 ----------------
 Makefile                                |  8 ++++----
 4 files changed, 21 insertions(+), 30 deletions(-)
 delete mode 100644 Documentation/manpage-quote-apos.xsl

Diff-intervalle contre v1 :
1:  9ba34d9ec9 ! 1:  0d5f8f1b80 doc: add an option to have Asciidoctor build man pages directly
    @@
      ## Metadata ##
    -Author: Felipe Contreras <felipe.contreras@gmail.com>
    +Author: brian m. carlson <sandals@crustytoothpaste.net>
     
      ## Commit message ##
         doc: add an option to have Asciidoctor build man pages directly
    @@ Commit message
         by the GNU_ROFF option.  This option for the DocBook toolchain, as well
         as newer versions of Asciidoctor, makes groff output an ASCII apostrophe
         instead of a Unicode apostrophe in text, so as to make copy and pasting
    -    commands easier.  These newer versions of Asciidoctor detect groff and
    -    do the right thing in all cases, so the GNU_ROFF option is obsolete in
    -    this case.
    +    commands easier.  These newer versions of Asciidoctor (1.5.3 and above)
    +    detect groff and do the right thing in all cases, so the GNU_ROFF option
    +    is obsolete in this case.
     
         We also need to update the code that tells Asciidoctor how to format our
         linkgit macros so that it can output proper code for man pages.  Be
         careful to reset the font to the previous after the change.  In order to
         do so, we must reset to the previous after each font change so the
         previous state at the end is the state before our inserted text, since
    -    troff only remembers one previous font.
    +    troff only remembers one previous font.  We insert \e before each
    +    font-change backslash so Asciidoctor doesn't convert them into \*(rs,
    +    the reverse solidus character, and instead leaves them as we wanted
    +    them.
    +
    +    Additionally, we don't want to use XML-style escapes for the litdd and
    +    plus macros, so let's only use the XML-style escapes in HTML and XML and
    +    use something different for our man pages.
     
         Because Asciidoctor versions before 2.0 had a few problems with man page
         output, let's default this to off for now, since some common distros are
    @@ Commit message
         Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
     
      ## Documentation/Makefile ##
    -@@ Documentation/Makefile: ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;'
    +@@ Documentation/Makefile: ASCIIDOC_HTML = xhtml5
    + ASCIIDOC_DOCBOOK = docbook5
    + ASCIIDOC_EXTRA += -acompat-mode -atabsize=8
    + ASCIIDOC_EXTRA += -I. -rasciidoctor-extensions
    +-ASCIIDOC_EXTRA += -alitdd='&\#x2d;&\#x2d;'
    ++TXT_TO_HTML += -alitdd='&\#x2d;&\#x2d;'
    ++TXT_TO_XML  += -alitdd='&\#x2d;&\#x2d;'
      DBLATEX_COMMON =
      XMLTO_EXTRA += --skip-validation
      XMLTO_EXTRA += -x manpage.xsl
     +ifdef USE_ASCIIDOCTOR_MANPAGE
     +TXT_TO_MAN = $(ASCIIDOC_COMMON) -b manpage
    ++TXT_TO_MAN += -aplus='+'
    ++TXT_TO_MAN += -alitdd='\--'
     +endif
      endif
      
      SHELL_PATH ?= $(SHELL)
    +@@ Documentation/Makefile: 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)'; \
     @@ Documentation/Makefile: $(OBSOLETE_HTML): %.html : %.txto asciidoc.conf asciidoctor-extensions.rb GIT-AS
      manpage-base-url.xsl: manpage-base-url.xsl.in
      	$(QUIET_GEN)sed "s|@@MAN_BASE_URL@@|$(MAN_BASE_URL)|" $< > $@
    @@ Documentation/asciidoctor-extensions.rb: module Git
              elsif parent.document.basebackend? 'html'
                %(<a href="#{prefix}#{target}.html">#{target}(#{attrs[1]})</a>)
     +        elsif parent.document.basebackend? 'manpage'
    -+          %(\\fB#{target}\\fP\\fR(#{attrs[1]})\\fP)
    ++          %(\e\\fB#{target}\e\\fP\e\\fR(#{attrs[1]})\e\\fP)
              elsif parent.document.basebackend? 'docbook'
                "<citerefentry>\n" \
                  "<refentrytitle>#{target}</refentrytitle>" \
    @@ Makefile: all::
      # documentation.
      #
     +# Define USE_ASCIIDOCTOR_MANPAGE to use Asciidoctor's manual page backend
    -+# instead of building manual pages from DocBook.
    ++# 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:  c0a21dd700 ! 2:  b12a068f5b doc: remove GNU_ROFF option
    @@ Commit message
         GNU_ROFF code.
     
         Additionally, this functionality was implemented in 2010.  Since nobody
    -    is shipping security support for an operating system that old anymore,
    -    we can just safely assume that the user has upgraded their system in the
    -    past decade and remove the GNU_ROFF option and its corresponding
    -    stylesheet altogether.
    +    is shipping a mainstream Linux distribution with security support that
    +    old anymore, we can just safely assume that the user has upgraded their
    +    system in the past decade and remove the GNU_ROFF option and its
    +    corresponding stylesheet altogether.
     
         Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
     
    @@ Documentation/manpage-quote-apos.xsl (deleted)
     -</xsl:template>
     -
     -</xsl:stylesheet>
    +
    + ## Makefile ##
    +@@ Makefile: 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.
    + #