forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Steven Noels" <stev...@outerthought.org>
Subject [todo?] So, what are those internals?
Date Sun, 09 Jun 2002 06:58:35 GMT
After reading Stefano's mail, I found myself thinking "Yeah, but what
are those internals?", "Where should we actually be working on, then?".
Add some more thinking about my first real involvement with open source
development, group dynamics etc, and I went into literature mode.

The next two weeks, I have a fairly busy 'paid work' agenda so I won't
be doing much, and I really wanted to post some general thoughts on the
progress so far, and what we should be doing next.

                                      ~o~

1) Forrest CVS repository

Several people are apparently feeling it's spring cleaning time, which
is good - there is various cruft here and there and we should try to
keep our repository nice and tidy. Lately, I was wondering if we
shouldn't set up some coding guidelines for XML/XSLT documents, i.e.
tabsize, indentation, etc... just as we have for Java code. Also, we
need to make sure we make sufficient reference to the Apache license,
and I don't know whether the common practice of including a reference to
the license inside each file is recommended or required anymore.

2) Content

We need 'boilerplate' template content for reuse across other XML
subprojects, i.e. CVS access for committers, proficient use of the patch
utitity, and the like. I think such common content could be created and
stored within Forrest and later on migrated to the main XML site. I
found myself also thinking that we should have some people feeling
responsible about the main site.

3) DTDs

DTD documentation - some of you have seen the thread (cocoon-dev) of
Konstantin posting a new draft for the XML Schema of the Cocoon sitemap
and the XMLSpy-generated documentation for this grammar on
http://outerthought.net/sitemap/sitemap.html... we need similar things
for our DTDs, preferably automated and grafted into the sitemap. I've
just polled James Clark for catalog support in DTDinst, we could set up
a DTD --(DTDinst)--> RELAXNG --(XSLT)--> HTML pipeline if DTDinst works
with catalogs.

4) Forrestbot

The progress so far is that we (Nicola, myself, Pier, Brian, Sam,
Stefano) have been discussing at length the different possibilities of
moving 'forrestbot', the automated './build.sh docs' cron job currently
running on outerthought-owned equipment to ASF equipment, and also
moving the publication target from www.krysalis.org/forrest to the
xml.apache.org website. So far, we have been partially successful, but
not finished yet. We have not yet obtained accounts for nagoya as the
host platform for the cron job, but neither are we ready to move there:
forrest is currently only able to publish itself, and not any other XML
subprojects (Cocoon, the main site, etc). Nicola seems swamped
currently, so if anyone feels like he's up to it, automating
cross-project builds, and implementing support for the forrest
descriptor, feel free to jump in.

5) Site hierarchy (tabs et al)

We really need to think about information design, i.e. structure of the
URI request space, and how this maps onto (remote) repository structure
and graphical look & feel. In terms of navigational aids in our current
preferred skin, we have breadcrumbs, tabs and an outline. In terms of
general structure, we have (culled from different projects):

 * http://www.apache.org/                  (ASF)
   * http://xml.apache.org/                (The XML project)
     * the main site
     * http://xml.apache.org/forrest/      (XML subprojects)
       * http://xml.apache.org/cocoon/link/index.html
                                           (internal structure)

In terms of repository structure, I assume we have one CVS location per
subproject (the src/documentation dir of each subproject), and the
directory hierarchy inside this location reflecting the tab
structure/internal structure. Do we need to have a stronger binding
between the directory hierarchy and the tabs/outline? What about the
information which isn't present in this hierarchy (I assume we don't
have everything in place to produce the new aggregated main page -
http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-forrest/src/resources/l
ayout/xml.apache.org/home.html?rev=1.3, we'll need some extra
information there).

6) Comment facility

Some thinking has been going on in forrest-dev and cocoon-dev about
dynamic comments/additions to existing docs, and given slashedit,
chaperon and wikiland and the SourceWritingTransformer, it is difficult
not to envision forrest supporting this kind of informal document
revision process for the entire XML project. We (as in Outerthought,
Stefano ;-) are willing to provide a testbed server to play with this,
and given the relative success Nicola and I had asking for access to ASF
equipment, we could hopefully migrate this afterwards to ASF equipment.
It would be great if we have a running Cocoon webapp somewhere that is
linked from the static pages where one can enter comments or additions
through a webform, and these comments being automagically placed in
patch queue. I assume Diana has some ideas about this ;-)

7) Link management

We have various people discussing better link management through
lightweight TopicMaps. We still have the need to vote on link elements
in the DTD, and the XSLT that comes with it (if we use this TopicMap
approach).

8) PDF generation

Printable pages. For docheads who actually like to do XSLT instead of
internals, here's your work area. We need PDFs with automated table of
contents, pagination, table formatting (!), image support, etc...

9) Stats graphs

Who remembers the early days of forrest? We were planning to generate
graphs of vital project statistics (# downloads, # committers, etc...)
Sam has been putting up some shell scripts to extract this info form
various locations, but there's still plenty of work ahead, also with
actually visualizing this data and aggregating it with the static
documentation. (http://www.apache.org/~rubys/stats/)

Krysalis Wings (http://www.krysalis.org/wings/index.html) could
eventually be helping us out there, if we can't manage to do it with
XML --(XSLT)--> SVG --(Batik)--> PNG transformations.

10) Main-site front-page design & content provisioning

As indicated above. We should start work on finalizing the graphical
look & feel and its HTML implementation.

11) Content migration guerilla

We need to 'support' subprojects transitioning to forrest (new DTDs,
perhaps new repository structure, etc). For smallish projects, we can
simply grab their documentation and do the work ourselves and provide it
back as a patch. We need to have the necesary tools for this (XSLT
migration stylesheets, the validation target in our build environment,
migration targets, etc).

12) Cocoon crawler (regeneration of unmodified sources, efficiency,
errors)

There's a number of outstanding issues with the Cocoon crawler, my prime
concern being its unawareness of unmodified files. This means the entire
website is regenerated each time, making the use of rsync or other
remote synchronization mechanisms difficult or inefficient.

13) Libre

Oh well... ;-) See various other threads!

                                      ~o~

OK, family time right now.

If we agree some of this thoughts actually being todo's, I'll move them
to forrest.xgump.

Have fun,

</Steven>


Mime
View raw message