Add a howto for building documentation.

git-svn-id: svn://svn.valgrind.org/valgrind/trunk@15017

diff --git a/README_DEVELOPERS b/README_DEVELOPERS
index 6ebeef064c17eb38ebac1e189eb794d3a637a613..6ffbdf73a5f647fcdfcf1db5075e315ac31e7787 100644 (file)
--- a/README_DEVELOPERS
+++ b/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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

diff --git a/docs/internals/howto_build_documentation b/docs/internals/howto_build_documentation
new file mode 100644 (file)
index 0000000..d89ee4a
--- /dev/null
+++ b/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.