Re: GNOME Policy, draft 0.0.0.1
On Mon, 2003-01-13 at 09:04, Ross Burton wrote:
> This is the latest draft.
Very nice, Ross!
> Currently this document is simply a list of "best practises" for
> packaging GNOME libraries and programs. As it evolves it should become
> more organised.
Hm, since we will hopefully have a best packaging practices document, I
would instead say something like:
"This document describes the policy requirements for the packaging of
GNOME programs."
That is the goal, right?
Now, most of my further comments have to do with the usage of the words
"must" and "should". If you haven't already, check out the Debian
Policy, section 1.1, for information about how these words should be
used in a policy document.
> Nautilus views should be packaged as "nautilus-[viewname]". As they
> are not executable by the user, they should be installed into
> /usr/lib/nautilus.
Path stuff like this might be good candidates for "must". If you look
at the Perl policy, it often uses "must" for things related to paths.
> The documentation of a library should be generated with a tool such as
> gtk-doc or doxygen at package build time
I'd rephrase this to: "If the package contains documentation for a
library which is generated using gtk-doc or doxygen, it should be
rebuilt during the Debian package build process."
That way it's clearer that it's not a bug in the Debian package if the
upstream package doesn't have API docs.
> , and either included in the
> -dev package if it is reasonably small, or in a separate -doc package.
> API docs should be installed in /usr/share/doc/foo-{doc|dev]/,
> normally in a folder named after the type of file (such as "html").
> All API documentation should include a doc-base and .dhelp file.
I don't think this should be a "should" either. I would just drop the
above sentence entirely. The core Debian policy should be the one
talking about requirements for doc-base and dhelp.
> If user documentation exists, and a .omf file is provided, the package
> should
must?
> Currently, Debian has no XML catalogue. This means that when
> Scrollkeeper is used to register user documentation, it will try and
> connect to the Internet and download a DTD. As a temporary measure,
Adding "you must" might make it clearer that this is very important.
> replace the URL with a absolute path. For the details of this, see
> bug #155129.
>
> An example script to do this would be:
>
> find -name '*.xml' -exec perl -i -pe
> 's,http://www.oasis-open.org/docbook/xml/([^/]+)/docbookx.dtd,/usr/share/sgml/docbook/dtd/xml/\1/docbookx.dtd,' {} \;
> find -name '*.omf' -exec perl -i -pe
> 's,http://scrollkeeper.sourceforge.net/dtds/scrollkeeper-omf-1.0/scrollkeeper-omf.dtd,/usr/share/xml/scrollkeeper/dtds/scrollkeeper-omf.dtd,' {} \;
>
> Run this one-liner before running 'make'.
I also personally prefer reversing the changes in the "clean" rule, so
as not to bloat the diff.
> When gconftool supports it, the prerm script should
must?
> also un-apply the
> schemas when the package is being purged. This is currently
> unimplemented in gconftool however.
>
> TODO: I plan to write a dh_gconfschema helper which will auto-generate
> the relevant postinst/prerm scripts.
>
> If the binaries accept the standard GTK+/GNOME options, in the manual
> pages refer to the GNOME options manual page . TODO: what was the
> status with this? Is it packaged anywhere?
I'm not aware of such a beast existing yet.
In general, this looks very cool! Let me know if you need help
docbookizing it.
Reply to: