X-Git-Url: https://granicus.if.org/sourcecode?a=blobdiff_plain;f=docs%2FSTATUS;h=c2446f69a163a397b7d379ac1ac79af07a507df5;hb=96746b9253f64ebc4df91522eb59d5cc111dae84;hp=d3cb9a29989da4072819ff761539774e73f4d223;hpb=bee1a3e808cf0d45d3c564c26a3de719b569deb8;p=apache diff --git a/docs/STATUS b/docs/STATUS index d3cb9a2998..c2446f69a1 100644 --- a/docs/STATUS +++ b/docs/STATUS @@ -1,192 +1,180 @@ -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?). - - 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 +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 , 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 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: - - 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 element in modulesynopsis - - Use a tag like in place of for things like the + - Use a tag like in place of for things like the 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: - 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 +- 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