From: Eric Covener <covener@apache.org>
Date: Mon, 28 Dec 2015 18:24:39 +0000 (+0000)
Subject: Merge r1721973 from trunk:
X-Git-Tag: 2.4.19~331
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=f2f0a2426415ca4d14a184847d77421043c5425a;p=apache

Merge r1721973 from trunk:

PR58761: developer doc improvements.

Submitted By: Luca Toscano




git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x@1721974 13f79535-47bb-0310-9956-ffa450edef68
---

diff --git a/docs/manual/developer/filters.html.en b/docs/manual/developer/filters.html.en
index 7af339ba64..e5db22fc4f 100644
--- a/docs/manual/developer/filters.html.en
+++ b/docs/manual/developer/filters.html.en
@@ -105,12 +105,14 @@
     <p>This is actually rather simple in theory, but the code is
     complex.  First of all, it is important that everybody realize that
     there are three filter lists for each request, but they are all
-    concatenated together.  So, the first list is
-    <code>r-&gt;output_filters</code>, then <code>r-&gt;proto_output_filters</code>,
-    and finally <code>r-&gt;connection-&gt;output_filters</code>. These correspond
-    to the <code>RESOURCE</code>, <code>PROTOCOL</code>, and
-    <code>CONNECTION</code> filters respectively. The problem previously, was
-    that we used a singly linked list to create the filter stack, and we
+    concatenated together:</p>
+    <ul>
+        <li><code>r-&gt;output_filters</code> (corresponds to RESOURCE)</li>
+        <li><code>r-&gt;proto_output_filters</code> (corresponds to PROTOCOL)</li>
+        <li><code>r-&gt;connection-&gt;output_filters</code> (corresponds to CONNECTION)</li>
+    </ul> 
+    
+    <p>The problem previously, was that we used a singly linked list to create the filter stack, and we
     started from the "correct" location.  This means that if I had a
     <code>RESOURCE</code> filter on the stack, and I added a
     <code>CONNECTION</code> filter, the <code>CONNECTION</code> filter would
diff --git a/docs/manual/developer/filters.xml b/docs/manual/developer/filters.xml
index 5e44ababc5..e4b42253d0 100644
--- a/docs/manual/developer/filters.xml
+++ b/docs/manual/developer/filters.xml
@@ -99,12 +99,14 @@
     <p>This is actually rather simple in theory, but the code is
     complex.  First of all, it is important that everybody realize that
     there are three filter lists for each request, but they are all
-    concatenated together.  So, the first list is
-    <code>r->output_filters</code>, then <code>r->proto_output_filters</code>,
-    and finally <code>r->connection->output_filters</code>. These correspond
-    to the <code>RESOURCE</code>, <code>PROTOCOL</code>, and
-    <code>CONNECTION</code> filters respectively. The problem previously, was
-    that we used a singly linked list to create the filter stack, and we
+    concatenated together:</p>
+    <ul>
+        <li><code>r->output_filters</code> (corresponds to RESOURCE)</li>
+        <li><code>r->proto_output_filters</code> (corresponds to PROTOCOL)</li>
+        <li><code>r->connection->output_filters</code> (corresponds to CONNECTION)</li>
+    </ul> 
+    
+    <p>The problem previously, was that we used a singly linked list to create the filter stack, and we
     started from the "correct" location.  This means that if I had a
     <code>RESOURCE</code> filter on the stack, and I added a
     <code>CONNECTION</code> filter, the <code>CONNECTION</code> filter would
diff --git a/docs/manual/developer/hooks.html.en b/docs/manual/developer/hooks.html.en
index c00af2ccd3..7b1f133d5c 100644
--- a/docs/manual/developer/hooks.html.en
+++ b/docs/manual/developer/hooks.html.en
@@ -36,11 +36,29 @@
     Modules can provide functions that are called, and specify when 
     they get called in comparison to other modules.</p>
 </div>
-<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#create">Creating a hook function</a></li>
+<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#corehooks">Core Hooks</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#create">Creating a hook function</a></li>
 <li><img alt="" src="../images/down.gif" /> <a href="#hooking">Hooking the hook</a></li>
 </ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 <div class="section">
+<h2><a name="corehooks" id="corehooks">Core Hooks</a></h2>
+    <p>The httpd's core modules offer a predefinined list of hooks
+    used during the standard <a href="./request.html">request processing</a>
+    phase. Creating a new hook will expose a function that 
+    implements it (see sections below) but it is essential to undestand that you will not 
+    extend the httpd's core hooks. Their presence and order in the request processing is in fact 
+    a consequence of how they are called in <code>server/request.c</code> 
+    (check <a href="./modguide.html#hooking">this section</a> 
+    for an overview). The core hooks are listed in the 
+    <a href="https://ci.apache.org/projects/httpd/trunk/doxygen/group__hooks.html">doxygen documentation</a>.</p>
+
+    <p>Reading <a href="./modguide.html">guide for developing modules</a> and 
+    <a href="./request.html">request processing</a> before proceeding is 
+    highly recomended.
+    </p> 
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
 <h2><a name="create" id="create">Creating a hook function</a></h2>
     <p>In order to create a new hook, four things need to be
     done:</p>
@@ -172,7 +190,8 @@ mode MODULE_VAR_EXPORT my_module =
 
     <h3><a name="hooking-order" id="hooking-order">Controlling hook calling order</a></h3>
       <p>In the example above, we didn't use the three arguments in
-      the hook registration function that control calling order.
+      the hook registration function that control calling order of 
+      all the functions registered within the hook.
       There are two mechanisms for doing this. The first, rather
       crude, method, allows us to specify roughly where the hook is
       run relative to other modules. The final argument control this.
diff --git a/docs/manual/developer/hooks.xml b/docs/manual/developer/hooks.xml
index e9a5c5f52e..3f6651014f 100644
--- a/docs/manual/developer/hooks.xml
+++ b/docs/manual/developer/hooks.xml
@@ -37,6 +37,23 @@
     they get called in comparison to other modules.</p>
 </summary>
 
+<section id="corehooks"><title>Core Hooks</title>
+    <p>The httpd's core modules offer a predefinined list of hooks
+    used during the standard <a href="./request.html">request processing</a>
+    phase. Creating a new hook will expose a function that 
+    implements it (see sections below) but it is essential to undestand that you will not 
+    extend the httpd's core hooks. Their presence and order in the request processing is in fact 
+    a consequence of how they are called in <code>server/request.c</code> 
+    (check <a href="./modguide.html#hooking">this section</a> 
+    for an overview). The core hooks are listed in the 
+    <a href="https://ci.apache.org/projects/httpd/trunk/doxygen/group__hooks.html">doxygen documentation</a>.</p>
+
+    <p>Reading <a href="./modguide.html">guide for developing modules</a> and 
+    <a href="./request.html">request processing</a> before proceeding is 
+    highly recomended.
+    </p> 
+</section>
+
 <section id="create"><title>Creating a hook function</title>
     <p>In order to create a new hook, four things need to be
     done:</p>
@@ -177,7 +194,8 @@ mode MODULE_VAR_EXPORT my_module =
 
     <section id="hooking-order"><title>Controlling hook calling order</title>
       <p>In the example above, we didn't use the three arguments in
-      the hook registration function that control calling order.
+      the hook registration function that control calling order of 
+      all the functions registered within the hook.
       There are two mechanisms for doing this. The first, rather
       crude, method, allows us to specify roughly where the hook is
       run relative to other modules. The final argument control this.
diff --git a/docs/manual/developer/index.html.en b/docs/manual/developer/index.html.en
index 5a98852846..98b5b26de9 100644
--- a/docs/manual/developer/index.html.en
+++ b/docs/manual/developer/index.html.en
@@ -30,9 +30,8 @@
     <div class="warning"><h3>Warning</h3>
     <p>Many of the documents listed here are in need of update.
     They are in different stages of progress.
-    Please be patient, and point out any discrepancies or
-    errors on the developer/ pages directly to the
-    <a href="http://httpd.apache.org/lists.html#http-dev">dev@httpd.apache.org</a> mailing list.</p>
+    Please be patient and follow <a href="https://httpd.apache.org/docs-project/">this link</a>
+    to propose a fix or point out any error/discrepancy.</p>
     </div>
 </div>
 <div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#developing">2.4 development documents</a></li>
@@ -62,7 +61,9 @@
 <div class="section">
 <h2><a name="external" id="external">External Resources</a></h2>
     <ul>
-      <li><a href="http://ci.apache.org/projects/httpd/trunk/doxygen/">Autogenerated Apache HTTP Server (trunk) code documentation</a></li>
+      <li><a href="http://ci.apache.org/projects/httpd/trunk/doxygen/">Autogenerated Apache HTTP Server (trunk) code documentation</a> (the link is built by
+        this <a href="https://ci.apache.org/builders/httpd-doxygen-nightly">job</a>).
+      </li>
 
       <li>Developer articles at <a href="http://www.apachetutor.org/">apachetutor</a> include:
       <ul>
diff --git a/docs/manual/developer/index.xml b/docs/manual/developer/index.xml
index e7cba43105..ccbba6f792 100644
--- a/docs/manual/developer/index.xml
+++ b/docs/manual/developer/index.xml
@@ -29,10 +29,8 @@
     <note type="warning"><title>Warning</title>
     <p>Many of the documents listed here are in need of update.
     They are in different stages of progress.
-    Please be patient, and point out any discrepancies or
-    errors on the developer/ pages directly to the
-    <a href="http://httpd.apache.org/lists.html#http-dev"
-    >dev@httpd.apache.org</a> mailing list.</p>
+    Please be patient and follow <a href="https://httpd.apache.org/docs-project/">this link</a>
+    to propose a fix or point out any error/discrepancy.</p>
     </note>
 </summary>
 
@@ -59,7 +57,9 @@
     <ul>
       <li><a
         href="http://ci.apache.org/projects/httpd/trunk/doxygen/"
-        >Autogenerated Apache HTTP Server (trunk) code documentation</a></li>
+        >Autogenerated Apache HTTP Server (trunk) code documentation</a> (the link is built by
+        this <a href="https://ci.apache.org/builders/httpd-doxygen-nightly">job</a>).
+      </li>
 
       <li>Developer articles at <a href="http://www.apachetutor.org/">apachetutor</a> include:
       <ul>
diff --git a/docs/manual/developer/request.html.en b/docs/manual/developer/request.html.en
index 75b8b7508e..e139f0f0a7 100644
--- a/docs/manual/developer/request.html.en
+++ b/docs/manual/developer/request.html.en
@@ -63,15 +63,15 @@
 <div class="section">
 <h2><a name="processing" id="processing">The Request Processing Cycle</a></h2>
     <p>All requests pass through <code>ap_process_request_internal()</code>
-    in <code>request.c</code>, including subrequests and redirects. If a module
+    in <code>server/request.c</code>, including subrequests and redirects. If a module
     doesn't pass generated requests through this code, the author is cautioned
     that the module may be broken by future changes to request
     processing.</p>
 
     <p>To streamline requests, the module author can take advantage
-    of the hooks offered to drop out of the request cycle early, or
-    to bypass core hooks which are irrelevant (and costly in
-    terms of CPU.)</p>
+    of the <a href="./modguide.html#hooking">hooks offered</a> to drop 
+    out of the request cycle early, or to bypass core hooks which are 
+    irrelevant (and costly in terms of CPU.)</p>
 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 <div class="section">
 <h2><a name="parsing" id="parsing">The Request Parsing Phase</a></h2>
diff --git a/docs/manual/developer/request.xml b/docs/manual/developer/request.xml
index b54e41e3d0..8c329b4b26 100644
--- a/docs/manual/developer/request.xml
+++ b/docs/manual/developer/request.xml
@@ -56,15 +56,15 @@
 
 <section id="processing"><title>The Request Processing Cycle</title>
     <p>All requests pass through <code>ap_process_request_internal()</code>
-    in <code>request.c</code>, including subrequests and redirects. If a module
+    in <code>server/request.c</code>, including subrequests and redirects. If a module
     doesn't pass generated requests through this code, the author is cautioned
     that the module may be broken by future changes to request
     processing.</p>
 
     <p>To streamline requests, the module author can take advantage
-    of the hooks offered to drop out of the request cycle early, or
-    to bypass core hooks which are irrelevant (and costly in
-    terms of CPU.)</p>
+    of the <a href="./modguide.html#hooking">hooks offered</a> to drop 
+    out of the request cycle early, or to bypass core hooks which are 
+    irrelevant (and costly in terms of CPU.)</p>
 </section>
 
 <section id="parsing"><title>The Request Parsing Phase</title>