 @@ -1,14 +1,14 @@
-<!-- $NetBSD: components.xml,v 1.41 2010/06/07 16:06:58 tnn Exp $ -->
+<!-- $NetBSD: components.xml,v 1.42 2011/02/02 10:25:36 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>.
 @@ -218,104 +218,105 @@ converters    games         mbone
 <sect1 id="components.patches">
   <title>patches/*</title>
   <para>Many packages still don't work out-of-the box on the various
   platforms that are supported by pkgsrc. Therefore, a number of custom
   patch files are needed to make the package work. These patch files are
   found in the <filename>patches/</filename> directory.</para>
   <para>In the <emphasis>patch</emphasis> phase, these patches are
   applied to the files in <varname>WRKSRC</varname> directory after
   extracting them, in <ulink
   url="http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#tag_02_13_03">alphabetic
-  order</ulink>, so <filename>patch-aa</filename> is applied before
+  order</ulink>.</para>
   <filename>patch-ab</filename>, etc.</para>
 <sect2 id="components.patch.structure">
 <title>Structure of a single patch file</title>
   <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, each patch
   should contain only changes for a single file, and no file should be
   patched by more than one patch file. This helps to keep future
   modifications simple.</para>
   <para>Each patch file is structured as follows: In the first line,
   there is the RCS Id of the patch itself. The second line should be
   empty for aesthetic reasons. After that, there should be a comment for
   each change that the patch does. There are a number of standard
   cases:</para>
   <itemizedlist>
   <listitem><para>Patches that replace the <literal>==</literal>
   operator for &man.test.1; with <literal>=</literal> in shell scripts
   are so common that they don't need a comment at all.</para></listitem>
   <listitem><para>Patches for commonly known vulnerabilities should
   mention the vulnerability ID (CAN, CVE).</para></listitem>
   <listitem><para>Patches that change source code should mention the
   platform and other environment (for example, the compiler) that the
   patch is needed for.</para></listitem>
   </itemizedlist>
-  <para>In all other cases, the patch should be commented so that any
+  <para>In all, the patch should be commented so that any
   developer who knows the code of the application can make some use of
   the patch. Special care should be taken for the upstream developers,
   since we generally want that they accept our patches, so we have less
   work in the future.</para>
 </sect2>
 <sect2 id="components.patches.caveats">
 <title>Creating patch files</title>
   <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> 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
+  <command>patchdiff</command>. The files in <filename>patches</filename>
-  or update from the <filename>work/.newpatches</filename>
+  are replaced by new files, so carefully check if you want to take all
-  directory to <filename>patches/</filename>.</para>
+  the changes.</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>The file names of the patch files are usually of the form
-  <filename>patch-<replaceable>[a-z][a-z]</replaceable></filename>.</para>
+  <filename>patch-<replaceable>path_to_file__with__underscores.c</replaceable></filename>.
   Many packages still use the previous convention
   <filename>patch-<replaceable>[a-z][a-z]</replaceable></filename>,
   but new patches should be of the form containing the filename.
   <command>mkpatches</command> included in <filename
   role="pkg">pkgtools/pkgdiff</filename> takes care of the name
   automatically.</para>
 </sect2>
 <sect2 id="components.patches.sources">
 <title>Sources where the patch files come from</title>
   <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>
 @@ -473,26 +474,29 @@ monitor_file(...)
       and to ensure that future versions can be built out-of-the box on
       NetBSD.  Furthermore, any user that gets newer distfiles will get
       the fixes straight from the packaged code.</para>
       <para>This generally involves cleaning up the patches
       (because sometimes the patches that are
       added to pkgsrc are quick hacks), filling bug reports in the
       appropriate trackers for the projects and working with the
       mainstream authors to accept your changes.  It is
       <emphasis>extremely important</emphasis> that you do it so that
       the packages in pkgsrc are kept simple and thus further changes
       can be done without much hassle.</para>
       <para>When you have done this, please add a URL to the upstream
       bug report to the patch comment.</para>
       <para>Support the idea of free software!</para>
     </sect2>
   </sect1>
   <sect1 id="other-mandatory-files">
     <title>Other mandatory files</title>
     <variablelist>
       <varlistentry>
 	<term><filename>DESCR</filename></term>