first implementation of doc-base
[I CC this mail to the maintainers of menu, dwww, and dhelp since I don't
know who of them is subscribed to debian-policy. Just tell me and we'll
drop the CCs.]
The basic idea
--------------
Some time ago there was a _big_ discussion about the preferred
documentation format in Debian, since the current text in the policy
manual contradicts itself (cf. bug #7890). A result from the discussion
was that people have very different opinions on that topic and we'll have
to implement a flexible solution so that everyone is pleased.
That's what the new "doc-base" package will be for: Every Debian package
that provides online documentation (other than manual pages) will register
these documents to doc-base via some "install-docs" mechanims (similar to
install-info, etc.) at installation time and de-register the manuals once
the package is removed.
doc-base will be provided with details about the installed manuals, file
names, documentation formats, etc. Based on configuration options that are
adjusted by the local system administrator, doc-base will eventually
convert between different documentation formats (where available, for
example, texinfo source to GNU info or PostScript), optionally compress or
remove HTML manuals which are also available in GNU info format, etc. etc.
(The details are unimportant for now.)
Since all manuals will be eventually registered to doc-base, it looks like
the best solution to use doc-base also as interface between the packages
providing documents and the different online menu systems (currently, dwww
and dhelp). With that, the maintainer does not have to care about
implementation details of dwww or dhelp, and it's up to the system
administrator which online menu system he/she prefers (even both can be
used at a time).
The current status
------------------
1. dhelp and dwww use quite different approaches. Since both approaches
have advantages and disadvantages I think dropping either tool would not
be optimal. As long as we have the manpower to maintain both tools, I'd
suggest to keep them both and have both supported by doc-base.
2. I've started to implement a first version of doc-base which implements
the menu-registry functionality. Currently, menu/dwww and dhelp methods
are supported and everything seems to work fine (expceptions, see below).
As soon as we've worked out the last problems here, I'll upload that
version for "unstable" and update my own documentation packages (policy,
devref) to support it.
3. For now, use of doc-base will be voluntary, as support for dhelp or
dwww is. However, it's likely that doc-base will become policy some day
(provided I get the necessary consensus, of course--this mail is to get
some first feedback about the idea). Note, that since doc-base is still in
a very early state, the registration procedure might be changed when
necessary.
How doc-base works currently
----------------------------
The current implementation is the following: Each document gets a
`document id' (DOCID) that has to be unique within the distribution. This
id will appear in several places where one has to identify a certain
document. (The package name cannot be used since a package may install
several documents.)
For each document, the packages will install a file
/usr/lib/doc-base/<docid>, referred to `doc-base control file' below. Here
is an example:
---cut-here---
Document: foo
Title: Debian Foo's Manual
Author: Wile E. Coyote
Abstract: This manual is about foos, bars, and Debian.
Second line of abstract.
.
The above line is empty, etc.
Section: debian
Format: debiandoc-sgml
Files: /usr/doc/foo/sgml/foo.sgml.gz
Format: HTML
Index: /usr/doc/foo/html-sgml/index.html
Files: /usr/doc/foo/html-sgml/*.html
---cut-here---
Note, that the syntax, just as the whole design of doc-base, is heavily
based on dpkg. This is important since every maintainer will have to work
with doc-base and thus, it should be simply to remember the basic ideas.
The first "paragraph" (terminated by an empty line) describes the
document, starting with the DOCID (Document:), title, etc. This
information is required to register the document to the online menu
systems (dhelp, dwww, etc.)
The next paragraph describe the different formats which are provided by
the package. This information will be needed when the format-conversion
feature is implemented. (Note, that these fields are likely to be changed
as soon as I start with the implementation.)
The interface to doc-base is currently called `install-docs' (I'm thinking
of a more general name as this utility is not only used for installing
documents). Packages will have
install-docs -i /usr/lib/doc-base/<docid>
in the postinst scripts and
install-docs -r <docid>
in the prerm scripts.
Similar to dpkg, install-docs has a `-s' option to tell the current
document status, for example:
$ install-docs -s foo
---document-information---
Document: foo
Abstract: This manual is about foos, bars, and Debian.
Author: Wile E. Coyote
Section: debian
Title: Debian Foo's Manual
---format-description---
Format: debiandoc-sgml
Files: /usr/doc/foo/sgml/foo.sgml.gz
---format-description---
Format: html
Files: /usr/doc/foo/html-sgml/*.html
Index: /usr/doc/foo/html-sgml/index.html
---status-information---
Control-File: ../foo-0.0/foo.desc
Registered-to-dhelp: 1
Registered-to-dwww: 1
$
And there is another option to list all files created by doc-base:
$ install-docs -L foo
/usr/doc/foo/html-sgml/.dhelp
/usr/lib/menu/doc-base-foo
$
(doc-base keeps track of which files have been created for which documents
to remove these files when the package is removed.)
Current problems
----------------
1. We have to get a consensus about which document information is required
for the online menus. Currently, dhelp and dwww require different fields
(e.g., dwww can handle a `longtitle' which is not supported by dhelp).
Simply using all fields required either for dhelp or dwww is not enough,
IMHO. Remember, that the solution has to be simple for the maintainers!
2. We've to define a policy about the preferred document directory (i.e.,
for possible values for the `Section:' field above). Currently, dhelp and
dwww use different menu structures. This is not acceptable.
3. dwww currently uses two different registration methods: via
/usr/doc/foo/.dwww-index files or via menu. The latter method is already
supported by lots of packages while the first is not supported widely.
Jim, what are the future plans for dwww? I think it would be good to drop
one method. (We should discuss whether using `menu' for this is a good
idea. Though, `menu' does an excellent job by now, it has a different
purpose--registering applications to menus, not documents.)
4. doc-base currently supports registering to dhelp and dwww (via menu
only). There is one problem, though:
When doc-base installs a menu/dwww entry for a manual, it installs the
file /usr/lib/menu/doc-base-<docid> and uses "?package(doc-base)" in the
file for menu. (doc-base does not know which package registered the
document. This should not be a problem since when the package is removed
later, doc-base will automatically remove that file.)
Obviously, this does not work with the /usr/lib/menu/default files, since
menu compares the filenames in menu/default with those in menu/ . For
example, there is a file `menu/default/dpkg', but once dpkg supports
doc-base, the documents will also be included in `menu/doc-base-<docids
for dpkg documents>', which will result in the documents appearing in the
menus twice.
Should the default entries be removed for packages which support doc-base,
or is there a better solution?
How to continue
---------------
As soon as the above problems have been resolved, I'll upload a first
release of doc-base to unstable and update my own packages to use it.
(There have been two bug reports against debian-policy and
developers-reference to support menu/dwww. I'll fix these bug reports with
that.)
Ideally, a few others would have a look at doc-base and support in their
packages too. However, the registration process is likely to change as new
features are implemented, so I can't guarantee that all changes will be
compatible. I guess we'll need some time until doc-base will be stable
enough to force it by policy, but I think this will happen some day.
I really appreciate _any_ comments about doc-base, this mail, etc. This
thing will only work if we have enough people supporting it. Thanks!
Chris
PS: Hope you didn't mind this long mail.
-- _,, 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: