A short guide on how to supply Proftpd documentation patches
First of all you've to make sure that you've installed the CVS tools. Under normal
circumstances your free operating system of choice should've a pre
packaged version avaible that you can install. For the Debian users
it's nothing more than a 'aptitude
install cvs'. For the MacOS X users is a package
avaible from the FINK project.
I guess there are even CVS tools avaible for various Microsoft OS but I
can not help you on this end, sorry.
Step 1 - Get a current cvs checkout
The central diretive list is build from a bunch a sgml files which are
hosted in a cvs repository at sourceforge.net within a project called pdd, short for Proftpd
documenation. To get started you've to simply check out a current copy
directly from the cvs. It's quite simple and you've not to understand
what the exact magic behind the following lines will do. You've to type
(or copy & paste) only the italicised parts after the $ sign.
$ cvs
-d:pserver:anonymous@pdd.cvs.sourceforge.net:/cvsroot/pdd login
Logging in to
:pserver:anonymous@pdd.cvs.sourceforge.net:2401/cvsroot/pdd
CVS password: [hit enter - we don't need a password for anonymous
access]
$ cvs -z3
-d:pserver:anonymous@pdd.cvs.sourceforge.net:/cvsroot/pdd co -P
Userguide
cvs checkout: Updating Userguide
U Userguide/.cvsignore
U Userguide/build.sh
U Userguide/main.sgml
[... here you'll see a lot more lines like these ...]
Now you should find a new directory called 'Userguide' in your current
directory. This directory holds the complete source of the diretive
documentation and some build scripts you won't need.
Step 2 - Find the right sgml file to edit
The intersting part you're searching for is in
'Userguide/diretives/sgml' changing to that directory you'll find a lot
of files named like the well known Proftpd diretives you know from your
proftpd.conf. Every file is a sgml object in will be part of the final
document when the docs are build.
Step 3 - Edit the file
Now let's get some work done and say you'll like to update the template
for the recently (we'll ATM Proftpd 1.3.1rc1 is recent) added
diretive
'UseIPv6'. To edit the file you've todo nothing more then open it in
the editor of your choice and start editing.
The first part I've to fix here is the purpose of the diretive. I'll
change the following lines from
<refnamediv>
<refname>UseIPv6</refname>
<refpurpose>FIXFIXFIX</refpurpose>
</refnamediv>
to
<refnamediv>
<refname>UseIPv6</refname>
<refpurpose>Disable IPv6 support</refpurpose>
</refnamediv>
Now let's change the options this diretive will take. As this one is
simple one only understanding on and off we've just to change
<arg choice="opt">
<option>"name" limit|regex|ip value</option>
</arg>
to
<arg choice="opt">
<option>"on"|"off"</option>
</arg>
The next thing is the default value of this diretive. In this case it's
on so we change
<varlistentry><term><synopsis>Default</synopsis></term>
<listitem> <para>
FIXFIXFIX
</para> </listitem>
</varlistentry>
to
<varlistentry><term><synopsis>Default</synopsis></term>
<listitem> <para>
UseIPv6 on
</para> </listitem>
</varlistentry>
According to the changelog this diretive should be placed on top of our
proftpd.conf so the next change for the context is to change
<varlistentry><term><synopsis>Context</synopsis></term>
<listitem> <para>
server config, <Global>, <VirtualHost>,
<Anonymous>, <Limit>, .ftpaccess
</para> </listitem>
</varlistentry>
to
<varlistentry><term><synopsis>Context</synopsis></term>
<listitem> <para>
server config
</para> </listitem>
</varlistentry>
The hardest part follows now. If nobody wrote a description for this
diretive you're on your own to add one. Mine looks like this:
<refsect1>
<title>Description</title>
<para>
This directive enables or disables the IPv6 support within proftpd.
It's also
possible to controll this behaviour with command-line options.
</para>
<literallayout>
-4, --ipv4 Support IPv4 functionality only
-6, --ipv6 Support IPv6 functionality
</literallayout>
</refsect1>
As there's nothing to link to we skip the 'see also' part and go the
example were we create the following one:
<refsect1>
<title>Examples</title>
<literallayout>
proftpd -4
</literallayout>
<para>
Start Proftpd only with IPv4 functionality enabled.
</para>
</refsect1>
Step 4 - Review your diff
Now you can review your changes with the cvs diff command. Type on the
commandline (within the 'Userguide' directory):
$ cvs diff -u
cvs diff: Diffing .
Index: UseIPv6
===================================================================
RCS file: /cvsroot/pdd/Userguide/directives/sgml/UseIPv6,v
retrieving revision 1.1
diff -u -r1.1 UseIPv6
--- UseIPv6 28 Dec 2006 12:22:06
-0000 1.1
+++ UseIPv6 30 Dec 2006 11:25:04 -0000
@@ -13,14 +13,14 @@
</refmeta>
<refnamediv>
<refname>UseIPv6</refname>
-<refpurpose>FIXFIXFIX</refpurpose>
+<refpurpose>Disable IPv6 support</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>UseIPv6</command>
<arg choice="opt">
- <option>"name" limit|regex|ip value</option>
+
<option>"on"|"off"</option>
</arg>
<!--
<arg choice="opt" rep="repeat">file</arg>
@@ -30,13 +30,13 @@
<variablelist><title></title>
<varlistentry><term><synopsis>Default</synopsis></term>
<listitem> <para>
-FIXFIXFIX
+UseIPv6 on
</para> </listitem>
</varlistentry>
<varlistentry><term><synopsis>Context</synopsis></term>
<listitem> <para>
-server config, <Global>, <VirtualHost>,
<Anonymous>, <Limit>, .ftpaccess
+server config
</para> </listitem>
</varlistentry>
@@ -56,8 +56,14 @@
<refsect1>
<title>Description</title>
<para>
-FIX FIX FIX
+This directive enables or disables the IPv6 support within proftpd.
It's also
+possible to controll this behaviour with command-line options.
</para>
+<literallayout>
+-4, --ipv4 Support IPv4 functionality only
+-6, --ipv6 Support IPv6 functionality
+</literallayout>
+
</refsect1>
<refsect1>
@@ -73,11 +79,11 @@
<title>Examples</title>
<literallayout>
-FIXFIXFIX
+proftpd -4
</literallayout>
<para>
-FIXFIX
+Start Proftpd only with IPv4 functionality enabled.
</para>
</refsect1>
Lines prefixed with a '-' got removed, lines prefixed with a '+' were
added. When you're happy with your changes you can move on with the
document. Otherwise just fire up your editor again and make more
changes until you're happy.
If you want to only diff one special file (maybe you've edited more
than one file) you can type
$ cvs diff -u directives/sgml/UseIPv6
Step 5 - Create a patch file from your diff ready to be reported
Now that you've done your changes you should first save your diff in a
patch file.
$ cvs diff -u
directives/sgml/UseIPv6 > /home/sven/UseIPv6.patch
This command redirects your diff in a file called 'UseIPv6.patch' in my
home diretory.
To actually make your changes a avaible you've several ways to go, you
can choose one that fits you most.
Step 6a - Working with the Proftpd bug reporting system Bugzilla
Point your browser to bugs.proftpd.org,
create a user account and open a bugreport with the .patch file you
created in Step 5. You'll find a component called 'docs' in the
reporting mask which you should select so that the right people have a
chance to read your report soon and apply your patch timely.
Step 6b - The proftpd-docs mailinglist
A second possible way to report your patch is the proftpd-docs
mailinglist. To participate you've to be subscribed otherwise you're
posts will have to be approved by the moderation guys.
The easiest way to subscribe is the mailman
webfrontend. Your mails should be addressed to
proftp-docs@lists.sourceforge.net
Step 6c - A backup solution if every other attemp to supply your
patch
fails
Well this is not really an option you should consider but if every
other of your attemps to report your patch has failed you can mail the
patch diretly to me. Address the patch to hoaxter@users.sourceforge.net
and if you're nice prefix the subject with '[pdd-patch]'.
Further questions?
If you've further questions on how things work or how to do help feel
free to subscribe to the proftpd-docs mailinglist (read about it in
Step 6b) and post your questions/comments.
If you've further comments related to this document mail to
hoaxter@users.sourceforge.net.