forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jeff Turner <je...@apache.org>
Subject Re: Data models (Re: Fixing menus)
Date Thu, 10 Apr 2003 15:50:51 GMT
On Thu, Apr 10, 2003 at 03:22:16PM +0200, Nicola Ken Barozzi wrote:
> 
> Jeff Turner wrote, On 10/04/2003 12.56:
> >On Wed, Apr 09, 2003 at 06:26:47PM +0200, Nicola Ken Barozzi wrote:
> >
> >>Jeff Turner wrote, On 09/04/2003 18.18:
> >
> >...
> >
> >>>OTOH, navigation.xml can precisely define a special menu for a directory,
> >>>something site.xml can't do.
> >>
> >>So it seems that site.xml is a superset of navigation.xml, and that with 
> >>a few additions it can be even better.
> >
> >If we could allow a site.xml per directory which augments a central
> >site.xml, then it would be a superset of what book.xml/navigation.xml
> >offers.
> 
> Interesting.
> 
> But again, I miss the role of having the three.
> If we have site.xml as you suggest, we could as well do without either. 
> So as a user I would never use them, only the enhanced site.xml.

Yes, an _enhanced_ site.xml.

There are some examples in Forrest's docs where site.xml-generated menus
aren't appropriate:

community/howto/bugzilla-patch/book.xml
community/howto/cvs-ssh/book.xml

I think allowing a site.xml in subdirectories that overrides the parent
site.xml would solve these corner cases.

In any case, we need to support book.xml for backwards-compatibility, and
it can plug these holes in site.xml until we fix it.

...
> Ok then, let's see what goes into that descriptor.
> 
> From skinconf.xml there are two kinds of tags IMHO: one tells us 
> descriptove information about the *project* another about the *site*.

Agreed, although the line is a bit fuzzy; the ability to specify
height/width for credit images, for instance.  We can sort this out
later..

> Project data:
> 
>   <searchsite-domain>www.krysalis.org</searchsite-domain>
>   <searchsite-name>Krysalis</searchsite-name>
> 
>   <!-- mandatory project logo
>        skin: forrest-site renders it at the top -->
>   <project-name>Centipede</project-name>
>   <project-url>http://www.krysalis.org/centipede//</project-url>
>   <project-logo>images/project-logo.gif</project-logo>
> 
>   <!-- optional group logo
>        skin: forrest-site renders it at the top-left corner -->
>   <group-name>Krysalis</group-name>
>   <group-url>http://www.krysalis.org/</group-url>
>   <group-logo>images/group-logo.gif</group-logo>
> 
>   <!-- optional host logo (e.g. sourceforge logo)
>        skin: forrest-site renders it at the bottom-left corner -->
>   <host-url>http://sourceforge.net</host-url>
>   <host-logo>http://sourceforge.net/sflogo.php?...</host-logo>
> 
>   <!-- The following are used to construct a copyright statement -->
>   <year>2002-2003</year>
>   <vendor>The Krysalis Community Project</vendor>
> 
>   <credits>
>     <credit>
>       <name>Built with Apache Forrest</name>
>       <url>http://xml.apache.org/forrest/</url>
>       <image>images/built-with-forrest-button.png</image>
>       <width>88</width>
>       <height>31</height>
>     </credit>
>   </credits>
> 
> IMHO these should go in the gump descriptor.
>
> I agree though that they 
> should be extracted to a common format, merged with all datas, and fed 
> that way into Forrest.
>
> Anyway, here are the infos about the presentational aspects of the site:
> 
>   <!-- Do we want to disable the Google search box? -->
>   <disable-search>false</disable-search>
>   <!-- Do we want to disable the print link? -->
>   <disable-print-link>false</disable-print-link>
>   <!-- Do we want to disable the PDF link? -->
>   <disable-pdf-link>false</disable-pdf-link>
>   <!-- Do we want to disable the xml source link? -->
>   <disable-xml-link>false</disable-xml-link>
>   <!-- Do we want to disable w3c compliance links? -->
>   <disable-compliance-links>false</disable-compliance-links>
> 
> 
>   <!-- Some skins use this to form a 'breadcrumb trail' of links. If 
> you don't
>   want these, set the attributes to blank. The DTD purposefully 
> requires them.
>   -->
>   <trail>
>     <link1 name="krysalis at sf.net" 
> href="http://www.sf.net/projects/krysalis/"/>
>     <link2 name="krysalis" href="http://www.krysalis.org/"/>
>     <link3 name="" href=""/>
>   </trail>
> 
> 
> These are not properly project properties, but may as well be put there, 
> or with the new forrestproperties.

All sounds good.

Seems we're converging on the same data/properties division that Maven
has:

project.xml           # Project Object Model
project.properties    # Maven properties

Forrest:

forrest.xml/gump.xml  # Documentation Object Model
forrest.properties    # Forrest properties

Where Maven uses a Betwixt to build a POM Java class, we can use a Cocoon
pipeline + XMLModule to provide access to data in the sitemap and XSLTs.

> Then we have the forrest.properties, that are intimately tied to 
> Forrest. They are not part of the project descriptor, as they cannot 
> really be used by anything else, only Forrest.

There are currently two types of properties in forrest.properties:

# Properties describing the user's project (used in Ant)
project.name
project.skin
project.status
project.content-dir
project.conf-dir
...

# Properties specifying Forrest's behaviour in the current project
forrest.echo
forrest.catalog.verbosity
forrest.validate
forrest.validate.xdocs
forrest.validate.skinconf
...

The project.* ones should be moved into {gump,forrest}.xml.

> These should remain, only that I would like them under the documentation 
> dir. We would only need an extra tag in the descriptor that tells us 
> where the base dir for Forrest is.

+1, makes sense.

> Since should not need forrest.properties for Ant but for Cocoon, we 
> could as well:

We need them for Ant as well.  Ant does the XML validation, and we
need forrest.properties to specify which files to validate.  There's
also things like specifying the Cocoon debug level.

> 1) read the Gump descriptor or equivalent and get the Forrest base
>    dir
> 2) run Cocoon with that info
> 3) Cocoon uses its pipelines to gather info from the Gump profile
>    (converting on the fly to skinconf for compatibility), and
>    source locations from forrest.xml (the properties)

Oh, bit of terminology difference there.. seems you're thinking:

gump.xml     # Project data
forrest.xml  # Forrest properties

I was thinking:

forrest.xml         # Project data
forrest.properties  # Forrest properties:

Two issues here:

- do we need a separate descriptor (my forrest.xml), or can all of
  Forrest's data (including directory layout) be squeezed into
  gump.xml?  I don't mind.

- If our 'properties' data model is nice simple key:value pairs, then
  I think we should use a flat .properties file instead of XML.
  Reasons being:
    - simpler to edit (see cocoon.properties)
    - easier to describe in our documentation
    - easily mapped to Maven's properties

> Are we getting nearer to a solution?

Yep :) Much closer.


--Jeff

> -- 
> Nicola Ken Barozzi                   nicolaken@apache.org
>             - verba volant, scripta manent -
>    (discussions get forgotten, just code remains)
> ---------------------------------------------------------------------
> 

Mime
View raw message