Documentation doesn't build anymore on old asciidoc due to i18n series

Documentation doesn't build anymore on old asciidoc due to i18n series

[Ævar Arnfjörð Bjarmason]

I can submit a patch for this later, just thought I'd note it and
solicit feedback on the best solution to this.

On my Debian box with asciidoc 8.6.4 Git builds just fine from master.

But on a Centos 5.5 box with asciidoc 8.2.5 I get:

    rm -f git-sh-i18n--envsubst.html+ git-sh-i18n--envsubst.html && \
            asciidoc -b xhtml11 -d manpage -f asciidoc.conf \
                     -a asciidoc7compatible -a no-inline-literal -a
git-asciidoc-no-roff -agit_version=1.7.5.3.367.ga9930 -o
git-sh-i18n--envsubst.html+ git-sh-i18n--envsubst.txt && \
            mv git-sh-i18n--envsubst.html+ git-sh-i18n--envsubst.html
    ERROR: git-sh-i18n--envsubst.txt: line 9: second section must be
named SYNOPSIS
    make[1]: *** [git-sh-i18n--envsubst.html] Error 1

The solution is obvious: just add a SYNOPSIS section for
consistency. I'll do that later, unless we want to provide some option
(which old asciidoc may or may not support) to not have a SYNOPSIS
there, which we arguably can just omit for purely internal tooling
like this.

I'll submit patches soon for adding a SYNOPSIS unless we want to go
that route.

[PATCH] git-sh-i18n--envsubst: add SYNOPSIS section to the documentation

[Ævar Arnfjörð Bjarmason]

Change the documentation for the git-sh-i18n--envsubst program to
include a SYNOPSIS section. Include the invocation of the program from
git-sh-i18n.sh.

Not having a SYNOPSIS section caused the "doc" target to fail on
Centos 5.5 with asciidoc 8.2.5, while building with 8.6.4 on Debian
works just fine.

The relevant error was:

    ERROR: git-sh-i18n--envsubst.txt: line 9: second section must be named SYNOPSIS

Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
 Documentation/git-sh-i18n--envsubst.txt |   10 ++++++++++
 1 files changed, 10 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-sh-i18n--envsubst.txt b/Documentation/git-sh-i18n--envsubst.txt
index f5bbf77..61e4c08 100644
--- a/Documentation/git-sh-i18n--envsubst.txt
+++ b/Documentation/git-sh-i18n--envsubst.txt
@@ -5,6 +5,16 @@ NAME
 ----
 git-sh-i18n--envsubst - Git's own envsubst(1) for i18n fallbacks
 
+SYNOPSIS
+--------
+[verse]
+eval_gettext () {
+	printf "%s" "$1" | (
+		export PATH $('git sh-i18n--envsubst' --variables "$1");
+		'git sh-i18n--envsubst' "$1"
+	)
+}
+
 DESCRIPTION
 -----------
 
-- 
1.7.5.1

Re: [PATCH] git-sh-i18n--envsubst: add SYNOPSIS section to the documentation

[Junio C Hamano]

Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:

> Not having a SYNOPSIS section caused the "doc" target to fail on
> Centos 5.5 with asciidoc 8.2.5, while building with 8.6.4 on Debian
> works just fine.

So does FC13 and FC15, both of which has 8.4.5.

Will queue; thanks.