tomcat-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Robert L Sowders" <>
Subject How to contribute to the docs in 7 easy steps.
Date Wed, 23 Oct 2002 09:34:35 GMT
As Craig McClanahan once said to me

"General whines about how the documentation sucks will go to /dev/null.
Specific patches to add to (or fix) the existing documentation pages are
MUCH more likely to be effective :-)."

Ok, so let's get to it.

I'm going to try to make it easy for everyone to help out with the 
documentation of Tomcat, more specifically the documentation for the 
connectors.  I was a little bewildered at how to get started.  Hopefully, 
you will be clued in after reading of this.

It's really quite simple:

Here's what you'll need:
A recent version of Ant
The source code for the connectors from cvs
Any ascii text editor.

STEP 1.  Install Ant, and setup your 
environment variables for ANT_HOME and the path to Ant/bin so you can run 
ant from the command line.

STEP 2.  Get the sources for jakarta-tomcat-connectors from CVS.  If 
you'll be editing from a windows platform you will need a cvs client. 
Install CYG-WIN and during the install elect to 
install the cvs client.  You can also use jEdit,, 
which also includes a CVS plug-in.  Unix people should install the CVS 
client of their choice.  Run the following from a command prompt window.

Change directory to the location where you want to store your CVS 
        cd c:\
Run the following command to download the source for the first time.

        cvs -d login

Type in the password for anonymous access at the next prompt.


When the prompt comes back, run the following to download the sources.

        cvs -d checkout 

You should now be watching all the downloads come in.

STEP 3.  Set up your build environment.  Change to the directory you 
downloaded the source into.  Now cd to the jk directory.  Copy the file to and edit it for the 
locations of your installed Tomcat.  My only edits were:

Optional:  cd into the xdocs directory and copy the supplied file to  I would not edit this 

STEP 4.  Test the build for the docs.  On a windows machine, open a 
command prompt window in the jk directory of the CVS repository you made. 
On a Unix machine just cd into the directory that contains your CVS 
repository then cd into the jk directory.  Now type in the following 

        ant docs
You should see build lines start flowing.  Notice that all the files are 
sent to a new directory under jk called build/doc.  Open the doc directory 
and you should see all the files translated into html.

STEP 5.  Find a typo in the documentation to edit, pay attention to what 
file your actually looking at.  Cd back into the xdocs directory and after 
you have found your intended target, open up the xml file in a text 
editor.  Correct the typo then from a command prompt window in the jk 
directory run:

        ant clean
        ant docs

Now check how your edit looks in the build/docs directory by opening it in 
your web browser.

STEP 6.  Create a unified diff of the corrections you just made.  Cd into 
the directory containing the xml file you edited and run the following 

        cvs diff -u name_of_the_file_you_edited >> patch.txt
STEP 7.  Now to get it, (or yourself :-), committed.  Patches to the 
documentation are handled just like a bug report.  Send it to and include a good one line subject. At 
the web site paste your patch into the web form and don't forget to 
describe what it is your patch is for.  Sooner or later a someone with 
commit privileges will commit your change.  They are pretty good about 
doing this. 

That's all there is to it.  It's easy once you know how.  Now you know 

General notes about using CVS.

It is much easier to use CVS if you setup a CVSROOT environment variable. 
After setting up the CVSROOT variable you don't have to type in those long 
command lines to use CVS. 

A Unix bash user could do the following:
        export CVSROOT

A windows user would set a system environment variable for CVSROOT to the 
same value as above
Now all you would have to do is open a command prompt window or bash 
window and cd to the directory where you have or want your repository and 

        cvs login

then at the password prompt


To check out the sources for the first time:

        cvs checkout jakarta-tomcat-connectors

After you have checked out the connectors source the first time you will 
periodically need to update your repository.  Do this especially before 
you edit your files to prevent conflicts.  Make sure you are above the 
directory of your repository, then you can run the following cvs command.

        cvs update -dP jakarta-tomcat-connectors

Pay attention to the terminal window during the update. 

Lines beginning with a P mean the local copy was patched to update it to 
the current version in the master repository. 

Lines beginning with a M mean your local copy is different from the master 
copy, and the changes were successfully merged into your copy. 

Lines beginning with a C mean there was a conflict in merging the changes 
and you need to review the file and merge the changes manually.  Do a 
search for >>>> and merge the changes by hand.

That's about it.  Now you have no excuse.  If you really think the 
documentation needs help, then do something about it.


To unsubscribe, e-mail:   <>
For additional commands, e-mail: <>

View raw message