Apache HTTP Server 2.1 Documentation Status File.

Last modified: $Date: 2002/12/08 21:05:55 $

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

index.html.en # leave in html?

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

# Perhaps these should be left in html to allow the developers to

# play with them

# converting from nroff to xml