Re: Documentation Policy
> *) The default format should be HTML, but everything necessary to
> view the documents should be provided as part of the base system.
> This includes a default HTML viewer (lynx), which users can override
> by means of the update-alternatives method. It would also include
> a default HTML server, which should also be installed as part of the
> base system and changeable by the update-alternatives method (or
> maybe conflicting with others?).
> Suggestions for HTML server: boa, small and fast
> cern, if you want caching
Rather than make any of lynx, dwww, and boa part of the base system,
I'd mark them "important". The base system has the sole purpose of
getting you bootstrapped to the point where you can load other stuff
from packages. It should remain small to facilitate that. In the case
of a CD or network install, you can do something in the installation
system to install the important packages right away (along with the
editor the user has selected). In the case of a floppy install, the user
would probably prefer that we not add another three floppies.
>
> *) The package dwww should be marked important. It should provide
> on-the-fly converters (as CGI programs) for as many formats as
> using dselect. possible. No converter should depend on a non-required package.
I think this should be handled by making dwww depend on the packages
that provide its converters.
> *) Documents should be provided in the least processed (closest to
> the original source) format for which an on-the-fly converter exists.
> Given the choice of several formats, the most versatile one (which
> can more easily be converted to other formats) should be chosen.
Note that on-the-fly conversion is sometimes awfuly slow. Try it on a 386.
I suppose you can cache pre-converted pages.
> *) Until there is a better option available, dpkg should include a script
> to automate the process of unpacking the /usr/doc/package part of a
> package without installing it. This is to allow users to install
> documentation of packages which conflict with an installed one.
> Users might need to manually remove the directory /usr/doc/package
> when they no longer need it.
> Scripts to register and unregister documents with dwww should be
> provided in order to properly handle this case
Is anyone interested in writing this?
> *) The project should stick to the policy and not include alternative
> formats or viewers by default. If we are convinced that HTML is the
> format, then we must show it.
>
> *) Man pages should be installed in raw format and converted to HTML
> on-the-fly. Since a man->html converter which does not depend on groff
> is possible, neither "groff" nor "man" should be installed by
> default.
This is fine _only_ if you bring provide a "man" command that invokes lynx
on the appropriate page. This is simple to do and would forestall a ton
of complaints.
Bruce
--
Bruce Perens K6BP bruce@pixar.com 510-215-3502
Finger bruce@master.debian.org for PGP public key.
PGP fingerprint = 88 6A 15 D0 65 D4 A3 A6 1F 89 6A 76 95 24 87 B3
--
TO UNSUBSCRIBE FROM THIS MAILING LIST: e-mail the word "unsubscribe" to
debian-devel-request@lists.debian.org .
Trouble? e-mail to templin@bucknell.edu .
Reply to: