xml-general mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Theodore W. Leung" <twle...@sauria.com>
Subject Re: Forrest (a.k.a. xml.apache.org 2.0)
Date Tue, 18 Dec 2001 19:05:03 GMT
On Sun, 2001-12-16 at 13:33, Stefano Mazzocchi wrote:
> [sorry for cross-post: this is a general issue, but I'd like the cocoon
> people to know what I'm doing so that they might give me a hand :)]
> 
> I started the effort that will, hopefully, bring us a much more useful
> documentation system for xml.apache.org and, hopefully, to the entire
> ASF, even if political and ego obstacles will get in the way.
> 
> I personally don't care: this effort is mainly to create a better
> documentation infrastructure following the goals outlined below. I
> started the Cocoon project three years ago exactly for this reason and
> now that has all the features I needed, I think I can attack the problem
> from a very wide angle. 
> 
> The site building system will be targetted toward xml.apache.org, but
> I'll keep a very broad perspective, making it possible to adapt the
> system to other apache.org projects with very few changes.
> 
> BIG DISCLAIMER: however, whether this happens or not, I personally don't
> care. For sure, don't count on me wasting my time on fighting about 'my
> DTD is better than yours' or 'my system is
> faster/smaller/cleaner/easier-to-use/more-extensible than yours'.
> 
> I'll come up with a system that works and then you guys will vote on
> what to do. I consider this an exercise to present full Cocoon
> potentials (that, objectively, beat the pants out of all the other
> systems used around Apache) but nothing more than this.
> 
>                                     - o -
> 
> Ok, now that I stated this, let's get into the effort goals.
> 
> GOALS
> -----
> 
> 1) Speed: current xml.apache.org is slow. Empirical studies on learning
> processes indicate that if a page takes more than 10 seconds on a 56Kbs
> modem, the cognitive experience is degrated.
> 
> 2) Coherence: current xml.apache.org is extremely incoherent. Again,
> it's easy to understand that lack of coherence between subprojects docs
> is perceived (and sometimes reflects!) lack of cooperation.
> 
> 3) Navigation: the navigation experience on current xml.apache.org is a
> nightmare. There is no way to perceive the basic elements of spatial
> navigation: where am I? where can I go? how do I go back? how do I go
> there?
> 
> 4) Depth: the current xml.apache.org page layout forces a flat hierarchy
> of levels. The current Cocoon documentation somewhat extends this, but
> the visual look doesn't reflect the notion. Visual codes are extremely
> important to allow a easy and immediate navigation even at the deepest
> level.
> 
> 5) Usefulness: xml.apache.org contains powerful software but it's not
> powerful in itself. It should be a window on the information useful for
> both users and developers, along with friendly behavior, such as
> print-friendly versions of the single pages and of the whole
> per-subproject documentation, pagination of long articles,
> site-restricted search, graphs of project-related data and so on.
> 
> 6) Simplicity: xml.apache.org is done by volunteers, on all levels.
> Nobody is directly paid to do this. Not even myself. So, if the above
> goals are met, but the system is not simple and immediate to use for
> those who have to maintain and update the information, the result is
> void over a short period of time.
> 
> 7) Extensibility, Flexibility, Modularity: web sites, just as software,
> are living entities that adapt on their environment. The build system
> must not restrict the ability to evolutionary extend the information
> architecture.
> 
> 8) URI Solidity and Future Compatibility: URIs are contracts between the
> publisher and the user. Human users have the ability to estimate the
> long-term validity of these contracts and 'route around' eventual broken
> links, while machine users do not. The goal is to come up with a system
> that allows to generate a web site with strong URIs.
> 
> 
> Design Decisions
> ----------------
> 
> staticity: even if I think that the availability of a dynamic publishing
> system would be beneficial, considering the web site load, the load of
> the apache machines and the state of the JVM for FreeBSD and the
> political problems behind all this, it's *must* easier (at least for
> now) to have a static version of the site batch-produced and then placed
> into the web-serving space.
+1
> automaticity: the site will be automatically generated out of files
> stored into CVS. The idea is to have GUMP-like nagging features that
> send email to the various mail lists using XML validation to estimate
> the 'integrity' of the docs placed.
+1
> For this reason, in honor of Sam Ruby's great work, and for the
> resonation with 'forest', thus a huge number of trees (i.e. XML files),
> I call this effort "Forrest".
> 
> I believe that together, Forrest and Gump, will help bringing apache
> quality one step up (moreover, as in the name, forrest wraps gump and
> will publish its generated data, providing more overall coherence)
> 
>                                         - o -
> 
> separation of concerns
> ----------------------
> 
> There are three concern islands, here is a list of their duties.
> 
> subproject
> ==========
> 
> each subproject should provide:
> 3.a) a 'description' file that includes information on the codebase, its
> description, its released versions, its CVS modules, its CVS tags, its
> mail lists and its documentations (yes, a subproject might have more
> than one, think of Xerces1/Xerces2, Xalan1/Xalan2, Cocoon1/Cocoon2).
> [proposed filename: /description.xml]
>  
> 3.b) a 'committers info' file that includes information on the
> committers, along with a short bio, an email address and a picture of
> them. [proposed filename: /committers.xml]
> 
> 3.c) a 'change log' file that includes information on changes and
> software relases [proposed filename: /changes.xml]
> 
> 3.d) a 'todo list' file that includes the information on things to do
> and who volunteered for doing it [proposed filename: /todo.xml]
> 
> 3.e) a 'news' file that includes events and useful information that
> should be made available to the general public.
> 
> then, for each documentation (location is get from the description
> file):
> 
> 3.f) a 'table of content' that indicates the hierarchical sequence of
> the files and where to find them into the CVS repository (for each
> documentation). This is kept as a single file to allow document writers
> to maintain 'coherence' and visualize the entire part. This is
> equivalent to the stylebook book.xml file but with full nesting
> capabilities.
> 
> 3.e) the pages that componse the documentation (their location is get
> from the ToC file)
> 
> Log scanner
> ===========
> 
> The log scanner is a set of scripts that scan the logs from the CVS, the
> mail lists and the web site to gather information on:
> 
>  1) mail list activity (subscribers and messages)
>  2) web site activity (hits and downloads)
>  3) CVS activity (general commits, commits per person)
> 
> This scanner provides this information in a simple format that can be
> easily fed into the documentation building system.
> 
> Build system
> ============
> 
> The build system will:
> 
> 1) aggregate, filter and otherwise adapt the information collected from
> the various subprojects CVS modules, from the log scanner and from the
> GUMP run into static HTML files (for the browser pages), static PDF
> files (for print-friendly versions) and JPEG images (for graphs).
> 
> 2) generate navigation information in all the pages
> 
> 3) check validation of all the required XML files and send nag messages
> to the mail lists if failure occurs.
> 
> 4) generate httpd-related corollary files (.htaccess, header.html,
> footer.html and so on).
> 
> 5) upload the parts that didn't have failures online.
> 
> The goal is to have the system running completely autonomous: this
> follows the Gump approach. [Sam, I'll need your help here, since I don't
> have an account on nagoya]
> 
>                                         - o -
> 
> Things to decide
> ================
> 
> 1) DTDs
> -------
> 
> The Cocoon project already has DTDs for 'documentation','change
> logs','todo list' and 'specifications'. They mainly use XHTML tags and
> are very easy to learn (they are an expansion of the original stylebook
> DTDs, so it's pretty easy to automatically adapt existing stylebook
> documents to this improved DTD, still keeping the simplicity we had
> before).
> 
> The rest of the required DTDs (description, news and ToC) must be agreed
> upon (i'll work on them in the next days)
> 
> 2) URIs
> -------
> 
> In order to achieve the future-compatible goal, we must come up with a
> guideline for URIs.
> 
> For example, the Cocoon project had /cocoon and /cocoon2, then Cocoon
> 2.0 was released final and we moved /cocoon2 into /cocoon and /cocoon
> into /cocoon1, creating a shit-load of broken links.
> 
> Two solutions where proposed (add your own if you have more)
> 
>  a) use version specific information and use mod_rewrite to adapt. for
> example
> 
>  xml.apache.org/cocoon/1.8.2/index.html
>  xml.apache.org/cocoon/2.0b1/index.html
>  xml.apache.org/cocoon/2.0b2/index.html
>  xml.apache.org/cocoon/2.0rc1/index.html
>  xml.apache.org/cocoon/2.0rc2/index.html
>  xml.apache.org/cocoon/2.0/index.html
> 
> then
> 
>  xml.apache.org/cocoon/ -> xml.apache.org/cocoon/2.0/index.hml
> 
> Problem is that while those versioned URI are never broken, the
> version-less redirected URI is changed for each release and doesn't
> reduce broken links. Also, it's probably easier to download the required
> version and look into the shipped docs and results in unnecessary big
> web sites.
> 
>  b) use semantic-meaningful yet version-less URIs
> 
>   xml.apache.org/cocoon/previous/ -> points to the previous generation
> docs
>   xml.apache.org/cocoon/ -> points to the latest docs
>   xml.apache.org/cocoon/next/ -> points to the next generation docs
> 
> which removes the need to have keep all the docs versions online, yet
> provides the ability to have both versions the latest one and the
> previous generation (for Cocoon would be Cocoon 1.8.2, Cocoon 2.0,
> Cocoon 2.1-dev today). 
> 
> The problem of broken links isn't solved since everytime there is a
> transition, there is a chance of breaking previously established links
> if the docs ToC changes from one generation to the next.
> 
> 3) layout
> ---------
> 
> The layout previously proposed on this list was a solution to the speed
> problem but I couldn't adapt it to the depth needs identified in the
> rest of the goals.
> 
> So, I resurrected my rusty web design skills and came up with the layout
> you find attached. I've tested it on IE 5.5, NS 4.78 and Moz 0.9.5 on
> win2k. 
> 
> Feedback, suggestions and criticisms are appreciated.
> 
> 4) CVS location and mail list discussions
> -----------------------------------------
> 
> Just like Gump which is not a subproject on its own, Forrest doesn't
> deserve that status neither as long as it remains a single-man show (and
> my experience tells me it will very likely remain so if the above goals
> are met)
> 
> At the same time, just like Gump, it requires a CVS space.
> 
> Possible places are:
> 
>  1) xml-site
>  2) xml-forrest
>  3) xml-site2
> 
> for mail list discussions, solutions are:
> 
>  1) general@xml.apache.org
>  2) cocoon-dev@xml.apache.org
>  3) site@xml.apache.org
>  4) forrest@xml.apache.org

Let's do this in xml-site or at xml-site2.   

> Please, add your comments/suggestions and your votes where a decision is
> required.
> 
> Thank you.
> 
> -- 
> Stefano Mazzocchi      One must still have chaos in oneself to be
>                           able to give birth to a dancing star.
> <stefano@apache.org>                             Friedrich Nietzsche
> --------------------------------------------------------------------
> ----
> 

> ---------------------------------------------------------------------
> In case of troubles, e-mail:     webmaster@xml.apache.org
> To unsubscribe, e-mail:          general-unsubscribe@xml.apache.org
> For additional commands, e-mail: general-help@xml.apache.org



---------------------------------------------------------------------
In case of troubles, e-mail:     webmaster@xml.apache.org
To unsubscribe, e-mail:          general-unsubscribe@xml.apache.org
For additional commands, e-mail: general-help@xml.apache.org


Mime
View raw message