Return-Path: Delivered-To: apmail-httpd-docs-archive@httpd.apache.org Received: (qmail 49920 invoked by uid 500); 1 May 2003 03:45:58 -0000 Mailing-List: contact docs-help@httpd.apache.org; run by ezmlm Precedence: bulk list-help: list-unsubscribe: list-post: Reply-To: docs@httpd.apache.org Delivered-To: mailing list docs@httpd.apache.org Received: (qmail 49908 invoked by uid 500); 1 May 2003 03:45:58 -0000 Delivered-To: apmail-apache-docs@Apache.Org Date: Wed, 30 Apr 2003 23:46:08 -0400 Message-Id: <200305010346.h413k8h01966@Boron.MeepZor.Com> From: Rodent of Unusual Size To: Apache httpd documenters Subject: [STATUS] (httpd-docs-2.0) Wed Apr 30 23:46:08 EDT 2003 X-Note: This is an automated message. X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N Apache HTTP Server 2.1 Documentation Status File. Last modified: $Date: 2003/05/01 00:39:16 $ For more information on how to contribute to the Apache Documentation Project, please see http://httpd.apache.org/docs-project/ ------------------------------ Decisions pending ================= - Backport removal of SSI from docs directory in default config docs/conf/httpd-std.conf.in rev 1.36 docs/conf/httpd-win.conf rev 1.82 +1: slive, nd -Comment out .gz etc. AddEncoding lines in our default configuration. docs/conf/httpd-std.conf.in rev 1.32 jerenkrantz said in the log message: Current browsers have a tendency to decompress the data when no one really wants it to do that. If you want the old behavior that leads to transparent decompression by modern browsers, uncomment these lines. But, this shouldn't be our default. Someone else said: Certainly wasn't in 1.3. nd adds: we should provide example solutions somewhere in the docs. e.g.: .tar.gz should get the content-type application/x-gzip (hmm, bad x-, better suggestions?). Forcetype ... - Backport to 2.0 +1: wrowe, slive, nd - Figure out what to do about the 2.0 FAQ - Copy important stuff from 1.3? - Some kind of XML? - Something that allows dynamic contributions from users a la FAQ-O-Matic? (I don't think any really good software exists for this.) - Perhaps we can use the newly created Wiki for this. (SubWiki, with the possibility to get nice commit mails.) nd: someone should try to convince me, what the heck is so cool with wikis erik: it lowers the entry barrier and therefore users are able to contribute (handy for a FAQ, see PHP site) nd: yes, good bad example. The PHP docs would mostly be better without these comments. I don't want to censor the entries, but also don't want to leave them without control. IMHO it's better to incorporate changes into the static docs. We need some better way of feedback, anyway. Things That Need Fixing ======================= - XML - Rewriting of the remainder of the manual into xml is in progress. See the bottom of this file for status info. - add ids to non-directive sections of the module docs, so they get a chance to be linked in the sidebar - Windows platform docs are in desperate need of rewrites/updates for 2.0. - Bill Rowe and Bill Stoddard are good contacts for tech questions. - "using apache" has been done, "compiling apache" is still open - hints on uninstalling apache (exit monitor, close directories, registry entries etc) (PR 10154) - FAQ! UTF-8 config and URL encoding for non-ascii characters. - New Auth system - Much clean-up and enhancement of aaa howto - Independent note on how to upgrade to new auth system - modules docs - mod_suexec: very little documentation - mod_proxy: updates for 2.0 - mod_status: updates for 2.0 - mod_example: updates for 2.0 - mod_rewrite: explain, when what variables are actually available (PR 16402) - man pages - Convert from nroff to our xml format. See list at bottom. - Then if someone gets creative, they can try to find an automatic way to convert back to nroff. - An example: http://cyberelk.net/tim/data/xmlto/db2man/ This is designed for docbook, but it could be adapted. I'm not sure what the license is. - MPM documentation - explain what the following command line options do (perhaps in the developer/debugging docs): -D DEBUG -D ONE_PROCESS one-process-mode == no threads, i.e. only one process handling the requests in a single loop? -D NO_DETACH (not in every MPM avail.) no daemon, but detached from terminal? -D FOREGROUND (not in every MPM avail.) ? - Individual docs will need some cleanup. - misc/custom_errordocs.html needs to be updated to essentially describe how the international error docs included in 2.0 work - misc/perf-tuning.html - needs major rewrite for 2.0 - misc/rewriteguide.html - needs cleaning in 1.3 and 2.0 - platform/ebcdic.xml - needs major rework for 2.0 - New build process. - install.html has had a first-pass rewrite, it is basically accurate, but very incomplete: many configure options are missing, especially those inherited from apr. - API documentation - Ben Laurie has written some hooks documentation - authn provider API documentation could be useful - Several features in Apache require write-access to the filesystem. Examples: CacheRoot, DavLockDB, ScriptLog We should treat the things consistently in the docs, and perhaps suggest the use of directory like /usr/local/apache2/var/ that is httpd-writable. - SSL docs are generally good, but they need a refreshing by someone familiar with mod_ssl and openssl. Documentation improvements ========================== * New user docs: Directory Handling (mod_dir/mod_autoindex/etc) * Enhancements to the DTD/XSL: - tag that links to the glossary and uses some special style in the css. - New index: directives by context, including listing which directives are available for each AllowOverride setting. - New index: backout modules by type (aaa, mappers, loggers etc.) probably by introducing a element in modulesynopsis - Use a tag like in place of for things like the listing. - in progress - add letter links to glossary and quickreference, perhaps also a term overview (sidebar) - cross references between the different languages, at least links from non-en docs to the originals. - Javascript? - post processing (s&r, XML::Parser, ...)? - pre processing ([kind of] type maps generated from sitemap entries like: title)? - looking for other good ideas ;-) - remove 
 elements. Use 
 and  elements to get
    a similar effect.

* Autogeneration of PDF
  - Andr� is working on this, Erik volunteers to help out

* Improving the "security docs"
  - More content and better organisation.
    - mod_dav ressources are owned by the httpd

* General cleaning and improving of module docs

* Making the directive definitions "less terse" (i.e., adding more
  examples and details to the definitions of the directives)

* Making site-specific enhancements easier, including a documented
  and robust way for 3P module docco to be added -- and have it
  survive a server docco upgrade

  - This could be something a simple and hackish as a manual/extra/
    directory (a la the 1.3 src/modules/extra/ directory) and a
    script in the support directory that scans the files there and
    updates the manual indices.  (We do something like that now for
    httpd.conf file with apxs [LoadModule, etc.].)

* Summarize all the implemented drafts/standards with short explanations
  within a document. (PR 16938)

XML Conversions
===============

The following files need to be converted to XML as described at
http://httpd.apache.org/docs-project/docsformat.html

# Perhaps these should be left in html to allow the developers to
# play with them
# nope. in order to create other formats, we need 'em as xml. --nd
developer/API.html

# converting from nroff to xml
programs/htpasswd.html
programs/other.html

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org