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.

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.

doc/asciidoc-helper.sh

@@ -46,13 +46,19 @@ elif [ "$1" = "man" ]; then
     if "$2" -f manpage $input; then
       mv $base.1 $output;
     else
-      echo "==================================";
+      cat<<EOF
-      echo;
+==================================
-      echo "a2x is installed, but some required docbook support files are";
+You need a working asciidoc installed to be able to build the manpage.
-      echo "missing. Please install docbook-xsl, docbook-xml, and";
+
-      echo "libxml2-utils (Debian) or similar.";
+a2x is installed, but for some reason it isn't working.  Sometimes
-      echo;
+This happens because required docbook support files are missing.
-      echo "==================================";
+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