diff options
Diffstat (limited to 'rubbos/app/tomcat-connectors-1.2.32-src/xdocs/miscellaneous/doccontrib.xml')
| -rw-r--r-- | rubbos/app/tomcat-connectors-1.2.32-src/xdocs/miscellaneous/doccontrib.xml | 337 |
1 files changed, 0 insertions, 337 deletions
diff --git a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/miscellaneous/doccontrib.xml b/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/miscellaneous/doccontrib.xml deleted file mode 100644 index 5108a85f..00000000 --- a/rubbos/app/tomcat-connectors-1.2.32-src/xdocs/miscellaneous/doccontrib.xml +++ /dev/null @@ -1,337 +0,0 @@ -<?xml version="1.0" encoding="ISO-8859-1"?> -<!DOCTYPE document [ - <!ENTITY project SYSTEM "project.xml"> -]> -<document url="doccontrib.html"> - - &project; -<copyright> - Licensed to the Apache Software Foundation (ASF) under one or more - contributor license agreements. See the NOTICE file distributed with - this work for additional information regarding copyright ownership. - The ASF licenses this file to You 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: 2010-03-15 16:27:18 +0100 (Mon, 15 Mar 2010) $</date> -</properties> -<body> -<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 syntax 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 subversion</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://ant.apache.org/">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>xdocs</b> directory. In the -<b>build.xml</b> file there is a target named <b>all</b> 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://svn.apache.org/repos/asf/tomcat/jk/trunk/">tomcat-connectors</a> -from the subversion repository. If you'll -be editing from a windows platform you will need a windows subversion client. There -are several available. I like <a href="http://tortoisesvn.tigris.org/">turtoiseSVN</a>. -Unix users should install the subversion 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. For simplicity we will call this -your <b>SVN_HOME</b>. Mine is located in C:\build. -</p> -<p> - 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\>svn checkout http://svn.apache.org/repos/asf/tomcat/jk/trunk/ -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 is over. From now on, to update your -sources all you have to do is cd into any directory in your repository and run -the <b>svn update</b> command. - <screen> -<note> To update your xdocs directory simply cd into the xdocs directory -and:</note> -<read>C:\build\tomcat-connectors\>cd xdocs</read> -<read>C:\build\tomcat-connectors\xdocs\>svn update</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 xdocs directory so that <b>Ant</b> can see the -<b>build.xml</b> file. Then from a command prompt, run the following: -<screen> -<read> </read> -<read>C:\build\tomcat-connectors>cd xdocs</read> -<read>C:\build\tomcat-connectors\xdocs>ant all</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\tomcat-connectors\build\docs\news\printer></read> -<read>[style] Processing C:\build\tomcat-connectors\xdocs\news\20041100.xml -to</read> -<read>C:\build\tomcat-connectors\build\docs\news/20041100.html</read> -<read>[style] Loading stylesheet C:\build\tomcat-connectors\xdocs\style.xsl</read> -<read>[style] Processing C:\build\tomcat-connectors\xdocs\news\20050101.xml -to</read> -<read>C:\build\tomcat-connectors\build\docs\news/20050101.html</read> -<read>[style] Processing C:\build\tomcat-connectors\xdocs\news\20060101.xml -to</read> -<read>C:\build\tomcat-connectors\build\docs\news/20060101.html</read> -<read>[style] Transforming into C:\build\tomcat-connectors\build\docs></read> -<read>[style] Processing C:\build\tomcat-connectors\xdocs\index.xml -to</read> -<read>C:\build\tomcat-connectors\build\docs\index.html</read> -<read>[style] Loading stylesheet C:\build\tomcat-connectors\xdocs\style.xsl</read> -<read> </read> -<read>BUILD SUCCESSFUL</read> -<read>Total time: 10 seconds</read> -<read>C:\build\tomcat-connectors></read> -</screen> -</p> -<p> - All the xml files present in the xdocs directory structure were transformed -to html and copied to the <b>SVN_HOME\tomcat-connectors\build\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>SVN_HOME\tomcat-connectors\xdocs</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 all</read> -<read> </read> -</screen> -</p> -<p> - My second window I call my <b>edit</b> window and I keep that one in the -<b>SVN_HOME\tomcat-connectors\xdocs</b> directory where I'm doing my -edits, diffs and svn 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\tomcat-connectors>cd xdocs</read> -<read>C:\build\tomcat-connectors\xdocs></read> -<read>C:\build\tomcat-connectors\xdocs>svn update</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 something 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>SVN_HOME\tomcat-connectors\xdocs</b> directory run: -<screen> -<read> </read> -<read>C:\build\tomcat-connectors\xdocs> 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\tomcat-connectors\xdocs>ant all</read> -<read> </read> -</screen> -</p> -<p> - Use your browser to view the edits you just made, they will be in the -<b>SVN_HOME\tomcat-connectors\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>svn update</b> command. For example, -to produce a 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\tomcat-connectors\xdocs\>svn diff 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://issues.apache.org/bugzilla/">http://issues.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://issues.apache.org/bugzilla/bugwritinghelp.html">http://issues.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="Subversion Basics"> -<p> - After you have checked out the sources the first time it is much easier to -use subversion. You can cd into any directory of the repository and run <b>svn -update</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>svn diff</b> to generate patches for submission. -Again cd into the directory containing the file you are editing and run <b>svn -diff name_of_the_file_you_edited > patch.txt</b> to generate a patch for -submission. -</p> -<p> - Pay attention to the terminal window during the update. -</p> -<p> - Lines begining with a <b>A</b> indicate files that have been added. -</p> -<p> - Lines begining with a <b>D</b> indicate files that have been deleted. -</p> -<p> - Lines begining with a <b>U</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>G</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="Updating Web site"> -<p> - Only Committers are able to update the web site (http://tomcat.apache.org/connectors-doc/). - To do it: - <ul> - <li>Connect to people.apache.org.</li> - <li>umask 002</li> - <li>Copy the changed files to /www/tomcat.apache.org/connectors-doc/.</li> - <li>or use ant from a checkout tomcat/jk/trunk/xdocs repository:<br /> - ant -Dbuild.dir=/www/tomcat.apache.org -Ddist.name=connectors-doc - </li> - <li>The changes need around 4 hours to be synced to tomcat.apache.org.</li> - </ul> -</p> -</section> -<section name="Guides and Resources"> -<p> - A little help to get you started 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://issues.apache.org/bugzilla/">Bugzilla</a> -</li> -<li> -<a href="http://issues.apache.org/bugwritinghelp.html">Bugzilla Bug -Writing Guide</a> -</li> -<li> -<a href="http://ant.apache.org/">Ant</a> -</li> -<li> -<a href="http://subversion.tigris.org/">Subversion Home</a> -</li> -<li> -<a href="http://svn.apache.org/repos/asf/tomcat/jk/trunk/xdocs/">JK Docs repository</a> -</li> -</ul> -</section> -</body> -</document> |