Document SVR4_PKGNAME; improve pkgdiff description; document

PATCHDIR, default setting of MESSAGE_SUBST, and FILESDIR.
Reindent.

1 files changed, 422 insertions, 371 deletions

diff --git a/doc/guide/files/components.xml b/doc/guide/files/components.xml
index 0d4cca769b1..906b426e001 100644
--- a/doc/guide/files/components.xml
+++ b/doc/guide/files/components.xml
@@ -1,260 +1,290 @@
-<!-- $NetBSD: components.xml,v 1.28 2006/09/03 00:20:49 wiz Exp $ -->
+<!-- $NetBSD: components.xml,v 1.29 2006/09/10 19:11:15 wiz Exp $ -->
 
 <chapter id="components"> <?dbhtml filename="components.html"?>
-  <title>Package components - files, directories and contents</title>
-
-  <para>  Whenever you're preparing a package, there are a number of
-    files involved which are described in the following
-    sections. </para>
-
-  <sect1 id="components.Makefile">
-    <title><filename>Makefile</filename></title>
-
-    <para>Building, installation and creation of a binary package are all
-      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. The ordering and
-    grouping of variables is mostly historical and has no further
-    meaning.</para>
-
-      <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 <varname>DISTNAME</varname>. Usually it is the directory name together
-      with the version number. It must match the regular expression
-      <varname>^[A-Za-z0-9][A-Za-z0-9-_.+]*$</varname>, that is, it
-      starts with a letter or digit, and contains only letters, digits,
-      dashes, underscores, dots and plus signs.</para></listitem>
-
-      <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>
-
-	<para>Currently the following values are available for
-	  <varname>CATEGORIES</varname>. If more than
-	  one is used, they need to be separated by spaces:</para>
-
-<programlisting>
-    archivers     cross         geography     meta-pkgs     security
-    audio         databases     graphics      misc          shells
-    benchmarks    devel         ham           multimedia    sysutils
-    biology       editors       inputmethod   net           textproc
-    cad           emulators     lang          news          time
-    chat          finance       mail          parallel      wm
-    comms         fonts         math          pkgtools      www
-    converters    games         mbone         print         x11
-</programlisting>
-	</listitem>
-
-	<listitem><para><varname>MASTER_SITES</varname>,
-	<varname>DYNAMIC_MASTER_SITES</varname>,
-	<varname>DIST_SUBDIR</varname>, <varname>EXTRACT_SUFX</varname>
-	and <varname>DISTFILES</varname> are discussed in detail in
-	<xref linkend="build.fetch"/>.</para></listitem>
-
-	</itemizedlist>
-
-    <para>The second section contains information about separately
-      downloaded patches, if any.
-      <itemizedlist>
-	<listitem><para><varname>PATCHFILES:</varname>
-	  Name(s) of additional files that contain distribution patches.
-	  There is no default. pkgsrc will look for them at
-	  <varname>PATCH_SITES</varname>.
-	  They will automatically be uncompressed before patching if
-	  the names end with <filename>.gz</filename> or
-	  <filename>.Z</filename>.</para>
-	</listitem>
-	<listitem><para><varname>PATCH_SITES</varname>:
-	  Primary location(s) for distribution patch files (see
-	  <varname>PATCHFILES</varname> below) if not found locally.</para>
-	</listitem>
-      </itemizedlist>
-    </para>
-    <para>The third section contains the following variables.
-      <itemizedlist>
-
-      <listitem><para><varname>MAINTAINER</varname> is the email address
-      of the person who feels responsible for this package, and who is
-      most likely to look at problems or questions regarding this
-      package which have been reported with &man.send-pr.1;. Other
-      developers should contact the <varname>MAINTAINER</varname> before
-      making major changes to the package. When packaging a new program,
-      set <varname>MAINTAINER</varname> to yourself. If you really can't
-      maintain the package for future updates, set it to
-      <email>pkgsrc-users@NetBSD.org</email>.</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
-      description of the package (should not include the package
-      name).</para></listitem>
-      </itemizedlist>
-    </para>
-
-    <para>Other variables that affect the build:
-      <itemizedlist>
-
-	<listitem>
-
-	  <para><varname>WRKSRC</varname>: The directory where the
-	  interesting distribution files of the package are found. The
-	  default is <filename>${WRKDIR}/${DISTNAME}</filename>, which
-	  works for most packages.</para>
-
-	  <para>If a package doesn't create a subdirectory for itself
-	  (most GNU software does, for instance), but extracts itself in
-	  the current directory, you should set <varname>WRKSRC=
-	  ${WRKDIR}</varname>.</para>
-
-	  <para>If a package doesn't create a subdirectory with the name
-	  of <varname>DISTNAME</varname> but some different name, set
-	  <varname>WRKSRC</varname> to point to the proper name in
-	  <filename>${WRKDIR}</filename>, for example <varname>WRKSRC=
-	  ${WRKDIR}/${DISTNAME}/unix</varname>. See <filename
-	  role="pkg">lang/tcl</filename> and <filename
-	  role="pkg">x11/tk</filename> for other examples.</para>
-
-	  <para>The name of the working directory created by pkgsrc is
-	  taken from the <varname>WRKDIR_BASENAME</varname> variable. By
-	  default, its value is <filename>work</filename>. If you want
-	  to use the same pkgsrc tree for building different kinds of
-	  binary packages, you can change the variable according to your
-	  needs. Two other variables handle common cases of setting
-	  <varname>WRKDIR_BASENAME</varname> individually. If
-	  <varname>OBJHOSTNAME</varname> is defined in
-	  <filename>/etc/mk.conf</filename>, the first component of the
-	  host's name is attached to the directory name. If
-	  <varname>OBJMACHINE</varname> is defined, the platform name is
-	  attached, which might look like <filename>work.i386</filename>
-	  or <filename>work.sparc</filename>.</para>
-
-	</listitem>
-      </itemizedlist>
-    </para>
-    <para>Please pay attention to the following gotchas:</para>
-
-    <itemizedlist>
-      <listitem>
-        <para>Add <varname>MANCOMPRESSED</varname> if man pages are installed in
-          compressed form by the package; see comment in
-          <filename>bsd.pkg.mk</filename>.</para>
-      </listitem>
-
-      <listitem>
-        <para>Replace <filename>/usr/local</filename> with
-          <quote>${PREFIX}</quote> in all files (see patches, below).</para>
-      </listitem>
-
-      <listitem>
-        <para>If the package installs any info files, see
-          <xref linkend="faq.info-files"/>.</para>
-      </listitem>
-
-    </itemizedlist>
-  </sect1>
+<title>Package components - files, directories and contents</title>
+
+<para>Whenever you're preparing a package, there are a number of
+files involved which are described in the following
+sections.</para>
+
+<sect1 id="components.Makefile">
+  <title><filename>Makefile</filename></title>
+
+  <para>Building, installation and creation of a binary package are all
+  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.  The order and
+  grouping of the variables is mostly historical and has no further
+  meaning.</para>
+  <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
+    <varname>DISTNAME</varname> (which is the default) is not a good
+    name for the package in pkgsrc.  Usually it is the pkgsrc
+    directory name together with the version number. It must match the
+    regular expression
+    <varname>^[A-Za-z0-9][A-Za-z0-9-_.+]*$</varname>, that is, it
+    starts with a letter or digit, and contains only letters, digits,
+    dashes, underscores, dots and plus signs.</para></listitem>
+
+    <listitem><para><varname>SVR4_PKGNAME</varname> is the name of
+    the package file to create if the <varname>PKGNAME</varname>
+    isn't unique on a SVR4 system. The default is
+    <varname>PKGNAME</varname>, which may be shortened when you use
+    <filename role="pkg">pkgtools/gensolpkg</filename>. Only add
+    <varname>SVR4_PKGNAME</varname> if <varname>PKGNAME</varname>
+    does not produce an unique package name on a SVR4 system.
+    The length of <varname>SVR4_PKGNAME</varname> is limited to 5
+    characters.</para></listitem>
+
+    <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>
+
+    <para>Currently the following values are available for
+    <varname>CATEGORIES</varname>. If more than
+    one is used, they need to be separated by spaces:</para>
+
+    <programlisting>
+      archivers     cross         geography     meta-pkgs     security
+      audio         databases     graphics      misc          shells
+      benchmarks    devel         ham           multimedia    sysutils
+      biology       editors       inputmethod   net           textproc
+      cad           emulators     lang          news          time
+      chat          finance       mail          parallel      wm
+      comms         fonts         math          pkgtools      www
+      converters    games         mbone         print         x11
+    </programlisting>
+    </listitem>
+
+    <listitem><para><varname>MASTER_SITES</varname>,
+    <varname>DYNAMIC_MASTER_SITES</varname>,
+    <varname>DIST_SUBDIR</varname>, <varname>EXTRACT_SUFX</varname>
+    and <varname>DISTFILES</varname> are discussed in detail in
+    <xref linkend="build.fetch"/>.</para></listitem>
+
+  </itemizedlist>
+
+  <para>The second section contains information about separately
+  downloaded patches, if any.
+  <itemizedlist>
+    <listitem><para><varname>PATCHFILES:</varname>
+    Name(s) of additional files that contain distribution patches.
+    There is no default. pkgsrc will look for them at
+    <varname>PATCH_SITES</varname>.
+    They will automatically be uncompressed before patching if
+    the names end with <filename>.gz</filename> or
+    <filename>.Z</filename>.</para>
+    </listitem>
+    <listitem><para><varname>PATCH_SITES</varname>:
+    Primary location(s) for distribution patch files (see
+    <varname>PATCHFILES</varname> below) if not found locally.</para>
+    </listitem>
+  </itemizedlist></para>
+  <para>The third section contains the following variables.
+  <itemizedlist>
+
+    <listitem><para><varname>MAINTAINER</varname> is the email address
+    of the person who feels responsible for this package, and who is
+    most likely to look at problems or questions regarding this
+    package which have been reported with &man.send-pr.1;. Other
+    developers should contact the <varname>MAINTAINER</varname> before
+    making major changes to the package. When packaging a new program,
+    set <varname>MAINTAINER</varname> to yourself. If you really can't
+    maintain the package for future updates, set it to
+    <email>pkgsrc-users@NetBSD.org</email>.</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
+    description of the package (should not include the package
+    name).</para></listitem>
+  </itemizedlist></para>
+
+  <para>Other variables that affect the build:
+  <itemizedlist>
+
+    <listitem>
+      <para><varname>WRKSRC</varname>: The directory where the
+      interesting distribution files of the package are found. The
+      default is <filename>${WRKDIR}/${DISTNAME}</filename>, which
+      works for most packages.</para>
+
+      <para>If a package doesn't create a subdirectory for itself
+      (most GNU software does, for instance), but extracts itself in
+      the current directory, you should set
+      <varname>WRKSRC=${WRKDIR}</varname>.</para>
+
+      <para>If a package doesn't create a subdirectory with the
+      name of <varname>DISTNAME</varname> but some different name,
+      set <varname>WRKSRC</varname> to point to the proper name in
+      <filename>${WRKDIR}</filename>, for example
+      <varname>WRKSRC=${WRKDIR}/${DISTNAME}/unix</varname>. See
+      <filename role="pkg">lang/tcl</filename> and <filename
+      role="pkg">x11/tk</filename> for other examples.</para>
+
+      <para>The name of the working directory created by pkgsrc is
+      taken from the <varname>WRKDIR_BASENAME</varname>
+      variable. By default, its value is
+      <filename>work</filename>. If you want to use the same
+      pkgsrc tree for building different kinds of binary packages,
+      you can change the variable according to your needs. Two
+      other variables handle common cases of setting
+      <varname>WRKDIR_BASENAME</varname> individually. If
+      <varname>OBJHOSTNAME</varname> is defined in
+      <filename>/etc/mk.conf</filename>, the first component of
+      the host's name is attached to the directory name. If
+      <varname>OBJMACHINE</varname> is defined, the platform name
+      is attached, which might look like
+      <filename>work.i386</filename> or
+      <filename>work.sparc</filename>.</para>
+
+    </listitem>
+
+  </itemizedlist></para>
+  
+  <para>Please pay attention to the following gotchas:</para>
+  <itemizedlist>
+    <listitem>
+      <para>Add <varname>MANCOMPRESSED</varname> if man pages are
+      installed in compressed form by the package; see comment in
+      <filename>bsd.pkg.mk</filename>.</para>
+    </listitem>
+
+    <listitem>
+      <para>Replace <filename>/usr/local</filename> with
+      <quote>${PREFIX}</quote> in all files (see patches, below).</para>
+    </listitem>
+
+    <listitem>
+      <para>If the package installs any info files, see
+      <xref linkend="faq.info-files"/>.</para>
+    </listitem>
+
+  </itemizedlist>
+</sect1>
 
-  <sect1 id="components.distinfo">
-    <title><filename>distinfo</filename></title>
-
-    <para>The <filename>distinfo</filename> file contains the message
-    digest, or checksum, of each distfile needed for the package. This
-    ensures that the distfiles retrieved from the Internet have not been
-    corrupted during transfer or altered by a malign force to introduce
-    a security hole. Due to recent rumor about weaknesses of digest
-    algorithms, all distfiles are protected using both SHA1 and RMD160
-    message digests, as well as the file size.</para>
-
-    <para>The <filename>distinfo</filename> file also contains the
-    checksums for all the patches found in the
-    <filename>patches</filename> directory (see <xref
-    linkend="components.patches"/>).</para>
-
-    <para>To regenerate the <filename>distinfo</filename> file, use the
-    <command>make makedistinfo</command> or <command>make mdi</command>
-    command.</para>
-
-    <para>Some packages have different sets of distfiles depending on
-    the platform, for example <filename
-    role="pkg">www/navigator</filename>). These are kept in the same
-    <filename>distinfo</filename> file and care should be taken when
-    upgrading such a package to ensure distfile information is not
-    lost.</para>
+<sect1 id="components.distinfo">
+  <title><filename>distinfo</filename></title>
+
+  <para>The <filename>distinfo</filename> file contains the message
+  digest, or checksum, of each distfile needed for the package. This
+  ensures that the distfiles retrieved from the Internet have not been
+  corrupted during transfer or altered by a malign force to introduce
+  a security hole. Due to recent rumor about weaknesses of digest
+  algorithms, all distfiles are protected using both SHA1 and RMD160
+  message digests, as well as the file size.</para>
+
+  <para>The <filename>distinfo</filename> file also contains the
+  checksums for all the patches found in the
+  <filename>patches</filename> directory (see <xref
+  linkend="components.patches"/>).</para>
+
+  <para>To regenerate the <filename>distinfo</filename> file, use the
+  <command>make makedistinfo</command> or <command>make mdi</command>
+  command.</para>
+
+  <para>Some packages have different sets of distfiles depending on
+  the platform, for example <filename
+  role="pkg">www/navigator</filename>). These are kept in the same
+  <filename>distinfo</filename> file and care should be taken when
+  upgrading such a package to ensure distfile information is not
+  lost.</para>
 
-  </sect1>
+</sect1>
 
-  <sect1 id="components.patches">
-    <title>patches/*</title>
-
-    <para>This directory contains files that are used by the
-      &man.patch.1; command to
-      modify the sources as distributed in the distribution file into a form
-      that will compile and run perfectly on &os;. The files are applied
-      successively in alphabetic order (as returned by a shell
-      <quote>patches/patch-*</quote> glob expansion), so
-      <filename>patch-aa</filename> is applied before
-      <filename>patch-ab</filename>, etc.</para>
-
-    <para>The <filename>patch-*</filename> files should be in
-      <command>diff -bu</command> format, and apply without a fuzz to avoid
-      problems. (To force patches to apply
-      with fuzz you can set <varname>PATCH_FUZZ_FACTOR=-F2</varname>).
-      Furthermore, do not put changes for more than one file into a single
-      patch file, as this will make future modifications more difficult.</para>
-
-    <para>Similar, a file should be patched at most once, not several times by
-      several different patches. If a file needs several patches, they should
-      be combined into one file.</para>
-
-    <para>One important thing to mention is to pay attention that no RCS IDs
-      get stored in the patch files, as these will cause problems when
-      later checked into the &os; CVS tree. Use the
-      <command>pkgdiff</command> from the
-      <filename role="pkg">pkgtools/pkgdiff</filename> package to avoid
-      these problems.</para>
-
-    <para>For even more automation, we recommend using <command>mkpatches</command> from the same
-      package to make a whole set of patches. You just have to backup files
-      before you edit them to <filename>filename.orig</filename>, e.g. with
-      <command>cp -p filename filename.orig</command> or, easier, by using
-      <command>pkgvi</command> again from the same package. If you upgrade a package
-      this way, you can easily compare the new set of patches with the
-      previously existing one with <command>patchdiff</command>.</para>
-
-    <para>When you have finished a package, remember to generate the checksums
-      for the patch files by using the <command>make makepatchsum</command>
-      command, see <xref linkend="components.distinfo"/>.</para>
+<sect1 id="components.patches">
+  <title>patches/*</title>
+
+  <para>This directory contains files that are used by the
+  &man.patch.1; command to
+  modify the sources as distributed in the distribution file into a form
+  that will compile and run perfectly on &os;. The files are applied
+  successively in alphabetic order (as returned by a shell
+  <quote>patches/patch-*</quote> glob expansion), so
+  <filename>patch-aa</filename> is applied before
+  <filename>patch-ab</filename>, etc.</para>
+
+  <para>The <filename>patch-*</filename> files should be in
+  <command>diff -bu</command> format, and apply without a fuzz to avoid
+  problems. (To force patches to apply
+  with fuzz you can set <varname>PATCH_FUZZ_FACTOR=-F2</varname>).
+  Furthermore, do not put changes for more than one file into a single
+  patch file, as this will make future modifications more difficult.</para>
+
+  <para>Similar, a file should be patched at most once, not several times by
+  several different patches. If a file needs several patches, they should
+  be combined into one file.</para>
+
+  <para>One important thing to mention is to pay attention that no RCS IDs
+  get stored in the patch files, as these will cause problems when
+  later checked into the &os; CVS tree. Use the
+  <command>pkgdiff</command> from the
+  <filename role="pkg">pkgtools/pkgdiff</filename> package to avoid
+  these problems.</para>
+
+  <para>For even more automation, we recommend using
+  <command>mkpatches</command> from the same package to make a
+  whole set of patches. You just have to backup files before you
+  edit them to <filename>filename.orig</filename>, e.g. with
+  <command>cp -p filename filename.orig</command> or, easier, by
+  using <command>pkgvi</command> again from the same package. If
+  you upgrade a package this way, you can easily compare the new
+  set of patches with the previously existing one with
+  <command>patchdiff</command>. Copy the patches you want to use
+  or update from the <filename>work/.newpatches</filename>
+  directory to <filename>patches/</filename>.</para>
+
+  <para>When you have finished a package, remember to generate
+  the checksums for the patch files by using the <command>make
+  makepatchsum</command> command, see <xref
+  linkend="components.distinfo"/>.</para>
+
+  <para>When adding a patch that corrects a problem in the
+  distfile (rather than e.g. enforcing pkgsrc's view of where
+  man pages should go), send the patch as a bug report to the
+  maintainer.  This benefits non-pkgsrc users of the package,
+  and usually makes it possible to remove the patch in future
+  version.</para>
+
+  <para>If you want to share patches between multiple packages
+  in pkgsrc, e.g. because they use the same distfiles, set
+  <varname>PATCHDIR</varname> to the path where the patch files
+  can be found, e.g.:</para>
+  <programlisting>
+    PATCHDIR= ${.CURDIR}/../xemacs/patches
+    </programlisting>>
 
     <para>Patch files that are distributed by the author or other
-      maintainers can be listed in
-      <varname>$PATCHFILES</varname>. </para>
-
-    <para>If it is desired to store any patches that should not be committed into
-      pkgsrc, they can be kept outside the pkgsrc tree in the
-      <filename>$LOCALPATCHES</filename>
-      directory. The directory tree there is expected to have the same
-      <quote>category/package</quote> structure as pkgsrc, and patches are
-      expected to be stored inside these dirs (also known as
-      <filename>$LOCALPATCHES/$PKGPATH</filename>). For
-      example, if you want to keep a private patch for
-      <filename>pkgsrc/graphics/png</filename>, keep
-      it in <filename>$LOCALPATCHES/graphics/png/mypatch</filename>. All
-      files in the named directory are expected to be patch files, and
-      <emphasis>they are applied after pkgsrc patches are applied</emphasis>.</para>
+    maintainers can be listed in
+    <varname>PATCHFILES</varname>.</para>
+
+    <para>If it is desired to store any patches that should not be
+    committed into pkgsrc, they can be kept outside the pkgsrc
+    tree in the <filename>$LOCALPATCHES</filename> directory. The
+    directory tree there is expected to have the same
+    <quote>category/package</quote> structure as pkgsrc, and
+    patches are expected to be stored inside these dirs (also
+    known as <filename>$LOCALPATCHES/$PKGPATH</filename>). For
+    example, if you want to keep a private patch for
+    <filename>pkgsrc/graphics/png</filename>, keep it in
+    <filename>$LOCALPATCHES/graphics/png/mypatch</filename>. All
+    files in the named directory are expected to be patch files,
+    and <emphasis>they are applied after pkgsrc patches are
+    applied</emphasis>.</para>
 
     <sect2 id="components.patches.guidelines">
       <title>Patching guidelines</title>
@@ -302,9 +332,9 @@
 	      <entry>configure script</entry>
 	      <entry>
 		<programlisting>case ${target_os} in
-      netbsd*) have_kvm=yes ;;
-      *)       have_kvm=no  ;;
-  esac</programlisting>
+		netbsd*) have_kvm=yes ;;
+		*)       have_kvm=no  ;;
+		esac</programlisting>
 	      </entry>
 
 	      <entry>
@@ -316,40 +346,40 @@
 	      <entry>C source file</entry>
 	      <entry>
 		<programlisting>#if defined(__NetBSD__)
-  #  include &lt;sys/event.h&gt;
-  #endif</programlisting>
+		#  include &lt;sys/event.h&gt;
+		#endif</programlisting>
 	      </entry>
 	      <entry>
 		<programlisting>#if defined(HAVE_SYS_EVENT_H)
-  #  include &lt;sys/event.h&gt;
-  #endif</programlisting>
+		#  include &lt;sys/event.h&gt;
+		#endif</programlisting>
 	      </entry>
 	    </row>
 
 	    <row>
 	      <entry>C source file</entry>
 	      <entry><programlisting>int
-  monitor_file(...)
-  {
-  #if defined(__NetBSD__)
-      int fd = kqueue();
-      ...
-  #else
-      ...
-  #endif
-  }</programlisting>
+	      monitor_file(...)
+	      {
+	      #if defined(__NetBSD__)
+	      int fd = kqueue();
+	      ...
+	      #else
+	      ...
+	      #endif
+	      }</programlisting>
 	      </entry>
 	      <entry>
 		<programlisting>int
-  monitor_file(...)
-  {
-  #if defined(HAVE_KQUEUE)
-      int fd = kqueue();
-      ...
-  #else
-      ...
-  #endif
-  }</programlisting>
+		monitor_file(...)
+		{
+		#if defined(HAVE_KQUEUE)
+		int fd = kqueue();
+		...
+		#else
+		...
+		#endif
+		}</programlisting>
 	      </entry>
 	    </row>
 	  </tbody>
@@ -399,27 +429,27 @@
 
     <variablelist>
       <varlistentry>
-        <term><filename>DESCR</filename></term>
-
-        <listitem>
-          <para>A multi-line description of the piece of software.  This should include
-            any credits where they are due.  Please bear in mind that others do not
-            share your sense of humour (or spelling idiosyncrasies), and that others
-            will read everything that you write here.</para>
-        </listitem>
+	<term><filename>DESCR</filename></term>
+
+	<listitem>
+	  <para>A multi-line description of the piece of software.  This should include
+	  any credits where they are due.  Please bear in mind that others do not
+	  share your sense of humour (or spelling idiosyncrasies), and that others
+	  will read everything that you write here.</para>
+	</listitem>
       </varlistentry>
 
       <varlistentry>
-        <term><filename>PLIST</filename></term>
-
-        <listitem>
-          <para>
-            This file governs the files that are installed on your system: all the
-            binaries, manual pages, etc. There are other directives which may be
-            entered in this file, to control the creation and deletion of
-            directories, and the location of inserted files.
-            See <xref linkend="plist"/> for more information. </para>
-        </listitem>
+	<term><filename>PLIST</filename></term>
+
+	<listitem>
+	  <para>This file governs the files that are installed on your
+	  system: all the binaries, manual pages, etc. There are other
+	  directives which may be entered in this file, to control the
+	  creation and deletion of directories, and the location of
+	  inserted files.  See <xref linkend="plist"/> for more
+	  information.</para>
+	</listitem>
       </varlistentry>
     </variablelist>
   </sect1>
@@ -427,69 +457,82 @@
   <sect1 id="components.optional">
     <title>Optional files</title>
 
-<sect2 id="components.optional.bin">
-<title>Files affecting the binary package</title>
-
-    <variablelist>
-      <varlistentry>
-        <term><filename>INSTALL</filename></term>
-
-        <listitem>
-          <para>This shell script is invoked twice by &man.pkg.add.1;.
-            First time after package
-            extraction and before files are moved in place, the second time after
-            the files to install are moved in place. This can be used to do any
-            custom procedures not possible with @exec commands in
-            <filename>PLIST</filename>. See
-            &man.pkg.add.1; and &man.pkg.create.1; for more information.</para>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><filename>DEINSTALL</filename></term>
-
-        <listitem>
-          <para>This script is executed before and after any files are removed.  It is
-            this script's responsibility to clean up any additional messy details
-            around the package's installation, since all pkg_delete knows is how to
-            delete the files created in the original distribution.
-            See &man.pkg.delete.1;
-            and &man.pkg.create.1; for more information.</para>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term><filename>MESSAGE</filename></term>
-
-        <listitem>
-          <para>This file is displayed after installation of the package.
-            Useful for things like legal notices on almost-free
-            software and hints for updating config files after
-            installing modules for apache, PHP etc.
-            Please note that you can modify variables in it easily by using
-            <varname>MESSAGE_SUBST</varname> in the package's
-            <filename>Makefile</filename>:</para>
-
-<programlisting>
-    MESSAGE_SUBST+=  SOMEVAR="somevalue"
-</programlisting>
-
-          <para>replaces "${SOMEVAR}" with <quote>somevalue</quote> in
-            <filename>MESSAGE</filename>.</para>
-        </listitem>
-      </varlistentry>
+    <sect2 id="components.optional.bin">
+      <title>Files affecting the binary package</title>
+
+      <variablelist>
+	<varlistentry>
+	  <term><filename>INSTALL</filename></term>
+
+	  <listitem>
+	    <para>This shell script is invoked twice by &man.pkg.add.1;.
+	    First time after package extraction and before files are
+	    moved in place, the second time after the files to install
+	    are moved in place. This can be used to do any custom
+	    procedures not possible with @exec commands in
+	    <filename>PLIST</filename>. See &man.pkg.add.1; and
+	    &man.pkg.create.1; for more information.  See also <xref
+	    linkend="files-and-dirs-outside-prefix" />.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><filename>DEINSTALL</filename></term>
+
+	  <listitem>
+	    <para>This script is executed before and after any files are removed.  It is
+	    this script's responsibility to clean up any additional messy details
+	    around the package's installation, since all pkg_delete knows is how to
+	    delete the files created in the original distribution.
+	    See &man.pkg.delete.1;
+	    and &man.pkg.create.1; for more information.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><filename>MESSAGE</filename></term>
+
+	  <listitem>
+	    <para>This file is displayed after installation of the package.
+	    Useful for things like legal notices on almost-free
+	    software and hints for updating config files after
+	    installing modules for apache, PHP etc.
+	    Please note that you can modify variables in it easily by using
+	    <varname>MESSAGE_SUBST</varname> in the package's
+	    <filename>Makefile</filename>:</para>
+
+	    <programlisting>
+	      MESSAGE_SUBST+=  SOMEVAR="somevalue"
+	    </programlisting>
+
+	    <para>replaces "${SOMEVAR}" with <quote>somevalue</quote> in
+	    <filename>MESSAGE</filename>.  By default, substitution is
+	    performed for <varname>PKGNAME</varname>,
+	    <varname>PKGBASE</varname>, <varname>PREFIX</varname>,
+	    <varname>LOCALBASE</varname>, <varname>X11PREFIX</varname>,
+	    <varname>X11BASE</varname>,
+	    <varname>PKG_SYSCONFDIR</varname>,
+	    <varname>ROOT_GROUP</varname>, and
+	    <varname>ROOT_GROUP</varname>.</para>
+
+	    <para>You can display a different or additional files by
+	    setting the <varname>MESSAGE_SRC</varname> variable.  Its
+	    default is <filename>MESSAGE</filename>, if the file
+	    exists.</para>
+	  </listitem>
+	</varlistentry>
 
 	<varlistentry><term><filename>ALTERNATIVES</filename></term>
 	<listitem><para>FIXME: There is no documentation on the
 	alternatives framework.</para></listitem></varlistentry>
 
-    </variablelist>
+      </variablelist>
 
-</sect2>
-<sect2 id="components.optional.build">
-<title>Files affecting the build process</title>
+    </sect2>
+    <sect2 id="components.optional.build">
+      <title>Files affecting the build process</title>
 
-	<variablelist>
+      <variablelist>
 
 	<varlistentry><term><filename>Makefile.common</filename></term>
 	<listitem><para>This file contains arbitrary things that could
@@ -519,13 +562,13 @@
 	it is equally acceptable to put the code directly into the
 	<filename>Makefile</filename>.</para></listitem></varlistentry>
 
-	</variablelist>
+      </variablelist>
 
-</sect2>
-<sect2 id="components.optional.none">
-<title>Files affecting nothing at all</title>
+    </sect2>
+    <sect2 id="components.optional.none">
+      <title>Files affecting nothing at all</title>
 
-	<variablelist>
+      <variablelist>
 
 	<varlistentry><term><filename>README*</filename></term>
 	<listitem><para>These files do not take place in the creation of
@@ -537,34 +580,42 @@
 	to make the package even
 	better.</para></listitem></varlistentry>
 
-	</variablelist>
+      </variablelist>
 
-</sect2>
-</sect1>
+    </sect2>
+  </sect1>
 
   <sect1 id="work-dir">
     <title><filename>work*</filename></title>
 
     <para>When you type <command>make</command>, the distribution files are
-      unpacked into the directory denoted by
-      <varname>WRKDIR</varname>. It can be removed by running
-      <command>make clean</command>. Besides the sources, this
-      directory is also used to keep various timestamp files.
-      The directory gets <emphasis>removed completely</emphasis> on clean.
-      The default is <filename>${.CURDIR}/work</filename>
-      or <filename>${.CURDIR}/work.${MACHINE_ARCH}</filename>
-      if <varname>OBJMACHINE</varname> is set.</para>
+    unpacked into the directory denoted by
+    <varname>WRKDIR</varname>. It can be removed by running
+    <command>make clean</command>. Besides the sources, this
+    directory is also used to keep various timestamp files.
+    The directory gets <emphasis>removed completely</emphasis> on clean.
+    The default is <filename>${.CURDIR}/work</filename>
+    or <filename>${.CURDIR}/work.${MACHINE_ARCH}</filename>
+    if <varname>OBJMACHINE</varname> is set.</para>
   </sect1>
 
   <sect1 id="files-dir">
     <title><filename>files/*</filename></title>
 
     <para>If you have any files that you wish to be placed in the package prior
-      to configuration or building, you could place these files here and use
-      a <quote>${CP}</quote> command in the
-      <quote>pre-configure</quote> target to achieve
-      this. Alternatively, you could simply diff the file against
-      <filename>/dev/null</filename> and use the patch mechanism to manage
-      the creation of this file.</para>
+    to configuration or building, you could place these files here and use
+    a <command>${CP}</command> command in the
+    <quote>pre-configure</quote> target to achieve
+    this. Alternatively, you could simply diff the file against
+    <filename>/dev/null</filename> and use the patch mechanism to manage
+    the creation of this file.</para>
+
+    <para>If you want to share files in this way with other
+    packages, set the <varname>FILESDIR</varname> variable to point
+    to the other package's <filename>files</filename> directory,
+    e.g.:</para>
+    <programlisting>
+      FILESDIR=${.CURDIR}/../xemacs/files
+    </programlisting>
   </sect1>
 </chapter>