Updated the diff (attached patch.txt) with new links that I believe would
make the /developer documents a bit more clear. Validated everything using
./build.sh validate-xml/xhtml.
Please let me know if you like the idea or if you want me to drop
everything :)
Thanks!
Luca
2015-12-19 12:15 GMT+01:00 Luca Toscano <toscano.l...@gmail.com>:
> Hi Apache devs,
>
> after asking some questions in the IRC channel I decided to add some notes
> to the docs/developer pages. I've attached a very small patch to this email
> generated from svn diff (as stated in
> https://httpd.apache.org/dev/patches.html) against the last commit of the
> trunk branch. I've also followed
> http://httpd.apache.org/docs-project/docsformat.html for the
> build/validation steps.
>
> If you like the idea I would be available to start reviewing all the
> developer docs to add more info and update dead/broken links (possibly
> asking you more questions of the IRC channel). I would really love to start
> contributing to the httpd project and this might be a good starting point.
> Please also let me know if you have ideas about areas that are not covered
> well enough, I could add more sections as well (for example: how mpm_event
> works, what resources must be read before submitting code, etc...)
>
> Let me know!
>
> Luca
>
Index: docs/manual/developer/filters.xml
===================================================================
--- docs/manual/developer/filters.xml (revision 1721404)
+++ docs/manual/developer/filters.xml (working copy)
@@ -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
Index: docs/manual/developer/hooks.xml
===================================================================
--- docs/manual/developer/hooks.xml (revision 1721404)
+++ docs/manual/developer/hooks.xml (working copy)
@@ -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 @@
<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.
Index: docs/manual/developer/index.xml
===================================================================
--- docs/manual/developer/index.xml (revision 1721404)
+++ docs/manual/developer/index.xml (working copy)
@@ -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";
- >d...@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>
Index: docs/manual/developer/request.xml
===================================================================
--- docs/manual/developer/request.xml (revision 1721404)
+++ docs/manual/developer/request.xml (working copy)
@@ -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>
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscr...@httpd.apache.org
For additional commands, e-mail: docs-h...@httpd.apache.org
