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 <[email protected]> writes: > Russ Allbery <[email protected]> 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 ([email protected]) <http://www.eyrie.org/~eagle/> -- To UNSUBSCRIBE, email to [email protected] with a subject of "unsubscribe". Trouble? Contact [email protected] Archive: http://lists.debian.org/[email protected]
