r19846 - gnucash-docs/trunk - Update HACKING and README for the pdf changes
Geert Janssens
gjanssens at code.gnucash.org
Fri Nov 19 17:21:21 EST 2010
Author: gjanssens
Date: 2010-11-19 17:21:21 -0500 (Fri, 19 Nov 2010)
New Revision: 19846
Trac: http://svn.gnucash.org/trac/changeset/19846
Modified:
gnucash-docs/trunk/HACKING
gnucash-docs/trunk/README
Log:
Update HACKING and README for the pdf changes
Modified: gnucash-docs/trunk/HACKING
===================================================================
--- gnucash-docs/trunk/HACKING 2010-11-19 22:21:12 UTC (rev 19845)
+++ gnucash-docs/trunk/HACKING 2010-11-19 22:21:21 UTC (rev 19846)
@@ -92,39 +92,29 @@
Generating PDF
-Currently the Guide docbook source is capable of supporting the generation of
-pdf output, but it may take a little work to assemble the tools if you don't
-have them. The following is based on a Linux Fedora Core 7 installation.
+The GnuCash documentation build system can generate pdfs from the
+guide's and help manual's xml source files, provided you have the proper
+tools available on your system. This functionality was introduced by
+Tom Browder (<tom.browder at gmail.com>) and improved by
+Geert Janssens (<janssens-geert at telenet.be>).
-Required:
+Other than xsltproc (which is already required to build html documentation)
+you also need Apache fop 0.95 or more recent.
- 1. docbook-xsl >= 1.74.0
+At the time of this writing, you can install fop straight from any of the
+current distros' package repositories, or at least fop is available in one
+of the addon repositories.
- available at: http://docbook.sourceforge.net
+* Fedora 12 and up: fop is in the main repository
+* Debian Lenny: fop 0.95 has been backported
+* Debian Squeeze and up: fop is in the main repository
+* CentOS 5: fop can be installed via EPEL testing
+* Ubuntu 9.10 and up: fop is in the universe repository
- Follow the first link to the download site, then choose the "docbook-xsl"
- package. I can find nothing specific about installation, but I think the
- preferred place to unpack the package is in /usr/local/share.
+If your distro doesn't ship fop you can still install it manually. It
+is available at http://xmlgraphics.apache.org/fop
+and it requires:
- Note the location of the file 'docbook.xsl'. Point to it by assigning it
- to an environment variable DOCBOOK_XSL. In this case, for csh or tcsh users:
-
- setenv DOCBOOK_XSL /usr/local/share/docbook-xsl-1.74.0/fo/docbook.xsl
-
- or for sh or bash users:
-
- export DOCBOOK_XSL=/usr/local/share/docbook-xsl-1.74.0/fo/docbook.xsl
-
- (Note: I find the www.docbook.org site very confusing--full of circular
- references to the source of the docbook xml style sheets, but no specific
- link that is easily found.)
-
- 2. Apache Fop >= 0.95
-
- available at: http://xmlgraphics.apache.org/fop
-
- requires:
-
a. Sun Java JDK >= 1.4
available at: http://java.sun.com/javase/downloads/index.jsp
@@ -132,11 +122,3 @@
b. ant >= 1.7
available at: http://ant.apache.org
-
-You may need additional xml tools, but they should be available through the yum
-update if they are not already installed.
-
-Tom Browder
-<tom.browder at gmail.com>
-Niceville, Florida
-2008-10-02
Modified: gnucash-docs/trunk/README
===================================================================
--- gnucash-docs/trunk/README 2010-11-19 22:21:12 UTC (rev 19845)
+++ gnucash-docs/trunk/README 2010-11-19 22:21:21 UTC (rev 19846)
@@ -3,24 +3,21 @@
------------------------------------------------------------
This is the docs module for GnuCash. The docs can be accessed
-from Yelp (the GNOME2 help browser). If you wish an html version
-'make html' will convert them for you and leave the html files in
-a subdirectory of the doc called <docname> (eg the html for help
-would be in help/C/gnucash-help).
+from Yelp (the GNOME2 help browser) directly without any conversion.
+If you wish to obtain a copy of the documentation in another format,
+like html, pdf or others, see below under Other Formats.
Requirements
############
-libxml2/libxslt
-docbook-xsl
-scrollkeeper >=0.3.4
-yelp (for viewing)
+* libxml2/libxslt
+* docbook-xsl
+* scrollkeeper >=0.3.4
+* yelp (for viewing)
-Additonal Requirements for Generating PDF
-=========================================
+Additonal Requirements for Generating PDF:
-docbook-xsl >= 1.74.0
-Apache fop >= 0.95
+* Apache fop >= 0.95
Notes
#####
@@ -41,19 +38,55 @@
GnuCash-docs is written using docbook-xml. This allows it to be
outputted to alternative formats using external tools.
-DocBook comes in two flavours - xml and sgml. GnuCash uses the xml.
+DocBook comes in two flavours - xml and sgml. GnuCash uses the xml flavour.
-If you use external tools to render HTML, remember to bring the images
+The documentation source comes with built-in commands to generate html or
+pdf output. For other formats, you will need to use external tools.
+
+Note: if you use external tools to render HTML, remember to bring the images
from figures/ along with the final HTML. The browser will expect to find
the figures/ directory directly beneath the HTML directory:
~/gnucash-docs/html/
~/gnucash-docs/html/figures/
- ================================
+* html and pdf
+--------------
-XML/XSL-based tools:
---------------------
+You can generate the documentation in html or pdf using the autotools
+based build system that comes with the sources.
+ cd gnucash-docs
+ ./autogen.sh
+ ./configure
+
+=> This will tell you if you are missing some required tools.
+
+To generate the documentation in html format, run
+
+ make html
+
+To generate the documentation in pdf format, instead run
+
+ make pdf
+
+If you only wish to generate a subset of the documentation, you can
+go into the directory for that subset and run the above make commands
+from there. For example to only generate the English concepts guide,
+
+ cd guide/C
+ make html
+
+or
+
+ cd guide/C
+ make pdf
+
+depending on the output format you require.
+
+
+* XML/XSL-based tools:
+----------------------
+
If you have xmlto installed, this can be used to convert to other formats
but problems have been experienced with PDF generation. If you output
an XML-FO format using xmlto, you could use FOP to convert to PDF - this
@@ -73,7 +106,7 @@
make and install.
Examples:
---------
+
To convert the GnuCash Tutorial and Concepts Guide DocBook XML document
to HTML and store the resulting HTML files in a separate directory use:
@@ -87,51 +120,7 @@
cd help/C/
xmlto html-nochunks gnucash-help.xml
- ==============================
-SGML-based tools:
-----------------
-
-(Note these tools and the sgml docs are no longer being updated)
-If you have docbook-utils installed, you can convert this documentation
-into other formats like PDF, DVI, TXT, texi, RTF. docbook-utils is SGML
-based and so a SGML header file is provided. The content files are still
-XML based - this doesn't cause problems for conversion to HTML but to
-generate PDF's validity errors need to be suppressed.
-
-Use -e no-valid to suppress SGML validity errors.
-
-Currently, there are also problems incorporating the images into the
-PDF versions. However, unlike the XML/XSL tools, docbook-utils will
-generate a valid PDF, albeit without images.
-
-Note that the docs are designed for XML/XSL. Allowing them to function
-with SGML tools requires a few syntax tweaks. You may get errors reported
-but as long as the majority of the tweaks are in place, the conversion
-will succeed. Syntax errors are not suppressed with '-e -no-valid',
-only validity errors (like _ instead of - in id attributes).
-
-Examples:
----------
-Convert the GnuCash guide to a single HTML file:
-cd guide/C/
-docbook2html -e no-valid -u gnucash-guide.sgml
-cd help/C/
-docbook2html -u gnucash-help.sgml
-
-Convert the GnuCash guide into a PDF:
-cd guide/C/
-docbook2pdf -e no-valid gnucash-guide.sgml
-
-Convert the GnuCash Help Manual into DVI:
-cd help/C/
-docbook2dvi -e no-valid gnucash-help.sgml
-
-One workaround for the images is to convert to a single HTML file and
-use Print to PDF File from your web browser. Bear in mind that the single
-HTML file is v.large and each PDF, without images, goes to over 100 pages.
-
-
Known Problems
##############
@@ -143,8 +132,6 @@
- Guide needs some updates still.
-- Most of the information (although still relevant) refers to the 1.8 version.
-
That's it for now! Please report any problems to the GNOME bugzilla at
http://bugzilla.gnome.org. Or alternately email me or preferably the
devel list with any problems you have.
More information about the gnucash-changes
mailing list