Rodent of Unusual Size wrote:
>
> Raymond S Brand wrote:
> >
> > If this index is going to go into the docs, then I suggest that it
> > and the existing alphabetical module list both have links from the
> > "top" index page.
>
> So are we leaning toward separate pages? One ordered lexically
> (the current version) and one functionally?
Yes.
> > And to be> complete, you should also create another directive
> > index that categorizes the individual directives like you did
> > the modules, and link the two directive indexes off the "top"
> > index page.
>
> A good idea, but a lot more work. :-)
That's why I didn't volunteer :-)
> One problem with keeping separate lists is that there will
> be a tendency for them to fall out of sync. We could do
> some neat single-data-source things if we could use PHP or
> the like, but we have to stay with basic HTML and some SSI
> because of the mirrors and release packaging.
Could definitely be a problem but the "many eyes" approach should
keep it mostly under control.
<Fair_Warning "What follows is an idea I have no time to implement>
An alternative to some form of dynamic content is build the directive
index pages and module index pages statically from a set of source
files.
Basic setup:
Create a doc source directory and populate it with a file
for each module.
Each module file contains the module name, short description,
list of functional areas, long description, and the
list of implemented directives in some parse-able
structure.
Each implemented directive in the list contains the directive
name, attributes, description, etc. in some parse-able
structure.
Build process:
A program loops through the files in the doc source directory
producing the static HTML doc pages. The program
should get run as part of the build process and could
also be run when creating the source tarballs.
Nice advantage:
Documentation for non ASF modules can be included in the end-users
doc tree easily.
</Fair_Warning>
Raymond S Brand
