documentation organization

[David Relson]

Greetings,

Currently, bogofilter has documentation in several places.

In the bogofilter directory exist AUTHORS, NEWS, README, README.*, and 
UPGRADE.  In bogofilter/doc exist several integrating-with-xxx files.  In 
bogofilter/contrib exist several additional README.xyz files.

When installed from the binary RPM, /usr/share/doc/bogofilter-x.y.z 
contains all these files plus the .xml files (from which the man pages are 
built) plus many of the scripts from bogofilter/contrib.  In addition 
/usr/share/man/man1 contains man pages for bogofilter, bogoutil, bogolexer, 
and bogoupgrade.

It has been suggested that all of bogofilter's documentation be in one 
directory, so it can be found more easily.  I agree that this would be 
useful.  Since the RPM installation already does this, but the source code 
doesn't, I'm thinking about reorganizing the source code (a bit).

First, there's the installation to consider:

The /usr/share/doc directory is somewhat cluttered.  There are standalone 
README files, the 4 bogo*.xml files, README files that document particular 
scripts, groups of files (for example, the qmail group), etc.  Should these 
files be left alone in this directory, or should they be organized?  One 
organization would be to add config and contrib subdirectories within 
/usr/share/doc.  The config directory would/could have copies of 
bogofilter.cf.example and files for qmail and procmail.  The contrib 
directory would have all the scripts.  An open question is whether all 
documentation should remain at the top level or whether a script's 
documentation should be in contrib with the script.

Second, there are the source directories which developers and builders use:

Should all documentation be moved to bogofilter/doc?  Probably not, since 
README, NEWS, AUTHORS, COPYING, etc are traditionally at the top 
level.  I'd vote for keeping them there.  For the docs currently in 
bogofilter/contrib (and which document the scripts), I'd keep the files 
where they are and add a link from bogofilter/doc to 
bogofilter/contrib.  I'd suggest moving the other documentation files from 
the top level to bogofilter/doc.  In bogofilter/README I'd add a pointer to 
bogofilter/doc.

David