Return-Path: <new-httpd-owner-new-httpd-archive=hyperreal.org@apache.org>
Delivered-To: new-httpd-archive@hyperreal.org
Received: (qmail 19942 invoked by uid 6000); 7 Sep 1999 22:30:54 -0000
Received: (qmail 19737 invoked from network); 7 Sep 1999 22:30:38 -0000
Received: from eastwood.aldigital.algroup.co.uk (194.128.162.193)
  by taz.hyperreal.org with SMTP; 7 Sep 1999 22:30:38 -0000
Received: from freeby.ben.algroup.co.uk (freeby.ben.algroup.co.uk
 [193.133.15.6]) by eastwood.aldigital.algroup.co.uk (8.8.8/8.6.12) with ESMTP
 id WAA12996; Tue, 7 Sep 1999 22:29:51 GMT
Received: from algroup.co.uk (naughty.ben.algroup.co.uk [193.133.15.107]) by
 freeby.ben.algroup.co.uk (8.6.12/8.6.12) with ESMTP id XAA09911;
 Tue, 7 Sep 1999 23:30:17 +0100
Message-ID: <37D591DE.10BCC157@algroup.co.uk>
Date: Tue, 07 Sep 1999 23:29:50 +0100
From: Ben Laurie <ben@algroup.co.uk>
Organization: A.L. Group plc
X-Mailer: Mozilla 4.6 [en-gb] (WinNT; I)
MIME-Version: 1.0
To: new-httpd@apache.org
CC: apache-docs@apache.org, gui-dev@apache.org
Subject: Re: Strawman XML
References: 
 <Pine.BSF.4.05.9908251607290.24950-100000@kim.ispra.webweaving.org>
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit
Sender: new-httpd-owner@apache.org
Precedence: bulk
Reply-To: new-httpd@apache.org

Dirk-Willem van Gulik wrote:
> 
> As a sequel on the previous question.. "has anyone parsed/recorded the
> apache documentation into a semantic format (such as one could use
> for the configurators) or automatic generation of, say a PDF version of
> the documents ??".. here is a followup:
> 
> Does anyone see great error or fundamental wrongs with the attached
> strawman ? It is the result of half an hour of perl hacking and 10 minutes
> of touch up. The script more or less works for all module mod_*.html
> files. The example below should be complete; i.e. there is no information
> lost in the transformation; and the orignal HTML can be reconstructed.
> 
> I'd like to hear some noice from people writing configurators, just to see
> where they are heading.. and from people thinking of improving the doc's,
> having multiple language variants, etc.
> 
> Dw
> 
> <MODULE id="manual/mod/mod_auth">
> <TITLE>
>         Apache module mod_auth
> </TITLE>
> <SUMMARY>
>         This module is contained in the <CODE>mod_auth.c</CODE> file, and
>         is compiled in by default. It provides for user authentication using
>         textual files.
> </SUMMARY>
> <SUMMARY LANG="nl">
>         De mod_auth module voorziet in toegangs controle op basis van text
>         bestanden met gebruikersnaam en wachtwoord gegevens.
>         <p>
>         Deze code voor deze module bevindt zich in het bestand <CODE>mod_auth.c</CODE>
>         en maakt deel uit van de groep die standaard mee gecompileerd
>         wordt.
> </SUMMARY>
> <DIRECTIVE id="AuthGroupFile">
>         <NAME>
>                 AuthGroupFile
>         </NAME>
>         <SYNTAX TYPE="TAKEONE">
>                 <ARGUMENT TYPE="filename">
>                         <DESCRIPTION>
>                                 AuthGroupFile <EM>filename</EM>
>                         </DESCRIPTION>

This can't be right: the description for the whole line is nested within
a single argument.

>                 </ARGUMENT>
>         <CONTEXT>
>                 directory, .htaccess
>         </CONTEXT>
>         <OVERRIDE>
>                 AuthConfig
>         </OVERRIDE>
>         <STATUS>
>                 Base
>         </STATUS>
>         <MODULE>
>                 mod_auth
>         </MODULE>
>         <TOKEN>
>                 The AuthGroupFile directive sets the name of a textual file containing the list
>                 of user groups for user authentication. <EM>Filename</EM> is the path

<EM>Filename</EM> should be a reference to the argument (forgot how you
do that in XML). Not sure about including things like <EM> at all,
anyway.

>                 to the group file.  If it is not absolute (<EM>i.e.</EM>, if it
>                 doesn't begin with a slash), it is treated as relative to the ServerRoot.
>                 <P>
>                 Each line of the group file contains a groupname followed by a colon, followed
>                 by the member usernames separated by spaces.
>                 <EXAMPLE>
>                         mygroup: bob joe anne
>                 </EXAMPLE>
>                 Note that searching large text files is <EM>very</EM> inefficient;
>                 <IA REF="AuthDBMGroupFile/> should be used instead.
>                 <P>
>         </TOKEN>
>         <SECURITY>
>                 Make sure that the AuthGroupFile is stored outside the
>                 document tree of the web-server; do <EM>not</EM> put it in the directory that
>                 it protects. Otherwise, clients will be able to download the AuthGroupFile.
>         <SECURITY>
>         <RELATED>
>                 <A HREF="core.html#authname">AuthName</A>,

XML refs, not HTML refs, surely?

>                 <A HREF="core.html#authtype">AuthType</A>
>                 <A HREF="#authuserfile">AuthUserFile</A>
>         <RELATED>
> </DIRECTIVE>
> <DIRECTIVE id="AuthUserFile</A>">
>         <NAME>AuthUserFile</A></NAME>
>         <SYNTAX TYPE="TAKEONE">
>                 <ARGUMENT TYPE="filename">
>                         <DESCRIPTION>
>                                 AuthUserFile <EM>filename</EM>
>                         </DESCRIPTION>
>                 </ARGUMENT>
>         </SYNTAX>

Same problem as above

>         <CONTEXT>
>                  directory, .htaccess
>         </CONTEXT>
>         <OVERRIDE>
>                  AuthConfig
>         </OVERRIDE>
>         <STATUS>
>                  Base
>         </STATUS>
>         <MODULE>
>                  mod_auth
>         </MODULE>
>         <TOKEN>
>                 The AuthUserFile directive sets the name of a textual file containing
>                 the list of users and passwords for user
>                 authentication. <EM>Filename</EM> is the path to the user
>                 file. If it is not absolute (<EM>i.e.</EM>, if it doesn't begin with a
>                 slash), it is treated as relative to the ServerRoot.
>                 <P>
>                 Each line of the user file file contains a username followed
>                 by a colon, followed by the crypt() encrypted password. The behavior
>                 of multiple occurrences of the same user is undefined.
>                 <P>
>                 The utility <code>htpasswd</code> which is installed as part of the
>                 binary distribution, or which can be found in <code>src/support</code>,
>                 is used to maintain this password file. See the <code>man</code>
>                 page for more details.
>                 <EXAMPLE>
>                         <code>htpasswd -c Filename username</code><br>
>                         Create a password file 'Filename' with 'username'
>                         as the initial ID. It will prompt for the password.
>                         <code>htpasswd Filename username2</code><br>
>                         Adds or modifies in password file 'Filename' the 'username'.
>                 </EXAMPLE>
>                 <P> Note that
>                 searching large text files is <EM>very</EM> inefficient;
>                 <IA REF="AuthDBMUserFile"> should be used instead.
>                 <P>
>         </TOKEN>
>         <SECURITY>
>                 Make sure that the AuthUserFile is stored outside the
>                 document tree of the web-server; do <EM>not</EM> put it in the directory that
>                 it protects. Otherwise, clients will be able to download the AuthUserFile.<P>
>         </SECURITY>
>         <RELATED>
>                 <A HREF="core.html#authname">AuthName</A>,
>                 <A HREF="core.html#authtype">AuthType</A>
>                 <A HREF="#authgroupfile">AuthGroupFile</A>
>         </RELATED>
> </DIRECTIVE>
> 
> <DIRECTIVE id="AuthAuthoritative</A>">
>         <NAME>AuthAuthoritative</A></NAME>
>         <SYNTAX TYPE="TAKEONE">
>                 <ARGUMENT TYPE="flag">
>                         <DEFAULT VALUE="On"/>
>                         <DESCRIPTION>
>                                 AuthAuthoritative &lt; <STRONG> on</STRONG>(default) | off &gt;
>                         </DESCRIPTION>
>                 </ARGUMENT>
>         </SYNTAX>
>         <CONTEXT>
>                  directory, .htaccess
>         </CONTEXT>
>         <OVERRIDE>
>                  AuthConfig
>         </OVERRIDE>
>         <STATUS>
>                  Base
>         </STATUS>
>         <MODULE>
>                  mod_auth
>         </MODULE>
>         <DEFAULT>
>                  By default; control is not passed on; and an unknown
>                 userID or rule will result in an Authorization Required reply. Not
>                 setting it thus keeps the system secure; and forces an NCSA compliant
>                 behaviour.
>         </DEFAULT>
>         <TOKEN>
>                 Setting the AuthAuthoritative directive explicitly to <STRONG>'off'</STRONG>
>                 allows for both authentication and authorization to be passed on to
>                 lower level modules (as defined in the <CODE>Configuration</CODE> and
>                 <CODE>modules.c</CODE> files) if there is <STRONG>no userID</STRONG> or
>                 <STRONG>rule</STRONG> matching the supplied userID. If there is a userID and/or
>                 rule specified; the usual password and access checks will be applied
>                 and a failure will give an Authorization Required reply.
>                 <P>
>                 So if a userID appears in the database of more than one module; or if
>                 a valid require directive applies to more than one module; then the
>                 first module will verify the credentials; and no access is passed on;
>                 regardless of the AuthAuthoritative setting.
>                 <P>
>                 A common use for this is in conjunction with one of the database
>                 modules; such as <A
>                 HREF="mod_auth_db.html"><CODE>mod_auth_db.c</CODE></A>, <A
>                 HREF="mod_auth_dbm.html"><CODE>mod_auth_dbm.c</CODE></A>,
>                 <CODE>mod_auth_msql.c</CODE>, and <A
>                 HREF="mod_auth_anon.html"><CODE>mod_auth_anon.c</CODE></A>. These modules
>                 supply the bulk of the user credential checking; but a few
>                 (administrator) related accesses fall through to a lower level with a
>                 well protected AuthUserFile.
>                 <P>
>         </TOKEN>
>         <SECURITY>
>                 Security: Do consider the implications of allowing a user to allow
>                 fall-through in his .htaccess file; and verify that this is really
>                 what you want; Generally it is easier to just secure a single
>                 .htpasswd file, than it is to secure a database such as mSQL. Make
>                 sure that the AuthUserFile is stored outside the document tree of the
>                 web-server; do <EM>not</EM> put it in the directory that it
>                 protects. Otherwise, clients will be able to download the
>                 AuthUserFile.
>         </SECURITY>
>         <RELATED>
>                 <A HREF="core.html#authname">AuthName</A>,
>                 <A HREF="core.html#authtype">AuthType</A>
>                 <A HREF="#authgroupfile">AuthGroupFile</A>
>         </RELATED>
> </DIRECTIVE>
> <NOTES>
> </NOTES>
> </MODULE>

--
http://www.apache-ssl.org/ben.html

"My grandfather once told me that there are two kinds of people: those
who work and those who take the credit. He told me to try to be in the
first group; there was less competition there."
     - Indira Gandhi