You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cactus-dev@jakarta.apache.org by IAS <ca...@iasandcb.pe.kr> on 2002/10/25 09:44:19 UTC
Recent trend in Apache documentation methodology
Now Apache has two major sectors about Java: XML and Jakarta. Actually
the two sectors have interacted a lot, and as its result, there have
been also several various ideas for documentation.
Originally XML brought out stylebook as an ant task, which currently
seems obsolete somehow. For its alternative, Velocity Anakia appeared.
It utilizes Velocity template technology with xml documents, however,
does not go with XSLT.
Velocity DVSL is slightly different from Anakia in this sense. As you
see the initials as Declarative XML Transformation and Templating, DVSL
"steals" some features of XSLT, but "still" sticks to Velocity template
language.
Meanwhile, XML Forrest came up as a sort of "ASF" representative
documentation system. Forrest is purely based on XML technologies such
as XML itself, XSLT, DTD, and possibly even XML Schema some day. Its
range is also remarkable: Ant, Centipede, Cocoon, Gump, Scarab, Slide,
and etc... All the names are on the page of the Forrest Primer.
At this very moment, I suggest that we be as considerate as possible for
next generation documentation system for the cactus project. IMHO,
stylebook is naturally connected to Forrest, so it might be smooth and
promising to choose Forrest.
Here's a summarized table of each technology:
document template (relative) stability
Stylebook XML XSLT (literally) too stable
Anakia XML Velocity stable
DVSL XML Velocity CVS stage
Forrest XML XSLT CVS stage
Thank everyone in advance.
IAS
Independent Java Technology Evangelist
http://www.iasandcb.pe.kr
Jakarta Seoul Project Coordinator
http://jakarta.apache-korea.org
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
Re: Recent trend in Apache documentation methodology
Posted by Christopher Lenz <cm...@gmx.de>.
IAS wrote:
> Now Apache has two major sectors about Java: XML and Jakarta. Actually
> the two sectors have interacted a lot, and as its result, there have
> been also several various ideas for documentation.
>
> Originally XML brought out stylebook as an ant task, which currently
> seems obsolete somehow. For its alternative, Velocity Anakia appeared.
> It utilizes Velocity template technology with xml documents, however,
> does not go with XSLT.
>
> Velocity DVSL is slightly different from Anakia in this sense. As you
> see the initials as Declarative XML Transformation and Templating, DVSL
> "steals" some features of XSLT, but "still" sticks to Velocity template
> language.
>
> Meanwhile, XML Forrest came up as a sort of "ASF" representative
> documentation system. Forrest is purely based on XML technologies such
> as XML itself, XSLT, DTD, and possibly even XML Schema some day. Its
> range is also remarkable: Ant, Centipede, Cocoon, Gump, Scarab, Slide,
> and etc... All the names are on the page of the Forrest Primer.
>
> At this very moment, I suggest that we be as considerate as possible for
> next generation documentation system for the cactus project. IMHO,
> stylebook is naturally connected to Forrest, so it might be smooth and
> promising to choose Forrest.
>
> Here's a summarized table of each technology:
> document template (relative) stability
> Stylebook XML XSLT (literally) too stable
> Anakia XML Velocity stable
> DVSL XML Velocity CVS stage
> Forrest XML XSLT CVS stage
I would like to add an item to that list: the Ant <style>/<xslt> task.
The Slide project, for example, uses that, but also Struts, IIRC. It's
pretty much a "no-dependancy" solution, and it works if you don't
want/need to get fancy.
IMHO, both Maven and Forrest are looking promising (although they have
different focusses of course), but they are also both pretty much moving
targets ATM. I *personally* wouldn't move a serious project to either
technology just now.
The topic of XSLT vs. DVLS/Anakia has often enough been a trigger for
flame wars. IMHO, as complex as XSLT might be considered by some, it's
usage is far more common than usage of DVSL. In consequence, more people
will be able to contribute to the stylesheets if XSLT is used, at least
in theory (personally, I'm not going to learn DVSL any time soon ;-) ).
However, this discussion doesn't actually matter, as the stylesheets
would actually come with the documentation system, and wouldn't need to
be touched by the individual projects (in an ideal world, that is).
--
Christopher Lenz
/=/ cmlenz at gmx.de
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>
RE: Recent trend in Apache documentation methodology
Posted by Vincent Massol <vm...@octo.com>.
Hi IAS,
Thanks for this nice summary email! See my comments below.
> -----Original Message-----
> From: IAS [mailto:cactus@iasandcb.pe.kr]
> Sent: 25 October 2002 08:44
> To: 'Cactus Developers List'
> Subject: Recent trend in Apache documentation methodology
>
> Now Apache has two major sectors about Java: XML and Jakarta. Actually
> the two sectors have interacted a lot, and as its result, there have
> been also several various ideas for documentation.
>
> Originally XML brought out stylebook as an ant task, which currently
> seems obsolete somehow. For its alternative, Velocity Anakia appeared.
> It utilizes Velocity template technology with xml documents, however,
> does not go with XSLT.
Yes and there's a reason for that: XSLT is very complex. DVSL makes it
very simple.
>
> Velocity DVSL is slightly different from Anakia in this sense. As you
> see the initials as Declarative XML Transformation and Templating,
DVSL
> "steals" some features of XSLT, but "still" sticks to Velocity
template
> language.
>
yes.
> Meanwhile, XML Forrest came up as a sort of "ASF" representative
> documentation system. Forrest is purely based on XML technologies such
> as XML itself, XSLT, DTD, and possibly even XML Schema some day. Its
> range is also remarkable: Ant, Centipede, Cocoon, Gump, Scarab, Slide,
> and etc... All the names are on the page of the Forrest Primer.
>
> At this very moment, I suggest that we be as considerate as possible
for
> next generation documentation system for the cactus project. IMHO,
> stylebook is naturally connected to Forrest, so it might be smooth and
> promising to choose Forrest.
>
> Here's a summarized table of each technology:
> document template (relative) stability
> Stylebook XML XSLT (literally) too stable
> Anakia XML Velocity stable
> DVSL XML Velocity CVS stage
I would consider DVSL to be stable. It's used in lots of places
including in Maven and I've always been very happy with it.
> Forrest XML XSLT CVS stage
>
Here's my point of view: I don't really care which technology! :-) Let
me explain it better: Cactus should choose tools that make its build
process faster. ATM we are using Ant. However, maintaining and improving
the build is costly as the Ant scripts are getting quite sophisticated.
My intent is to move to Maven as soon as I am convinced there are all
the elements in Maven for that. To that effect (and for other needs at
work) I have been helping the Maven project by slowly adding the
necessary plugins and helping drive its features.
Thus, what I would like to commit to is rather to choose the build tool
than choose the doc generation tool. ATM, Maven uses DVSL. A forrest
plugin is in the works but not yet integrated in Maven. Thus the current
logical choice for Cactus doc system is DVSL.
That said, we do not really care. What's important at this stage is to
move the xdocs from the Stylebook DTD to the site DTD (can't recall the
name). Then calling DVSL for example is just replacing the current
<stylebook> task with the <dvsl> one (and copying one site.dvsl file).
We should choose the simplest possible build as we will be moving to
Maven in due time (unless someone objects of course).
What do you think?
Thanks
-Vincent
> Thank everyone in advance.
>
> IAS
>
> Independent Java Technology Evangelist
> http://www.iasandcb.pe.kr
>
> Jakarta Seoul Project Coordinator
> http://jakarta.apache-korea.org
>
>
>
>
> --
> To unsubscribe, e-mail: <mailto:cactus-dev-
> unsubscribe@jakarta.apache.org>
> For additional commands, e-mail: <mailto:cactus-dev-
> help@jakarta.apache.org>
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>