Added the chapter ``Design goals''.

2 files changed, 94 insertions, 1 deletions

diff --git a/pkgtools/pkglint/files/doc/chap.design.xml b/pkgtools/pkglint/files/doc/chap.design.xml
new file mode 100644
index 00000000000..2f18b875fb3
--- /dev/null
+++ b/pkgtools/pkglint/files/doc/chap.design.xml
@@ -0,0 +1,91 @@
+<!-- $NetBSD: chap.design.xml,v 1.1 2006/02/28 11:40:15 rillig Exp $ -->
+
+<chapter id="design">
+<title>Design goals</title>
+
+	<para>&pkglint; should be simple to use. It should be consistent
+	and predictable in what it does. The diagnostics should be
+	understandable. The number of false positive and false negative
+	diagnostics should be minimal.</para>
+
+<sect1 id="design.simple-to-use">
+<title>Simple to use</title>
+
+	<para><emphasis>Requirement:</emphasis> Using &pkglint; should
+	not require any knowledge about obscure command line options or
+	hidden features.</para>
+
+	<para>Calling &pkglint; without options gives a useful amount of
+	warnings. No further knowledge is needed. Users that are
+	accustomed to GNU software will quickly find the
+	<literal>--help</literal> command line option, which gives a
+	quite verbose description of the available options. Users that
+	know the GNU compilers will easily remember the
+	<literal>-W</literal> class of options, especially
+	<literal>-Wall</literal>. Other than with the GNU compilers, the
+	latter option enables really <emphasis>all</emphasis> warnings
+	that are intended to be user-visible.</para>
+
+	<para>The command line options come in two flavors: short and
+	long options. The long options are meant to be used when
+	explaining them to others, while the short options are meant to
+	be used when invoking &pkglint; in an interactive shell.</para>
+
+</sect1>
+<sect1 id="design.consistent-and-predictable">
+<title>Consistent and predictable</title>
+
+	<para><emphasis>Requirement:</emphasis> &pkglint; should behave
+	such that the user quickly gets an impression about what
+	&pkglint; does. This impression should be persistent, that is,
+	the output format for diagnostics should be stable over time,
+	and diagnostic messages should not be changed without
+	reason.</para>
+
+	<para>There are only two cases of what the output of
+	&pkglint; is. One is a single line containing the text
+	<quote>looks fine.</quote>, the other is a list of diagnostics,
+	followed by a summary on the number of diagnostics.</para>
+
+	<para>If no warnings are printed, the single line <quote>looks
+	fine.</quote> gives a little motivation to the user. This
+	message is one of the few things that have been kept in
+	&pkglint; since it has been adopted from FreeBSD. It just makes
+	pkglint a more friendly tool. :)</para>
+
+</sect1>
+<sect1 id="design.understandable">
+<title>Understandable diagnostics</title>
+
+	<para><emphasis>Requirement:</emphasis> The diagnostics are
+	intended to help the user in writing better package definitions.
+	They should use an unambiguous, clear language and point
+	directly to the problem. If possible, they should include a hint
+	on how the problem can be fixed properly.</para>
+
+</sect1>
+<sect1 id="design.false-diagnostics">
+<title>False diagnostics</title>
+
+	<para><emphasis>Requirement:</emphasis> The number of
+	<firstterm>false positives</firstterm>, that is diagnostics
+	where no problem actually exists, should be minimal. On the
+	other hand, &pkglint; should detect as many problems as
+	possible. If it fails to detect a problem, this is called a
+	<firstterm>false negative</firstterm>.</para>
+
+	<para>Currently, there are very few false positives. The way
+	&pkglint; parses the files is already close to the way
+	<command>make</command> and <command>sh</command> parse them, so
+	the structure of the files is modelled quite well.</para>
+
+	<para>Since &pkglint; is also very strict in what it accepts,
+	many problems can already be detected. But since the pkgsrc
+	developers are quite creative when it comes to solving problems,
+	&pkglint; cannot detect everything. After all, the language used
+	to define packages is turing-complete, so it cannot be decided
+	in every case whether a package is valid or not. Luckily, most
+	packages are quite simple.</para>
+
+</sect1>
+</chapter>
diff --git a/pkgtools/pkglint/files/doc/pkglint.xml b/pkgtools/pkglint/files/doc/pkglint.xml
index 133dbd48309..f036b5d3503 100644
--- a/pkgtools/pkglint/files/doc/pkglint.xml
+++ b/pkgtools/pkglint/files/doc/pkglint.xml
@@ -7,12 +7,13 @@
 
 	<!ENTITY chap.intro SYSTEM "chap.intro.xml">
 	<!ENTITY chap.defs SYSTEM "chap.defs.xml">
+	<!ENTITY chap.design SYSTEM "chap.design.xml">
 	<!ENTITY chap.types SYSTEM "chap.types.xml">
 	<!ENTITY chap.code SYSTEM "chap.code.xml">
 	<!ENTITY chap.statemachines SYSTEM "chap.statemachines.xml">
 ]>
 
-<!-- $NetBSD: pkglint.xml,v 1.1 2006/02/26 23:38:07 rillig Exp $ -->
+<!-- $NetBSD: pkglint.xml,v 1.2 2006/02/28 11:40:15 rillig Exp $ -->
 
 <book>
 <title>Design and implementation of &pkglint;</title>
@@ -27,6 +28,7 @@
 
 &chap.intro;
 &chap.defs;
+&chap.design;
 &chap.types;
 &chap.code;
 &chap.statemachines;