You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@httpd.apache.org by Noirin Plunkett <fi...@nerdchic.net> on 2005/08/22 21:31:05 UTC
PATCH: Language changes & fixes
Hi there,
I've been going through the Apache trunk docs, and have some language changes and fixes to suggest.
The following is the patch:
Index: manual/stopping.xml
===================================================================
--- manual/stopping.xml (revision 239220)
+++ manual/stopping.xml (working copy)
@@ -119,9 +119,10 @@
been created, then create enough to pick up the slack. Hence the
code tries to maintain both the number of children appropriate for
the current load on the server, and respect your wishes with the
- <directive>StartServers</directive> parameter.</p>
+ <directive module="mpm_common">StartServers</directive>
+ parameter.</p>
- <p>Users of the <module>mod_status</module>
+ <p>Users of <module>mod_status</module>
will notice that the server statistics are <strong>not</strong>
set to zero when a <code>USR1</code> is sent. The code was
written to both minimize the time in which the server is unable
@@ -188,26 +189,27 @@
<section id="race"><title>Appendix: signals and race conditions</title>
<p>Prior to Apache 1.2b9 there were several <em>race
- conditions</em> involving the restart and die signals (a simple
- description of race condition is: a time-sensitive problem, as
- in if something happens at just the wrong time it won't behave
- as expected). For those architectures that have the "right"
+ conditions</em> involving the restart and die signals (a simply put,
+ a race condition is a time-sensitive problem - if something happens
+ at just the wrong time or things happen in the wrong order,
+ undesired behaviour will result. If the same thing happens at the right
+ time, all will be well). For those architectures that have the "right"
feature set we have eliminated as many as we can. But it should
- be noted that there still do exist race conditions on certain
+ be noted that race conditions do still exist on certain
architectures.</p>
- <p>Architectures that use an on disk <directive
- module="mpm_common">ScoreBoardFile</directive> have the potential
- to corrupt their scoreboards. This can result in the "bind:
+ <p>Architectures that use an on-disk <directive
+ module="mpm_common">ScoreBoardFile</directive> can potentially have
+ their scoreboards corrupted. This can result in the "bind:
Address already in use" (after <code>HUP</code>) or "long lost
child came home!" (after <code>USR1</code>). The former is a fatal
error, while the latter just causes the server to lose a
- scoreboard slot. So it might be advisable to use graceful
+ scoreboard slot. So it may be advisable to use graceful
restarts, with an occasional hard restart. These problems are very
difficult to work around, but fortunately most architectures do
not require a scoreboard file. See the <directive
- module="mpm_common">ScoreBoardFile</directive> documentation for a
- architecture uses it.</p>
+ module="mpm_common">ScoreBoardFile</directive> documentation for
+ architecture which uses it.</p>
<p>All architectures have a small race condition in each child
involving the second and subsequent requests on a persistent
Index: manual/install.html.en
===================================================================
--- manual/install.html.en (revision 239220)
+++ manual/install.html.en (working copy)
@@ -155,14 +155,15 @@
[OPTIONAL]</dt>
<dd>For some of the support scripts like <code class="program"><a href="./programs/apxs.html">apxs</a></code> or <code class="program"><a href="./programs/dbmmanage.html">dbmmanage</a></code> (which are
written in Perl) the Perl 5 interpreter is required (versions
- 5.003 or newer are sufficient). If no such interpreter is found by
- the <code class="program"><a href="./programs/configure.html">configure</a></code> script there is no harm. Of course, you
- still can build and install Apache 2.0. Only those support scripts
- cannot be used. If you have multiple Perl interpreters
- installed (perhaps a Perl 4 from the vendor and a Perl 5 from
- your own), then it is recommended to use the <code>--with-perl</code>
- option (see below) to make sure the correct one is selected
- by <code class="program"><a href="./programs/configure.html">configure</a></code>.</dd>
+ 5.003 or newer are sufficient). If you have multiple Perl
+ interpreters (for example, a systemwide install of Perl 4, and
+ your own install of Perl 5), you are advised to use the
+ <code>--with-perl</code> option (see below) to make sure the
+ correct one is used by <code class="program"><a href="./programs/configure.html">configure</a></code>.
+ If no Perl 5 interpreter is found by the
+ <code class="program"><a href="./programs/configure.html">configure</a></code> script, you will not be able to use
+ the affected support scripts. Of course, you will still be able to
+ build and use Apache 2.0.</dd>
</dl>
</div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
<div class="section">
Index: manual/install.xml
===================================================================
--- manual/install.xml (revision 239220)
+++ manual/install.xml (working copy)
@@ -152,14 +152,15 @@
<dd>For some of the support scripts like <program>
apxs</program> or <program>dbmmanage</program> (which are
written in Perl) the Perl 5 interpreter is required (versions
- 5.003 or newer are sufficient). If no such interpreter is found by
- the <program>configure</program> script there is no harm. Of course, you
- still can build and install Apache 2.0. Only those support scripts
- cannot be used. If you have multiple Perl interpreters
- installed (perhaps a Perl 4 from the vendor and a Perl 5 from
- your own), then it is recommended to use the <code>--with-perl</code>
- option (see below) to make sure the correct one is selected
- by <program>configure</program>.</dd>
+ 5.003 or newer are sufficient). If you have multiple Perl
+ interpreters (for example, a systemwide install of Perl 4, and
+ your own install of Perl 5), you are advised to use the
+ <code>--with-perl</code> option (see below) to make sure the
+ correct one is used by <program>configure</program>.
+ If no Perl 5 interpreter is found by the
+ <program>configure</program> script, you will not be able to use
+ the affected support scripts. Of course, you will still be able to
+ build and use Apache 2.0.</dd>
</dl>
</section>
Index: manual/stopping.html.en
===================================================================
--- manual/stopping.html.en (revision 239220)
+++ manual/stopping.html.en (working copy)
@@ -117,9 +117,10 @@
been created, then create enough to pick up the slack. Hence the
code tries to maintain both the number of children appropriate for
the current load on the server, and respect your wishes with the
- <code class="directive">StartServers</code> parameter.</p>
+ <code class="directive"><a href="./mod/mpm_common.html#startservers">StartServers</a></code>
+ parameter.</p>
- <p>Users of the <code class="module"><a href="./mod/mod_status.html">mod_status</a></code>
+ <p>Users of <code class="module"><a href="./mod/mod_status.html">mod_status</a></code>
will notice that the server statistics are <strong>not</strong>
set to zero when a <code>USR1</code> is sent. The code was
written to both minimize the time in which the server is unable
@@ -186,24 +187,25 @@
<h2><a name="race" id="race">Appendix: signals and race conditions</a></h2>
<p>Prior to Apache 1.2b9 there were several <em>race
- conditions</em> involving the restart and die signals (a simple
- description of race condition is: a time-sensitive problem, as
- in if something happens at just the wrong time it won't behave
- as expected). For those architectures that have the "right"
+ conditions</em> involving the restart and die signals (a simply put,
+ a race condition is a time-sensitive problem - if something happens
+ at just the wrong time or things happen in the wrong order,
+ undesired behaviour will result. If the same thing happens at the right
+ time, all will be well). For those architectures that have the "right"
feature set we have eliminated as many as we can. But it should
- be noted that there still do exist race conditions on certain
+ be noted that race conditions do still exist on certain
architectures.</p>
- <p>Architectures that use an on disk <code class="directive"><a href="./mod/mpm_common.html#scoreboardfile">ScoreBoardFile</a></code> have the potential
- to corrupt their scoreboards. This can result in the "bind:
+ <p>Architectures that use an on-disk <code class="directive"><a href="./mod/mpm_common.html#scoreboardfile">ScoreBoardFile</a></code> can potentially have
+ their scoreboards corrupted. This can result in the "bind:
Address already in use" (after <code>HUP</code>) or "long lost
child came home!" (after <code>USR1</code>). The former is a fatal
error, while the latter just causes the server to lose a
- scoreboard slot. So it might be advisable to use graceful
+ scoreboard slot. So it may be advisable to use graceful
restarts, with an occasional hard restart. These problems are very
difficult to work around, but fortunately most architectures do
- not require a scoreboard file. See the <code class="directive"><a href="./mod/mpm_common.html#scoreboardfile">ScoreBoardFile</a></code> documentation for a
- architecture uses it.</p>
+ not require a scoreboard file. See the <code class="directive"><a href="./mod/mpm_common.html#scoreboardfile">ScoreBoardFile</a></code> documentation for
+ architecture which uses it.</p>
<p>All architectures have a small race condition in each child
involving the second and subsequent requests on a persistent
Thanks,
Noirin
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: PATCH: Language changes & fixes
Posted by Astrid Keßler <ke...@kess-net.de>.
> We did have a brief discussion here as to whether an attachment or
> inline text was more appropriate - the resident Apache developer
> suggested an attachment, but being new to this, I was anxious to do
> things by the book =)
Hehe, no problem :)
I've committed your patch. Thank you very much.
> Perhaps an update to Ken's doc on how to get started documenting is due
> - I'll write up the instructions on how to use svn, if you like (I was
> delighted with how easy it was!)
Oh, yes, that would really be fine. Many people have thought about an
update of this "newcomer" docs, but unfortunally it is one of the last
things updated. :/
Kess
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: PATCH: Language changes & fixes
Posted by André Malo <nd...@perlig.de>.
* Noirin Plunkett wrote:
> Andre,
> Does this mean I should diff before I run build.sh?
That's one possibility. Another one would be to run `svn revert' on the
generated files, or just diff only the xml files in question:
$ svn diff foo.xml bar.xml
(one could automate that with a bash one liner. Hmm - perhaps we should add
a target to the build system for such situtations, which runs exactly this
one liner, but written in many lines of ant xml ;-)
> If so, what's the best way to check that my XML is valid?
there's a validate-xml target, which helps, but actually building the files
is still the best.
nd
--
s s^saaaaaoaaaoaaaaooooaaoaaaomaaaa a alataa aaoat a a
a maoaa a laoata a oia a o a m a o alaoooat aaool aaoaa
matooololaaatoto aaa o a o ms;s;\s;s;g;y;s;:;s;y#mailto: #
\51/\134\137| http://www.perlig.de #;print;# > nd@perlig.de
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: PATCH: Language changes & fixes
Posted by Noirin Plunkett <fi...@nerdchic.net>.
On Mon, Aug 22, 2005 at 10:52:31PM +0200, André Malo wrote:
> * Noirin Plunkett wrote:
>
> > Perhaps an update to Ken's doc on how to get started documenting is due
> > - I'll write up the instructions on how to use svn, if you like (I was
> > delighted with how easy it was!)
> > Attached is my patch.
>
> Further you don't need to attach a patch of the html files. They are
> autogenerated ;-)
Andre,
Does this mean I should diff before I run build.sh?
If so, what's the best way to check that my XML is valid?
Thanks!
Noirin
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: PATCH: Language changes & fixes
Posted by André Malo <nd...@perlig.de>.
* Noirin Plunkett wrote:
> On Mon, Aug 22, 2005 at 10:19:03PM +0200, Astrid Ke?ler wrote:
> > Hi Noirin,
> >
> > it looks good for me, but I've difficulties to use the patch from your
> > mail. Could you please attach it as a separate file?
>
> We did have a brief discussion here as to whether an attachment or
> inline text was more appropriate - the resident Apache developer
> suggested an attachment, but being new to this, I was anxious to do
> things by the book =)
> Perhaps an update to Ken's doc on how to get started documenting is due
> - I'll write up the instructions on how to use svn, if you like (I was
> delighted with how easy it was!)
> Attached is my patch.
Further you don't need to attach a patch of the html files. They are
autogenerated ;-)
Thanks, nd
--
die (eval q-qq[Just Another Perl Hacker
]
;-)
# André Malo, <http://www.perlig.de/> #
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: PATCH: Language changes & fixes
Posted by Noirin Plunkett <fi...@nerdchic.net>.
On Mon, Aug 22, 2005 at 10:19:03PM +0200, Astrid Ke?ler wrote:
> Hi Noirin,
>
> it looks good for me, but I've difficulties to use the patch from your
> mail. Could you please attach it as a separate file?
>
We did have a brief discussion here as to whether an attachment or
inline text was more appropriate - the resident Apache developer
suggested an attachment, but being new to this, I was anxious to do
things by the book =)
Perhaps an update to Ken's doc on how to get started documenting is due
- I'll write up the instructions on how to use svn, if you like (I was
delighted with how easy it was!)
Attached is my patch.
Thanks
Noirin
Re: PATCH: Language changes & fixes
Posted by Astrid Keßler <ke...@kess-net.de>.
Hi Noirin,
> Hi there,
> I've been going through the Apache trunk docs, and have some
> language changes and fixes to suggest.
it looks good for me, but I've difficulties to use the patch from your
mail. Could you please attach it as a separate file?
Thank you.
Kess
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: PATCH: Language changes & fixes
Posted by Colm MacCarthaigh <co...@stdlib.net>.
On Fri, Sep 02, 2005 at 11:38:30AM +0100, Noirin Plunkett wrote:
> I've added this to the Certificates section - if you could review the
> updated patch (attached) and check that what I've added is right,
> that'd be great =)
+1 on this patch, it's taken me a while, but I've read and compared all
the changes and they all seem to be better.
--
Colm MacCárthaigh Public Key: colm+pgp@stdlib.net
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: PATCH: Language changes & fixes
Posted by Noirin Plunkett <fi...@nerdchic.net>.
On Fri, Sep 02, 2005 at 09:38:06AM +0100, Joe Orton wrote:
> On Thu, Sep 01, 2005 at 06:03:42PM +0100, Noirin Plunkett wrote:
> > On Mon, Aug 29, 2005 at 08:28:41PM +0100, Colm MacCarthaigh wrote:
> > > On Tue, Aug 23, 2005 at 03:20:54PM +0100, Noirin Plunkett wrote:
> > > > I've been going through the mod_ssl docs, and have some fixes and
> > > > language changes to suggest. I've also added a FAQ entry on how to
> > > > create a self-signed cert.
> >
> > I've included these patches again, in case anyone else has any further
> > suggestions on them.
>
> This is looking really good, thanks a lot. I do have suggestions, if
> you time :)
>
> 1. remove the entire "About Support" section - it's almost entirely
> outdated
I'm loathe to do this - if it's outdated, is there something more up to
date we could replace it with? If there really is nothing relevant in
it, then it can go, but I think it would be useful to at least keep the
first two, possibly three, questions, revised as necessary.
> 2. remove the stuff about the MM library, it's not true any more
Done.
> 3. remove the "When I access my website the first time via HTTPS I get a
> core dump?" -- not really relevant any more
Done.
> it would be great if there was a "how do I create a self-signed
> certificate for testing purposes?" section which explained to use
>
> openssl req -new -x509 -nodes -out conf/server.crt -keyout conf/server.key
>
> to get going quickly.
I've added this to the Certificates section - if you could review the
updated patch (attached) and check that what I've added is right,
that'd be great =)
Thanks for the feedback,
Noirin
Re: PATCH: Language changes & fixes
Posted by Joe Orton <jo...@redhat.com>.
On Thu, Sep 01, 2005 at 06:03:42PM +0100, Noirin Plunkett wrote:
> On Mon, Aug 29, 2005 at 08:28:41PM +0100, Colm MacCarthaigh wrote:
> > On Tue, Aug 23, 2005 at 03:20:54PM +0100, Noirin Plunkett wrote:
> > > I've been going through the mod_ssl docs, and have some fixes and
> > > language changes to suggest. I've also added a FAQ entry on how to
> > > create a self-signed cert.
>
> I've included these patches again, in case anyone else has any further
> suggestions on them.
This is looking really good, thanks a lot. I do have suggestions, if
you time :)
1. remove the entire "About Support" section - it's almost entirely
outdated
2. remove the stuff about the MM library, it's not true any more
3. remove the "When I access my website the first time via HTTPS I get a
core dump?" -- not really relevant any more
it would be great if there was a "how do I create a self-signed
certificate for testing purposes?" section which explained to use
openssl req -new -x509 -nodes -out conf/server.crt -keyout conf/server.key
to get going quickly.
joe
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: PATCH: Language changes & fixes
Posted by Noirin Plunkett <fi...@nerdchic.net>.
On Mon, Aug 29, 2005 at 08:28:41PM +0100, Colm MacCarthaigh wrote:
> On Tue, Aug 23, 2005 at 03:20:54PM +0100, Noirin Plunkett wrote:
> > I've been going through the mod_ssl docs, and have some fixes and
> > language changes to suggest. I've also added a FAQ entry on how to
> > create a self-signed cert.
I've included these patches again, in case anyone else has any further
suggestions on them.
> You seem to have uncovered a problem the SSL faq aswell, it refers to
> "sign.sh" ;
I've also gone over the SSL FAQ as best I can, from top to toe. I'd be
grateful for a few extra pairs of eyes to look over it though, just to
make sure I haven't inadvertently introduced any factual/technical
errors.
> That should probably be left alone, as it's refering to mod_ssl in its
> previous incarnation, rather than what's in httpd right now. But the
> rest looks good :)
I've removed that now, thanks!
Noirin
Re: PATCH: Language changes & fixes
Posted by Colm MacCarthaigh <co...@stdlib.net>.
On Tue, Aug 23, 2005 at 03:20:54PM +0100, Noirin Plunkett wrote:
> I've been going through the mod_ssl docs, and have some fixes and
> language changes to suggest. I've also added a FAQ entry on how to
> create a self-signed cert.
You seem to have uncovered a problem the SSL faq aswell, it refers to
"sign.sh" ;
http://httpd.apache.org/docs/2.1/ssl/ssl_faq.html#ownca
But this isn't shipped with Apache any more. The docs probably need
something more along the lines of
http://sial.org/howto/openssl/self-signed/
This isn't a problem with your patch though, just noticed it from
there.
> Index: manual/ssl/index.xml
> ===================================================================
> --- manual/ssl/index.xml (revision 239410)
> +++ manual/ssl/index.xml (working copy)
> @@ -31,7 +31,7 @@
> href="http://www.openssl.org/">OpenSSL</a> library, which provides
> Strong Encryption using the Secure Sockets Layer and Transport Layer
> Security protocols. The module and this documentation are based on
> -Ralf S. Engelschall's mod_ssl project.</p>
> +Ralf S. Engelschall's <module>mod_ssl</module> project.</p>
That should probably be left alone, as it's refering to mod_ssl in its
previous incarnation, rather than what's in httpd right now. But the
rest looks good :)
--
Colm MacCárthaigh Public Key: colm+pgp@stdlib.net
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: PATCH: Language changes & fixes
Posted by Colm MacCarthaigh <co...@stdlib.net>.
On Tue, Aug 23, 2005 at 03:20:54PM +0100, Noirin Plunkett wrote:
> sslfaq.patch -> FAQ entry on self-signing
> sslindex.patch & sslintro.patch -> patches for mod_ssl docs
Thanks! I've read and commited the sslintro changes. The FAQ change is
dependent on the other patch which being discussed, so I've left that
alone for now.
Just one nit, in some places you had tab characters, however the
httpd-docs project uses spaces (usually in groups of 4) instead of tabs
for indentation.
--
Colm MacCárthaigh Public Key: colm+pgp@stdlib.net
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: PATCH: Language changes & fixes
Posted by Noirin Plunkett <fi...@nerdchic.net>.
Hi there,
I've been going through the mod_ssl docs, and have some fixes and
language changes to suggest. I've also added a FAQ entry on how to
create a self-signed cert.
The patches attached are as follows:
sslfaq.patch -> FAQ entry on self-signing
sslindex.patch & sslintro.patch -> patches for mod_ssl docs
Thanks
Noirin