forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ross Gardler <rgard...@apache.org>
Subject Re: docbook documentation splittet in several chunk
Date Mon, 14 Nov 2005 13:45:26 GMT
Fabian Müller wrote:
> 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. 

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.

> 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.

It is in the FORREST_HOME/build/plugins directory. If it was not 
installed Forrest would have told you.

Ross


Mime
View raw message