| <?xml version="1.0" encoding="UTF-8"?> |
| <document> |
| <copyright> |
| Copyright 1999-2004 The Apache Software Foundation |
| |
| Licensed under the Apache License, Version 2.0 (the "License"); |
| you may not use this file except in compliance with the License. |
| You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| </copyright> |
| <properties> |
| <title>How to Contribute to the Documentation</title> |
| <author email="rsowders@usgs.gov">Robert Sowders</author> |
| <date>$Date$</date> |
| </properties> |
| <section name="Introduction"> |
| <p> |
| This document describes how you can easily contribute to the |
| documentation. 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. This is written from a windows user perspective as I believe they |
| will most benefit from it. For people using Unix it should be easy for them to |
| apply these steps. Just substitute Unix sytax where needed. |
| </p> |
| <p> |
| The documentation is produced using xml with xsl style sheets. This |
| effectivly seperates the content of the documents from the style, so all that |
| contributers need to worry about the content. It is much easier to use than |
| html. |
| </p> |
| <p> |
| It's all really quite simple. Here is what you will need: |
| <ul> |
| <li> |
| <b>A recent version of Ant</b> |
| </li> |
| <li> |
| <b>The source code for the connectors from cvs</b> |
| </li> |
| <li> |
| <b>Any ascii text editor</b> |
| </li> |
| </ul> |
| </p> |
| </section> |
| <section name="Getting Started Step by Step"> |
| <p> |
| After you get these tools they are simple to set up. |
| </p> |
| <subsection name="STEP 1. Get Ant"> |
| <p> |
| Install <a href="http://jakarta.apache.org/ant">Ant</a>. The only advice I |
| have is to choose a simple installation path. Now set an environment variable |
| for ANT_HOME, and then add the location of the Ant/bin directory to your PATH |
| variable. Consult your Operating system documentation for information on how |
| to do this. When you are finished verify that you can run ant from the command |
| line. |
| </p> |
| <p> |
| Ant is used to build the documentation, among other things, and it must be |
| able to see a file called <b>build.xml</b>. This file is located in the |
| <b>CVS_HOME\jakarta-tomcat-connectors\jk</b> directory. In the |
| <b>build.xml</b> file there is a target named docs that will be used to build |
| the docs. |
| </p> |
| </subsection> |
| <subsection name="STEP 2. Get the sources"> |
| <p> |
| Get the sources for <a href="http://cvs.apache.org/viewcvs/jakarta-tomcat- |
| connectors/">jakarta-tomcat-connectors</a> from the CVS repository. If you'll |
| be editing from a windows platform you will need a windows cvs client. There |
| are several available. I like <a href="http://www.cygwin.com/">cygwin</a>. |
| During the install open the developer group and click on cvs. Unix users |
| should install the CVS client of their choice, if they don't already have one. |
| </p> |
| <p> |
| You are ready to download the sources now. Change directory to the |
| location where you want your repository to be, and run the following commands |
| to download the sources for the first time. For simplicity we will call this |
| your <b>CVS_HOME.</b> Mine is located in C:\build. |
| </p> |
| <p> |
| Login to the repository and then give the cvs password <b>anoncvs</b>. |
| <screen> |
| <read> </read> |
| <read>C:\build></read> |
| <read>C:\build\>cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic |
| login</read> |
| <read>cvs password: anoncvs</read> |
| <read> </read> |
| </screen> |
| </p> |
| <p> |
| When your prompt comes back you are logged in. Now run the following |
| command to <b>checkout</b> the sources for the first time. You should only |
| need to do this once. |
| <screen> |
| <read> </read> |
| <read>C:\build\>cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic checkout |
| jakarta-tomcat-connectors</read> |
| <read> </read> |
| </screen> |
| </p> |
| <p> |
| You should now be watching all the downloads come in. Now that you have |
| the sources on your machine the hard part if over. From now on, to update your |
| sources all you have to do is cd into any directory in your repository and run |
| cvs update |
| <screen> |
| <note> To update your xdocs directory simply cd into the xdocs directory |
| and:</note> |
| <read>C:\build\jakarta-tomcat-connectors\jk\>cd xdocs</read> |
| <read>C:\build\jakarta-tomcat-connectors\jk\xdocs\>cvs update -dP</read> |
| </screen> |
| </p> |
| </subsection> |
| <subsection name="STEP 3. Test your build environment"> |
| <p> |
| Open a command prompt window and cd to the directory where you downloaded |
| the source. Now cd into the jk directory so <b>Ant</b> can see the |
| <b>build.xml</b> file and, from a command prompt, run the following: |
| <screen> |
| <read> </read> |
| <read>C:\build\jakarta-tomcat-connectors>cd jk</read> |
| <read>C:\build\jakarta-tomcat-connectors\jk>ant docs</read> |
| <read> </read> |
| </screen> |
| </p>. |
| <p> |
| You should see the ant compiler messages scrolling by rapidly and then stop |
| with the following: |
| <screen> |
| <read>[style] Transforming into C:\build\jakarta-tomcat- |
| connectors\jk\build\docs></read> |
| <read>[style] Processing C:\build\jakarta-tomcat-connectors\jk\xdocs\faq.xml |
| to</read> |
| <read>C:\build\jakarta-tomcat-connectors\jk\build\docs\faq.html</read> |
| <read>[style] Loading stylesheet C:\build\jakarta-tomcat- |
| connectors\jk\xdocs\style.xsl</read> |
| <read>[style] Processing C:\build\jakarta-tomcat-connectors\jk\xdocs\index.xml |
| to</read> |
| <read>C:\build\jakarta-tomcat-connectors\jk\build\docs\index.html</read> |
| <read>[copy] Copying 8 files to C:\build\jakarta-tomcat- |
| connectors\jk\build\docs</read> |
| <read> </read> |
| <read>BUILD SUCCESSFUL</read> |
| <read>Total time: 10 seconds</read> |
| <read>C:\build\jakarta-tomcat-connectors\jk</read> |
| </screen> |
| </p> |
| <p> |
| All the xml files present in the xdocs directory structure were transformed |
| to html and copied to the <b>CVS_HOME\jk\docs</b> directory. Open one of the |
| html files in your browser and see how it looks. |
| </p> |
| </subsection> |
| <subsection name="STEP 4. The editing process."> |
| <p> |
| I find it easier to use two windows while doing my updates. One I call my |
| <b>build</b> window. I keep this one in the <b>CVS_HOME\jk</b> directory and I |
| only run two commands in this window: |
| <screen> |
| <read> </read> |
| <note> First I run</note> |
| <read>ant clean</read> |
| <note> Then I run</note> |
| <read>ant docs</read> |
| <read> </read> |
| </screen> |
| </p> |
| <p> |
| My second window I call my <b>edit</b> window and I keep that one in the |
| <b>CVS_HOME\jk\xdocs</b> directory where I'm doing my edits, diffs, and cvs |
| updates. |
| </p> |
| <p> |
| Before you start editing you should always update your local repository to |
| prevent conflicts. |
| <screen> |
| <note> You only need to update the xdocs directory</note> |
| <read>C:\build\jakarta-tomcat-connectors\jk>cd xdocs</read> |
| <read>C:\build\jakarta-tomcat-connectors\jk\xdocs></read> |
| <read>C:\build\jakarta-tomcat-connectors\jk\xdocs>cvs update -dP</read> |
| </screen> |
| </p> |
| <p> |
| Now that your repository is up to date you can begin editing. Find |
| something in the documentation to edit. When you find somethng remember the |
| name of the file. In your <b>edit</b> window find and edit the xml source file |
| with the same name. After you are done return to the <b>build</b> window, and |
| in the <b>CVS_HOME\jk</b> directory run: |
| <screen> |
| <read> </read> |
| <read>C:\build\jakarta-tomcat-connectors\jk> ant clean</read> |
| <read> </read> |
| </screen> |
| </p> |
| <p> |
| This will delete all the previous html files and make the area ready for |
| updated material. Now to make fresh documents that incorporate your changes |
| run: |
| <screen> |
| <read> </read> |
| <read>C:\build\jakarta-tomcat-connectors\jk\>ant docs</read> |
| <read> </read> |
| </screen> |
| </p> |
| <p> |
| Use your browser to view the edits you just made, they will be in the |
| <b>CVS_HOME\jk\build\docs</b> sub-tree. If it looks good and is ready to go, |
| all that is left to do is to create a patch and submit it. |
| </p> |
| </subsection> |
| <subsection name="STEP 5. Creating a patch and submitting it."> |
| <p> |
| From your <b>edit</b> window cd into the directory that contains the xml |
| file you are working on, and run the <b>cvs update</b> command. For example, |
| to produce a unified diff of the index.xml file and call it patch.txt, you |
| would cd into the directory containing the index.xml file and: |
| <screen> |
| <read>C:\build\jakarta-tomcat-connectors\jk\xdocs\>cvs diff -u index.xml > |
| patch.txt.</read> |
| <read> </read> |
| </screen> |
| </p> |
| <p> |
| Now that you have your patch you are ready to send it in. |
| </p> |
| <p> |
| Patches to the documentation are handled just like a bug report. You |
| should submit your patches to <a |
| href="http://nagoya.apache.org/bugzilla/">http://nagoya.apache.org/bugzilla/</a> |
| and include a good one line subject. If this is your first time to use the |
| bug database then you should read <a |
| href="http://nagoya.apache.org/bugzilla/bugwritinghelp.html">http://nagoya.apach |
| e.org/bugzilla/bugwritinghelp.html.</a> You will need to create a user |
| account. 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 review your suggestion. |
| </p> |
| </subsection> |
| </section> |
| <section name="CVS Basics"> |
| <p> |
| After you have checked out the sources the first time it is much easier to |
| use CVS. You can cd into any directory of the repository and run <b>cvs |
| update -dP</b> to get the latest sources for that directory. For editing |
| purposes you should always update your repository before you start editing to |
| reduce conflicts. |
| </p> |
| <p> |
| You will need to run <b>cvs diff</b> to generate patches for submission. |
| Again cd into the directory containing the file you are editing and run <b>cvs |
| diff -u name_of_the_file_you_edited patch.txt</b> to generate a patch for |
| submission. The <b>-u</b> is the flag for a unified diff which is the prefered |
| type. |
| </p> |
| <p> |
| Pay attention to the terminal window during the update. |
| </p> |
| <p> |
| Lines begining with a <b>P</b> mean the local copy was patched to update it |
| to the current version in the master repository. |
| </p> |
| <p> |
| Lines begining with a <b>M</b> mean your local copy is different from the |
| master copy, and the changes were successfully merged into your copy. |
| </p> |
| <p> |
| Lines begining with a <b>C</b> mean there was a conflict in merging the |
| changes and you need to review the file and merge the changes manually. Search |
| for >>>> and merge the changes. |
| </p> |
| <p> |
| Lines begining with a <b>?</b> indicate files that reside on your local |
| system which are not part of the repository. You will normally see this when |
| you are creating new files for submission. |
| </p> |
| </section> |
| <section name="Guides and Resources"> |
| <p> |
| A little help to get you if you need it |
| </p> |
| <ul> |
| <li> |
| <a href="http://www.xml.org/xml/resources_focus_beginnerguide.shtml">XML |
| Beginner's Guide</a> |
| </li> |
| <li> |
| <a href="http://nagoya.apache.org/bugzilla/">Bugzilla</a> |
| </li> |
| <li> |
| <a href="http://nagoya.apache.org/bugzilla/bugwritinghelp.html">Bugzilla Bug |
| Writing Guide</a> |
| </li> |
| <li> |
| <a href="http://jakarta.apache.org/ant">Ant</a> |
| </li> |
| <li> |
| <a href="http://www.cvshome.org/">CVS Home</a> |
| </li> |
| <li> |
| <a href="http://cvs.apache.org/viewcvs/jakarta-tomcat-connectors/jk/xdocs/">JK |
| Docs CVS</a> |
| </li> |
| </ul> |
| </section> |
| </document> |