httpd-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From j...@apache.org
Subject svn commit: r1334814 [1/3] - /httpd/site/trunk/content/dev/
Date Sun, 06 May 2012 22:53:20 GMT
Author: joes
Date: Sun May  6 22:53:19 2012
New Revision: 1334814

URL: http://svn.apache.org/viewvc?rev=1334814&view=rev
Log:
xforms

Added:
    httpd/site/trunk/content/dev/debugging.mdtext
      - copied, changed from r1334802, httpd/site/trunk/content/dev/debugging.xml
    httpd/site/trunk/content/dev/devnotes.mdtext
      - copied, changed from r1334802, httpd/site/trunk/content/dev/devnotes.xml
    httpd/site/trunk/content/dev/guidelines.mdtext
      - copied, changed from r1334802, httpd/site/trunk/content/dev/guidelines.xml
    httpd/site/trunk/content/dev/how-to-release.mdtext
      - copied, changed from r1334802, httpd/site/trunk/content/dev/how-to-release.xml
    httpd/site/trunk/content/dev/index.mdtext
      - copied, changed from r1334802, httpd/site/trunk/content/dev/index.xml
    httpd/site/trunk/content/dev/patches.mdtext
      - copied, changed from r1334802, httpd/site/trunk/content/dev/patches.xml
    httpd/site/trunk/content/dev/release.mdtext
      - copied, changed from r1334802, httpd/site/trunk/content/dev/release.xml
    httpd/site/trunk/content/dev/styleguide.mdtext
      - copied, changed from r1334802, httpd/site/trunk/content/dev/styleguide.xml
    httpd/site/trunk/content/dev/verification.mdtext
      - copied, changed from r1334802, httpd/site/trunk/content/dev/verification.xml
Removed:
    httpd/site/trunk/content/dev/debugging.xml
    httpd/site/trunk/content/dev/devnotes.xml
    httpd/site/trunk/content/dev/guidelines.xml
    httpd/site/trunk/content/dev/how-to-release.xml
    httpd/site/trunk/content/dev/index.xml
    httpd/site/trunk/content/dev/patches.xml
    httpd/site/trunk/content/dev/release.xml
    httpd/site/trunk/content/dev/styleguide.xml
    httpd/site/trunk/content/dev/verification.xml

Copied: httpd/site/trunk/content/dev/debugging.mdtext (from r1334802, httpd/site/trunk/content/dev/debugging.xml)
URL: http://svn.apache.org/viewvc/httpd/site/trunk/content/dev/debugging.mdtext?p2=httpd/site/trunk/content/dev/debugging.mdtext&p1=httpd/site/trunk/content/dev/debugging.xml&r1=1334802&r2=1334814&rev=1334814&view=diff
==============================================================================
--- httpd/site/trunk/content/dev/debugging.xml (original)
+++ httpd/site/trunk/content/dev/debugging.mdtext Sun May  6 22:53:19 2012
@@ -1,188 +1,193 @@
-<?xml version="1.0"?>
-<document>
-  <properties>
-    <author email="docs@httpd.apache.org">Documentation Group</author>
-    <title>Apache HTTPD Debugging Guide</title>
-  </properties>
-<body>
-
-<section id="id">
-<title>Apache Debugging Guide</title>
-
-<p>This document is a collection of notes regarding tools and techniques
-for debugging Apache httpd and its modules.</p>
-
-<p>Got more tips?  Send 'em to
-<a href="mailto:docs@httpd.apache.org">docs@httpd.apache.org</a>.  Thanks!</p>
-
-<ol>
-<li><a href="#gdb">Using <code>gdb</code></a></li>
-<li><a href="#backtrace">Getting a live backtrace on unix</a></li>
-<li><a href="#backtrace-win">Getting a live backtrace on Windows</a></li>
-<li><a href="#crashes">Debugging intermittent crashes</a></li>
-<li><a href="#truss">Using '<code>truss/trace/strace</code>' to
-    trace system calls and signals</a></li>
-<li><a href="#gcore">Getting the server to dump core</a></li>
-<li><a href="#sol27">Solaris and coredumps</a></li>
-<li><a href="#tcpdump">Getting and analyzing a TCP packet trace</a></li>
-</ol>
-</section>
-
-<section id="gdb">
-<title>Using gdb</title>
-
-<p>If you use the gcc compiler, it is likely that the best
-debugger for your system is gdb.  This is only a brief summary of how
-to run gdb on Apache -- you should look at the info and man files for
-gdb to get more information on gdb commands and common debugging techniques.
-Before running gdb, be sure that the server is compiled with the
-<code>-g</code> option in <code>CFLAGS</code> to include the
-symbol information in the object files.</p>
-
-<p>The only tricky part of running gdb on Apache is forcing the server
-into a single-process mode so that the parent process being debugged 
-does the request-handling work instead of forking child processes.
-We have provided the <code>-X</code> option for that purpose, which will
-work fine for most cases.  However, some modules don't like starting
-up with <code>-X</code>, but are happy if you force only one child to run
-(using "<code>MaxClients 1</code>"); you can then use gdb's attach command
-to debug the child server.</p>
+Title: Apache HTTPD Debugging Guide
+Notice:    Licensed to the Apache Software Foundation (ASF) under one
+           or more contributor license agreements.  See the NOTICE file
+           distributed with this work for additional information
+           regarding copyright ownership.  The ASF licenses this file
+           to you under the Apache License, Version 2.0 (the
+           "License"); you may not use this file except in compliance
+           with the License.  You may obtain a copy of the License at
+           .
+             http://www.apache.org/licenses/LICENSE-2.0
+           .
+           Unless required by applicable law or agreed to in writing,
+           software distributed under the License is distributed on an
+           "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+           KIND, either express or implied.  See the License for the
+           specific language governing permissions and limitations
+           under the License.
+
+This document is a collection of notes regarding tools and techniques for
+debugging Apache httpd and its modules.
+
+Got more tips? Send 'em to
+[docs@httpd.apache.org](mailto:docs@httpd.apache.org). Thanks!
+
+1.  [Using](#gdb) 
+
+1.  [Getting a live backtrace on unix](#backtrace) 
+
+1.  [Getting a live backtrace on Windows](#backtrace-win) 
+
+1.  [Debugging intermittent crashes](#crashes) 
+
+1.  [Using '](#truss) 
+
+1.  [Getting the server to dump core](#gcore) 
+
+1.  [Solaris and coredumps](#sol27) 
+
+1.  [Getting and analyzing a TCP packet trace](#tcpdump) 
+
+# Using gdb # {#gdb}
+
+If you use the gcc compiler, it is likely that the best debugger for your
+system is gdb. This is only a brief summary of how to run gdb on Apache --
+you should look at the info and man files for gdb to get more information
+on gdb commands and common debugging techniques. Before running gdb, be
+sure that the server is compiled with the `-g` option in `CFLAGS` to
+include the symbol information in the object files.
+
+The only tricky part of running gdb on Apache is forcing the server into a
+single-process mode so that the parent process being debugged does the
+request-handling work instead of forking child processes. We have provided
+the `-X` option for that purpose, which will work fine for most cases.
+However, some modules don't like starting up with `-X` , but are happy if
+you force only one child to run (using " `MaxClients 1` "); you can then
+use gdb's attach command to debug the child server.
 
-<p>The following example, with <font color="green">user input in green</font>,
+The following example, with<font color="green">user input in green</font>,
 shows the output of gdb run on a server executable (httpd) in the current
-working directory and using the server root of 
-<code>/usr/local/apache</code>:</p>
-
+working directory and using the server root of `/usr/local/apache` :
 <pre>
-    % <font color="green">gdb httpd</font>
+    % gdb httpd
     GDB is free software and you are welcome to distribute copies of it
      under certain conditions; type "show copying" to see the conditions.
-    There is absolutely no warranty for GDB; type "show warranty" for details.
+    There is absolutely no warranty for GDB; type "show warranty" for
+    details.
     GDB 4.16.gnat.1.13 (sparc-sun-solaris2.5), 
     Copyright 1996 Free Software Foundation, Inc...
-    (gdb) <font color="green">b ap_process_request</font>
+    (gdb) b ap_process_request
     Breakpoint 1 at 0x49fb4: file http_request.c, line 1164.
-    (gdb) <font color="green">run -X -d /usr/local/apache</font>
+    (gdb) run -X -d /usr/local/apache
     Starting program: /usr/local/apache/src/httpd -X -d /usr/local/apache
-    
+
     [at this point I make a request from another window]
 
     Breakpoint 1, ap_process_request (r=0x95250) at http_request.c:1164
-    1164        if (ap_extended_status)
-    (gdb) <font color="green">s</font>
-    1165            ap_time_process_request(r-&gt;connection-&gt;child_num, ...
-    (gdb) <font color="green">n</font>
-    1167        process_request_internal(r);
-    (gdb) <font color="green">s</font>
+    1164	if (ap_extended_status)
+    (gdb) s
+    1165	   
+    ap_time_process_request(r-&gt;connection-&gt;child_num,...
+    (gdb) n
+    1167	process_request_internal(r);
+    (gdb) s
     process_request_internal (r=0x95250) at http_request.c:1028
-    1028        if (!r-&gt;proxyreq &amp;&amp; r-&gt;parsed_uri.path) {
-    (gdb) <font color="green">s</font>
-    1029            access_status = ap_unescape_url(r-&gt;parsed_uri.path);
-    (gdb) <font color="green">n</font>
-    1030            if (access_status) {
-    (gdb) <font color="green">s</font>
-    1036        ap_getparents(r-&gt;uri);     /* OK ...
-    (gdb) <font color="green">n</font>
-    1038        if ((access_status = location_walk(r))) {
-    (gdb) <font color="green">n</font>
-    1043        if ((access_status = ap_translate_name(r))) {
-    (gdb) <font color="green">n</font>
-    1048        if (!r-&gt;proxyreq) {
-    (gdb) <font color="green">n</font>
-    1053            if (r-&gt;method_number == M_TRACE) {
-    (gdb) <font color="green">n</font>
-    1062        if (r-&gt;proto_num &gt; HTTP_VERSION(1,0) &amp;&amp; ap_ ...
-    (gdb) <font color="green">n</font>
-    1071        if ((access_status = directory_walk(r))) {
-    (gdb) <font color="green">s</font>
+    1028	if (!r-&gt;proxyreq &amp;&amp; r-&gt;parsed_uri.path) {
+    (gdb) s
+    1029	    access_status = ap_unescape_url(r-&gt;parsed_uri.path);
+    (gdb) n
+    1030	    if (access_status) {
+    (gdb) s
+    1036	ap_getparents(r-&gt;uri);     /* OK...
+    (gdb) n
+    1038	if ((access_status = location_walk(r))) {
+    (gdb) n
+    1043	if ((access_status = ap_translate_name(r))) {
+    (gdb) n
+    1048	if (!r-&gt;proxyreq) {
+    (gdb) n
+    1053	    if (r-&gt;method_number == M_TRACE) {
+    (gdb) n
+    1062	if (r-&gt;proto_num &gt; HTTP_VERSION(1,0) &amp;&amp;
+    ap_...
+    (gdb) n
+    1071	if ((access_status = directory_walk(r))) {
+    (gdb) s
     directory_walk (r=0x95250) at http_request.c:288
-    288         core_server_config *sconf = ap_get_module_ ...
-    (gdb) <font color="green">b ap_send_error_response</font>
+    288 	core_server_config *sconf = ap_get_module_...
+    (gdb) b ap_send_error_response
     Breakpoint 2 at 0x47dcc: file http_protocol.c, line 2090.
-    (gdb) <font color="green">c</font>
+    (gdb) c
     Continuing.
-    
+
     Breakpoint 2, ap_send_error_response (r=0x95250, recursive_error=0)
-        at http_protocol.c:2090
-    2090        BUFF *fd = r-&gt;connection-&gt;client;
-    (gdb) <font color="green">where</font>
-    #0  ap_send_error_response (r=0x95250, recursive_error=0)
-        at http_protocol.c:2090
-    #1  0x49b10 in ap_die (type=403, r=0x95250) at http_request.c:989
-    #2  0x49b60 in decl_die (status=403, phase=0x62db8 "check access", r=0x95250)
-        at http_request.c:1000
-    #3  0x49f68 in process_request_internal (r=0x95250) at http_request.c:1141
-    #4  0x49fe0 in ap_process_request (r=0x95250) at http_request.c:1167
-    #5  0x439d8 in child_main (child_num_arg=550608) at http_main.c:3826
-    #6  0x43b5c in make_child (s=0x7c3e8, slot=0, now=907958743)
-        at http_main.c:3898
-    #7  0x43ca8 in startup_children (number_to_start=6) at http_main.c:3972
-    #8  0x44260 in standalone_main (argc=392552, argv=0x75800) at http_main.c:4250
-    #9  0x449fc in main (argc=4, argv=0xefffee8c) at http_main.c:4534
-    (gdb) <font color="green">s</font>
-    2091        int status = r-&gt;status;
-    (gdb) <font color="green">p status</font>
+	at http_protocol.c:2090
+    2090	BUFF *fd = r-&gt;connection-&gt;client;
+    (gdb) where
+    #0	ap_send_error_response (r=0x95250, recursive_error=0)
+	at http_protocol.c:2090
+    #1	0x49b10 in ap_die (type=403, r=0x95250) at http_request.c:989
+    #2	0x49b60 in decl_die (status=403, phase=0x62db8 "check access",
+    r=0x95250)
+	at http_request.c:1000
+    #3	0x49f68 in process_request_internal (r=0x95250) at
+    http_request.c:1141
+    #4	0x49fe0 in ap_process_request (r=0x95250) at http_request.c:1167
+    #5	0x439d8 in child_main (child_num_arg=550608) at http_main.c:3826
+    #6	0x43b5c in make_child (s=0x7c3e8, slot=0, now=907958743)
+	at http_main.c:3898
+    #7	0x43ca8 in startup_children (number_to_start=6) at http_main.c:3972
+    #8	0x44260 in standalone_main (argc=392552, argv=0x75800) at
+    http_main.c:4250
+    #9	0x449fc in main (argc=4, argv=0xefffee8c) at http_main.c:4534
+    (gdb) s
+    2091	int status = r-&gt;status;
+    (gdb) p status
     $1 = 403
     (gdb) 
 </pre>
+There are a few things to note about the above example:
+
+1. the " `gdb httpd` " command does not include any command-line options
+for httpd: those are provided when the " `run` " command is done within
+gdb;
+
+1. I set a breakpoint before starting the run so that execution would stop
+at the top of ap_process_request();
+
+1. the " `s` " command steps through the code and into called procedures,
+whereas the " `n` " (next) command steps through the code but not into
+called procedures.
 
-<p>There are a few things to note about the above example:</p>
+1. additional breakpoints can be set with the " `b` " command, and the run
+continued with the " `c` " command.
 
-<ol>
-<li>the "<code>gdb httpd</code>" command does not include any command-line
-    options for httpd: those are provided when the "<code>run</code>" command
-    is done within gdb;</li>
-<li>I set a breakpoint before starting the run so that execution would stop
-    at the top of ap_process_request();</li>
-<li>the "<code>s</code>" command steps through the code and into called
-    procedures, whereas the "<code>n</code>" (next) command steps through
-    the code but not into called procedures.</li>
-<li>additional breakpoints can be set with the "<code>b</code>" command,
-    and the run continued with the "<code>c</code>" command.</li>
-<li>use the "<code>where</code>" command (a.k.a. "<code>bt</code>") to see
-    a stack backtrace that shows the order of called procedures and their
-    parameter values.</li>
-<li>use the "<code>p</code>" command to print the value of a variable.</li>
-</ol>
-
-<p>A file in the the root directory called <code>.gdbinit</code> provides
-useful macros for printing out various internal structures of httpd like tables
-(<code>dump_table</code>), brigades (<code>dump_brigade</code>) and filter chains
-(<code>dump_filters</code>).</p>
-
-<p>If you are debugging a repeatable crash, simply run gdb as above
-and make the request -- gdb should capture the crash and provide a
-prompt where it occurs.</p>
-
-<p>If you are debugging an apparent infinite loop, simply run gdb as above
-and type a Control-C -- gdb will interrupt the process and provide a
-prompt where it was stopped.</p>
+1. use the " `where` " command (a.k.a. " `bt` ") to see a stack backtrace
+that shows the order of called procedures and their parameter values.
 
-<p>If you are debugging a system crash and you have a core file from
-the crash, then do the following:</p>
+1. use the " `p` " command to print the value of a variable.
 
+A file in the the root directory called `.gdbinit` provides useful macros
+for printing out various internal structures of httpd like tables (
+`dump_table` ), brigades ( `dump_brigade` ) and filter chains (
+`dump_filters` ).
+
+If you are debugging a repeatable crash, simply run gdb as above and make
+the request -- gdb should capture the crash and provide a prompt where it
+occurs.
+
+If you are debugging an apparent infinite loop, simply run gdb as above and
+type a Control-C -- gdb will interrupt the process and provide a prompt
+where it was stopped.
+
+If you are debugging a system crash and you have a core file from the
+crash, then do the following:
 <pre>
-    % <font color="green">gdb httpd -c core</font>
-    (gdb) <font color="green">where</font>
-</pre>
+    % gdb httpd -c core
+    (gdb) where</pre>
+and it will (hopefully) print a stack backtrace of where the core dump
+occurred during processing.
+
+# Getting a live backtrace on unix # {#backtrace}
 
-<p>and it will (hopefully) print a stack backtrace of where the core dump
-occurred during processing.</p>
-</section>
-
-<section id="backtrace">
-<title>Getting a live backtrace on unix</title>
-
-<p>A backtrace will let you know the hierarchy of procedures that
-were called to get to a particular point in the process.  On some platforms
-you can get a live backtrace of any process.</p>
-
-<p>For SVR4-based variants of Unix, the <code>pstack</code> command for proc can
-be used to display a a live backtrace.  For example, on Solaris it looks 
-like</p>
+A backtrace will let you know the hierarchy of procedures that were called
+to get to a particular point in the process. On some platforms you can get
+a live backtrace of any process.
 
+For SVR4-based variants of Unix, the `pstack` command for proc can be used
+to display a a live backtrace. For example, on Solaris it looks like
 <pre>
-    % <font color="green">/usr/proc/bin/pstack 10623</font>
+    % /usr/proc/bin/pstack 10623
     10623:  httpd -d /usr/local/apache
      ef5b68d8 poll     (efffcd08, 0, 3e8)
      ef5d21e0 select   (0, ef612c28, 0, 0, 3e8, efffcd08) + 288
@@ -191,18 +196,17 @@ like</p>
      000449f4 main     (3, efffeee4, efffeef4, 75fe4, 1, 0) + 374
      000162fc _start   (0, 0, 0, 0, 0, 0) + 5c
 </pre>
-
-<p>Another technique is to use gdb to attach to the running process
-and then using "where" to print the backtrace, as in</p>
-
+Another technique is to use gdb to attach to the running process and then
+using "where" to print the backtrace, as in
 <pre>
-    % <font color="green">gdb httpd 10623</font>
+    % gdb httpd 10623
     GDB is free software and you are welcome to distribute copies of it
      under certain conditions; type "show copying" to see the conditions.
-    There is absolutely no warranty for GDB; type "show warranty" for details.
+    There is absolutely no warranty for GDB; type "show warranty" for
+    details.
     GDB 4.16.gnat.1.13 (sparc-sun-solaris2.5), 
     Copyright 1996 Free Software Foundation, Inc...
-    
+
     /usr/local/apache/src/10623: No such file or directory.
     Attaching to program `/usr/local/apache/src/httpd', process 10623
     Reading symbols from /usr/lib/libsocket.so.1...done.
@@ -212,290 +216,222 @@ and then using "where" to print the back
     Reading symbols from /usr/lib/libintl.so.1...done.
     Reading symbols from /usr/lib/libmp.so.1...done.
     Reading symbols from /usr/lib/libw.so.1...done.
-    Reading symbols from /usr/platform/SUNW,Ultra-1/lib/libc_psr.so.1...done.
+    Reading symbols from
+    /usr/platform/SUNW,Ultra-1/lib/libc_psr.so.1...done.
     0xef5b68d8 in   ()
-    (gdb) <font color="green">where</font>
-    #0  0xef5b68d8 in   ()
-    #1  0xef5d21e8 in select ()
-    #2  0x4257c in wait_or_timeout (status=0x0) at http_main.c:2357
-    #3  0x44318 in standalone_main (argc=392552, argv=0x75800) at ...
-    #4  0x449fc in main (argc=3, argv=0xefffeee4) at http_main.c:4534
+    (gdb) where
+    #0	0xef5b68d8 in	()
+    #1	0xef5d21e8 in select ()
+    #2	0x4257c in wait_or_timeout (status=0x0) at http_main.c:2357
+    #3	0x44318 in standalone_main (argc=392552, argv=0x75800) at...
+    #4	0x449fc in main (argc=3, argv=0xefffeee4) at http_main.c:4534
     (gdb) 
 </pre>
-</section>
-
-<section id="backtrace-win">
-<title>Getting a live backtrace on Windows</title>
 
-<ol>
-<li> Unzip the <code>-symbols.zip</code> files (obtained from the
-   Apache download site) in the root Apache2 directory tree (where
-   bin\, htdocs\, modules\ etc. are usually found.)  These .pdb files
-   should unpack alongside the .exe, .dll, .so binary files they
-   represent, e.g., mod_usertrack.pdb will unpack alongside
-   mod_usertrack.so.</li>
-
-<li> Invoke <code>drwtsn32</code> and ensure you are creating a crash
-   dump file, you are dumping all thread contexts, your log and crash
-   dump paths make sense, and (depending on the nature of the bug) you
-   pick an appropriate crash dump type.  (Full is quite large, but
-   necessary sometimes for a programmer-type to load your crash dump
-   into a debugger and begin unwinding exactly what has happened.
-   Mini is sufficient for your first pass through the process.)</li>
-
-<li> Note that if you previously installed and then uninstalled other debugging
-   software, you may need to invoke <code>drwtsn32 -i</code> in order to make
-   Dr Watson your default crash dump tool.  This will replace the 'report
-   problem to MS' dialogs.  (Don't do this if you have a full debugger such 
-   as Visual Studio or windbg installed on the machine, unless you back up the
-   registry value for <code>Debugger</code> under the 
-   <code>HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\AeDebug</code>
-   registry tree.  Developers using multiple tools might want to keep copies
-   of their different tools Debugger entries there, for fast switching.)</li>
-
-<li> Invoke the Task Manager, Choose 'show processes from all users',
-   and modify the <code>View -> Select Columns</code> to include
-   <strong>at least</strong> the <code>PID</code> and <code>Thread
-   Count</code>.  You can change this just once and Task Manager
-   should keep your preference.</li>
-
-<li> Now, track down the errant Apache that is hanging.  The parent
-   process has about three threads, we don't care about that one.  The
-   child worker process we want has many more threads (a few more than
-   you configured with the ThreadsPerChild directive.)  The process
-   name is Apache (for 1.3 and 2.0) or httpd (for 2.2 and 2.4).  Make note of
-   the child worker's PID.</li>
-
-<li> Using the {pid} number you noted above, invoke the command
-   <blockquote><code>drwtsn32 -p {pid}</code></blockquote></li>
-</ol>
-
-<p>Voila, you will find in your 'log file path' a
-<code>drwtsn32.log</code> file, and if you choose to 'append to
-existing log file', jump through the 'App:' sections until you find
-the one for the process you just killed.  Now you can identify
-about where 'Stack Back Trace' points to help identify what the server
-is doing.</p>
-
-<p>You will note that many threads look identical, almost all of them
-polling for the next connection, and you don't care about those.  You will
-want to see the ones that are deep inside of a request at the time you
-kill them, and only the stack back trace entries for those.  This can
-give folks a clue of where that request is hanging, which handler
-module picked up the request, and what filter it might be stuck in.</p>
-</section>
-
-
-<section id="crashes">
-<title>Debugging intermittent crashes</title>
-
-<p>For situations where a child process is crashing intermittently,
-the server must be configured and started such that it produces core
-dumps which can be analyzed further.</p>
-
-<p>To ensure that a core dump is written to a directory which is
-writable by the user which child processes run as (such as
-<code>apache</code>), the <a
-href="http://httpd.apache.org/docs/current/mod/mpm_common.html#coredumpdirectory"><code>CoreDumpDirectory</code></a>
-directive must be added to <code>httpd.conf</code>; for example:</p>
+# Getting a live backtrace on Windows # {#backtrace-win}
 
-<pre>
+1. Unzip the `-symbols.zip` files (obtained from the Apache download site)
+in the root Apache2 directory tree (where bin\, htdocs\, modules\ etc. are
+usually found.) These.pdb files should unpack alongside the.exe,.dll,.so
+binary files they represent, e.g., mod_usertrack.pdb will unpack alongside
+mod_usertrack.so.
+
+1. Invoke `drwtsn32` and ensure you are creating a crash dump file, you are
+dumping all thread contexts, your log and crash dump paths make sense, and
+(depending on the nature of the bug) you pick an appropriate crash dump
+type. (Full is quite large, but necessary sometimes for a programmer-type
+to load your crash dump into a debugger and begin unwinding exactly what
+has happened. Mini is sufficient for your first pass through the process.)
+
+1. Note that if you previously installed and then uninstalled other
+debugging software, you may need to invoke `drwtsn32 -i` in order to make
+Dr Watson your default crash dump tool. This will replace the 'report
+problem to MS' dialogs. (Don't do this if you have a full debugger such as
+Visual Studio or windbg installed on the machine, unless you back up the
+registry value for `Debugger` under the `HKLM\SOFTWARE\Microsoft\Windows
+NT\CurrentVersion\AeDebug` registry tree. Developers using multiple tools
+might want to keep copies of their different tools Debugger entries there,
+for fast switching.)
+
+1. Invoke the Task Manager, Choose 'show processes from all users', and
+modify the `View -&gt; Select Columns` to include **at least** the `PID`
+and `Thread
+   Count`. You can change this just once and Task Manager should keep your
+   preference.
+
+1. Now, track down the errant Apache that is hanging. The parent process
+has about three threads, we don't care about that one. The child worker
+process we want has many more threads (a few more than you configured with
+the ThreadsPerChild directive.) The process name is Apache (for 1.3 and
+2.0) or httpd (for 2.2 and 2.4). Make note of the child worker's PID.
+
+1. Using the {pid} number you noted above, invoke the command
+> `drwtsn32 -p {pid}` 
+
+Voila, you will find in your 'log file path' a `drwtsn32.log` file, and if
+you choose to 'append to existing log file', jump through the 'App:'
+sections until you find the one for the process you just killed. Now you
+can identify about where 'Stack Back Trace' points to help identify what
+the server is doing.
+
+You will note that many threads look identical, almost all of them polling
+for the next connection, and you don't care about those. You will want to
+see the ones that are deep inside of a request at the time you kill them,
+and only the stack back trace entries for those. This can give folks a clue
+of where that request is hanging, which handler module picked up the
+request, and what filter it might be stuck in.
+
+# Debugging intermittent crashes # {#crashes}
+
+For situations where a child process is crashing intermittently, the server
+must be configured and started such that it produces core dumps which can
+be analyzed further.
+
+To ensure that a core dump is written to a directory which is writable by
+the user which child processes run as (such as `apache` ), the
+[](http://httpd.apache.org/docs/current/mod/mpm_common.html#coredumpdirectory)
+directive must be added to `httpd.conf` ; for example:
+`
    CoreDumpDirectory /tmp
-</pre>
-
-<p>Before starting up the server, any process limits on core dump file
-size must be lifted; for example:</p>
-
-<pre>
+` 
+Before starting up the server, any process limits on core dump file size
+must be lifted; for example:
+`
   # ulimit -c unlimited
   # apachectl start
-</pre>
-
-<p>On some platforms, further steps might be needed to enable core
-dumps - see <a href="#sol27">Solaris and coredumps</a> below.</p>
-
-<p>When a child process crashes, a message like the following will be
-logged to the error_log:</p>
-
-<blockquote><code>
-[Mon Sep 05 13:35:39 2005] [notice] child pid 2027 exit signal Segmentation fault (11), possible coredump in /tmp
-</code></blockquote>
-
-<p>If the text "possible coredump in /tmp" does not appear in the
-error line, check that the ulimit was set correctly, that the
-permissions on the configured <code>CoreDumpDirectory</code> are
-suitable and that platform specific steps
-(<a href="#sol27">Solaris and coredumps</a>) have been done if needed.</p>
-
-<p>To analyse the core dump, pass the core dump filename on the gdb
-command-line, and enter the command <code>bt full</code> at the gdb
-prompt:</p>
+` 
+On some platforms, further steps might be needed to enable core dumps - see
+[Solaris and coredumps](#sol27) below.
+
+When a child process crashes, a message like the following will be logged
+to the error_log:
+
+> `
+[Mon Sep 05 13:35:39 2005] [notice] child pid 2027 exit signal Segmentation
+fault (11), possible coredump in /tmp
+` 
+
+If the text "possible coredump in /tmp" does not appear in the error line,
+check that the ulimit was set correctly, that the permissions on the
+configured `CoreDumpDirectory` are suitable and that platform specific
+steps ( [Solaris and coredumps](#sol27) ) have been done if needed.
 
+To analyse the core dump, pass the core dump filename on the gdb
+command-line, and enter the command `bt full` at the gdb prompt:
 <pre>
-  % <b>gdb /usr/local/apache2/bin/httpd /tmp/core.2027</b>
-  ...
+  % gdb /usr/local/apache2/bin/httpd /tmp/core.2027
+...
   Core was generated by `/usr/local/apache2/bin/httpd -k start'
-  ...
-  (gdb) <b>bt full</b>
-</pre>
-
-<p>If attempting to debug a threaded server, for example when using
-the <code>worker</code> MPM, use the following gdb command:</p>
-
+...
+  (gdb) bt full</pre>
+If attempting to debug a threaded server, for example when using the
+`worker` MPM, use the following gdb command:
 <pre>
-  (gdb) <b>thread apply all bt full</b>
-</pre>
+  (gdb) thread apply all bt full</pre>
 
-</section>
+# Using 'truss/trace/strace' to trace system calls and signals # {#truss}
 
-<section id="truss">
-<title>Using 'truss/trace/strace' to trace system calls and 
-signals</title>
-
-<p>Most Unix-based systems have at least one command for displaying
-a trace of system calls and signals as they are accessed by a running
-process.  This command is called <code>truss</code> on most SVR4-based
-systems and either <code>trace</code> or <code>strace</code> on many
-other systems.</p>
-
-<p>A useful tip for using the <code>truss</code> command on Solaris is
-the <code>-f</code> option (often also works with <code>strace</code>); it tells
-truss to follow and continue tracing any child processes forked by the main
-process. The easiest way to get a full trace of a server is to do something
-like:</p>
+Most Unix-based systems have at least one command for displaying a trace of
+system calls and signals as they are accessed by a running process. This
+command is called `truss` on most SVR4-based systems and either `trace` or
+`strace` on many other systems.
 
+A useful tip for using the `truss` command on Solaris is the `-f` option
+(often also works with `strace` ); it tells truss to follow and continue
+tracing any child processes forked by the main process. The easiest way to
+get a full trace of a server is to do something like:
 <pre>
-    % <font color="green">truss -f httpd -d /usr/local/apache &gt;&amp; outfile</font>
-</pre>
-and let it run through a few requests before killing the parent. You can
-then view the entire trace in outfile, or use something like
+    % truss -f httpd -d /usr/local/apache &gt;&amp; outfile</pre><pre>
+    % egrep '^10698:' outfile</pre>
+to view just the trace of the process id 10698.
+
+If attempting to truss a threaded server, for example when using the
+`worker` MPM, the `truss` option `-l` is very useful as it prints also the
+LWP id after the process id. You can use something like
 <pre>
-    % <font color="green">egrep '^10698:' outfile</font>
-</pre>
+    % egrep '^10698/1:' outfile</pre>
+to view just the trace of the process id 10698 and LWP id 1.
 
-<p>to view just the trace of the process id 10698.</p>
+Other useful options for truss are
 
-<p>If attempting to truss a threaded server, for example when using
-the <code>worker</code> MPM, the <code>truss</code> option <code>-l</code>
-is very useful as it prints also the LWP id after the process id. You can use
-something like</p>
+-  `-a` to print all command line parameters used for this executable.
 
-<pre>
-    % <font color="green">egrep '^10698/1:' outfile</font>
-</pre>
+-  `-e` to print all environment variables used for this executable.
 
-<p>to view just the trace of the process id 10698 and LWP id 1.</p>
+-  `-d` to print timestamps.
 
-<p>Other useful options for truss are</p>
+# Getting the server to dump core # {#gcore}
 
-<ul>
-<li>
-<code>-a</code> to print all command line parameters used for this executable.
-</li>
-<li>
-<code>-e</code> to print all environment variables used for this executable.
-</li>
-<li>
-<code>-d</code> to print timestamps.
-</li>
-</ul>
-
-</section>
-
-<section id="gcore">
-<title>Getting the server to dump core</title>
-
-<p>Strangely enough, sometimes you actually want to force the server
-to crash so that you can get a look at some nutty behavior.  Normally
-this can be done simply by using the <code>gcore</code> command.
-However, for security reasons, most Unix systems do not allow a setuid
-process to dump core, since the file contents might reveal something
-that is supposed to be protected in memory.</p>
-
-<p>Here is one way to get a core file from a setuid Apache httpd process
-on Solaris, without knowing which httpd child might be the one to die
-[note: it is probably easier to use the MaxClients trick in the first
-section above].</p>
+Strangely enough, sometimes you actually want to force the server to crash
+so that you can get a look at some nutty behavior. Normally this can be
+done simply by using the `gcore` command. However, for security reasons,
+most Unix systems do not allow a setuid process to dump core, since the
+file contents might reveal something that is supposed to be protected in
+memory.
 
-<pre>
+Here is one way to get a core file from a setuid Apache httpd process on
+Solaris, without knowing which httpd child might be the one to die [note:
+it is probably easier to use the MaxClients trick in the first section
+above].
+`
     # for pid in `ps -eaf | fgrep httpd | cut -d' ' -f4`
     do
-      truss -f -l -t\!all -S SIGSEGV -p $pid 2&gt;&amp;1 | egrep SIGSEGV &amp;
+      truss -f -l -t\!all -S SIGSEGV -p $pid 2&gt;&amp;1 | egrep SIGSEGV
+      &amp;
     done
-</pre>
-
-<p>The <a href="http://www.dejanews.com/=zzz_maf/getdoc.xp?AN=352257973">
-undocumented '-S' flag</a> to truss will halt the process in place
-upon receipt of a given signal (SIGSEGV in this case).  
-At this point you can use:</p>
-
-<pre>
-    # gcore <i>PID</i>
-</pre>
-
-<p>and then look at the backtrace as discussed above for 
-<a href="#gdb">gdb</a>.</p>
-</section>
-
-<section id="sol27">
-<title>Solaris and coredumps</title>
-
-<p>On Solaris use <a href="http://docs.sun.com/app/docs/doc/816-5166/coreadm-1m"
-><code>coreadm(1M)</code></a> to make
-<code>setuid()</code> processes actually dump core. By default a setuid()
-process does not dump core. This is the reason why httpd servers started as
-root with child processes running as a different user (such as
-<code>apache</code>) do not coredump even when the
-<a href="http://httpd.apache.org/docs/current/mod/mpm_common.html#coredumpdirectory">
-<code>CoreDumpDirectory</code></a>
-directive had been set to an appropriate and writable directory and
-<b><code>ulimit -c</code></b> has a sufficient size. See also
-<a href="#crashes">Debugging intermittent crashes</a> above.
-</p>
+` 
+The [undocumented '-S'
+flag](http://www.dejanews.com/=zzz_maf/getdoc.xp?AN=352257973) to truss
+will halt the process in place upon receipt of a given signal (SIGSEGV in
+this case). At this point you can use:
+<pre>
+    # gcore PID</pre>
+and then look at the backtrace as discussed above for [gdb](#gdb).
+
+# Solaris and coredumps # {#sol27}
+
+On Solaris use [](http://docs.sun.com/app/docs/doc/816-5166/coreadm-1m) to
+make `setuid()` processes actually dump core. By default a setuid() process
+does not dump core. This is the reason why httpd servers started as root
+with child processes running as a different user (such as `apache` ) do not
+coredump even when the
+[](http://httpd.apache.org/docs/current/mod/mpm_common.html#coredumpdirectory)
+directive had been set to an appropriate and writable directory and **
+`ulimit -c` ** has a sufficient size. See also [Debugging intermittent
+crashes](#crashes) above.
 
-<p>Example:</p>
-<pre>
+Example:
+`
 -bash-3.00# coreadm
      global core file pattern: /var/core/core.%f.%p.u%u
      global core file content: default
        init core file pattern: core
        init core file content: default
-            global core dumps: disabled
+	    global core dumps: disabled
        per-process core dumps: enabled
       global setid core dumps: enabled
- per-process setid core dumps: enabled
+per-process setid core dumps: enabled
      global core dump logging: disabled
-</pre>
-</section>
+` 
+
+# Getting and analyzing a TCP packet trace # {#tcpdump}
+
+This is too deep a subject to fully describe in this documentation. Here
+are some pointers to useful discussions and tools:
+
+-  `snoop` is a packet sniffer that is part of Solaris.
 
-<section id="tcpdump">
-<title>Getting and analyzing a TCP packet trace</title>
+-  [tcpdump](http://www.tcpdump.org/) is a packet sniffer that is available
+for Unix-based systems and Windows (
+[windump](http://www.winpcap.org/windump/) ). It is part of many free
+Unix-based distributions.
 
-<p>This is too deep a subject to fully describe in this documentation.
-Here are some pointers to useful discussions and tools:</p>
+-  [Wireshark](http://www.wireshark.org/) is another packet sniffer that is
+available for Unix-based systems and Windows. It has a nice GUI and allows
+the analysis of the sniffed data.
 
-<ul>
-<li>
-<code>snoop</code> is a packet sniffer that is part of Solaris.
-</li>
-<li>
-<a href="http://www.tcpdump.org/">tcpdump</a> is a packet sniffer that is
-available for Unix-based systems and Windows
-(<a href="http://www.winpcap.org/windump/">windump</a>).
-It is part of many free Unix-based distributions.
-</li>
-<li>
-<a href="http://www.wireshark.org/">Wireshark</a> is another packet sniffer
-that is available for Unix-based systems and Windows. It has a nice GUI and
-allows the analysis of the sniffed data.
-</li>
-<li><a href="http://jarok.cs.ohiou.edu/software/tcptrace/">
-    tcptrace</a> is a TCP dump file analysis tool.</li>
-<li><a href="http://www.tcpshow.org/">tcpshow</a> is
-    another one.</li>
-</ul>
+-  [tcptrace](http://jarok.cs.ohiou.edu/software/tcptrace/) is a TCP dump
+file analysis tool.
 
-</section>
+-  [tcpshow](http://www.tcpshow.org/) is another one.
 
-</body>
-</document>

Copied: httpd/site/trunk/content/dev/devnotes.mdtext (from r1334802, httpd/site/trunk/content/dev/devnotes.xml)
URL: http://svn.apache.org/viewvc/httpd/site/trunk/content/dev/devnotes.mdtext?p2=httpd/site/trunk/content/dev/devnotes.mdtext&p1=httpd/site/trunk/content/dev/devnotes.xml&r1=1334802&r2=1334814&rev=1334814&view=diff
==============================================================================
--- httpd/site/trunk/content/dev/devnotes.xml (original)
+++ httpd/site/trunk/content/dev/devnotes.mdtext Sun May  6 22:53:19 2012
@@ -1,207 +1,177 @@
-<?xml version="1.0"?>
-<document>
-  <properties>
-    <author email="docs@httpd.apache.org">Documentation Group</author>
-    <title>Apache Development Notes</title>
-  </properties>
-<body>
-<section>
-<title>Apache Development Notes</title>
-
-<p>This page is intended to provide some basic background about
-development nits and the maintenance of the developer site.</p>
-</section>
-
-<section>
-<title>Overview</title>
-
-<p>The Apache HTTP Server Project has switched to
-<a href="http://subversion.apache.org/">Subversion</a> for hosting its source
-code.</p>
-
-<p>To check out the 2.4.x branch:</p>
-<blockquote>
-<code>
-svn checkout http://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x httpd-2.4.x
-</code>
-</blockquote>
+Title: Apache Development Notes
+Notice:    Licensed to the Apache Software Foundation (ASF) under one
+           or more contributor license agreements.  See the NOTICE file
+           distributed with this work for additional information
+           regarding copyright ownership.  The ASF licenses this file
+           to you under the Apache License, Version 2.0 (the
+           "License"); you may not use this file except in compliance
+           with the License.  You may obtain a copy of the License at
+           .
+             http://www.apache.org/licenses/LICENSE-2.0
+           .
+           Unless required by applicable law or agreed to in writing,
+           software distributed under the License is distributed on an
+           "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+           KIND, either express or implied.  See the License for the
+           specific language governing permissions and limitations
+           under the License.
+
+This page is intended to provide some basic background about development
+nits and the maintenance of the developer site.
+
+# Overview #
+
+The Apache HTTP Server Project has switched to
+[Subversion](http://subversion.apache.org/) for hosting its source code.
+
+To check out the 2.4.x branch:
+
+> `
+svn checkout http://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x
+httpd-2.4.x
+` 
 
-<p>To check out the current development version (as of this writing, 2.5.x),
-use:</p>
+To check out the current development version (as of this writing, 2.5.x),
+use:
 
-<blockquote>
-<code>
+> `
 svn checkout http://svn.apache.org/repos/asf/httpd/httpd/trunk httpd-trunk
-</code>
-</blockquote>
+` 
 
-<p>Committers should check out via https instead of http (so that they can
-commit their changes).  For more info about Subversion, please read <a
-href="http://www.apache.org/dev/version-control.html"
->the ASF version control FAQ</a>.</p>
+Committers should check out via https instead of http (so that they can
+commit their changes). For more info about Subversion, please read [the ASF
+version control FAQ](http://www.apache.org/dev/version-control.html).
 
-<p>The developers continue to seek to maintain module compatibility between
+The developers continue to seek to maintain module compatibility between
 2.4.1 and future 2.4 releases for administrators and end users, while
-continuing the forward progress that has made the 2.2 server faster and more
-scalable.</p>
-</section>
-
-<section>
-<title>Maintaining the Sources</title>
-
-<p>Almost all files relating to Apache, both the actual sources and the
-files that aren't part of the distribution, are now maintained in an
-<a href="http://subversion.apache.org/">SVN</a> repository.  Here is the way
-in which changes are applied:</p>
-
-  <ol>
-   <li>Developer checks out a copy of the files on which he wants to
-    work (in this case, the trunk), into a private working directory
-    called <samp>httpd-trunk</samp>:
-    <p>
-    <dl>
-     <dd><samp>% svn checkout http://svn.apache.org/repos/asf/httpd/httpd/trunk
-      httpd-trunk</samp>
-     </dd>
-    </dl>
-    </p>
-    <p>
-    This step only needs to be performed once (unless the private working
-    directory is tainted or deleted.)  Committers should use a URL prefix
-    of <samp>https</samp> on the checkout, to save themselves headaches later.
-    </p>
-   </li>
-   <li>Developer keeps his working directory synchronised with changes
-    made to the repository:
-    <p>
-    <dl>
-     <dd><samp>% svn update httpd-trunk</samp>
-     </dd>
-    </dl>
-    </p>
-    <p>
-    This should probably be done daily or even more frequently during
-    periods of high activity.
-    </p>
-   </li>
-   <li>Developer makes changes to his working copies, makes sure they
-    work, and generates a patch so others can apply the changes to test
-    them:
-    <p>
-    <dl>
-     <dd><samp>% svn diff httpd-trunk/modules/http/mod_mime.c &gt; /tmp/foo</samp>
-     </dd>
-    </dl>
-    </p>
-    <p>
-    The <samp>/tmp/foo</samp> file is mailed to the
-    <a href="http://httpd.apache.org/lists.html#http-dev">developers list</a> so
-    they can consider the value/validity of the patch.  It is worth
-    making sure your code follows the Apache style, as described in the
-    <a href="styleguide.html">style guide</a>.
-    </p>
-   </li>
-   <li>Once other developers have agreed that the change is a Good
-    Thing, the developer checks the changes into the repository:
-    <p>
-    <dl>
-     <dd><samp>% svn commit httpd-trunk/modules/http/mod_mime.c</samp>
-     </dd>
-    </dl>
-    </p>
-   </li>
-  </ol>
-</section>
-
-<section>
-<title>SVN Subtrees</title>
-  <p>There are several different branches under the <samp>httpd</samp>
-   subtree in the Apache SVN repository that pertain to the different
-   releases.  The top level can be perused with the
-   <a href="http://svn.apache.org/viewcvs.cgi/">SVN ViewCVS</a> pages.
-   The main subtrees pertaining to the <samp>httpd</samp> server source
-   are:</p>
-
-  <section><title>httpd-2.2</title>
-   <p>To create a directory tree containing the 2.2 sources,
-    and call it <samp>httpd-2.2</samp>, change your current directory
-    to the <em>parent</em> of the tree and then check the 2.2 sources
-    out as follows:</p>
-   <source>
+continuing the forward progress that has made the 2.2 server faster and
+more scalable.
+
+# Maintaining the Sources #
+
+Almost all files relating to Apache, both the actual sources and the files
+that aren't part of the distribution, are now maintained in an
+[SVN](http://subversion.apache.org/) repository. Here is the way in which
+changes are applied:
+
+1. Developer checks out a copy of the files on which he wants to work (in
+this case, the trunk), into a private working directory
+called<samp>httpd-trunk</samp>:
+
+:    <samp>% svn checkout http://svn.apache.org/repos/asf/httpd/httpd/trunk
+     httpd-trunk</samp>
+
+This step only needs to be performed once (unless the private working
+directory is tainted or deleted.) Committers should use a URL prefix
+of<samp>https</samp>on the checkout, to save themselves headaches later.
+
+1. Developer keeps his working directory synchronised with changes made to
+the repository:
+
+:    <samp>% svn update httpd-trunk</samp>
+
+This should probably be done daily or even more frequently during periods
+of high activity.
+
+1. Developer makes changes to his working copies, makes sure they work, and
+generates a patch so others can apply the changes to test them:
+
+:    <samp>% svn diff httpd-trunk/modules/http/mod_mime.c &gt;
+     /tmp/foo</samp>
+
+The<samp>/tmp/foo</samp>file is mailed to the [developers
+list](http://httpd.apache.org/lists.html#http-dev) so they can consider the
+value/validity of the patch. It is worth making sure your code follows the
+Apache style, as described in the [style guide](styleguide.html).
+
+1. Once other developers have agreed that the change is a Good Thing, the
+developer checks the changes into the repository:
+
+:    <samp>% svn commit httpd-trunk/modules/http/mod_mime.c</samp>
+
+# SVN Subtrees #
+
+There are several different branches under the<samp>httpd</samp>subtree in
+the Apache SVN repository that pertain to the different releases. The top
+level can be perused with the [SVN
+ViewCVS](http://svn.apache.org/viewcvs.cgi/) pages. The main subtrees
+pertaining to the<samp>httpd</samp>server source are:
+
+## httpd-2.2 ##
+
+To create a directory tree containing the 2.2 sources, and call
+it<samp>httpd-2.2</samp>, change your current directory to the *parent* of
+the tree and then check the 2.2 sources out as follows:
+<pre>
 % cd /usr/local/apache
 % svn checkout http://svn.apache.org/repos/asf/httpd/httpd/branches/2.2.x
-   httpd-2.2</source>
-  </section>
+   httpd-2.2</pre>
+
+## httpd-2.4 ##
 
-  <section><title>httpd-2.4</title>
-   <p>To create a directory tree containing the 2.4 sources,
-    and call it <samp>httpd-2.4</samp>, change your current directory
-    to the <em>parent</em> of the tree and then check the 2.4 sources
-    out as follows:</p>
-   <source>
+To create a directory tree containing the 2.4 sources, and call
+it<samp>httpd-2.4</samp>, change your current directory to the *parent* of
+the tree and then check the 2.4 sources out as follows:
+<pre>
 % cd /usr/local/apache
 % svn checkout http://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x
-   httpd-2.4</source>
-  </section>
+   httpd-2.4</pre>
 
-  <section><title>httpd-2.5</title>
-   <p>If you want to check out the bleeding edge of development, the
-     httpd-2.5 development tree (slated for a release 2.6), and call it
-     <samp>httpd-trunk</samp>, checkout as follows:</p>
-   <source>
+## httpd-2.5 ##
+
+If you want to check out the bleeding edge of development, the httpd-2.5
+development tree (slated for a release 2.6), and call
+it<samp>httpd-trunk</samp>, checkout as follows:
+<pre>
 % cd /usr/local/apache
-% svn checkout http://svn.apache.org/repos/asf/httpd/httpd/trunk httpd-trunk</source>
-  </section>
+% svn checkout http://svn.apache.org/repos/asf/httpd/httpd/trunk
+httpd-trunk</pre>
+
+## httpd-site ##
 
-  <section><title>httpd-site</title>
-   <p>This subtree contains the files that live at <samp>http://httpd.apache.org/</samp>.
-    The directory on the host that maps to that URL is actually a set of
-    checked-out working copies of the SVN files.</p>
-   <p>The SVN URL is
-    <samp>https://svn.apache.org/repos/asf/httpd/site/trunk/docs</samp>.</p>
-   <make_note>
-    It is important that the files on the Web host not be modified
-    directly.  If you want or need to change one, check it out into a
-    private working copy, modify <strong>that</strong>, commit the
-    change into SVN, and then perform a <samp>svn update</samp> to
-    bring the host directory into sync with the SVN sources.
-   </make_note>
-   <p>The Web site <em>directories</em> (as opposed to files) are not
-    maintained in synch with the SVN files automatically.  They are
-    manually updated from SVN by various people as they consider
-    appropriate.  This is usually not an issue, unless a group of files
-    are being updated according to an ongoing group discussion.</p>
-  </section>
-
-  <section><title>httpd-dist</title>
-   <p>Like the <samp>httpd-site</samp> subtree, this one is used to
-    maintain the files that comprise a website - in this case,
-    <samp>http://www.apache.org/dist/httpd/</samp>.  Also like the
-    previous subtree, the directory on the server is a checked-out
-    working copy of this subtree.  However, since this is a distribution
-    directory, we only have the surrounding documentation and control
-    files checked into this subtree -- the actual tarballs are simply
-    copied to www.apache.org.</p>
-   <p>The SVN URL is
-    <samp>https://svn.apache.org/repos/asf/httpd/httpd/dist</samp>.</p>
-   <p>Committers will generally deal with this subtree when "rolling" a
-    release.  This is a series of steps taken to create a complete new
-    release of the Apache httpd software.  Amongst other things, the
-    key to this subtree is the <samp>tools/</samp> directory, which
-    contains the <samp>release.sh</samp> shell script.  More information
-    on the policies and procedures relating to rolling releases can be
-    found on the <a href="release.html">Release Guidelines</a> page.</p>
-  </section>
-</section>
-
-<section>
-<title>Setting Up Remote SVN</title>
-
-<p>A brief overview of getting started with SVN committer access can be
-found <a href="http://www.apache.org/dev/version-control.html#https-svn">
-here</a>.  One key change to note is that SSH is not used anymore for
-committer access, due to the functional differences with SVN.</p>
-</section>
+This subtree contains the files that live
+at<samp>http://httpd.apache.org/</samp>. The directory on the host that
+maps to that URL is actually a set of checked-out working copies of the SVN
+files.
+
+The SVN URL
+is<samp>https://svn.apache.org/repos/asf/httpd/site/trunk/docs</samp>.
+<make_note>It is important that the files on the Web host not be modified
+directly. If you want or need to change one, check it out into a private
+working copy, modify **that** , commit the change into SVN, and then
+perform a<samp>svn update</samp>to bring the host directory into sync with
+the SVN sources.</make_note>
+The Web site *directories* (as opposed to files) are not maintained in
+synch with the SVN files automatically. They are manually updated from SVN
+by various people as they consider appropriate. This is usually not an
+issue, unless a group of files are being updated according to an ongoing
+group discussion.
+
+## httpd-dist ##
+
+Like the<samp>httpd-site</samp>subtree, this one is used to maintain the
+files that comprise a website - in this
+case,<samp>http://www.apache.org/dist/httpd/</samp>. Also like the previous
+subtree, the directory on the server is a checked-out working copy of this
+subtree. However, since this is a distribution directory, we only have the
+surrounding documentation and control files checked into this subtree --
+the actual tarballs are simply copied to www.apache.org.
+
+The SVN URL
+is<samp>https://svn.apache.org/repos/asf/httpd/httpd/dist</samp>.
+
+Committers will generally deal with this subtree when "rolling" a release.
+This is a series of steps taken to create a complete new release of the
+Apache httpd software. Amongst other things, the key to this subtree is
+the<samp>tools/</samp>directory, which contains
+the<samp>release.sh</samp>shell script. More information on the policies
+and procedures relating to rolling releases can be found on the [Release
+Guidelines](release.html) page.
+
+# Setting Up Remote SVN #
+
+A brief overview of getting started with SVN committer access can be found
+[here](http://www.apache.org/dev/version-control.html#https-svn). One key
+change to note is that SSH is not used anymore for committer access, due to
+the functional differences with SVN.
 
-</body>
-</document>



Mime
View raw message