Bug#106073: recommend to install package documentation into /usr/share/doc/package/
On Wed, Apr 29, 2015 at 11:56:41AM +0200, Bill Allombert wrote: Seconded. I suggest we move forward with this and that I apply it to master next week, if Russ is still OK with this. Done. This is the summary: * Policy: [12.3] recommend to ship additional documentation for package 'pkg' in a separate package 'pkg-doc' and install it into /usr/share/doc/pkg. Wording: Russ Allbery r...@debian.org Seconded: Bill Allombert ballo...@debian.org Seconded: Charles Plessy ple...@debian.org Closes: #106073 Cheers, -- Bill. ballo...@debian.org Imagine a large red swirl here. -- To UNSUBSCRIBE, email to debian-policy-requ...@lists.debian.org with a subject of unsubscribe. Trouble? Contact listmas...@lists.debian.org Archive: https://lists.debian.org/20150508154128.GA12759@yellowpig
Bug#106073: recommend to install package documentation into /usr/share/doc/package/
On Sat, Jan 07, 2012 at 08:51:58AM -0800, Russ Allbery wrote: Russ Allbery r...@debian.org writes: As always, once I start seriously poking at an area of Policy, I see other little things that need to be fixed as well. Here is a general overhaul of the additional documentation section, which should both address this bug as well as a few other things. [...] Here is an updated version of the patch with feedback to date taken into account. diff --git a/policy.sgml b/policy.sgml index c1ff4b4..4dce37c 100644 --- a/policy.sgml +++ b/policy.sgml @@ -9702,45 +9702,77 @@ END-INFO-DIR-ENTRY /p /sect - sect + sect id=docs-additional headingAdditional documentation/heading p - Any additional documentation that comes with the package may - be installed at the discretion of the package maintainer. - Plain text documentation should be installed in the directory - file/usr/share/doc/varpackage/var/file, where - varpackage/var is the name of the package, and - compressed with ttgzip -9/tt unless it is small. -/p + Any additional documentation that comes with the package may be + installed at the discretion of the package maintainer. It is + often a good idea to include text information files + (fileREADME/files, FAQs, and so forth) that come with the + source package in the binary package. However, you don't need + to install the instructions for building and installing the + package, of course! + /p p - If a package comes with large amounts of documentation which - many users of the package will not require you should create - a separate binary package to contain it, so that it does not - take up disk space on the machines of users who do not need - or want it installed./p + Plain text documentation should be compressed with ttgzip + -9/tt unless it is small. + /p p - It is often a good idea to put text information files - (fileREADME/files, changelogs, and so forth) that come with - the source package in file/usr/share/doc/varpackage/var/file - in the binary package. However, you don't need to install - the instructions for building and installing the package, of - course!/p + If a package comes with large amounts of documentation that many + users of the package will not require, you should create a + separate binary package to contain it so that it does not take + up disk space on the machines of users who do not need or want + it installed. As a special case of this rule, shared library + documentation of any appreciable size should always be packaged + with the library development package (ref id=sharedlibs-dev) + or in a separate documentation package, since shared libraries + are frequently installed as dependencies of other packages by + users who have little interest in documentation of the library + itself. The documentation package for the + package varpackage/var is conventionally + named varpackage/var-doc + (or varpackage/var-doc-varlanguage-code/var if there are + separate documentation packages for multiple languages). + /p + + p + Additional documentation included in the package should be + installed under file/usr/share/doc/varpackage/var/file. + If the documentation is packaged separately, + as varpackage/var-doc for example, it may be installed under + either that path or into the documentation directory for the + separate documentation package + (file/usr/share/doc/varpackage/var-doc/file in this + example). 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 + + p + Any separate package providing documentation must still install + standard documentation files in its + own file/usr/share/doc/file directory as specified in the + rest of this policy. See, for example, ref id=copyrightfile + and ref id=changelogs. + /p p Packages must not require the existence of any files in file/usr/share/doc//file in order to function footnote - The system administrator should be able to - delete files in file/usr/share/doc//file without causing - any programs to break. - /footnote. - Any files that are referenced by programs but are also - useful as stand alone documentation should be installed under - file/usr/share/varpackage/var//file with symbolic links from - file/usr/share/doc/varpackage/var/file. + The system
Bug#106073: recommend to install package documentation into /usr/share/doc/package/
Le Sat, Jan 07, 2012 at 08:51:58AM -0800, Russ Allbery a écrit : Russ Allbery r...@debian.org writes: As always, once I start seriously poking at an area of Policy, I see other little things that need to be fixed as well. Here is a general overhaul of the additional documentation section, which should both address this bug as well as a few other things. [...] Here is an updated version of the patch with feedback to date taken into account. diff --git a/policy.sgml b/policy.sgml index c1ff4b4..4dce37c 100644 Seconded. -- Charles -- 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/20120108092048.gf1...@merveille.plessy.net
Bug#106073: recommend to install package documentation into /usr/share/doc/package/
Russ Allbery r...@debian.org writes: As always, once I start seriously poking at an area of Policy, I see other little things that need to be fixed as well. Here is a general overhaul of the additional documentation section, which should both address this bug as well as a few other things. [...] Here is an updated version of the patch with feedback to date taken into account. diff --git a/policy.sgml b/policy.sgml index c1ff4b4..4dce37c 100644 --- a/policy.sgml +++ b/policy.sgml @@ -9702,45 +9702,77 @@ END-INFO-DIR-ENTRY /p /sect - sect + sect id=docs-additional headingAdditional documentation/heading p - Any additional documentation that comes with the package may - be installed at the discretion of the package maintainer. - Plain text documentation should be installed in the directory - file/usr/share/doc/varpackage/var/file, where - varpackage/var is the name of the package, and - compressed with ttgzip -9/tt unless it is small. -/p + Any additional documentation that comes with the package may be + installed at the discretion of the package maintainer. It is + often a good idea to include text information files + (fileREADME/files, FAQs, and so forth) that come with the + source package in the binary package. However, you don't need + to install the instructions for building and installing the + package, of course! + /p p - If a package comes with large amounts of documentation which - many users of the package will not require you should create - a separate binary package to contain it, so that it does not - take up disk space on the machines of users who do not need - or want it installed./p + Plain text documentation should be compressed with ttgzip + -9/tt unless it is small. + /p p - It is often a good idea to put text information files - (fileREADME/files, changelogs, and so forth) that come with - the source package in file/usr/share/doc/varpackage/var/file - in the binary package. However, you don't need to install - the instructions for building and installing the package, of - course!/p + If a package comes with large amounts of documentation that many + users of the package will not require, you should create a + separate binary package to contain it so that it does not take + up disk space on the machines of users who do not need or want + it installed. As a special case of this rule, shared library + documentation of any appreciable size should always be packaged + with the library development package (ref id=sharedlibs-dev) + or in a separate documentation package, since shared libraries + are frequently installed as dependencies of other packages by + users who have little interest in documentation of the library + itself. The documentation package for the + package varpackage/var is conventionally + named varpackage/var-doc + (or varpackage/var-doc-varlanguage-code/var if there are + separate documentation packages for multiple languages). + /p + + p + Additional documentation included in the package should be + installed under file/usr/share/doc/varpackage/var/file. + If the documentation is packaged separately, + as varpackage/var-doc for example, it may be installed under + either that path or into the documentation directory for the + separate documentation package + (file/usr/share/doc/varpackage/var-doc/file in this + example). 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 + + p + Any separate package providing documentation must still install + standard documentation files in its + own file/usr/share/doc/file directory as specified in the + rest of this policy. See, for example, ref id=copyrightfile + and ref id=changelogs. + /p p Packages must not require the existence of any files in file/usr/share/doc//file in order to function footnote - The system administrator should be able to - delete files in file/usr/share/doc//file without causing - any programs to break. - /footnote. - Any files that are referenced by programs but are also - useful as stand alone documentation should be installed under - file/usr/share/varpackage/var//file with symbolic links from - file/usr/share/doc/varpackage/var/file. + The system administrator
Bug#106073: recommend to install package documentation into /usr/share/doc/package/
As always, once I start seriously poking at an area of Policy, I see other little things that need to be fixed as well. Here is a general overhaul of the additional documentation section, which should both address this bug as well as a few other things. The changes here are: * Shared library documentation is called out as a special case of the general rule that documentation should be packaged separately if it's large, recommending installing documentation of any appreciable size in the development package or a separate documentation package rather than the shared library package. * The naming convention for documentation packages (package-doc or package-doc-language) is explicitly stated (but is not a requirement). * package-doc is allowed to put documentation in either /usr/share/doc/package or /usr/share/doc/package-doc, but the former is preferred. package-doc still has to install its own mandatory documentation files (changelog, copyright) in /usr/share/doc/package-doc. * The paragraph about /usr/doc is removed. * Some reorganization and wording tweaks to hopefully make things clearer. Discussion, objections, seconds? diff --git a/policy.sgml b/policy.sgml index c1ff4b4..0b034c8 100644 --- a/policy.sgml +++ b/policy.sgml @@ -9702,45 +9702,77 @@ END-INFO-DIR-ENTRY /p /sect - sect + sect id=docs-additional headingAdditional documentation/heading p - Any additional documentation that comes with the package may - be installed at the discretion of the package maintainer. - Plain text documentation should be installed in the directory - file/usr/share/doc/varpackage/var/file, where - varpackage/var is the name of the package, and - compressed with ttgzip -9/tt unless it is small. -/p + Any additional documentation that comes with the package may be + installed at the discretion of the package maintainer. It is + often a good idea to include text information files + (fileREADME/files, fileTODO/files, and so forth) that + come with the source package in the binary package. However, + you don't need to install the instructions for building and + installing the package, of course! + /p p - If a package comes with large amounts of documentation which - many users of the package will not require you should create - a separate binary package to contain it, so that it does not - take up disk space on the machines of users who do not need - or want it installed./p + Plain text documentation should be compressed with ttgzip + -9/tt unless it is small. + /p p - It is often a good idea to put text information files - (fileREADME/files, changelogs, and so forth) that come with - the source package in file/usr/share/doc/varpackage/var/file - in the binary package. However, you don't need to install - the instructions for building and installing the package, of - course!/p + If a package comes with large amounts of documentation that many + users of the package will not require, you should create a + separate binary package to contain it so that it does not take + up disk space on the machines of users who do not need or want + it installed. As a special case of this rule, shared library + documentation of any appreciable size should always be packaged + with the library development package (ref id=sharedlibs-dev) + or in a separate documentation package, since shared libraries + are frequently installed as dependencies of other packages by + users who have little interest in documentation of the library + itself. The documentation package for the + package varpackage/var is conventionally + named varpackage/var-doc + (or varpackage/var-doc-varlanguage-code/var if there are + separate documentation packages for multiple languages). + /p + + p + Additional documentation included in the package must be + installed under file/usr/share/doc/varpackage/var/file. + If the documentation is packaged separately, + as varpackage/var-doc for example, it may be installed under + either that path or into the documentation directory for the + separate documentation package + (file/usr/share/doc/varpackage/var-doc/file in this + example). 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 + + p + Any separate package providing documentation must still install + standard documentation files in its + own
Bug#106073: recommend to install package documentation into /usr/share/doc/package/
Hi, Russ Allbery wrote: * Some reorganization and wording tweaks to hopefully make things clearer. Alas, there's a lot of this --- enough that I wish this had been prepared as a multiple-patch series, with for example whitespace-only changes split out. Oh, well. Onward. :) [...] --- a/policy.sgml +++ b/policy.sgml @@ -9702,45 +9702,77 @@ END-INFO-DIR-ENTRY /p /sect - sect + sect id=docs-additional headingAdditional documentation/heading p - Any additional documentation that comes with the package may + Any additional documentation that comes with the package may be The rewrapping could go straight to master. [...] - Plain text documentation should be installed in the directory - file/usr/share/doc/varpackage/var/file + It is + often a good idea to include text information files Putting the overview information first. Good idea. [...] p - It is often a good idea to put text information files - (fileREADME/files, changelogs, and so forth) that come with - the source package in file/usr/share/doc/varpackage/var/file - in the binary package. + It is + often a good idea to include text information files + (fileREADME/files, fileTODO/files, 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. 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.) [...] p - If a package comes with large amounts of documentation which - many users of the package will not require you should create - a separate binary package to contain it, so that it does not - take up disk space on the machines of users who do not need - or want it installed./p + If a package comes with large amounts of documentation that many + users of the package will not require, you should create a + separate binary package to contain it so that it does not take + up disk space on the machines of users who do not need or want + it installed. Could go straight to master (rewrapping and trivial wording changes). As a special case of this rule, shared library + documentation of any appreciable size should always be packaged + with the library development package (ref id=sharedlibs-dev) + or in a separate documentation package [...] +The documentation package for the + package varpackage/var is conventionally + named varpackage/var-doc + (or varpackage/var-doc-varlanguage-code/var if there are + separate documentation packages for multiple languages). + /p Sensible. + p + Additional documentation included in the package must be + installed under file/usr/share/doc/varpackage/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. + If the documentation is packaged separately, + as varpackage/var-doc for example, it may be installed under + either that path or into the documentation directory for the + separate documentation package + (file/usr/share/doc/varpackage/var-doc/file in this + example). I guess this modifies the must above. 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? [...] p Packages must not require the existence of any files in file/usr/share/doc//file in order to function footnote - The system administrator should be able to + The system administrator should be able to delete files Could go straight to master. :) [...] - /footnote. - Any files that are referenced by programs but are also - useful as stand alone documentation should be installed under - file/usr/share/varpackage/var//file with symbolic links from - file/usr/share/doc/varpackage/var/file. + /footnote. Any files that are referenced by programs but are + also useful as stand alone documentation should be installed + elsewhere,
Bug#106073: recommend to install package documentation into /usr/share/doc/package/
Jonathan Nieder jrnie...@gmail.com writes: Russ Allbery wrote: [...] p - It is often a good idea to put text information files - (fileREADME/files, changelogs, and so forth) that come with - the source package in file/usr/share/doc/varpackage/var/file - in the binary package. + It is + often a good idea to include text information files + (fileREADME/files, fileTODO/files, 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/varpackage/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/varpackage/var//file with symbolic links from - file/usr/share/doc/varpackage/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/varpackage/var//file, and then + included via symbolic links + in file/usr/share/doc/varpackage/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
Re: Bug#106073: recommend to install package documentation into /usr/share/doc/package/
Le Fri, Jan 06, 2012 at 09:13:13AM -0800, Russ Allbery a écrit : Discussion, objections, seconds? Dear Russ, overall, I am very positive with your changes, but here are two comments that I hope can improve the section. + p + Any separate package providing documentation must still install + standard documentation files in its + own file/usr/share/doc/file directory as specified in the + rest of this policy. See, for example, ref id=copyrightfile + and ref id=changelogs. + /p There have been recurrent discussions about /usr/share/doc/varpackage/var-doc being a symbolic link to /usr/share/doc/varpackage/var. In my understanding, this is discouraged now. Perhaps this desserves a 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/varpackage/var//file, and then + included via symbolic links + in file/usr/share/doc/varpackage/var/file. While ‘referenced’ is in the original wording, maybe it could be clarified. For instance, if the help page of a program contains “Please refer to the Foo specification”, and the spec is in /usr/share/doc, I assume that it can stay there ? Have a nice day, -- Charles Plessy Tsurumi, Kanagawa, Japan -- 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/20120107032050.ga3...@merveille.plessy.net
Bug#106073: recommend to install package documentation into /usr/share/doc/package/
Charles Plessy ple...@debian.org writes: There have been recurrent discussions about /usr/share/doc/varpackage/var-doc being a symbolic link to /usr/share/doc/varpackage/var. In my understanding, this is discouraged now. Perhaps this desserves a footnote ? I tried to avoid changing anything in this area because we have another bug with quite a bit of discussion about that (#556015 and its merged bug) and resolving that is going to be more work. That section was just an attempt to preserve the status quo until we can deal with the other issue, since I'm not sure what the outcome will be. +Any files that are referenced by programs but are + also useful as stand alone documentation should be installed + elsewhere, normally + under file/usr/share/varpackage/var//file, and then + included via symbolic links + in file/usr/share/doc/varpackage/var/file. While ‘referenced’ is in the original wording, maybe it could be clarified. For instance, if the help page of a program contains “Please refer to the Foo specification”, and the spec is in /usr/share/doc, I assume that it can stay there ? Oh, yes. The intent here is that any files that are used or read by programs need to not be in /usr/share/doc so that those programs don't break; just referring to that area in, say, help text in the program is fine. I'll reword this. -- 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/877h14nq74@windlord.stanford.edu
Bug#106073: recommend to install package documentation into /usr/share/doc/package/
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+deb...@benfinney.id.au writes: Russ Allbery r...@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//filevarpackage-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//filevarpackage-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 (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/8762yprpci@windlord.stanford.edu
Re: Bug#106073: recommend to install package documentation into /usr/share/doc/package/
Russ Allbery r...@debian.org writes: Thank you for writing this up! It's my pleasure. 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? We'll need a Lintian tag, etc., to actually get everything moved over. Should that be a separate bug report? 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? + 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. -- \ “Teach a man to make fire, and he will be warm for a day. Set a | `\ man on fire, and he will be warm for the rest of his life.” | _o__) —John A. Hrastar | Ben Finney -- 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/8739tziscr@benfinney.id.au
Bug#106073: recommend to install package documentation into /usr/share/doc/package/
On Fri, 2010-08-27 at 10:16 -0700, Russ Allbery wrote: Andrew McMillan and...@morphoss.com writes: My personal preference would be to encourage -doc packages to install their files into /usr/share/doc/package/docs - including their internal administrivia. That would break Lintian, apt-listchanges, probably the DAK processing scripts, and anything else that looks at copyright and changelog in binary packages. I don't think it's worth it to make that change. While this is not current practice, I'm not convinced that current practice has evolved into what was suggested in 2003 either. Right now, I'm seeing a real mix of behavior, with some packages installing all the documentation into the -doc package's /usr/share/doc (probably in part because that's easier) and others installing it into the parent package, some with symlinks and some without. As a result, right now one cannot easily find the documentation in any standardized place. I also remember as a user hunting for these documents the first time or two when I had installed the -doc package and it slowly dawning on me that they weren't anywhere in /usr/share/doc/package, and I think that breaks the principal of least surprise, for everyone except long-time, hard-core Debianista. Yeah, that's what Ben's writeup would fix, and I agree that's worth fixing. Those points are justifications for both proposals, of course, and I guess that one reason for retaining the administrivia in /usr/share/doc/package-doc might be that there are tools that expect to find it there. Is that the case? Yup. I don't think I ever do more than refer to them by hand, and either proposed change can probably be codified in some small number of scripts. I don't think the change proposed here requires changing any scripts, although it will require changing a bunch of packages (and a change to debhelper to make it easier to install docs into the right place would be useful). In that case I support changing it the way Ben proposes. I can certainly see the value of standardising it, and doing it this way definitely improves the situation. Cheers, Andrew. -- andrew (AT) morphoss (DOT) com+64(272)DEBIAN I'll burn my books. -- Christopher Marlowe signature.asc Description: This is a digitally signed message part
Bug#106073: recommend to install package documentation into /usr/share/doc/package/
package debian-policy retitle 106073 recommend to install additional documentation into /usr/share/doc/package/ tags 106073 + patch thanks On 27-Sep-2003, Josip Rodin wrote: Some proposed mandating that -doc package contents is placed into /usr/share/doc/package/, and that the administrivia such as copyright and changelog stays in /usr/share/doc/package-doc/. This sounds good to me because it has a sort of an internal logic, the -doc suffix only exists because of packaging, it's actually the docs for package. Plus, it's shorter, less to type. There seems to be consensus on doing this, so I've made a patch (attached to this message) which implements that recommendation. -- \ “We are stuck with technology when what we really want is just | `\ stuff that works.” —Douglas Adams | _o__) | Ben Finney b...@benfinney.id.au === modified file 'debian/changelog' --- debian/changelog 2010-08-18 20:55:34 + +++ debian/changelog 2010-08-25 03:28:19 + @@ -16,7 +16,12 @@ paragraph discussing non-interactivity, and explicitly mark all rules as either required or optional. (Closes: #536790) - -- Russ Allbery r...@debian.org Thu, 12 Aug 2010 10:47:47 -0700 + [ Ben Finney ] + + * Be explicit about where additional documentation should be installed. +(Closes: Bug#106073) + + -- debian-policy (3.9.1.0) unstable; urgency=low === modified file 'policy.sgml' --- policy.sgml 2010-08-18 20:55:34 + +++ policy.sgml 2010-08-25 03:23:50 + @@ -9444,16 +9444,17 @@ /p /sect - sect + sect id=docs-additional headingAdditional documentation/heading p Any additional documentation that comes with the package may be installed at the discretion of the package maintainer. - Plain text documentation should be installed in the directory - file/usr/share/doc/varpackage/var/file, where - varpackage/var is the name of the package, and - compressed with ttgzip -9/tt unless it is small. + /p + + p + Plain text documentation should be compressed with ttgzip + -9/tt unless it is small. /p p @@ -9464,6 +9465,25 @@ or want it installed./p p + Additional documentation for varpackage/var, whether the + documentation is packaged separately or not, should be + installed to the directory + file/usr/share/doc/varpackage/var/file or its + subdirectories.footnote + Rationale: Once installed, the separation of the + documentation packaging should be invisible to the user, + and the documentation should be found in the expected + location for the main binary package. + /footnote + /p + + p + Any separate package providing documentation must still + install files as specified in the rest of this policy; for + example, ref id=copyrightfile and ref id=changelogs. + /p + + p It is often a good idea to put text information files (fileREADME/files, changelogs, and so forth) that come with the source package in file/usr/share/doc/varpackage/var/file @@ -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/varappropriate-package/var/file or - its subdirectories.footnote - The rationale: The important thing here is that HTML - docs should be available in emsome/em package, not - necessarily in the main binary package. + package.footnote + Rationale: The important thing here is that HTML + documentation should be available from emsome/em + binary package. /footnote + The documentation must be installed as specified in + ref id=docs-additional. /p p signature.asc Description: Digital signature
Processed: Bug#106073: recommend to install package documentation into /usr/share/doc/package/
Processing commands for cont...@bugs.debian.org: package debian-policy Limiting to bugs with field 'package' containing at least one of 'debian-policy' Limit currently set to 'package':'debian-policy' retitle 106073 recommend to install additional documentation into /usr/share/doc/package/ Bug #106073 [debian-policy] Separate doc packages should not put docs in /usr/share/doc/package-doc Changed Bug title to 'recommend to install additional documentation into /usr/share/doc/package/' from 'Separate doc packages should not put docs in /usr/share/doc/package-doc' tags 106073 + patch Bug #106073 [debian-policy] recommend to install additional documentation into /usr/share/doc/package/ Added tag(s) patch. thanks Stopping processing here. Please contact me if you need assistance. -- 106073: http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=106073 Debian Bug Tracking System Contact ow...@bugs.debian.org with problems -- 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/handler.s.c.128271211213004.transcr...@bugs.debian.org
Bug#106073: recommend to install package documentation into /usr/share/doc/package/
On Wed, 2010-08-25 at 14:55 +1000, Ben Finney wrote: On 27-Sep-2003, Josip Rodin wrote: Some proposed mandating that -doc package contents is placed into /usr/share/doc/package/, and that the administrivia such as copyright and changelog stays in /usr/share/doc/package-doc/. This sounds good to me because it has a sort of an internal logic, the -doc suffix only exists because of packaging, it's actually the docs for package. Plus, it's shorter, less to type. There seems to be consensus on doing this, so I've made a patch (attached to this message) which implements that recommendation. Hi Ben, Thanks for the patch, but since that was from 2003 I wonder if it deserves a little more discussion now, before we apply it. My personal preference would be to encourage -doc packages to install their files into /usr/share/doc/package/docs - including their internal administrivia. While this is not current practice, I'm not convinced that current practice has evolved into what was suggested in 2003 either. While both proposals would move the package-doc content to under /usr/share/doc/package, I would prefer to see a reduction in the number of directories under /usr/share/doc - admittedly on my own system this would only be around 1% reduction. I also remember as a user hunting for these documents the first time or two when I had installed the -doc package and it slowly dawning on me that they weren't anywhere in /usr/share/doc/package, and I think that breaks the principal of least surprise, for everyone except long-time, hard-core Debianista. I think it particularly confuses people when the -doc package first splits out of the original package, since the docs get moved away at that point. Those points are justifications for both proposals, of course, and I guess that one reason for retaining the administrivia in /usr/share/doc/package-doc might be that there are tools that expect to find it there. Is that the case? I don't think I ever do more than refer to them by hand, and either proposed change can probably be codified in some small number of scripts. Cheers, Andrew McMillan. -- andrew (AT) morphoss (DOT) com+64(272)DEBIAN Change your thoughts and you change your world. signature.asc Description: This is a digitally signed message part
Virtual package documentation (Was Re: [... Bug#154142 ...])
At (time_t)1027974412 Wichert Akkerman wrote: For each virtual package we should document * a description of what it should be used for * a complete description of the interface packages should provide if that is relevant for that virtual package Another potential documentation point would be whether the virtual package name is shared by a real package. I understand that that could change over time, however, and thus perhaps should be excluded. -John -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Re: Package documentation
Ben == Ben Collins [EMAIL PROTECTED] writes: Ben If the maintainer can't add The docs reference paths that do Ben not exist on a Debian system to README.Debian, then I would Ben think something is severely wrong with how the package is Ben maintained. I would suggest that it would be better use of the maintainers time fixing problems. Maybe not immediately, but whenever convenient. Also, I would encourage the upstream maintainer to create the documentation (eg. man pages) dynamically (eg. pre-processed by sed, m4, or whatever), so the paths will always be correctly set (especially for packages based on autoconf). -- Brian May [EMAIL PROTECTED]
Re: Package documentation
* Brian May [EMAIL PROTECTED] [010305 22:20]: I would suggest that it would be better use of the maintainers time fixing problems. It shouldn't be that tough; note whatever the --prefix etc options are to the configure script if it has one, and make a note of this in README.Debian. For those packages without configure, well .. hopefully it still isn't difficult. :) -- Earthlink: The #1 provider of unsolicited bulk email to the Internet.
Re: Package documentation
On Tue, Mar 06, 2001 at 12:07:20AM -0500, Ben Collins wrote: On Tue, Mar 06, 2001 at 10:24:41AM +1000, Anthony Towns wrote: On Mon, Mar 05, 2001 at 09:01:23AM -0500, Ben Collins wrote: IMO, it should say packages SHOULD change the docs to match the package setup, and there MUST be a disclaimer when docs do not match the package, and the disclaimer SHOULD be in the upstream doc itself, or in a the README.Debian if not. Give me a break. You want a package removed from the archive, just because it doesn't have a disclaimer about buggy docs? If the maintainer can't add The docs reference paths that do not exist on a Debian system to README.Debian, then I would think something is severely wrong with how the package is maintained. Quite possibly. I'm sure you think there're problems with the way most of my packages are being maintained too, and to be honest there is. There are lots of open bugs that should've been fixed a while ago. Why is it that whenever something is proposed as a MUST, people always resort to you really want to remove packages for reason foo? Because that is what must means. If you don't want to remove packages, the guidelines should be expressed as a should, not a must. I mean, this is a simple request, and a simple thing to do, and for consistency sake, it's all the better that it be done. It doesn't mean it will be removed, it means someone has to fix the bug. Plain and simple. (Here we go again) _NO_. This is completely mistaken and bogus. You are completely wrong in making that statement. Packages with RC bugs, packages violating policy requirements (musts) get pulled. That's what RC bugs, and MUSTs, are for. They don't have any other purpose; they're not there to give us a bigger or sharper stick for beating inactive maintainers over the head with, they're not there to differentiate between which guidelines are easy and which are hard; they're there simply to set an absolute minimum standard for inclusion in a Debian release. It's in policy because it's better to have it documented than left to the release manager's whim. I'm running out of ways to say this, and I'm not really convinced shouting helps, but this really really needs to sink in. Cheers, aj -- Anthony Towns [EMAIL PROTECTED] http://azure.humbug.org.au/~aj/ I don't speak for anyone save myself. GPG signed mail preferred. ``_Any_ increase in interface difficulty, in exchange for a benefit you do not understand, cannot perceive, or don't care about, is too much.'' -- John S. Novak, III (The Humblest Man on the Net) pgpXMoIcmdeJp.pgp Description: PGP signature
Re: Package documentation
On Tue, Mar 06, 2001 at 12:01:05PM +0100, Richard Braakman wrote: I think the basic problem here is that the policy manual is using MUST and SHOULD (actually _must_ and _should_) in a different sense than anywhere else. Actually it's just the words `must' and `should', capitalisation and markup isn't relevant. Cheers, aj -- Anthony Towns [EMAIL PROTECTED] http://azure.humbug.org.au/~aj/ I don't speak for anyone save myself. GPG signed mail preferred. ``_Any_ increase in interface difficulty, in exchange for a benefit you do not understand, cannot perceive, or don't care about, is too much.'' -- John S. Novak, III (The Humblest Man on the Net)
Re: Package documentation
On Tue, Mar 06, 2001 at 12:01:05PM +0100, Richard Braakman wrote: I think the basic problem here is that the policy manual is using MUST and SHOULD (actually _must_ and _should_) in a different sense than anywhere else. This is hard to adjust to for someone used to reading RFCs. The usage I'm familiar with is that MUST signifies that noncompliance is definitely a bug, and SHOULD signifies that noncompliance is a bug unless it solves a real problem. With the policy manual's usage, there seems to be no way to express that something is definitely a bug, but not necessarily a severe one. Agreed. Julian -- =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- Julian Gilbey, Dept of Maths, Queen Mary, Univ. of London Debian GNU/Linux Developer, see http://people.debian.org/~jdg Donate free food to the world's hungry: see http://www.thehungersite.com/
Re: Package documentation
Henrique == Henrique M Holschuh [EMAIL PROTECTED] writes: I think that all documentation must reflect the Debian locations of configuration and other files, and that manpages and the like should be altered as necessary to achieve this. =20 Comments? Henrique I've seen many manpages in Debian altered to do exactly Henrique what you describe. Actually, I've seen upstream code Henrique that automatically does this when properly configured. Henrique I wonder if anyone ever refused doing such a change? I suspect I will be in the position of doing so fairly shortly. The Openafs admin guide is distributed as PDF and HTML. Neither of those are reasonable source formats and while the license would allow me to change them, I will probably not do so. I am especially not interested in hacking the contents of a PDF. I consider the lack of reasonable documentation sources an upstream bug and have pointed it out to upstream, which cannot easily fix it. Instead I will try to have a very clear warning in the appropriate READMEs and potentially in a package level index.html. As such, I would not like to see a MUST added to policy for updating upstream docs.
Re: Package documentation
On Mon, Mar 05, 2001 at 08:07:56AM -0500, Sam Hartman wrote: As such, I would not like to see a MUST added to policy for updating upstream docs. I think it should atleast say Some of the locations and features depend on how the program was compiled and installed. This is what it says in passwd and login program manpages. IMO, it should say packages SHOULD change the docs to match the package setup, and there MUST be a disclaimer when docs do not match the package, and the disclaimer SHOULD be in the upstream doc itself, or in a the README.Debian if not. Ben -- ---===-=-==-=---==-=-- / Ben Collins -- ...on that fantastic voyage... -- Debian GNU/Linux \ ` [EMAIL PROTECTED] -- [EMAIL PROTECTED] -- [EMAIL PROTECTED] ' `---=--===-=-=-=-===-==---=--=---'
Re: Package documentation
On Tue, Mar 06, 2001 at 10:24:41AM +1000, Anthony Towns wrote: On Mon, Mar 05, 2001 at 09:01:23AM -0500, Ben Collins wrote: IMO, it should say packages SHOULD change the docs to match the package setup, and there MUST be a disclaimer when docs do not match the package, and the disclaimer SHOULD be in the upstream doc itself, or in a the README.Debian if not. Give me a break. You want a package removed from the archive, just because it doesn't have a disclaimer about buggy docs? If the maintainer can't add The docs reference paths that do not exist on a Debian system to README.Debian, then I would think something is severely wrong with how the package is maintained. Why is it that whenever something is proposed as a MUST, people always resort to you really want to remove packages for reason foo? I mean, this is a simple request, and a simple thing to do, and for consistency sake, it's all the better that it be done. It doesn't mean it will be removed, it means someone has to fix the bug. Plain and simple. -- ---===-=-==-=---==-=-- / Ben Collins -- ...on that fantastic voyage... -- Debian GNU/Linux \ ` [EMAIL PROTECTED] -- [EMAIL PROTECTED] -- [EMAIL PROTECTED] ' `---=--===-=-=-=-===-==---=--=---'
Re: Package documentation
Oliver == Oliver Elphick olly@lfix.co.uk writes: Oliver I think that all documentation must reflect the Debian Oliver locations of configuration and other files, and that manpages Oliver and the like should be altered as necessary to achieve this. Oliver Comments? Indeed, incorrect documentation is a bug. Why do you think we need to burden policy with stating the obvious? At best, this should go into the developers reference. manoj -- ...A strange enigma is man! Someone calls him a soul concealed in an animal, I suggested. Winwood Reade is good upon the subject, said Holmes. He remarked that, while the individual man is an insoluble puzzle, in the aggregate he becomes a mathematical certainty. You can, for example, never foretell what any one man will do, but you can say with precision what an average number will be up to. Individuals vary, but percentages remain constant. So says the statistician. Sherlock Holmes, The Sign of Four Manoj Srivastava [EMAIL PROTECTED] http://www.debian.org/%7Esrivasta/ 1024R/C7261095 print CB D9 F4 12 68 07 E4 05 CC 2D 27 12 1D F5 E8 6E 1024D/BF24424C print 4966 F272 D093 B493 410B 924B 21BA DABB BF24 424C
Package documentation
I should like to suggest an alteration to policy in respect of package documentation. Configuration file locations are oftenn changed for Debian. However the manual pages still refer to the upstream locations. This makes it very difficult to find out where to make changes, particularly for new users. I think that all documentation must reflect the Debian locations of configuration and other files, and that manpages and the like should be altered as necessary to achieve this. Comments? -- Oliver Elphick[EMAIL PROTECTED] Isle of Wight http://www.lfix.co.uk/oliver PGP: 1024R/32B8FAA1: 97 EA 1D 47 72 3F 28 47 6B 7E 39 CC 56 E4 C1 47 GPG: 1024D/3E1D0C1C: CA12 09E0 E8D5 8870 5839 932A 614D 4C34 3E1D 0C1C I will lift up mine eyes unto the hills, from whence cometh my help. My help cometh from the LORD, which made heaven and earth. Psalms 121:1,2
Re: Package documentation
On Fri, Mar 02, 2001 at 12:55:01PM +, Oliver Elphick wrote: Configuration file locations are oftenn changed for Debian. However the manual pages still refer to the upstream locations. This makes it very difficult to find out where to make changes, particularly for new users. Uh, so what's the point of policy here? If you change where the config files are, you're meant to change the documentation to match... Cheers, aj -- Anthony Towns [EMAIL PROTECTED] http://azure.humbug.org.au/~aj/ I don't speak for anyone save myself. GPG signed mail preferred. ``_Any_ increase in interface difficulty, in exchange for a benefit you do not understand, cannot perceive, or don't care about, is too much.'' -- John S. Novak, III (The Humblest Man on the Net) pgptC1K98ZhQw.pgp Description: PGP signature
Re: Package documentation
Previously Oliver Elphick wrote: I think that all documentation must reflect the Debian locations of configuration and other files, and that manpages and the like should be altered as necessary to achieve this. I would consider this a normal task for a maintainer and is too obvious to be in Debian. Incorrect documentation is a bug, and we don't need a policy document to tell us that. Wichert. -- / Generally uninteresting signature - ignore at your convenience \ | [EMAIL PROTECTED] http://www.liacs.nl/~wichert/ | | 1024D/2FA3BC2D 576E 100B 518D 2F16 36B0 2805 3CB8 9250 2FA3 BC2D |
Re: Package documentation
On Fri, 02 Mar 2001, Oliver Elphick wrote: Configuration file locations are oftenn changed for Debian. However the manual pages still refer to the upstream locations. This makes it very difficult to find out where to make changes, particularly for new users. AFAIK what you describe is a bug. manpages and other documentation should be patched to point to the correct locations, OR the change of locations must be made clear in README.Debian, IMHO (and also IMHO that's common sense). I think that all documentation must reflect the Debian locations of configuration and other files, and that manpages and the like should be altered as necessary to achieve this. Comments? I've seen many manpages in Debian altered to do exactly what you describe. Actually, I've seen upstream code that automatically does this when properly configured. I wonder if anyone ever refused doing such a change? I have doubts we need to add such to policy... Maybe mentioning make sure you update the location of files in the documentation you are packaging in the packaging-guide (if it's not there already, that is) as a remider would be enough? -- One disk to rule them all, One disk to find them. One disk to bring them all and in the darkness grind them. In the Land of Redmond where the shadows lie. -- The Silicon Valley Tarot Henrique Holschuh pgpEgbePzaGr3.pgp Description: PGP signature
Re: Package documentation
Wichert Akkerman wrote: Previously Oliver Elphick wrote: I think that all documentation must reflect the Debian locations of configuration and other files, and that manpages and the like should be altered as necessary to achieve this. I would consider this a normal task for a maintainer and is too obvious to be in Debian. Incorrect documentation is a bug, and we don't need a policy document to tell us that. I have in the past seen people argue that the upstream stuff should be left alone. -- Oliver Elphick[EMAIL PROTECTED] Isle of Wight http://www.lfix.co.uk/oliver PGP: 1024R/32B8FAA1: 97 EA 1D 47 72 3F 28 47 6B 7E 39 CC 56 E4 C1 47 GPG: 1024D/3E1D0C1C: CA12 09E0 E8D5 8870 5839 932A 614D 4C34 3E1D 0C1C I will lift up mine eyes unto the hills, from whence cometh my help. My help cometh from the LORD, which made heaven and earth. Psalms 121:1,2
Re: Package documentation
Anthony Towns wrote: --Dxnq1zWXvFF0Q93v Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Fri, Mar 02, 2001 at 12:55:01PM +, Oliver Elphick wrote: Configuration file locations are oftenn changed for Debian. However the manual pages still refer to the upstream locations. This makes it very difficult to find out where to make changes, particularly for new users. Uh, so what's the point of policy here? If you change where the config files are, you're meant to change the documentation to match... A number of packages don't. But if there is general agreement on this I shall simply raise bugs where I find them. -- Oliver Elphick[EMAIL PROTECTED] Isle of Wight http://www.lfix.co.uk/oliver PGP: 1024R/32B8FAA1: 97 EA 1D 47 72 3F 28 47 6B 7E 39 CC 56 E4 C1 47 GPG: 1024D/3E1D0C1C: CA12 09E0 E8D5 8870 5839 932A 614D 4C34 3E1D 0C1C I will lift up mine eyes unto the hills, from whence cometh my help. My help cometh from the LORD, which made heaven and earth. Psalms 121:1,2
Re: Package documentation
Previously Oliver Elphick wrote: I have in the past seen people argue that the upstream stuff should be left alone. Many things are argued, but not all are correct. If you follow that reasoning we would all be DJB-clones.. Wichert. -- / Generally uninteresting signature - ignore at your convenience \ | [EMAIL PROTECTED] http://www.liacs.nl/~wichert/ | | 1024D/2FA3BC2D 576E 100B 518D 2F16 36B0 2805 3CB8 9250 2FA3 BC2D |
Re: Package documentation
On Fri, Mar 02, 2001 at 10:43:21AM -0300, Henrique M Holschuh wrote: I wonder if anyone ever refused doing such a change? That would be a reason *not* to put it in policy, at least until we consider the reasons for such a refusal. Policy is supposed to encode the things we do agree on. I have doubts we need to add such to policy... Maybe mentioning make sure you update the location of files in the documentation you are packaging in the packaging-guide (if it's not there already, that is) as a remider would be enough? Such a reminder would be useful. It's something a maintainer might not think of when writing a rules file. And I think it should go in policy. Surely it is our policy to have documentation point to the correct files? Richard Braakman
Re: Package documentation
On Fri, 02 Mar 2001, Richard Braakman wrote: On Fri, Mar 02, 2001 at 10:43:21AM -0300, Henrique M Holschuh wrote: I have doubts we need to add such to policy... Maybe mentioning make sure you update the location of files in the documentation you are packaging in the packaging-guide (if it's not there already, that is) as a remider would be enough? Such a reminder would be useful. It's something a maintainer might not think of when writing a rules file. And I think it should go in I agree that it is a non-obvious thing, which is why I'd like to see a reminder added to the packaging guide if there isn't one there yet. policy. Surely it is our policy to have documentation point to the correct files? From a QA standpoint, I have to agree with you. On the other hand, I am not sure it is actually needed to modify policy to state that one should/must change all references of files that changed location. I am not objecting to a proposal, if one is actually put forth. -- One disk to rule them all, One disk to find them. One disk to bring them all and in the darkness grind them. In the Land of Redmond where the shadows lie. -- The Silicon Valley Tarot Henrique Holschuh pgps965A8R8vY.pgp Description: PGP signature
Re: Package documentation
That would be a reason *not* to put it in policy, at least until we consider the reasons for such a refusal. Policy is supposed to encode the things we do agree on. That's not true, and it never was. Policy changes often leaves existing packages in non-compliance. And that's good. As I see it policy is there to give somebody the right of filing a bug report.
Re: Non-free package documentation requirement
On Tue, Apr 07, 1998 at 07:05:33PM +0100, Ian Jackson wrote: I propose the following extra requirement for non-free and contrib packages: A package which is non-free must contain a file /usr/doc/package/README.non-free (or one of its dependencies must contain a relevant such file). This file must contain either: 1. A copy of an electronic mail message received by the package maintainer from the copyright holder(s) denying a request to make the package DFSG-free. Package maintainers should usually use a standard [deletia] How about calling the file README.why-non-free? And just require the maintainer to state in her own words why the package is in non-free? We could also have parallel README.why-contrib, README.why-non-us and README.why-dfsg (or README.why-free? or README.why-main?). However, for packages in main, the file could be omitted if the program adheres to a standard copyright and no controversy has previously been raised about its status. Then, when a package moves from non-free to main, for example, the maintainer would simply rename the file and add a statement about why it was moved. (Of course, this would be in the changelog anyway) Alternatively, the statement about why it's in that distribution could just be put at the top of the copyright file. The only difficulty would be if you wanted to add supporting evidence (excerpts from emails, for example), which could make the file a little long and unwieldly. ** MIKE ORR [EMAIL PROTECTED] ** ** Russki Deutsch Esperanto* * ** * * ** * * * (Insert silly quote here) -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Re: Non-free package documentation requirement
[I wonder at which stage this proposal is at the moment] On Tue, Apr 07, 1998 at 07:05:33PM +0100, Ian Jackson wrote: I propose the following extra requirement for non-free and contrib packages: A package which is non-free must contain a file /usr/doc/package/README.non-free (or one of its dependencies must contain a relevant such file). This file must contain either: 1. A copy of an electronic mail message received by the package maintainer from the copyright holder(s) denying a request to make the package DFSG-free. Package maintainers should usually use a standard request for this, which is at [INSERT URL/FILENAME]. The request must have stated that the response will be made public, and must also be included in the file. I like this. This sounds logical to what Debian is and wants to be, the 100% free Linux distribution. Regards, Joey -- / Martin Schulze * [EMAIL PROTECTED] * 26129 Oldenburg / / http://home.pages.de/~joey/ / Never trust an operating system you don't have source for! / pgpPQwTT8kT9H.pgp Description: PGP signature
Re: Non-free package documentation requirement
Hi, Alex == [EMAIL PROTECTED] writes: I disagree. A package's placement in non-free should be a last resort. Making sorting out the copyright a requirement for inclusion in non-free will encourage efforts to fix the problem. Alex ... and be the way to ban the packages from being included into Alex the distribution available for the users. The world is coming to an end. I agree with Alex here. I maintain non-free/games/angband; and there is a morass of authors through whose hands angband has passed, with almost everyone putting a different set of copyright statements on their work, beofre passing the torch. Tracking down all the people involved in that is way too much work for me; I would just continue to maintain the package for myself, if the track down and implore author policy were made madatory. A free software fanatic would probably say that is a good thing. Mayhap a more enrgetic maintianer for angband would arrive on the scene. manoj -- Tourists -- have some fun with New york's hard-boiled cabbies. When you get to your destination, say to your driver, Pay? I was hitchhiking. David Letterman Manoj Srivastava [EMAIL PROTECTED] http://www.datasync.com/%7Esrivasta/ Key C7261095 fingerprint = CB D9 F4 12 68 07 E4 05 CC 2D 27 12 1D F5 E8 6E -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Re: Non-free package documentation requirement
Branden Robinson writes (Re: Non-free package documentation requirement): Uh, can we have some exception classes to this? For instance, xtrs is in contrib because it requires the ROM images from some very old, long dead computers. Those images were copyrighted by Tandy/Radio Shack and/or Microsoft. Their current legal status may be difficult to determine, and should they happen to belong to the latter, you can guess how we'll get laughed at. I honestly feel my time is better spent working on X than doing a paper chase after 20-year old ROM images. If no exceptions can be made, would someone care to chase this down for me by proxy? Incidentally, xtrs's own copyright is BSD-ish. They don't get much more free than that. This is already covered, because a free program can be in contrib. For contrib packages my proposal says: A package which is contrib must contain a file /usr/doc/package/README.contrib-only which describes the reasons for the package's placement in contrib. This is easily satisfied. Ian. -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Re: Non-free package documentation requirement
[Ian:] A package which is non-free must contain a file /usr/doc/package/README.non-free (or one of its dependencies must contain a relevant such file). This file must contain either: 1. A copy of an electronic mail message received by the package maintainer from the copyright holder(s) denying a request to make the package DFSG-free. Insert here: or a short description of the ongoing discussion. I disagree. A package's placement in non-free should be a last resort. Making sorting out the copyright a requirement for inclusion in non-free will encourage efforts to fix the problem. ... and be the way to ban the packages from being included into the distribution available for the users. I still insist on the inclusion of this correction. Package maintainers should usually use a standard request for this, which is at [INSERT URL/FILENAME]. The request must have stated that the response will be made public, and must also be Upstream author may object to making his response public. In this case maintainer sould NOT include the response, but just make a note of that. This is already covered by ... I don't see this being covered. If the author disagrees to make response public and just don't answer the mail - it is covered, but if he responds but asks not to make his response public - this is not covered. 2. A description by the package maintainer of their unsuccessful attempts to communicate with the original author to get a response to the request above. If the author's email address is believed to be known this must include at least two emails sent at intervals of at least one month. Insert here: (One email is enough if package upload date is within one month from the date of the first email). See my disagreement above. And my disagreement above. Thanks. Alex Y. -- _ _( )_ ( (o___ +---+ | _ 7 |Alexander Yukhimets| \()| http://pages.nyu.edu/~aqy6633/ | / \ \ +---+ -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Re: Non-free package documentation requirement
Count me 100% in favor. One question -- what about giflib where the copyright is obvious and will not change. Can this be noted rather than wasting our time e-mailing them? -- --- How can you see, when your mind is not open? How can you think, when your eyes are closed? - Jason Bonham Band, Ordinary Black and White --- -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Re: Non-free package documentation requirement
On Tue, 7 Apr 1998, Shaleh wrote: Count me 100% in favor. One question -- what about giflib where the copyright is obvious and will not change. Can this be noted rather than wasting our time e-mailing them? I expect we can/should probably draft a standard disclaimer similar to: --- snip --- This package uses LZW compression technology which Unisys claims to hold US and forign patents over (including US #4,558,302). Use of this software may require licencing from Unisys. Currently applicable information as to Unisys licensing policies for products using LZW (GIF, TIFF-LZW, PostScript, Portable Document Format (PDF), V.42bis, etc.) can be obtained by contacting the following: Welch Patent Licensing Department; Unisys; Mail Stop C1SW19; P.O. Box 500, Blue Bell, PA 19424. Via the Internet, send E-mail to [EMAIL PROTECTED], or use a form available on the Contact Page of the Unisys Web Server to request follow-up information. Via facsimile, send inquiries to Welch Patent Licensing Department at 215-986-3090. --- snip --- Note, of course, that I'm not a lawyer and I've just borrowed portions from http://www.unisys.com/LeadStory/lzwfaq.html -- Scott K. Ellis [EMAIL PROTECTED] http://www.gate.net/~storm/ -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
