Re: new approach: Documentation Policy
Hi,
after my apparently rather useless summary now on to some constructive
comments.
On Jul 3, Christian Schwarz wrote
> In case of converted HTML documentation, the files with the original mark
> up format should not be included, unless they are considered as "example
> documents" for that mark up language. (.texi files are an exception to
> this rule, see below.)
doesn't fit sgml this bill too? It's a generic markup language and can
be converted into html, info, etc. on demand.
>
> All documentation related files will be kept in the "main binary package"
> if they do not exceed 500 kbytes installed size together. (Of course,
> documentation-only packages are not covered by this rule.)
For now the 500k limit seems ok but after testing the new policy and with the
availability of more ports we should probably lower this limit to keep
the mirror admins happy.
>
> Every package that includes HTML documentation has to support the
> "doc-base" package (which will be created soon). This package will have
> the following functionality:
>
> - opt. ask the user at installation time if he/she wants to compress
> all HTML docs. (One can do this, if one has a web browser that can read
> ..html.gz files or a web server that can decompress the files on-the-fly.)
> Note, that the contents of the .html files (i.e. links) will _not_ be
> touched in either case. (The newly created ".html.gz" files will be
> removed in the prerm script, automatically.)
>
> - opt. remove all GNU info-converted HTML docs
> /usr/doc/*/html-info/*, if the user doesn't want to have these
>
> - opt. compile "*.texi" files into GNU info files
>
> - opt. compile "*.texi" files into PostScript format
>
> - the options above will be asked in the postinst script, unless
> they are predefined in some /etc/doc.conf configuration file
According to this setup it's fairly important that doc-base is
installed resonably early in the whole installation. After
installation it will scan all already installed packages and process
them depending on the user preferences.
What about packages which are installed after the doc-base package ?
Will they look up the user preferences in /etc/doc.conf and then
compile *.texi, remove html-info and so on (falling back on defaults
if /etc/doc.conf doesn't exist) ?
> Notes:
>
> 1. This approach does not depend in any way on special "deity
> features". It can fully be implemented with the current versions of
> dpkg and dselect without any problems. (Of course, this does not make
> "deity" obsolete :-)
That's good (we shouldn't put pressure on the deity people ;-)
>
> 2. The statement, that PostScript files should be created and uploaded
> to the ftp server, has been dropped, since this would have been too much
> work for the developers and everyone can create PostScript files on
> demand.
>
> 3. There is no need for a unification of the paper format (A4 or
> letter) since all PostScript manuals are created on-demand only, where
> the sysadmin can specify which formats he/she wants to have.
>
>
> Comments?
Otherwise I like the proposal.
Greetings,
Christian
--
Christian Meder, email: christian.meder@utoronto.ca
What's the railroad to me ?
I never go to see
Where it ends.
It fills a few hollows,
And makes banks for the swallows,
It sets the sand a-blowing,
And the blackberries a-growing.
(Henry David Thoreau)
--
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: