In asciidoc-helper.sh, be more verbose when a2x fails.

Previously, we said (more or less), "a2x is broken and here's how you could
try to fix it".  Instead, we now say "We need a2x to build manpages; a2x
didn't work; here is a fix that might work for you; alternatively you
could just skip manpage building."

Addresses bug 1524.

Also, give the message as a here-document rather than a bunch of echos.

2 files changed, 16 insertions, 7 deletions

diff --git a/changes/bug1524 b/changes/bug1524
new file mode 100644
index 0000000000..03d6ff51b1
--- /dev/null
+++ b/changes/bug1524
@@ -0,0 +1,3 @@
+ o Minor documentation fixes
+   - When a2x fails, mention that the user could disable manpages instead
+     of trying to fix their asciidoc installation.
diff --git a/doc/asciidoc-helper.sh b/doc/asciidoc-helper.sh
index ea0efbefdc..00f8b8d07f 100755
--- a/doc/asciidoc-helper.sh
+++ b/doc/asciidoc-helper.sh
@@ -46,13 +46,19 @@ elif [ "$1" = "man" ]; then
     if "$2" -f manpage $input; then
       mv $base.1 $output;
     else
-      echo "==================================";
-      echo;
-      echo "a2x is installed, but some required docbook support files are";
-      echo "missing. Please install docbook-xsl, docbook-xml, and";
-      echo "libxml2-utils (Debian) or similar.";
-      echo;
-      echo "==================================";
+      cat<<EOF
+==================================
+You need a working asciidoc installed to be able to build the manpage.
+
+a2x is installed, but for some reason it isn't working.  Sometimes
+This happens because required docbook support files are missing.
+Please install docbook-xsl, docbook-xml, and libxml2-utils (Debian) or
+similar.
+
+Alternatively, to build without manpages, use the --disable-asciidoc
+argument when calling configure.
+==================================
+EOF
       exit 1;
     fi
 fi