documentation effort

[Chris Parker]

At 06:38 PM 5/24/2001 +0200, Khaled Daham wrote:
>How did DocBook fail one of the above criteria ?
>IMHO DocBook is the most generic and complete set that someone can pick up
>regardless of OS preference, packages exists etc.
>
> > debiandoc requires perl (and a few perl modules), Jim Clark's 'sp', tex,
> > and the DTD file.  In Debian, the package is debiandoc-sgml.
>
>Which make it less attractive for those not doing Debian.

I dunno, maybe I'm old fashioned, but plain-text works for me, and
is a lot more cross-platform.

> > Offer skeleton tables-of-contents, as to how you think some documentation
> > should be structured.
> >
> > Where should the docs go?  In the radiusd module, too?  In its own module?
>
>Why not just keep it in doc/ ?

I think a better organization would be to have each module in a separate
directory undor /doc, and all of the readme's/examples for that module
are placed in that directory.

Something like the following:

   /doc
       README
       ...
       main module stuff ( users, etc. )
       ...
       /rlm_sql
             README
             example.conf   ( sample config(s) )
             mysql.sql
             postgresql.sql
             oracle.sql
       /rlm_ldap
             README
             example.conf   ( sample config(s) )
             radius.schema
             radius-v3.schema
       ...

This will reduce the "clutter" and make it more navigable to find
the docs/schema/table formats for the modules you are looking for
( IMHO of course ).

Agree/Disagree/Cowboy Neal?

-Chris
--
    \\\|||///  \  Chris Parker:       Manager, Development Engineering
    \ ~   ~ /   \   cparker@starnetusa.net   \   cparker@megapop.net
    | @   @ |    \    www.starnetusa.net      \    www.megapop.net
oOo---(_)---oOo--\------------------------------------------------------
                   \ Without C we would have 'obol', 'basi', and 'pasal'