-Apache HTTP Server 2.1 Documentation Status File.
-Last modified: $Date: 2003/05/02 00:58:26 $
+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
-=================
-
- - 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?).
- <Files *.tar.gz>
- Forcetype ...
- </Files>
-
- - 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
+To Do List
=======================
-- 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.
+- 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: UTF-8 config and URL encoding for non-ascii characters.
- 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 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.
+
+- 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
-- 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.
+- How does <Proxy> fit into sections.html?
-- SSL docs are generally good, but they need a refreshing by someone
- familiar with mod_ssl and openssl.
+- Missing documentation for the support program checkgid
-Documentation improvements
-==========================
+- 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)
- - 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:
- <page><variant lang="en" href="">title</variant>)?
- - looking for other good ideas ;-)
- - remove <pre> elements. Use <br /> and <indent> 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
+- 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
+
+- 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
+==================
+
+- Dozens of other little problems with presentation, cross-referencing,
+ etc.
+
+- 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
+ drop this and manually adjust the relevant spacing.
+
+- Reduce the size of the pdf (both bytes and pages) in any way possible.
+
+- Translations.
+
-# converting from nroff to xml
-programs/other.html
projects / apache / blobdiff