apache/docs/STATUS

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/ and
http://httpd.apache.org/docs-project/docsformat.html

              ------------------------------

To Do List
=======================

- Update the http://httpd.apache.org/docs-project/docsformat.html
  document to be useful. In particular:
    - 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? 
  - 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" misc/perf-scaling.xml
  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.

- New Auth system
    - 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 following modules added since 2.2 lack documentation
        - mod_serf
        - 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_substitute and reverse proxies: Add example using mod_filter
  (see: http://marc.info/?l=apache-httpd-users&m=128830729603423&w=2)

-Mod auth spanish doc add the following that a community member has created.
https://github.com/valenbg1/auth-example-mod-apache

- MPM documentation
     - explain what the following command line options do
       (perhaps in the developer/debugging docs):
        -D DEBUG
        -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?

- 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

- How does <Proxy> fit into sections.html?

- Missing documentation for the support program checkgid

- New user docs: Directory Handling (mod_dir/mod_autoindex/etc)
  (draft available in wiki)

- 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
    <syntax> listing.
    - in progress
  - add letter links to glossary and quickreference,
    perhaps also a term overview (sidebar)

- Provide example solutions for the mapping of encodings, especially
  for .gz etc. (also in regard to our default configuration)

- How-To style documents for more of the daily tasks
    - Logging, log rotation, and log reporting
    - Secure mod_dav configuration

- http://httpd.apache.org/docs/trunk/developer/ is a graveyard, and a
  profound embarrassment.
    - Purge all the dead links
    - 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?

- Examples in Rewrite Flags doc for QSD, Redirect, Chain, DPI, END, NS

- Error codes
    Decide how and where to document the error codes (AH****), and then
    start on doing it.

- If someone has xslt and LaTeX skills, they could consider getting the
  xml->LaTeX->PDF build chain working again. See specifically 
  https://issues.apache.org/bugzilla/show_bug.cgi?id=45526 for details
  of what's broken. For the moment, PDF docs are no longer referenced on
  the docs site.

- Add example of using -p flag to rotatelogs to do something useful.

- Log rotation doc - http://httpd.apache.org/docs/2.4/logs.html#rotation
  needs to mention rotatelogs as well as fairly standard log rotation
  stuff, rather than encouraging people to do this by hand.