forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stefano Mazzocchi <stef...@apache.org>
Subject Re: [todo?] So, what are those internals?
Date Sun, 09 Jun 2002 13:18:51 GMT
Steven Noels wrote:
> 
> 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.

The above is very low priority ATM IMO.

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

This touches a nerve: which community is responsible for project-wide
content? I don't think it should be Forrest's but
general@xml.apache.org... but who becomes responsible? nobody and the
documentation sucks, just it happens for jakarta.

So, it might be good to follow Steven's suggestion and work on those
general docos here and keep them going. People will follow what works,
not what is structurally more balanced.

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

Sounds good.

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

Since I'm back to dial-up mode (for personal reasons), I can't volunteer
for any work what requires some non-timed connection to a remote server
for a while in the future. 

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

This is, IMO, what I was referring to as 'internals': the forrest
concept model of the URI space. We need to work on this before going
further.

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

It would be great to have such a feature, but I would move this on Phase
2. We are currently on Phase 1 and we require to *get there* first
before attempting to do anything more than 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).

I'm not personally against Linkmaps, but I'm not bugged by direct
hyperlinking enough to dedicate efforts to implement the concept. At the
same time, I'll be happy if others do.
 
> 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...

There is a very very draft-stage stub in the skin/forrest-site/fo
directory in the CVS. FO-lovers, feel free to jump in and help.

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

Yes, this is something I would really like to see for Phase 1.

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

Hmmm, that should proceed incrementally as we move along the underlying
content structure.
 
> 11) Content migration guerilla

I like this :) It really shows the concept.
 
> 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).

Well do that when we get there.
 
> 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.

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

Cool. Thanks for keeping the ball flying.

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