forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stefano Mazzocchi <stef...@apache.org>
Subject Re: Proposal: alternative for book.xml
Date Wed, 20 Mar 2002 15:43:28 GMT
Steven Noels wrote:
> 
> 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.

Yes, I like this much more than "sitemap", for obvious reason.

> > > 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).

I don't think that having an index 'out of synch' should be something
bad. I might want to work on a document *without* having it linked in
the navigation. So, no, I don't want this 'index' to be automatically
generated at all.

> > 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). 

Exactly.

> 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? 

That wouldn't be hard, just write a velocity template for that.

> Or WebCVS?

I think it would be easier to write a CVS generator for Cocoon rather
than trying to adapt what we already have there on webcvs... but I don't
really care.
 
> > 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.

Yes, I think we should not be that abstract.
 
> > > 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>


-- 
Stefano Mazzocchi      One must still have chaos in oneself to be
                          able to give birth to a dancing star.
<stefano@apache.org>                             Friedrich Nietzsche
--------------------------------------------------------------------



Mime
View raw message