Hi.
Here it is. I welcome comments to improve the language, but send them
to me personally, not to the list.
Technical comments to the list, naturally.
Samples will be created after the basics are accepted.
(mk)
Proposal: OpenPKG documentation structure (First Draft)
To ease the process of packaging for the OpenPKG developers and to help
the users to find informations quickly, there should be a clear documented
documentation structure.
1. Classification of documentation
----------------------------------
We will make a distinction between mandatory and auxilliary documentation.
Mandatory documentation is always installed while the installation of
auxilliary documentation can be controlled using the package manager
application.
For RPM there are the options --includedocs and --excludedocs and the
macro %_excludedocs, that defines the default behaviour. The global
setting for %_excludedocs is '1' which means, that auxilliary docs are
only installed, when the option --includedocs is given to rpm. [1] The
user can define a different default value in $HOME/.rpmmacros.
2. Mandatory documentation
--------------------------
In short, every documentation that an administrator of a "headless
peripheral host" needs for his daily work is considered "mandatory". This
are especially manual pages (%prefix/man) and GNU info files (%prefix/info).
When the packager decides that there should be more mandatory documentation
it should be placed under %prefix/share/<package>/docs.
3. Auxilliary documentation
---------------------------
Every "in depth" documentation (e.g. user/administrator guide) and every
documentation that is not needed for the daily work (e.g. WHATSNEW) is
considered "auxilliary".
3.1. Organization of auxilliary documentation
---------------------------------------------
There will be a new toplevel directory %prefix/doc. Every file below this
directory is considered auxilliary documentation. The placement of the file
alone defines its type. It is not necessary to use %doc or %docdir.
Every single file of the auxilliary documentation has to be reachable
from _one_ entry point that lies under %prefix/share/openpkg/docs.
3.1.1 Structure of the per package directory under %prefix/doc
--------------------------------------------------------------
For _every_ package there exists a directory %prefix/doc/<package>.
Inside this directory there exists a file "index.html" that describes
the package and every piece of documentation. [2]
To ease packaging, there will be a small utility that creates a skeleton
index.html. It uses the package's .spec file (%Name, %Summary, %URL,
%Vendor, %description) and puts in a filelist of %prefix/doc/<package>
as well as some placeholders that can be expanded using simple
search&replace. Ideally the packager will not need to edit the
index.html for simple packages.
4. "External" documentation
---------------------------
Sometimes the packager can decide, that additional documentation (either
mandatory or auxilliary) should be supplied with a package (but see 7.
Priorities). Such documentation can be generated or collected and placed
for download on the OpenPKG servers. There should be a version management.
5. Samples
----------
The new structure will be demonstrated on 2 packages: 'ant' and 'ratbox'
'ant' serves as a "standard" package, while 'ratbox' is used to give hints
how to handle external documentation.
6. Implementation
-----------------
Changing to the new documentation structure should be done in serveral
passes. In a first pass only (and only) the documentation that can be
installed "as is" should be classified and installed. During this first
pass information should be collected about what additional documentation
exists that would need additional actions and what those actions are.
Then it should carefully be decided what further actions are acceptable.
7. Priorities
-------------
Documentation is an important thing, but no packager should ever forget,
that the main focus of the OpenPKG project lies on the _binaries_.
[1] How can this be integrated in openpkg-tools ? Should there be new
options that result in --includedocs and --excludedocs during
package installation ?
[2] Ideally also stuff under %prefix/share/<package>/docs
--
Matthias Kurz; Fuldastr. 3; D-28199 Bremen; VOICE +49 421 53 600 47
>> Im prämotorischen Cortex kann jeder ein Held sein. (bdw) <<
______________________________________________________________________
The OpenPKG Project www.openpkg.org
Developer Communication List openpkg-dev@openpkg.org
