dpkg documentation structure
I've decided that the situation with dpkg/dselect/Guidelines
documentation being inadequate has gone on long enough; when we have
new beta-testers and users we'll want to educate them rapidly, and
documents are the way to do this.
I'm therefore shifting writing a proper set of manuals (for dpkg,
dselect and the project's policies) up my priority queue, ahead of
further improvements to dpkg and the novice mode interface to
dselect. If someone wants to write the novice mode interface to
dselect in the meantime don't let me stop you :-).
Having been thinking about the dpkg manual problem a bit lately, I've
come up with a proposed structure for the documentation I'll be
writing, which you'll find below.
I propose to write as much of this as is practical in linuxdoc-sgml,
so that I can produce plain text, manpage, HTML and formatted output
as required. I'll need to do a bit of hacking at linuxdoc-sgml, I
think.
Comments on the manuals' structure are welcome, as are suggestions for
things that ought to be included that I haven't mentioned and aren't
currently documented in the Guidelines or associated doc files in the
dpkg source.
However, I don't want comments of the form `it is more important that
manual Y be written instead'. This is not helpful to me, as I want to
be writing about things I know about.
* dpkg system administrator's manual
(items listed here in no particular order):
Describes package states, dpkg command line arguments and their
effects on the system and the way it installs packages, different
types of files found in packages, sysvinit rc?.d link handling by
packages, /usr/info/dir handling, how to use dselect.
* dpkg programmer's manual (items listed here in no particular order):
Describes the technical interface between a package and dpkg. Control
file fields and their syntax and semantics. How to use update-rc.d,
diversions, update-alternatives, install-info in a package. How to
safely put shared libraries in a package. dpkg actions in order when
installing and deinstalling; maintainer script arguments and
requirements. Details of dpkg's handling of individual files.
Semantics of virtual packages. Sections on when to use which feature
(eg Replaces vs. Replaces/Conflicts vs. update-alternatives
vs. diversions) Cross-references to the policy document (see below)
where appropriate. Description of the interface between dselect and
its access methods. Hints on where to start with a new package (ie,
the hello package).
* Debian policy (in three sections):
(a) General requirements: understanding the copyright of your package;
upload procedure; package classification; bug tracking.
(b) Source package requirements: debian.rules targets and their
required behaviour.
(c) Binary package requirements: permissions of files, shared library
package naming conventions, /usr/doc/copyright, virtual package name
selection procedure, uid/gid allocation policy/procedure (including
reference to adduser documentation).
Ian.
Reply to: