On Sat, 7 Jul 2001 [EMAIL PROTECTED] wrote:
> On Fri, Jul 06, 2001 at 10:06:21PM -0700, Craig R. McClanahan wrote:
> >
> > * 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.
>
> That remains to be seen. My gut tells me the opposite. I'm thinking
> connectors, classpath issues (though some details are different with
> Catalina, a lot are the same),
Although the concepts of the issues above are similar, the details are
very different.
> web.xml docs, authentication,
These are the same because they are application-related (i.e. portable
because of the servlet spec) not Tomcat-related. In principle, anything
we write about this should apply to any servlet container.
> performance-tuning a web app...
That's a huge area, and may be somewhat ambitious. But, again, most of
this would be portable to any servlet container, not just Tomcat.
> I'd love to get your input on the
> outline I just posted if you get around to it -- tell me which
> sections are definitely different between 3 and 4.
>
Could you repost the most recent version of the proposed outline? My
delete key got a little sticky, and I accidentally deleted the most recent
version last night.
Just for interest's sake, here's the list of "user" things in Tomcat 4.0
that are new (relative to 3.2), cribbed from my JavaOne talk:
* Access logs (web-server style)
* CGI support
* Configurable realms at Engine, Host, and Context levels, including
JNDIRealm.
* Container-managed security (DIGEST and CLIENT-CERT modes,
plus single sign on support)
* "Default Context" configuration
* HTTP/1.1 support in stand-alone mode
* JNDI naming context support (including support for configuring
<env-entry> and <resource-ref> mappings, JDBC connection pooling,
and extensible object factories).
* "Manager" web app
* MOD_WEBAPP
* Request filtering valves (accept/deny based on client hostname
or IP address)
* Run directly from war file
* Server side includes (*.shtml)
* User web apps (http://www.mycompany.com/~craigmcc)
Now, picture yourself installing Tomcat 3.2 (because it's the current
production version). Do you *really* want to wade through the docs on all
of the above, which is totally irrelevant to your needs, just because we
put the docs for all versions in one file? To say nothing about all the
things that were present in 3.2 but are configured differently in 4.0 ...
> The current situation with the docs on the site for 3.2 and 3.3
> illustrate the problem with fragmenting two doc trees that are
> actually very similar.
Nearly everything important about configuring Tomcat is different
anyway. The only "common" stuff is the App Dev Guide. As has been
discussed, that probably makes sense in a common docs directory (until you
have do decide whether or not to cover both versions of the specs --
servlet 2.2/2.3 and JSP 1.1/1.2 -- in the same docs :-). But, if it's
separate, you've also got to figure out how you're going to "release" it.
> Any reorganization or new docs or error fixing
> will need to be propagated back to the 3.2 branch,
Why?
The code is in maintenance mode -- I don't see a problem with the docs
being in maintenance mode as well.
Of course, anyone who *wants* to do this is welcome to do so, but I don't
see it as a prerequisite.
> which will be a
> terror to maintain. I feel the same thing could easily happen with
> 4.0 vs 4.1 in the near future.
>
Not if we get started with a nice disciplined source directory
structure. That's why this discussion is so timely.
Not when you remember that the 4.0->4.1 changes won't be a complete
rearchitecting (at least to the extent that people listen to me :-), the
way that 3.2->3.3 turned out to be.
Not when you remember that 4.0 will go into maintenance mode when 4.1 is
released, so we can focus energies (both code and docs) on the current
version.
But 4.1 *will* be different than 4.0. So there will need to be a way
to produce the docs for 4.1 *only* -- by that time, users won't care how
4.0 worked, either.
IMHO, trying to mix docs for multiple versions in the same document set
is a receipie for disaster -- for reasons that I articulated last
night, plus the fact that people only care about the version they are
installing.
It's fine to have "comparative features" sorts of docs in some separate
(common) docs repository, along with the App Dev Guide type stuff that is
also common. But that's maybe three-to-five pages worth of stuff -- good,
comprehensive docs on something like Tomcat is going to be more in the low
hundreds of pages (depending, of course, on how fine-grained we decide to
make it), for any given version.
> > * 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 :-).
>
> +1
>
> .xml = .java, .html = .class
> ./build.sh docs would generate the html directory
>
>
> --
> Alex Chaffee mailto:[EMAIL PROTECTED]
Craig
