On Mon, Sep 26, 2011 at 1:46 AM, Vincent Manis <vmanis@telus.net> wrote:
>
> I would suggest the following conventions for package documentation.
>
> {snip}
>
>  * All other documentation appears in a doc directory, with the entry point being the file index.html {snip}

On the subject of package documentation in general, my guess is that
this would be the simplest most straightforward way to have a package
contributor include documentation for a given package. It is:

  * simple for the snowfort to make available (just serving static html),
  * simple for the upload tools to deal with (extract files and copy
them to `/<snowball-name>/doc` dir on server),
  * simple for the developer to provide (no new technology to learn),
  * should be easy if migrating docs originating from elsewhere, and
  * the developer gets to use whatever tools they like to generate the
html (Scribble, LaTeX, Texinfo, Pandoc, etc.), so no time wasted
debating doc formats.

>  * 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.

Makes sense.

> 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, {...snip...} I'd prefer dependency management to be copied from Debian than from CPAN.

( Sorry for veering off-topic here: )

The situation with Perl is interesting because Perl has become a
rather integral part of the OS itself. In my experience, if you use
only the Debian tools to manage packages for the system perl, and use
only the CPAN tools to manage the packages for the Perl you
built/installed yourself, then everything works quite well.

---John

_______________________________________________
Scheme-reports mailing list
Scheme-reports@scheme-reports.org
http://lists.scheme-reports.org/cgi-bin/mailman/listinfo/scheme-reports