GnuCash Documentation in pdf Format

Sat Feb 26 15:25:06 EST 2005

On Friday 25 February 2005 5:08 am, Chris Lyttle wrote:
> I've not attempted to validate the xml in the docs for use to convert to
> pdf, just that its valid for conversion to html which the build script
> does. 

OK, I've got most of that done. The changes to the XML itself are quite 
limited - there are some <listitem> tags without the enclosed <para>.

I'll commit those anyway, there are no consequences to the existing make from 
correcting this syntax.

On a more awkward note:
From HACKING in the CVS:
NOTE: The id used in the <article> and <sect1> tag is important as it defines
the name used when the html pages are generated. Please be careful with these.

I've realised that using 
  <sect2 id="basics_accountingdouble2">

is generating errors. I'd like to change each id to use hyphens instead of 
underscores:

  <sect2 id="basics-accountingdouble2">

underscores work fine for your make process but cause problems for the other 
conversions.

If you are happy for me to change each id to use - instead of _ (image file 
references will not need to be changed but the resulting HTML filenames will 
change to - instead of _ when built), I'll make a commit this weekend.

All I'll be doing is adding a .docbook for each set (guide and help) because I 
can't convert files based on <article>, I need <book> (a truly minor change 
that doesn't require any further changes and is therefore a really annoying 
discrepancy between the various docbook utilities) and changing the id 
strings as above.

> Its possible to do this, but I'd rather not add the MB of pdf to 
> the docs build

Agreed, I've prepared a sample snippet to put into the README:

Other Formats
#############

GnuCash-docs uses DocBook to create the HTML content during the make.
You can output to alternative formats using external tools.

If you have docbook-utils installed, you can convert this documentation
into other formats like PDF, DVI, TXT, texi, RTF. Currently, there are
problems incorporating the images into the PDF versions.

Examples:
Convert the GnuCash guide to a single HTML file:
cd guide/C/
docbook2html -u gnucash-guide.xml

Convert the GnuCash guide into a PDF:
cd guide/C/
docbook2pdf gnucash-guide-xml

Convert the GnuCash Help Manual into DVI:
cd help/C/
docbook2dvi gnucash-help.xml

One workaround for the images is to convert to a single HTML file and
use Print to PDF File from your web browser.

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
a XML-FO format using xmlto, you could use FOP to convert to PDF - this
step requires Java. See man xmlto for more information.

####################

Note the reference to images in PDF - I haven't solved that. The workaround 
would seem acceptable though for those who do need embedded images in the 
PDF. I've tried lots of tricks with the fileref attribute with no success.

One other tweak: I got problems with using the empty XML marker <tag /> and if 
you are in agreement, I'd like to change the image references from:
<imagedata fileref="figures/basics_accounts.png"              srccredit="Jon 
Lapham" format="PNG"/>   
to
<imagedata fileref="figures/basics_accounts.png"              srccredit="Jon 
Lapham" format="PNG"></imagedata>

Don't ask - it smells like a bug in the docbook-utils and even with this 
change, I get warnings and no images in the PDF (although it handles images 
in HTML perfectly). With />, I get errors that halt the conversion. I'll 
continue to investigate - I feel a bug report on the PDF backend coming on.

xmlto is closer to your existing xsl / scrollkeeper implementation but on my 
system, converting to PDF using xmlto took TWO HOURS and then failed with an 
error!! I can convert to XML-FO in a reasonable time but the only open source 
XML-FO converter (that I can find) is Java based and I don't want to install 
the JRE just to test one little step! Shall I bother to mention xmlto at all?

docbook2pdf takes about 2 minutes to convert either set to PDF, albeit without 
the images.

> and I haven't really had a lot of time to do more than 
> release new docs whenever someone updates them.

If you agree, I can minimise future duplication if I take the existing content 
from gnucash-guide.xml and gnucash-help.xml into a new XML file that is 
referenced from the stub. Then there'll be no duplication in the .docbook - 
it'll simply be a slightly altered version of the entity list and DTD 
declaration. It's a real bind that I can't use the existing <article>. Still, 
the .docbook will be tiny and will provide lots of alternative output formats 
for a low overhead.

> Basically, anyone who 
> wants to submit patches

If I change the id strings, the patches will be repetitive in the extreme and 
I have commit access, so if you agree, let me know and I'll commit as above.

-- 

Neil Williams
=============
http://www.dcglug.org.uk/
http://www.nosoftwarepatents.com/
http://sourceforge.net/projects/isbnsearch/
http://www.neil.williamsleesmill.me.uk/
http://www.biglumber.com/x/web?qs=0x8801094A28BCB3E3

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.gnucash.org/pipermail/gnucash-devel/attachments/20050226/7e72ccd2/attachment.bin