[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: Directories named after packages


On Thu, Jan 06, 2011 at 02:54:38PM +0000, Ian Jackson wrote:
> Many of the bits of the policy manual, and informal practice, suggest
> naming directories after your package.
> In general, the principle should be that where to look in the
> filesystem for something should not depend on how the packages have
> been organised.
> For example, there has been a recent trend for FOO's documentation
> package FOO-doc to contain /usr/share/doc/FOO-doc/html/index.html (or
> whatever).  I think this is daft.  It should be in
> /usr/share/doc/FOO/html/index.html.  That way you can find the
> documentation for FOO in the filesystem without knowing whether the
> FOO package happens to have been split into FOO and FOO-doc, or for
> that matter libFOO8.9-dev, FOO-bin, etc. etc. etc.

As for /usr/share/doc/* area, there are a few types of stems chosen.

1. package name: alsa-base, aptitude, aptitude-doc-en, ... 
   (lower case, most common)
2. Category name: FAQ, HOWTO, HTML, RFC
   (Always upper case)
3. Historic/Upstream choice (?): /usr/share/doc/texmf
   (Several TeX packages uses this.)

I agree that historical best practice for FOO-doc was to put
documentation in /usr/share/doc/FOO or /usr/share/doc/FOO-common (when
there is FOO1 and FOO2 variants but one each of FOO-doc and FOO-common

One of the early days of debian-doc before I joined created doc-base for
package so we can have one single data base to look.  Unfortunately, I
hear some packages do not use it these days but it is very good shape in
general.  /usr/share/doc/HTML is populated with data taken from doc-base
as I understand.  But it is much nice to have documents located by their
package name stem.

In any case, this is about *best practice* and something to put in
developers reference, I think.

If /usr/share/doc/FOO-doc has html, it will be at least nice to have
symlink from /usr/share/doc/FOO.

If we go for this common practice, we may need to ask FAQ, HOWTO, RFC,
texmf to be changed/moved to regular places.

Reply to: