Minor grammar tweaks and style-guide updates.

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1935516 13f79535-47bb-0310-9956-ffa450edef68

diff --git a/docs/manual/howto/public_html.xml b/docs/manual/howto/public_html.xml
index 16d05ce1030070382104b70cdf914daadc246e38..82ed2de686f8bb2cfbad7818afaf9f4dfdc398c1 100644 (file)
--- a/docs/manual/howto/public_html.xml
+++ b/docs/manual/howto/public_html.xml
@@ -33,17 +33,25 @@
     out of the home directory of the user "<code>username</code>", out of
     the subdirectory specified by the <directive
     module="mod_userdir">UserDir</directive> directive.</p>
-<p>Note that, by default, access to these directories is <strong>not</strong>
+<p>By default, access to these directories is <strong>not</strong>
     enabled. You can enable access when using <directive module="mod_userdir"
     >UserDir</directive> by uncommenting the line:</p>
-    <highlight language="config">
-      #Include conf/extra/httpd-userdir.conf
-    </highlight>
+<example>
+<highlight language="config">
+#Include conf/extra/httpd-userdir.conf
+</highlight>
+</example>
     <p>in the default config file <code>conf/httpd.conf</code>, and adapting the <code
     >httpd-userdir.conf</code>
     file as necessary, or by including the appropriate directives in a
     <directive module="core" type="section">Directory</directive> block
     within the main config file.</p>
+
+    <note>Third-party distributions of httpd (from your OS vendor or
+    package manager) often place the <module>mod_userdir</module>
+    configuration in a separate file, and may enable it by default.
+    Check your distribution's documentation for specifics. The examples
+    in this document assume a default source build of httpd.</note>
 </summary>
 
 <seealso><a href="../urlmapping.html">Mapping URLs to the Filesystem</a></seealso>
@@ -73,9 +81,11 @@
     assumed to be a directory path relative to the home directory of the
     specified user. Given this configuration:</p>
 
-    <highlight language="config">
+<example>
+<highlight language="config">
 UserDir public_html
-    </highlight>
+</highlight>
+</example>
 
     <p>the URL <code>http://example.com/~rbowen/file.html</code> will be
     translated to the file path
@@ -85,9 +95,11 @@ UserDir public_html
     constructed using that path, plus the username specified. Given this
     configuration:</p>
 
-    <highlight language="config">
+<example>
+<highlight language="config">
 UserDir /var/html
-    </highlight>
+</highlight>
+</example>
 
     <p>the URL <code>http://example.com/~rbowen/file.html</code> will be
     translated to the file path <code>/var/html/rbowen/file.html</code></p>
@@ -96,9 +108,11 @@ UserDir /var/html
     in which the asterisk is replaced with the username. Given this
     configuration:</p>
 
-    <highlight language="config">
+<example>
+<highlight language="config">
 UserDir /var/www/*/docs
-    </highlight>
+</highlight>
+</example>
 
     <p>the URL <code>http://example.com/~rbowen/file.html</code> will be
     translated to the file path
@@ -106,15 +120,17 @@ UserDir /var/www/*/docs
 
     <p>Multiple directories or directory paths can also be set.</p>
 
-    <highlight language="config">
+<example>
+<highlight language="config">
 UserDir public_html /var/html
-    </highlight>
+</highlight>
+</example>
 
-    <p>For the URL <code>http://example.com/~rbowen/file.html</code>,
-    Apache will search for <code>~rbowen</code>. If it isn't found,
-    Apache will search for <code>rbowen</code> in <code>/var/html</code>. If
-    found, the above URL will then be translated to the file path
-    <code>/var/html/rbowen/file.html</code></p>
+    <p>The arguments are considered in the order they appear.
+    For the URL <code>http://example.com/~rbowen/file.html</code>,
+    httpd will search for <code>~rbowen</code>. If it isn't found,
+    httpd will then search for <code>rbowen</code> in <code>/var/html</code>. 
+    The file will be served from whichever location is found first.</p>
 
   </section>
 
@@ -123,9 +139,11 @@ UserDir public_html /var/html
     <p>The <directive module="mod_userdir">UserDir</directive> directive can be
       used to redirect user directory requests to external URLs.</p>
 
-    <highlight language="config">
+<example>
+<highlight language="config">
 UserDir http://example.org/users/*/
-    </highlight>
+</highlight>
+</example>
 
     <p>The above example will redirect a request for
     <code>http://example.com/~bob/abc.html</code> to
@@ -139,19 +157,23 @@ UserDir http://example.org/users/*/
     <p>Using the syntax shown in the UserDir documentation, you can restrict
     what users are permitted to use this functionality:</p>
 
-    <highlight language="config">
+<example>
+<highlight language="config">
 UserDir disabled root jro fish
-    </highlight>
+</highlight>
+</example>
 
     <p>The configuration above will enable the feature for all users
     except for those listed in the <code>disabled</code> statement.
     You can, likewise, disable the feature for all but a few users by
     using a configuration like the following:</p>
 
-    <highlight language="config">
+<example>
+<highlight language="config">
 UserDir disabled
 UserDir enabled rbowen krietz
-    </highlight>
+</highlight>
+</example>
 
     <p>See <directive module="mod_userdir">UserDir</directive>
     documentation for additional examples.</p>
@@ -161,17 +183,19 @@ UserDir enabled rbowen krietz
   <section id="cgi">
   <title>Enabling a cgi directory for each user</title>
 
-   <p>In order to give each user their own cgi-bin directory, you can use
+   <p>To give each user their own cgi-bin directory, you can use
     a <directive module="core" type="section">Directory</directive>
     directive to make a particular subdirectory of a user's home directory
     cgi-enabled.</p>
 
-    <highlight language="config">
+<example>
+<highlight language="config">
 &lt;Directory "/home/*/public_html/cgi-bin/"&gt;
-    Options ExecCGI
-    SetHandler cgi-script
+Options ExecCGI
+SetHandler cgi-script
 &lt;/Directory&gt;
-    </highlight>
+</highlight>
+</example>
 
     <p>Then, presuming that <code>UserDir</code> is set to
     <code>public_html</code>, a cgi program <code>example.cgi</code>
@@ -186,7 +210,7 @@ UserDir enabled rbowen krietz
     <section id="htaccess">
     <title>Allowing users to alter configuration</title>
 
-    <p>If you want to allows users to modify the server configuration in
+    <p>If you want to allow users to modify the server configuration in
     their web space, they will need to use <code>.htaccess</code> files to
     make these changes. Ensure that you have set <directive
     module="core">AllowOverride</directive> to a