Bug#106073: recommend to install <package> documentation into /usr/share/doc/<package>/
Thank you for writing this up!
Ben Finney <ben+debian@benfinney.id.au> writes:
> There seems to be consensus on doing this, so I've made a patch
> (attached to this message) which implements that recommendation.
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.
We'll need a Lintian tag, etc., to actually get everything moved over.
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.
> @@ -9524,16 +9544,16 @@
> via HTML.</p>
>
> <p>
> - If your package comes with extensive documentation in a
> + If the package comes with extensive documentation in a
> markup format that can be converted to various other formats
> you should if possible ship HTML versions in a binary
> - package, in the directory
> - <file>/usr/share/doc/<var>appropriate-package</var></file> or
> - its subdirectories.<footnote>
> - The rationale: The important thing here is that HTML
> - docs should be available in <em>some</em> package, not
> - necessarily in the main binary package.
> + package.<footnote>
> + Rationale: The important thing here is that HTML
> + documentation should be available from <em>some</em>
> + binary package.
> </footnote>
> + The documentation must be installed as specified in
> + <ref id="docs-additional">.
> </p>
>
> <p>
This part is fairly confusing, although that's not a new problem, just
highlighted by the changes nearby.
I think that last "must" should be a "should".
--
Russ Allbery (rra@debian.org) <http://www.eyrie.org/~eagle/>
Reply to: