git.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: "brian m. carlson" <sandals@crustytoothpaste.net>
To: <git@vger.kernel.org>
Cc: "Felipe Contreras" <felipe.contreras@gmail.com>,
	"Martin Ågren" <martin.agren@gmail.com>,
	"Bagas Sanjaya" <bagasdotme@gmail.com>,
	"Jeff King" <peff@peff.net>
Subject: [PATCH v2 0/2] Asciidoctor native manpage builds
Date: Fri, 14 May 2021 00:31:02 +0000	[thread overview]
Message-ID: <20210514003104.94644-1-sandals@crustytoothpaste.net> (raw)
In-Reply-To: <609b2828309fc_678ff2082@natae.notmuch>

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.
    + #

  parent reply	other threads:[~2021-05-14  0:31 UTC|newest]

Thread overview: 45+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-05-11 22:27 [PATCH] doc: use asciidoctor to build man pages directly Felipe Contreras
2021-05-11 23:26 ` brian m. carlson
2021-05-12  0:58   ` Felipe Contreras
2021-05-12  2:11     ` [PATCH 1/2] doc: add an option to have Asciidoctor " brian m. carlson
2021-05-12  2:11       ` [PATCH 2/2] doc: remove GNU_ROFF option brian m. carlson
2021-05-12  2:18         ` Eric Sunshine
2021-05-12  2:28           ` brian m. carlson
2021-05-12  4:45         ` Felipe Contreras
2021-05-14  0:11           ` brian m. carlson
2021-05-15 13:30             ` Felipe Contreras
2021-05-13 13:11         ` Martin Ågren
2021-05-12  2:48       ` [PATCH 1/2] doc: add an option to have Asciidoctor build man pages directly Bagas Sanjaya
2021-05-12  5:03         ` Felipe Contreras
2021-05-13 23:24         ` brian m. carlson
2021-05-14 12:58           ` Felipe Contreras
2021-05-15 13:25           ` Felipe Contreras
2021-05-12  4:41       ` Felipe Contreras
2021-05-13 23:38         ` brian m. carlson
2021-05-14 19:02           ` Felipe Contreras
2021-05-12  4:43       ` Bagas Sanjaya
2021-05-13 23:54         ` brian m. carlson
2021-05-12  6:22       ` Jeff King
2021-05-12  6:30         ` Jeff King
2021-05-12  6:59           ` Jeff King
2021-05-12 19:29             ` Felipe Contreras
2021-05-13 17:30             ` Martin Ågren
2021-05-13 22:37               ` Felipe Contreras
2021-05-12 19:53           ` Eric Sunshine
2021-05-12 22:37             ` Jeff King
2021-05-14 15:34           ` Martin Ågren
2021-05-14  0:31     ` brian m. carlson [this message]
2021-05-14  0:31       ` [PATCH v2 " brian m. carlson
2021-05-14  3:58         ` Junio C Hamano
2021-05-14  5:27           ` Jeff King
2021-05-14 20:00             ` Felipe Contreras
2021-05-14 19:55           ` brian m. carlson
2021-05-14 20:52             ` Felipe Contreras
2021-05-14 19:57           ` Felipe Contreras
2021-05-14 19:53         ` Felipe Contreras
2021-05-14 20:17           ` brian m. carlson
2021-05-14 23:31             ` Felipe Contreras
2021-05-14  0:31       ` [PATCH v2 2/2] doc: remove GNU_ROFF option brian m. carlson
2021-05-14 19:07       ` [PATCH v2 0/2] Asciidoctor native manpage builds Felipe Contreras
2021-05-14 20:00         ` brian m. carlson
2021-05-14 21:21           ` Felipe Contreras

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20210514003104.94644-1-sandals@crustytoothpaste.net \
    --to=sandals@crustytoothpaste.net \
    --cc=bagasdotme@gmail.com \
    --cc=felipe.contreras@gmail.com \
    --cc=git@vger.kernel.org \
    --cc=martin.agren@gmail.com \
    --cc=peff@peff.net \
    --subject='Re: [PATCH v2 0/2] Asciidoctor native manpage builds' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
on how to clone and mirror all data and code used for this inbox