Hi Michael,
On Samstag, 3. März 2007, Michael Grundvig wrote:
> I'm working on a large application and will need to generate
> some documentation. Specifically I need to create a manual and would
> like that to be in both HTML and PDF format when I'm done. There might
> also be a few articles as well and keeping them in the same format
> would be convenient but not required.
> I've done some research and it SEEMS that Docbook + FOP is a good way
> to do this.
DocBook is one of the primary formats for writing documentation. It exists
for a long time and in most cases you can't do anything wrong. From your
explanation above I think DocBook should be really useful for you. It has
a helpful user community, good stylesheets and it is pretty stable.
> Before I really dig in though I wanted to make sure I
> wasn't heading down the wrong path. I've reached the point where I can
> create a PDF file via this command:
>
> fop -xsl docbook5-xsl-1.72.0\fo\docbook.xsl -xml manual.xml -pdf
> manual.pdf
>
> and all seems to work (even hyphenation). Where I run into problems is
> when I start trying to do anything beyond the basics. For instance,
> bookmarks.
The stylesheets contains code for creating bookmarks but it is disabled by
default. You have to enable it to show up in your PDF.
I am not sure how to deliver parameters to fop, but you can do it in two
steps:
1. Create the intermediate XSL-FO file:
xsltproc --output manual.fo \
--stringparam fop1.extensions 1 \
docbook5-xsl-1.72.0\fo\docbook.xsl \
manual.xml
2. Format the XSL-FO file:
fop manual.fo manual.pdf
I hope you have the latest FOP, have you? Do not use FOP version below
0.93. :)
> I've found a lot of documentation on using various
> techniques for bookmarks but they all seem to involve editing the XSL
> or generated FO files.
You can do it, but it is not required as I showed you in the last
paragraph.
> Sadly, I'm way over my head with the massive XSL
> used to get this working. Isn't there a way to just put that in my
> manual.xml file? That seems to make the most sense to me.
It is really not that difficult as it seems to be. If you want to
customize your output to your needs, that's true, then you need a deeper
knowledge about XSLT and probably XSL-FO. However, the DocBook
stylesheets can be customized through various parameters without digging
too much into the stylesheet internals.
Adapting a parameters to your needs is in most cases enough. The
parameters are documented here:
For HTML:
http://docbook.sourceforge.net/release/xsl/current/doc/html/
For XSL-FO:
http://docbook.sourceforge.net/release/xsl/current/doc/fo/
If you have lots of parameters better use a customization layer. Bob
Stayton, one of maintainers for the DocBook stylesheets, created a really
helpful book about it. Read more about how you can customize the
stylesheet here:
http://www.sagehill.net/docbookxsl/CustomMethods.html#CustomizationLayer
> Should I even be using Docbook at all? What do others use to generate
> manuals? To be honest, this seems very cumbersome thus far and I'm
> thinking there has to be a way to make it cleaner. Any advice would be
> appreciated. Thanks!
If you are considering DocBook, I would recommend you to subscribe to the
DocBook mailinglists. Here you can ask your questions and you will get
lots of helpful answers. :)
In my company we use DocBook for a long time now and are pretty satisfied.
We create HTML, PDF and even Manpages for our whole documentation. It's
an easy, reliable and automated process.
Hope that helps,
Tom
--
Thomas Schraitle
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
