Jonathan Nieder <jrnie...@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 (r...@debian.org) <http://www.eyrie.org/~eagle/> -- To UNSUBSCRIBE, email to debian-policy-requ...@lists.debian.org with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org Archive: http://lists.debian.org/87y5tknrp4....@windlord.stanford.edu
