GnuCash Documentation in pdf Format

[Chris Lyttle]

On Sat, 2005-02-26 at 20:25 +0000, Neil Williams wrote:
> 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">

This is fine by me, its a pretty minor change. Go ahead and add it.

> 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.
> 

As long as changing from article to book doesn't affect the html output
and it looks the same in Yelp this is fine too.
BTW The main aim behind making the help and guide docbook-xml was to
have them be integrated into the gnome-help system (Yelp) so that when
we finally get the g2 version of gnucash out the door we can drop the
html conversion from the docs module code and just use yelp within
gnucash for the help display. For me any changes must work in yelp, if
there's no breakage there then I'm fine with just about anything you
want to do.

> > 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:
> 

Looks fine too.

> 
> 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.
> 

I seem to remember some discussion of this on the gnome-docs list. I
believe that images need to be in a certain format for conversion to pdf
and that png doesn't work.

> 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.
> 

Yeah that's a bug, the /> for closing is standard docbook-xml. Are you
sure those tools aren't using docbook-sgml which that would be an
illegal tag for?

> 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?
> 

I'd like to leave xmlto in. Even tho it needs java I think its more
designed for docbook-xml conversion than other tools.

> > 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.
> 

Not really sure what you are referring to here. There isn't a lot of
content that is shared between the guide and the help so I can't see how
combining them would minimise duplication. Can you explain a bit more
please?

> > 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.
> 

Sure go for it.

Chris
-- 
RedHat Certified Engineer #807302549405490.
Checkpoint Certified Security Expert 2000 & NG
--------------------------------------------
        |^|
        | |   |^|
        | |^| | |  Life out here is raw 
        | | |^| |  But we will never stop
        | |_|_| |  We will never quit 
        | / __> |  cause we are Metallica
        |/ /    |
        \       /
         |     |
--------------------------------------------