Re: PDFs for user-guide, accessibility-guide and system-admin-guide

[Shaun McCance <shaunm gnome org>]

On Thu, 2006-03-09 at 00:09 -0700, Brent Smith wrote:
> Jody Goldberg wrote:
> > On Tue, Mar 07, 2006 at 10:57:49PM -0700, Brent Smith wrote:
> > 
> >>I've been working on generating some new PDFs for the documentation in
> >>the gnome-user-docs package.  I've come up with some build scripts[1]
> >>that  generate some decent output using Apache's FOP and Norman Walsh's
> >>DocBook -> XSL-FO stylesheets.
> > 
> > 
> > I'd love to see a write up of how you generated those.  As a
> > non-docs person that generates content there's a steep learning
> > curve to find that various tools necessary.
> > 
> > Thanks
> 
> Jody,
> 
>     Unfortunately, you're right - there is a steep learning curve.  I
> would recommend taking a look at these technologies in the following
> order: DocBook[1], XSL[2], libxml2/Xalan[3], XSL-FO[4] and then Apache
> FOP[5].
> 
> Also, I can't lie - Shaun McCance has been an excellent help on #docs in
> irc.gnome.org, and being a co-maintainer for yelp didn't hurt either.
> 
> Basically our documentation is written in DocBook XML.  From there, you
> use a XSL stylesheet to convert the DocBook XML to the desired format;
> This can be either HTML (we have our own stylesheets written by Shaun in
> the gnome-doc-utils module) or XSL-FO, in which case we use Norman
> Walsh's stylesheets[6].  If the output is XSL-FO, then we have one more
> step to create the PDF, and that is to run the Apache FOP processor on
> the XSL-FO output.  You can provide customization layers for the
> conversion from DocBook to XSL-FO, and Bob Stayton has written an
> excellent reference on this[7].  Once you feel comfortable with all
> this, you can take a look at the customization layer that I wrote
> against Norman's stylesheets[8].
> 
> I know this is probably not what you wanted, so I will try to write up
> something about how this all works, i.e. a walkthrough tutorial, one of
> these days.

Ideally, we'd get this whole toolchain integrated into
gnome-doc-utils, so you could just type 'make pdf', grab
a cup of joe, and move on with your life.

I foresee consistency problems in using Norm's stylesheets.
One of the big reasons we did our own thing with HTML was
that the i18n stuff in Norm's XSLT just didn't meet our
needs, and plugging different i18n code into Norm's XSLT
would have meant replacing nearly every non-trivial piece
of XSLT anyway.

I'm still not completely happy with our i18n stuff, but it
does address a lot of concerns that translators have brought
to me, and I'm confident we can make it better.

Now, I know I have a nasty habit of letting my perfectionism
get in the way of getting real work done, so let me clarify:
Absolutely continue forward with what you're doing.  Do not
balk on my wishy-washy thoughts of making our own FO XSLT.

--
Shaun