Making future Forrest upgrades less painful

[Jeff Turner <je...@apache.org>]

Hi,

I was thinking, lots of projects like FOP have an overridden 0.4 sitemap.
These projects cannot be built out the box with Forrest 0.5.  The sitemap
needs to be ported to 0.5's.  Once that happens,  all users wishing to
build docs have to switch from 0.4 to 0.5 en-mass.

To prevent a similar situation in 0.5 -> 0.6, how about we let users
provide version-specific sitemaps:

src/documentation/sitemap-0.5.xmap

So if src/documentation/sitemap-<version>.xmap is found, it is used in
preference to src/documentation/sitemap.xmap.  That way, when we release
Forrest 0.6, people can still build projects with Forrest 0.5.

Thoughts?  Better ideas?  If not I'll have a go at doing this for 0.5.


--Jeff

Re: Making future Forrest upgrades less painful

[Juan Jose Pablos <ch...@che-che.com>]

Jeff,

Jeff Turner wrote:
> 
> To prevent a similar situation in 0.5 -> 0.6, how about we let users
> provide version-specific sitemaps:

+1 to versioning sitempas. Maybe better inside sitemap.xmap <version />

> 
> Thoughts?  Better ideas?  If not I'll have a go at doing this for 0.5.
> 

I would not want to test everytime I run forrest for diferent versions, 
maybe a task for upgrade (forrest upgrade), then a normal use.

You can test if someone have overwrite sitemap because the location is 
different right?

Cheers,
Cheche

Re: Making future Forrest upgrades less painful

[David Crossley <cr...@indexgeo.com.au>]

Dave Brondsema wrote:
> Jeff Turner wrote:
> >
> > I was thinking, lots of projects like FOP have an overridden 0.4 sitemap.
> > These projects cannot be built out the box with Forrest 0.5.  The sitemap
> > needs to be ported to 0.5's.  Once that happens,  all users wishing to
> > build docs have to switch from 0.4 to 0.5 en-mass.
> >
> > To prevent a similar situation in 0.5 -> 0.6, how about we let users
> > provide version-specific sitemaps:
> >
> > src/documentation/sitemap-0.5.xmap
> >
> > So if src/documentation/sitemap-<version>.xmap is found, it is used in
> > preference to src/documentation/sitemap.xmap.  That way, when we release
> > Forrest 0.6, people can still build projects with Forrest 0.5.
> >
> > Thoughts?  Better ideas?  If not I'll have a go at doing this for 0.5
> >
> > --Jeff

Sounds like an elegant solution to me. Typical.

> An XSLT file for them to convert their sitemap from 0.4 to 0.5 would be
> useful too.  But that might not be possible if there are some complex
> changes, in which case we should provide a document explaining the changes
> that the enduser would have to do to upgrade their file.
>
> Dave Brondsema

A transformation tool could be difficult - so many possibilities.

I help/do a website where we need to have our own sitemap. It is
only one tiny match to intercept a certain document and generate
it with full DocBook. We just mark the section we have added and
occasionally copy the Forrest head sitemap and re-insert our match.

It would be cool to have an Ant task in the build that took our
sitemap snippet and inserted it at the top of the matchers in a
copy of the default sitemap.

--David Crossley

Re: Making future Forrest upgrades less painful

[Dave Brondsema <da...@brondsema.net>]

On Wed, 3 Sep 2003, Jeff Turner wrote:

> Hi,
>
> I was thinking, lots of projects like FOP have an overridden 0.4 sitemap.
> These projects cannot be built out the box with Forrest 0.5.  The sitemap
> needs to be ported to 0.5's.  Once that happens,  all users wishing to
> build docs have to switch from 0.4 to 0.5 en-mass.
>
> To prevent a similar situation in 0.5 -> 0.6, how about we let users
> provide version-specific sitemaps:
>
> src/documentation/sitemap-0.5.xmap
>
> So if src/documentation/sitemap-<version>.xmap is found, it is used in
> preference to src/documentation/sitemap.xmap.  That way, when we release
> Forrest 0.6, people can still build projects with Forrest 0.5.
>
> Thoughts?  Better ideas?  If not I'll have a go at doing this for 0.5.
>
>
> --Jeff
>

An XSLT file for them to convert their sitemap from 0.4 to 0.5 would be
useful too.  But that might not be possible if there are some complex
changes, in which case we should provide a document explaining the changes
that the enduser would have to do to upgrade their file.

Dave Brondsema