~ubuntu-branches/ubuntu/oneiric/libapache-mod-jk/oneiric

<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Tomcat Connector - How to Contribute to the Documentation</title><meta value="Robert Sowders" name="author"><meta value="rsowders@usgs.gov" name="email"><link rel="stylesheet" type="text/css" href="../style.css"></head><body vlink="#525D76" alink="#525D76" link="#525D76" text="#000000" bgcolor="#ffffff"><table cellspacing="4" width="100%" border="0"><tr><td colspan="2"><a href="http://tomcat.apache.org/"><img border="0" alt="Apache Tomcat" align="left" src="../images/tomcat.gif"></a><a href="http://www.apache.org/"><img border="0" alt="Apache Logo" align="right" src="http://www.apache.org/images/asf-logo.gif"></a></td></tr><tr><td colspan="2"><hr size="1" noshade="noshade"></td></tr><tr><td nowrap="true" valign="top" width="20%">Links<ul><li><a href="../index.html">Docs Home</a></li></ul>Generic Howto<ul><li><a href="quick.html">For the impatient</a></li><li><a href="workers.html">All about workers</a></li><li><a href="loadbalancers.html">Load Balancing</a></li></ul>Webservers<ul><li><a href="apache.html">Apache</a></li><li><a href="iis.html">IIS</a></li><li><a href="domino.html">Domino</a></li><li><a href="nes.html">SunOne (Netscape)</a></li></ul>Get Involved<ul><li><a href="doccontrib.html">Contribute documentation</a></li></ul></td><td align="left" valign="top" width="80%"><table cellspacing="4" width="100%" border="0"><tr><td valign="top" align="left"><h1>Tomcat Connector</h1><h2>How to Contribute to the Documentation</h2></td><td nowrap="true" valign="top" align="right"><a href="printer/doccontrib.html"><img alt="Printer Friendly Version" border="0" src="../images/printer.gif"> print-friendly version

</a></td></tr></table><table width="100%" cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><a name="Introduction">Introduction</a></td></tr><tr><td><blockquote>

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.

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.

It's all really quite simple. Here is what you will need:

<ul>

<li>

A recent version of Ant

</li>

<li>

The source code for the connectors from subversion

</li>

<li>

Any ascii text editor

</li>

</ul>

</blockquote></td></tr></table><table width="100%" cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><a name="Getting Started Step by Step">Getting Started Step by Step</a></td></tr><tr><td><blockquote>

After you get these tools they are simple to set up.

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.

Ant is used to build the documentation, among other things, and it must be

able to see a file called build.xml. This file is located in the

SVN_HOME\tomcat\connectors\trunk\jk\xdocs directory. In the

build.xml file there is a target named all that will be used to build

the docs.

</blockquote></td></tr></table>

<table width="100%" cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><a name="STEP 2. Get the sources">STEP 2. Get the sources</a></td></tr><tr><td><blockquote>

Get the sources for

<a href="http://svn.apache.org/repos/asf/tomcat/connectors/">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.

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 SVN_HOME. Mine is located in C:\build.

Run the following command to checkout the sources for the first time.

You should only need to do this once.

tomcat-connectors</code> <code class="screen"> </code> </td></tr></table></div>

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 svn update command.

and:</div><code class="screen">C:\build\tomcat-connectors\jk\>cd xdocs</code> <code class="screen">C:\build\tomcat-connectors\jk\xdocs\>svn update</code> </td></tr></table></div>

</blockquote></td></tr></table>

<table width="100%" cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><a name="STEP 3. Test your build environment">STEP 3. Test your build environment</a></td></tr><tr><td><blockquote>

Open a command prompt window and cd to the directory where you downloaded

the source. Now cd into the jk directory and then into the xdocs directory so

that Ant can see the

build.xml file. Then from a command prompt, run the following:

<div align="left"><table bgcolor="#000000" cellpadding="2" cellspacing="0" border="1" width="80%"><tr><td align="left" bgcolor="#000000"><code class="screen"> </code> <code class="screen">C:\build\tomcat-connectors>cd jk</code> <code class="screen">C:\build\tomcat-connectors\jk>cd xdocs</code> <code class="screen">C:\build\tomcat-connectors\jk\xdocs>ant all</code> <code class="screen"> </code> </td></tr></table></div>

.

You should see the ant compiler messages scrolling by rapidly and then stop

with the following:

to</code> <code class="screen">C:\build\tomcat-connectors\jk\build\docs\faq.html</code> <code class="screen">[style] Loading stylesheet C:\build\tomcat-connectors\jk\xdocs\style.xsl</code> <code class="screen">[style] Processing C:\build\tomcat-connectors\jk\xdocs\index.xml

to</code> <code class="screen">C:\build\tomcat-connectors\jk\build\docs\index.html</code> <code class="screen">[copy] Copying 8 files to C:\build\tomcat-connectors\jk\build\docs</code> <code class="screen"> </code> <code class="screen">BUILD SUCCESSFUL</code> <code class="screen">Total time: 10 seconds</code> <code class="screen">C:\build\tomcat-connectors\jk></code> </td></tr></table></div>

All the xml files present in the xdocs directory structure were transformed

to html and copied to the SVN_HOME\tomcat-connectors\jk\build\docs

100

directory. Open one of the

101

html files in your browser and see how it looks.

102

103

</blockquote></td></tr></table>

104

<table width="100%" cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><a name="STEP 4. The editing process.">STEP 4. The editing process.</a></td></tr><tr><td><blockquote>

105

106

I find it easier to use two windows while doing my updates. One I call my

107

build window. I keep this one in the SVN_HOME\tomcat-connectors\jk\xdocs

108

directory and I only run two commands in this window:

109

<div align="left"><table bgcolor="#000000" cellpadding="2" cellspacing="0" border="1" width="80%"><tr><td align="left" bgcolor="#000000"><code class="screen"> </code> <div class="screen"> First I run</div><code class="screen">ant clean</code> <div class="screen"> Then I run</div><code class="screen">ant all</code> <code class="screen"> </code> </td></tr></table></div>

110

111

112

My second window I call my edit window and I keep that one in the

113

SVN_HOME\tomcat-connectors\jk\xdocs directory where I'm doing my

114

edits, diffs and svn updates.

115

116

117

Before you start editing you should always update your local repository to

118

prevent conflicts.

119

<div align="left"><table bgcolor="#000000" cellpadding="2" cellspacing="0" border="1" width="80%"><tr><td align="left" bgcolor="#000000"><div class="screen"> You only need to update the xdocs directory</div><code class="screen">C:\build\tomcat-connectors\jk>cd xdocs</code> <code class="screen">C:\build\tomcat-connectors\jk\xdocs></code> <code class="screen">C:\build\tomcat-connectors\jk\xdocs>svn update</code> </td></tr></table></div>

120

121

122

Now that your repository is up to date you can begin editing. Find

123

something in the documentation to edit. When you find something remember the

124

name of the file. In your edit window find and edit the xml source file

125

with the same name. After you are done return to the build window, and

126

in the SVN_HOME\tomcat-connectors\jk\xdocs directory run:

127

128

129

130

This will delete all the previous html files and make the area ready for

131

updated material. Now to make fresh documents that incorporate your changes

132

run:

133

134

135

136

Use your browser to view the edits you just made, they will be in the

137

SVN_HOME\tomcat-connectors\jk\build\docs sub-tree. If it looks

138

good and is ready to go,

139

all that is left to do is to create a patch and submit it.

140

141

</blockquote></td></tr></table>

142

<table width="100%" cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><a name="STEP 5. Creating a patch and submitting it.">STEP 5. Creating a patch and submitting it.</a></td></tr><tr><td><blockquote>

143

144

From your edit window cd into the directory that contains the xml

145

file you are working on, and run the svn update command. For example,

146

to produce a diff of the index.xml file and call it patch.txt, you

147

would cd into the directory containing the index.xml file and:

148

149

patch.txt.</code> <code class="screen"> </code> </td></tr></table></div>

150

151

152

Now that you have your patch you are ready to send it in.

153

154

155

Patches to the documentation are handled just like a bug report. You

156

should submit your patches to <a href="http://issues.apache.org/bugzilla/">http://issues.apache.org/bugzilla/</a>

157

and include a good one line subject. If this is your first time to use the

158

bug database then you should read <a href="http://issues.apache.org/bugzilla/bugwritinghelp.html">http://issues.apach

159

e.org/bugzilla/bugwritinghelp.html.</a> You will need to create a user

160

account. At the web site paste your patch into the web form and don't forget

161

to describe what it is your patch is for. Sooner or later a someone with

162

commit privileges will review your suggestion.

163

164

</blockquote></td></tr></table>

165

</blockquote></td></tr></table><table width="100%" cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><a name="Subversion Basics">Subversion Basics</a></td></tr><tr><td><blockquote>

166

167

After you have checked out the sources the first time it is much easier to

168

use subversion. You can cd into any directory of the repository and run svn

169

update to get the latest sources for that directory. For editing

170

purposes you should always update your repository before you start editing to

171

reduce conflicts.

172

173

174

You will need to run svn diff to generate patches for submission.

175

Again cd into the directory containing the file you are editing and run svn

176

diff name_of_the_file_you_edited > patch.txt to generate a patch for

177

submission.

178

179

180

Pay attention to the terminal window during the update.

181

182

183

Lines begining with a A indicate files that have been added.

184

185

186

Lines begining with a D indicate files that have been deleted.

187

188

189

Lines begining with a U mean the local copy was patched to update it

190

to the current version in the master repository.

191

192

193

Lines begining with a G mean your local copy is different from the

194

master copy, and the changes were successfully merged into your copy.

195

196

197

Lines begining with a C mean there was a conflict in merging the

198

changes and you need to review the file and merge the changes manually. Search

199

for >>>> and merge the changes.

200

201

202

Lines begining with a ? indicate files that reside on your local

203

system which are not part of the repository. You will normally see this when

204

you are creating new files for submission.

205

206

</blockquote></td></tr></table><table width="100%" cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><a name="Updating Web site">Updating Web site</a></td></tr><tr><td><blockquote>

207

208

Only Committers are able to update the web site (http://tomcat.apache.org/connectors-doc/).

209

To do it:

210

<ul>

211

<li>Connect to people.apache.org.</li>

212

<li>umask 002</li>

213

<li>Copy the changed files to /www/tomcat.apache.org/connectors-doc/.</li>

214

<li>or use ant from a checkout tomcat/connectors/jk/xdocs repository:

215

ant -Dbuild.dir=/www/tomcat.apache.org -Ddist.name=connectors-doc

216

</li>

217

<li>The changes need around 4 hours to be synced to tomcat.apache.org.</li>

218

</ul>

219

220

</blockquote></td></tr></table><table width="100%" cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><a name="Guides and Resources">Guides and Resources</a></td></tr><tr><td><blockquote>

221

222

A little help to get you started if you need it

223

224

<ul>

225

<li>

226

<a href="http://www.xml.org/xml/resources_focus_beginnerguide.shtml">XML

227

Beginner's Guide</a>

228

</li>

229

<li>

230

<a href="http://issues.apache.org/bugzilla/">Bugzilla</a>

231

</li>

232

<li>

233

<a href="http://issues.apache.org/bugzilla/bugwritinghelp.html">Bugzilla Bug

234

Writing Guide</a>

235

</li>

236

<li>

237

238

</li>

239

<li>

240

<a href="http://subversion.tigris.org/">Subversion Home</a>

241

</li>

242

<li>

243

<a href="http://svn.apache.org/repos/asf/tomcat/connectors/jk/xdocs/">JK Docs repository</a>

244

</li>

245

</ul>

246

</blockquote></td></tr></table></td></tr><tr><td colspan="2"><hr size="1" noshade="noshade"></td></tr><tr><td colspan="2"><div align="center">

247

248

</div></td></tr></table></body></html>

b'\\ No newline at end of file'

Older »