forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ross Gardler <rgard...@apache.org>
Subject Re: [RT] RAW content
Date Sat, 27 Nov 2004 01:24:39 GMT
Nicola Ken Barozzi wrote:
> Nicola Ken Barozzi wrote:
> 
>> Ross Gardler wrote:
>> ....
>>
>>> I'm not sure I am mixing the two issues. The plugin decides what to 
>>> do based on the request URI
> 
> ...
> 
>> But the thing still keeps ringing, as in my head all the URI space is 
>> identified in the locationmap... gotta think more about this :-)
> 
> 
> Ok, my first thoughts.
> 
> The javadocs are in fact a rendering of .java files.
> So, if I tell the locationmap to mount my
> 
>   src/java dir
> 
> under
> 
>   /sources
> 
> ,I could ask javadocs for
> 
>   src/java/MyClass.java
> 
> as
> 
>   /sources/Myclass.javadoc.html
 >
> If the javadocs view is the "default" one, I could also see it as:
> 
>   /sources/Myclass.html

OK, I'm with you so far

> Javadocs also have extra cross-reference info, and that should be 
> pregenerated by the plugin buildfile and used as metadata by the plugin. 
> or at the first call of the java file. This is how the Cocoon plugin for 
> this works.

Yes, I had not addressed how the javadocs are created in the first 
place. I had made the assumption that they were available as a part of 
the *application* build system. However, you are correctly saying that 
they should be built as part of the *site* build system.

> Let's instead imagine, for the sake of completeness, that the plugin has 
> to pregenerate all the files before the start of the Forrest run.
> 
> In this case, I would imagine that this plugin needs to know the place 
> where the java code is, and the user can indicate in the locationmap 
> that it wants to get the javadocs from the javadoc plugin docs 
> generation dir.

So, if I understand you correctly, the process is:

command: forrest site
process: look at "in use" plugins, ensure all plugins are installed
process: pre-processing of relevant plugins (i.e. javadoc generation)
process: start forrest

Everything good so far.

request: /sources/myclass.javadoc.html
process: javadoc plugin handles request in the normal "forrest" way

This doesn't work, we are running in *site* mode, so unless we are going 
to re-write all the pregenerated links as *.javadoc.html this will not 
work, since they will be of the form *.html. This means that the 
"javadocs" bit in the request is meaningless in anything but the first 
request (which is presumably the site link into the javadocs).

OK, so we might as well just have sources/myclass.html. You did say that 
above, but you also said "if javadocs are the default view", thereby 
implying that we could also do, for example, 
/sources/myclass.javaxref.html. Since we're not re-writing all the links 
in the xref generated files this is meaningless as the generated links 
are of the form *.html.

======================================================================
Now we have two sets of pregenerated files that have an identical URI space.

/sources/mycalss.javadocs.html = /sources/myclass.html
/sources/mycalss.xref.html     = /sources/myclass.html
======================================================================

To avoid this we have to move the definition of the "type" of document:

sources/javadoc/myclass.html
sources/xref/myclass.html

But we are now we are back at square one. How does Forrest know what to 
do with these? It will try and process them as normal requests.

So, we need a plugin!

This one is an Internal plugin as we have to be sure that it will 
process the request before any other plugin gets hold of it. The javadoc 
plugin has:

<map:match pattern="/sources/javadoc/**.html"/>
   <map:read src="{locationmap:javadoc}"/>

and the java xref plugin has:


<map:match pattern="/sources/xref/**.html"/>
   <map:read src="{locationmap:javaxref}"/>

Cocoon can walk the links just as it would any other page. This means we 
can skin the output if we want to, or you can leave it as is 
(configurable in the plugin).

The problem now is that we are fixing the URI space as /sources/javadoc 
and /sources/xref, which is another thing we want to avoid.

Can Cocoon match on a parameter? e.g.

<map:match pattern="{locationmap:javadoc.URI}/**.html"/>
   <map:read src="{locationmap:javadoc.dir}"/>

If not I'm sure we could right the necessary class.

This removes the include and exclude stuff that both yourself and 
Thorsten were unsure about and it will still work in both dynamic and 
static modes of Forrest.

----

One last problem (with a suggestion...)

We still need to pregenerate the files, so the plugin still has a 
"preprocess" target, problem is, /forrest run/ will be slow if we do the 
preprocessing up front.

I would therefore propose that we do not do any pre-processing on 
/forrest run/ (only on /forrest site/). The plugin should be intelligent 
enough to put a placeholder in place if it could do the preprocessing, 
but has not done so. It should also be capable of using a previously 
generated set of documents, possibly inserting a warning stating they 
may not be up to date. This should be sufficient for testing.

There are other issues here (what about those running as a webapp in a 
production environment), but I feel I am digressing and they don't seem 
to be major issues so I will leave them for now.

Ross


Mime
View raw message