forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ross Gardler <>
Subject Re: lm question for our docs
Date Mon, 22 May 2006 08:59:52 GMT
Ferdinand Soethe wrote:
> I have a problem in the release rotation of our docs that might be
> solved elegantly using lm.
> The problem is as follows: In site.xml we have this sections
> <versions tab="docs">
>     <overview label="Overview" href="versions/index.html"/>
>     <v0.8 label="0.8-dev" href="site:v0.80//index"/>
>     <v0.7 label="0.7 (current)" href="site:v0.70//index"/>
>     <v0.6 label="0.6" href="site:v0.60//index"/>
>   </versions>
> to create the versioned docs subtabs.
> When creating a new release we will change this to
> <versions tab="docs">
>     <overview label="Overview" href="versions/index.html"/>
>     <v0.9 label="0.9-dev" href="site:v0.90//index"/>
>     <v0.8 label="0.8 (current)" href="site:v0.80//index"/>
>     <v0.7 label="0.7" href="site:v0.70//index"/>
>   </versions>
> basically rotating the version number one down.
> The problem is that the published release package will not have a
> docs_0_90-directory because it would just bloat the package to include an (at
> this point) exact copy of 0.8-docs as 0.9-docs.
> Soon after however, when the realease is announced, we will publish
> the very same docs to our Website and by then will have a
> 0.9-directory.
> So what I'd like to do is create a lm:map-entry that is used as href
> in <v0.9 label="0.9-dev" href="site:v0.90//index"/> and works like
> this:
> if there is a 0.9 directory in the static pages, point to it
> if there isn't, point to the same directory on the forrest website.
> That way we won't have to touch site after building the release
> candidate, simply do an svn-copy of the current dev docs to the new
> dev docs.
> Is that possible, is it a good idea, will it work?

The idea is great, this is exactly the kind of flexibility the 
locationmap was designed to give us.

Unfortunately, it won't quite work the way you want because the syntax 
for url rewriting and locationmap lookup is different. Therefore to 
change the behaviour requires a change in the site.xml file.

However, I have a slightly different suggestion that will work. I've 
always intended on using this technique to include javadocs and other 
auto generated docs in our site, but have never found the time to build 
the necessary plugins. Anyway, to my suggestion:

Create a placeholder page that says something like "the latest 
development docs are not available in this content object because...". 
This page should provide a link to the Forrest website version, it could 
provide a redirect meta tag too (assuming Forrest will let such a thing 
pass through).

Then, in site.xml you have:

<v0.9 label="0.9-dev" href=""/>

and in the site-author locationmap you have:

<map pattern="*">
     <location src="{project:content}/docs_{1}"/>
     <location src:"{project:content}/devDocsPlacehoder.html"/>

If the versioned directory exists it will be used, if not the 
placeholder page will be used.

When we release a new version we would need to update the URL in the 
placeholder page. If we want to avoid this we could dynamically generate 
the placeholder, using the docs version as a parameter. Once this 
dynamically created page is available this solution will work for any 
number of future releases without modification of the source files.


View raw message