On Mon, 2 Jul 2001, Rob S. wrote:
> This seems to be one of the questions that comes up and never gets answered
> (re: docs, not Jon's behavior ;) I'm not sure what magical solution will
> get people to read docs. Frankly, I'd just like to get started. Anakia
> works for Jakarta,
Yep, thanks to Jon's hard work setting up jakarta-site2, a large majority
of the Jakarta web site is generated using Anakia.
> it works for Struts
Technically, it's not actually *used* by Struts -- Struts uses the Ant
<style> tag, which does an XSLT transformation.
However, the XML tags that Anakia (as used in jakarta-site2) understands
are very similar to the ones used in the Struts stylesheets -- and that is
a very important point.
==> it'll probably work for Catalina.
>
The important issue is *not* what transformation tool is used. The
important issue is on what tags you use in your docs, so that you can use
your favorite transformation tool. That's what we should agree on first,
because that is the gating factor on actually writing documentation.
> Committers, [VOTE] on this?
>
+1 on anyone willing to propose *and act on* writing docs, using some
reasonable XML format, on all interesting versions of Tomcat.
That being said, I do have a couple of thoughts on process -- but they are
just my own feelings, not mandates or requirements.
* Docs should live in the source tree of the project that they
are about. Although Henri's suggestion for jakarta-tomcat-docs
is noble, what you'll find in practice is that there is very little
documentation that is relevant across multiple versions of Tomcat.
* The files that are checked in should only be the XML sources, *not* the
generated files. This varies from what Jon set up in jakarta-site2,
based on long and drawn out earlier discussions (same issues as those
surrounding checking JAR files into CVS :-).
* Tomcat docs for a particular version should be delivered as one or more
web apps (not necessarily the root webapp as is current practice). That
way, the corresponding WAR files could be dropped into *any* container,
or opened up and read directly from the filesystem.
* At least two documentation webapps (developer-oriented and
user-oriented) would seem to be appropriate. Having more than two
will make it difficult to create reliable hyperlinks (since you don't
have any control over the context path that someone uses to deploy).
> - r
>
Craig McClanahan
