forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Piroumian, Konstantin" <KPiroum...@flagship.ru>
Subject RE: Proposal: alternative for book.xml
Date Mon, 18 Mar 2002 16:44:59 GMT
> -----Original Message-----
> From: Steven Noels [mailto:stevenn@outerthought.org] 
> Sent: Monday, March 18, 2002 7:20 PM
> To: forrest-dev@xml.apache.org
> Subject: RE: Proposal: alternative for book.xml
> 
> 
> 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.

So, maybe it'll be better to name it in a little more obvious way? Say:
doc-index? 

Speaking frankly, I didn't think about all the site menu, but only the
documentation index. Other parts of the site can have any layout they like
and documentation index has a little to do with the site menu. Am I wrong?

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

So, here comes the idea of using a generator/logicsheet/transformer with
something like this:

<menu>
	<dir:insert src="/docs/*.xml" exclude="*-exclude.xml"/>
	<menu-item href="explicit.xml" label="Explicit" />
	<dir:insert src="/docs/extra/*.xml" />
</menu>

Or a more advanced version of XPath enabled directory generator/transformer
that I've proposed a while ago (something like an XSLT syntax: <dir:for-each
.../>, <dir:value-of .../>).

Isn't it too complicated? What about KISS? ;)
Maybe simply use an Ant task to copy all the necessary files to some
destination then generate the site from there?

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

Like I've described above?

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

Yes, I know that. But as I've said, documentation index is a different to
the site menu. Should we tie these two together?

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

Sure, it'd be fine. But they should be integrated to site menu and not doc
index, don't them?

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

Ok. That's not an issue. IMHO, menu-like names would fit better in this
case.

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

Could you please elaborate on this a little. I don't see why current
'external' elements in book.dtd are not enough for inserting liks to
external resources.

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

Or my English is a little weak to understand you better ;)

Konstantin

> 
> </Steven>
> 

Mime
View raw message