[pkgsrc/trunk]: pkgsrc/pkgtools/pkglint/files Added explanations for all warn...

[rillig <rillig%pkgsrc.org@localhost>]

details:   https://anonhg.NetBSD.org/pkgsrc/rev/f143c9196bb9
branches:  trunk
changeset: 556645:f143c9196bb9
user:      rillig <rillig%pkgsrc.org@localhost>
date:      Wed Mar 25 14:12:58 2009 +0000

description:
Added explanations for all warnings that currently appear in wip/dcc.

diffstat:

 pkgtools/pkglint/files/pkglint.pl |  35 ++++++++++++++++++++++++++++++++++-
 1 files changed, 34 insertions(+), 1 deletions(-)

diffs (92 lines):

diff -r 5019c4905531 -r f143c9196bb9 pkgtools/pkglint/files/pkglint.pl
--- a/pkgtools/pkglint/files/pkglint.pl Wed Mar 25 14:12:04 2009 +0000
+++ b/pkgtools/pkglint/files/pkglint.pl Wed Mar 25 14:12:58 2009 +0000
@@ -1,5 +1,5 @@
 #! @PERL@
-# $NetBSD: pkglint.pl,v 1.804 2009/03/22 05:57:40 rillig Exp $
+# $NetBSD: pkglint.pl,v 1.805 2009/03/25 14:12:58 rillig Exp $
 #
 
 # pkglint - static analyzer and checker for pkgsrc packages
@@ -2532,6 +2532,7 @@
        $relpath =~ s,\$\{PHPPKGSRCDIR\},../../lang/php5,;
        $relpath =~ s,\$\{SUSE_DIR_PREFIX\},suse91,;
        $relpath =~ s,\$\{PYPKGSRCDIR\},../../lang/python23,;
+       $relpath =~ s,\$\{FILESDIR\},$filesdir, if defined($filesdir);
        if ($adjust_depth && $relpath =~ m"^\.\./\.\./([^.].*)$") {
                $relpath = "${cur_pkgsrcdir}/$1";
        }
@@ -3507,6 +3508,11 @@
 
        if ($line->text =~ /\s+$/) {
                $line->log_note("Trailing white-space.");
+               $line->explain_note(
+"When a line ends with some white-space, that space is in most cases",
+"irrelevant and can be removed, leading to a \"normal form\" syntax.",
+"",
+"Note: This is mostly for aesthetic reasons.");
                $line->replace_regex(qr"\s+\n$", "\n");
        }
 }
@@ -3933,6 +3939,12 @@
        assert(defined($mkctx_build_defs), "The build_defs variable must be defined here.");
        if (exists(get_userdefined_variables()->{$varname}) && !exists(get_system_build_defs()->{$varname}) && !exists($mkctx_build_defs->{$varname})) {
                $line->log_warning("The user-defined variable ${varname} is used but not added to BUILD_DEFS.");
+               $line->explain_warning(
+"When a pkgsrc package is built, many things can be configured by the",
+"pkgsrc user in the mk.conf file. All these configurations should be",
+"recorded in the binary package, so the package can be reliably rebuilt.",
+"The BUILD_DEFS variable contains a list of all these user-settable",
+"variables, so please add your variable to it, too.");
        }
 }
 
@@ -5565,6 +5577,14 @@
                        # FIXME: What about these ones? They occur quite often.
                } else {
                        $opt_warn_extra and $line->log_warning("Please include \"../../mk/bsd.prefs.mk\" before using \"?=\".");
+                       $opt_warn_extra and $line->explain_warning(
+"The ?= operator is used to provide a default value to a variable. In",
+"pkgsrc, many variables can be set by the pkgsrc user in the mk.conf",
+"file. This file must be included explicitly. If a ?= operator appears",
+"before mk.conf has been included, it will not care about the user's",
+"preferences, which can result in unexpected behavior. The easiest way",
+"to include the mk.conf file is by including the bsd.prefs.mk file,",
+"which will take care of everything.");
                }
        }
 
@@ -7639,6 +7659,9 @@
                                if (defined($last_file_seen)) {
                                        if ($last_file_seen gt $text) {
                                                $line->log_warning("${text} should be sorted before ${last_file_seen}.");
+                                               $line->explain_warning(
+"For aesthetic reasons, the files in the PLIST should be sorted",
+"alphabetically.");
                                        } elsif ($last_file_seen eq $text) {
                                                $line->log_warning("Duplicate filename.");
                                        }
@@ -7663,6 +7686,11 @@
                                        # Fine.
                                } else {
                                        $opt_warn_extra and $line->log_warning("Manual page missing for bin/${basename}.");
+                                       $opt_warn_extra and $line->explain_warning(
+"All programs that can be run directly by the user should have a manual",
+"page for quick reference. The programs in the bin/ directory should have",
+"corresponding manual pages in section 1 (filename program.1), not in",
+"section 8.");
                                }
 
                        } elsif ($text =~ m"^doc/") {
@@ -7747,6 +7775,11 @@
 
                                if (!exists($all_files->{"man/man8/${binname}.8"})) {
                                        $opt_warn_extra and $line->log_warning("Manual page missing for sbin/${binname}.");
+                                       $opt_warn_extra and $line->explain_warning(
+"All programs that can be run directly by the user should have a manual",
+"page for quick reference. The programs in the bin/ directory should have",
+"corresponding manual pages in section 1 (filename program.1), not in",
+"section 8.");
                                }
 
                        } elsif ($text =~ m"^share/applications/.*\.desktop$") {