Package: lintian Version: 1.23.16 Severity: wishlist Tags: patch Hi, Most of the debconf templates are not following the recommandations made by the developers-reference (see section 6.5 especially). For example, we may have different prompt such as "What is your password?", "Please enter your password", "Password?", etc. in different packages, while the developers-reference recommands to use "Password:". The attached patches add an initial set of checks (which can of course be improved) for accordance with the developers-reference. Most of the descriptions in debconf.desc.diff are only copy/pasted from the dev-ref. I have tried to make the addition of new checks as easy as possible. If you need help to understand this patch, please do not hesitate to ask me. You may want to see the results (or a list of packages to test these checks): they are available at http://haydn.debian.org/~thuriaux-guest/templates/ Note that theses results are based on the source packages, while the lintian checks added by these patches are made on the binary packages, so they may differ a little. Cheers, -- Thomas Huriaux
--- debconf 2006-03-16 04:32:14.000000000 +0100
+++ debconf.new 2006-04-12 15:40:12.000000000 +0200
@@ -64,6 +64,118 @@
return unless $seenconfig or $seentemplates;
+# Definition of unitary tests for debconf writing style
+
+my %testSuite = (
+ "isNotAPrompt" => \&isNotAPrompt,
+ "isAFullSentence" => \&isAFullSentence,
+ "isNotATitle" => \&isNotATitle,
+ "isNotAQuestion" => \&isNotAQuestion,
+ "shortIsTooLong" => \&shortIsTooLong,
+ "extendedIsTooLong" => \&extendedIsTooLong,
+ "usingYesOrNo" => \&usingYesOrNo,
+ "isPersonal" => \&isPersonal,
+ "containsAQuestion" => \&containsAQuestion
+);
+
+my %testsDescription;
+@{$testsDescription{'string'}} = ('isNotAPrompt','isAFullSentence');
+@{$testsDescription{'note'}} = ('isNotATitle');
+@{$testsDescription{'select'}} = ('isNotAPrompt', 'isAFullSentence');
+@{$testsDescription{'boolean'}} = ('isNotAQuestion');
+@{$testsDescription{'password'}} = ('isNotAPrompt', 'isAFullSentence');
+@{$testsDescription{'multiselect'}} = ('isNotAPrompt', 'isAFullSentence');
+@{$testsDescription{'text'}} = ();
+@{$testsDescription{'error'}} = ();
+
+my @globalDescriptionTests = ('shortIsTooLong');
+
+my %testsExtended;
+@{$testsExtended{'string'}} = ();
+@{$testsExtended{'note'}} = ();
+@{$testsExtended{'select'}} = ();
+@{$testsExtended{'boolean'}} = ('containsAQuestion');
+@{$testsExtended{'password'}} = ();
+@{$testsExtended{'multiselect'}} = ();
+@{$testsExtended{'text'}} = ();
+@{$testsExtended{'error'}} = ();
+
+my @globalExtendedTests = ('extendedIsTooLong');
+
+my @globalTests = ('isPersonal', 'usingYesOrNo');
+
+# unitary tests
+sub isNotAPrompt {
+ if ($_[0] !~ m/.*:$/) {
+ tag "malformed-prompt-in-templates", "";
+ }
+}
+
+sub isNotATitle {
+ if ($_[0] =~ m/.*[.?;:]$/) {
+ tag "malformed-title-in-templates", "";
+ }
+}
+
+sub isNotAQuestion {
+ if ($_[0] !~ m/.*\?/) {
+ tag "malformed-question-in-templates", "";
+ }
+}
+
+sub containsAQuestion {
+ if ($_[0] =~ m/\?/) {
+ tag "using-question-in-extended-description-in-templates", "";
+ }
+}
+
+sub isAFullSentence {
+ if ($_[0] =~ m/^(Please|Cho+se|Enter|Select|Specify|Give)/) {
+ tag "using-imperative-form-in-templates", "";
+ }
+}
+
+sub isPersonal {
+ if ($_[0] =~ m/(^(I|My|We|Our|Ours|Me)| (I|my|we|our|ours|mine|myself|ourself|me|us)) /) {
+ tag "using-first-person-in-templates", "";
+ }
+}
+
+sub usingYesOrNo {
+ if ($_[0] =~ m/[ '"]([Yy]es)[ '",.]/) {
+ tag "making-assumptions-about-interfaces-in-templates", "";
+ }
+}
+
+sub shortIsTooLong {
+ if (length($_[0]) > 75) {
+ tag "too-long-short-description-in-templates", "";
+ }
+}
+
+sub extendedIsTooLong {
+ my $lines = 0;
+ foreach my $string (split ("\n",$_[0])) {
+ while (length($string) > 75) {
+ my $pos = rindex($string," ",75);
+ if ($pos == -1) {
+ $pos = index($string," ");
+ }
+ if ($pos == -1) {
+ $string = "";
+ } else {
+ $string = substr($string,$pos+1);
+ $lines++;
+ }
+ }
+ $lines += 1;
+ }
+ if ($lines > 12) {
+ tag "too-long-extended-description-in-templates", "";
+ }
+}
+
+
# parse depends info for later checks
# Consider every package to depend on itself.
@@ -224,6 +336,15 @@
}
}
}
+ # Check the debconf writing style
+ $template->{description} =~ m/^([^\n]*)\n(.*)$/s;
+ my ($shortDescription, $extendedDescription) = ($1, $2);
+ foreach my $test (@{$testsDescription{$template->{type}}}, @globalTests, @globalDescriptionTests) {
+ $testSuite{$test}->($shortDescription);
+ }
+ foreach my $test (@{$testsExtended{$template->{type}}}, @globalTests, @globalExtendedTests) {
+ $testSuite{$test}->($extendedDescription);
+ }
}
# Check the maintainer scripts.
--- debconf.desc 2006-03-16 04:32:14.000000000 +0100
+++ debconf.desc.new 2006-04-12 15:40:18.000000000 +0200
@@ -186,3 +186,69 @@
Since SETTITLE was added after debconf-2.0, one cannot use the normal
debconf-2.0 alternative to allow for cdebconf or other implementations.
Instead, use <tt>debconf (>= 1.3.22) | cdebconf (>= 0.43)</tt>.
+
+Tag: malformed-prompt-in-templates
+Type: warning
+Info: The short description of a select, multiselect, string and password
+ debconf template is a prompt and NOT a title. Avoid question style
+ prompts ("IP Address?") in favour of "opened" prompts ("IP address:").
+ The use of colons is recommended.
+
+Tag: malformed-title-in-templates
+Type: warning
+Info: The short description of a note debconf template should be
+ considered to be a *title*.
+
+Tag: malformed-question-in-templates
+Type: warning
+Info: The short description of a boolean debconf template should be
+ phrased in the form of a question which should be kept short and should
+ generally end with a question mark. Terse writing style is permitted and
+ even encouraged if the question is rather long.
+
+Tag: using-question-in-extended-description-in-templates
+Type: warning
+Info: The extended description of a debconf template should NOT include a
+ question. The interaction with the user should happen only in the short
+ description.
+
+Tag: using-imperative-form-in-templates
+Type: warning
+Info: Do NOT use useless imperative constructions such as "Please choose...",
+ "Enter...". Users are clever enough to figure out they have to choose
+ something...
+
+Tag: using-first-person-in-templates
+Type: warning
+Info: You should avoid the use of first person ("I will do this..." or
+ "We recommend..."). The computer is not a person and the Debconf
+ templates do not speak for the Debian developers. You should use neutral
+ construction and often the passive form. Those of you who already wrote
+ scientific publications, just write your templates like you would write
+ a scientific paper.
+
+Tag: making-assumptions-about-interfaces-in-templates
+Type: warning
+Info: Templates text should not make reference to widgets belonging to
+ some debconf interfaces. Sentences like "If you answer Yes..." have no
+ meaning for users of graphical interfaces which use checkboxes for
+ boolean questions.
+ .
+ String templates should also avoid mentioning the default values in their
+ description. First, because this is redundant with the values seen by the
+ users. Also, because these default values may be different from the
+ maintainer choices (for instance, when the debconf database was
+ preseeded).
+ .
+ More generally speaking, try to avoid referring to user actions. Just
+ give facts.
+
+Tag: too-long-short-description-in-templates
+Type: warning
+Info: The short description should be limited to 75 chars to fit on one
+ line on a basic 80x25 terminal.
+
+Tag: too-long-extended-description-in-templates
+Type: warning
+Info: The extended description should be limited to 12 lines of 75 chars
+ to fit on a basic 80x25 terminal.
Attachment:
signature.asc
Description: Digital signature