Mailing-List: contact docs-help@httpd.apache.org; run by ezmlm
Date: Wed, 4 Dec 2002 23:45:53 -0500
Message-Id: <200212050445.gB54jrE20531@Boron.MeepZor.Com>
From: Rodent of Unusual Size <Ken.Coar@Golux.Com>
To: Apache httpd documenters <apache-docs@Apache.Org>
Subject: [STATUS] (httpd-docs-2.0) Wed Dec  4 23:45:53 EST 2002

Apache HTTP Server 2.0 Documentation Status File.
Last modified: $Date: 2002/11/23 18:49:31 $

If you are interested in helping accomplish some of the tasks on this
list or otherwise improving the documentation, please join the
apache-docs mailing list by mailing to docs-subscribe@httpd.apache.org

For more information on how to contribute to the Apache Documentation
Project, please see http://httpd.apache.org/docs-project/, and
http://apache-server.com/tutorials/ATdocs-project.html for an excellent
tutorial on how to get started with making your contribution.

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

Things That Need Fixing
=======================

- 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.

- New Auth system
    (Wait on this until the code has stabalized a little)
    - With the new auth system, we have a bunch of directives that are
      duplicated in multiple modules, where one of the modules is obsolete.
      We probably need to mark the old modules as <status>obsolete</status>
      and key on that to omit them from the directive index, etc.
    - Much clean-up and enhancement of docs
    - Independent note on how to upgrade to new auth system

- 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.)

- modules docs
    - mod_suexec: very little documentation
    - mod_proxy: updates for 2.0
    - mod_status: updates for 2.0
    - mod_example: updates for 2.0
    - mod_file_cache: missing documentation

    
- 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.

- MPM documentation
     - Non unix/windows MPMs still need to be completed.
     - the perchild directives in threaded/worker need docs

- 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/tutorials.html - mostly not relevant to 2.0
     - misc/stopping.html
     - misc/rewriteguide.html - needs cleaning in 1.3 and 2.0
     - misc/known_client_problems.html - mostly ancient
     - 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.

- API documentation
    Status: Ben Laurie has written some hooks documentation

- 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.

- Translations
    There are several efforts underway to translate the documentation
    into other languages. A detailed list of the currently known
    translators (and the corresponding websites) can be found at

    http://httpd.apache.org/docs-project/translations.html


Documentation improvements
==========================

* 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.
  - New index: directives by context, including listing which directives
    are available for each AllowOverride setting.
  - Use a tag like <var> in place of <em> for things like the 
    <syntax> listing.
    - nd volunteers
  - 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
    same effect.
  - need to add new <parentdocument> element to more docs

* Autogeneration of PDF
  - FOP?

* Windows help file
  - David Shane Holden was working on this

* Improving the "security docs"
  - More content and better organisation.

* 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)

  - We'll need to audit these and find out which ones need munging, as
    some of it looks ok.  --jsl

* 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.].)

XML Conversions
===============

The following files need to be converted to XML as described at
http://httpd.apache.org/docs-project/docsformat.html

index.html.en                      # leave in html?
howto/auth.html.en
misc/custom_errordocs.html         # obsolete?
misc/descriptors.html              # obsolete?
misc/fin_wait_2.html               # obsolete?
misc/known_client_problems.html    # obsolete?
misc/tutorials.html                # obsolete?
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
developer/API.html
developer/debugging.html
developer/documenting.html
developer/filters.html
developer/footer.html
developer/header.html
developer/hooks.html
developer/index.html
developer/layeredio.html
developer/request.html
developer/thread_safety.html
developer/modules.html.en

# 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