Re: document registration policy needing to be written
On 10 Apr 1998, Adam P. Harris wrote:
> 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.
Thanks for the excellent summary!! This is exactly what we need now. It
would be great if you could update the summary as the discussion evolves.
> 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.
I agree 110% with the above.
> 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.
[snip]
I disagree. I still think that registering documents to install-docs does
make sense, even if dwww and dhelp share a common format:
* As soon as we start with the document conversion stuff (you can't
exclude this aspect of doc-base completely in this part of the
discussion), packages would have to register their documents to
doc-base _and_ to dhelp/dwww. However, the registered information is
quite similar.
* Even if you say dhelp/dwww will handle only HTML while doc-base will
handle all other formats, doc-base is required: there are currently
3 different HTML formats that have been requested by the users during
the last doc policy discussion: plain HTML, HTML.gz, and HTML.gz with
fixed hyperlinks. Converting between these formats would be trivial
for doc-base, but you'd have to duplicate this conversion code if you
move this functionality to dhelp/dwww.
* As you stated above, there might be other online menu systems in the
future which might use a different registration scheme.
Of course, if you think install-docs would get too large if it does the
registry and format conversion, you could split the script into a
package-registry frontend and a conversion backend.
Are there any specific reasons you don't want to have the registry code in
doc-base?
> 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.
[snip]
The `Required' part is less important since packages can easily check for
existance of install-docs if they want to register their documents. We
could even improve this situation if packages don't have to call
install-docs for each installed document: if they could just place a file
in /usr/share/doc-base/registry (or something similar) and run
`update-docs,' doc-base could search this directory for new entries. Same
goes for the prerm procedure. With that, doc-base wouldn't fail if it is
installed _after_ a doc package is installed.
> * 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
[snip]
1. Marco indicated in a private mail discussion with myself yesterday,
that dhelp does have the functionality to search for .dhelp files in an
arbitrary directory. With that, it might be possible for doc-base to put
all .dhelp files in /var/lib/doc-base/dhelp/<doc-id> and run dhelp's
registry program over these files. (Having to touch /usr/doc/<package> is
less optimal since if doc-base has a bug, people might end up with an
installation where a lot of `unknown' files are lying around where neither
doc-base nor dpkg knows about them.)
2. When talking about filesystem structure, I'd suggest we check out the
new paths that will be required with FHS. (Debian will switch to FHS
soon.) Moving `registry' directories like /var/lib/dpkg is nearly
impossible (we'll not move this directory, for example) but this would be
required if we aimed 100% compliance with FHS (we'll not do). Therefore,
I'd suggest we use FHS paths right from the start.
3. We'd also have to watch out which files we put below /usr and which
below /var. As a thumb rule, everything which is modified at installation
time _only_, can go into /usr. At run-time dynamically generated and
modified files must go into /var. Putting any dynamically generated files
into /var is also a good option since it would simplify the `purge'
process of doc-base. (That's important, see also #1 above.)
Note, that information about converted doc formats would have to go
into a /var directory, since the user might request a converted format
_after_ installation time.
> * 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
Oh, do you want to change doc-base's registry file format into a SGML
format? I wouldn't like that for the following reasons:
* The format has to be supported by the package maintainers (only), so
we should try to make life most easiest for them. The `dpkg style'
control file syntax doc-base uses until know should be known to any
developer already.
* AFAICS, we don't need SGML `functionality' in the registry files.
* Parsing SGML files is a lot more work and would require more CPU time
at installation time, than to parse the simple dpkg control files.
* Just using a SGML-like file syntax but by picky about where line breaks
and spaces may appear (that's like dhelp behaves now) is even worse,
since the SGML-like syntax makes the maintainers think doc-base doesn't
care about spaces--a fail. (This happened to me with dhelp.)
> * add fields to register document type (ASCII, HTML, etc.) and
> language
Ok.
> * 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
Yes, that's an important point. Note, that people suggested before that we
use the same menu structure which is also used for the `application
menus'. However, I don't think this structure works well with
documentation.
> * 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.
Right. (Oh, this is what I also said above. I fully agree!)
Thanks,
Chris
-- Christian Schwarz
schwarz@monet.m.isar.de, schwarz@schwarz-online.com,
Debian has a logo! schwarz@debian.org, schwarz@mathematik.tu-muenchen.de
Check out the logo PGP-fp: 8F 61 EB 6D CF 23 CA D7 34 05 14 5C C8 DC 22 BA
pages at http://fatman.mathematik.tu-muenchen.de/~schwarz/debian-logo/
--
To UNSUBSCRIBE, email to debian-doc-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Reply to: