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, http://jakarta.apache.org/builds/jakarta-ant/release/ 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 http://www.cygwin.com/ and during the install elect to install the cvs client. You can also use jEdit, http://www.jedit.org/, 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 repository. cd c:\ Run the following command to download the source for the first time. cvs -d :pserver:[EMAIL PROTECTED]:/home/cvspublic login Type in the password for anonymous access at the next prompt. anoncvs When the prompt comes back, run the following to download the sources. cvs -d :pserver:[EMAIL PROTECTED]:/home/cvspublic checkout jakarta-tomcat-connectors 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 build.properties.sample file to build.properties and edit it for the locations of your installed Tomcat. My only edits were: tomcat41.home=c:/Tomcat Optional: cd into the xdocs directory and copy the supplied build.properties.sample file to build.properties. I would not edit this file. 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 command: 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 command. 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 http://nagoya.apache.org/bugzilla/ 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 how. 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: CVSROOT=:pserver:[EMAIL PROTECTED]:/home/cvspublic 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 then: cvs login then at the password prompt anoncvs 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. rls -- To unsubscribe, e-mail: <mailto:tomcat-user-unsubscribe@;jakarta.apache.org> For additional commands, e-mail: <mailto:tomcat-user-help@;jakarta.apache.org>
