[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 <***@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
----

[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 <***@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

[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 <***@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

[Jeff King]

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
make doc ASCIIDOC=asciidoctor ASCIIDOC_HTML=html5 \
ASCIIDOC_DOCBOOK=docbook45 ASCIIDOC_EXTRA="'-alitdd=&#45;&#45;'" \
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

[Junio C Hamano]

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

Thanks.