On Tue, May 10, 2005, Matthias Kurz wrote:
> On Tue, May 10, 2005, Michael Schloh wrote:
>
> Yes. I thought, %docdir is just [working recursive]
>
I hope this is the way it works but it has to be verified.
> > So far, we have a few things which I hope is clear to everyone.
> > Please make corrections if any of the following is wrong:
> >
> > --includedocs (RPM feature): includes files tagged with '%doc'
> > --excludedocs (RPM feature): excludes files tagged with '%doc' (the
> > default)
> > %doc (RPM feature): describes a file as optional documentation
> > %docdir (RPM feature): describes a directory as containing documentation
> > with_doc (OpenPKG feature): inconsistent option which should be removed
> > $ openpkg rpm -qd <pkg> (qd is RPM feature): list documentation
> >
Close to how I understand it. But there is an important thing missing
here. The RPM feature controls the installation of documentation files
from the binary RPM into the filesystem. The OpenPKG feature with_docs
controls the inclusion of documentation files from the buildroot
into the binary RPM. The RPM feature is simply a "copy" or "skip"
decision. However, the OpenPKG feature sometimes means that additional
dependencies exist at build time. Consider a package that includes docs
in a single "original" format. During build the docs might be converted
into additional formats using - BANG! - additional tools which are
not part of the package. People will hate us if we insist having them
install text based web browsers just to dump a HTML page into TXT,
install tex just to render a beautiful postscript file and install some
x-to-PDF converter - just to finally skip the docs at install time
later. The need to create the docs during build is the actual problem
which prevented us to support them.
> > We might consider the questions:
> >
> > 1. How do we want to consistently use the tags '%doc' and '%docdir'?
> >
We can only decide when we have understood how $docdir really works.
> > 2. Do we package absolutely all vendor docs even when they overlap?
> > - When a user's guide is available in all .html, .ps, and .pdf,
> > then which do we prefer to package?
> >
Once we start I recommend putting in everything we can grab. Sometimes
even 3rd party docs like HOWTOs etc.
> > 3. Where do the docs go?
> > - %{l_prefix}/share/<package>/<here>?
> > - %{l_prefix}/share/<package>/doc/<here>?
> >
Or maybe a new "toplevel" dir using %{l_prefix}/doc/<package>/<here>
> > ...and of course the organisational questions:
> >
> > Where do we document and enforce this new standard?
> > - Documented in the long outdated handbook?
> > - Documented in a new 'package standards' document?
> > - Not documented anywhere, and only enforced?
> > - Enforced in the speclint script of openpkg-tools?
> >
The speclint enforcement has been prooven to work very well, also it is
incomplete because of a missing human readable "standards" document.
______________________________________________________________________
The OpenPKG Project www.openpkg.org
Developer Communication List openpkg-dev@openpkg.org
