httpd-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Joshua Slive <jos...@slive.ca>
Subject Re: Translation
Date Wed, 26 Oct 2005 20:35:06 GMT
Hey Ken!

Would you like to either apply the below patch or donate the document to 
apache so we can host it?  (I'd prefer the former.)

(We'll see if Ken will dig this message out of his enormous mail box...)

Noirin Plunkett wrote:
> On Wed, Oct 26, 2005 at 02:48:46PM -0500, William A. Rowe, Jr. wrote:
>> Joshua Slive wrote:
>>> Just one caution: Although the docs-project tutorial listed above has 
>>> lots of good general information, almost all of the technical details 
>>> are outdated and incorrect.
>> This made me chuckle ...
>>
>> Documentor, document thyself :)
> 
> I wrote a patch for this document several months ago - it's with Ken at
> the moment, waiting to be applied.
> I've attached the patch to this mail, in any case.
> Changes can be seen at http://www.nerdchic.net/apachedoc-howto.html
> Noirin
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
>> For additional commands, e-mail: docs-help@httpd.apache.org
>>
>>
>>
>> ------------------------------------------------------------------------
>>
>> --- ATdocs-project.html	2005-08-25 14:04:40.000000000 +0100
>> +++ apachedoc-howto.html	2005-08-25 14:04:06.000000000 +0100
>> @@ -50,8 +50,7 @@
>>     <li><a href="#mail">The <code>apache-docs</code> Mailing List</a></li>
>>     <li><a href="#cvs">Accessing the Documentation Project</a>
>>      <ul>
>> -     <li><a href="#anoncvs">Using Anonymous CVS</a></li>
>> -     <li><a href="#rsync">Using <code>rsync</code> to Stay Current</a></li>
>> +     <li><a href="#svn">Using SVN</a></li>
>>       <li><a href="#tarball">Downloading and Unpacking Tarballs</a></li>
>>       <li><a href="#havecommit">Once You Have Commit Access</a></li>
>>      </ul></li>
>> @@ -72,10 +71,12 @@
>>    <p>
>>    The mailing list that's dedicated to the documentation project
>>    is called <code>apache-docs</code>.  Discussions about what
>> -  needs to be done and how to do it take place on that list;
>> -  in addition, the reports of changes actually made to the master
>> -  documentation files are sent there, as well.  (There's an example
>> -  message of this sort <a href="#sample-message">later in this article</a>.)
>> +  needs to be done and how to do it take place on that list.
>> +  The reports of changes actually made to the master
>> +  documentation files are sent to a different list, <code
>> +  >cvs@httpd.apache.org</code>.  (There's an example
>> +  message of this sort <a href="#sample-message"
>> +  >later in this article</a>.)
>>    </p>
>>    <p>
>>    All comers are welcome to join and participate in the mailing list,
>> @@ -87,38 +88,62 @@
>>      docs-subscribe@httpd.apache.org
>>    </pre>
>>    <p>
>> +  or
>> +  </p>
>> +  <pre>
>> +    cvs-subscribe@httpd.apache.org
>> +  </pre>
>> +  <p>
>> +  for the documentation and change-control lists respectively. 
>>    You'll receive a confirmation message in response, which you must
>>    handle as it instructs in order to complete your subscription.
>>    </p>
>>    <p>
>> +  Particularly for the change-control list, you may prefer to keep up by 
>> +  periodically looking through the archives - it can be a little 
>> +  overwhelming at first! The archives for these lists are available at
>> +  <a href="http://mail-archives.apache.org/mod_mbox/httpd-docs/"
>> +  >http://mail-archives.apache.org/mod_mbox/httpd-docs/</a> and 
>> +  <a href="http://mail-archives.apache.org/mod_mbox/httpd-cvs/"
>> +  >http://mail-archives.apache.org/mod_mbox/httpd-cvs/</a>.
>> +  
>> +  <p>
>>    Once you're successfully subscribed to the mailing list, you'll start
>> -  receiving copies of all its mail traffic.  Much of it will be discussions
>> -  between people concerning how to document certain things.  Some
>> +  receiving copies of all its mail traffic.  On the docs list, much of 
>> +  it will be discussions concerning how to document certain things.  Some
>>    of the messages you'll receive are proposals for changes or additions
>> -  to the documentation, and others will be reports of changes actually
>> -  made to the master copies.  The former usually have a subject starting
>> -  with the word  '<code>[PATCH]</code>'; but the subjects of the latter
>> -  <i>always</i> begin with '<code>cvs&nbsp;commit</code>'.
>> +  to the documentation. These usually have a subject starting with the
>> +  word '<code>[PATCH]</code>'.
>> +  </p>
>> +  <p>On the cvs list, the messages will be reports of changes actually
>> +  made to the master copies, of both documentation and code.  
>> +  The subjects of these <i>always</i> begin with '<code
>> +  >svn&nbsp;commit</code>'.
>>    </p>
>>  
>>    <h2><a name="cvs">Accessing the Documentation Project</a></h2>
>>    <p>
>> -  There are currently four parts to the Apache Web server documentation
>> -  project.  There are two versions, one for Apache 1.3 and one for
>> -  Apache 2.0 (still in development at this point), and for each
>> -  version there are two sections: the 'user manual,' which describes the
>> -  directives and how to use the server, and the API (Application
>> -  Programming Interface) documentation, which exists to help developers
>> -  such as those writing modules for Apache.  Ordinarily when you
>> -  download the files, you request either the 1.3 or 2.0 version
>> -  and get both sections, but you can cut it more finely than that
>> -  if you like and only download a single section.
>> +  There are currently several parts to the Apache Web server documentation
>> +  project.  There are versions for Apache 2.0 and 2.2 (still in 
>> +  development at this point), and for Apache 2.1 (trunk - the next 
>> +  version to be released).  Apache 2.0 has already been released, and as 
>> +  such, the documentation for it is rarely changed.
>> +  </p>
>> +  <p>
>> +  For each version there are two sections: the 'user manual,' which 
>> +  describes the directives and how to use the server, and the API 
>> +  (Application Programming Interface) documentation, which exists to 
>> +  help developers such as those writing modules for Apache.  
>> +  Ordinarily, when you download the files, you request a particular 
>> +  version and get both sections, but you can cut it more finely than 
>> +  that if you like and only download a single section.
>>    </p>
>>    <p>
>>    Just like the source code, the master documentation files are
>> -  maintained using <i>CVS</i>, the Concurrent Versioning System.
>> -  CVS allows multiple people to work on the same files and coordinates
>> -  their changes, making conflict resolution very simple and easy.
>> +  maintained using <i>Subversion</i>, or '<code>svn</code>'.
>> +  SVN is a version control system, that allows multiple people to 
>> +  work on the same files, and coordinates their changes, making 
>> +  conflict resolution very simple and easy.
>>    </p>
>>    <p>
>>    There are essentially two different ways to obtain a copy of the
>> @@ -144,30 +169,16 @@
>>    work on it.
>>    </p>
>>    <p>
>> -  The Web server documentation project has been separated into two
>> -  distinct areas: one for version 1.3 of the server, and one for
>> -  version 2.0.  Apache 1.3 is stable, released, and widely deployed,
>> -  so there are a lot of people (millions!) who can benefit from improvements
>> -  to its documentation. Apache 2.0, however, is still in development
>> -  and hasn't been released yet.  There are a lot of significant
>> -  differences between it and version 1.3, so there are lots of areas
>> -  needing new documentation written or 1.3 documentation adapted.  There's
>> -  no shortage of needed documentation work!  Which version you choose
>> -  to work on is entirely up to you -- you can even choose to work on
>> -  both.
>> -  </p>
>> -  <p>
>>    For people who haven't (yet) been granted commit access, there are
>> -  three basic ways to keep up with the changes made to the master
>> +  two basic ways to keep up with the changes made to the master
>>    copies:
>>    </p>
>>    <ol>
>> -   <li>Anonymous CVS</li>
>> -   <li><code>rsync</code></li>
>> +  <li><code>svn</code></li>
>>     <li>Regular tarballs</li>
>>    </ol>
>>    <p>
>> -  I've listed these in descending order of ease-of-use when it comes to
>> +  <code>svn</code> is considerably easier to use, when it comes to 
>>    submitting changes.  These procedures are essentially the same as
>>    would be used to keep up with changes to the source code (as opposed
>>    to the documentation), except
>> @@ -175,196 +186,70 @@
>>    How to use them will be described in the following sections.
>>    </p>
>>  
>> -  <h3><a name="anoncvs">Using Anonymous CVS</a></h3>
>> +  <h3><a name="svn">Using Subversion</a></h3>
>>    <p>
>>    This is probably the best way to stay synchronised with the master
>>    documentation sources while actively working on changes.  This method
>> -  allows CVS to do one of the things it does best, keeping your local
>> +  allows <code>svn</code> to do one of the things it does best, keeping your local
>>    working files up to date with any changes other people are making while
>>    keeping your own alterations intact.
>>    </p>
>>    <p>
>> -  Anonymous CVS uses a real CVS repository, but the username used to
>> -  access it does not have permission to upload changes.  So
>> -  it's strictly a one-way proposition, keeping your local copies
>> -  synchronised with the master files, with no commit ability.
>> +  Anyone can check the documents out of the <svn> repository, but 
>> +  without being granted access, you will not be able to upload changes.  
>> +  So it's strictly a one-way proposition, keeping your local copies
>> +  synchronised with the master files, with no commit ability. So feel free
>> +  to experiment - you won't break anything!
>>    </p>
>>    <p>
>> -  There are currently two anonymous CVS repositories available.
>> -  One is actually the master Apache repository in read-only mode;
>> -  if you use that you're guaranteed to get the very latest and
>> -  up-to-the-second versions of the files.  The other repository
>> -  is on another system, and is synchronised with the master
>> -  every two hours, so you can use that if the one on the Apache site becomes
>> -  unavailable or you don't need its steaming freshness.
>> +  The first step in using <code>svn</code> is to install 
>> +  <a href="http://subversion.tigris.org/">Subversion</a>.
>> +  To work on the Apache project, you should also install 
>> +  <a href="http://java.sun.com/">Java</a> - this is used by the build
>> +  tool, which verifies that your XML is valid, and generates the HTML
>> +  documents from the XML.
>>    </p>
>>    <p>
>> -  The first step in using anoncvs is setting your CVSROOT environment 
>> -  variable.  This tells CVS to what server it should connect.  There
>> -  are currently two servers, and the only available method to access these
>> -  anoncvs servers is pserver; you need a reasonably recent CVS client
>> -  (such as 1.10) to use it.  An example of setting CVSROOT from a Bourne
>> -  shell:
>> -  </p>
>> +  Once you have these installed, and have chosen a local directory in
>> +  which to work (eg 'httpd-docs'), you need to check out the
>> +  documentation to that location. The commands below are to check out
>> +  the current version of the 'trunk' documentation - that is, the next 
>> +  version to be released.</p>
>>    <pre>
>> -    user@host:~$ <b>CVSROOT=:pserver:anoncvs@cvs.apache.org:/home/cvspublic</b>
>> -    user@host:~$ <b>export CVSROOT</b>
>> +    user@host:~$ <b>svn checkout http://svn.apache.org/repos/asf/httpd/httpd/trunk/docs httpd-docs</b>
>>    </pre>
>> -  <dl compact>
>> -   <dt><b>Note:</b></dt>
>> -   <dd>It is very important that you <b>not</b> put a trailing "/" on the value
>> -    of CVSROOT.</dd>
>> -  </dl>
>>    <p>
>> -  The two anoncvs servers currently available are:
>> +  Now you'll need to check out the build environment. First, change into the directory 'manual'
>>    </p>
>>    <pre>
>> -    :pserver:anoncvs@cvs.apache.org:/home/cvspublic
>> +    user@host:~/httpd-docs/manual/$ <b>svn checkout http://svn.apache.org/repos/asf/httpd/docs-build/trunk build</b>
>>    </pre>
>>    <p>
>> -  and
>> +  To update your local version of the documentation in future, you just need to run
>>    </p>
>>    <pre>
>> -    :pserver:anoncvs@CVS.Sourcery.Org:/cvs/apache
>> +    user@host:~/httpd-docs/$ <b>svn update</b>
>>    </pre>
>>    <p>
>> -  Choose one of these values for your setting of CVSROOT.
>> -  Once you have set your CVSROOT, you need to log in:
>> -  </p>
>> -  <pre>
>> -    user@host:~$ <b>cvs login</b>
>> -    (Logging in to anoncvs@cvs.apache.org:/home/cvspublic)
>> -    CVS password: 
>> -  </pre>
>> -  <p>
>> -  The password is "anoncvs" (without the quotation marks) for
>> -  both servers.
>> -  </p>
>> -  <p>
>> -  To check out the Apache 1.3 documentation:
>> -  </p>
>> -  <pre>
>> -    user@host:~$ <b>cvs checkout httpd-docs-1.3</b>
>> -    cvs server: Updating httpd-docs-1.3
>> -    cvs server: Updating httpd-docs-1.3
>> -    cvs server: Updating httpd-docs-1.3/apidoc
>> -    U httpd-docs-1.3/apidoc/.cvsignore
>> -    U httpd-docs-1.3/apidoc/APIdict.pm
>> -    U httpd-docs-1.3/apidoc/README
>> -    U httpd-docs-1.3/apidoc/TODO
>> -    U httpd-docs-1.3/apidoc/api-dict.html
>> -    <i>[...]</i>
>> -    user@host:~$ <b>ls httpd-docs-1.3</b>
>> -    CVS             apidoc          htdocs
>> -  </pre>
>> -  <p>
>> -  To update your local tree to the latest version:
>> -  <pre>
>> -    user@host:~$ <b>cvs update -dP httpd-docs-1.3</b>
>> -  </pre>
>> -  <p>
>> -  or
>> -  </p>
>> -  <pre>
>> -    user@host:~/httpd-docs-1.3/$ <b>cvs update -dP .</b>
>> -    P apidoc/APIdict.pm
>> -    RCS file: /home/cvs/httpd-docs-1.3/apidoc/TODO,v
>> -    retrieving revision 1.109
>> -    retrieving revision 1.110
>> -    Merging differences between 1.109 and 1.110 into TODO
>> -    M apidoc/README
>> -  </pre>
>> -  <p>
>> -  The <b>P</b> means that the local copy was patched to update it to the 
>> -  current version in the master repository.  The <b>M</b> means that your
>> -  local copy is different from the master copy, but that any changes were
>> -  merged into your copy successfully.  If
>> -  you see a <b>C</b> that means that there was a conflict in merging 
>> -  the changes and that you need to review the file manually (hint: 
>> -  search for <code>&gt;&gt;&gt;&gt;</code> in the file) to merge the changes.
>> -  </p>
>> -  <p>
>>    To obtain a diff (patch) of changes between your checked out copy and 
>>    the source tree at the time you checked it out:
>>    </p>
>>    <pre>
>> -    user@host:~$ <b>cvs diff -u httpd-docs-1.3</b>
>> +    user@host:~httpd-docs/$ <b>svn diff</b>
>>    </pre>
>>    <p>
>>    To obtain a diff against the current source tree, be sure to
>>    do an update before the diff.
>>    </p>
>>    <p>
>> -  The idea of having an anoncvs server is to make it much easier
>> -  for people interested in doing development to have access to the
>> -  CVS tree so they can submit patches against the current
>> -  tree and can keep their patched version up to date without 
>> -  having to manually merge their patches all the time.
>> -  </p>
>> -  <p>
>> -  The main disadvantage of using the anonymous CVS method is that
>> -  it requires you to have a CVS client on your local system.
>> +  The main disadvantage of using the <code>svn</code> method is that
>> +  it requires you to have a <code>svn</code> client on your local system.
>>    </p>
>>  
>> -  <h3><a name="rsync">Using <code>rsync</code> to Stay Current</a></h3>
>> -  <p>
>> -  The <code>rsync</code> (Remote SYNChroniser) tool is a very fast
>> -  and easy way to keep a local copy of a directory tree up-to-date with
>> -  the remote master files.  It's a client/server application, and the
>> -  local <code>rsync</code> client command works with the remote
>> -  server daemon to figure out which files on the remote end are new,
>> -  deleted, or have changed, and then propagates the changes to the
>> -  local copy, adding, deleting, or modifying files locally as needed.
>> -  </p>
>> -  <p>
>> -  Here's how you can use it with Apache:
>> -  </p>
>> -  <pre>
>> -    % <b>rsync -avz dev.apache.org::<i>doc-module</i> ~/<i>doc-module</i></b>
>> -  </pre>
>> -  <p>
>> -  where <code><i>doc-module</i></code> is either '<code>httpd-docs-1.3</code>'
>> -  or '<code>httpd-docs-2.0</code>'.
>> -  </p>
>> -  <p>
>> -  The second parameter, '<code>~/<i>doc-module</i></code>', is the name of
>> -  the local directory under which you want the remote files copied.
>> -  You can call that directory whatever you like; for simplicity's
>> -  sake, I suggest you give the directory the same name as the
>> -  documentation module, although you can call it anything you like
>> -  and put it anywhere you have access.  The first time you use
>> -  <code>rsync</code>, it will correctly think that <i>all</i>  of
>> -  the remote files are 'new,' and will download everything.
>> -  </p>
>> -  <p>
>> -  If you've already <code>rsync</code>ed the files into that directory
>> -  before, the command will only apply changes -- that's where the real
>> -  speed comes in.
>> -  </p>
>> -  <p>
>> -  There are two main drawbacks to using this method to keep synchronised
>> -  with the master files:
>> -  </p>
>> -  <ol>
>> -   <li><code>rsync</code> only notes that files have been changed;
>> -    it doesn't try to coordinate local and remote alterations.  You can
>> -    instruct it to not download files from the remote system if the
>> -    local copies of them have been modified more recently, or to
>> -    download them regardless.  The former will keep you from
>> -    receiving changes to the files you're actively editing,
>> -    and the latter will cause you to lose your edits.</li>
>> -   <li>Because of the way the documentation for Apache 2.0
>> -    is being done, only the 2.0 user manual is available <i>via</i>
>> -    <code>rsync</code>, so you can't use this method to keep
>> -    up with the API section if you want to work on that.  Unless,
>> -    of course, some solution is figured out that allows the
>> -    API files to be made available through <code>rsync</code>, too.</li>
>> -  </ol>
>> -
>>    <h3><a name="tarball">Downloading and Unpacking Tarballs</a></h3>
>>    <p>
>>    An automatic job runs on the Apache system every six hours and
>> -  bundles up the master CVS repositories into a <code>tar</code> archive
>> +  bundles up the master Subversion repositories into a <code>tar</code> archive
>>    (called a <i>tarball</i> or <i>tarchive</i>).  These tarballs are
>>    put into a directory for downloading, 
>>    </p>
>> @@ -375,18 +260,28 @@
>>    to download the tarballs.  The URL is:
>>    </p>
>>    <pre>
>> -    &lt;URL:<a href="http://cvs.apache.org/snapshots/"
>> -            >http://cvs.apache.org/snapshots/</a>&gt;
>> +    &lt;URL:<a href="http://cvs.apache.org/snapshots/httpd-docs-2.0/"
>> +            >http://cvs.apache.org/snapshots/httpd-docs-2.0/</a>&gt;
>> +  </pre>
>> +  <p>
>> +  for the v2.0 docs, or
>> +  </p>
>> +  <pre>
>> +    &lt;URL:<a href="http://cvs.apache.org/snapshots/httpd-docs-build/"
>> +            >http://cvs.apache.org/snapshots/httpd-docs-build/</a>&gt;
>>    </pre>
>>    <p>
>> +  for the trunk docs.
>> +  </p>
>> +  <p>
>>    The tarballs are gzipped and named with a timestamp indicating when they were
>>    created.  For example,
>>    </p>
>>    <pre>
>> -    apache-1.3_20000819060015.tar.gz
>> +    httpd-docs-build_20050825104056.tar.gz
>>    </pre>
>>    <p>
>> -  was created at 6:00:15 AM (PDT) on Saturday, 19 August 2000.  (All
>> +  was created at 10:40:56 AM (PDT) on Thursday, 25th August 2005.  (All
>>    times are U.S. West Coast time.)
>>    </p>
>>    <p>
>> @@ -402,124 +297,55 @@
>>  
>>    <h3><a name="havecommit">Once You Have Commit Access</a></h3>
>>    <p>
>> -  Once you've been granted direct access to the CVS repository
>> -  for the documentation, you need to go through a few actions before
>> -  you can take advantage of it.  This section describes those
>> -  actions.  Getting commit access isn't that difficult, so
>> +  Once you've been granted direct access to the Subversion repository
>> +  for the documentation, you'll be able to commit your changes straight
>> +  in to the documentation tree.  Getting commit access isn't that difficult, so
>>    if you really want to help out with the project, it's almost certainly
>>    just a matter of time.
>>    </p>
>>    <p>
>> -  Setting things up so you can take advantage of your direct access to
>> -  the project files takes a number of steps, but almost all of them
>> -  only need to be done once.  So even though this section is rather
>> -  long, it's not like it's something you need to run through each and
>> -  every time you want to make a change.
>> -  </p>
>> -  <p>
>> -  When you're given commit access, you'll be assigned an account on the
>> -  machine where the documentation sources live.  You will need to log
>> -  onto the system at least once, but not very often after that.  Telnet
>> -  access isn't permitted, and all the CVS activity goes through
>> -  channels secured with SSH (Secure SHell), so you'll need to log on
>> -  using it.  The first thing you need to do is change your password
>> -  on the Apache machine:
>> -  </p>
>> -  <pre>
>> -    % <b>ssh -l jdoe locus.apache.org</b>
>> -    jdoe@locus.apache.org's password: <b><i>enter the password you were given</i></b>
>> -    [<i>welcome message</i>]
>> -    bash-2.03$ <b>passwd</b>
>> -    Old password: <b><i>enter the password you were given</i></b>
>> -    New password: <b><i>enter the new password you want</i></b>
>> -    Retype new password: <b><i>enter the new password again</i></b>
>> -    passwd: updating the database...
>> -    passwd: done
>> -  </pre>
>> -  <p>
>> -  The next thing you should do is create an <code>.ssh</code> directory
>> -  on the Apache machine so that your transmissions will be secure, and
>> -  make sure the directory itself is secure:
>> -  </p>
>> -  <pre>
>> -    bash-2.03$ <b>mkdir .ssh</b>
>> -    bash-2.03$ <b>chmod 700 .ssh</b>
>> -  </pre>
>> -  <p>
>> -  Next you need to set up an SSH environment on your working
>> -  machine (if you don't already have one), so log out of the Apache
>> -  system again.  How you set up your local SSH environment depends on
>> -  whether you're using Windows or some flavour of Unix; the example here
>> -  is for the latter, since that's common to all Unix environments while
>> -  the Windows procedure varies depending on the SSH tools
>> -  you're using:
>> -  </p>
>> -  <pre>
>> -    % <b>ssh-keygen</b>
>> -    Initializing random number generator...
>> -    Generating p:  ........................++ (distance 378)
>> -    Generating q:  ......++ (distance 78)
>> -    Computing the keys...
>> -    Testing the keys...
>> -    Key generation complete.
>> -    Enter file in which to save the key (/home/jdoe/.ssh/identity): 
>> -    Enter passphrase: <b><i>some phrase</i></b>
>> -    Enter the same passphrase again: <b><i>some phrase</i></b>
>> -    Your identification has been saved in /home/jdoe/.ssh/identity.
>> -    Your public key is:
>> -    1024 37 1757929984416721208730364810902293553450996411072075783191053944
>> -    754656443598770447187276288423727562812292885286108547911953028869014076
>> -    111044194416145436315271955021155359447781640675839182941840834261082262
>> -    672358626432123431097764865833697997894646219556601685973804104269238278
>> -    14361628743139739328209517121 jdoe@myhost.com
>> -    Your public key has been saved in /tmp/identity.pub
>> -  </pre>
>> -  <p>
>> -  The next step is to make the Apache system aware of your SSH key; you
>> -  do this by copying a file to it:
>> -  </p>
>> -  <pre>
>> -    % <b>scp .ssh/identity.pub jdoe@locus.apache.org:.ssh/authorized_keys</b>
>> -    Enter passphrase for RSA key 'jdoe@myhost.com': <b><i>some phrase</i></b>
>> -    identity.pub              |          0 KB |   0.8 kB/s | ETA: 00:00:00 | 100%
>> -  </pre>
>> -  <p>
>> -  At this point, you should be able to use the <code>ssh</code> command to
>> -  log directly into the Apache system with the passphrase you assigned to
>> -  your SSH key instead of the login password:
>> -  </p>
>> -  <pre>
>> -    % <b>ssh locus.apache.org</b>
>> -    Enter passphrase for RSA key 'jdoe@myhost.com': <b><i>some phrase</i></b>
>> -    [<i>welcome message</i>]
>> -    bash-2.03$
>> -  </pre>
>> -  <p>
>> -  Now you should be all set up to take advantage of your commit access.
>> -  You need to set up a set of working directories in order to do this,
>> -  so do the following on your working machine:
>> -  </p>
>> -  <pre>
>> -    % cvs -d locus.apache.org:/home/cvs checkout httpd-docs-1.3
>> -    Enter passphrase for RSA key 'jdoe@myhost.com': <b><i>some phrase</i></b>
>> -    cvs server: Updating httpd-docs-1.3
>> -    cvs server: Updating httpd-docs-1.3/apidoc
>> -    U httpd-docs-1.3/apidoc/.cvsignore
>> -    U httpd-docs-1.3/apidoc/README
>> -    U httpd-docs-1.3/apidoc/TODO
>> -    U httpd-docs-1.3/apidoc/api-dict.html
>> -       [<i>more output</i>]
>> -  </pre>
>> -  <p>
>> -  Now when you want to work on the documentation, make your changes in the
>> -  newly checked-out working tree, and then use <code>cvs&nbsp;commit</code>
>> -  to check them into the master repository.
>> +  All you need to do, to commit  your changes, is to type
>> +  </p>
>> +  <pre>
>> +    user@host:~/httpd-docs/$ <b>svn commit</b>
>> +  </pre>
>> +  <p>
>> +  and you're done.
>>    </p>
>>    <p>
>>    If you have any questions about this process, you should ask them on
>>    the <code>apache-docs</code> mailing list.
>>    </p>
>>  
>> +  <h2><a name="editing">Editing the Documentation</a></h2>
>> +  <p>
>> +  When editing the documentation, you should only ever edit the XML 
>> +  files. When you have finished editing them, you should run the build
>> +  tool, to make sure your XML is valid, and all is well. To do this,
>> +  change to the build directory, and run 'build.sh' in that directory.
>> +  (You may need to change the permissions on this, the first time you
>> +  try to run it).
>> +  </p>
>> +  <pre>
>> +    user@host:~/httpd-docs/manual/build/$ <b>./build.sh</b>
>> +  </pre>
>> +  <p>
>> +  If all goes well, that command will run, and eventually output something like
>> +  </p>
>> +  <pre>
>> +    BUILD SUCCESSFUL
>> +    Total time: 1 minute 43 seconds
>> +  </pre>
>> +  <p>
>> +  If the build fails, look at the last few lines of its output. Usually,
>> +  the error is clear, and easy to fix (for example, you've forgotten to 
>> +  close a <code>&lt;p&gt;</code> tag). If you run into any problems, or
>> +  can't figure out what the error is, you can ask on the 
>> +  <code>apache-docs</code> mailing list. (Remember to include the last
>> +  few lines of the build output, which include the error!)
>> +  </p>
>> +
>> +
>>    <h2><a name="translating">Translating the Documentation</a></h2>
>>    <p>
>>    One of the major outcomes we hope to see from the documentation
>> @@ -533,7 +359,7 @@
>>    <p>
>>    The translated versions are being maintained alongside the
>>    English versions, with the goal of allowing Apache's
>> -  content negociation process to choose the appropriate language
>> +  content negotiation process to choose the appropriate language
>>    variant.  This means that for a particular section, there
>>    may be the following files:
>>    </p>
>> @@ -568,6 +394,7 @@
>>    world; we hope to be able to merge their efforts into the master
>>    documentation.
>>    </p>
>> +  
>>  
>>    <h2><a name="patches">Patches</a></h2>
>>    <p>
>> @@ -576,7 +403,8 @@
>>    of <i>patches</i>.  A patch is a list of differences between
>>    what's currently in the master repository and to what it should
>>    be changed, and understanding them is critical to keeping up
>> -  with what's going on.  Figure 1 shows an example patch:
>> +  with what's going on.  Figure 1 shows an example patch (this is 
>> +  purely for demonstration, not a real patch):
>>    </p>
>>    <div align="center">
>>     <table border="1">
>> @@ -586,37 +414,22 @@
>>      <tr>
>>       <td><!-- We break the usual indent-4 rule here 'cuz we're in a table -->
>>        <pre>
>> -Index: index.html.en
>> +Index: manual/caching.xml
>>  ===================================================================
>> -RCS file: /home/cvs/httpd-docs-1.3/htdocs/index.html.en,v
>> -retrieving revision 1.4
>> -diff -u -r1.4 index.html.en
>> ---- index.html.en       1999/11/20 21:29:40     1.4
>> -+++ index.html.en       2000/08/16 11:50:51
>> -@@ -12,9 +12,12 @@
>> -   ALINK="#FF0000"
>> -  &gt;
>> - 
>> --
>> --&lt;P&gt;
>> --If you can see this, it means that the installation of the &lt;A HREF=...<a href="#tfn1.1"><sup>1</sup></a>
>> -+&lt;p&gt;
>> -+If you can see this, it means that the installation of the
>> -+&lt;a href="http://www.apache.org/httpd"&gt;Apache web server&lt;/a&gt; software on
>> -+this system was successful.  You may now add content to this directory
>> -+and replace this page.
>> -+&lt;/p&gt;
>> - 
>> - &lt;P&gt;&lt;HR WIDTH="50%" SIZE="8"&gt;
>> +--- manual/caching.xml  (revision 240041)
>> ++++ manual/caching.xml  (working copy)
>> +@@ -29,7 +29,7 @@
>> +     &lt;module&gt;mod_disk_cache&lt;/module&gt;, &lt;module&gt;mod_mem_cache&lt;/module&gt;,
>> +     &lt;module&gt;mod_file_cache&lt;/module&gt; and &lt;a 
>> +     href="programs/htcacheclean.html"&gt;htcacheclean&lt;/a&gt; reference documentation.
>> +-    It describes how to use Apache's caching features to accelerate web and 
>> ++    The document describes how to use Apache's caching features to accelerate web and 
>> +     proxy serving, while avoiding common problems and misconfigurations.&lt;/p&gt;
>> +   </summary>
>>   
>>        </pre>
>>       </td>
>>      </tr>
>> -    <tr>
>> -     <td><a name="tfn1.1"><sup>1</sup></a> This line from the original source
>> -      was very long and has been truncated for display purposes.  Part of
>> -      the purpose of the patch is to fix that by wrapping the line.</td>
>> -    </tr>
>>     </table>
>>    </div>
>>    <p>
>> @@ -628,10 +441,7 @@
>>    <p>
>>    The first few lines of the patch identify the file involved, and
>>    the sources of the changes and the original against which they
>> -  compared.  In Figure 1, the '<code><b>1.4</b></code>' at the end of
>> -  the third line indicates that the original source used as a reference
>> -  was version 1.4 of the file in the CVS repository.  You don't generally
>> -  need to worry about this stuff, either.
>> +  compared.  You don't generally need to worry about this stuff, either.
>>    </p>
>>    <p>
>>    In the body of the patch, there are one or more sections separated
>> @@ -648,29 +458,44 @@
>>    </p>
>>    <pre>
>>       Line 0
>> -    -Line 1
>> -    +Line 2
>> -     Line 3
>> +     Line 1
>> +     Line 2
>> +    -Line 3
>> +    +Line 4
>> +     Line 5
>> +     Line 6
>> +  </pre>
>> +  <p>
>> +  as meaning '<code>Line 3</code> is replaced by <code>Line 4</code>',
>> +  and all other lines stay the same.
>> +  </p>
>> +  <p>
>> +  Creating a patch is a simple matter of typing
>> +  </p>
>> +  <pre>
>> +    user@host:~/httpd-docs/$ <b>svn diff</b>
>>    </pre>
>>    <p>
>> -  as meaning '<code>Line 1</code> is replaced by <code>Line 2</code>',
>> -  and '<code>Line 0</code>' and '<code>Line 3</code>' don't get changed.
>> +  This will create a diff of all the files. However, we usually only want
>> +  a diff of the XML files - the HTML ones will be regenerated by the person
>> +  committing the patch. To create a diff of a specific file, simply add 
>> +  the name of that file to the end of the command:
>>    </p>
>> +  <pre>
>> +    user@host:~/httpd-docs/$ <b>svn diff manual/caching.xml</b>
>> +  </pre>
>>  
>>    <h2><a name="patchapply">Applying Patches to Your Working Files</a></h2>
>>    <p>
>> -  So much for what patches look like.  A lot of the patch messages
>> -  which will sent to the mailing list will merely be signals of
>> -  changes that have been made to the master files -- but some
>> -  of them will be <i>proposed</i>  changes, sent to the list
>> -  for review and suggestions.
>> +  So much for what patches look like. Some of the time, <i>proposed</i> 
>> +  patches will be sent to the list for review and suggestions.
>>    </p>
>>    <p>
>>    In order to properly review such proposals, you need to be able to
>>    apply the changes to your own working copies of the documentation
>>    files so you can see how the result looks.
>>    </p>
>> -  <p>
>> +
>>    On either Windows or Unix, the key to this is the <code>patch</code>
>>    tool.  It accepts as input a text file containing a unified or
>>    context diff, and applies the changes to the indicated files.  It
>> @@ -678,9 +503,8 @@
>>    so you can simply save a patch mail message in a file and use that.
>>    </p>
>>    <pre>
>> -    % <b>cd httpd-docs-1.3/htdocs/</b>
>> -    % <b>patch &lt; /tmp/index.html.en.patch</b>
>> -    patching file `index.html.en'
>> +    user@host:~/httpd-docs/manual/$ <b>patch &lt; /tmp/index.xml.patch</b>
>> +    patching file `index.xml'
>>    </pre>
>>    <p>
>>    You may need to define the environment variable <code>POSIXLY_CORRECT</code>
>> @@ -711,9 +535,8 @@
>>    add the <code>-R</code> flag to the <code>patch</code> command:
>>    </p>
>>    <pre>
>> -    % <b>cd httpd-docs-1.3/htdocs/</b>
>> -    % <b>patch <u>-R</u> &lt; /tmp/index.html.en.patch</b>
>> -    patching file `index.html.en'
>> +    user@host:~/httpd-docs/manual/$ <b>patch <u>-R</u>&lt; /tmp/index.xml.patch</b>
>> +    patching file `index.xml'
>>    </pre>
>>    <p>
>>    The <code>-R</code> means &quot;reverse this patch&quot;.
>> @@ -728,19 +551,22 @@
>>    for you.
>>    </p>
>>    <p>
>> -  Patches can be generated automatically by CVS, which is one reason
>> -  people intending to submit changes are strongly encouraged to use
>> -  it.  Here's an example:
>> +  Patches can be generated automatically by <code>svn</code>, which is 
>> +  one reason people intending to submit changes are strongly encouraged 
>> +  to use it.  Here's an example:
>>    </p>
>>    <pre>
>> -    % <b>cvs update                 # <i>make sure we're up to date</i></b>
>> -    % <b>cvs diff -u index.html.en  # <i>generate the patch</i></b>
>> +    user@host:~/httpd-docs/manual/$ <b>svn update                 # <i>make sure we're up to date</i></b>
>> +    user@host:~/httpd-docs/manual/$ <b>svn diff caching.xml       # <i>generate the patch</i></b>
>>      <i>[output from Figure 1 displayed]</i>
>>    </pre>
>>    <p>
>> -  Redirect the output of <code>cvs&nbsp;diff</code> to a file, and you
>> -  have a patch to submit.   As shown in the example above, unidiffs
>> -  (unified diffs) are vastly preferred to context diffs.
>> +  Redirect the output to a file by running the following, and you have your patch. 
>> +  </p>
>> +  <pre>
>> +    user@host:~/httpd-docs/manual/$ <b>svn diff caching.xml > caching.xml.patch</b>
>> +  </pre>
>> +  
>>    </p>
>>    <p>
>>    To actually submit a patch, send a message to the
>> @@ -749,120 +575,50 @@
>>    start with '<code>[PATCH]</code>' and describe briefly what
>>    the patch is changing.  In the body of the message, give a more
>>    detailed explanation of the patch, such as what it's altering
>> -  and why, and follow it with the patch text itself.
>> -  </p>
>> -  <p>
>> -  <b>DO NOT</b> send patches as attachments!  They should definitely
>> -  be included as inline text.  Attachments have a tendency to be
>> -  difficult to apply, and often get tagged as being binary, making
>> -  them difficult to read as well.
>> +  and why, and attach the patch itself. You need not include patches
>> +  of the HTML files - but you can include patches for more than one XML
>> +  file at a time (for example, if you've fixed several related documents).
>>    </p>
>>    <p>
>> -  Don't try to mix operating systems, either!  If you're working with
>> +  Try not to mix operating systems, please!  If you're working with
>>    a tree that you checked out on Windows, generate the patch and send
>>    the mail on Windows as well.  Likewise, if you are working on Unix,
>>    generate the patch and send the mail from the Unix system.  If you
>>    don't abide by this stricture, the different formats of the two
>>    systems' text files will cause confusion and require careful editing
>> -  to undo.  (I.e., files will end up with embedded carriage-return
>> +  to undo.  (i.e., files will end up with embedded carriage-return
>>    characters that will need to be manually removed.)
>>    </p>
>>    <p>
>> -  When a change is committed to the CVS repository, the CVS server will
>> -  automatically send a mail message to the mailing list showing the
>> -  regenerated patch.  Such mail messages have a subject line beginning
>> -  with '<tt>cvs&nbsp;commit:</tt>', and the body of the message is
>> +  When a change is committed to the <code>svn</code> repository, 
>> +  the server will automatically send a message to the CVS mailing list 
>> +  showing the regenerated patch.  Such mail messages have a subject line 
>> +  beginning '<tt>svn&nbsp;commit:</tt>', and the body of the message is
>>    acceptable as input to the <code>patch</code> utility.  This means
>>    that people on the mailing list can apply committed changes to their
>>    own copies based on the mail, instead of updating from the repository.
>> -  Since the mailing list is used to discuss patches (among other things),
>> -  it also means that subscribers can reply to the commit report with
>> -  comments, which keeps discussions nicely focussed in a single thread.
>> -  </p>
>> -  <p>
>> -  <a href="#sample-message">Figure 2</a> shows a sample patch submission
>> -  message, including the inline patch text and the 'cover letter'
>> -  explaining what it fixes and why it's being submitted.  If the patch
>> -  text looks familiar, that's because it was used in examples earlier in this
>> -  article.  Note the prefix '<code>[PATCH]</code>' in the message's
>> -  subject line.
>> +  If you have comments on the commit report, please reply to the docs
>> +  mailing list - not the CVS one.
>>    </p>
>> -  <div align="center">
>> -   <a name="sample-message">&nbsp;</a>
>> -   <table border="1">
>> -    <tr>
>> -     <th>Figure 2: Sample Patch Submission Message</th>
>> -    </tr>
>> -    <tr>
>> -     <td><!-- We break the usual indent-4 rule here 'cuz we're in a table -->
>> -      <pre>
>> -From:     Rodent of Unusual Size &lt;Ken.Coar@Golux.Com&gt;
>> -To:       apache-docs@apache.org
>> -Reply-to: apache-docs@apache.org
>> -Subject:  [PATCH] to wrap long lines
>> -
>> -The English 'welcome' page has a reeeally long line in it; this
>> -is just a cosmetic change to wrap the text for easier maintainability.
>> -
>> -Index: index.html.en
>> -===================================================================
>> -RCS file: /home/cvs/httpd-docs-1.3/htdocs/index.html.en,v
>> -retrieving revision 1.4
>> -diff -u -r1.4 index.html.en
>> ---- index.html.en       1999/11/20 21:29:40     1.4
>> -+++ index.html.en       2000/08/16 11:50:51
>> -@@ -12,9 +12,12 @@
>> -   ALINK="#FF0000"
>> -  &gt;
>> - 
>> --
>> --&lt;P&gt;
>> --If you can see this, it means that the installation of the &lt;A HREF=...<a href="#tfn2.1"><sup>1</sup></a>
>> -+&lt;p&gt;
>> -+If you can see this, it means that the installation of the
>> -+&lt;a href="http://www.apache.org/httpd"&gt;Apache web server&lt;/a&gt; software on
>> -+this system was successful.  You may now add content to this directory
>> -+and replace this page.
>> -+&lt;/p&gt;
>> - 
>> - &lt;P&gt;&lt;HR WIDTH="50%" SIZE="8"&gt;
>> - 
>> -      </pre>
>> -     </td>
>> -    </tr>
>> -    <tr>
>> -     <td><a name="tfn2.1"><sup>1</sup></a> This line from the original source
>> -      was very long and has been truncated for display purposes.  Part of
>> -      the purpose of the patch is to fix that by wrapping the line.</td>
>> -    </tr>
>> -   </table>
>> -  </div>
>> -  <p>
>> -  Also note that the patch text is included inline as part of the
>> -  message's body, and not as an attachment.
>> -  </p>
>> -
>> -  <h2><a name="htmlrules">Rules for HTML</a></h2>
>> -  <p>
>> +  
>> +  <h2><a name="htmlrules">Rules for XML</a></h2>
>>    The rules governing the format and syntax of the Apache documentation
>>    are quite loose, but there <i>are</i> some guiding principles:
>>    </p>
>>    <ol>
>> -   <li>HTML tags should be <b>lowercase</b> wherever possible.  In other
>> +   <li>XML tags should be <b>lowercase</b> wherever possible.  In other
>>      words, '<code>&lt;a&nbsp;href="foo.html"&gt;Link&lt;/a&gt;</code>' is
>>      preferred over '<code>&lt;A&nbsp;HREF="foo.html"&gt;Link&lt;/A&gt;</code>'.
>>      This is because lowercase letters result in more efficient
>>      space savings when documents are compressed.</li>
>> -   <li>The HTML source should be wrapped at column 72 or less
>> +   <li>The XML source should be wrapped at column 72 or less
>>      when possible.  (This may not be possible for long URLs.)</li>
>> -   <li>The documentation <b>should</b> be valid HTML, and pass the
>> -    HTML validator at
>> -    &lt;URL:<a href="http://validator.w3.org/"
>> -            >http://validator.w3.org/</a>&gt;.</li>
>> +   <li>The documentation <b>should</b> be valid XML - the build tool will
>> +    not run sucessfully otherwise 
>>     <li>Container tags with optional closing tags (such as &lt;p&gt;
>> -    and &lt;li&gt;) should always include the closing tag regardless.</li>
>> -   <li>Use indentation and blank lines to make the HTML more easily
>> -    readable, since readable HTML is easier to maintain.</li>
>> +   and &lt;li&gt;) should <b>always</b> include the closing tag regardless.</li>
>> +   <li>Use indentation and blank lines to make the XML more easily
>> +    readable, since readable XML is easier to maintain.</li>
>>     <li>If you have to split an anchor tag across multiple lines,
>>      it is preferable to split it before the '&gt;' character.  For
>>      example:
>> @@ -880,8 +636,8 @@
>>      <i>displayed</i> by some browsers, giving the link a little tail.</li>
>>     <li>Remember that every byte of HTML has a network cost associated
>>      with it, and try to strike a balance between readability of the
>> -    HTML source and  the amount of whitespace and other nonsignificant
>> -    bytes that will consume bandwidth.</li>
>> +    XML source and  the amount of whitespace and other nonsignificant
>> +    bytes that will consume bandwidth in the generated HTML.</li>
>>    </ol>
>>  
>>    <h2><a name="troubleshooting">Troubleshooting</a></h2>
>>
>>
>> ------------------------------------------------------------------------
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
>> For additional commands, e-mail: docs-help@httpd.apache.org

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org


Mime
View raw message