Re: Next approach: Documentation Policy
Hi, a few (hopefully) final comments:
----------------------------------------------------------------------------
>
> > 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.
>
> I don't get your point. Do you want us to force all developers to write
> docs, if these are not available? I will definitely _not_ do this. We
>From the users' point of view, this will be very helpful. From the developers'
one, force is too strong of a word, let's say encourage or suggest.
In practice, this only means that a bug can be filed for non-compliant
packages.
----------------------------------------------------------------------------
> > 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!
>
> Sure, but what's the problem with that? We'll just have all maintainers
> add a line like
> update-docs <insert-your-package-name-here>
> (or something very similar) to the postinst and preinst script.
Ok. Now we are forcing all developers to change the postinst scripts... :-)
----------------------------------------------------------------------------
> > 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.
>
Think from the user point of view. It would be nice to have HTML docs for
any package. It's the same reasoning that now applies to man pages not
provided upstream.
Besides, binary docs are very often useless if GS or xdvi are not installed.
----------------------------------------------------------------------------
>
> > 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.)
>
> Are you kidding? "Man" will surely not be dropped in the near future!
>
>
No. I'm not kidding. I said "man" (the program), not "manpages".
Manpages can be viewed through man2html, which is _faster_ than groff.
Besides, I've been told that the next release of elvis will include
a man page formatter which will not depend on groff. Groff should be
optional. It is not necesary, and it's big and slow.
When the user types "man whatever" he could be presented with the HTML
converted man page directly (HTML is the preferred online format, isn't it?)
----------------------------------------------------------------------------
> After all, I'm very happy that our proposals are getter nearer to each
I'm happy too!!
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: