You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@velocity.apache.org by "Henning P. Schmiedehausen" <hp...@intermeta.de> on 2006/11/03 14:06:50 UTC
Re: Right way to use docbook and xdoc support from Velocity in other
Marshall Schor <ms...@schor.com> writes:
Hi Marshall,
let's see if I got your questions right.
First thing is, how to integrate the docbook environment in your
project so that you don't duplicate libraries etc.
Well, I wouldn't. That is why I started the docbook documentation
outside the Velocity engine tree. The libraries included in the
docbook tree are there for the one reason of creating the
documentation.
If you share them with the build path of your application, you will at
some point have to update the dependencies of your project and if then
your documentation creation process fails, you will have to split up
anyway. So in a way, I consider the docbook framework to be a tool in
itself just as e.g. LaTeX which you wouldn't copy into your project
either if the docs were written in TeX.
For Velocity, the documentation in docbook format will probably live in
.../docbook/src/docbook/userguide/VelocityUsersGuide.xml
.../docbook/src/docbook/devguide/VelocityDevelopersGuide.xml
in the docbook repository. For the actual release versions of the
Velocity engine, the docs get built _outside_ the engine tree and then
copied (probably to .../engine/pdf or .../engine/doc/pdf, no decision
about that yet.
The xdocs are a different beast because they are likely to change with
every release of the engine (or even change with each build; release
notes etc.). So the PDFs will just be linked from the xdoc
documentation.
Second, how do you put your own docs into the docbook framework. I
just did a similar thing at a customer project; here is my recipe:
- get the tree from .../velocity/docbook
- follow the instructions from README.FIRST (get the jai stuff)
- now you have to carve out the current velocity documentation (that
is in there already):
- remove src/docbook/userguide and its contents
- remove src/images/*
- Let's say you want to start with the docs for your project. Let's say
you have two guides, the FooGuide and the BarGuide.
- create src/docbook/foo and src/docbook/bar.
- If you already have a docbook skeleton for your guides, copy them to
src/docbook/foo/FooGuide.xml and src/docbook/bar/BarGuide.xml
- Now open the main build.xml file. Look for the "all" target.
- Remove the
<!-- Build the Users Guide -->
<ant antfile="build-docbook.xml" target="all">
<property name="docbook.dir" value="userguide"/>
<property name="docbook.file" value="VelocityUsersGuide"/>
</ant>
section. Add
<!-- Build the Foo Guide -->
<ant antfile="build-docbook.xml" target="all">
<property name="docbook.dir" value="foo"/>
<property name="docbook.file" value="FooGuide"/>
</ant>
<!-- Build the Bar Guide -->
<ant antfile="build-docbook.xml" target="all">
<property name="docbook.dir" value="bar"/>
<property name="docbook.file" value="BarGuide"/>
</ant>
instead.
- Now run "ant". The framework should create directories for foo and
bar in the target folder, containing the foo and bar
guide. Obviously the two guides will use the same kind of styles and
formatting, but for common documentation, this might actually be
wanted.
- Files you want to look into:
- src/styles/htmlsingle.xsl
- src/styles/html.xsl
- src/styles/pdf.xsl
for anything that should be ant-filtered (these files can be left
alone most of the times)
- src/styles/html/custom.xsl
- src/styles/pdf/custom.xsl
these files are called "custom" for a reason, mainly because they can
and should be customized to your needs. They define e.g. the
numbering of chapters and sections, whether you get ToC and/or title
pages, borders etc. These files are currently customized for Velocity
but you might find that the settings here work for you. If not, they
should provide a starting point but then you have to read up on the
docbook xsl docs to customize these files further.
- src/css/html/stylesheet.css
is the stylesheet (referenced from src/styles/html/custom.xsl) used to render
the HTML docs. There you might want to change the color of h1,h2,h3,h4,h5, because
it is the Velocity greyish-blue used so prominently. :-)
My general recommendation would be (mainly because that it how I will
try to do it with Velocity, but with a current known user base of
"one" for the docbook framework it is hard to speak of best
practice... :-) ) that you simply create a docbook sub-project either
inside your project or next to your project (like Velocity). There you
keep the docbook files and simply copy rendered versions (HTML or PDF)
into your actual project.
Best regards
Henning
>I have a general question about reusing the docbook and xdoc support
>that Velocity nicely provides. One way that works is to copy the
>docbook (or xdoc) trunk (e.g. jakarta/velocity/docbook/trunk) into my
>project, and start modifying my copy to be for my documentation. This
>includes the code, libs, ant build scripts, etc. However, that
>duplicates in my project the lib/ content, etc., which would be the same
>for all projects that were using this version - and could be shared.
>Pros for copying - keeps your projects version independently of others -
>so if the others change in ways that might "break" your build - you're
>isolated from these.
>Cons: duplicate files in SVN.
>What's the recommended best practice here?
>-Marshall Schor
>---------------------------------------------------------------------
>To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
>For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
--
Dipl.-Inf. (Univ.) Henning P. Schmiedehausen INTERMETA GmbH
hps@intermeta.de +49 9131 50 654 0 http://www.intermeta.de/
RedHat Certified Engineer -- Jakarta Turbine Development -- hero for hire
Linux, Java, perl, Solaris -- Consulting, Training, Development
Social behaviour: Bavarians can be extremely egalitarian and folksy.
-- http://en.wikipedia.org/wiki/Bavaria
Most Franconians do not like to be called Bavarians.
-- http://en.wikipedia.org/wiki/Franconia
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
Re: Right way to use docbook and xdoc support from Velocity in other
Posted by "Henning P. Schmiedehausen" <hp...@intermeta.de>.
Marshall Schor <ms...@schor.com> writes:
Hi,
hm. It should be possible to do some ant magic to have a "docbook
generation environment" that can be shared all over projects and is
static (containing libs, transformer zip's etc.) and just have the src
tree outside it. However that would in its current state require the
user to download two trees (one with the environment, one with the
actual docbook sources), probably set an environment variable or
property to find the tree and then convert it.
Will think about this some more. Might even be easily doable.
Best regards
Henning
>Henning P. Schmiedehausen wrote:
>> Marshall Schor <ms...@schor.com> writes:
>>
>> Hi Marshall,
>>
>> let's see if I got your questions right.
>>
>> First thing is, how to integrate the docbook environment in your
>> project so that you don't duplicate libraries etc.
>>
>> Well, I wouldn't.
>Hi Henning -
>You make a good point. Let's assume the particular jars, zip-files of
>docbook transforms, etc., are not
>integrated into my project, but rather are kept in the lib/ directory of
>my special docbook project.
>Now suppose producing docbooks this way becomes popular with other
>Apache projects
>(as xdoc has) and rather than being just 1, there are many projects in
>Apache using this.
>Is there a way Apache shares the sharable parts of all these doc books
>in many projects
>(for example, the FOP jars, the docbook xsl transforms, etc.) that would
>be the same
>for all of these, or is it a better practice to have every one of these
>projects have their own
>copy of all of this?
>If this did exist - I suppose it would consist of some kind of a shared
>repository of
>tools found useful in Apache project maintenance, and a way to have the
>Ant scripts
>reference such a repository of shared objects (not just JARs, but also other
>resources like docbook XSL Transforms).
>That was what my question was trying to get at...
>Thanks for the rest of your note - I'm on my way converting our
>documentation to docbook
>format so we can produce PDFs with all the nice features that make for
>readable documentation
>(TOCs, cross refs with page numbers, footnotes, etc.).
>-Marshall
>---------------------------------------------------------------------
>To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
>For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
--
Dipl.-Inf. (Univ.) Henning P. Schmiedehausen INTERMETA GmbH
hps@intermeta.de +49 9131 50 654 0 http://www.intermeta.de/
RedHat Certified Engineer -- Jakarta Turbine Development -- hero for hire
Linux, Java, perl, Solaris -- Consulting, Training, Development
Social behaviour: Bavarians can be extremely egalitarian and folksy.
-- http://en.wikipedia.org/wiki/Bavaria
Most Franconians do not like to be called Bavarians.
-- http://en.wikipedia.org/wiki/Franconia
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org
Re: Right way to use docbook and xdoc support from Velocity in other
Posted by Marshall Schor <ms...@schor.com>.
Henning P. Schmiedehausen wrote:
> Marshall Schor <ms...@schor.com> writes:
>
> Hi Marshall,
>
> let's see if I got your questions right.
>
> First thing is, how to integrate the docbook environment in your
> project so that you don't duplicate libraries etc.
>
> Well, I wouldn't.
Hi Henning -
You make a good point. Let's assume the particular jars, zip-files of
docbook transforms, etc., are not
integrated into my project, but rather are kept in the lib/ directory of
my special docbook project.
Now suppose producing docbooks this way becomes popular with other
Apache projects
(as xdoc has) and rather than being just 1, there are many projects in
Apache using this.
Is there a way Apache shares the sharable parts of all these doc books
in many projects
(for example, the FOP jars, the docbook xsl transforms, etc.) that would
be the same
for all of these, or is it a better practice to have every one of these
projects have their own
copy of all of this?
If this did exist - I suppose it would consist of some kind of a shared
repository of
tools found useful in Apache project maintenance, and a way to have the
Ant scripts
reference such a repository of shared objects (not just JARs, but also other
resources like docbook XSL Transforms).
That was what my question was trying to get at...
Thanks for the rest of your note - I'm on my way converting our
documentation to docbook
format so we can produce PDFs with all the nice features that make for
readable documentation
(TOCs, cross refs with page numbers, footnotes, etc.).
-Marshall
---------------------------------------------------------------------
To unsubscribe, e-mail: velocity-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: velocity-dev-help@jakarta.apache.org