Fabian Müller wrote:
Ross Gardler <[EMAIL PROTECTED]> 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.
Well you should believe what you read. It will download it and install
it. You have a point that it should mention this more explicitly -
patches for our docs are welcome.
Note, if an Internet connectio is not avilalable then Forrest provides
errors and tips on how to manually install the plugin.
Does it mean that it copies some files in the forrest
directory structure
The point of plugins is that they can be provided by third parties, not
just by Apache Forrest. Another goal is to reduce the size of Forrest by
stipping out all but the requried funcitonlaity. Thus we will not always
be able to retrieve it locally.
Because of this and other things I did not understand I downloaded the
file manually.
Whilst are docs are minimal it is usually best to follow the
instructions rather than guess at some hidden meaning. If, after
following the instructions it doesn't work then ask questions on the
user list.
I read
http://forrest.apache.org/pluginDocs/plugins_0_80/pluginInfrastructure.html
which answers the question what happens when forrest "installs" a plugin:
That is a developer doc, for those who need to know how it works. We try
and hide such unnecessary info from users.
| When Forrest installs a plugin it downloads a zip of the plugin code
...
This means that the plugins (or at least some of them) are already on
my harddisk.
Not if you are using a binary release.
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?
See above, re third party plugins. Also see
http://issues.apache.org/jira/browse/FOR-388 which is relevant to
"official" plugins.
In the above issue you can see there are a number of workarounds for
those who don't want to or cannot download.
A final reason is that plugins are a versioned resource. You may want to
use a specific version of a plugin, which is different from the one on
your src directory.
Note the download is a one time download, once the plugin is installed
it need never be downloaded again (unless you clean you build 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
Have you also changed the name of your source file?
Try requesting tut.xml, this should show you the internal format of the
document.
Also look n PROJECT_HOME/build/webapp/WEB-INF/logs for some log filts
that may point to what the problem is.
[EMAIL PROTECTED]:~/opt/apache-forrest-0.7/plugins$ ls
build.xml org.apache.forrest.plugin.output.pdf plugins.xml pluginTemplate
[EMAIL PROTECTED]:~/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.
It is in the FORREST_HOME/build/plugins directory. If it was not
installed Forrest would have told you.
Ross
