Bug#139820: debian-policy: Overlong lines in .ps version
On Mon, 25 Mar 2002 17:49:34 -0600, Ardo van Rangelrooij [EMAIL PROTECTED] wrote: I'm the current developer of the DebianDoc-SGML package. (Just to clarify: my only concern is that the PostScript copy of the Policy Manual is not 100% usable at the moment. I'm not laying the blame on any particular tool; certainly the person who produced the file should be held responsible for the end result's fitness for the intended purpose.) I can also add an option to debiandoc2latex* to indicate lines wider then the textwidth. I imagine this could come in useful for avoiding similar problems in the future, though. /* era */ -- Too much to say to fit into this .signature anyway: http://www.iki.fi/era/ Fight spam in Europe: http://www.euro.cauce.org/ * Sign the EU petition -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Bug#139957: period at the end of short description?
Package: debian-policy Severity: minor Tags: patch Hi, this is not a major problem, but I'd like to see a bit more consistency among the package descriptions. The attached patch should be self-explanatory. A quick analysis of the Packages file suggests there is already a rough consensus in agreement. This is obviously a post-woody thing; we should put it off until then. cd /tmp/ diff -u -L /usr/share/doc/debian-policy/policy.sgml.gz -L /tmp/policy.sgml.new /tmp/jka-com6962AcG /tmp/policy.sgml.new --- /usr/share/doc/debian-policy/policy.sgml.gz +++ /tmp/policy.sgml.new @@ -2397,7 +2397,9 @@ p The single line synopsis should be kept brief - certainly - under 80 characters. + under 80 characters. This should be a sentence fragment + which summarizes the key features provided by the package. + It should not end in a full stop (`.'). /p p Diff finished at Tue Mar 26 01:07:12
Bug#139969: debian-policy: dubious shell programming advice re: set -e [patch included]
Package: debian-policy Version: 3.5.6.1 Severity: normal The sections which recommend the use of set -e are IMHO a bit off the mark. The recommendations imply that failing silently is a Good Thing and that not handling errors sensibly is okay in shell scripts. In summary, relying on set -e to trap your errors for you results in counter-intuitive behavior from the end user's perspective. If the init.d script just runs and doesn't tell you the program you wanted to start is not available, is that good behavior? If the script just dies silently when your disk fills up, is that good behavior? No, these errors should be trapped and at least result in a warning message. (For example, I have filed a bug against e.g. the `bug' package for an issue which is more or less caused by the present policy; see bug #76127. I suspect there will be many more which just wait to be discovered.) As a proposed fix, I have reworded some parts of the policy, as included in the patch below. This modifies the should and adds a may, with some related changes in earlier sections of the manual. I also took the liberty to add comments to the /etc/init.d/bind example where it breaks the new recommendation. I am not familiar with the procedures for making a formal proposal for an amendment to the policy. Somebody who is a Debian Developer could perhaps take it from here if you agree with this. Thank you for your time, /* era */ Index: policy.sgml === RCS file: /cvs/debian-policy/debian-policy/policy.sgml,v retrieving revision 1.67 diff -c -r1.67 policy.sgml *** policy.sgml 2002/03/14 18:17:48 1.67 --- policy.sgml 2002/03/26 08:57:11 *** *** 2486,2492 non-zero status if there is an error, so that the package management system can stop its processing. For shell scripts this means that you emalmost always/em need to ! use ttset -e/tt (this is usually true when writing shell scripts, in fact). It is also important, of course, that they don't exit with a non-zero status if everything went well. --- 2486,2492 non-zero status if there is an error, so that the package management system can stop its processing. For shell scripts this means that you emalmost always/em need to ! use ttset -e/tt (this is often true when writing shell scripts, in fact). It is also important, of course, that they don't exit with a non-zero status if everything went well. *** *** 4720,4728 --- 4720,4730 # Original version by Robert Leslie # lt;[EMAIL PROTECTED]gt;, edited by iwj and cs + # XXX: should perhaps print an error message test -x /usr/sbin/named || exit 0 # Source defaults file. + # XXX: should perhaps try to trap errors in the defaults file PARAMS='' if [ -f /etc/default/bind ]; then . /etc/default/bind *** *** 5631,5637 should almost certainly start with ttset -e/tt so that errors are detected. Every script should use ttset -e/tt or check the exit status of emevery/em ! command./p p The standard shell interpreter tt/bin/sh/tt can be a --- 5633,5644 should almost certainly start with ttset -e/tt so that errors are detected. Every script should use ttset -e/tt or check the exit status of emevery/em ! command. ! For maximum usability, ! it is recommended that ! common error conditions ! are caught and handled ! even if ttset -e/tt is used./p p The standard shell interpreter tt/bin/sh/tt can be a -- System Information Debian Release: 2.2 Kernel Version: Linux there 2.2.17 #1 Sun Jun 25 09:24:41 EST 2000 i586 unknown -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Bug#139957: period at the end of short description?
On Tue, Mar 26, 2002 at 01:10:14AM -0500, Colin Walters wrote: Package: debian-policy Severity: minor Tags: patch Hi, this is not a major problem, but I'd like to see a bit more consistency among the package descriptions. The attached patch should be self-explanatory. A quick analysis of the Packages file suggests there is already a rough consensus in agreement. --- /usr/share/doc/debian-policy/policy.sgml.gz +++ /tmp/policy.sgml.new The single line synopsis should be kept brief - certainly - under 80 characters. + under 80 characters. This should be a sentence fragment + which summarizes the key features provided by the package. + It should not end in a full stop (`.'). I second this. -- 2. That which causes joy or happiness. -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Bug#139957: period at the end of short description?
Colin == Colin Walters [EMAIL PROTECTED] writes: Colin Hi, this is not a major problem, but I'd like to see a bit more Colin consistency among the package descriptions. The attached patch should Colin be self-explanatory. A quick analysis of the Packages file suggests Colin there is already a rough consensus in agreement. I formally object to this. Why should the short description not be a full sentence? Why are we adding useless bloat to policy? This does not seem appropriate for policy anyway (there is no technical reason for not including a period, nor has there been any justification for doing it this way). Even if it were justified (I fail to see how), policy is not a best practices document. Policy is also not a stick to shake at developers after they close bugs that you reported on the issue. It is equally likely that the better thing to do would be to require all short descriptions to have a ending period (indeed, this shall be my counter GR). manoj irritated -- Your aim is high and to the right. 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 -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Bug#139969: debian-policy: dubious shell programming advice re: set -e [patch included]
era == era eriksson [EMAIL PROTECTED] writes: era The sections which recommend the use of set -e are IMHO a bit off the era mark. The recommendations imply that failing silently is a Good Thing era and that not handling errors sensibly is okay in shell scripts. Really? If you do not set -e, it is easier to handle errors? How is that? Withiut set -e we may never even know there is an error era In summary, relying on set -e to trap your errors for you era results in counter-intuitive behavior from the end user's era perspective. set -e does not, in the normal sense of the word, trap errors. It causes your script to handle errors that would otherwise be missed. So, set -e actually detects error otherwise missed, and while you say you want errors detected and handled, you are actually making the situation worse. era If the init.d script just runs and doesn't tell you era the program you wanted to start is not available, is that good era behavior? Indeed. It is also required behaviour. I may have removed (put not purged) the package, and would not like the init script to bitch and moan about it. era If the script just dies silently when your disk fills era up, is that good behavior? No, these errors should be trapped era and at least result in a warning message. I think set -e is orthogonal to error handling. using set -e makes one handle the errors -- for set -e does end execution with an failed status on error. era (For example, I have filed a bug against e.g. the `bug' package for an era issue which is more or less caused by the present policy; see bug 76127. I suspect there will be many more which just wait to be era discovered.) Well, it would be nice to handle all possible errors, yes. But in this case it was not a set -e that caused the problem, it was the fact that the result was indistinguishable from a user not adding anything to the report. Having file systems full is an exceptional condition, and like all unusual error conditions, may not be fully detected. Removing error detection with set -e makes things worse. era As a proposed fix, I have reworded some parts of the policy, as era included in the patch below. This modifies the should and adds a era may, with some related changes in earlier sections of the manual. I era also took the liberty to add comments to the /etc/init.d/bind example era where it breaks the new recommendation. And would make policy inconsistent with itself. manoj -- Date: 28 Mar 90 18:06:57 GMT From: [EMAIL PROTECTED] (Randal Schwartz) $_ = Just a sed user,;s/a/another/;s/sed/Perl/;s/user/hacker/;print 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 -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
Bug#139957: period at the end of short description?
On Tue, Mar 26, 2002 at 01:10:14AM -0500, Colin Walters wrote: cd /tmp/ diff -u -L /usr/share/doc/debian-policy/policy.sgml.gz -L /tmp/policy.sgml.new /tmp/jka-com6962AcG /tmp/policy.sgml.new --- /usr/share/doc/debian-policy/policy.sgml.gz +++ /tmp/policy.sgml.new @@ -2397,7 +2397,9 @@ p The single line synopsis should be kept brief - certainly - under 80 characters. + under 80 characters. This should be a sentence fragment + which summarizes the key features provided by the package. + It should not end in a full stop (`.'). /p p I second this. We should also discourage capitalization of the first letter in a package description. (I.e., don't make it a capital letter if it wouldn't be one in the middle of a sentence.) -- G. Branden Robinson| Never attribute to malice that Debian GNU/Linux | which can be adequately explained [EMAIL PROTECTED] | by stupidity. http://people.debian.org/~branden/ | pgpH4QjJI4nE3.pgp Description: PGP signature
Bug#139957: period at the end of short description?
On Tue, Mar 26, 2002 at 08:43:02AM -0600, Manoj Srivastava wrote: Colin == Colin Walters [EMAIL PROTECTED] writes: Colin Hi, this is not a major problem, but I'd like to see a bit more Colin consistency among the package descriptions. The attached patch should Colin be self-explanatory. A quick analysis of the Packages file suggests Colin there is already a rough consensus in agreement. I formally object to this. Yay. Woo. Why should the short description not be a full sentence? Because making it just a phrase is briefer and conveys the same information. There's a lot of stuff to read through when looking through dselect, and the more we can minimise that the better. Why are we adding useless bloat to policy? This does not seem appropriate for policy anyway (there is no technical reason for not including a period, nor has there been any justification for doing it this way). Even if it were justified (I fail to see how), policy is not a best practices document. Says who? Section 5.7.1 seems pretty much `best practices for writing descriptions', eg. IMO, what policy is is a means of recording the current consensus on packaging issues amongst developers. It's necessary to have that written down somewhere rather than in everyone's heads, since there's so much of it and it's too easy to forget. Policy is also not a stick to shake at developers after they close bugs that you reported on the issue. No, it's a tool to resolve confusion amongst developers: Descriptions should be short and not include useless words or Descriptions should make grammatically correct sentences. It is equally likely that the better thing to do would be to require all short descriptions to have a ending period (indeed, this shall be my counter GR). You want to inflate this to GR? Don't you have more useful things you could be doing? Cheers, aj -- Anthony Towns [EMAIL PROTECTED] http://azure.humbug.org.au/~aj/ I don't speak for anyone save myself. GPG signed mail preferred. ``Debian: giving you the power to shoot yourself in each toe individually.'' -- with kudos to Greg Lehey pgpmPozu62wGF.pgp Description: PGP signature
Bug#139957: period at the end of short description?
Colin Walters wrote: p The single line synopsis should be kept brief - certainly - under 80 characters. + under 80 characters. This should be a sentence fragment + which summarizes the key features provided by the package. + It should not end in a full stop (`.'). /p I can't second this because I think there can be cases where it makes sense to put a complete sentence in a short description, and there is no reason to outright prohibit those cases. I would be much happier with something that said, If your short description is not a complete sentence, do not end it with a period.. -- see shy jo -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of unsubscribe. Trouble? Contact [EMAIL PROTECTED]
