forrest-user mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ross Gardler <rgard...@apache.org>
Subject Re: Hiding sections
Date Tue, 21 Mar 2006 09:32:05 GMT
David Crossley wrote:
> Flavio Cordova wrote:
> 
>>Is there a way to set any attribute (or something else) to a section
>>so I could omit it when using forrest site or forrestbot, based on a
>>parameter ?
> 
> 
> Forrestbot is just an automated way to run "forrest site".
> 
> 
>>Today I use forrest to create an application's user manual. Most of
>>the information I use to create this documentation is based on use
>>cases specifications, but this specification has some information that
>>aren't appropriated to end users. So today I keep two different
>>documents, one for developers and other for end users (this last one
>>using forrest)..
>>
>>So I'd like to unify these two documents and keep it all on Forrest's
>>format... then, developers will see the full content while end users
>>will receive the same files without some sections...
> 
> 
> This sounds like simple pre-processing.
> 
> I have a solution tested that works. However
> it has a couple of problems. Perhaps other devs
> can see a way around it. See the [*] below.
> 
> For the sections that you want excluded, add a class
> attribute, e.g.
> ...
>   <body>
>     <section id="overview">
>       <title>Overview</title>
>       <p>Hello to all</p>
>     </section>
>     <section class="dev" id="dev-examples">
>       <title>Using examples as templates</title>
>       <p>Hello to developers</p>
>     </section>
> ...
> 
> In your project sitemap.xmap:
> ...
> <map:match pattern="user-manual**.xml">
>   <map:generate src="{project:content.xdocs}{1}.xml"/>
>   <map:transform src="{project:resources.stylesheets}/stripDev-to-document.xsl" />
>   <map:serialize type="xml-document"/>
> </map:match>
> ...
> 
> The stripDev-to-document transformer's stylesheet removes
> the relevant sections and xsl:copy the rest. Here is the
> main part of the stylesheet:
> ...
>   <xsl:template match="body">
>     <body>
>       <xsl:apply-templates select="section[not(@class='dev')]"/>
>     </body>
>   </xsl:template>
> ...

This is similar to th solution I was proposing that uses XSL. The only 
real difference is that I was not suggesting adding the processing to a 
custom skin. The reason for doing it at the other end of the processing 
pipeline is that it will work with an input format (that supports the 
creation of classes). The above will only work on xdocs that are located 
in the projects xdoc directory.

However, if your use case is that you only want xdocs processed in this 
way then this will work well and is easy to implement. It also removes 
the need for a processing parameter since this information is in the 
URL. It would be easy to do this with my proposal too, and is better 
than a forrest.properties or skinconf parameter.

> [*] now to the problems ...
> 
> Menus and links all point back to the main site, i.e. to the
> "dev" version.

Not a problem in my proposed approach.

A solution for this approach would be to pass a path to the XSL and 
rebuild all links to include the prefix. Problem then is, which links to 
process and which to leave the same. Sticky.

> Because of the "user-manual" in the URIs, the left-hand
> navigation menus are not triggered open.

This is messy too. It could be worked around by generating a custom 
site.xml for requests in this url space. But now we are just getting silly.

My conclusion...

Although harder to implement, my proposal does not have the problems of 
URL space that Davids does. My CSS proposal is just as easy to implement 
as Davids solution, but has the problem of the output source containing 
everything (and wouldn't work for generetaion of other output formats, 
such as PDF, without further customisation).

Ross

Mime
View raw message