[PATCH v2 0/3] Allow building Git with Asciidoctor

[PATCH v2 0/3] Allow building Git with Asciidoctor

[brian m. carlson]

This series is designed to implement the changes necessary to build Git
using Asciidoctor instead of AsciiDoc.

The first two patches are bug fixes, and are unchanged from v1.
Asciidoctor is stricter about some aspects of formatting, and these
patches are required to make the documentation build correctly.

The third patch moves several pieces of the documentation makefile into
variables.  Some of these changes were suggested by Junio, and some of
them were required to simply build correctly.

In this patch, I have maintained the ASCIIDOC_HTML and ASCIIDOC_DOCBOOK
variables, because otherwise there is no way to override the backends
easily, which is required to build.  For Asciidoctor, there is no
xhtml11 backend and the docbook backend produces DocBook 5, which xmlto
doesn't like.

The fourth patch in the previous series has been dropped, as Dan Allen
of the Asciidoctor project has pointed me to a backend-agnostic
implementation of the linkgit macro which is included in the Asciidoctor
project.  The litdd attribute, the only other missing piece, can be
moved to the command line, so the patch became unnecessary.

I've successfully built the documentation with Asciidoctor using the
following command line:

  make doc ASCIIDOC=asciidoctor ASCIIDOC_HTML=html5 \
  ASCIIDOC_DOCBOOK=docbook45 ASCIIDOC_EXTRA="'-alitdd=--'" \
  ASCIIDOC_CONF=

This resulted in a total build time (documentation only) of 3:17 versus
5:43 for AsciiDoc (a 42% improvement).

brian m. carlson (3):
  Documentation: adjust document title underlining
  Documentation: fix mismatched delimiters in git-imap-send
  Documentation: move some AsciiDoc parameters into variables

 Documentation/Makefile             | 26 +++++++++++++++-----------
 Documentation/git-imap-send.txt    |  4 ++--
 Documentation/git-prune-packed.txt |  2 +-
 Documentation/git-quiltimport.txt  |  2 +-
 Documentation/git-stage.txt        |  2 +-
 5 files changed, 20 insertions(+), 16 deletions(-)

-- 
2.1.1

[PATCH v2 1/3] Documentation: adjust document title underlining

[brian m. carlson]

AsciiDoc specification states that in two-line titles, the title
underline has to be the same length as the title text, plus or minus two
characters.  Asciidoctor, however, requires that this must be plus or
minus one character.  Adjust the underlines to be the same length as the
title text to improve compatibility.

Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
 Documentation/git-prune-packed.txt | 2 +-
 Documentation/git-quiltimport.txt  | 2 +-
 Documentation/git-stage.txt        | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-prune-packed.txt b/Documentation/git-prune-packed.txt
index 6738055..9fed59a 100644
--- a/Documentation/git-prune-packed.txt
+++ b/Documentation/git-prune-packed.txt
@@ -1,5 +1,5 @@
 git-prune-packed(1)
-=====================
+===================
 
 NAME
 ----
diff --git a/Documentation/git-quiltimport.txt b/Documentation/git-quiltimport.txt
index a356196..d64388c 100644
--- a/Documentation/git-quiltimport.txt
+++ b/Documentation/git-quiltimport.txt
@@ -1,5 +1,5 @@
 git-quiltimport(1)
-================
+==================
 
 NAME
 ----
diff --git a/Documentation/git-stage.txt b/Documentation/git-stage.txt
index ba3fe0d..25bcda9 100644
--- a/Documentation/git-stage.txt
+++ b/Documentation/git-stage.txt
@@ -1,5 +1,5 @@
 git-stage(1)
-==============
+============
 
 NAME
 ----
-- 
2.1.1

[PATCH v2 2/3] Documentation: fix mismatched delimiters in git-imap-send

[brian m. carlson]

The documentation for git-imap-send uses block delimiters with
mismatched lengths, which Asciidoctor doesn't support.  As a result, the
page is misrendered.  Adjust the delimiters so that they are of the same
length.

Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
 Documentation/git-imap-send.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt
index 7d991d9..c7c0d21 100644
--- a/Documentation/git-imap-send.txt
+++ b/Documentation/git-imap-send.txt
@@ -97,7 +97,7 @@ Using direct mode:
     host = imap://imap.example.com
     user = bob
     pass = p4ssw0rd
-..........................
+.........................
 
 Using direct mode with SSL:
 
@@ -109,7 +109,7 @@ Using direct mode with SSL:
     pass = p4ssw0rd
     port = 123
     sslverify = false
-..........................
+.........................
 
 
 EXAMPLE
-- 
2.1.1

[PATCH v2 3/3] Documentation: move some AsciiDoc parameters into variables

[brian m. carlson]

Asciidoctor takes slightly different arguments from AsciiDoc in some
cases.  It has a different name for the HTML backend and the "docbook"
backend produces DocBook 5, not DocBook 4.5.  Also, Asciidoctor does not
accept the -f option.  Move these values into variables so that they can
be overridden by users wishing to use Asciidoctor instead of Asciidoc,
and simplify several redundant rules.

Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net>
---
 Documentation/Makefile | 26 +++++++++++++++-----------
 1 file changed, 15 insertions(+), 11 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index cea0e7a..5952cc2 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -97,6 +97,13 @@ man7dir = $(mandir)/man7
 
 ASCIIDOC = asciidoc
 ASCIIDOC_EXTRA =
+ASCIIDOC_HTML = xhtml11
+ASCIIDOC_DOCBOOK = docbook
+ASCIIDOC_CONF = -f asciidoc.conf
+ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) $(ASCIIDOC_CONF) \
+		-agit-version=$(GIT_VERSION)
+TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML)
+TXT_TO_XML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_DOCBOOK)
 MANPAGE_XSL = manpage-normal.xsl
 XMLTO = xmlto
 XMLTO_EXTRA =
@@ -304,14 +311,12 @@ clean:
 
 $(MAN_HTML): %.html : %.txt asciidoc.conf
 	$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
-	$(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf \
-		$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \
+	$(TXT_TO_HTML) -d manpage -o $@+ $< && \
 	mv $@+ $@
 
 $(OBSOLETE_HTML): %.html : %.txto asciidoc.conf
 	$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
-	$(ASCIIDOC) -b xhtml11 -f asciidoc.conf \
-		$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \
+	$(TXT_TO_HTML) -o $@+ $< && \
 	mv $@+ $@
 
 manpage-base-url.xsl: manpage-base-url.xsl.in
@@ -323,13 +328,12 @@ manpage-base-url.xsl: manpage-base-url.xsl.in
 
 %.xml : %.txt asciidoc.conf
 	$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
-	$(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf \
-		$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $< && \
+	$(TXT_TO_XML) -d manpage -o $@+ $< && \
 	mv $@+ $@
 
 user-manual.xml: user-manual.txt user-manual.conf
 	$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
-	$(ASCIIDOC) $(ASCIIDOC_EXTRA) -b docbook -d article -o $@+ $< && \
+	$(TXT_TO_XML) -d article -o $@+ $< && \
 	mv $@+ $@
 
 technical/api-index.txt: technical/api-index-skel.txt \
@@ -338,8 +342,7 @@ technical/api-index.txt: technical/api-index-skel.txt \
 
 technical/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../
 $(patsubst %,%.html,$(API_DOCS) technical/api-index $(TECH_DOCS)): %.html : %.txt asciidoc.conf
-	$(QUIET_ASCIIDOC)$(ASCIIDOC) -b xhtml11 -f asciidoc.conf \
-		$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) $*.txt
+	$(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt
 
 XSLT = docbook.xsl
 XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css
@@ -386,14 +389,15 @@ howto-index.txt: howto-index.sh $(wildcard howto/*.txt)
 	mv $@+ $@
 
 $(patsubst %,%.html,$(ARTICLES)) : %.html : %.txt
-	$(QUIET_ASCIIDOC)$(ASCIIDOC) $(ASCIIDOC_EXTRA) -b xhtml11 $*.txt
+	$(QUIET_ASCIIDOC)$(TXT_TO_HTML) $*.txt
 
 WEBDOC_DEST = /pub/software/scm/git/docs
 
 howto/%.html: ASCIIDOC_EXTRA += -a git-relative-html-prefix=../
 $(patsubst %.txt,%.html,$(wildcard howto/*.txt)): %.html : %.txt
 	$(QUIET_ASCIIDOC)$(RM) $@+ $@ && \
-	sed -e '1,/^$$/d' $< | $(ASCIIDOC) $(ASCIIDOC_EXTRA) -b xhtml11 - >$@+ && \
+	sed -e '1,/^$$/d' $< | \
+	$(TXT_TO_HTML) - >$@+ && \
 	mv $@+ $@
 
 install-webdoc : html
-- 
2.1.1

Re: [PATCH v2 0/3] Allow building Git with Asciidoctor

[Jeff King]

On Mon, Oct 20, 2014 at 12:20:35AM +0000, brian m. carlson wrote:

> This series is designed to implement the changes necessary to build Git
> using Asciidoctor instead of AsciiDoc.

These all looked sane to me from my cursory read (I haven't played with
AsciiDoctor myself yet, but it looks from your results like you have).

> I've successfully built the documentation with Asciidoctor using the
> following command line:
> 
>   make doc ASCIIDOC=asciidoctor ASCIIDOC_HTML=html5 \
>   ASCIIDOC_DOCBOOK=docbook45 ASCIIDOC_EXTRA="'-alitdd=--'" \
>   ASCIIDOC_CONF=

That incantation is getting a bit hairy. Is it worth adding a meta-macro
like USE_ASCIIDOCTOR that encompasses it all? That might encourage other
people to play around with it.

-Peff

Re: [PATCH v2 0/3] Allow building Git with Asciidoctor

[Junio C Hamano]

Too late that the original is already in 'next'.  Care to reroll as
an incremental, plaese?

Thanks.