Re: new approach: Documentation Policy
On Fri, 4 Jul 1997, Christian Meder wrote:
> 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.
We have chosen to do texi->info compilation on-demand since the "makeinfo"
compiler is quite fast. Unfortunately, the sgml2* compilers are too slow
and require too many other packages to work.
> > 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.
This is exactly what I planned to do. The 500k limit should be ok for now.
If we have more architectures "officially supported" (in 2.0) and if deity
simplies the management of even more packages, I'd say we lower this
bound.
I don't want to produce new work for the maintainers where not necessary.
This new policy will not make much extra work, but surely creating multi
binary packages will be more work then.
> > 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.
Since nearly all packages will have to support doc-base sooner or later,
we should place it in the "base" system, if there is enough space. This
would prevent us from all packages having to depend on "doc-base". (I
expect doc-base being less than 50 kbytes.)
Does someone know what's happening when a new package is installed in
section "base"? Are these packages selected in "dselect" automatically
when upgrading? And are they ensured to be configured _before_ any other
package (outside of "base") just if every other packages depends on it?
If not, I think we'd have to use dependencies! :-(
> 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) ?
Doc-base will provide the infrastructure for the other packages. When it
is installed, there will be a few questions about which documentation
formats are preferred, etc. This info will be stored in /etc/doc.conf and
can be edited by the sysadmin at any time with an editor or by called
"docbaseconfig" again. (The names will be changed, perhaps.)
Any package providing docs will have to add a call to some doc-base
registry program in the postinst script, where the all docs are
"registered", that is, you specify the title of the document, the markup
format (HTML, info, etc.), a short description (abstract), etc.
The doc-base program that's called will then choose what to do with the
docs according to the settings in /etc/doc.conf. Thus, the user is only
asked _once_, when installing doc-base, which documentation formats he/she
prefers. Everything else is done automagically. (There will be another
utility, to convert already installed docs if /etc/doc.conf is changed, to
the extent where this is possible. If some files are removed, you can't
undo this without reinstalling the package.)
Thanks,
Chris
-- Christian Schwarz
schwarz@monet.m.isar.de, schwarz@schwarz-online.com
schwarz@debian.org, schwarz@mathematik.tu-muenchen.de
PGP-fp: 8F 61 EB 6D CF 23 CA D7 34 05 14 5C C8 DC 22 BA
CS Software goes online! Visit our new home page at
http://www.schwarz-online.com
--
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: