Marshall Schor <[EMAIL PROTECTED]> 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: [EMAIL PROTECTED]
>For additional commands, e-mail: [EMAIL PROTECTED]
--
Dipl.-Inf. (Univ.) Henning P. Schmiedehausen INTERMETA GmbH
[EMAIL PROTECTED] +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: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
