tomcat-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Punky Tse" <punky...@yahoo.com>
Subject Re: Table of Contents
Date Tue, 10 Jul 2001 01:53:38 GMT
Alex,

Please see my comment below:

1) The details of the TOC looks better than my version.

2) How about moving Developing Interceptors, Valves and Connectors, and
Using Tomcat Utility Classes to a seperate Developer Guide?  They are only
useful for real hackers.

3) How about putting all the installation and configuration of Tomcat
standalone first, and then followed by some chapters (advanced topics) about
Running Tomcat behind web servers?

4) Overall, I prefer to have all the basics chapters comes first, and then
some advanced topices listed in the later chapter.  This is what I found
from most of user manuals in my bookshelf.

5) About Copyright and Authorship.  It is fine for you to hold the
copyright.  But if somebody modified your TOC and send back to you, and you
accepted these changes.  How about identity of authorship of this document?

Punky


----- Original Message -----
From: "Alex Chaffee" <guru@stinky.com>
To: <tomcat-dev@jakarta.apache.org>
Cc: <alex@jguru.com>; <imf@neo.com>; <mslinn@mslinn.com>
Sent: Saturday, July 07, 2001 1:02 AM
Subject: DOC: Table of Contents


> Here's my current Table of Contents. As I said in an earlier message,
>
>  > I'd like to organize this TOC as a little more abstract than a simple
> table of contents. Each section should be organized to contain not just
> our original documents, but also a list of other resources on that
> topic. This will be a good way to get a useful set of docs up and
> running quickly. In fact, I imagine that many of the chapters will
> remain unwritten for a while, since there may be existing documents, or
> articles, or FAQ entries that cover the topic (even if not exclusively).
>
>  > In short, I propose that writing a TOC is a very important first
> step, and that this TOC should live a life of its own as a standalone
> document, containing links to other docs, and meta-information like
> links to other docs as well.
>
> I used emacs outline mode, which uses * to represent header level, so we
> don't have to renumber all the chapters all the time.
>   * = part
>   ** = chapter
>   *** = section
>
> For the Security chapter, I took the outline Antony wrote. I trust the
> current discussion thread will improve upon it.
>
> Since there's a lot of detail in here, here's the outline to one level
> of headers only:
>
> * Part I: Installation Guide
> ** Overview
> ** Pre-Installation
> ** Installation Standalone
> ** Server lifecycle management
> ** Secure Server (SSL)
> ** Virtual Hosts
> ** Installing Jasper (JSP)
> ** Logging
> ** Load Balancing
> * Part II: Installation Behind A Web Server
> ** Installation Behind a Web Server Overview
> ** Behind Apache
> ** Behind IIS
> ** Behind iPlanet
> * Part III: Deploying Web Applications in Tomcat
> ** Web Application Primer
> ** The Web application directory structure
> ** Deploying your Web applications
> ** Reloading
> ** Aliasing and redirecting
> ** Security
> ** Developing with Jasper (JSP)
> * Part IV: Performance
> ** Performance Tuning Web Applications
> ** Tuning the server
> ** Load Balancing
> * Part V: Tomcat Development
> ** Tomcat 3.x vs 4.x
> ** Overview of Tomcat code base
> ** Downloading the source code
> ** Building the source code
> ** Bugs
> ** Developing Interceptors (Tomcat 3.x)
> ** Developing Valves (Tomcat 4.x)
> ** Developing Connectors
> ** Using Tomcat Utility Classes
> * Appendices
> ** server.xml documentation
> ** web.xml documentation
> ** Glossary
> ** Resources
>
> A note on copyright: I'm claiming copyright for this document, since I
> may use parts of it to write articles or books, and I haven't done the
> research on what it means to post text (as opposed to code) into an
> Apache project. I'd contribute it explicitly as open source if I were
> sure I'd keep my rights to use it too. If anyone can enlighten me on
> this topic, please respond with a separate subject line (like
> "Copyrights") so we can keep discussions of copyright separate from
> discussions of the table of contents itself. The copyright will not
> prevent other Apache contributors from using or editing it or adding it
> to the code base -- that is, I want to preserve *my* right to use it in
> a non-Apache context, but also to grant Apache the right to use it too.
> If that's even possible. I'm confused.
>
> Anyway, here it is :-)
>
> Next steps:
> comments & revisions ad infinitum
> flag each section as applicable to 3.x, 4.x, or both
> add links to existing documents
> volunteer authors to write chapters/sections
>
> --
> Alex Chaffee                       mailto:alex@jguru.com
> jGuru - Java News and FAQs         http://www.jguru.com/alex/
> Creator of Gamelan                 http://www.gamelan.com/
> Founder of Purple Technology       http://www.purpletech.com/
> Curator of Stinky Art Collective   http://www.stinky.com/
>


----------------------------------------------------------------------------
----


> This document Copyright (C) 2001 by Alex Chaffee.  All rights
> reserved.  Permission is granted for the Apache project to incorporate
> it in whole or in part into their documentation.
>
>
> * Editorial Notes
>
> The "installation" unit is the most crucial. I think there should be a
> chapter or series of chapters on installing Tomcat standalone, that
> covers *everything* or almost everything start-to-finish. Then we also
> need separate chapters for installing behind each Web server. Then
> come chapters on administration and advanced configuration issues.
>
> We should make it clear that it is *HIGHLY* recommended to install
> standalone first. This will help the users debug their setups. It will
> also help us organize the docs. Each "behind" chapter will assume
> you've read the "standalone" chapter(s).
>
> http://jakarta.apache.org/tomcat/tomcat-3.3-doc/appdev/deployment.html
> is very well organized and would be great as a "Web Application
> Developer's Guide"
>
>
>
> * Part I: Installation Guide
>
> Covers installing Tomcat.  Separate instructions (sidebars?) for
> Windows 9x, Windows NT, Linux, Solaris, Other Unixes, Mac OS.
> Separate instructions for standalone vs. plug-in.  Separate
> instructions for Tomcat 3.x vs 4.x.
>
>
> ** Overview
>
> Big picture, 30,000 foot view.
>
> *** Diagram of all the parts of Tomcat
> **** Servlet Container
> ***** Directories
> ***** Config files
> ***** Web apps
> ***** Connectors
>
> *** Basic terms
> **** servlet
> **** web app
> **** see glossary [in fact, maybe this whole section should be removed
> in favor of the appendix]
>
>
> ** Pre-Installation
>
> Covers what to do before you "actually" install Tomcat.
>
> *** DIAGRAM: Flowchart of installation steps
> **** Choose OS
> **** Install Java
> **** Download Tomcat
> **** etc.
>
> *** HIGHLY recommended to install standalone first
>
> We should make it clear that it is *HIGHLY* recommended to install
> standalone first. This will help the users debug their setups. It will
> also help us organize the docs. Each "behind" chapter will assume
> you've read the "standalone" chapter(s).
>
> *** Choosing an OS
>
> Religious rants here :-)
>
> *** Installing Java
>
> How to install a JDK or JRE on your target platform.  It might make
> sense to break this out into separate chapters per platform, if it
> turns out a lot of the information is different.
>
> **** Downloading JDK
> **** Setting environment variables
> **** Setting class path (see Tomcat Classpath section)
> **** OS Issues
>
> *** Choosing a Tomcat Version
> **** 3.x vs. 4.x
>     - see also "Development:3.x vs 4.x" chapter
> **** 3.1 vs 3.2 vs 3.3
> **** 4.0 status
>
> *** Downloading Tomcat
> **** Binary distribution
> **** Source distribution
> **** CVS (see "developing" section)
>
>
> ** Installation Standalone
>
> This section covers the basic steps of installing Tomcat as a
> standalone application.  It is the core of the Installation Guide.
> Everyone who reads the later chapters is expected to have read these,
> and to have a working standalone install before going and installing
> behind the Web server.
>
> *** HIGHLY recommended to install standalone first
>
> *** Basic procedure
>
> *** Windows Issues
> **** Where to place TOMCAT_HOME?
> **** Port 80
> **** Admin user
> **** Running as a service
>
> *** Unix Issues
> **** Where to place TOMCAT_HOME?
> **** Port 80
> **** Redirector
> **** root user
> **** Running as a daemon
>
> *** Testing your basic standalone installation
> **** The Example Context (Webapp)
> **** telnet from same machine
> **** web browser
>
>
> ** Server lifecycle management
>
> Maybe this should go in a later Admin guide, but it's important to get
> the users comfortable with the use of the scripts and stuff early
> on. Maybe here we just cover starting and stopping, and have a more
> thorough chapter later on.
>
> *** Starting Tomcat
> *** Stopping Tomcat
> *** Checking if Tomcat is running
> *** Automatically restarting [=reloading?]
> *** [Log rotation? See "logging" chapter]
>
> *** The Admin Context (Costin?)
> *** The Tomcat Manager Application (Craig?)
>
>
> ** Secure Server (SSL)
>
> Covers how to get Tomcat up and running with SSL.  Since this is in an
> Installation guide, it does not cover other aspects of security (but
> refers to the relevant chapter in the Admin Guide)
>
> *** Overview of SSL - what it is and isn't
> *** Acquiring a key
> *** Where to install your key
> *** Pointers to other chapters
>
>
> ** Virtual Hosts
>
> So far, the installation examples have covered the simple case where
> you are using a single Tomcat server to handle requests for a single
> domain.  In this chapter, we cover using Tomcat to handle requests for
> multiple domains.  Note that we're still talking about standalone
> Tomcat; getting VHosts to work behind other servers is a topic for
> later on.
>
> *** Context-based
>
> *** Multiple roots
>
> *** Reference to Virtual Hosts in "Behind" chapters
> **** Apache
> **** IIS
> **** iPlanet
>
>
> ** Installing Jasper (JSP)
>
> *** JSP Primer
> *** Enabling the Jasper servlet
> *** Disabling the Jasper servlet
> *** Precompiling JSPs
> *** Where are JSP files stored
> **** source
> **** compiled .java
> **** compiled .class
> *** Choosing a compiler
> *** Debugging a JSP
>
>
> ** Logging
>
> Maybe this should go in a later Admin Guide, but it's important to at
> least mention where the logs are during the installation phase.
>
> *** Log management
> *** System.out and System.err
> *** Server/JSP log output
> *** Log file rotation
> *** Custom logging
>
>
> ** Load Balancing
>
> Covers briefly what Load Balancing is.  Mentions that as presently
> written, Tomcat does not support load balancing in standalone mode.
> Refers to individual web server chapters and to Performance
> chapter. Basically this is a placeholder for references to other parts
> (until TC standalone supports load balancing).
>
>
> * Part II: Installation Behind A Web Server
>
> This unit builds on the standalone unit. Readers are assumed to have
> read the relevant chapters in the standalone unit, and to have a
> -working- standalone installation. The structure of these chapters
> should follow the structure of the standalone unit -- that is, just
> like the standalone unit had a chapter on basic installation, SSL,
> virtual hosts, JSP, each Web server-based chapter will have a section
> on basic installation, SSL, virtual hosts, JSP, in that order. This
> will allow people to "flip back and forth" or at least to get less
> confused about what information is Tomcat-general and which is
> Apache-specific.
>
> ** Installation Behind a Web Server Overview
>
> *** Behind mode overview
> *** Connector protocols
> **** AJP12
> **** AJP13
> **** AJP14
>
> ** Behind Apache
>
> *** basic installation
> *** Choosing a mod
> **** mod_jserv
> **** mod_jk
> **** mod_webapp
> *** httpd.conf-auto
> **** different versions' idiosyncracies
> *** Enabling SSL
> *** Virtual Hosts
> *** JSP integration
> *** Logging
> *** Authentication
>
> ** Behind IIS
>
> *** Installation steps
> *** Enabling SSL
> *** Virtual Hosts
> *** JSP integration
> *** Logging
> *** Authentication
>
> ** Behind iPlanet
>
>
>
> * Part III: Deploying Web Applications in Tomcat
>
> Covers developing and deploying Web Applications inside Tomcat.  This
> follows a fairly clean break between "installing tomcat" and
> "deploying applications" -- even though there's a lot of configuration
> in both steps, you can separate problems by "my server isn't running
> at all" vs. "my server is running but my app doesn't work."
>
> It may be better to name this the "Administrator's Guide" which would
> better suit discussions of things like security and lifecycle which
> aren't really about *deploying* per se.  But if so, the word
> "deploying" should appear in appropriate chapter titles.
>
> ** Web Application Primer
>
> *** See Web Application Developer's Guide
> *** What's a servlet
> *** What's a JSP
> *** What's a webapp
>
> ** The Web application directory structure
>
> *** Context root
> *** The WEB-INF directory
> *** WEB-INF configuration files
> *** WEB-INF/servlets
> *** WEB-INF/classes
> *** WEB-INF/lib
> *** WAR Files
> **** Using the jar tool to make a WAR file
> **** Where to place the WAR file
>
> ** Deploying your Web applications
> *** Telling Tomcat where your web applications are
> **** webapps directory
>     - redeploying gotcha
> **** WAR files
> **** unpacked webapps
>
> ** Reloading
>
> *** Reloading webapps
> *** Reloading servlets
> *** Reloading classes
> *** Restarting the server
>
> ** Aliasing and redirecting
>
> *** Inside Tomcat
> **** Webapp contexts
> **** Using web.xml
> *** Inside Web Server
> **** Apache
> **** IIS
> **** Others
> *** Examples
> **** (several examples)
> *** See also Virtual Hosts chapter
>
> ** Security
>
> *** Concepts - Explanation of J2EE and Java 2 security models
>
> *** Transport-Level Security
> **** SSL
>
> *** Authentication
> **** Authentication with Realms
> ***** Simple realm
> ***** JDBC Realm
> ***** Custom realms
>
> *** Authorization
> **** J2EE role based
>
> In particular, it should try to explain in simpler terms than the API
> spec how J2EE roles are designed to work, covering the mapping from
> developer roles to deployment roles.
>
> *** Java 2 security policy
>
> ** Developing with Jasper (JSP)
>
> *** JSP Overview
> *** Some JSP Gotchas
> *** Using JSP Explorer
> *** JSP Error Tracking
>
>
> * Part IV: Performance
>
> ** Performance Tuning Web Applications
>
> ** Tuning the server
> *** Thread pool size
>
> ** Load Balancing
>
>
> * Part V: Tomcat Development
>
> Covers actually writing code for the Tomcat code base.
>
> ** Tomcat 3.x vs 4.x
>
> ** Overview of Tomcat code base
>
> ** Downloading the source code
>
> *** Using CVS
> *** Downloading
>
> ** Building the source code
> *** Using Ant
> *** Contents of "build" directory
> *** Using Ant to build your own Web apps
> [misplaced? should go in Developing Web Apps guide?]
>
> ** Bugs
> *** Submitting Bugs
> *** The Bug Database(s)
> *** Fixing Bugs
>
> ** Developing Interceptors (Tomcat 3.x)
>
> ** Developing Valves (Tomcat 4.x)
>
> ** Developing Connectors
>
> ***  mod_jserv
> ***  mod_jk
> ***  mod_webapp
>
> ** Using Tomcat Utility Classes
> *** What the Apache license means to you
>
>
> * Appendices
>
> ** server.xml documentation
>
> ** web.xml documentation
>
> ** Glossary
>
> ** Resources
> *** Mailing Lists
> *** FAQs and online documentation
> *** Other Web Sites
>
>
> ----
>
>
> ----
>


Mime
View raw message