-Apache HTTP Server 2.1 Documentation Status File.
-Last modified: $Date: 2003/10/31 08:05:42 $
+Apache HTTP Server Trunk Documentation Status File. Last modified: $Date$
For more information on how to contribute to the Apache Documentation
-Project, please see http://httpd.apache.org/docs-project/
+Project, please see http://httpd.apache.org/docs-project/ and
+http://httpd.apache.org/docs-project/docsformat.html
------------------------------
-Decisions pending
-=================
-
-- Remove manual/search/manual-index.cgi from the distribution and
- httpd-2.0-docs/ repository? These can be maintained in the httpd-site
- repository but don't belong in distributions unless we introduce the
- tools to generate the index database or keep a current database checked
- into cvs.
- +1: wrowe, nd, slive, erikabele, kess, mads
-
-- Remove several out-of-place files into somewhere in the tree outside
- of the actual web site content? Erik suggests we merge the two icons
- readmes into one. Perhaps all of these go into httpd-2.0/docs/README?
- error/readme
- icons/readme
- icons/small/readme.txt
- Votes for a single top-level README reference?
- +1: wrowe, slive, nd, erikabele, kess, mads
-
-
-Things That Need Fixing
+To Do List
=======================
-- Windows platform docs are in desperate need of rewrites/updates for 2.0.
- - Bill Rowe and Bill Stoddard are good contacts for tech questions.
+- Update the http://httpd.apache.org/docs-project/docsformat.html
+ document to be useful. In particular:
+ - Document the various macros that can be used in documents.
+ - Document the translation process.
+ - Generally update it to make it reflect the current reality of how
+ we work.
+ - Improving the documentation of the documentations' build system
+ itself (requirements, procedures)
+
+- Continue to enhance the FAQ, which is in the wiki:
+ http://wiki.apache.org/httpd/FAQ
+
+- Security docs are unhelpful, and assume that the reader knows nothing.
+ Need something a little more advanced, which either discusses
+ application-level security, or links to something that does. I'm not
+ even sure what to say needs done. Can we get someone to elaborate on
+ what, exactly, needs written? Ivan Ristic has said maybe he would be
+ willing to contribute.
+ - More content and better organisation
+ - mod_dav resources are owned by the httpd. Perhaps write up the
+ two-httpd dav setup covered in Rich Bowen's DAV Apachecon
+ presentation.
+
+- Performance doc "drop-in replace" wikified by Igor from Sander's
+ presentation: http://wiki.apache.org/httpd/PerformanceScalingUp
+ as well as: http://wiki.apache.org/httpd/PerformanceScalingOut
+ They both need review and updates to reflect the current state
+ of the art.
+
+- Windows platform docs are in desperate need of rewrites/updates for 2.x.
+ - Bill Rowe is a good contact 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.
- - FAQ: AcceptEx failed / virusscanner, firewall fun
- New Auth system
- - Much clean-up and enhancement of aaa howto
+ - Much clean-up and enhancement of aaa howto (Can someone clarify
+ exactly what needs cleaned up and enhanced?)
- Independent note on how to upgrade to new auth system
+ - Discussion of DBD auth, and, in particular, examples of how to set
+ up auth using each of the supported databases.
+
+- Expression syntax for <If>, Require expr, SetEnvIfExpr, CustomLog, ...
+ Start is in expr.xml, igalic is working on this
- modules docs
+ - the follwing modules added since 2.2 lack documentation
+ - mod_serf
+ - mod_watchdog
+ - mod_heartbeat
+ - mod_heartmonitor
+ - mod_lbmethod_heartbeat
+ - mod_socache_dbm
+ - mod_socache_memcache
+ - mod_socache_shmcb
+ - mpm_simple
+ the list may be incomplete
+ maybe some of the modules will not be included in 2.4
- 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 which variables are actually available
- (PR 16402)
-
+
+- mod_substitute and reverse proxies: Add example using mod_filter
+ (see: http://marc.info/?l=apache-httpd-users&m=128830729603423&w=2)
+
- MPM documentation
- explain what the following command line options do
(perhaps in the developer/debugging docs):
-D DEBUG
- -D ONE_PROCESS
+ -D ONE_PROCESS -- is this the same as -X, if not, should it be?
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.
+- Identify which documents are grossly out of date, and fix.
+ - platform/ebcdic.xml - needs major rework for 2.0
+ - SSL docs need serious update and enhancement
+ - compat docs are wrong
+ - A basic how to has been started here:
+ http://wiki.apache.org/httpd/SettingUpModSSL
+ but it needs some work...
+ - http://blag.esotericsystems.at/2011/01/answering-trivial-and-interesting-questions-with-openssl/
+ looks like a good starting point for overhauling the FAQ, and
+ has been placed at our disposal by the author.
- API documentation
- Ben Laurie has written some hooks documentation
- authn provider API documentation could be useful
-- SSL docs are generally good, but they need a refreshing by someone
- familiar with mod_ssl and openssl.
-
- - I've begun working on this (again) --mads
-
- How does <Proxy> fit into sections.html?
-Documentation improvements
-==========================
+- Missing documentation for the support program checkgid
-* Missing documentation for the support programs htdbm and checkgid
+- New user docs: Directory Handling (mod_dir/mod_autoindex/etc)
+ (draft available in wiki)
-* New user docs: Directory Handling (mod_dir/mod_autoindex/etc)
-
-* Enhancements to the DTD/XSL:
- - <glossary> tag that links to the glossary and uses some special
- style in the css.
+- Enhancements to the DTD/XSL:
- 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 <category> element in modulesynopsis
- - Use a tag like <var> in place of <em> for things like the
+ - Use a tag like <var> in place of <em> for things like the
<syntax> listing.
- in progress
- - add letter links to glossary and quickreference,
+ - add letter links to glossary and quickreference,
perhaps also a term overview (sidebar)
- - remove <pre> elements. Use <br /> and <indent> elements to get
- a similar effect.
-
-* Improving the documentation of the documentations' build system
- itself (requirements, procedures)
-
-* 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)
-
- - I've begun working on this --jsl
-
-* Provide example solutions for the mapping of encodings, especially
+- Provide example solutions for the mapping of encodings, especially
for .gz etc. (also in regard to our default configuration)
-* 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.
-
-* Change the name 'Apache' to 'Apache HTTP Server' or 'http'.
+- How-To style documents for more of the daily tasks
+ - Logging, log rotation, and log reporting
+ - Secure mod_dav configuration
+
+- Writing modules - Can we provide a basic intro to writing modules,
+ perhaps based around mod_example, or one of the other simple example
+ modules?
+
+- http://httpd.apache.org/docs/trunk/developer/ is a graveyard, and a
+ profound embarrassment.
+ - Purge all the dead links
+ - Introductory module authoring doc
+ - Verify links to external resources at least every year
+
+- Update the list of translations at
+ http://httpd.apache.org/docs-project/translations.html Some of those
+ are accurate, and others are way outdated.
+
+- I'd like to expand the discussion of conditional logging, and add a
+ few more useful exmaples.
+ That would be a good place to document logging of cache hit/miss:
+ https://issues.apache.org/bugzilla/show_bug.cgi?id=48241#c2
+
+- Is it worth having a doc that discusses recommended (what does this
+ mean?) third-party modules like mod_security, mod_php, and so on - the
+ things that we all assume everyone uses, but some folks might not know
+ about.
+
+- Clarify which directives only affect requests when they're handled
+ by the default handler. (e.g. ForceType, TraceEnable, etc.)
+
+- Add examples using expr to mod_rewrite recipes. Possibly benchmark the
+ different approaches and make intelligent remarks about the
+ comparative value of each.
+
+- Fix this error message:
+ Request exceeded the limit of 10 internal redirects due to probable
+ configuration error. Use 'LimitInternalRecursion' to increase the limit
+ if necessary. Use 'LogLevel debug' to get a backtrace.
+ This error message is often returned when a RewriteRUle loops, in
+ which case setting LimitInternalRecursion won't do anything towards
+ fixing the problem. However, the error message is already very long.
+ Thoughts?
LaTeX Todo list
==================
-- Tables
- Add <columnspec> to xml files.
-
-- Images
-
- A quick search makes me believe that pdftex will not handle gifs.
- It probably will handle png.
-
-- Hundreds of other little problems with presentation, cross-referencing,
+- Dozens of other little problems with presentation, cross-referencing,
etc.
-- Fix build system
-
-- Cleanup xsl to make it more readable and add licenses. Almost everything
+- Cleanup xsl to make it more readable. Almost everything
that is currently in latex.xsl should probably be moved to common.xsl.
There may be a license problem with the atbeginend.sty file, since
latex style files rarely have explict licenses. At worst, we can
- Reduce the size of the pdf (both bytes and pages) in any way possible.
-- Speed up the XSLT tranform.
-
- Translations.
+
+