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
Scheme-reports@scheme-reports.org
http://lists.scheme-reports.org/cgi-bin/mailman/listinfo/scheme-reports