[pkgsrc/trunk]: pkgsrc/doc/guide/files Restructured the description of the fi...

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

details:   https://anonhg.NetBSD.org/pkgsrc/rev/a5961e5fa7c5
branches:  trunk
changeset: 493468:a5961e5fa7c5
user:      rillig <rillig%pkgsrc.org@localhost>
date:      Sat May 07 15:28:40 2005 +0000

description:
Restructured the description of the first two sections of the package
Makefile. Fixed some other typos. Removed the MESSAGE file of audit-
package and described how to display it. Approved by wiz.

diffstat:

 doc/guide/files/components.xml |  69 +++++++++++++++++++++++++++++------------
 doc/guide/files/faq.xml        |  52 +++++++++----------------------
 2 files changed, 63 insertions(+), 58 deletions(-)

diffs (178 lines):

diff -r 4a2d7a0aa0cd -r a5961e5fa7c5 doc/guide/files/components.xml
--- a/doc/guide/files/components.xml    Sat May 07 15:25:54 2005 +0000
+++ b/doc/guide/files/components.xml    Sat May 07 15:28:40 2005 +0000
@@ -1,4 +1,4 @@
-<!-- $NetBSD: components.xml,v 1.3 2004/12/02 22:20:34 dillo Exp $ -->
+<!-- $NetBSD: components.xml,v 1.4 2005/05/07 15:28:40 rillig Exp $ -->
 
 <chapter id="components"> <?dbhtml filename="components.html"?>
   <title>Package components - files, directories and contents</title>
@@ -11,27 +11,54 @@
     <title><filename>Makefile</filename></title>
 
     <para>Building, installation and creation of a binary package are all
-      controlled by the package's <filename>Makefile</filename>.</para>
+      controlled by the package's <filename>Makefile</filename>.
+      The <filename>Makefile</filename> describes various things about
+      a package, for example from where to get it, how to configure,
+      build, and install it.
+    </para>
+
+    <para>A package <filename>Makefile</filename> contains several
+     sections that describe the package.</para>
+
+    <para>In the first section there are the following variables, which
+      should appear exactly in the order given here.
+      <itemizedlist>
+
+      <listitem><para><varname>DISTNAME</varname> is the basename of the
+      distribution file to be downloaded from the package's
+      website.</para></listitem>
+
+      <listitem><para><varname>PKGNAME</varname> is the name of the package,
+      as used by pkgsrc. You only need to provide it if it differs from
+      DISTNAME. Usually it is the directory name together with the
+      version number.</para></listitem>
 
-    <para>There is a <filename>Makefile</filename> for each package.
-      This file includes the standard
-      <filename>bsd.pkg.mk</filename> file (referenced as
-      <filename>../../mk/bsd.pkg.mk</filename>), which sets all the
-      definitions and actions necessary for the package to compile and
-      install itself. The mandatory variables are the
-      <varname>DISTNAME</varname> which specifies the base name
-      of the distribution file to be downloaded from the site on the
-      Internet, <varname>MASTER_SITES</varname> which specifies that site,
-      <varname>CATEGORIES</varname> which denotes the
-      categories into which the package falls, <varname>PKGNAME</varname>
-      which is the name of the package, the <varname>MAINTAINER</varname>'s
-      name, and the <varname>COMMENT</varname> variable, which should
-      contain a one-line description of the package (the package name
-      should not appear, it will be added automatically). The maintainer
-      variable is there so that anyone who quibbles with the (always
-      completely correct) decisions taken by the guy who maintains the
-      package can complain vigorously, or send chocolate as a sign of
-      appreciation.</para>
+      <listitem><para><varname>CATEGORIES</varname> is a list of categories
+      which the package fits in. You can choose any of the top-level
+      directories of pkgsrc for it.</para></listitem>
+
+      <listitem><para><varname>MASTER_SITES</varname> is a list of URLs where
+      the distribution files can be downloaded. Each URL must end with a
+      slash.</para></listitem>
+
+      </itemizedlist>
+    </para>
+
+    <para>The second section contains the following variables.
+      <itemizedlist>
+
+      <listitem><para><varname>MAINTAINER</varname> is the mail address of the
+      package's maintainer, which is the person you can contact when the
+      package does not work.</para></listitem>
+
+      <listitem><para><varname>HOMEPAGE</varname> is a URL where users can
+      find more information about the package.</para></listitem>
+
+      <listitem><para><varname>COMMENT</varname> is a one-line comment about
+      the purpose of the package.</para></listitem>
+
+      </itemizedlist>
+    </para>
 
     <para>The <varname>MASTER_SITES</varname> may be set to one of the
       predefined sites:</para>
diff -r 4a2d7a0aa0cd -r a5961e5fa7c5 doc/guide/files/faq.xml
--- a/doc/guide/files/faq.xml   Sat May 07 15:25:54 2005 +0000
+++ b/doc/guide/files/faq.xml   Sat May 07 15:28:40 2005 +0000
@@ -1,4 +1,4 @@
-<!-- $NetBSD: faq.xml,v 1.5 2005/02/24 14:24:32 jschauma Exp $ -->
+<!-- $NetBSD: faq.xml,v 1.6 2005/05/07 15:28:40 rillig Exp $ -->
 
 <chapter id="faq"> <?dbhtml filename="faq.html"?>
   <title>Frequently Asked Questions</title>
@@ -348,7 +348,7 @@
     <para> The answer here is to do a <command>make
       fetch-list</command> in <filename>/usr/pkgsrc</filename> or one
       of it's subdirectories, carry the resulting list to your machine
-      at work/school and use it there If you don't have a
+      at work/school and use it there. If you don't have a
       NetBSD-compatible ftp(1) (like lukemftp) at work, don't forget
       to set <varname>FETCH_CMD</varname> to something that fetches a
       URL: </para>
@@ -388,8 +388,9 @@
     <para> When compiling the <pkg>pkgtools/pkg_install</pkg> package,
       you get the error from make that it doesn't know how to make
       <filename>/usr/share/tmac/tmac.andoc</filename>? This indicates
-      that you don't have installed the <quote>text</quote> set on
-      your machine (nroff, ...). It is recommended to do that to
+      that you don't have installed the <quote>text</quote> set
+      (nroff, ...) from the NetBSD base distribution on
+      your machine. It is recommended to do that to
       format manpages.  </para>
 
     <para> In the case of the <pkg>pkgtools/pkg_install</pkg> package,
@@ -430,8 +431,8 @@
       <filename>/etc/mk.conf</filename>: </para>
 
     <programlisting>
-        .if exists(/usr/pkg/bin/sudo)
-        SU_CMD=/usr/pkg/bin/sudo /bin/sh -c
+        .if exists(${LOCALBASE}/bin/sudo)
+        SU_CMD=${LOCALBASE}/bin/sudo /bin/sh -c
         .endif
     </programlisting>
 </sect1>
@@ -573,44 +574,21 @@
 
       <listitem>
         <para> <quote>audit-packages</quote>, an easy way to audit the
-          current machine, checking       each vulnerability which is
-          known. If a vulnerable package is       installed, it will
-          be shown by output to stdout, including a       description
+          current machine, checking each vulnerability which is
+          known. If a vulnerable package is installed, it will
+          be shown by output to stdout, including a description
           of the type of vulnerability, and a URL containing more
           information.  </para> 
       </listitem>
     </orderedlist>
 
-    <para> Use of the audit-packages package is strongly recommended!
+    <para> Use of the <pkg>security/audit-packages</pkg> package is
+        strongly recommended!
+        After <quote>audit-packages</quote> is installed, please read
+        the package's message, which you can get by running
+        <userinput>pkg_info -D audit-package</userinput>.
       </para>
 
-    <para> The following message is displayed as part of the
-      audit-packages installation procedure: </para>
-
-    <screen>
-===========================================================================
-$NetBSD: faq.xml,v 1.5 2005/02/24 14:24:32 jschauma Exp $
-
-You may wish to have the vulnerabilities file downloaded daily so that
-it remains current.  This may be done by adding an appropriate entry
-to the root users crontab(5) entry.  For example the entry
-
-# download vulnerabilities file
-0 3 * * * ${PREFIX}/sbin/download-vulnerability-list >/dev/null 2>&1
-
-will update the vulnerability list every day at 3AM. You may wish to do
-this more often than once a day.
-
-In addition, you may wish to run the package audit from the daily
-security script.  This may be accomplished by adding the following
-lines to /etc/security.local
-
-if [ -x ${PREFIX}/sbin/audit-packages ]; then
-          ${PREFIX}/sbin/audit-packages
-fi
-
-===========================================================================
-    </screen>
   </sect1>
 
 </chapter>