Add a howto for building documentation.

git-svn-id: svn://svn.valgrind.org/valgrind/trunk@15017 a5019735-40e9-0310-863c-91ae7b9d1cf9

Author: florian

README_DEVELOPERS

@@ -24,15 +24,15 @@ To build a distribution tarball from the valgrind sources:
   make dist
 
 In addition to compiling, linking and packaging everything up, the command
-will also build the documentation. Even if all required tools for building the
-documentation are installed, this step may not succeed because of hidden
-dependencies. E.g. on Ubuntu you must have "docbook-xsl" installed.
-Additionally, specific tool versions maybe needed.
+will also attempt to build the documentation.
 
 If you only want to test whether the generated tarball is complete and runs
 regression tests successfully, building documentation is not needed.
 Edit docs/Makefile.am, search for BUILD_ALL_DOCS and follow instructions there.
 
+If you insist on building documentation some embarrassing instructions
+can be found in docs/internals/howto_build_documentation.
+
 
 Running the regression tests
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/internals/howto_build_documentation

@@ -0,0 +1,41 @@
+A typical "make" will not build documentation.
+Documentation is only built during "make dist".
+Typically, building documentation will fail.
+
+On Ubuntu 14.04.2 LTS the following is known to work:
+
+Required packages:
+texlive
+dblatex
+xsltproc
+xmltex
+docbook-xml
+docbook-xsl
+
+Additional the following lines need to be changed in
+/usr/share/texlive/texmf-dist/tex/latex/oberdiek/epstopdf-base.sty
+around line 450  from
+
+
+\ifETE@prepend
+  \expandafter\PrependGraphicsExtensions
+\else
+  \expandafter\AppendGraphicsExtensions
+\fi
+{.eps}
+
+
+to
+
+
+%% \ifETE@prepend
+%%   \expandafter\PrependGraphicsExtensions
+%% \else
+%%   \expandafter\AppendGraphicsExtensions
+%% \fi
+%% {.eps}
+
+
+This hack was devised by Mark Wielaard. 
+
+It is unknown how to build documentation on other platforms.