RE: [V] Remove out-of-date doc files
There must be a text/plain file in the top-level source
directory named README that gives the basic information.
There should be a short BUGS file, and possibly a short BETA
file, but they can both be incorporated into README.
README.packages can go, as it has by now served its purpose
(or perhaps never served it very well at all).
README need not be all that long, but it MUST give a short
blurb describing the program, (at least for now) describing
the unbundled packages, a description of the basic install process:
tar xzf xemacs.tar.gz
cd xemacs
./configure --prefix=PREFIX ...
make
make check
[on some platforms chown root:mail lib-src/movemail; chmod
g+s lib-src/movemail] make install cd PREFIX/lib test ! -d
xemacs && mkdir xemacs cd xemacs tar xzf
xemacs-sumo-DATE.tar.gz [optionally tar xzf
xemacs-mule-sumo-DATE.tar.gz]
and a pointer to INSTALL, a brief mention that it is beta and
a pointer to beta.info/.texi, and the bug report address and
a pointer to the information about reporting bugs in
text/more-or-less-readable as well as the Info or web docs.
Basically, I got rid of this stuff because of the maintenance hassle of
having duplicated text and the difficulty in people finding what they are
looking for.
As I see it, someone looking for README will find it, and there will be
pointers to the FAQ, where the basic info plus a lot more is found. If info
is in the README and not the FAQ (as used to be the case), people who look
at the FAQ will probably miss the stuff scattered in these various textual,
source-only files (i.e. much of the info is relevant to non-developers, too,
and the FAQ is on the website as well as everywhere else).
If you copy the FAQ stuff into README, you have the problem of duplication
and the associated maintenance headache.
Since you obviously have a very specific idea for what the README file
should contain, could you either
[a] (ideally) Write a template file and a script that will construct the
README file by filling in the relevant text from the info files, so we solve
the duplication problem; or
[b] (next possibility) Construct the README file manually out of the
relevant FAQ sections, or
[c] (least ideal) Make an outline of exactly what should go in, and which
FAQ sections the text should come from, and I'll see what I can do.
Ben