From c1980adcd69f0b5b7086bf3be087edd9fd60c19e Mon Sep 17 00:00:00 2001
From: Eric Covener <covener@apache.org>
Date: Mon, 28 Dec 2015 18:23:36 +0000
Subject: [PATCH] PR58761: developer doc improvements.

Submitted By: Luca Toscano



git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1721973 13f79535-47bb-0310-9956-ffa450edef68
---
 docs/manual/developer/filters.html.en | 14 ++++++++------
 docs/manual/developer/filters.xml     | 14 ++++++++------
 docs/manual/developer/hooks.html.en   | 23 +++++++++++++++++++++--
 docs/manual/developer/hooks.xml       | 20 +++++++++++++++++++-
 docs/manual/developer/index.html.en   |  9 +++++----
 docs/manual/developer/index.xml       | 10 +++++-----
 docs/manual/developer/request.html.en |  8 ++++----
 docs/manual/developer/request.xml     |  8 ++++----
 8 files changed, 74 insertions(+), 32 deletions(-)

diff --git a/docs/manual/developer/filters.html.en b/docs/manual/developer/filters.html.en
index a91dd847ad8..084239b0e7d 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 5e44ababc53..e4b42253d05 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 28d05af542b..3692a9c68a1 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 fcd4ce07eb3..bba2d184f23 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 cfd1de89f0a..bed6a5f66e6 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 e7cba431059..ccbba6f7928 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 9b0cb07de2d..16d0cfee757 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 3bc48c27b74..3d1a2e34439 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>
-- 
2.47.3