From: Florian Krohm <florian@eich-krohm.de>
Date: Mon, 16 Mar 2015 12:22:35 +0000 (+0000)
Subject: Add a howto for building documentation.
X-Git-Tag: svn/VALGRIND_3_11_0~575
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=df2bfc8447b50d6ed9caf1e3795e28715be2249a;p=thirdparty%2Fvalgrind.git

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 6ebeef064c..6ffbdf73a5 100644
--- 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
index 0000000000..d89ee4af0a
--- /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.