regen for upstream patch admonition.

(Also noticed part numbering changed to I/II/A, but that seems ok.)

2 files changed, 108 insertions, 97 deletions

diff --git a/doc/pkgsrc.html b/doc/pkgsrc.html
index ef1ee87169e..a5358b8cb2e 100644
--- a/doc/pkgsrc.html
+++ b/doc/pkgsrc.html
@@ -108,7 +108,7 @@ alink="#0000FF">
           </dl>
         </dd>
 
-        <dt><span class="part"><a href="#users-guide">1. The pkgsrc
+        <dt><span class="part"><a href="#users-guide">I. The pkgsrc
         user's guide</a></span></dt>
 
         <dd>
@@ -384,7 +384,7 @@ alink="#0000FF">
           </dl>
         </dd>
 
-        <dt><span class="part"><a href="#developers-guide">2. The
+        <dt><span class="part"><a href="#developers-guide">II. The
         pkgsrc developer's guide</a></span></dt>
 
         <dd>
@@ -909,63 +909,63 @@ alink="#0000FF">
           </dl>
         </dd>
 
-        <dt><span class="appendix"><a href="#examples">1. A simple
+        <dt><span class="appendix"><a href="#examples">A. A simple
         example package: bison</a></span></dt>
 
         <dd>
           <dl>
-            <dt><span class="sect1"><a href="#example-files">1.1.
+            <dt><span class="sect1"><a href="#example-files">A.1.
             files</a></span></dt>
 
             <dd>
               <dl>
                 <dt><span class="sect2"><a href=
-                "#example-Makefile">1.1.1. Makefile</a></span></dt>
+                "#example-Makefile">A.1.1. Makefile</a></span></dt>
 
                 <dt><span class="sect2"><a href=
-                "#example-descr">1.1.2. DESCR</a></span></dt>
+                "#example-descr">A.1.2. DESCR</a></span></dt>
 
                 <dt><span class="sect2"><a href=
-                "#example-plist">1.1.3. PLIST</a></span></dt>
+                "#example-plist">A.1.3. PLIST</a></span></dt>
 
                 <dt><span class="sect2"><a href=
-                "#checking-package-with-pkglint">1.1.4. Checking a
+                "#checking-package-with-pkglint">A.1.4. Checking a
                 package with <span><strong class=
                 "command">pkglint</strong></span></a></span></dt>
               </dl>
             </dd>
 
-            <dt><span class="sect1"><a href="#steps-for-b-i-p">1.2.
+            <dt><span class="sect1"><a href="#steps-for-b-i-p">A.2.
             Steps for building, installing,
             packaging</a></span></dt>
           </dl>
         </dd>
 
-        <dt><span class="appendix"><a href="#logs">2. Build
+        <dt><span class="appendix"><a href="#logs">B. Build
         logs</a></span></dt>
 
         <dd>
           <dl>
-            <dt><span class="sect1"><a href="#logs.building">2.1.
+            <dt><span class="sect1"><a href="#logs.building">B.1.
             Building figlet</a></span></dt>
 
-            <dt><span class="sect1"><a href="#logs.package">2.2.
+            <dt><span class="sect1"><a href="#logs.package">B.2.
             Packaging figlet</a></span></dt>
           </dl>
         </dd>
 
-        <dt><span class="appendix"><a href="#ftp-layout">3. Layout
+        <dt><span class="appendix"><a href="#ftp-layout">C. Layout
         of the FTP server's package archive</a></span></dt>
 
-        <dt><span class="appendix"><a href="#editing">4. Editing
+        <dt><span class="appendix"><a href="#editing">D. Editing
         guidelines for the pkgsrc guide</a></span></dt>
 
         <dd>
           <dl>
-            <dt><span class="sect1"><a href="#targets">4.1.
+            <dt><span class="sect1"><a href="#targets">D.1.
             Targets</a></span></dt>
 
-            <dt><span class="sect1"><a href="#procedure">4.2.
+            <dt><span class="sect1"><a href="#procedure">D.2.
             Procedure</a></span></dt>
           </dl>
         </dd>
@@ -1150,16 +1150,16 @@ alink="#0000FF">
 
         <p>This document is divided into two parts. The first,
         <a href="#users-guide" title=
-        "Part&nbsp;1.&nbsp;The pkgsrc user's guide">The pkgsrc
+        "Part&nbsp;I.&nbsp;The pkgsrc user's guide">The pkgsrc
         user's guide</a>, describes how one can use one of the
         packages in the Package Collection, either by installing a
         precompiled binary package, or by building one's own copy
         using the NetBSD package system. The second part, <a href=
         "#developers-guide" title=
-        "Part&nbsp;2.&nbsp;The pkgsrc developer's guide">The pkgsrc
-        developer's guide</a>, explains how to prepare a package so
-        it can be easily built by other NetBSD users without
-        knowing about the package's building details.</p>
+        "Part&nbsp;II.&nbsp;The pkgsrc developer's guide">The
+        pkgsrc developer's guide</a>, explains how to prepare a
+        package so it can be easily built by other NetBSD users
+        without knowing about the package's building details.</p>
 
         <p>This document is available in various formats:</p>
 
@@ -1310,8 +1310,7 @@ alink="#0000FF">
         <div>
           <div>
             <h1 class="title"><a name="users-guide" id=
-            "users-guide"></a>Part&nbsp;1.&nbsp;The pkgsrc user's
-            guide</h1>
+            "users-guide"></a>The pkgsrc user's guide</h1>
           </div>
         </div>
       </div>
@@ -2869,7 +2868,7 @@ CFLAGS= -xtarget=ultra -xarch=v9
 
           <p>This assumes that the package is already in pkgsrc. If
           it is not, see <a href="#developers-guide" title=
-          "Part&nbsp;2.&nbsp;The pkgsrc developer's guide">Part&nbsp;2,
+          "Part&nbsp;II.&nbsp;The pkgsrc developer's guide">Part&nbsp;II,
           &#8220;The pkgsrc developer's guide&#8221;</a> for
           instructions how to create your own packages.</p>
 
@@ -2976,7 +2975,7 @@ CFLAGS= -xtarget=ultra -xarch=v9
             <p>Taking the figlet utility as an example, we can
             install it on our system by building as shown in
             <a href="#logs" title=
-            "Appendix&nbsp;2.&nbsp;Build logs">Appendix 2, <i>Build
+            "Appendix&nbsp;B.&nbsp;Build logs">Appendix B, <i>Build
             logs</i></a>.</p>
 
             <p>The program is installed under the default root of
@@ -3676,7 +3675,7 @@ CFLAGS= -xtarget=ultra -xarch=v9
           "http://www.w3.org/TR/xhtml1/transitional" class=
           "filename">/usr/pkgsrc/packages</code>, in the form of a
           gzipped tar file. See <a href="#logs.package" title=
-          "2.2.&nbsp;Packaging figlet">Section 2.2,
+          "B.2.&nbsp;Packaging figlet">Section B.2,
           &#8220;Packaging figlet&#8221;</a> for a continuation of
           the above <a xmlns=
           "http://www.w3.org/TR/xhtml1/transitional" href=
@@ -5519,8 +5518,8 @@ SU_CMD=${LOCALBASE}/bin/sudo /bin/sh -c
         <div>
           <div>
             <h1 class="title"><a name="developers-guide" id=
-            "developers-guide"></a>Part&nbsp;2.&nbsp;The pkgsrc
-            developer's guide</h1>
+            "developers-guide"></a>The pkgsrc developer's
+            guide</h1>
           </div>
         </div>
       </div>
@@ -6512,6 +6511,13 @@ SITES_foo-file.tar.gz=http://www.somewhere.com/somehow/ \
           &#8220;<code xmlns="http://www.w3.org/TR/xhtml1/transitional"
           class="filename">distinfo</code>&#8221;</a>.</p>
 
+          <p>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 enables removing the patch in
+          future version.</p>
+
           <p>Patch files that are distributed by the author or
           other maintainers can be listed in <code class=
           "varname">$PATCHFILES</code>.</p>
@@ -13689,7 +13695,7 @@ PERL5_PACKLIST=   ${PERL5_SITEARCH}/auto/Pg/.packlist
         <div>
           <div>
             <h2 class="title"><a name="examples" id=
-            "examples"></a>Appendix&nbsp;1.&nbsp;A simple example
+            "examples"></a>Appendix&nbsp;A.&nbsp;A simple example
             package: bison</h2>
           </div>
         </div>
@@ -13699,28 +13705,28 @@ PERL5_PACKLIST=   ${PERL5_SITEARCH}/auto/Pg/.packlist
         <p><b>Table of Contents</b></p>
 
         <dl>
-          <dt><span class="sect1"><a href="#example-files">1.1.
+          <dt><span class="sect1"><a href="#example-files">A.1.
           files</a></span></dt>
 
           <dd>
             <dl>
               <dt><span class="sect2"><a href=
-              "#example-Makefile">1.1.1. Makefile</a></span></dt>
+              "#example-Makefile">A.1.1. Makefile</a></span></dt>
 
               <dt><span class="sect2"><a href=
-              "#example-descr">1.1.2. DESCR</a></span></dt>
+              "#example-descr">A.1.2. DESCR</a></span></dt>
 
               <dt><span class="sect2"><a href=
-              "#example-plist">1.1.3. PLIST</a></span></dt>
+              "#example-plist">A.1.3. PLIST</a></span></dt>
 
               <dt><span class="sect2"><a href=
-              "#checking-package-with-pkglint">1.1.4. Checking a
+              "#checking-package-with-pkglint">A.1.4. Checking a
               package with <span><strong class=
               "command">pkglint</strong></span></a></span></dt>
             </dl>
           </dd>
 
-          <dt><span class="sect1"><a href="#steps-for-b-i-p">1.2.
+          <dt><span class="sect1"><a href="#steps-for-b-i-p">A.2.
           Steps for building, installing, packaging</a></span></dt>
         </dl>
       </div>
@@ -13739,7 +13745,7 @@ PERL5_PACKLIST=   ${PERL5_SITEARCH}/auto/Pg/.packlist
             <div>
               <h2 class="title" style="clear: both"><a name=
               "example-files" id=
-              "example-files"></a>1.1.&nbsp;files</h2>
+              "example-files"></a>A.1.&nbsp;files</h2>
             </div>
           </div>
         </div>
@@ -13749,7 +13755,7 @@ PERL5_PACKLIST=   ${PERL5_SITEARCH}/auto/Pg/.packlist
             <div>
               <div>
                 <h3 class="title"><a name="example-Makefile" id=
-                "example-Makefile"></a>1.1.1.&nbsp;Makefile</h3>
+                "example-Makefile"></a>A.1.1.&nbsp;Makefile</h3>
               </div>
             </div>
           </div>
@@ -13777,7 +13783,7 @@ INFO_FILES=     bison.info
             <div>
               <div>
                 <h3 class="title"><a name="example-descr" id=
-                "example-descr"></a>1.1.2.&nbsp;DESCR</h3>
+                "example-descr"></a>A.1.2.&nbsp;DESCR</h3>
               </div>
             </div>
           </div>
@@ -13794,7 +13800,7 @@ of the NetBSD source tree is beyond me.
             <div>
               <div>
                 <h3 class="title"><a name="example-plist" id=
-                "example-plist"></a>1.1.3.&nbsp;PLIST</h3>
+                "example-plist"></a>A.1.3.&nbsp;PLIST</h3>
               </div>
             </div>
           </div>
@@ -13813,7 +13819,7 @@ share/bison.hairy
               <div>
                 <h3 class="title"><a name=
                 "checking-package-with-pkglint" id=
-                "checking-package-with-pkglint"></a>1.1.4.&nbsp;Checking
+                "checking-package-with-pkglint"></a>A.1.4.&nbsp;Checking
                 a package with <span><strong class=
                 "command">pkglint</strong></span></h3>
               </div>
@@ -13849,7 +13855,7 @@ looks fine.
             <div>
               <h2 class="title" style="clear: both"><a name=
               "steps-for-b-i-p" id=
-              "steps-for-b-i-p"></a>1.2.&nbsp;Steps for building,
+              "steps-for-b-i-p"></a>A.2.&nbsp;Steps for building,
               installing, packaging</h2>
             </div>
           </div>
@@ -14007,7 +14013,7 @@ Creating gzip'd tar ball in '/u/pkgsrc/lang/bison/bison-1.25.tgz'
         <div>
           <div>
             <h2 class="title"><a name="logs" id=
-            "logs"></a>Appendix&nbsp;2.&nbsp;Build logs</h2>
+            "logs"></a>Appendix&nbsp;B.&nbsp;Build logs</h2>
           </div>
         </div>
       </div>
@@ -14016,10 +14022,10 @@ Creating gzip'd tar ball in '/u/pkgsrc/lang/bison/bison-1.25.tgz'
         <p><b>Table of Contents</b></p>
 
         <dl>
-          <dt><span class="sect1"><a href="#logs.building">2.1.
+          <dt><span class="sect1"><a href="#logs.building">B.1.
           Building figlet</a></span></dt>
 
-          <dt><span class="sect1"><a href="#logs.package">2.2.
+          <dt><span class="sect1"><a href="#logs.package">B.2.
           Packaging figlet</a></span></dt>
         </dl>
       </div>
@@ -14030,7 +14036,7 @@ Creating gzip'd tar ball in '/u/pkgsrc/lang/bison/bison-1.25.tgz'
             <div>
               <h2 class="title" style="clear: both"><a name=
               "logs.building" id=
-              "logs.building"></a>2.1.&nbsp;Building figlet</h2>
+              "logs.building"></a>B.1.&nbsp;Building figlet</h2>
             </div>
           </div>
         </div>
@@ -14134,7 +14140,7 @@ cp figlet.6 /usr/pkg/man/man6
             <div>
               <h2 class="title" style="clear: both"><a name=
               "logs.package" id=
-              "logs.package"></a>2.2.&nbsp;Packaging figlet</h2>
+              "logs.package"></a>B.2.&nbsp;Packaging figlet</h2>
             </div>
           </div>
         </div>
@@ -14157,7 +14163,7 @@ Registering depends:.
         <div>
           <div>
             <h2 class="title"><a name="ftp-layout" id=
-            "ftp-layout"></a>Appendix&nbsp;3.&nbsp;Layout of the
+            "ftp-layout"></a>Appendix&nbsp;C.&nbsp;Layout of the
             FTP server's package archive</h2>
           </div>
         </div>
@@ -14262,7 +14268,7 @@ Registering depends:.
         <div>
           <div>
             <h2 class="title"><a name="editing" id=
-            "editing"></a>Appendix&nbsp;4.&nbsp;Editing guidelines
+            "editing"></a>Appendix&nbsp;D.&nbsp;Editing guidelines
             for the pkgsrc guide</h2>
           </div>
         </div>
@@ -14272,10 +14278,10 @@ Registering depends:.
         <p><b>Table of Contents</b></p>
 
         <dl>
-          <dt><span class="sect1"><a href="#targets">4.1.
+          <dt><span class="sect1"><a href="#targets">D.1.
           Targets</a></span></dt>
 
-          <dt><span class="sect1"><a href="#procedure">4.2.
+          <dt><span class="sect1"><a href="#procedure">D.2.
           Procedure</a></span></dt>
         </dl>
       </div>
@@ -14288,7 +14294,7 @@ Registering depends:.
           <div>
             <div>
               <h2 class="title" style="clear: both"><a name=
-              "targets" id="targets"></a>4.1.&nbsp;Targets</h2>
+              "targets" id="targets"></a>D.1.&nbsp;Targets</h2>
             </div>
           </div>
         </div>
@@ -14346,7 +14352,7 @@ Registering depends:.
             <div>
               <h2 class="title" style="clear: both"><a name=
               "procedure" id=
-              "procedure"></a>4.2.&nbsp;Procedure</h2>
+              "procedure"></a>D.2.&nbsp;Procedure</h2>
             </div>
           </div>
         </div>
diff --git a/doc/pkgsrc.txt b/doc/pkgsrc.txt
index 952265fe509..18d979b9921 100644
--- a/doc/pkgsrc.txt
+++ b/doc/pkgsrc.txt
@@ -33,7 +33,7 @@ Table of Contents
     1.3. Terminology
     1.4. Typography
 
-1. The pkgsrc user's guide
+I. The pkgsrc user's guide
 
     2. Where to get pkgsrc
 
@@ -114,7 +114,7 @@ Table of Contents
         7.14. How do I change the location of configuration files?
         7.15. Automated security checks
 
-2. The pkgsrc developer's guide
+II. The pkgsrc developer's guide
 
     8. Package components - files, directories and contents
 
@@ -260,27 +260,27 @@ Table of Contents
         17.4. Updating a package to a newer version
         17.5. Moving a package in pkgsrc
 
-1. A simple example package: bison
+A. A simple example package: bison
 
-    1.1. files
+    A.1. files
 
-        1.1.1. Makefile
-        1.1.2. DESCR
-        1.1.3. PLIST
-        1.1.4. Checking a package with pkglint
+        A.1.1. Makefile
+        A.1.2. DESCR
+        A.1.3. PLIST
+        A.1.4. Checking a package with pkglint
 
-    1.2. Steps for building, installing, packaging
+    A.2. Steps for building, installing, packaging
 
-2. Build logs
+B. Build logs
 
-    2.1. Building figlet
-    2.2. Packaging figlet
+    B.1. Building figlet
+    B.2. Packaging figlet
 
-3. Layout of the FTP server's package archive
-4. Editing guidelines for the pkgsrc guide
+C. Layout of the FTP server's package archive
+D. Editing guidelines for the pkgsrc guide
 
-    4.1. Targets
-    4.2. Procedure
+    D.1. Targets
+    D.2. Procedure
 
 Chapter 1. Introduction
 
@@ -417,7 +417,7 @@ command should/can be issued as root, or if "normal" user privileges are
 sufficient. We use a # for root's shell prompt, and a % for users' shell
 prompt, assuming they use the C-shell or tcsh.
 
-Part 1. The pkgsrc user's guide
+The pkgsrc user's guide
 
 Table of Contents
 
@@ -1038,7 +1038,7 @@ your system by indiscriminate adding of such files.
 
 4.2. Building packages from source
 
-This assumes that the package is already in pkgsrc. If it is not, see Part 2,
+This assumes that the package is already in pkgsrc. If it is not, see Part II,
 "The pkgsrc developer's guide" for instructions how to create your own
 packages.
 
@@ -1085,7 +1085,7 @@ has a just-in-time-su feature, which allows you to only become root for the
 actual installation step
 
 Taking the figlet utility as an example, we can install it on our system by
-building as shown in Appendix 2, Build logs.
+building as shown in Appendix B, Build logs.
 
 The program is installed under the default root of the packages tree - /usr/
 pkg. Should this not conform to your tastes, set the LOCALBASE variable in your
@@ -1345,7 +1345,7 @@ and run make package:
 This will build and install your package (if not already done), and then build
 a binary package from what was installed. You can then use the pkg_* tools to
 manipulate it. Binary packages are created by default in /usr/pkgsrc/packages,
-in the form of a gzipped tar file. See Section 2.2, "Packaging figlet" for a
+in the form of a gzipped tar file. See Section B.2, "Packaging figlet" for a
 continuation of the above misc/figlet example.
 
 See Chapter 17, Submitting and Committing for information on how to submit such
@@ -2024,7 +2024,7 @@ Use of the security/audit-packages package is strongly recommended! After
 "audit-packages" is installed, please read the package's message, which you can
 get by running pkg_info -D audit-package.
 
-Part 2. The pkgsrc developer's guide
+The pkgsrc developer's guide
 
 Table of Contents
 
@@ -2380,6 +2380,11 @@ When you have finished a package, remember to generate the checksums for the
 patch files by using the make makepatchsum command, see Section 8.2, "distinfo"
 .
 
+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 enables removing the patch in future version.
+
 Patch files that are distributed by the author or other maintainers can be
 listed in $PATCHFILES.
 
@@ -5268,27 +5273,27 @@ possibly untested features.
 
     (and any packages from step 5, of course).
 
-Appendix 1. A simple example package: bison
+Appendix A. A simple example package: bison
 
 Table of Contents
 
-1.1. files
+A.1. files
 
-    1.1.1. Makefile
-    1.1.2. DESCR
-    1.1.3. PLIST
-    1.1.4. Checking a package with pkglint
+    A.1.1. Makefile
+    A.1.2. DESCR
+    A.1.3. PLIST
+    A.1.4. Checking a package with pkglint
 
-1.2. Steps for building, installing, packaging
+A.2. Steps for building, installing, packaging
 
 We checked to find a piece of software that wasn't in the packages collection,
 and picked GNU bison. Quite why someone would want to have bison when Berkeley
 yacc is already present in the tree is beyond us, but it's useful for the
 purposes of this exercise.
 
-1.1. files
+A.1. files
 
-1.1.1. Makefile
+A.1.1. Makefile
 
 # $NetBSD$
 #
@@ -5306,13 +5311,13 @@ INFO_FILES=     bison.info
 
 .include "../../mk/bsd.pkg.mk"
 
-1.1.2. DESCR
+A.1.2. DESCR
 
 GNU version of yacc.  Can make re-entrant parsers, and numerous other
 improvements.  Why you would want this when Berkeley yacc(1) is part
 of the NetBSD source tree is beyond me.
 
-1.1.3. PLIST
+A.1.3. PLIST
 
 @comment $NetBSD$
 bin/bison
@@ -5320,7 +5325,7 @@ man/man1/bison.1.gz
 share/bison.simple
 share/bison.hairy
 
-1.1.4. Checking a package with pkglint
+A.1.4. Checking a package with pkglint
 
 The NetBSD package system comes with pkgtools/pkglint which helps to check the
 contents of these files. After installation it is quite easy to use, just
@@ -5332,7 +5337,7 @@ looks fine.
 Depending on the supplied command line arguments (see pkglint(1)) more verbose
 checks will be performed. Use e.g. pkglint -v for a very verbose check.
 
-1.2. Steps for building, installing, packaging
+A.2. Steps for building, installing, packaging
 
 Create the directory where the package lives, plus any auxiliary directories:
 
@@ -5447,14 +5452,14 @@ Now that you don't need the source and object files any more, clean up:
 # make clean
 ===>  Cleaning for bison-1.25
 
-Appendix 2. Build logs
+Appendix B. Build logs
 
 Table of Contents
 
-2.1. Building figlet
-2.2. Packaging figlet
+B.1. Building figlet
+B.2. Packaging figlet
 
-2.1. Building figlet
+B.1. Building figlet
 
 # make
 ===> Checking for vulnerabilities in figlet-2.2.1nb2
@@ -5545,7 +5550,7 @@ cp figlet.6 /usr/pkg/man/man6
 ===> Registering installation for figlet-2.2.1nb2
 #
 
-2.2. Packaging figlet
+B.2. Packaging figlet
 
 # make package
 ===> Checking for vulnerabilities in figlet-2.2.1nb2
@@ -5556,7 +5561,7 @@ Using SrcDir value of /usr/pkg
 Registering depends:.
 #
 
-Appendix 3. Layout of the FTP server's package archive
+Appendix C. Layout of the FTP server's package archive
 
 Layout for precompiled binary packages on ftp.NetBSD.org:
 
@@ -5634,16 +5639,16 @@ To create:
  3. If necessary, create a symlink ln -s `uname -m` `uname -p` (amiga -> m68k,
     ...)
 
-Appendix 4. Editing guidelines for the pkgsrc guide
+Appendix D. Editing guidelines for the pkgsrc guide
 
 Table of Contents
 
-4.1. Targets
-4.2. Procedure
+D.1. Targets
+D.2. Procedure
 
 This section contains information on editing the pkgsrc guide itself.
 
-4.1. Targets
+D.1. Targets
 
 The pkgsrc guide's source code is stored in pkgsrc/doc/guide/files, and several
 files are created from it:
@@ -5663,7 +5668,7 @@ files are created from it:
   * http://www.NetBSD.org/Documentation/pkgsrc/pkgsrc.ps: PostScript version of
     the pkgsrc guide.
 
-4.2. Procedure
+D.2. Procedure
 
 The procedure to edit the pkgsrc guide is: