Bug#106073: recommend to install <package> documentation into /usr/share/doc/<package>/
Jonathan Nieder <jrnieder@gmail.com> writes:
> Russ Allbery wrote:
> [...]
>> <p>
>> - It is often a good idea to put text information files
>> - (<file>README</file>s, changelogs, and so forth) that come with
>> - the source package in <file>/usr/share/doc/<var>package</var></file>
>> - in the binary package.
>> + It is
>> + often a good idea to include text information files
>> + (<file>README</file>s, <file>TODO</file>s, and so forth) that
>> + come with the source package in the binary package.
> Before, this included a reminder that including the upstream changelog
> is often a good idea[1]. Removing that reminder saves me from being
> confused into thinking it is _just_ a good idea rather than a policy
> "should" (good), but on the other hand it is removing a reminder.
I removed this because it just duplicates what we already say in 12.7 even
more strongly (as a "should"), and I didn't see any point in saying it
twice.
> This adds a mention that including upstream's TODO files is often a
> good idea. Maybe it is --- I'm not sure. (FAQs, acknowledgements,
> and API changelogs are more obvious examples to me.)
I can change the example to FAQs. I just wanted more than one example.
>> + <p>
>> + Additional documentation included in the package must be
>> + installed under <file>/usr/share/doc/<var>package</var></file>.
> (*)
> Strengthening to a "must". Is that intended? I haven't had the
> gumption yet, but I'd like to move liblzma-dev's documentation to
> /usr/share/doc/liblzma/ (with symlinks from .../doc/liblzma-dev) some
> day.
I suppose that probably doesn't matter, and we previously had this as a
should, so I could leave it as a should. I'll change this to should.
>> However, installing the documentation into the
>> + documentation directory of the main package is preferred since
>> + it is independent of the packaging method and will be easier for
>> + users to find.
>> + </p>
> In the case of liblzma-doc, what is the main package?
liblzma-dev, IMO. But more generally it's whatever package the
documentation is for, and that's intentionally left to the maintainer's
discretion, I think.
> [...]
>> - </footnote>.
>> - Any files that are referenced by programs but are also
>> - useful as stand alone documentation should be installed under
>> - <file>/usr/share/<var>package</var>/</file> with symbolic links from
>> - <file>/usr/share/doc/<var>package</var></file>.
>> + </footnote>. Any files that are referenced by programs but are
>> + also useful as stand alone documentation should be installed
>> + elsewhere, normally
>> + under <file>/usr/share/<var>package</var>/</file>, and then
>> + included via symbolic links
>> + in <file>/usr/share/doc/<var>package</var></file>.
> Yep, makes sense. Maybe even s/normally/for example/.
Good point. I'll change that. I just knew that should was too strong. :)
--
Russ Allbery (rra@debian.org) <http://www.eyrie.org/~eagle/>
Reply to: