From 544aa45a0fe58ec8b6b211d71d703ab9519f95fc Mon Sep 17 00:00:00 2001 From: Florian Krohm Date: Mon, 16 Mar 2015 22:42:13 +0000 Subject: [PATCH] Merge the contents of docs/internals/howto_build_documentation into docs/README. Remove the section about the XML Toolchain as it is outdated. git-svn-id: svn://svn.valgrind.org/valgrind/trunk@15019 --- README_DEVELOPERS | 5 +- docs/README | 99 ++++++++++++------------ docs/internals/howto_build_documentation | 41 ---------- 3 files changed, 53 insertions(+), 92 deletions(-) delete mode 100644 docs/internals/howto_build_documentation diff --git a/README_DEVELOPERS b/README_DEVELOPERS index 6ffbdf73a5..997f495742 100644 --- a/README_DEVELOPERS +++ b/README_DEVELOPERS @@ -28,10 +28,11 @@ 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. + + make dist BUILD_ALL_DOCS=no If you insist on building documentation some embarrassing instructions -can be found in docs/internals/howto_build_documentation. +can be found in docs/README. Running the regression tests diff --git a/docs/README b/docs/README index 82e32397c5..155fe5ebeb 100644 --- a/docs/README +++ b/docs/README @@ -76,47 +76,56 @@ could just build the docs from XML when doing 'make install', which would be simpler. -The XML Toolchain ------------------- -I spent some time on the docbook-apps list in order to ascertain -the most-useful / widely-available / least-fragile / advanced -toolchain. Basically, everything has problems of one sort or -another, so I ended up going with what I felt was the -least-problematical of the various options. - -The maintainer is responsible for ensure the following tools are -present on his system: -- xmllint: using libxml version 20620 -- xsltproc: Using libxml 20620, libxslt 10114 and libexslt 812 - (Nb:be sure to use a version based on libxml2 - version 2.6.11 or later. There was a bug in - xml:base processing in versions before that.) -- pdfxmltex: pdfeTeX 3.141592-1.21a-2.2 (Web2C 7.5.4) -- pdftops: version 3.00 -- DocBook: version 4.2 -- bzip2 - -A big problem is latency. Norman Walsh is constantly updating -DocBook, but the tools tend to lag behind somewhat. It is -important that the versions get on with each other. If you -decide to upgrade something, then it is your responsibility to -ascertain whether things still work nicely - this *cannot* be -assumed. - -Print output: if make expires with an error, cat output. -If you see something like this: - ! TeX capacity exceeded, sorry [pool size=436070] - -then look at this: - http://lists.debian.org/debian-doc/2003/12/msg00020.html -and modify your texmf files accordingly. - - - -Catalog/Stylesheet Location ---------------------------- -/etc/xml/ seems to have become the standard place for catalogs -in recent distros. +Notes on building PDF / PS documents +------------------------------------ +Below are random notes and recollections about how to build PDF / PS +documents from the XML source at various times on various Linux distros. + + +Notes [Mar 2015] +---------------- +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. + + +Notes [Aug. 2012] +----------------- +On Ubuntu 10.04 there was a new capacity-related failure whilst +building the print docs in the run up to the 3.8.0 release. This was +fixed by editing /etc/texmf/texmf.cnf and changing pool_size to +2000000. Notes [May 2009] @@ -140,14 +149,6 @@ if it can't find this one: I haven't succeeded in building the print docs. -Notes [Aug. 2012] ------------------ -On Ubuntu 10.04 there was a new capacity-related failure whilst -building the print docs in the run up to the 3.8.0 release. This was -fixed by editing /etc/texmf/texmf.cnf and changing pool_size to -2000000. - - Notes [Mar. 2007] ----------------- For SuSE 10.1, I have to install the following packages to get a diff --git a/docs/internals/howto_build_documentation b/docs/internals/howto_build_documentation deleted file mode 100644 index d89ee4af0a..0000000000 --- a/docs/internals/howto_build_documentation +++ /dev/null @@ -1,41 +0,0 @@ -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. -- 2.47.3