docs: howto/access.xml editorial cleanup and examples

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

diff --git a/docs/manual/howto/access.xml b/docs/manual/howto/access.xml
index 5861e124d94c379ffff65721e105167eb9e4be88..1581e4d9ca67e67614d45819f59e1c7a6872d93a 100644 (file)
--- a/docs/manual/howto/access.xml
+++ b/docs/manual/howto/access.xml
@@ -43,7 +43,7 @@
 <section id="host"><title>Access control by host</title>
     <p>
     If you wish to restrict access to portions of your site based on the
-    host address of your visitors, this is most easily done using
+    host address of your visitors, use
     <module>mod_authz_host</module>.
     </p>
 
@@ -67,10 +67,12 @@
 
     <p>The usage of these directives is:</p>
 
-    <highlight language="config">
+<example>
+<highlight language="config">
 Require host <var>address</var>
 Require ip <var>ip.address</var>
-    </highlight>
+</highlight>
+</example>
 
     <p>In the first form, <var>address</var> is a fully qualified
     domain name (or a partial domain name); you may provide multiple
@@ -80,12 +82,29 @@ Require ip <var>ip.address</var>
     partial IP address, a network/netmask pair, or a network/nnn CIDR
     specification. Either IPv4 or IPv6 addresses may be used.</p>
 
+<example><title>Examples of IP address formats</title>
+<highlight language="config">
+# Full IP address
+Require ip 10.2.3.4
+# Partial IP address (matches any host in the 172.20.0.0/16 range)
+Require ip 172.20
+# Network/netmask pair
+Require ip 192.168.1.0/255.255.255.0
+# Network/CIDR specification
+Require ip 192.168.1.0/24
+# IPv6 address
+Require ip 2001:db8::a00:20ff:fea7:ccea
+# IPv6 with CIDR
+Require ip 2001:db8:1::/48
+</highlight>
+</example>
+
     <p>See <a href="../mod/mod_authz_host.html#requiredirectives">the
     mod_authz_host documentation</a> for further examples of this
     syntax.</p>
 
     <p>You can insert <code>not</code> to negate a particular requirement.
-    Note, that since a <code>not</code> is a negation of a value, it cannot
+    Since a <code>not</code> is a negation of a value, it cannot
     be used by itself to allow or deny a request, as <em>not true</em>
     does not constitute <em>false</em>. Thus, to deny a visit using a negation,
     the block must have one element that evaluates as true or false.
@@ -93,30 +112,36 @@ Require ip <var>ip.address</var>
     board, and you want to keep them out, you could do the
     following:</p>
 
-    <highlight language="config">
+<example>
+<highlight language="config">
 &lt;RequireAll&gt;
-    Require all granted
-    Require not ip 10.252.46.165
+Require all granted
+Require not ip 10.252.46.165
 &lt;/RequireAll&gt;
-    </highlight>
+</highlight>
+</example>
 
     <p>Visitors coming from that address (<code>10.252.46.165</code>)
     will not be able to see the content covered by this directive. If,
     instead, you have a machine name, rather than an IP address, you
     can use that.</p>
 
-    <highlight language="config">
+<example>
+<highlight language="config">
 Require not host <var>host.example.com</var>
-    </highlight>
+</highlight>
+</example>
 
     <p>And, if you'd like to block access from an entire domain,
-    you can specify just part of an address or domain name:</p>
+    you can specify part of an address or domain name:</p>
 
-    <highlight language="config">
+<example>
+<highlight language="config">
 Require not ip 192.168.205
-Require not host phishers.example.com moreidiots.example
+Require not host phishers.example.com badguys.example
 Require not host gov
-    </highlight>
+</highlight>
+</example>
 
     <p>Use of the <directive
     module="mod_authz_core">RequireAll</directive>, <directive
@@ -134,19 +159,23 @@ Require not host gov
     based on user-agent (the browser type) you might do the
     following:</p>
 
-    <highlight language="config">
+<example>
+<highlight language="config">
 &lt;If "%{HTTP_USER_AGENT} == 'BadBot'"&gt;
-    Require all denied
+Require all denied
 &lt;/If&gt;
-    </highlight>
+</highlight>
+</example>
 
     <p>Using the <directive module="mod_authz_core">Require</directive>
     <code>expr</code> syntax, this could also be written as:</p>
 
 
-    <highlight language="config">
+<example>
+<highlight language="config">
 Require expr %{HTTP_USER_AGENT} != 'BadBot'
-    </highlight>
+</highlight>
+</example>
 
     <note><title>Warning:</title>
     <p>Access control by <code>User-Agent</code> is an unreliable technique,
@@ -170,12 +199,14 @@ Require expr %{HTTP_USER_AGENT} != 'BadBot'
     <p>For example, if you wish to block access to a resource between 8pm
     and 7am, you can do this using <module>mod_rewrite</module>.</p>
 
-    <highlight language="config">
+<example>
+<highlight language="config">
 RewriteEngine On
 RewriteCond "%{TIME_HOUR}" "&gt;=20" [OR]
 RewriteCond "%{TIME_HOUR}" "&lt;07"
 RewriteRule "^/fridge"     "-"       [F]
-    </highlight>
+</highlight>
+</example>
 
     <p>This will return a 403 Forbidden response for any request after 8pm
     or before 7am. This technique can be used for any criteria that you wish