X-Git-Url: https://granicus.if.org/sourcecode?a=blobdiff_plain;f=docs%2FSTATUS;h=c2446f69a163a397b7d379ac1ac79af07a507df5;hb=96746b9253f64ebc4df91522eb59d5cc111dae84;hp=a9bf5b7b2fc6454e2c66e9ee86f4eb0a79478ce3;hpb=10c70ea0cea76d6aab58f42d7dd4eb23bdc3e266;p=apache diff --git a/docs/STATUS b/docs/STATUS index a9bf5b7b2f..c2446f69a1 100644 --- a/docs/STATUS +++ b/docs/STATUS @@ -1,216 +1,180 @@ -Apache HTTP Server 2.1 Documentation Status File. -Last modified: $Date: 2003/04/09 20:47:33 $ +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 -================= - - -Comment out .gz etc. AddEncoding lines in our default configuration. - docs/conf/httpd-std.conf.in rev 1.32 - jerenkranz: Current browsers have a tendency to decompress the data - when no one really wants it to do that. If you want the - 2.0 behavior that leads to transparent decompression - by modern browsers, uncomment these lines. But, this - shouldn't be our default, and certainly wasn't in 1.3. - - Backport to 2.0 - +1: wrowe, slive - -- Where to put docs checkout on website - - Leave it at /docs-x.y/ - +1: slive, Erik, Kess, Mads - 0: nd - - - /manual/x.y/ - +1: nd - -0: Kess, Mads - - - /x.y/manual - -1: Erik, nd, Mads - 0: Kess - though it's probably my suggestion, I don't like it - very well ;-) -- 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 -- nd - 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. - -- SSL docs are generally good, but they need a refreshing by someone - familiar with mod_ssl and openssl. +- How does fit into sections.html? -Documentation improvements -========================== +- Missing documentation for the support program checkgid -* New user docs: Directory Handling (mod_dir/mod_autoindex/etc) +- New user docs: Directory Handling (mod_dir/mod_autoindex/etc) + (draft available in wiki) -* 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
+- Provide example solutions for the mapping of encodings, especially
+  for .gz etc. (also in regard to our default configuration)
 
-* Windows help file
-  - David Shane Holden was working on this
+- How-To style documents for more of the daily tasks
+    - Logging, log rotation, and log reporting
+    - Secure mod_dav configuration
 
-* Improving the "security docs"
-  - More content and better organisation.
-    - mod_dav ressources are owned by the httpd
+- Writing modules - Can we provide a basic intro to writing modules,
+  perhaps based around mod_example, or one of the other simple example
+  modules?
 
-* General cleaning and improving of module docs
+- 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
 
-* Making the directive definitions "less terse" (i.e., adding more
-  examples and details to the definitions of the directives)
+- Update the list of translations at
+  http://httpd.apache.org/docs-project/translations.html  Some of those
+  are accurate, and others are way outdated.
 
-* 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
+- 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
 
-  - 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.].)
+- 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.
 
-* Summarize all the implemented drafts/standards with short explanations
-  within a document. (PR 16938)
+- Clarify which directives only affect requests when they're handled
+  by the default handler.  (e.g. ForceType, TraceEnable, etc.)
 
-XML Conversions
-===============
+- 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.
 
-The following files need to be converted to XML as described at
-http://httpd.apache.org/docs-project/docsformat.html
 
-expand.pl                          # delete after finishing everything
-
-# These will require manual.xsl changes
-faq/footer.html                    
-faq/header.html
-faq/index.html
-faq/support.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
-
-# converting from nroff to xml
-programs/ab.html
-programs/apxs.html
-programs/dbmmanage.html
-programs/footer.html
-programs/header.html
-programs/htdigest.html
-programs/htpasswd.html
-programs/index.html
-programs/logresolve.html
-programs/other.html
-programs/rotatelogs.html
-programs/suexec.html