On Sat, 7 Jul 2001, Rob S. wrote:
> Unfortunatly, I won't be able to participate much in this discussion this
> weekend since i know *0* about AWT and the Java cert (Monday morning, 9am)
> apparently thinks you should =) Sorry all...
>
> > The important issue is *not* what transformation tool is used. The
>
> Oh, by "works for Catalina" I was stating that TC4 is already using the
> tool; why not continue using it?
>
TC4 is not currently using Anakia (which is the tool I thought you were
talking about). It's using Ant's <style> tag, just like Struts
does. But, as I tried to make very clear in the CVS commits, that's just
a temporary expedient until the tool choice is made.
FWIW, I'm fine with Anakia, XSLT, Cocoon, Stylebook, Docbook, or whatever
... but IF AND ONLY IF the tags for use by the document authors are well
documented, and the page generation procedure is amenable to Ant scripting
(not a difficult problem in most cases).
> > * 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.
>
> I have a feeling that whatever is the same will be a lot of piecemeal here
> and there, excluding of course, web-app documentation. So far yourself,
> Pier, and Henri are the only three TC developers to post their position on
> that (re: inter-version relevancy). Personally, I don't think there should
> be a separate project, but I think I've already said that a few times =)
>
I thought of another reason for my preference in the shower this morning
:-). Consider that I might make a code change that also requires a change
to the corresponding docs. If the docs are in the same repository, that
can easily be done on the same commit (and it becomes obvious to everyone
when a developer makes a change that breaks the documentation, but fails
to update it :-). Having a separate docs repository means I need to do
two independent check-ins -- it's easy to forget one, and there is no
obvious link between them to remind you (for example) to back out the docs
change if you back out the code change.
On the other hand, a separate docs repository has one potential advantage
as well: we can grant CVS commit privileges on the docs to people who do
not have those privileges on the code repositories. To me, this isn't a
big deal -- if we can trust people to get the docs right, we should be
able to trust them not to screw up the code -- but it's still there.
> > * 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 :-).
>
> Someone will have to setup something that exposes the latest generated
> documentation on the Jakarta www site. It's being done already for Struts,
> so I guess that won't be a big problem.
>
It's pretty straightforward.
> > * At least two documentation webapps (developer-oriented and
> > user-oriented) would seem to be appropriate. Having more than two
>
> "developer" as in "web" or "Tomcat"? I'm not sure why separating the doc
> into two packages helps - perhaps I'm missing some obvious benefit trying to
> think at 7:15am =)
>
"Developer" in the sense of this sentence is a Tomcat
developer. "User" is the people that just want to download, install,
configure, and utilize Tomcat as a servlet container.
> - r
>
>
Craig
