lintian: r662 - in trunk: checks debian testset testset/debconf/debian
Author: rra
Date: 2006-05-07 04:03:50 +0200 (Sun, 07 May 2006)
New Revision: 662
Modified:
trunk/checks/debconf
trunk/checks/debconf.desc
trunk/debian/changelog
trunk/testset/debconf/debian/debconf-test.templates
trunk/testset/tags.debconf
Log:
* checks/debconf{.desc,}:
+ [RA] Add checks for the Developer's Reference guidelines for debconf
templates. Based on a patch by Thomas Huriaux. (Closes: #362145)
Modified: trunk/checks/debconf
===================================================================
--- trunk/checks/debconf 2006-05-06 21:10:50 UTC (rev 661)
+++ trunk/checks/debconf 2006-05-07 02:03:50 UTC (rev 662)
@@ -227,6 +227,68 @@
}
}
}
+
+ # Check the description against the best practices in the Developer's
+ # Reference.
+ $template->{description} =~ m/^([^\n]*)\n(.*)$/s;
+ my ($short, $extended) = ($1, $2);
+ unless (defined $short) {
+ $short = $template->{description};
+ }
+ my $isprompt = grep { $_ eq $template->{type} } qw(string select password multiselect);
+ if ($isprompt) {
+ if ($short !~ m/:$/) {
+ tag "malformed-prompt-in-templates", $template->{template};
+ }
+ if ($short =~ /^(Please|Cho+se|Enter|Select|Specify|Give)/) {
+ tag "using-imperative-form-in-templates", $template->{template};
+ }
+ }
+ if ($template->{type} eq 'boolean') {
+ if ($short !~ /\?/) {
+ tag "malformed-question-in-templates", $template->{template};
+ }
+ if (defined ($extended) && $extended =~ /\?/) {
+ tag "using-question-in-extended-description-in-templates", $template->{template};
+ }
+ }
+ if ($template->{type} eq 'note') {
+ if ($short =~ /[.?;:]$/) {
+ tag "malformed-title-in-templates", $template->{template};
+ }
+ }
+ if (length ($short) > 75) {
+ tag "too-long-short-description-in-templates", $template->{template};
+ }
+ if ($template->{description} =~ /(\A|\s)(I|[Mm]y|[Ww]e|[Oo]ur|[Oo]urs|mine|myself|ourself|me|us) /) {
+ tag "using-first-person-in-templates", $template->{template};
+ }
+ if ($template->{description} =~ /[ \'\"]([Yy]es)[ \'\",.]/) {
+ tag "making-assumptions-about-interfaces-in-templates", $template->{template};
+ }
+
+ # Check whether the extended description is too long.
+ if ($extended) {
+ my $lines = 0;
+ for my $string (split ("\n", $extended)) {
+ while (length ($string) > 80) {
+ my $pos = rindex ($string, ' ', 80);
+ if ($pos == -1) {
+ $pos = index ($string, ' ');
+ }
+ if ($pos == -1) {
+ $string = '';
+ } else {
+ $string = substr ($string, $pos + 1);
+ $lines++;
+ }
+ }
+ $lines++;
+ }
+ if ($lines > 20) {
+ tag "too-long-extended-description-in-templates", $template->{template};
+ }
+ }
}
# Check the maintainer scripts.
Modified: trunk/checks/debconf.desc
===================================================================
--- trunk/checks/debconf.desc 2006-05-06 21:10:50 UTC (rev 661)
+++ trunk/checks/debconf.desc 2006-05-07 02:03:50 UTC (rev 662)
@@ -186,3 +186,70 @@
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.
+Ref: devref 6.5.4.2
+
+Tag: malformed-title-in-templates
+Type: warning
+Info: The short description of a note debconf template should be written
+ as a title and therefore should not end with a period, question mark,
+ colon, or semicolon.
+Ref: devref 6.5.4.2.4
+
+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.
+Ref: devref 6.5.4.2.2
+
+Tag: using-question-in-extended-description-in-templates
+Type: warning
+Info: The extended description of a boolean debconf template should not
+ include a question.
+Ref: devref 6.5.4.2.2
+
+Tag: using-imperative-form-in-templates
+Type: warning
+Info: Do not use useless imperative constructions such as "Please choose...",
+ "Enter...". The interface will make it obvious that the user needs to
+ choose or enter something.
+Ref: devref 6.5.4.2
+
+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.
+Ref: devref 6.5.2.5
+
+Tag: making-assumptions-about-interfaces-in-templates
+Type: warning
+Info: Template 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.
+Ref: devref 6.5.2.4
+
+Tag: too-long-short-description-in-templates
+Type: warning
+Info: The short description should be kept short (50 characters or so) so
+ that it may be accomodated by most debconf interfaces. Keeping it short
+ also helps translators, as usually translations tend to end up being
+ longer than the original.
+Ref: devref 6.5.3.2
+
+Tag: too-long-extended-description-in-templates
+Type: warning
+Info: Some debconf interfaces cannot deal very well with descriptions of
+ more than about 20 lines, so try to keep the extended description below
+ this limit.
+Ref: devref 6.5.3.2
Modified: trunk/debian/changelog
===================================================================
--- trunk/debian/changelog 2006-05-06 21:10:50 UTC (rev 661)
+++ trunk/debian/changelog 2006-05-07 02:03:50 UTC (rev 662)
@@ -1,5 +1,8 @@
lintian (1.23.20) UNRELEASED; urgency=low
+ * checks/debconf{.desc,}:
+ + [RA] Add checks for the Developer's Reference guidelines for debconf
+ templates. Based on a patch by Thomas Huriaux. (Closes: #362145)
* checks/fields{.desc,}:
+ [RA] xfonts-encodings is also not an xfont package. Thanks, Drew
Parsons. (Closes: #365503)
@@ -50,7 +53,7 @@
+ [RA] Update standards version to 3.7.2 (no changes required).
+ [RA] Update description to note calibration for Policy 3.7.2.
- -- Russ Allbery <rra@debian.org> Sat, 6 May 2006 14:08:15 -0700
+ -- Russ Allbery <rra@debian.org> Sat, 6 May 2006 18:20:12 -0700
lintian (1.23.19) unstable; urgency=low
Modified: trunk/testset/debconf/debian/debconf-test.templates
===================================================================
--- trunk/testset/debconf/debian/debconf-test.templates 2006-05-06 21:10:50 UTC (rev 661)
+++ trunk/testset/debconf/debian/debconf-test.templates 2006-05-07 02:03:50 UTC (rev 662)
@@ -6,3 +6,44 @@
Type: multiselect
__Choices: foo, bar, boo
_Description: test comma usages in choices fields
+
+Template: debconf/testboolean
+Type: boolean
+_Description: Enter yes or no:
+ Do you want to answer this question?
+
+Template: debconf/teststring
+Type: string
+_Description: This template goes on and on.
+ This template goes on and on.
+ This template goes on and on.
+ This template goes on and on.
+ This template goes on and on.
+ This template goes on and on.
+ This template goes on and on.
+ This template goes on and on.
+ This template goes on and on.
+ This template goes on and on.
+ This template goes on and on.
+ This template goes on and on.
+ This template goes on and on.
+ This template goes on and on.
+ This template goes on and on.
+ This template goes on and on.
+ This template goes on and on.
+ This template goes on and on.
+ This template goes on and on.
+ This template goes on and on.
+ This template goes on and on.
+ This template goes on and on.
+
+Template: debconf/testnote
+Type: note
+Description: This should be a title and not a really long sentence that ends in a regular period.
+
+Template: debconf/1st-person
+Type: select
+__Choices: one, two
+_Description: Select one of these:
+ I am a stupid test of first-person syntax that tells you to select yes
+ even though yes isn't an option in this prompt.
Modified: trunk/testset/tags.debconf
===================================================================
--- trunk/testset/tags.debconf 2006-05-06 21:10:50 UTC (rev 661)
+++ trunk/testset/tags.debconf 2006-05-07 02:03:50 UTC (rev 662)
@@ -12,6 +12,17 @@
W: debconf-test-noscripts: old-fsf-address-in-copyright-file
W: debconf-test-noscripts: postinst-does-not-load-confmodule
W: debconf-test-noscripts: postrm-does-not-purge-debconf
+W: debconf-test: making-assumptions-about-interfaces-in-templates debconf/1st-person
+W: debconf-test: making-assumptions-about-interfaces-in-templates debconf/testboolean
+W: debconf-test: malformed-prompt-in-templates debconf/testmulti
+W: debconf-test: malformed-prompt-in-templates debconf/teststring
+W: debconf-test: malformed-question-in-templates debconf/testboolean
+W: debconf-test: malformed-title-in-templates debconf/testnote
W: debconf-test: old-fsf-address-in-copyright-file
W: debconf-test: partially-translated-question debconf/testmulti de.utf-8
+W: debconf-test: too-long-extended-description-in-templates debconf/teststring
+W: debconf-test: too-long-short-description-in-templates debconf/testnote
+W: debconf-test: using-first-person-in-templates debconf/1st-person
+W: debconf-test: using-imperative-form-in-templates debconf/1st-person
+W: debconf-test: using-question-in-extended-description-in-templates debconf/testboolean
W: debconf-udeb udeb: missing-debconf-dependency
Reply to: