document registration policy needing to be written
I've been working on doc-base lately, having taken over maintenance
from Christian. There are a lot of technical discussions about what
we want the debian documentation to be for slink. Right now, however,
rather than bring up those issues, I'd like to give the 20 thousand
foot up perspective to what we're doing. My principle objective is to
stake out agreed-upon terrian for doc-base, and determine what we're
doing with respect to system-wide document registration. I'm going to
ignore the automatic conversion and language support issues for this
message.
Documents must "register" themselves to Debian. A way should be found
to do this which minimizes the requirements on individual package
maintainers.
Rationale: Unfortunately, documentation that comes with packages,
within themselves, do not provide enough information to allow a
structured display of the documents. There are two competing
systems for unified display of Debian documentation: dhelp and dwww.
Both have strengths. Additional systems should be possible in the
future. Package maintainers should have a simple, single way to
register files for various display systems.
Current situation: 'dwww' uses 'menu' files, installing with
'update-menus', as well as an options .dwww-index file; 'dhelp' uses
'.dhelp' files in individual /usr/doc/<pkg> dirs, in conjunction
with 'dhelp_parse'.
Package-level support for all three systems is quite spotty. I have
754 packages installed. Looking for only .html files in /usr/doc[1]
shows 85 packages. Of that, I have 14 .dhelp files (16%) installed.
I show 7 .dwww-index files (8%), and 43 packages using dwww
conditional menu files (50%).
'doc-base' provides a single interface for package maintainer to use
to register files with both systems. This is doc-base/hamm's only
real function at this point.
Immediate prospects: it looks like Jim Pick, the dwww maintainer, is
going to abandon his scheme and alter his system to use .dhelp
files. In that case, doc-base's install-docs system will be
useless, in fact, creating a new document control file format
without any additional purpose.
The most recent version of dhelp includes a script to create dwww
files based on .dhelp files.
Options for slink:
* decide on whether we want to couple or decouple the document
registration side from the document presentation side. I think
this is a good idea. A stripped down document registration system
could be made 'Required' or at least reasonably standard so that
packages can register packages early on.
* standarize a document control file format, merging dhelp and
doc-base fields. TODO if so:
* consider file naming and placment. 'doc-base' uses
/usr/share/doc-base/<pkg>; dhelp uses /usr/doc/<package>/.dhelp.
In a way it's better to have files in /usr/share/doc-base or
some such, since then there's a single file location for
document control files
* file format should be standardized, we should whip up a DTD and
make it true SGML; this will assist in format validation and
standardize file parsing
* add fields to register document type (ASCII, HTML, etc.) and
language
* adopt the menu hierarchy as a standard documentation hierarchy (de
facto; make it official)
TODO if so:
* beef up a little, cf my Bug#20936
* consider how this hierarchy might integrate or not with language
specifiers. dhelp uses
* Could document registration could be 'execution free', i.e., all
we require is a small file in /usr/doc/<pkg>, and no commands from
maintainer scripts (not sure if this is possible)? Probably not.
Alternatively, given that document registration consists of
dropping a file in a specified directory in conjunction with
kicking up some hypothetic 'update-debdoc'; upon installation of
the package, it could scan for registration files.
.....A. P. Harris...apharris@onShore.com...<URL:http://www.onShore.com/>
--
To UNSUBSCRIBE, email to debian-doc-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Reply to: