incubator-general mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Geir Magnusson Jr." <ge...@apache.org>
Subject Re: [RT] Super Simple Site Generation Tool
Date Thu, 29 Dec 2005 13:23:48 GMT
I am +1 for dumping Forrest.  I never grok why something so simple as  
our static website needs something so complicated to build it.

What's wrong with the xdoc/Anakia approach?  If the problem is  
validation, that's trivial - we can easily create an dtd or xsd (if  
you don't want humans to be able to read the schema) to fix that, and  
while I admit that Anakia format doc is a bear to read, you can  
either do it via DVSL (another Vel based approach) or just plain  
XSLT.  And honestly, besides poking in the ApacheCon logo at the  
appropriate times of the year, who ever edits the Anakia doc?

I've put in a xdoc/anakia approach for Geronimo, JDO, Harmony and  
Agila, and it's been simple and mindless for anyone who wants to  
update or add to the site.

The other tools were too de-motivating, and kept people from updating  
the sites.

I'd rather err in having less-than-perfect technology with the  
benefit of trivial addition/edit/update.  Granted, it requires having  
Java running, but that's not so onerous in this day and age.

geir

On Dec 27, 2005, at 9:02 AM, Leo Simons wrote:

> Hi gang,
>
> It pains me to say this (Forrest is a cool project and I
> consider at least some of its active developers and community
> members my friends) but we've muddled around long enough.
>
> I think that, for the incubator website, Apache Forrest
>
>   * is too unstable as a codebase
>   * is way too complex
>   * has too many features we don't need and solves
>     too many problems we don't have
>   * has a learning curve that is too big
>   * does not work well with the SVN-based publishing
>     process we want to use
>   * is not well-understood by enough of the current
>     Incubator volunteers
>   * has caused frustration for too many of the current
>     Incubator volunteers
>
> I think this needs solving. I think this needs solving in
> general, not just for the Incubator (I have the exact same
> problem over at Gump, which also has a horrendously outdated
> website which also uses Apache Forrest).
>
> == Use case ==
>
> In particular, the use case we are looking at can be codified
> in the following workflow:
>
>   # 1) figure out how to edit docs...
>   curl http://svn.../site/README | less
>
>   # 2) get stuff from SVN
>   svn co http://.../site
>   cd site
>
>   # 3) edit docs
>   $EDITOR x/y/z/foo.xml
>
>   # 4) validate edit, generate results
>   ./build # must work on windows, linux, os x, solaris, ...
>
>   # 5) check results locally
>   svn diff
>   mozilla-firefox build/x/y/z/foo.html
>
>   # 6) commit
>   svn commit -m "foo.xml: fix typo. Its 'spelling', not 'speling'."
>
>   # 7) validate commit
>   mozilla-firefox http://staging.incubator.apache.org/x/y/z/foo.html
>
>   # 8) x hours later...
>   mozilla-firefox http://incubator.apache.org/x/y/z/foo.html
>
> == Requirements ==
>
> Now, steps 1-7 should be possible in about 5 minutes (provided you're
> on broadband network and a 600mhz/128mb/5400rpm machine. 5 minutes  
> includes
> reading the documentation and the like), and about 10 seconds for  
> someone
> who already knows how the tool works and has the checkout on his  
> machine
> already.
>
> Step 4 should be so quick and natural and trustable that steps 5,7  
> and 8
> are not really neccessary once you've used the tool a few times.
>
> The produced HTML should be simple, clean, valid XHTML 1.1 strict,  
> with
> navigational stuff similar to that available on other parts of
> www.apache.org. This output should be customizable in a manner that's
> similarly simple as the above use case (for eg adding banner logos or
> updating a project logo), though its allowed to be a little harder (eg
> having to learn some template language is just fine).
>
> The source format should be simple, clean, and simple to grok  
> (within the
> basic 5 minute period mentioned above) for anyone who knows how to  
> write
> basic HTML (eg <b>, <em>, <h1>). The translation from the source to
 
> the
> produced HTML should be obvious and without surprises.
>
> There should be a simple file (probably XML) for specifying  
> navigational
> elements where again the transformation from source to html is so  
> obvious
> that anyone who has ever edited XML doesn't need to RTFM.
>
> == Available tools ==
>
> None of the other generally available tools satisfy all the above
> requirements at the moment.
>
>  * forrest
>    * requires installing forrest, which takes way more than 5 mins  
> in and
>      of itself
>    * basically it fails many of the use case basics (too heavyweight,
>      takes more than 3 minutes to learn, input->output transforms too
>      complex), which is probably because I wrote the use case to  
> contrast
>      with the current forrest process
>    * the transformation is not predictable enough
>
>  * maven
>    * requires installing maven, which takes 5 mins in and of itself
>      * maven 1 not easy enough to install into svn self-contained
>        * maven 1Â will essentially be "dead" as everyone migrates to
>          maven 2
>      * don't know about maven 2 yet, but it doesn't have a very widely
>        installed base yet, since it was just released
>    * the source xdoc format is not simple or clean enough
>    * the validation step is not complete enough
>    * the transformation is not predictable enough
>    * changing the stylesheet is not simple enough
>      * if maven is upgraded your entire look and feel may change as
>        well as other things (eg the xdoc plugin is not stable enough)
>
>  * anakia
>    * the source xdoc format is not simple or clean enough
>    * the validation step is not complete enough
>    * the transformation is not predictable enough
>    * managing navigational elements is not simple or clean enough
>
>  * others
>    * no doubt there are many that could be used
>
> == Possible steps forward? ==
>
> Given the above, fixing forrest seems like a lot of work. I think  
> its a
> fundamentally bad fit, being built on top of many many layers of  
> java code
> and several frameworks makes it too heavy by definition. However,  
> since
> it is very easy to customize forrest to output the source format for
> another tool, and we have ready access to forrest experts,  
> migrating away
> from forrest is probably not very painful (I think it involves  
> writing some
> XSLT). As long as the source format stays XML, moving back to  
> forrest later
> is also not painful. Standards-based. Lack of lock-in. Good.
>
> Moving back to anakia is possible, but satisfying the validation  
> requirement
> is always going to be hard because of its use of velocity rather  
> than "real"
> XML parsing.
>
> Moving forward to maven 2 is probably possible but I think the same  
> argument
> against anakia still applies to its document generation process.  
> One big
> advantage with maven is that its easy to also automate many of the  
> other bits
> of workflow, eg doing things like the 'svn commit' too.
>
> Step 7 and 8 depend on what the site-dev at apache.org people come  
> up with;
> right now this is more like having to do an "svn up" remotely,  
> setting up
> a HTTP proxy, etc, or skip 7, and just do 8, with x == 2. But  
> that'll be
> fixed. Lots of plans made, apparently. Haven't been able to figure  
> out what
> the status is right now (seems there's no code for steps 1-6 at the  
> moment),
> but its definitely going to be compatible with any tool satisfying  
> the above
> use case. See:
>
>   http://people.apache.org/~rgardler/site-dev/Site-Build.html
>
> The site-dev people have been working on some other kinds of tools,  
> including
> one that uses Perl+XSL, which shows just how simple "step 4" at its  
> core really
> is:
>
>   #!/usr/local/bin/perl
>
>   use strict;
>
>   my $xdocdir = "xdoc";
>   my $htmldir = "html";
>   my $xslfn = "xsl/xdoc2html.xsl";
>
>   opendir(XDOC, $xdocdir) || die("Couldn't open directory $rdfdir");
>   while (my $r = readdir(XDOC)) {
>       next unless $r =~ /^[a-zA-Z].*\.xml$/;
>       my $infn = "$xdocdir/$r";
>       print "Processing $infn\n";
>       my $outfn = "$htmldir/$r";
>       $outfn =~ s/\.xml$/\.html/;
>       `xsltproc $xslfn $infn > $outfn`;
>   }
>   closedir(RDF);
>
> Some things to notice...
>
>  * needs xsltproc to be installed
>  * error reporting not so intuitive (just the output from xsltproc)
>  * no clear abort on error
>  * doesn't walk directories (I think perls readdir reads the current
>    directory only)
>  * specification of navigational elements not easy enough (eg no
>    maven-style site.xml)
> (* also note some of the use case being addressed depends on the XSLT
>    file)
>
> But these kinds of things aren't exactly hard to address. So I think
> I'm going to spend a day or maybe two writing a dedicated script that
> does the above, and a little more, and then once done I'll spec up
> what forrest should be spitting out, and ask for a volunteer to write
> the neccessary stylesheets and do the conversion.
>
> The code for this is probably going to end up somewhere inside
>
>   https://svn.apache.org/repos/asf/infrastructure/site-tools/trunk
>
> Unless there's lots of discussion resulting from the above on site-dev
> (there seems to be a lot of history to this topic), then it'll end up
> somewhere else.
>
> Its probably going to be written in python and will probably use  
> minidom
> and the Kid template language. Its probably going to have a source XML
> format that is a subset of XHTML 1.1 and specified as a DTD file. I  
> think
> I'll do away with a "site.xml" or anything like that and just specify
> the menu as an XHTML snippet, since I've never ever seen site.xml  
> files
> used for anything but generating websites. I'll try and write the  
> critter
> so that its easily thrown away and replaced by something written in  
> Perl
> or Java.
>
> I think I'll call it xdok.
>
> I'll send another email once I have something working and ready for a
> demo.
>
> From there, we'll see where it goes.
>
> - LSD
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
> For additional commands, e-mail: general-help@incubator.apache.org
>

-- 
Geir Magnusson Jr                                  +1-203-665-6437
geirm@apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org


Mime
View raw message