1
<?xml version="1.0" encoding="ISO-8859-1"?>
3
<!ENTITY project SYSTEM "project.xml">
5
<document url="doccontrib.html">
9
Copyright 1999-2006 The Apache Software Foundation
11
Licensed under the Apache License, Version 2.0 (the "License");
12
you may not use this file except in compliance with the License.
13
You may obtain a copy of the License at
15
http://www.apache.org/licenses/LICENSE-2.0
17
Unless required by applicable law or agreed to in writing, software
18
distributed under the License is distributed on an "AS IS" BASIS,
19
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
20
See the License for the specific language governing permissions and
21
limitations under the License.
24
<title>How to Contribute to the Documentation</title>
25
<author email="rsowders@usgs.gov">Robert Sowders</author>
26
<date>$Date: 2006-06-29 01:56:49 +0200 (Thu, 29 Jun 2006) $</date>
29
<section name="Introduction">
31
This document describes how you can easily contribute to the
32
documentation. I'm going to try to make it easy for everyone to help out with
33
the documentation of Tomcat, more specifically the documentation for the
34
connectors. This is written from a windows user perspective as I believe they
35
will most benefit from it. For people using Unix it should be easy for them to
36
apply these steps. Just substitute Unix syntax where needed.
39
The documentation is produced using xml with xsl style sheets. This
40
effectivly seperates the content of the documents from the style, so all that
41
contributers need to worry about the content. It is much easier to use than
45
It's all really quite simple. Here is what you will need:
48
<b>A recent version of Ant</b>
51
<b>The source code for the connectors from subversion</b>
54
<b>Any ascii text editor</b>
59
<section name="Getting Started Step by Step">
61
After you get these tools they are simple to set up.
63
<subsection name="STEP 1. Get Ant">
65
Install <a href="http://ant.apache.org/">Ant</a>. The only advice I
66
have is to choose a simple installation path. Now set an environment variable
67
for ANT_HOME, and then add the location of the Ant/bin directory to your PATH
68
variable. Consult your Operating system documentation for information on how
69
to do this. When you are finished verify that you can run ant from the command
73
Ant is used to build the documentation, among other things, and it must be
74
able to see a file called <b>build.xml</b>. This file is located in the
75
<b>SVN_HOME\tomcat\connectors\trunk\jk\xdocs</b> directory. In the
76
<b>build.xml</b> file there is a target named <b>all</b> that will be used to build
80
<subsection name="STEP 2. Get the sources">
83
<a href="http://svn.apache.org/repos/asf/tomcat/connectors/">tomcat-connectors</a>
84
from the subversion repository. If you'll
85
be editing from a windows platform you will need a windows subversion client. There
86
are several available. I like <a href="http://tortoisesvn.tigris.org/">turtoiseSVN</a>.
87
Unix users should install the subversion client of their choice,
88
if they don't already have one.
91
You are ready to download the sources now. Change directory to the
92
location where you want your repository to be. For simplicity we will call this
93
your <b>SVN_HOME</b>. Mine is located in C:\build.
96
Run the following command to <b>checkout</b> the sources for the first time.
97
You should only need to do this once.
100
<read>C:\build\>svn checkout http://svn.apache.org/repos/asf/tomcat/connectors/
101
tomcat-connectors</read>
106
You should now be watching all the downloads come in. Now that you have
107
the sources on your machine the hard part is over. From now on, to update your
108
sources all you have to do is cd into any directory in your repository and run
109
the <b>svn update</b> command.
111
<note> To update your xdocs directory simply cd into the xdocs directory
113
<read>C:\build\tomcat-connectors\jk\>cd xdocs</read>
114
<read>C:\build\tomcat-connectors\jk\xdocs\>svn update</read>
118
<subsection name="STEP 3. Test your build environment">
120
Open a command prompt window and cd to the directory where you downloaded
121
the source. Now cd into the jk directory and then into the xdocs directory so
122
that <b>Ant</b> can see the
123
<b>build.xml</b> file. Then from a command prompt, run the following:
126
<read>C:\build\tomcat-connectors>cd jk</read>
127
<read>C:\build\tomcat-connectors\jk>cd xdocs</read>
128
<read>C:\build\tomcat-connectors\jk\xdocs>ant all</read>
133
You should see the ant compiler messages scrolling by rapidly and then stop
136
<read>[style] Transforming into C:\build\tomcat-connectors\jk\build\docs></read>
137
<read>[style] Processing C:\build\tomcat-connectors\jk\xdocs\faq.xml
139
<read>C:\build\tomcat-connectors\jk\build\docs\faq.html</read>
140
<read>[style] Loading stylesheet C:\build\tomcat-connectors\jk\xdocs\style.xsl</read>
141
<read>[style] Processing C:\build\tomcat-connectors\jk\xdocs\index.xml
143
<read>C:\build\tomcat-connectors\jk\build\docs\index.html</read>
144
<read>[copy] Copying 8 files to C:\build\tomcat-connectors\jk\build\docs</read>
146
<read>BUILD SUCCESSFUL</read>
147
<read>Total time: 10 seconds</read>
148
<read>C:\build\tomcat-connectors\jk></read>
152
All the xml files present in the xdocs directory structure were transformed
153
to html and copied to the <b>SVN_HOME\tomcat-connectors\jk\build\docs</b>
154
directory. Open one of the
155
html files in your browser and see how it looks.
158
<subsection name="STEP 4. The editing process.">
160
I find it easier to use two windows while doing my updates. One I call my
161
<b>build</b> window. I keep this one in the <b>SVN_HOME\tomcat-connectors\jk\xdocs</b>
162
directory and I only run two commands in this window:
165
<note> First I run</note>
166
<read>ant clean</read>
167
<note> Then I run</note>
173
My second window I call my <b>edit</b> window and I keep that one in the
174
<b>SVN_HOME\tomcat-connectors\jk\xdocs</b> directory where I'm doing my
175
edits, diffs and svn updates.
178
Before you start editing you should always update your local repository to
181
<note> You only need to update the xdocs directory</note>
182
<read>C:\build\tomcat-connectors\jk>cd xdocs</read>
183
<read>C:\build\tomcat-connectors\jk\xdocs></read>
184
<read>C:\build\tomcat-connectors\jk\xdocs>svn update</read>
188
Now that your repository is up to date you can begin editing. Find
189
something in the documentation to edit. When you find something remember the
190
name of the file. In your <b>edit</b> window find and edit the xml source file
191
with the same name. After you are done return to the <b>build</b> window, and
192
in the <b>SVN_HOME\tomcat-connectors\jk\xdocs</b> directory run:
195
<read>C:\build\tomcat-connectors\jk\xdocs> ant clean</read>
200
This will delete all the previous html files and make the area ready for
201
updated material. Now to make fresh documents that incorporate your changes
205
<read>C:\build\tomcat-connectors\jk\xdocs>ant all</read>
210
Use your browser to view the edits you just made, they will be in the
211
<b>SVN_HOME\tomcat-connectors\jk\build\docs</b> sub-tree. If it looks
212
good and is ready to go,
213
all that is left to do is to create a patch and submit it.
216
<subsection name="STEP 5. Creating a patch and submitting it.">
218
From your <b>edit</b> window cd into the directory that contains the xml
219
file you are working on, and run the <b>svn update</b> command. For example,
220
to produce a diff of the index.xml file and call it patch.txt, you
221
would cd into the directory containing the index.xml file and:
223
<read>C:\build\tomcat-connectors\jk\xdocs\>svn diff index.xml >
229
Now that you have your patch you are ready to send it in.
232
Patches to the documentation are handled just like a bug report. You
233
should submit your patches to <a
234
href="http://issues.apache.org/bugzilla/">http://issues.apache.org/bugzilla/</a>
235
and include a good one line subject. If this is your first time to use the
236
bug database then you should read <a
237
href="http://issues.apache.org/bugzilla/bugwritinghelp.html">http://issues.apach
238
e.org/bugzilla/bugwritinghelp.html.</a> You will need to create a user
239
account. At the web site paste your patch into the web form and don't forget
240
to describe what it is your patch is for. Sooner or later a someone with
241
commit privileges will review your suggestion.
245
<section name="Subversion Basics">
247
After you have checked out the sources the first time it is much easier to
248
use subversion. You can cd into any directory of the repository and run <b>svn
249
update</b> to get the latest sources for that directory. For editing
250
purposes you should always update your repository before you start editing to
254
You will need to run <b>svn diff</b> to generate patches for submission.
255
Again cd into the directory containing the file you are editing and run <b>svn
256
diff name_of_the_file_you_edited > patch.txt</b> to generate a patch for
260
Pay attention to the terminal window during the update.
263
Lines begining with a <b>A</b> indicate files that have been added.
266
Lines begining with a <b>D</b> indicate files that have been deleted.
269
Lines begining with a <b>U</b> mean the local copy was patched to update it
270
to the current version in the master repository.
273
Lines begining with a <b>G</b> mean your local copy is different from the
274
master copy, and the changes were successfully merged into your copy.
277
Lines begining with a <b>C</b> mean there was a conflict in merging the
278
changes and you need to review the file and merge the changes manually. Search
279
for >>>> and merge the changes.
282
Lines begining with a <b>?</b> indicate files that reside on your local
283
system which are not part of the repository. You will normally see this when
284
you are creating new files for submission.
288
<section name="Updating Web site">
290
Only Committers are able to update the web site (http://tomcat.apache.org/connectors-doc/).
293
<li>Connect to people.apache.org.</li>
295
<li>Copy the changed files to /www/tomcat.apache.org/connectors-doc/.</li>
296
<li>or use ant from a checkout tomcat/connectors/jk/xdocs repository:<br />
297
ant -Dbuild.dir=/www/tomcat.apache.org -Ddist.name=connectors-doc
299
<li>The changes need around 4 hours to be synced to tomcat.apache.org.</li>
303
<section name="Guides and Resources">
305
A little help to get you started if you need it
309
<a href="http://www.xml.org/xml/resources_focus_beginnerguide.shtml">XML
313
<a href="http://issues.apache.org/bugzilla/">Bugzilla</a>
316
<a href="http://issues.apache.org/bugzilla/bugwritinghelp.html">Bugzilla Bug
320
<a href="http://ant.apache.org/">Ant</a>
323
<a href="http://subversion.tigris.org/">Subversion Home</a>
326
<a href="http://svn.apache.org/repos/asf/tomcat/connectors/jk/xdocs/">JK Docs repository</a>
added
removed
xdocs/howto/doccontrib.xml
