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 1/2] doc: add an option to have Asciidoctor build man pages directly
Date: Wed, 12 May 2021 02:11:37 +0000	[thread overview]
Message-ID: <20210512021138.63598-1-sandals@crustytoothpaste.net> (raw)
In-Reply-To: <609b2828309fc_678ff2082@natae.notmuch>

From: Felipe Contreras <felipe.contreras@gmail.com>

Asciidoctor contains a converter to generate man pages.  In some
environments, where building only the manual pages and not the other
documentation is desired, installing a toolchain for building
DocBook-based manual pages may be burdensome, and using Asciidoctor
directly may be easier, so let's add an option to build manual pages
using Asciidoctor without the DocBook toolchain.

We generally require Asciidoctor 1.5, but versions before 1.5.3 didn't
contain proper handling of the apostrophe, which is controlled normally
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.

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.

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
still on 1.5.  If users are using a more modern toolchain or don't care
about the rendering issues, they can enable the option.

Suggested-by: Bagas Sanjaya <bagasdotme@gmail.com>
Signed-off-by: Felipe Contreras <felipe.contreras@gmail.com>
Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
I've preserved Felipe's authorship on this patch because much of it is
his work.  However, I have made some substantial changes here with which
I suspect he will disagree, in addition to expanding on the commit
message, so if he would prefer, I can reroll with the authorship
changed.  I have no preference myself.

 Documentation/Makefile                  | 10 ++++++++++
 Documentation/asciidoctor-extensions.rb |  2 ++
 Makefile                                |  3 +++
 3 files changed, 15 insertions(+)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 2aae4c9cbb..536d9a5f3d 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -196,6 +196,9 @@ ASCIIDOC_EXTRA += -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
+endif
 endif
 
 SHELL_PATH ?= $(SHELL)
@@ -367,9 +370,16 @@ $(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)|" $< > $@
 
+ifdef TXT_TO_MAN
+%.1 %.5 %.7 : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
+	$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
+	$(TXT_TO_MAN) -o $@+ $< && \
+	mv $@+ $@
+else
 %.1 %.5 %.7 : %.xml manpage-base-url.xsl $(wildcard manpage*.xsl)
 	$(QUIET_XMLTO)$(RM) $@ && \
 	$(XMLTO) -m $(MANPAGE_XSL) $(XMLTO_EXTRA) man $<
+endif
 
 %.xml : %.txt asciidoc.conf asciidoctor-extensions.rb GIT-ASCIIDOCFLAGS
 	$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
diff --git a/Documentation/asciidoctor-extensions.rb b/Documentation/asciidoctor-extensions.rb
index d906a00803..40fa87b121 100644
--- a/Documentation/asciidoctor-extensions.rb
+++ b/Documentation/asciidoctor-extensions.rb
@@ -15,6 +15,8 @@ module Git
           "#{target}(#{attrs[1]})</ulink>"
         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)
         elsif parent.document.basebackend? 'docbook'
           "<citerefentry>\n" \
             "<refentrytitle>#{target}</refentrytitle>" \
diff --git a/Makefile b/Makefile
index 93664d6714..cb75dec314 100644
--- a/Makefile
+++ b/Makefile
@@ -285,6 +285,9 @@ 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.
+#
 # Define ASCIIDOCTOR_EXTENSIONS_LAB to point to the location of the Asciidoctor
 # Extensions Lab if you have it available.
 #

  reply	other threads:[~2021-05-12  2:11 UTC|newest]

Thread overview: 45+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-05-11 22:27 [PATCH] doc: use asciidoctor to " Felipe Contreras
2021-05-11 23:26 ` brian m. carlson
2021-05-12  0:58   ` Felipe Contreras
2021-05-12  2:11     ` brian m. carlson [this message]
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     ` [PATCH v2 0/2] Asciidoctor native manpage builds brian m. carlson
2021-05-14  0:31       ` [PATCH v2 1/2] doc: add an option to have Asciidoctor build man pages directly 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=20210512021138.63598-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 1/2] doc: add an option to have Asciidoctor build man pages directly' \
    /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