granicus.if.org Git - apache/blob - docs/STATUS

   1 Apache HTTP Server Trunk Documentation Status File.
   2 Last modified: $Date$
   3
   4 For more information on how to contribute to the Apache Documentation
   5 Project, please see http://httpd.apache.org/docs-project/ and
   6 http://httpd.apache.org/docs-project/docsformat.html
   7
   8               ------------------------------
   9
  10 ApacheCon 2010 Hackathon To Do List
  11 ===================================
  12
  13 - mod_lua documentation with examples. (PQuerna has tentatively agreed
  14   to give us an informal session on mod_lua in order to flesh out the
  15   docs and put some force behind the notion that mod_lua can replace
  16   mod_rewrite
  17
  18 - FAQ - Decide what to do with the FAQ - both the 1.3 FAQ and the
  19   current FAQ, if in fact we still need one.
  20
  21 - Scour the httpd.apache.org website for stale, inaccurate, or
  22   misleading information which seems to have accumulated over the years.
  23
  24 - Make the docs-project website more useful and actually welcoming of
  25   new contributors.
  26
  27 To Do List
  28 =======================
  29
  30 - The dns-caveats document is largely rubbish, and needs to be
  31   completely rewritten. Many of the points stopped being true over a
  32   decade ago.
  33
  34 - The 1.3 docs need to have links from each directive forward to the
  35   /docs/current/ version of that directive, or a note that it's not
  36   avaialble in this century. See core.html for examples of how this
  37   might be done. This is a large undertaking, and involves a lot of
  38   grunt work, but will be greatly appreciated by the folks that make it
  39   to the wrong doc via Google. (Update: This is clearly going to take
  40   many months of effort, due to the volume of work and the mind-numbing
  41   tediousness.)
  42
  43 - 1.3: Verify that the auto-generated link at the top of each module doc
  44   goes to a valid 2.2 module - that is, find the modules that have
  45   changed their names and in those cases hard-code the link to the
  46   appropriate 2.2 docs (see mod_auth for example).
  47
  48 - Adding to the discussion of conditional logging, which I think
  49   could be turned into more of a howto than the one paragraph it's
  50   got now.
  51
  52 - Update the http://httpd.apache.org/docs-project/docsformat.html
  53   document to be useful. In particular:
  54     - Document the various macros that can be used in documents.
  55     - Document the translation process.
  56     - Generally update it to make it reflect the current reality of how
  57       we work.
  58     -  Improving the documentation of the documentations' build system
  59        itself (requirements, procedures)
  60
  61 - Identify which documents are grossly out of date, and fix.
  62
  63 - The FAQ never amounted to much. Review the current FAQ, which is
  64   1.3-era, and bring it into this century. (RBowen - I've copied the FAQ
  65   into the wiki at http://wiki.apache.org/httpd/FAQ and am editing it
  66   there. Consensus seems to be that this should be its new home.)
  67
  68 - Security docs are unhelpful, and assume that the reader knows nothing.
  69   Need something a little more advanced, which either discusses
  70   application-level security, or links to something that does. I'm not
  71   even sure what to say needs done. Can we get someone to elaborate on
  72   what, exactly, needs written? Ivan Ristic has said maybe he would be
  73   willing to contribute.
  74   - More content and better organisation
  75   - mod_dav resources are owned by the httpd. Perhaps write up the
  76     two-httpd dav setup covered in Rich Bowen's DAV Apachecon
  77     presentation.
  78
  79 - Performance doc is way too low-level. Several people have said that
  80   they might help out here, but it's a significant undertaking, and more
  81   than a little daunting.
  82
  83 - Windows platform docs are in desperate need of rewrites/updates for 2.x.
  84     - Bill Rowe and Bill Stoddard are good contacts for tech questions.
  85     - "using apache" has been done, "compiling apache" is still open
  86     - hints on uninstalling apache (exit monitor, close directories,
  87       registry entries etc) (PR 10154)
  88     - FAQ: UTF-8 config and URL encoding for non-ascii characters.
  89
  90 - New Auth system
  91     - Much clean-up and enhancement of aaa howto
  92     - Independent note on how to upgrade to new auth system
  93     - Discussion of DBD auth, and, in particular, examples of how to set
  94       up auth using each of the supported databases.
  95
  96 - modules docs
  97     - the follwing modules added since 2.2 lack documentation
  98         - mod_serf
  99         - mod_watchdog
 100         - mod_heartbeat
 101         - mod_heartmonitor
 102         - mod_lbmethod_bybusyness
 103         - mod_lbmethod_byrequests
 104         - mod_lbmethod_bytraffic
 105         - mod_lbmethod_heartbeat
 106         - mod_socache_dbm
 107         - mod_socache_memcache
 108         - mod_socache_shmcb
 109         - mpm_simple
 110       the list may be incomplete
 111       maybe some of the modules will not be included in 2.4
 112     - The following modules have new docs added since 2.2, but are
 113       grossly lacking in details and examples.
 114         - mod_dialup
 115     - mod_suexec: very little documentation
 116     - mod_rewrite: explain, when which variables are actually available
 117       (PR 16402)
 118
 119 - mod_substitute and reverse proxies: Add example using mod_filter
 120   (see: http://marc.info/?l=apache-httpd-users&m=128830729603423&w=2)
 121
 122 - MPM documentation
 123      - explain what the following command line options do
 124        (perhaps in the developer/debugging docs):
 125         -D DEBUG
 126         -D ONE_PROCESS
 127               one-process-mode == no threads, i.e. only one
 128               process handling the requests in a single loop?
 129
 130 - Individual docs will need some cleanup.
 131      - platform/ebcdic.xml - needs major rework for 2.0
 132      - dso.xml - Reads as though this is a nifty new thing we just came
 133        up with recently.
 134
 135 - API documentation
 136     - Ben Laurie has written some hooks documentation
 137     - authn provider API documentation could be useful
 138
 139 - SSL docs need serious update and enhancement
 140     - compat docs are wrong
 141     - no basic how to setup ssl doc
 142     mads said he was working on this, but...
 143
 144 - How does <Proxy> fit into sections.html?
 145
 146 - Missing documentation for the support program checkgid
 147
 148 - New user docs: Directory Handling (mod_dir/mod_autoindex/etc)
 149   (draft available in wiki)
 150
 151 - Enhancements to the DTD/XSL:
 152   - New index: directives by context, including listing which directives
 153     are available for each AllowOverride setting.
 154   - New index: backout modules by type (aaa, mappers, loggers etc.)
 155     probably by introducing a <category> element in modulesynopsis
 156   - Use a tag like <var> in place of <em> for things like the
 157     <syntax> listing.
 158     - in progress
 159   - add letter links to glossary and quickreference,
 160     perhaps also a term overview (sidebar)
 161   - remove <pre> elements. Use <br /> and <indent> elements to get
 162     a similar effect.
 163
 164 - Provide example solutions for the mapping of encodings, especially
 165   for .gz etc. (also in regard to our default configuration)
 166
 167 - How-To style documents for more of the daily tasks
 168     - Logging, log rotation, and log reporting
 169     - Secure mod_dav configuration
 170
 171 - Writing modules - Can we provide a basic intro to writing modules,
 172   perhaps based around mod_example, or one of the other simple example
 173   modules?
 174
 175 - http://httpd.apache.org/docs/trunk/developer/ is a graveyard, and a
 176   profound embarrassment.
 177     - Purge all the dead links
 178     - API docs are generated via 'make dox'. Find somewhere that we can
 179       do this on a schedule, and link to that from the documentation.
 180     - Introductory module authoring doc
 181     - Verify links to external resources at least every year
 182
 183 - Update the list of translations at
 184   http://httpd.apache.org/docs-project/translations.html  Some of those
 185   are accurate, and others are way outdated.
 186
 187 - I'd like to expand the discussion of conditional logging, and add a
 188   few more useful exmaples.
 189   That would be a good place to document logging of cache hit/miss:
 190   https://issues.apache.org/bugzilla/show_bug.cgi?id=48241#c2
 191
 192 - Is it worth having a doc that discusses recommended (what does this
 193   mean?) third-party modules like mod_security, mod_php, and so on - the
 194   things that we all assume everyone uses, but some folks might not know
 195   about.
 196
 197 - Clarify which directives only affect requests when they're handled
 198   by the default handler.  (e.g. ForceType, TraceEnable, etc.)
 199
 200 LaTeX Todo list
 201 ==================
 202
 203 - Dozens of other little problems with presentation, cross-referencing,
 204   etc.
 205
 206 - Cleanup xsl to make it more readable.  Almost everything
 207   that is currently in latex.xsl should probably be moved to common.xsl.
 208   There may be a license problem with the atbeginend.sty file, since
 209   latex style files rarely have explict licenses.  At worst, we can
 210   drop this and manually adjust the relevant spacing.
 211
 212 - Reduce the size of the pdf (both bytes and pages) in any way possible.
 213
 214 - Translations.
 215