You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@forrest.apache.org by Jeff Turner <je...@apache.org> on 2003/04/08 19:00:00 UTC
Fixing menus
Hi,
Lots of people (including me) find Forrest's menus frustratingly limited.
Notably:
- There's an artificial distinction between 'menus' (non-clickable
titles) and 'menu-items', which are clickable links. There must be a
strict interleaving of menus and menu-items.
- Following on from the above, it isn't possible to say "this node
should stay closed until I click on it".
These are limitations of the book.xml format (which site.xml generates on
the fly).
So I was thinking, how about we ditch book.xml, and instead use Maven's
navigation.xml format?
<project name="Maven">
<title>Maven</title>
<body>
<links>
<item name="Home" href="/index.html"/>
<item name="Reference" href="/reference/index.html"/>
</links>
<menu name="Overview">
<item name="Goals" href="/goals.html"/>
<item name="Features" href="/features.html"/>
<item name="Download" href="/start/download.html"/>
<item name="News and Status" href="/status.html"/>
<item name="Getting Started" href="/start/index.html" collapse="true">
<item name="Download" href="/start/download.html"/>
<item name="Install" href="/start/install.html"/>
<item name="Integrate" href="/start/integrate.html"/>
<item name="Use" href="/start/use.html"/>
<item name="Build" href="/start/bootstrap.html"/>
<item name="Anakia Users" href="/start/anakia.html"/>
</item>
<item name="Reference" href="/reference/index.html" collapse="true">
<item name="Project Descriptors" href="/reference/project-descriptor.html"/>
<item name="User Guide" href="/reference/user-guide.html"/>
<item name="Plugins" href="/reference/plugins/index.html"/>
<item name="Developer Guide" href="/reference/developer-guide.html"/>
<item name="Project Layout" href="/reference/dirlayout.html"/>
</item>
<item name="FAQ" href="/faq.html"/>
<item name="Powered By" href="/powered.html"/>
<item name="Tasks" href="/tasks.html"/>
<item name="Glossary" href="/glossary.html"/>
</menu>
</body>
</project>
I like it mostly because:
- there's no menu/menu-item distinction
- the 'collapse' attribute would let us scratch a major itch of having
collapsible menus.
- we move closer to out-the-box support for Maven projects
Things I don't like:
- there's this <body> tag doing nothing.
- links with a common prefix (/reference/) must be duplicated.
-oOo-
On this topic, I think we need to draw a distinction between:
1) the menu "data model", which we should represent by an intermediate
menu XML format (let's call this menu.xml).
2) the XML format (book.xml, site.xml, navigation.xml) that the user
deals with.
So just as faqs, howtos and Docbook are transformed to our intermediate
doc-v11 content format, we'd have site.xml, navigation.xml etc.,
transformed into an intermediate menu.xml format.
This intermediate menu format 1) is transformed directly into a HTML
menu. We'd have:
site.xml
User --> navigation.xml ---> menu.xml ---> HTML
book.xml
menu.xml is our 'contract' with skin designers, just as site.xml and
friends are our contract with users. Separating out these two contracts
is nice, because now we can (in theory) have a proliferation of menu
styles:
site.xml Fancy DHTML menu
User --> navigation.xml ---> menu.xml ---> <ul> + CSS menu
book.xml Simple <table> menu
menu.xml isn't publicly visible, and can be verbose and even redundant as
necessary.
Thoughts?
--Jeff
Re: Data models (Re: Fixing menus)
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Jeff Turner wrote, On 10/04/2003 17.50:
> On Thu, Apr 10, 2003 at 03:22:16PM +0200, Nicola Ken Barozzi wrote:
>
>>Jeff Turner wrote, On 10/04/2003 12.56:
...
> 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.
Sounds good.
> ...
>
>>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..
I'd remove that and make Cocoon take that from the image (IIRC it can
already).
>>Project data:
...
>
> 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
And Centipede too BTW:
module.xml # Gump Object Model
properties.xml # Centipede properties
> Forrest:
>
> forrest.xml/gump.xml # Documentation Object Model
> forrest.properties # Forrest properties
Hmmm...
> 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.
Correct.
>>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.
Agreed.
>>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.
Ok then, I'd make it xml nevertheless, Ant can deal with that too with
xmlproperty.
>>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:
Yes.
> 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.
IMHO it can/should be squeezed into the Gump one. Stefano suggested that
extra things in Gump descriptor are namespaced.
> - 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)
I saw that Stefano reverted to properties.
> - easier to describe in our documentation
NOt if we keep the xml similarly flat. Look at Cocoon's cli.xconf, it
seems ok to me.
> - easily mapped to Maven's properties
?
Honestly, I don't mind using properties, they only have two issues, that
are not critical and that can be solved:
1) you don't see if a preperty ends in a space, while in xml it's evident
2) you cannot read them easily from Cocoon
Since I would like that Cocoon starts handling the "source" locations
itself, it's easier to have it in xml.
But we can quite easily make a properties-module, no big deal either way.
>>Are we getting nearer to a solution?
>
> Yep :) Much closer.
That's cool :-)
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: Data models (Re: Fixing menus)
Posted by Jeff Turner <je...@apache.org>.
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)
> ---------------------------------------------------------------------
>
Re: Data models (Re: Fixing menus)
Posted by Nicola Ken Barozzi <ni...@apache.org>.
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.
I still don't get what an explicit use of navigation.xml brings us in
this case.
I would like as an alternative to allow *only* navigation.xml, because
it brings us closer, but having also site.xml seems confusing. Hence
maybe it's better not to support it explicitly.
Hmmm...
> ...
>
>>Hmmm, ok, conceded. I put it in Gump's descriptor for my projects, but
>>somewhere we decided not to go that way IIRC. What would you say about
>>it now?
>
> I think we should perhaps define a specification of what data we need for
> a Forrest site, and then figure out how to represent it as a:
> - Gump descriptor
> - Maven descriptor
> - Custom XML for people who don't care about Gump/Maven
>
> This abstract data model should include the directory layout of the site,
> currently captured in forrest.properties.
>
> We could have a sitemap pipeline to convert external formats into a
> common internal format.
>
> Haven't really thought this out though.
The concept seems nice,
>>>>and that's why I talk about putting in site.xml, that is where users
>>>>would maybe look how to config the site... just ramblings, leave it, I
>>>>have no real intention of changing it, and overmore I don't have clear
>>>>alternatives myself.
>>>
>>>That's where I'm at too: not sure how to fix it, leaving it until things
>>>become clearer.
>>
>>Yes.
>>
>>Personally I like having that info in Gump descriptors. I am writing a
>>stylesheet that takes gump's merged descriptors and makes a site out of
>>it, *also* with the infos like the ones above.
>>
>>Given that Maven can create a Gumpo descriptor from his already, I tend
>>to think that we could use the Gump descriptor for it.
>>
>>Not that sure though, I might not be seeing nasty implications.
>
> Sounds alright to me.
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*.
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.
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.
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.
Since should not need forrest.properties for Ant but for Cocoon, we
could as well:
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)
Are we getting nearer to a solution?
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Data models (Re: Fixing menus)
Posted by Jeff Turner <je...@apache.org>.
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.
...
> Hmmm, ok, conceded. I put it in Gump's descriptor for my projects, but
> somewhere we decided not to go that way IIRC. What would you say about
> it now?
I think we should perhaps define a specification of what data we need for
a Forrest site, and then figure out how to represent it as a:
- Gump descriptor
- Maven descriptor
- Custom XML for people who don't care about Gump/Maven
This abstract data model should include the directory layout of the site,
currently captured in forrest.properties.
We could have a sitemap pipeline to convert external formats into a
common internal format.
Haven't really thought this out though.
> >>and that's why I talk about putting in site.xml, that is where users
> >>would maybe look how to config the site... just ramblings, leave it, I
> >>have no real intention of changing it, and overmore I don't have clear
> >>alternatives myself.
> >
> >That's where I'm at too: not sure how to fix it, leaving it until things
> >become clearer.
>
> Yes.
>
> Personally I like having that info in Gump descriptors. I am writing a
> stylesheet that takes gump's merged descriptors and makes a site out of
> it, *also* with the infos like the ones above.
>
> Given that Maven can create a Gumpo descriptor from his already, I tend
> to think that we could use the Gump descriptor for it.
>
> Not that sure though, I might not be seeing nasty implications.
Sounds alright to me.
--Jeff
> --
> Nicola Ken Barozzi nicolaken@apache.org
> - verba volant, scripta manent -
> (discussions get forgotten, just code remains)
> ---------------------------------------------------------------------
Re: Fixing menus
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Jeff Turner wrote, On 09/04/2003 18.18:
> On Wed, Apr 09, 2003 at 10:45:26AM +0200, Nicola Ken Barozzi wrote:
>
>>Jeff Turner wrote, On 09/04/2003 6.57:
...
>>>>I feel a bit confused by having site, book, navigation... how would a
>>>>user use them?
...
>>I understand that book.xml will be kept for dir-specific navs, but
>>what's the difference between navigation.xml and site.xml? How would
>>users use the two? Can't we scrape site.xml in favor of navigation.xml?
>>Are they mutually exclusive?
>
> site.xml and navigation.xml wouldn't be mutually exclusive, in exactly
> the same way book.xml and site.xml aren't mutually exclusive - they're
> useful for different things. Changing book.xml to navigation.xml doesn't
> change that balance.
>
> site.xml offers a few advantages over navigation.xml:
>
> - Cumulative paths, i.e.:
>
> <foo href="foo/">
> <bar href="bar.html">
> <baz href="#baz"/> <!-- The href here is foo/bar.html#baz -->
> </>
> </>
>
> - All the things linkrewriter needs. Built-in ids in the form of
> element names, and the <external-refs> section for ext: links. We can
> add a 'id' attribute to navigation.xml, solving the first issue, but
> not the second.
>
> - We can dork around with it without breaking compatibility with Maven.
>
> 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.
Honestly, I don't see why as a user I would use navigation.xml given
that site.xml is there... I thought that we could somewhat enhance
navigation.xml so that the Maven one is a subset of it, thus compatible.
Dunno though.
Who would want to use navigation.xml given that id does not give us link
rewriting? One should then make a site.xml *and* a navigation.xml... not
nice. So if I want to use rewriting, why would I want navigation? and if
I have navigation, why can't I have link rewriting?
Crappy phrases, hope you get my doubts.
>>Also, why not make book.xml in each dir an *additional* source of links,
>
> Additional to what?
On the navigation, I have site.xml contents. Below or above it I could
*also* have book.xml contents, for page-specific navigation.
The site.xml xontents would still be there, but maybe collapsed for
screen space.
>>by adding them to the navigation instead of replacing? With CSS then
>>skinwriters can decide to exclude what they prefer.
>>
>>
>>>>My best initial guess:
>>>>
>>>> (skinconf.xml)
>>>>User --> site.xml ---> navigation.xml ---> HTML
>>>> book.xml
>>>>
>>>>Skinconf.xml is also keeping metadata about the site, that could as well
>>>>be in site.xml. Not that I'm very keen on moving it there, given all the
>>>>code that has to be changed, but just taking note of it to see what you
>>>>think.
>>>
>>>I thought skinconf was logically an extension of the Gump project
>>>descriptor?
>>
>>Hmmm... does it describe the project? IMHO no
>
> ? Certainly seems to "describe the project" to me.. project-name/url,
> group-name/url, copyright, credits. Half that info probably ought to be
> in a regular Gump descriptor (its in Maven's project.xml).
Hmmm, ok, conceded. I put it in Gump's descriptor for my projects, but
somewhere we decided not to go that way IIRC. What would you say about
it now?
>>and that's why I talk about putting in site.xml, that is where users
>>would maybe look how to config the site... just ramblings, leave it, I
>>have no real intention of changing it, and overmore I don't have clear
>>alternatives myself.
>
> That's where I'm at too: not sure how to fix it, leaving it until things
> become clearer.
Yes.
Personally I like having that info in Gump descriptors. I am writing a
stylesheet that takes gump's merged descriptors and makes a site out of
it, *also* with the infos like the ones above.
Given that Maven can create a Gumpo descriptor from his already, I tend
to think that we could use the Gump descriptor for it.
Not that sure though, I might not be seeing nasty implications.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: Fixing menus
Posted by Jeff Turner <je...@apache.org>.
On Wed, Apr 09, 2003 at 10:45:26AM +0200, Nicola Ken Barozzi wrote:
>
> Jeff Turner wrote, On 09/04/2003 6.57:
> >On Tue, Apr 08, 2003 at 07:05:46PM +0200, Nicola Ken Barozzi wrote:
> >...
>
> >>Since xdoc11 is used by our users, I reckon that menu.xml /could/ be as
> >>well used, by following the analogy. Putting it backwards... why not do:
> >>
> >> site.xml
> >>User --> navigation.xml ---> navigation.xml ---> HTML
> >> book.xml
> >>?
> >
> >Yes, could do that, but then we've got a single contract with users *and*
> >skinwriters. Seems cleaner to have them separate, even if the
> >navigation.xml and menu.xml formats are identical to start with. The
> >navigation2menu.xsl stylesheet would just do a no-op.
>
> Ok, agreed. Similar to what we have done with book.xml, but this time
> it's declared as being different right from the start and can evolve as
> we need without problems.
Exactly.
> +1
>
> >>Second question (which invalidates the first ;-P)... how does it
> >>integrate with the rest of the descriptors?
> >>
> >>I feel a bit confused by having site, book, navigation... how would a
> >>user use them?
> >
> >Currently, book.xml is our 'source' format and our 'intermediate' format.
> >site.xml is an alternative source format. If we have a menu.xml
> >intermediate format, then everything else (site.xml, navigation.xml,
> >book.xml) is a source format.
>
> I understand that book.xml will be kept for dir-specific navs, but
> what's the difference between navigation.xml and site.xml? How would
> users use the two? Can't we scrape site.xml in favor of navigation.xml?
> Are they mutually exclusive?
site.xml and navigation.xml wouldn't be mutually exclusive, in exactly
the same way book.xml and site.xml aren't mutually exclusive - they're
useful for different things. Changing book.xml to navigation.xml doesn't
change that balance.
site.xml offers a few advantages over navigation.xml:
- Cumulative paths, i.e.:
<foo href="foo/">
<bar href="bar.html">
<baz href="#baz"/> <!-- The href here is foo/bar.html#baz -->
</>
</>
- All the things linkrewriter needs. Built-in ids in the form of
element names, and the <external-refs> section for ext: links. We can
add a 'id' attribute to navigation.xml, solving the first issue, but
not the second.
- We can dork around with it without breaking compatibility with Maven.
OTOH, navigation.xml can precisely define a special menu for a directory,
something site.xml can't do.
> Also, why not make book.xml in each dir an *additional* source of links,
Additional to what?
> by adding them to the navigation instead of replacing? With CSS then
> skinwriters can decide to exclude what they prefer.
>
> >>My best initial guess:
> >>
> >> (skinconf.xml)
> >>User --> site.xml ---> navigation.xml ---> HTML
> >> book.xml
> >>
> >>Skinconf.xml is also keeping metadata about the site, that could as well
> >>be in site.xml. Not that I'm very keen on moving it there, given all the
> >>code that has to be changed, but just taking note of it to see what you
> >>think.
> >
> >I thought skinconf was logically an extension of the Gump project
> >descriptor?
>
> Hmmm... does it describe the project? IMHO no
? Certainly seems to "describe the project" to me.. project-name/url,
group-name/url, copyright, credits. Half that info probably ought to be
in a regular Gump descriptor (its in Maven's project.xml).
> and that's why I talk about putting in site.xml, that is where users
> would maybe look how to config the site... just ramblings, leave it, I
> have no real intention of changing it, and overmore I don't have clear
> alternatives myself.
That's where I'm at too: not sure how to fix it, leaving it until things
become clearer.
--Jeff
> >The other formats (site.xml, book.xml, navigation.xml) are
> >strictly for menus, separate from project data. Just like in Maven,
> >navigation.xml is separate from the POM.
>
> Yes, if the above stands, the concept is correct.
>
> --
> Nicola Ken Barozzi nicolaken@apache.org
> - verba volant, scripta manent -
> (discussions get forgotten, just code remains)
> ---------------------------------------------------------------------
>
Re: Fixing menus
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Jeff Turner wrote, On 09/04/2003 6.57:
> On Tue, Apr 08, 2003 at 07:05:46PM +0200, Nicola Ken Barozzi wrote:
> ...
>>Since xdoc11 is used by our users, I reckon that menu.xml /could/ be as
>>well used, by following the analogy. Putting it backwards... why not do:
>>
>> site.xml
>> User --> navigation.xml ---> navigation.xml ---> HTML
>> book.xml
>>?
>
> Yes, could do that, but then we've got a single contract with users *and*
> skinwriters. Seems cleaner to have them separate, even if the
> navigation.xml and menu.xml formats are identical to start with. The
> navigation2menu.xsl stylesheet would just do a no-op.
Ok, agreed. Similar to what we have done with book.xml, but this time
it's declared as being different right from the start and can evolve as
we need without problems.
+1
>>Second question (which invalidates the first ;-P)... how does it
>>integrate with the rest of the descriptors?
>>
>>I feel a bit confused by having site, book, navigation... how would a
>>user use them?
>
> Currently, book.xml is our 'source' format and our 'intermediate' format.
> site.xml is an alternative source format. If we have a menu.xml
> intermediate format, then everything else (site.xml, navigation.xml,
> book.xml) is a source format.
I understand that book.xml will be kept for dir-specific navs, but
what's the difference between navigation.xml and site.xml? How would
users use the two? Can't we scrape site.xml in favor of navigation.xml?
Are they mutually exclusive?
Also, why not make book.xml in each dir an *additional* source of links,
by adding them to the navigation instead of replacing? With CSS then
skinwriters can decide to exclude what they prefer.
>>My best initial guess:
>>
>> (skinconf.xml)
>> User --> site.xml ---> navigation.xml ---> HTML
>> book.xml
>>
>>Skinconf.xml is also keeping metadata about the site, that could as well
>>be in site.xml. Not that I'm very keen on moving it there, given all the
>>code that has to be changed, but just taking note of it to see what you
>>think.
>
> I thought skinconf was logically an extension of the Gump project
> descriptor?
Hmmm... does it describe the project? IMHO no, and that's why I talk
about putting in site.xml, that is where users would maybe look how to
config the site... just ramblings, leave it, I have no real intention of
changing it, and overmore I don't have clear alternatives myself.
> The other formats (site.xml, book.xml, navigation.xml) are
> strictly for menus, separate from project data. Just like in Maven,
> navigation.xml is separate from the POM.
Yes, if the above stands, the concept is correct.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: Fixing menus
Posted by Jeff Turner <je...@apache.org>.
On Tue, Apr 08, 2003 at 07:05:46PM +0200, Nicola Ken Barozzi wrote:
...
> > site.xml Fancy DHTML menu
> >User --> navigation.xml ---> menu.xml ---> <ul> + CSS menu
> > book.xml Simple <table> menu
> >
> >
> >menu.xml isn't publicly visible, and can be verbose and even redundant as
> >necessary.
> >
> >Thoughts?
>
> Two questions.
>
> Since xdoc11 is used by our users, I reckon that menu.xml /could/ be as
> well used, by following the analogy. Putting it backwards... why not do:
>
> site.xml
> User --> navigation.xml ---> navigation.xml ---> HTML
> book.xml
> ?
Yes, could do that, but then we've got a single contract with users *and*
skinwriters. Seems cleaner to have them separate, even if the
navigation.xml and menu.xml formats are identical to start with. The
navigation2menu.xsl stylesheet would just do a no-op.
> Second question (which invalidates the first ;-P)... how does it
> integrate with the rest of the descriptors?
>
> I feel a bit confused by having site, book, navigation... how would a
> user use them?
Currently, book.xml is our 'source' format and our 'intermediate' format.
site.xml is an alternative source format. If we have a menu.xml
intermediate format, then everything else (site.xml, navigation.xml,
book.xml) is a source format.
> My best initial guess:
>
> (skinconf.xml)
> User --> site.xml ---> navigation.xml ---> HTML
> book.xml
>
> Skinconf.xml is also keeping metadata about the site, that could as well
> be in site.xml. Not that I'm very keen on moving it there, given all the
> code that has to be changed, but just taking note of it to see what you
> think.
I thought skinconf was logically an extension of the Gump project
descriptor? The other formats (site.xml, book.xml, navigation.xml) are
strictly for menus, separate from project data. Just like in Maven,
navigation.xml is separate from the POM.
--Jeff
> --
> Nicola Ken Barozzi nicolaken@apache.org
> - verba volant, scripta manent -
> (discussions get forgotten, just code remains)
> ---------------------------------------------------------------------
>
Re: Fixing menus
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Jeff Turner wrote, On 08/04/2003 19.00:
...
> So I was thinking, how about we ditch book.xml, and instead use Maven's
> navigation.xml format?
...
> - we move closer to out-the-box support for Maven projects
+1
I had the same idea, totally agree. BTW, the goal of using HTML tags
more brings us much closer to the Maven doc format.
> On this topic, I think we need to draw a distinction between:
>
> 1) the menu "data model", which we should represent by an intermediate
> menu XML format (let's call this menu.xml).
> 2) the XML format (book.xml, site.xml, navigation.xml) that the user
> deals with.
Ok.
> So just as faqs, howtos and Docbook are transformed to our intermediate
> doc-v11 content format, we'd have site.xml, navigation.xml etc.,
> transformed into an intermediate menu.xml format.
Ok.
> This intermediate menu format 1) is transformed directly into a HTML
> menu. We'd have:
>
> site.xml
> User --> navigation.xml ---> menu.xml ---> HTML
> book.xml
>
>
> menu.xml is our 'contract' with skin designers, just as site.xml and
> friends are our contract with users. Separating out these two contracts
> is nice, because now we can (in theory) have a proliferation of menu
> styles:
>
>
> site.xml Fancy DHTML menu
> User --> navigation.xml ---> menu.xml ---> <ul> + CSS menu
> book.xml Simple <table> menu
>
>
> menu.xml isn't publicly visible, and can be verbose and even redundant as
> necessary.
>
> Thoughts?
Two questions.
Since xdoc11 is used by our users, I reckon that menu.xml /could/ be as
well used, by following the analogy. Putting it backwards... why not do:
site.xml
User --> navigation.xml ---> navigation.xml ---> HTML
book.xml
?
Second question (which invalidates the first ;-P)... how does it
integrate with the rest of the descriptors?
I feel a bit confused by having site, book, navigation... how would a
user use them?
My best initial guess:
(skinconf.xml)
User --> site.xml ---> navigation.xml ---> HTML
book.xml
Skinconf.xml is also keeping metadata about the site, that could as well
be in site.xml. Not that I'm very keen on moving it there, given all the
code that has to be changed, but just taking note of it to see what you
think.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: Fixing menus
Posted by Jeff Turner <je...@apache.org>.
On Tue, Apr 08, 2003 at 08:58:02PM +0200, Bert Van Kets wrote:
> At 03:00 9/04/2003 +1000, you wrote:
> >Hi,
> >
> >Lots of people (including me) find Forrest's menus frustratingly limited.
> >Notably:
> >
> > - There's an artificial distinction between 'menus' (non-clickable
> > titles) and 'menu-items', which are clickable links. There must be a
> > strict interleaving of menus and menu-items.
> >
> > - Following on from the above, it isn't possible to say "this node
> > should stay closed until I click on it".
> >
> >These are limitations of the book.xml format (which site.xml generates on
> >the fly).
>
> IMHO These are limitation of the book2html.xsl.
> The current book.xml can have collapsible menus, it's just a matter of
> checking to which menu part the current link belongs.
> The closed menu labels can then get a link to the first item which makes
> them open and show the first page of the menu.
So using FOP as an example, if we have:
<menu label="Using FOP">
<menu-item label="Running" href="running.html"/>
<menu-item label="Embedding" href="embedding.html"/>
<menu-item label="Ant task" href="anttask.html"/>
<menu-item label="Output Formats" href="output.html"/>
<menu-item label="Compliance" href="compliance.html"/>
<menu-item label="Implemented" href="implemented.html"/>
<menu-item label="Limitations" href="limitations.html"/>
</menu>
Does clicking on the 'Using FOP' label give you the running.html page?
That isn't terribly intuitive..
> What you are describing is a 2 tier menu system. The book.xml dtd is the
> limiting factor here, as it does not allow nested menus.
> I am using a non validating Forrest version so added a second level menu
> tag, adjusted the book2html.xsl and created collapsible menus in my
> personal site without any problem.
Yes, actually the book.xml XML that site.xml generates doesn't validate
either.
> Check out www.dream-models.com.
>
> >So I was thinking, how about we ditch book.xml, and instead use Maven's
> >navigation.xml format?
>
> -1
> In the light of the carefulness of the backward compatibility used when
> implementing site.xml, I don't think it would be wise to ditch book.xml.
> I'm convinced we can maintain backward compatibility while providing
> collapsible menus in book.xml.
Oh yes, book.xml would still be there. We can keep backwards-compability
by internally translating book.xml into the more flexible intermediate
format.
--Jeff
> Bert
>
Re: Fixing menus
Posted by David Crossley <cr...@indexgeo.com.au>.
On Wed, 2003-04-09 at 04:58, Bert Van Kets wrote:
> At 03:00 9/04/2003 +1000, you wrote:
> >Hi,
> >
> >Lots of people (including me) find Forrest's menus frustratingly limited.
> >Notably:
> >
> > - There's an artificial distinction between 'menus' (non-clickable
> > titles) and 'menu-items', which are clickable links. There must be a
> > strict interleaving of menus and menu-items.
> >
> > - Following on from the above, it isn't possible to say "this node
> > should stay closed until I click on it".
> >
> >These are limitations of the book.xml format (which site.xml generates on
> >the fly).
>
> IMHO These are limitation of the book2html.xsl.
> The current book.xml can have collapsible menus, it's just a matter of
> checking to which menu part the current link belongs.
> The closed menu labels can then get a link to the first item which makes
> them open and show the first page of the menu.
>
> What you are describing is a 2 tier menu system. The book.xml dtd is the
> limiting factor here, as it does not allow nested menus.
(Pardon me, i have not yet read the rest of this thread.)
The book DTD is just a hack. If it does not meet your needs then
we can change it. It was manually reverse-engineered from the
book.xml instances of that time.
--David
> I am using a non validating Forrest version so added a second level menu
> tag, adjusted the book2html.xsl and created collapsible menus in my
> personal site without any problem.
>
> Check out www.dream-models.com.
>
>
>
> >So I was thinking, how about we ditch book.xml, and instead use Maven's
> >navigation.xml format?
>
> -1
> In the light of the carefulness of the backward compatibility used when
> implementing site.xml, I don't think it would be wise to ditch book.xml.
> I'm convinced we can maintain backward compatibility while providing
> collapsible menus in book.xml.
>
> Bert
Re: Fixing menus
Posted by Bert Van Kets <be...@vankets.com>.
At 03:00 9/04/2003 +1000, you wrote:
>Hi,
>
>Lots of people (including me) find Forrest's menus frustratingly limited.
>Notably:
>
> - There's an artificial distinction between 'menus' (non-clickable
> titles) and 'menu-items', which are clickable links. There must be a
> strict interleaving of menus and menu-items.
>
> - Following on from the above, it isn't possible to say "this node
> should stay closed until I click on it".
>
>These are limitations of the book.xml format (which site.xml generates on
>the fly).
IMHO These are limitation of the book2html.xsl.
The current book.xml can have collapsible menus, it's just a matter of
checking to which menu part the current link belongs.
The closed menu labels can then get a link to the first item which makes
them open and show the first page of the menu.
What you are describing is a 2 tier menu system. The book.xml dtd is the
limiting factor here, as it does not allow nested menus.
I am using a non validating Forrest version so added a second level menu
tag, adjusted the book2html.xsl and created collapsible menus in my
personal site without any problem.
Check out www.dream-models.com.
>So I was thinking, how about we ditch book.xml, and instead use Maven's
>navigation.xml format?
-1
In the light of the carefulness of the backward compatibility used when
implementing site.xml, I don't think it would be wise to ditch book.xml.
I'm convinced we can maintain backward compatibility while providing
collapsible menus in book.xml.
Bert