forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From mueller....@gmx.net (Fabian Müller)
Subject Re: docbook documentation splittet in several chunk
Date Mon, 14 Nov 2005 12:27:57 GMT
Ross Gardler <rgardler@apache.org> writes:

> Whilst I would never claim that our docs cannot be improved, in your
> case I think a little time understanding the basics of Forrest and XML
> will help. For example:
>
>> I downloaded
>> org.apache.forrest.plugin.input.simplifiedDocbook-0.1.zip,
>
> This is not the correct way to use a Forrest plugin, see
> http://forrest.apache.org/pluginDocs/plugins_0_70/usingPlugins.html

Yes, I had read everything on this page before I downloaded the
mentioned file but it did not help me to understand the basics and how
it works. In the "How is a Plugin Installed?" section I read this for
example:

| If a site requires one or more plugins then the site designer will
| have named them in the project.required.plugins property in the
| projects forrest.properties file. When Forrest builds the site it
| will automatically discover the plugin and install it.

What is meant by "install it"? Does it mean that forrest automatically
downloads the file? I cannot really believe that because that would
require an internet connection which should be mentioned in the
documentation. Does it mean that it copies some files in the forrest
directory structure and that forrest does not download anything? That
would mean that I have the plugin already on my harddisk and that it
is bundled with the main forrest tarfile. I cannot imagine this as
well. Or does "install" mean something like "make available" which
could be a synonym for "load" which is used it the next line:

| For example,
| project.required.plugins=org.apache.forrest.plugin.input.OpenOffice.org,org.apache.forrest.plugin.input.simplifiedDocbook
| will cause Forrest to load the plugins called
| "org.apache.forrest.plugin.input.OpenOffice.org" and
| "org.apache.forrest.plugin.input.simplifiedDocbook".

Because of this and other things I did not understand I downloaded the
file manually.

I read
http://forrest.apache.org/pluginDocs/plugins_0_80/pluginInfrastructure.html
which answers the question what happens when forrest "installs" a plugin:

| When Forrest installs a plugin it downloads a zip of the plugin code

Well, but now I found the directory apache-forrest-0.7/build/plugins/
with the subdirectories:

org.apache.forrest.plugin.input.dtdx
org.apache.forrest.plugin.input.OpenOffice.org
org.apache.forrest.plugin.input.projectInfo
org.apache.forrest.plugin.input.simplifiedDocbook
org.apache.forrest.plugin.input.wiki
org.apache.forrest.plugin.output.pdf
org.apache.forrest.plugin.output.POD
org.apache.forrest.plugin.output.Text

This means that the plugins (or at least some of them) are already on
my harddisk. Why do they need to be downloaded if they are bundled
with the tar file? Or are only those plugins downloaded that are not
listed in this directory?

Now I have

project.required.plugins=org.apache.forrest.plugin.output.pdf,org.apache.forrest.plugin.input.simplifiedDocbook

in [Project-Root]/forrest.properties.
In [Project-Root]/src/documentation/sitemap.xmap I changed
<map:match pattern="tutorial.html">
to
<map:match pattern="tut.html">
because I do not want to use the docbook stylesheets directly but the
plugin. Then I pointed my browser to
http://localhost:8888/tutorial.html and did not get any content. I
only saw the "decoration" (the menu on the left and the logo at the
top right and and the footer so on). I used this DTD this time:

<!DOCTYPE book PUBLIC "-//Norman Walsh//DTD DocBk XML V3.1.4//EN"
                         "file:///usr/share/xml/docbook/schema/dtd/4.2/docbookx.dtd">

The documentation on
http://forrest.apache.org/pluginDocs/plugins_0_80/pluginInfrastructure.html
says:

> When Forrest installs a plugin it downloads a zip of the plugin code
> and extracts it into the plugins directory of Forrest [...]

fabian@mobile1:~/opt/apache-forrest-0.7/plugins$ ls
build.xml  org.apache.forrest.plugin.output.pdf  plugins.xml  pluginTemplate
fabian@mobile1:~/opt/apache-forrest-0.7/plugins$

The simplified docbook plugin is not there. Typing "forrest" in the
project root directory does not put the plugin into this directory.

>> This time the "validate-xdocs" part
>> showed a lot of error messages. Here are only a few of them:
>
> That will be because Forrest validates your document against the DTD
> you specify. You document is not valid against the DTD specified in
> the XML you supplied which was:
>
> <!DOCTYPE article PUBLIC "-//OASIS//DTD Simplified DocBook XML V1.0//EN"

Yes, I used this DTD because this was used in the example file as
well. I thought that the simplified Docbook plugin can only use
elements that are specified in this Simplified DocBook DTD. Since
elements like <sect1> are not defined in this DTD I thought that the
simplified Docbook plugin cannot use them. But the I searched
sdocbook2document.xsl and realized that "sect1" is mentioned there so
now I gues that this plugin knows what to do with an element like
this. But I am only guessing and the plugin's README.txt does not say
anything about this.

> It may just requrie that you use the correct DTD (it looks like
> Docbook v4.x)

Ok, I did this now but as I wrote above I do not see any content. But
the error messages are away of course. 

I probably could go on with questions like these but I guess that I
bother you. Probably I should work with Forrest and related
technologies a few hours each day for about two or three months and
then come back to the users list with more specific questions and
enough knowledge to understand the answers. But at the moment I tend
towards being satisfied with what I currently have ...

Thank you Ross for your replies and trying to help me.

Fabian Müller

Mime
View raw message