Bug#106073: recommend to install <package> documentation into /usr/share/doc/<package>/

[Russ Allbery <rra@debian.org>]

I'm not sure where in the thread we lost this, but please copy the
relevant bug on Policy discussions so that we have an archived record of
the discussion without having to search out the appropriate time-based
portion of the debian-policy archive.  I also make extensive use of
debian-bug-get-bug-as-email in Emacs to reply to bug discussion, which
doesn't work if the messages don't go to the bug.

Ben Finney <ben+debian@benfinney.id.au> writes:
> Russ Allbery <rra@debian.org> writes:

>> I'm inclined to second this, although I wonder if should is too strong
>> at this point and we should instead allow for either method but
>> document that using the same directory as the "parent" package is
>> preferred. That would avoid the instantly buggy issue but still set up
>> a transition over time.

> Can you show me an example (perhaps elsewhere in Policy) that shows the
> less-strong wording you have in mind?

Something like:

        <p>
          It is recommended that supporting files and run-time support
          programs that do not need to be invoked manually by users, but
          are nevertheless required for the package to function, be placed
          (if they are binary) in a subdirectory of <file>/usr/lib</file>,
          preferably under <file>/usr/lib/</file><var>package-name</var>.
          If the program or file is architecture independent, the
          recommendation is for it to be placed in a subdirectory of
          <file>/usr/share</file> instead, preferably under
          <file>/usr/share/</file><var>package-name</var>.

Here for example the requirement (at the should level) is that the files
be installed in /usr/lib, and the preference is for them to be in a
directory named after the package.

We would say that the documentation should be installed into either
/usr/share/doc/<doc-package> or /usr/share/doc/<parent-package> (with some
better terms there, probably), with the latter preferred.

>> We'll need a Lintian tag, etc., to actually get everything moved over.

> Should that be a separate bug report?

In general, you don't need to file Lintian bugs for new Policy
requirements, since I always go through the new Policy requirements and
try to write new tests as part of releasing a new version of Lintian.

>> I also agree with Bill that it might be useful to say that one should
>> have a symlink or symlinks in the /usr/share/doc/package-doc directory
>> pointing to the docs in the other directory (or vice versa; it doesn't
>> really matter which direction the linking goes). That would also make
>> the transition easier.

> This might need more discussion; I didn't see a good consensus on that
> part. More bug reports, or am I getting overly picky?

I'd resolve that as part of this bug report.

I think that if the documentation package is new, or if the documentation
package has always put its files into /usr/share/doc/<parent-package>, the
symlinks are optional.  If the files are moved from the doc package's doc
directory to the parent package's doc directory, we probably want to
encourage symlinks a bit more strongly.

I'm not sure what to do about cases where the doc package is for a set of
other packages and there's no obvious parent package.  OpenAFS, for
example, doesn't have an obvious place to put its documentation other than
/usr/share/doc/openafs-doc, since there's no openafs package.  There's are
openafs-client, openafs-fileserver, and openafs-dbserver packages, but the
manuals installed by openafs-doc are unified manuals, not manuals divided
along lines similar to the packages.

I think we can handle this in the wording by just saying that installing
docs in the parent package's doc directory is only preferred if there's an
obvious parent package into which to install them.

>>> +	  The documentation must be installed as specified in
>>> +	  <ref id="docs-additional">.

>> I think that last "must" should be a "should".

> Why so? It's merely saying that another section of Policy must be
> followed. If that section includes less-strong language, the “must” here
> is exactly as restrictive or non-restrictive as that other section's
> wording.

That's one way of reading it, but the other way of reading it is as saying
that the "should" in the previous section becomes a "must" if this section
applies.  Better I think to avoid the ambiguity and not using that
phrasing.

-- 
Russ Allbery (rra@debian.org)               <http://www.eyrie.org/~eagle/>