From f810ccbc0a558500fb196d8b621a38af65dcac91 Mon Sep 17 00:00:00 2001
From: Joshua Slive <slive@apache.org>
Date: Tue, 23 Jul 2002 17:45:36 +0000
Subject: [PATCH] Introduce changes necessary to bring the remainder of the
 manual into xml.

1. Add a <relative-path href="whatever"/> element to the manualpage
DTD.  This should give the path from the location of the page to
the root of the manual directory.  It is necessary for proper linking
to directives, etc.

2. Add the stuff to common.xsl necessary to transform a <manualpage>.
This is basically the minimum.  It creates something VERY similar to
what we had before (with the exception of a little css here and
there).  I very much hope that this will be improved soon to look
nicer.

3. Add configuring.xml, which was written by Astrid Kessler.  I made only
a very few small changes to bring it in line with the current DTD.

I have not yet committed the corresponding configuring.html.en, since I
want to give people a little opporunity to comment on this stuff.

My appologies, but I am committing a few style changes to common.xsl
along with the substantial changes.  That file is really hard to
work with, and should probably be broken up.


git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@96158 13f79535-47bb-0310-9956-ffa450edef68
---
 docs/manual/configuring.xml      | 195 +++++++++++++++++++++++++++++++
 docs/manual/style/build.xml      |  11 ++
 docs/manual/style/common.xsl     | 160 +++++++++++++++++++++----
 docs/manual/style/en.xml         |   6 +-
 docs/manual/style/manualpage.dtd |   6 +-
 5 files changed, 355 insertions(+), 23 deletions(-)
 create mode 100644 docs/manual/configuring.xml

diff --git a/docs/manual/configuring.xml b/docs/manual/configuring.xml
new file mode 100644
index 0000000000..2a05174328
--- /dev/null
+++ b/docs/manual/configuring.xml
@@ -0,0 +1,195 @@
+<?xml version='1.0' encoding='UTF-8' ?>
+<!DOCTYPE manualpage SYSTEM "./style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="./style/manual.en.xsl"?>
+<manualpage>
+<relative-path href="."/>
+
+  <title>Configuration Files</title>
+
+<summary>
+<p>This document describes the files used to configure the Apache
+HTTP server.</p>
+</summary>
+
+  <section id="main">
+    <title>Main Configuration Files</title>
+    <related>
+      <modulelist>
+        <module>mod_mime</module>
+      </modulelist>
+      <directivelist>
+        <directive module="core" type="section">IfDefine</directive>
+        <directive module="core">Include</directive>
+        <directive module="mod_mime">TypesConfig</directive>
+      </directivelist>
+    </related>
+
+    <p>Apache is configured by placing <a
+    href="mod/directives.html">directives</a> in plain text
+    configuration files. The main configuration file is usually
+    called <code>httpd.conf</code>. The location of this file is
+    set at compile-time, but may be overridden with the
+    <code>-f</code> command line flag. In addition, other
+    configuration files may be added using the <directive
+    module="core">Include</directive> directive. Any
+    directive may be placed in any of these configuration files.
+    Changes to the main configuration files are only recognized by
+    Apache when it is started or restarted.</p>
+
+    <p>New with Apache 1.3.13 is a feature where if any
+    configuration file is actually a directory, Apache will enter
+    that directory and parse any files (and subdirectories) found
+    there as configuration files. One possible use for this would
+    be to add VirtualHosts by creating small configuration files
+    for each host, and placing them in such a configuration
+    directory. Thus, you can add or remove VirtualHosts without
+    editing any files at all, simply adding or deleting them. This
+    makes automating such processes much easier.</p>
+
+    <p>The server also reads a file containing mime document types;
+    the filename is set by the <directive
+    module="mod_mime">TypesConfig</directive> directive,
+    and is <code>mime.types</code> by default.</p>
+  </section>
+
+  <section id="syntax">
+    <title>Syntax of the Configuration Files</title>
+
+    <p>Apache configuration files contain one directive per line.
+    The back-slash "\" may be used as the last character on a line
+    to indicate that the directive continues onto the next line.
+    There must be no other characters or white space between the
+    back-slash and the end of the line.</p>
+
+    <p>Directives in the configuration files are case-insensitive,
+    but arguments to directives are often case sensitive. Lines
+    which begin with the hash character "#" are considered
+    comments, and are ignored. Comments may <strong>not</strong> be
+    included on a line after a configuration directive. Blank lines
+    and white space occurring before a directive are ignored, so
+    you may indent directives for clarity.</p>
+
+    <p>You can check your configuration files for syntax errors
+    without starting the server by using <code>apachectl
+    configtest</code> or the <code>-t</code> command line
+    option.</p>
+  </section>
+
+  <section id="modules">
+    <title>Modules</title>
+
+    <related>
+      <modulelist>
+        <module>mod_so</module>
+      </modulelist>
+      <directivelist>
+        <directive module="core">AddModule</directive>
+        <directive module="core">ClearModuleList</directive>
+        <directive module="core" type="section">IfModule</directive>
+        <directive module="mod_so">LoadModule</directive>
+      </directivelist>
+    </related>
+
+    <p>Apache is a modular server. This implies that only the most
+    basic functionality is included in the core server. Extended
+    features are available through <a
+    href="mod/index-bytype.html">modules</a> which can be loaded
+    into Apache. By default, a <a
+    href="mod/module-dict.html#Status">base</a> set of modules is
+    included in the server at compile-time. If the server is
+    compiled to use <a href="dso.html">dynamically loaded</a>
+    modules, then modules can be compiled separately and added at
+    any time using the <directive module="mod_so">LoadModule</directive>
+    directive.
+    Otherwise, Apache must be recompiled to add or remove modules.
+    Configuration directives may be included conditional on a
+    presence of a particular module by enclosing them in an<directive
+    module="core" type="section">IfModule</directive> block.</p>
+
+    <p>To see which modules are currently compiled into the server,
+    you can use the <code>-l</code> command line option.</p>
+  </section>
+
+  <section id="scope">
+    <title>Scope of Directives</title>
+
+    <related>
+      <directivelist>
+        <directive module="core" type="section">Directory</directive>
+        <directive module="core" type="section">DirectoryMatch</directive>
+        <directive module="core" type="section">Files</directive>
+        <directive module="core" type="section">FilesMatch</directive>
+        <directive module="core" type="section">Location</directive>
+        <directive module="core" type="section">LocationMatch</directive>
+        <directive module="core" type="section">VirtualHost</directive>
+      </directivelist>
+    </related>
+
+    <p>Directives placed in the main configuration files apply to
+    the entire server. If you wish to change the configuration for
+    only a part of the server, you can scope your directives by
+    placing them in <directive module="core"
+    type="section">Directory</directive>, <directive module="core"
+    type="section">DirectoryMatch</directive>, <directive module="core"
+    type="section">Files</directive>, <directive module="core"
+    type="section">FilesMatch</directive>, <directive module="core"
+    type="section">Location</directive>, and <directive module="core"
+    type="section">LocationMatch</directive>
+    sections. These sections limit the application of the
+    directives which they enclose to particular filesystem
+    locations or URLs. They can also be nested, allowing for very
+    fine grained configuration.</p>
+
+    <p>Apache has the capability to serve many different websites
+    simultaneously. This is called <a href="vhosts/">Virtual
+    Hosting</a>. Directives can also be scoped by placing them
+    inside <directive module="core" type="section">VirtualHost</directive>
+    sections, so that they will only apply to requests for a
+    particular website.</p>
+
+    <p>Although most directives can be placed in any of these
+    sections, some directives do not make sense in some contexts.
+    For example, directives controlling process creation can only
+    be placed in the main server context. To find which directives
+    can be placed in which sections, check the <a
+    href="mod/directive-dict.html#Context">Context</a> of the
+    directive. For further information, we provide details on <a
+    href="sections.html">How Directory, Location and Files sections
+    work</a>.</p>
+  </section>
+
+  <section id="htaccess">
+    <title>.htaccess Files</title>
+
+    <related>
+      <directivelist>
+        <directive module="core">AccessFileName</directive>
+        <directive module="core">AllowOverride</directive>
+      </directivelist>
+    </related>
+
+    <p>Apache allows for decentralized management of configuration
+    via special files placed inside the web tree. The special files
+    are usually called <code>.htaccess</code>, but any name can be
+    specified in the <directive module="core">AccessFileName</directive>
+    directive. Directives placed in <code>.htaccess</code> files
+    apply to the directory where you place the file, and all
+    sub-directories. The <code>.htaccess</code> files follow the
+    same syntax as the main configuration files. Since
+    <code>.htaccess</code> files are read on every request, changes
+    made in these files take immediate effect.</p>
+
+    <p>To find which directives can be placed in
+    <code>.htaccess</code> files, check the <a
+    href="mod/directive-dict.html#Context">Context</a> of the
+    directive. The server administrator further controls what
+    directives may be placed in <code>.htaccess</code> files by
+    configuring the <directive module="core">AllowOverride</directive>
+    directive in the main configuration files.</p>
+
+    <p>For more information on <code>.htaccess</code> files, see
+    Ken Coar's tutorial on <a
+    href="http://apache-server.com/tutorials/ATusing-htaccess.html">
+    Using .htaccess Files with Apache</a>.</p>
+  </section>
+</manualpage>
\ No newline at end of file
diff --git a/docs/manual/style/build.xml b/docs/manual/style/build.xml
index 22c2fdec36..7e7c8ac2da 100644
--- a/docs/manual/style/build.xml
+++ b/docs/manual/style/build.xml
@@ -30,5 +30,16 @@
       <mapper type="glob" from="*.xml.ja" to="*.html.ja.jis"/>
       <param name="relative-path" expression="."/>
     </style>
+
+   <!-- Transform the root directory of the manual -->
+    <style   basedir="../"
+             destdir="../"
+           extension=".html"
+               style="./manual.en.xsl"
+            includes="*.xml">
+      <mapper type="glob" from="*.xml" to="*.html.en"/>
+      <param name="relative-path" expression="."/>
+    </style>
+
   </target>
 </project>
diff --git a/docs/manual/style/common.xsl b/docs/manual/style/common.xsl
index 8f201dcaaa..ade088b0ed 100644
--- a/docs/manual/style/common.xsl
+++ b/docs/manual/style/common.xsl
@@ -13,8 +13,16 @@
  <xsl:variable name="lowercase" select="'abcdefghijklmnopqrstuvwxyz'" />
  <xsl:variable name="uppercase" select="'ABCDEFGHIJKLMNOPQRSTUVWXYZ'" />
 
- <!-- Defined parameters (overrideable) -->
- <xsl:param name="relative-path" select="'.'"/>
+ <xsl:variable name="path">
+ <xsl:choose>
+ <xsl:when test="*/relative-path/@href">
+     <xsl:value-of select="*/relative-path/@href"/>
+ </xsl:when>
+ <xsl:otherwise>
+  <xsl:value-of select="'..'"/>
+ </xsl:otherwise>
+ </xsl:choose>
+ </xsl:variable>
 
   <!--                              -->
   <!-- Builds the moduleindex page  -->
@@ -105,6 +113,62 @@
     </html>
   </xsl:template> <!-- /directiveindex -->
 
+  <!--                                                    -->
+  <!-- <manualpage>                                       -->
+  <!-- Process an entire document into an HTML page       -->
+  <!--                                                    -->
+  <xsl:template match="manualpage">
+    <html>
+      <head>
+        <xsl:comment> 
+          XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+                This file is generated from xml source: DO NOT EDIT
+          XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+        </xsl:comment>
+        <xsl:apply-templates select="meta"/>
+        <title>
+          <xsl:value-of select="title"/><xsl:value-of
+          select="$messages/message[@name='apachetitle']"/>
+        </title>
+        <link rel="stylesheet" type="text/css"
+        href="{$path}/style/manual.css" />
+     </head>
+     <body>
+        <blockquote>
+          <div align="center">
+            <img src="{$path}/images/sub.gif">
+            <xsl:attribute name="alt"><xsl:value-of
+            select="$messages/message[@name='apachedocalt']"/></xsl:attribute></img>
+            <h3><xsl:value-of
+            select="$messages/message[@name='apachehttpserver']"/></h3>
+          </div>
+          <h1 align="center"><xsl:value-of
+          select="$messages/message[@name='apachemodule']"/><xsl:text>
+          </xsl:text> <xsl:value-of select="title"/></h1>
+
+          <xsl:apply-templates select="summary"/>
+          
+          <ul>
+	  <xsl:apply-templates select="section" mode="index"/>
+          </ul>
+
+          <hr/>
+          <xsl:apply-templates select="section"/>
+       </blockquote>
+        <!-- Page footer -->
+        <h3 align="center"><xsl:value-of
+        select="$messages/message[@name='apachehttpserver']"/></h3>
+        <a href="./"><img src="{$path}/images/index.gif"><xsl:attribute
+        name="alt"><xsl:value-of
+        select="$messages/message[@name='index']"/></xsl:attribute></img></a>
+        <a href="{$path}/"><img src="{$path}/images/home.gif"><xsl:attribute
+        name="alt"><xsl:value-of
+        select="$messages/message[@name='home']"/></xsl:attribute></img></a>
+      </body>
+    </html>
+  </xsl:template><!-- /manualpage -->
+  
+
   <!--                                                    -->
   <!-- <modulesynopsis>                                   -->
   <!-- Process an entire document into an HTML page       -->
@@ -112,7 +176,6 @@
   <xsl:template match="modulesynopsis">
     <html>
       <head>
-        <!-- Do we need to translate this as well? -->
         <xsl:comment> 
           XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
                 This file is generated from xml source: DO NOT EDIT
@@ -165,31 +228,43 @@
             <xsl:apply-templates select="summary"/>
           </xsl:if>
    
-          <!-- Index of directives, automatically generated from directivesynopsis/name -->
-          <h2><xsl:value-of select="$messages/message[@name='directives']"/></h2>
+          <!-- Index of directives, automatically generated from
+          directivesynopsis/name -->
+          <h2><xsl:value-of
+          select="$messages/message[@name='directives']"/></h2>
           <xsl:if test="directivesynopsis">
             <ul>
               <xsl:for-each select="directivesynopsis">
                 <xsl:sort select="name"/>
-                <xsl:variable name="name"><xsl:value-of select="name"/></xsl:variable>
-                <xsl:variable name="lowername" select="translate($name, $uppercase, $lowercase)" />
+                <xsl:variable name="name"><xsl:value-of
+                select="name"/></xsl:variable>
+                <xsl:variable name="lowername"
+                select="translate($name, $uppercase, $lowercase)" />
                 <xsl:if test="not(@location)">
-                  <li><a href="#{$lowername}"><xsl:value-of select="name"/></a></li>
+                  <li><a href="#{$lowername}"><xsl:value-of
+                  select="name"/></a></li>
                 </xsl:if>
                 <xsl:if test="./@location">
-                  <xsl:variable name="location"><xsl:value-of select="./@location"/></xsl:variable>
-                  <xsl:variable name="lowerlocation" select="translate($location, $uppercase, $lowercase)" />
-                  <li><a href="{$lowerlocation}.html#{$lowername}"><xsl:value-of select="name"/></a></li>
+                  <xsl:variable name="location"><xsl:value-of
+                  select="./@location"/></xsl:variable>
+                  <xsl:variable name="lowerlocation"
+                  select="translate($location, $uppercase,
+                  $lowercase)" />
+                  <li><a
+                  href="{$lowerlocation}.html#{$lowername}"><xsl:value-of
+                  select="name"/></a></li>
                 </xsl:if>
               </xsl:for-each>
             </ul>
           </xsl:if>
           <xsl:if test="not(directivesynopsis)">
-            <p><xsl:value-of select="$messages/message[@name='nodirectives']"/></p>
+            <p><xsl:value-of
+            select="$messages/message[@name='nodirectives']"/></p>
           </xsl:if>
    
           <xsl:if test="seealso">
-            <p><strong><xsl:value-of select="$messages/message[@name='seealso']"/></strong></p>
+            <p><strong><xsl:value-of
+            select="$messages/message[@name='seealso']"/></strong></p>
             <ul>
               <xsl:for-each select="seealso">
                 <li><xsl:apply-templates/></li>
@@ -254,6 +329,19 @@
   
     <!-- Don't print the title twice -->
     <xsl:template match="section/title"></xsl:template>
+
+    <xsl:template match="section" mode="index">
+      <xsl:variable name="href">
+        <xsl:value-of select="@id"/>
+      </xsl:variable>
+      <li><a href="#{$href}"><xsl:apply-templates select="title"
+      mode="print"/></a>
+        <xsl:if test="section">
+          <ul><xsl:apply-templates select="section" mode="index"/></ul>
+        </xsl:if>
+      </li>
+    </xsl:template>
+
   
   <xsl:template match="directivesynopsis">
 
@@ -418,7 +506,7 @@
   <!-- in another module. References are converted into   --> 
   <!-- lower case.                                        -->
   <!--                                                    -->
-  <xsl:template match="directive">
+  <xsl:template match="directive" name="directive">
     <xsl:if test="@module">
       <xsl:variable name="module">
         <xsl:value-of select="./@module"/>
@@ -427,12 +515,14 @@
         <xsl:value-of select="."/>
       </xsl:variable>
       <xsl:variable name="lowerdirective" select="translate($directive, $uppercase, $lowercase)" />
-      <xsl:if test="@module=/modulesynopsis/name">
+      <xsl:choose>
+      <xsl:when test="@module=/modulesynopsis/name">
         <a class="directive" href="#{$lowerdirective}"><code class="directive"><xsl:if test="./@type='section'">&lt;</xsl:if><xsl:value-of select="."/><xsl:if test="./@type='section'">&gt;</xsl:if></code></a>
-      </xsl:if>
-      <xsl:if test="@module!=/modulesynopsis/name">
-        <a class="directive" href="{$module}.html#{$lowerdirective}"><code class="directive"><xsl:if test="./@type='section'">&lt;</xsl:if><xsl:value-of select="."/><xsl:if test="./@type='section'">&gt;</xsl:if></code></a>
-      </xsl:if>
+      </xsl:when>
+      <xsl:otherwise>
+        <a class="directive" href="{$path}/mod/{$module}.html#{$lowerdirective}"><code class="directive"><xsl:if test="./@type='section'">&lt;</xsl:if><xsl:value-of select="."/><xsl:if test="./@type='section'">&gt;</xsl:if></code></a>
+      </xsl:otherwise>
+      </xsl:choose>
     </xsl:if>
     <xsl:if test="not(@module)">
        <code class="directive"><xsl:if test="./@type='section'">&lt;</xsl:if><xsl:value-of select="."/><xsl:if test="./@type='section'">&gt;</xsl:if></code>
@@ -443,11 +533,39 @@
   <!-- <module>                                           -->
   <!-- Inserts a link to refereed module                  -->
   <!--                                                    -->
-  <xsl:template match="module">
-    <code><a href="{.}.html"><xsl:value-of select="."/></a></code><xsl:if test="parent::modulelist"><xsl:if test="not(position()=last())">, </xsl:if>
+  <xsl:template match="module" name="module">
+    <code><a href="{$path}/mod/{.}.html"><xsl:value-of select="."/></a></code><xsl:if test="parent::modulelist"><xsl:if test="not(position()=last())">, </xsl:if>
     </xsl:if>
   </xsl:template> <!-- /module -->
 
+  <!--                                                    -->
+  <!-- <related>                                           -->
+  <!--                                                    -->
+  <xsl:template match="related">
+  <table border="1">
+    <tr><td valign="top"><strong><xsl:value-of
+    select="$messages/message[@name='relatedmodules']"/></strong><br /><br />
+      <xsl:apply-templates select="modulelist"/>
+    </td><td valign="top"><strong><xsl:value-of
+    select="$messages/message[@name='relateddirectives']"/></strong><br
+    /><br />
+      <xsl:apply-templates select="directivelist"/>
+    </td></tr></table>
+  </xsl:template>
+     
+  <xsl:template match="related/modulelist">
+      <xsl:for-each select="module">
+        <xsl:call-template name="module"/><br />
+      </xsl:for-each>
+  </xsl:template>
+
+  <xsl:template match="related/directivelist">
+      <xsl:for-each select="directive">
+       <xsl:call-template name="directive"/><br />
+      </xsl:for-each>
+   </xsl:template>
+
+
   <!--                                                    -->
   <!-- <summary>                                          -->
   <!-- Passes through content                             -->
diff --git a/docs/manual/style/en.xml b/docs/manual/style/en.xml
index 45b2a3cddb..08e4a1abd1 100644
--- a/docs/manual/style/en.xml
+++ b/docs/manual/style/en.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="ISO-8859-1"?>
-<!DOCTYPE xsl:stylesheet [ <!ENTITY nbsp "&#160;"> ]>
+<!DOCTYPE translations [ <!ENTITY nbsp "&#160;"> ]>
 
 <!--                   -->
 <!-- Language: English -->
@@ -22,6 +22,10 @@
  <message name="moduleidentifier">Module&nbsp;Identifier</message>
  <message name="compatibility">Compatibility</message>
 
+ <!-- Used in manualpage -->
+ <message name="relatedmodules">Related Modules</message>
+ <message name="relateddirectives">Related Directives</message>
+
  <!-- Used in description box for directives -->
  <message name="syntax">Syntax</message>
  <message name="default">Default</message>
diff --git a/docs/manual/style/manualpage.dtd b/docs/manual/style/manualpage.dtd
index 8890f44559..61b4322e97 100644
--- a/docs/manual/style/manualpage.dtd
+++ b/docs/manual/style/manualpage.dtd
@@ -4,7 +4,11 @@
 %common;
 
 <!-- <manualpage> is the root element -->
-<!ELEMENT manualpage (title, summary?, seealso*, section*)>
+<!ELEMENT manualpage (relativepath, title, summary?, seealso*, section*)>
+
+<!-- The path to the root of the documentation from the current doc -->
+<!ELEMENT relativepath EMPTY>
+<!ATTLIST relativepath href CDATA #REQUIRED >
 
 <!-- the lists of related modules and/or related directives -->
 <!ELEMENT related (modulelist | directivelist)+>
-- 
2.40.0