Merge pull request #154 from andreasabel/issue128

[ #128 ] Build instructions for the doc; xsl path for brew

Author: simonmar

doc/README.md

@@ -0,0 +1,25 @@
+# Building the Alex documentation
+
+In this directory, run:
+```
+autoconf
+./configure
+make
+```
+On success, you should find the documentation in the
+subdirectory `alex/`.
+
+## Troubleshooting
+
+Running `./configure` might report:
+```
+checking for DocBook XSL stylesheet directory... no
+configure: WARNING: cannot find DocBook XSL stylesheets, you will not be able to build the documentation
+```
+Extending the list `FP_DIR_DOCBOOK_XSL` in file `configure.ac` might
+help.  E.g., on Mac OS X with homebrew-installed `docbook`, the path
+```
+/usr/local/Cellar/docbook-xsl/*/docbook-xsl
+```
+worked.  Inside this directory (pattern), `configure` looks for a file
+`/html/docbook.xsl`, see `aclocal.m4`.

doc/configure.ac

@@ -5,7 +5,7 @@ AC_CONFIG_SRCDIR([Makefile])
 
 dnl ** check for DocBook toolchain
 FP_CHECK_DOCBOOK_DTD
-FP_DIR_DOCBOOK_XSL([/usr/share/xml/docbook/stylesheet/nwalsh/current /usr/share/xml/docbook/stylesheet/nwalsh /usr/share/sgml/docbook/docbook-xsl-stylesheets* /usr/share/sgml/docbook/xsl-stylesheets* /opt/kde?/share/apps/ksgmltools2/docbook/xsl /usr/share/docbook-xsl /usr/share/sgml/docbkxsl /usr/local/share/xsl/docbook /sw/share/xml/xsl/docbook-xsl /usr/share/xml/docbook/xsl-stylesheets*])
+FP_DIR_DOCBOOK_XSL([/usr/local/Cellar/docbook-xsl/*/docbook-xsl /usr/share/xml/docbook/stylesheet/nwalsh/current /usr/share/xml/docbook/stylesheet/nwalsh /usr/share/sgml/docbook/docbook-xsl-stylesheets* /usr/share/sgml/docbook/xsl-stylesheets* /opt/kde?/share/apps/ksgmltools2/docbook/xsl /usr/share/docbook-xsl /usr/share/sgml/docbkxsl /usr/local/share/xsl/docbook /sw/share/xml/xsl/docbook-xsl /usr/share/xml/docbook/xsl-stylesheets*])
 
 AC_PATH_PROG(DbLatexCmd,dblatex)