regen.

1 files changed, 58 insertions, 32 deletions

diff --git a/doc/pkgsrc.txt b/doc/pkgsrc.txt
index 890475895aa..6da7d985a3e 100644
--- a/doc/pkgsrc.txt
+++ b/doc/pkgsrc.txt
@@ -199,7 +199,7 @@ II. The pkgsrc developer's guide
         14.2. Main targets
         14.3. Other helpful targets
 
-    15. Notes on fixes for packages
+    15. Making your package work
 
         15.1. General operation
 
@@ -228,7 +228,7 @@ II. The pkgsrc developer's guide
             15.3.2. Using libtool on GNU packages that already support libtool
             15.3.3. GNU Autoconf/Automake
 
-        15.4. Building considerations
+        15.4. Building the package
 
             15.4.1. CPP defines
             15.4.2. Getting a list of CPP defines
@@ -2150,7 +2150,7 @@ Table of Contents
     11.2. Writing buildlink3.mk files
 
         11.2.1. Anatomy of a buildlink3.mk file
-        11.2.2. Updating BUILDLINK_DEPENDS.pkg in buildlink3.mk files
+        11.2.2. Updating BUILDLINK_DEPENDS. pkg in buildlink3.mk files
 
     11.3. Writing builtin.mk files
 
@@ -2192,7 +2192,7 @@ Table of Contents
     14.2. Main targets
     14.3. Other helpful targets
 
-15. Notes on fixes for packages
+15. Making your package work
 
     15.1. General operation
 
@@ -2220,7 +2220,7 @@ Table of Contents
         15.3.2. Using libtool on GNU packages that already support libtool
         15.3.3. GNU Autoconf/Automake
 
-    15.4. Building considerations
+    15.4. Building the package
 
         15.4.1. CPP defines
         15.4.2. Getting a list of CPP defines
@@ -3139,8 +3139,8 @@ dependency on pkg is added. Several important variables are set in the section:
     is selected by setting BUILDLINK_DEPMETHOD.pkg to "build". By default, the
     full dependency is used.
 
-  * BUILDLINK_INCDIRS.pkg and BUILDLINK_LIBDIRS.pkg (not shown above) are lists
-    of subdirectories of ${BUILDLINK_PREFIX.pkg} to add to the header and
+  * BUILDLINK_INCDIRS.pkg and BUILDLINK_LIBDIRS. pkg (not shown above) are
+    lists of subdirectories of ${BUILDLINK_PREFIX.pkg} to add to the header and
     library search paths. These default to "include" and "lib" respectively.
 
   * BUILDLINK_CPPFLAGS.pkg (not shown above) is the list of preprocessor flags
@@ -3179,7 +3179,7 @@ dependencies. Including these buildlink3.mk files means that the headers and
 libraries for these dependencies are also symlinked into ${BUILDLINK_DIR}
 whenever the pkg buildlink3.mk file is included.
 
-11.2.2. Updating BUILDLINK_DEPENDS.pkg in buildlink3.mk files
+11.2.2. Updating BUILDLINK_DEPENDS. pkg in buildlink3.mk files
 
 There are two situations that require increasing the dependency listed in
 BUILDLINK_DEPENDS.pkg after a package update:
@@ -3198,9 +3198,9 @@ settle for an older one which will not contain the necessary shared libraries.
 
 Please take careful consideration before adjusting BUILDLINK_DEPENDS.pkg as we
 don't want to cause unneeded package deletions and rebuilds. In many cases, new
-versions of packages work just fine with older dependencies. See
-Section 15.1.4, "Handling dependencies" for more information about dependencies
-on other packages, including the BUILDLINK_RECOMMENDED and RECOMMENDED
+versions of packages work just fine with older dependencies. See Section
+15.1.4, "Handling dependencies" for more information about dependencies on
+other packages, including the BUILDLINK_RECOMMENDED and RECOMMENDED
 definitions.
 
 11.3. Writing builtin.mk files
@@ -3514,9 +3514,9 @@ original copies available.
 Once the required configuration files are in place (i.e., under the examples
 hierarchy), the pkginstall framework can use them as master copies during the
 package installation to update what is in ${PKG_SYSCONFDIR}. To achieve this,
-the variables CONF_FILES and CONF_FILES_PERMS are used. Check out
-Section 12.1.2, "File manipulation" for information about their syntax and
-their purpose. Here is an example, taken from the mail/mutt package:
+the variables CONF_FILES and CONF_FILES_PERMS are used. Check out Section
+12.1.2, "File manipulation" for information about their syntax and their
+purpose. Here is an example, taken from the mail/mutt package:
 
     EGDIR=        ${PREFIX}/share/doc/mutt/samples
     CONF_FILES=   ${EGDIR}/Muttrc ${PKG_SYSCONFDIR}/Muttrc
@@ -3713,14 +3713,14 @@ supported by the package, and any default options settings if needed.
  6. PKG_SUGGESTED_OPTIONS is a list of build options which are enabled by
     default.
 
- 7. PKG_OPTIONS_LEGACY_VARS is a list of "USE_VARIABLE:option" pairs that map
+ 7. PKG_OPTIONS_LEGACY_VARS is a list of "USE_VARIABLE: option" pairs that map
     legacy /etc/mk.conf variables to their option counterparts. Pairs should be
     added with "+=" to keep the listing of global legacy variables. A warning
     will be issued if the user uses a legacy variable.
 
- 8. PKG_OPTIONS_LEGACY_OPTS is a list of "old-option:new-option" pairs that map
-    options that have been renamed to their new counterparts. Pairs should be
-    added with "+=" to keep the listing of global legacy options. A warning
+ 8. PKG_OPTIONS_LEGACY_OPTS is a list of "old-option: new-option" pairs that
+    map options that have been renamed to their new counterparts. Pairs should
+    be added with "+=" to keep the listing of global legacy options. A warning
     will be issued if the user uses a legacy option.
 
  9. PKG_LEGACY_OPTIONS is a list of options implied by deprecated variables
@@ -4218,7 +4218,7 @@ bulk-install
 
     Beware that this target may deinstall all packages installed on a system!
 
-Chapter 15. Notes on fixes for packages
+Chapter 15. Making your package work
 
 Table of Contents
 
@@ -4248,7 +4248,7 @@ Table of Contents
     15.3.2. Using libtool on GNU packages that already support libtool
     15.3.3. GNU Autoconf/Automake
 
-15.4. Building considerations
+15.4. Building the package
 
     15.4.1. CPP defines
     15.4.2. Getting a list of CPP defines
@@ -4783,28 +4783,54 @@ automake sequence. This is prevented by touching various files in the configure
 stage. If this causes problems with your package you can set AUTOMAKE_OVERRIDE=
 NO in the package Makefile.
 
-15.4. Building considerations
+15.4. Building the package
 
 15.4.1. CPP defines
 
-To port an application to NetBSD, it's usually necessary for the compiler to be
-able to judge the system on which it's compiling, and we use definitions so
-that the C pre-processor can do this.
+Sometimes you need to compile different code depending on the target platform.
+The C preprocessor has a set of predefined macros that can be queried by using
+#ifdef FOO or #if defined(FOO). Among these macros are usually ones that
+describe the target CPU and operating system. Depending of which of the macros
+are defined, you can write code that uses features unique to a specific
+platform. The best way to handle these differences is to use the GNU autotools
+(automake, autoconf, etc.) to check for specific features (like the existence
+of a header file, a function or a library).
 
-To test whether you are working on a 4.4 BSD-derived system, you should use the
-BSD definition, which is defined in <sys/param.h> on said systems.
+If that is not possible you can use the predefined macros below to configure
+your code to the platform it runs on. Almost every operating system, hardware
+architecture and compiler has its own macro. For example, if the macros
+__GNUC__, __i386__ and __NetBSD__ are all defined, you know that you are using
+NetBSD on an Intel CPU, and your compiler is GCC.
 
-    #include <sys/param.h>
+15.4.1.1. CPP defines for operating systems
 
-and then you can surround the BSD-specific parts of your package's C/C++ code
-using this conditional:
+To distinguish between 4.4 BSD-derived systems and the rest of the world, you
+should use the following code.
 
+    #include <sys/param.h>
     #if (defined(BSD) && BSD >= 199306)
-    ...
+      /* your BSD-specific code goes here */
+    #else
+      /* non-BSD-specific code */
     #endif
 
-Please use the "__NetBSD__" definition sparingly - it should only apply to
-features of NetBSD that are not present in other 4.4-lite-derived BSDs.
+If this distinction is not fine enough, you can also use the following defines.
+
+    FreeBSD     __FreeBSD__
+    Linux       linux, __linux, __linux__
+    NetBSD      __NetBSD__
+    OpenBSD     __OpenBSD__
+    Solaris     sun, __sun (GCC and SunPro), __sun__ (only GCC)
+
+15.4.1.2. CPP defines for CPUs
+
+    i386        i386, __i386, __i386__
+    MIPS        __mips
+    SPARC       sparc, __sparc
+
+15.4.1.3. CPP defines for compilers
+
+    GCC         __GNUC__ (major version), __GNUC_MINOR__
 
 15.4.2. Getting a list of CPP defines