regen for upstream patch admonition.

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

1 files changed, 50 insertions, 45 deletions

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: