Re: Next approach: Documentation Policy
>
> > Did you read my alternative proposal? I think it issues important points
[...]
>
> I just read it again. You mention a few additional aspects (dpkg support
> to unpack doc only, for example) which we should consider _after_ the main
> points have been decided.
Oh! That was my old proposal. Maybe you missed the latest version I made then.
I include it below. I made it as short as I could, so as to not bore you too
much.
The main differences between your point of view and mine are:
1) You don't want to include source formats while I want to include them.
One more point for including source formats:
-) Local admins may want to modify docs to adjust to local layout
BEFORE printing the docs. That's impossible within your proposal,
unless they download the full source code (which may be expensive!)
2) You want uncompressed sources and no webserver by default, while I want
the opposite.
This has already been discussed at length.
3) You want HTML and info. I want HTML and texinfo.
Your reasons:
-) HTML because it is the default method.
-) Info for everyone because some people like it.
-) For printing, download our pre-compiled PS files.
My reasons:
-) HTML because it is the default method.
-) Texinfo to print (maybe locally modified) copies.
-) Info as an option for people who want it.
4) You don't make distinction between binary and markup formats. I do.
Binary formats are untouchable, impossible to index, almost impossible to
cut and paste into another document and much bigger than markup formats
with the same info. Use of binary formats as original source should be
discouraged and they should be kept separately.
On the other hand, markup formats are easy to index, easy to convert
locally to PS, easy to cut and paste, easy to modify. There is no real need
for us to pre-convert them to PS instead of just providing them.
5) There is no safeguard on your proposal that every program contain _some_
documentation, even if it is just instructions of how to get the rest, what
the user needs to view it (ghostscript and friends) and a summary of its
contents. That could be enough to decide whether or not the rest of the docs
are needed.
6) Your idea of a repository of documents in PS format is good, but I see
it as an added value option, not as the main option.
7) Your idea of the doc-base package is good, but here are some remarks:
-) The policy the user chooses has to be enforced every time a package
is installed or de-installed and not only when the doc-base is
installed. That's trickier, but important!
-) Makeinfo is very fast, even on slow machines. I think there is no
need to provide pre-compiled info files just to have them deleted
later. I think you are putting the burden on the wrong side.
---------------------------------------------------------------------------
My proposals on documentation:
1) The preferred format for online documents is compressed HTML.
The default installation supplies a default web server and a default web
browser. The user can override that, of course.
2) Documents for which on-the-fly conversion is available and fast should be
included in original format. The list of formats which are OK will change as
on-the-fly converters improve. Currently it will include plaintext and man
at the least. (man2html is very fast even in an old system.)
3) Other documents are classified in two groups:
3.a) Human-readable files. They typically are in a markup format.
Both HTML and original format will be supplied.
3.b) Machine-readable files. Commonly PS or DVI.
If no source is available from the upstream author, the files should
be packaged separately. However, instructions on how to get it and
a summary of its content should be included with the program.
4) Man and info should be optional and not installed by default.
(makeinfo is very fast even on an old system. Compiling info files when
installing info is not a problem.)
Thanks,
Fernando.
--
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: