You are viewing a plain text version of this content. The canonical link for it is here.
Posted to fop-users@xmlgraphics.apache.org by Michael Grundvig <mi...@electrotank.com> on 2007/03/03 06:58:12 UTC
Simple Beginner Question
Hi all; 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. 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.
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. 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.
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!
Mike
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-users-unsubscribe@xmlgraphics.apache.org
For additional commands, e-mail: fop-users-help@xmlgraphics.apache.org
Re: Simple Beginner Question
Posted by Thomas Schraitle <to...@web.de>.
Hi,
On Samstag, 3. März 2007, Andreas L Delmelle wrote:
>
> Sorry to be intruding, but just a little FYI
Thanks for the "intrusion". :-)
> [...]
> > I am not sure how to deliver parameters to fop, but you can do it
> > in two
> > steps:
>
> With FOP 0.9x, if you want, you can supply XSLT parameters like so:
>
> fop -xml manual.xml -xsl docbook.xsl \
> -param fop1.extensions 1 \
> -pdf manual.pdf
I thought it would be possible. Thanks, learned and saved. ;)
Bye,
Tom
--
Thomas Schraitle
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-users-unsubscribe@xmlgraphics.apache.org
For additional commands, e-mail: fop-users-help@xmlgraphics.apache.org
Re: Simple Beginner Question
Posted by Andreas L Delmelle <a_...@pandora.be>.
On Mar 3, 2007, at 10:45, Thomas Schraitle wrote:
Hi,
Sorry to be intruding, but just a little FYI
> On Samstag, 3. März 2007, Michael Grundvig wrote:
> <snip />
>> 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:
With FOP 0.9x, if you want, you can supply XSLT parameters like so:
fop -xml manual.xml -xsl docbook.xsl \
-param fop1.extensions 1 \
-pdf manual.pdf
Cheers,
Andreas
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-users-unsubscribe@xmlgraphics.apache.org
For additional commands, e-mail: fop-users-help@xmlgraphics.apache.org
Re: Simple Beginner Question
Posted by Thomas Schraitle <to...@web.de>.
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: fop-users-unsubscribe@xmlgraphics.apache.org
For additional commands, e-mail: fop-users-help@xmlgraphics.apache.org