I'm really glad to see this packaging proposal emerging.
Ideally, all packages would be documented to the degree found in the Chicken
eggs, or Alex's irregex package, or Edi Weitz's Common Lisp packages. Good,
consistent documentation is one of the key ways of selling a package
repository.
Color me profoundly neutral on the choice of markup formats. However, if I did
have a preference, it would probably be HTML, on the grounds that that requires
zero ancillary software (plain text has the same virtue). But I do think the
choice should be standardized in the package format so that package management
tools can process the documentation in an automated way. Ideally, there should
be some file that the tools keep up-to-date that acts as a directory, or table
of contents, of all currently installed packages. (Chicken does this extremely
well.)
I would suggest the following conventions for package documentation.
* At the top level, three files with generic information (these can be
consolidated into one README file, if there's a standard skeleton for what a
README file looks like).
- README: general package description
- INSTALL: information that should be read _prior_ to installation, e.g.,
auxiliary code that must be installed first; I'm always surprised at packages
that only tell you important installation information in ways that require you
to install the package first. This reminds me of the time I bought a very large
CRT TV and managed to get it home by myself. After opening the box and lifting
the TV out of the box, I found a sheet of paper inside (under where the TV had
been) that said `WARNING: THIS DEVICE IS TOO HEAVY TO BE LIFTED BY ONE PERSON.
ALWAYS HAVE TWO PEOPLE MOVE THE BOX OR REMOVE THE TELEVISION FROM THE BOX'.
- COPYING: description of licensing terms
* All other documentation appears in a doc directory, with the entry point
being the file index.html (change this to some other name if other than HTML is
the format).
* As part of preparing a package to add it to a repository, any preprocessing
of the documentation (e.g., extracting documentation from source code) is
performed. A standard prepare-doc target in a Makefile (if the package manager
uses make) is a good way to do that.
* Repositories present an automatically-maintained page or page hierarchy
that acts as a table of contents for all packages, linking to the documentation
for each available package. Similarly, the package management tool keeps an
updated table of contents of installed packages, so that a user always has an
up-to-date `User's Manual' for all installed packages on their system.
* Standard documentation conventions should discourage typographical
eccentricities (e.g., elaborate CSS specifications, weird frames, etc.), so as
to produce a consistent look-and-feel for all documentation.
On the subject of CPAN, I'm not a Perl user, so don't know much about how CPAN
packages work. My own experience with CPAN has generally been rather
frustrating, because most packages I have tried to install ended up having
unsatisfied dependencies, and I'd generally find myself doing several
iterations, and end up getting three quarters of everything installed before
discovering one package that was broken or didn't work on my OS, or the like
(there may be a better way of using CPAN, but I'm just relating my experience).
I'd prefer dependency management to be copied from Debian than from CPAN.
-- vincent
_______________________________________________
Scheme-reports mailing list
[email protected]
http://lists.scheme-reports.org/cgi-bin/mailman/listinfo/scheme-reports
