summaryrefslogtreecommitdiffstats
path: root/docs/STATUS
blob: fc569ec07613f1140065fb7940826fa505de9d41 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
Apache HTTP Server 2.1 Documentation Status File.
Last modified: $Date: 2003/01/16 03:55:42 $

For more information on how to contribute to the Apache Documentation
Project, please see http://httpd.apache.org/docs-project/

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

Decisions pending
=================

- Where to put docs checkout on website
     - Leave it at /docs-x.y/
       +1: Joshua, Erik, Kess
        0: nd

     - /manual/x.y/
       +1: nd
       -0: Kess

     - /x.y/manual
       -1: Erik, nd
        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.)

         someone should try to convince me, what the heck is
         so cool with wikis -- nd

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.
    - "using apache" has been done, "compiling apache" is still open

- New Auth system
    - Much clean-up and enhancement of aaa howto
    - Independent note on how to upgrade to new auth system

- 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
    
- 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
     - explain what the following command line options do
       (perhaps in the developer/debugging docs):
        -D DEBUG
        -D ONE_PROCESS
              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/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: many configure options are missing,
      especially those inherited from apr.

- API documentation
    Status: 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.

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.
  - 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 
    <syntax> listing.
    - in progress
  - 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.

* Autogeneration of PDF
  - Andr� is working on this, Erik volunteers to help out

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

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

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