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 22:22:24 GMT
Konstantin,

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

we should agree upon a global format for navigational taxonomies, so
that each resource repository (being it a static document collection for
documentation purposes, mailing list archives, CVS Web views etc) can
expose its internal hierarchy (navigation, menu, pick-your-term) using
the same XML format.

If you consider this taxonomy, it goes much further than a simple
project documentation website:

xml.apache.org
  projects (what we do)
    cocoon
      documentation
      graphs (downloads)
      cvs web view
      mailing list archives
      ...
    xerces
    xalan
    ...
  general info
    mailing lists
    cvs repositories
    infrastructure
    hall of fame
  etc

This is only skimming the surface, we really should do this exercise
(and we will find out some sections will re-appear on several locations
at the same time), but I hope this shows you that what we are aiming at
is much more than a collection of static web pages.

We need to define an URI-space for the entire website, and map this
URI-space back to a collection of pipelines in a Cocoon sitemap. But
this will only provide us with a 'content' view, whereas we also need a
tree navigation that helps people to navigate across the entire website
(using a tree or by showing a yahoo-path on each page)

[...]

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

The site generation process will be the Cocoon crawler to start with,
but is bound to be dynamic in the future. Forrest should be able to
collect the necessary documents from each sub-project on its own, and
not depend on Ant trickery to do its job. After all, we all want to
build Forrest, but don't want to be webmasters-drones-on-call to run Ant
scripts if and when some sub-project decides it wants to add some extra
info on the website.

I like your first suggestion, and will try to enhance my Schema and
functional description of that nifty Generator using it. It will be up
to a Real Programmer to transform this idea into reality however ;-)

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

I believe the documentation index and site menu should be tied to the
same taxonomy description, they are basically different renditions of
the same information. For documentation, we show a nice HTML tree, for
other pages, there's only a the tabs and yahoopath, etc. Point is that
we shouldn't hardcode the navigational taxonomy in the XSLT stylesheets,
but let them depend on the explicit or implicit hierarchy of the
different resources on which the site is based.

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

See above.

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

Let's first agree on the big picture, names we can decide upon
afterwards.

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

Well, as I said I would like to be able to present the implicit taxonomy
of non-document collection resources also as a navigational tree on a
web page, when necessary.

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

Or both :-p

Somebody else who cares to comment? Or is everybody off to
http://conference.wyona.org/ already? (which I cannot attend :-(

</Steven>


Mime
View raw message