forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Steven Noels" <stev...@outerthought.org>
Subject RE: Proposal: alternative for book.xml
Date Mon, 18 Mar 2002 16:20:05 GMT
Konstantin wrote:

> > -----Original Message-----
> > From: Steven Noels [mailto:stevenn@outerthought.org]
> > Sent: Sunday, March 17, 2002 6:36 PM
> > To: forrest-dev@xml.apache.org
> > Subject: Proposal: alternative for book.xml
> >
> >
> > I've been looking into book.xml, looking for a replacement
> > which is less linked to the idea of generating static
> > document collections. I've baptised my alternative 'sitemap',
> > a name which is bound to be changed due to prior art, but the
> > best name I could come up with so far.
>
> Why not 'site-index' or simply 'index'? As I can see from the
> structure it's
> closer to an index than to a map.

"index" will do, I guess. So we'll have the (rather unobviously named?)
index.xml document in the root of each project documentation section.

> > What I have so far is a XML Schema proposal - I want to throw
> > it in the group for feedback. The idea is that each project
> > provides a sitemap.xml, which can be manually authored as-is
> > for the entire site structure, or the result of doing some
> > sort of directory traversal. We could have some sort of
> > SitemapDirectoryGenerator which generates such a document,
> > checking whether there are sitemap.xml in a directory that
> > override the default sequence.
>
> So, site creation will be two--step build, isn't it:
>  - SitemapDirectoryGenerator creates sitemap.xml (site-index.xml)
>  - site author modifies it manually
>  - Cocoon creates pages according to sitemap.xml

Not sure whether one needs to be able to manually modify the result of
an automated process - I'd rather say that one can modify the
*behaviour* of an automated process by overriding defaults using
site.xml. Consider site.xml as being a parameter to a
ForrestIndexGenerator, which produces an expanded and enhanced view on
the traversed structure in an XML document (valid against the same site
Schema).

> Not so bad and rather maintanable. It will be possible to
> adminster and
> update the site remotely simply by editing/uploading new
> sitemap.xml file.

Yes. Preferably, these index.xml documents should be dispersed across
the documentation hierarchy: the idea is that only documents which
should be put in a specific order need to be defined in an index
document (per directory, remember .htaccess style). The documents which
are not referred to in an index document are appended to the declared
entries in index.xml (or are inserted in specific, explicitely declared
locations).

> > I haven't put any comments in the Schema, yet, so here goes:
> >
> > - sitemap: pretty obvious
> > - node: a node contains other nodes or leafs (for filesystem
> > based structures, this would be a directory, but I choose a
> > more generic name with e.g. Xindice-backed document
> > collections in mind)
> > - leaf: a document resource
> > - import: specifies which sitemap.xml should be imported in
> > this location (we could also do this using XInclude)
> > - external: provision for externally linked resources
>
> Why not use document structure names, e.g.: area, chapter,
> section, page?
> Will this structure be used for purposes  other than documentation
> generation?

Yes. Remember that Forrest will be used to power the new xml.apache.org
website. We should think in a broader perspective than only
project-specific documentation sites: what we are aiming at is the
creation of a Cocoon webapp that is able to generate the entire
xml.apache.org site, including relevant project metrics such as #
downloads, # cvs commits, etc...

Stefano mentioned http://eyebrowse.tigris.org/: wouldn't it be nice if
Eyebrowse is able to produce (dynamically) the same kind of index.xml
structure, so that we can seamlessly merge the site navigation with the
mailing list archives? Or WebCVS?

> One more alternative is to extend book.dtd to allow nested
> menus. Nodes and
> leaves are too abstract, IMHO, and are a little not obvious.

Branch and leaf? Collection and resource? The abstract names were
choosen deliberately. See above.

> > Creating a stylesheet that transforms this document structure
> > to a tree navigation or a 'yahoo-path' is fairly trivial.
>
> Yup
>
> >
> > One thing I'm not to happy with is the use of output-media
> > dependent URI attributes on node and leaf:
> >
> >   <leaf label="Home" uri="index.html"/>
>
> What about an extensionless format:
>    <leaf label="Home" uri="index"/>
>
> The output format will be defined with a build option or some
> other way.

Seems OK to me.

> > This obviously will cause problems when generating
> > other-than-HTML output.
> >
> > The idea basically is that we should be able to create such a
> > sitemap document for each kind of resource.
>
> What kind of resources are expected other than static documentation?

Lots :-)

> > Anyway, here goes as a first proposal: fire at will!
>
> Not much to fire yet ;)
>

Hehe.

I hope I'm able to explain what I really mean with this index format:
let me know if I'm not clear.

</Steven>


Mime
View raw message