dhelp and doc-base (was Re: [Fwd: dhelp support?])
On Wed, 7 Jan 1998, Santiago Vila wrote:
[snip]
> Marco Budde has asked me to add dhelp support in debmake (he even sent me
> patches), but there is a doc-base package planned for Debian 2.1. Since it
> seems that doc-base and dhelp will have very similar goals, I don't think
> it is a good idea to support dhelp (through debmake or not) at this
> moment, because we will easily end up having two incompatible document
> systems.
>
> This does not mean I don't like the dhelp idea (well, in fact I don't like
> invisible files being in /usr/doc :-), but not for hamm.
>
> Marco, I would suggest you to collaborate in the writing of doc-base.
> Perhaps a modified dhelp could be an important part of it.
(Santiago, can you read my private mails? :-)
Basically, I agree to your consideration. I don't have any problems with
packages supporting dhelp, but since doc-base will hopefully be available
some day all these packages will have to be changed.
I've already sent Marco a proposal of how doc-base would work this day,
but as this discussion may be of public intrest, I'll do it again:
Recall, that the basic idea of doc-base is to let the sysadmin choose
which documentation format is preferred. (Some people want HTML, others
info, etc.) This will be implemented by having all packages registering
their documentation files to doc-base in the postinst script and having
them removed in the prerm script. (That's similar to how install-info,
etc. work.)
Depending on how doc-base is configured, it will convert texinfo files
into PostScript, generate info files from texinfo source, etc.
Here is a concrete example how it could look like: The Debian manual
`Foo's and Bars' (to be written) is included in the "foo" package. The
manual is written in debiandoc-sgml, so HTML, Text, and postscript can be
generated.
According to the new doc-policy (to be definedd--this examples represents
the consensus of the last discussion), the package includes the SGML
source code and a pre-compiled HTML code (since most people want HTML and
SGML->HTML conversion is too slow on the average system).
The package will install the following files (besides others):
/usr/doc/foo/sgml/foo.sgml.gz
/usr/doc/foo/html-sgml/{index.html,ch1.html,...}
/var/lib/doc-base/info/foo
The last file looks like this:
Document: foo
Title: Foo's and Bars
Author: Wily E. Coyote
Abstract: something
next line
.
next line after an empty line
Section: eins/zwei
Format: SGML
DTD: debiandoc
Index: /usr/doc/foo/sgml/foo.sgml.gz
Files: /usr/doc/foo/sgml/*
Format: SGML-HTML
Index: /usr/doc/foo/html-sgml/index.html
Files: /usr/doc/foo/html-sgml/*.html
This file specifies the details about this piece of documentation to
doc-base.
Every piece of documentation gets a DOCUMENT-ID (first line, "foo") which
is unique within the distribution. After that, general info like title,
author, etc. is given. Then, there are one or more paragraphs describing
the different formats included in the package.
>From this info, doc-base will know that it's a debiandoc-sgml manual and
that text and postscript can be generated. If the sysadmin decided that
HTML is necessary for him/her, doc-base will remove the html files
automatically, since they are called "SGML-HTML", which means they have
been generated from a SGML source and thus, they could be re-generated at
any time. (doc-base would not remove plain HTML files. But there will
probably another option allowing this, too.)
Note, that the above syntax is the same that's also used in the dpkg
package formats. This has the advantage, that the maintainers don't need
to learn a new syntax. In addition, it's very easy to parse within
scripts.
With the new doc-policy, _every_ online manual (other than a manual page)
will have to be registered to doc-base. With that, all different menu
programs (dhelp, dwww, etc.) could very easily supported by doc-base.
There is no need to add this support to all the individual packages. In
addition, if dhelp's or dwww's syntax should change or if there should be
a third menu system, only doc-base would have to be adjusted.
Though the complete implementation of doc-base would be a bit work I guess
(I'm still looking for volunteers to help me, BTW) I think it would be
quite easy to get something running. If we could get a consensus of how
the input file's syntax should be, I could start with a first version of
doc-base which does not convert formats yet, but which registers all
manuals to the online menu systems.
Comments?
Thanks,
Chris
-- _,, Christian Schwarz
/ o \__ 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
\ / http://fatman.mathematik.tu-muenchen.de/~schwarz/
-.-.,---,-,-..---,-,-.,----.-.-
"DIE ENTE BLEIBT DRAUSSEN!"
Reply to: