Document where documentation should be installed.

3 files changed, 131 insertions, 82 deletions

diff --git a/doc/guide/files/fixes.xml b/doc/guide/files/fixes.xml
index f99bc8b5a37..2ab4c6d77a0 100644
--- a/doc/guide/files/fixes.xml
+++ b/doc/guide/files/fixes.xml
@@ -1,4 +1,4 @@
-<!-- $NetBSD: fixes.xml,v 1.15 2005/05/24 12:14:42 wiz Exp $ -->
+<!-- $NetBSD: fixes.xml,v 1.16 2005/05/26 16:32:42 wiz Exp $ -->
 
 <chapter id="fixes"> <?dbhtml filename="fixes.html"?>
   <title>Notes on fixes for packages</title>
@@ -44,6 +44,14 @@
         optimization for the current CPU.  </para>
     </sect2>
 
+    <sect2 id="where-to-install-documentation">
+      <title>Where to install documentation</title>
+
+      <para> Documentation should be installed into
+      <filename>${PREFIX}/share/doc/${PKGBASE}</filename> or
+      <filename>${PREFIX}/share/doc/${PKGNAME}</filename> (the
+      latter includes the version number of the package). </para>
+    </sect2>
 
     <sect2 id="restricted-packages">
       <title>Restricted packages</title>
diff --git a/doc/pkgsrc.html b/doc/pkgsrc.html
index e113fa3f7ea..b85beaeb3a5 100644
--- a/doc/pkgsrc.html
+++ b/doc/pkgsrc.html
@@ -591,41 +591,45 @@ alink="#0000FF">
                     /etc/mk.conf</a></span></dt>
 
                     <dt><span class="sect2"><a href=
-                    "#restricted-packages">13.1.2. Restricted
+                    "#where-to-install-documentation">13.1.2. Where
+                    to install documentation</a></span></dt>
+
+                    <dt><span class="sect2"><a href=
+                    "#restricted-packages">13.1.3. Restricted
                     packages</a></span></dt>
 
                     <dt><span class="sect2"><a href=
-                    "#dependencies">13.1.3. Handling
+                    "#dependencies">13.1.4. Handling
                     dependencies</a></span></dt>
 
                     <dt><span class="sect2"><a href=
-                    "#conflicts">13.1.4. Handling conflicts with
+                    "#conflicts">13.1.5. Handling conflicts with
                     other packages</a></span></dt>
 
                     <dt><span class="sect2"><a href=
-                    "#not-building-packages">13.1.5. Packages that
+                    "#not-building-packages">13.1.6. Packages that
                     cannot or should not be built</a></span></dt>
 
                     <dt><span class="sect2"><a href=
-                    "#undeletable-packages">13.1.6. Packages which
+                    "#undeletable-packages">13.1.7. Packages which
                     should not be deleted, once
                     installed</a></span></dt>
 
                     <dt><span class="sect2"><a href=
-                    "#security-handling">13.1.7. Handling packages
+                    "#security-handling">13.1.8. Handling packages
                     with security problems</a></span></dt>
 
                     <dt><span class="sect2"><a href=
-                    "#compiler-bugs">13.1.8. How to handle compiler
+                    "#compiler-bugs">13.1.9. How to handle compiler
                     bugs</a></span></dt>
 
                     <dt><span class="sect2"><a href=
-                    "#bumping-pkgrevision">13.1.9. How to handle
+                    "#bumping-pkgrevision">13.1.10. How to handle
                     incrementing versions when fixing an existing
                     package</a></span></dt>
 
                     <dt><span class="sect2"><a href=
-                    "#portability-of-packages">13.1.10. Portability
+                    "#portability-of-packages">13.1.11. Portability
                     of packages</a></span></dt>
                   </dl>
                 </dd>
@@ -5117,41 +5121,45 @@ CONF_FILES=   ${EGDIR}/Muttrc ${PKG_SYSCONFDIR}/Muttrc
                   /etc/mk.conf</a></span></dt>
 
                   <dt><span class="sect2"><a href=
-                  "#restricted-packages">13.1.2. Restricted
+                  "#where-to-install-documentation">13.1.2. Where
+                  to install documentation</a></span></dt>
+
+                  <dt><span class="sect2"><a href=
+                  "#restricted-packages">13.1.3. Restricted
                   packages</a></span></dt>
 
                   <dt><span class="sect2"><a href=
-                  "#dependencies">13.1.3. Handling
+                  "#dependencies">13.1.4. Handling
                   dependencies</a></span></dt>
 
                   <dt><span class="sect2"><a href=
-                  "#conflicts">13.1.4. Handling conflicts with
+                  "#conflicts">13.1.5. Handling conflicts with
                   other packages</a></span></dt>
 
                   <dt><span class="sect2"><a href=
-                  "#not-building-packages">13.1.5. Packages that
+                  "#not-building-packages">13.1.6. Packages that
                   cannot or should not be built</a></span></dt>
 
                   <dt><span class="sect2"><a href=
-                  "#undeletable-packages">13.1.6. Packages which
+                  "#undeletable-packages">13.1.7. Packages which
                   should not be deleted, once
                   installed</a></span></dt>
 
                   <dt><span class="sect2"><a href=
-                  "#security-handling">13.1.7. Handling packages
+                  "#security-handling">13.1.8. Handling packages
                   with security problems</a></span></dt>
 
                   <dt><span class="sect2"><a href=
-                  "#compiler-bugs">13.1.8. How to handle compiler
+                  "#compiler-bugs">13.1.9. How to handle compiler
                   bugs</a></span></dt>
 
                   <dt><span class="sect2"><a href=
-                  "#bumping-pkgrevision">13.1.9. How to handle
+                  "#bumping-pkgrevision">13.1.10. How to handle
                   incrementing versions when fixing an existing
                   package</a></span></dt>
 
                   <dt><span class="sect2"><a href=
-                  "#portability-of-packages">13.1.10. Portability
+                  "#portability-of-packages">13.1.11. Portability
                   of packages</a></span></dt>
                 </dl>
               </dd>
@@ -7507,8 +7515,8 @@ BUILDLINK_DEPTH:=       ${BUILDLINK_DEPTH:S/+$//}
             want to cause unneeded package deletions and rebuilds.
             In many cases, new versions of packages work just fine
             with older dependencies. See <a href="#dependencies"
-            title="13.1.3.&nbsp;Handling dependencies">Section
-            13.1.3, &#8220;Handling dependencies&#8221;</a> and
+            title="13.1.4.&nbsp;Handling dependencies">Section
+            13.1.4, &#8220;Handling dependencies&#8221;</a> and
             <a href="#buildlink" title=
             "Chapter&nbsp;10.&nbsp;Buildlink methodology">Chapter
             10, <i>Buildlink methodology</i></a> for more
@@ -8956,41 +8964,45 @@ make build
                 pull in variables from /etc/mk.conf</a></span></dt>
 
                 <dt><span class="sect2"><a href=
-                "#restricted-packages">13.1.2. Restricted
+                "#where-to-install-documentation">13.1.2. Where to
+                install documentation</a></span></dt>
+
+                <dt><span class="sect2"><a href=
+                "#restricted-packages">13.1.3. Restricted
                 packages</a></span></dt>
 
                 <dt><span class="sect2"><a href=
-                "#dependencies">13.1.3. Handling
+                "#dependencies">13.1.4. Handling
                 dependencies</a></span></dt>
 
                 <dt><span class="sect2"><a href=
-                "#conflicts">13.1.4. Handling conflicts with other
+                "#conflicts">13.1.5. Handling conflicts with other
                 packages</a></span></dt>
 
                 <dt><span class="sect2"><a href=
-                "#not-building-packages">13.1.5. Packages that
+                "#not-building-packages">13.1.6. Packages that
                 cannot or should not be built</a></span></dt>
 
                 <dt><span class="sect2"><a href=
-                "#undeletable-packages">13.1.6. Packages which
+                "#undeletable-packages">13.1.7. Packages which
                 should not be deleted, once
                 installed</a></span></dt>
 
                 <dt><span class="sect2"><a href=
-                "#security-handling">13.1.7. Handling packages with
+                "#security-handling">13.1.8. Handling packages with
                 security problems</a></span></dt>
 
                 <dt><span class="sect2"><a href=
-                "#compiler-bugs">13.1.8. How to handle compiler
+                "#compiler-bugs">13.1.9. How to handle compiler
                 bugs</a></span></dt>
 
                 <dt><span class="sect2"><a href=
-                "#bumping-pkgrevision">13.1.9. How to handle
+                "#bumping-pkgrevision">13.1.10. How to handle
                 incrementing versions when fixing an existing
                 package</a></span></dt>
 
                 <dt><span class="sect2"><a href=
-                "#portability-of-packages">13.1.10. Portability of
+                "#portability-of-packages">13.1.11. Portability of
                 packages</a></span></dt>
               </dl>
             </dd>
@@ -9209,9 +9221,28 @@ CFLAGS+=  -your -flags
             <div class="titlepage">
               <div>
                 <div>
+                  <h3 class="title"><a name=
+                  "where-to-install-documentation" id=
+                  "where-to-install-documentation"></a>13.1.2.&nbsp;Where
+                  to install documentation</h3>
+                </div>
+              </div>
+            </div>
+
+            <p>Documentation should be installed into <code class=
+            "filename">${PREFIX}/share/doc/${PKGBASE}</code> or
+            <code class=
+            "filename">${PREFIX}/share/doc/${PKGNAME}</code> (the
+            latter includes the version number of the package).</p>
+          </div>
+
+          <div class="sect2" lang="en" xml:lang="en">
+            <div class="titlepage">
+              <div>
+                <div>
                   <h3 class="title"><a name="restricted-packages"
                   id=
-                  "restricted-packages"></a>13.1.2.&nbsp;Restricted
+                  "restricted-packages"></a>13.1.3.&nbsp;Restricted
                   packages</h3>
                 </div>
               </div>
@@ -9290,7 +9321,7 @@ CFLAGS+=  -your -flags
               <div>
                 <div>
                   <h3 class="title"><a name="dependencies" id=
-                  "dependencies"></a>13.1.3.&nbsp;Handling
+                  "dependencies"></a>13.1.4.&nbsp;Handling
                   dependencies</h3>
                 </div>
               </div>
@@ -9443,8 +9474,8 @@ RECOMMENDED+=   tiff&gt;=3.6.1:../../graphics/tiff
                   vulnerabilities file as well as setting
                   <code class="varname">RECOMMENDED</code>, see
                   <a href="#security-handling" title=
-                  "13.1.7.&nbsp;Handling packages with security problems">
-                  Section 13.1.7, &#8220;Handling packages with
+                  "13.1.8.&nbsp;Handling packages with security problems">
+                  Section 13.1.8, &#8220;Handling packages with
                   security problems&#8221;</a> for more
                   information.</p>
                 </li>
@@ -9519,7 +9550,7 @@ pre-clean:
               <div>
                 <div>
                   <h3 class="title"><a name="conflicts" id=
-                  "conflicts"></a>13.1.4.&nbsp;Handling conflicts
+                  "conflicts"></a>13.1.5.&nbsp;Handling conflicts
                   with other packages</h3>
                 </div>
               </div>
@@ -9568,7 +9599,7 @@ CONFLICTS=      Xaw3d-[0-9]*
                 <div>
                   <h3 class="title"><a name="not-building-packages"
                   id=
-                  "not-building-packages"></a>13.1.5.&nbsp;Packages
+                  "not-building-packages"></a>13.1.6.&nbsp;Packages
                   that cannot or should not be built</h3>
                 </div>
               </div>
@@ -9601,7 +9632,7 @@ CONFLICTS=      Xaw3d-[0-9]*
                 <div>
                   <h3 class="title"><a name="undeletable-packages"
                   id=
-                  "undeletable-packages"></a>13.1.6.&nbsp;Packages
+                  "undeletable-packages"></a>13.1.7.&nbsp;Packages
                   which should not be deleted, once installed</h3>
                 </div>
               </div>
@@ -9626,7 +9657,7 @@ CONFLICTS=      Xaw3d-[0-9]*
               <div>
                 <div>
                   <h3 class="title"><a name="security-handling" id=
-                  "security-handling"></a>13.1.7.&nbsp;Handling
+                  "security-handling"></a>13.1.8.&nbsp;Handling
                   packages with security problems</h3>
                 </div>
               </div>
@@ -9665,7 +9696,7 @@ CONFLICTS=      Xaw3d-[0-9]*
               <div>
                 <div>
                   <h3 class="title"><a name="compiler-bugs" id=
-                  "compiler-bugs"></a>13.1.8.&nbsp;How to handle
+                  "compiler-bugs"></a>13.1.9.&nbsp;How to handle
                   compiler bugs</h3>
                 </div>
               </div>
@@ -9691,7 +9722,7 @@ CONFLICTS=      Xaw3d-[0-9]*
               <div>
                 <div>
                   <h3 class="title"><a name="bumping-pkgrevision"
-                  id="bumping-pkgrevision"></a>13.1.9.&nbsp;How to
+                  id="bumping-pkgrevision"></a>13.1.10.&nbsp;How to
                   handle incrementing versions when fixing an
                   existing package</h3>
                 </div>
@@ -9733,7 +9764,7 @@ DISTNAME=   foo-17.43
                 <div>
                   <h3 class="title"><a name=
                   "portability-of-packages" id=
-                  "portability-of-packages"></a>13.1.10.&nbsp;Portability
+                  "portability-of-packages"></a>13.1.11.&nbsp;Portability
                   of packages</h3>
                 </div>
               </div>
@@ -9750,7 +9781,7 @@ DISTNAME=   foo-17.43
                 <div>
                   <div>
                     <h4 class="title"><a name="install-scripts" id=
-                    "install-scripts"></a>13.1.10.1.&nbsp;${INSTALL},
+                    "install-scripts"></a>13.1.11.1.&nbsp;${INSTALL},
                     ${INSTALL_DATA_DIR}, ...</h4>
                   </div>
                 </div>
diff --git a/doc/pkgsrc.txt b/doc/pkgsrc.txt
index 773764467d4..0ca4b438423 100644
--- a/doc/pkgsrc.txt
+++ b/doc/pkgsrc.txt
@@ -173,16 +173,17 @@ II. The pkgsrc developer's guide
         13.1. General operation
 
             13.1.1. How to pull in variables from /etc/mk.conf
-            13.1.2. Restricted packages
-            13.1.3. Handling dependencies
-            13.1.4. Handling conflicts with other packages
-            13.1.5. Packages that cannot or should not be built
-            13.1.6. Packages which should not be deleted, once installed
-            13.1.7. Handling packages with security problems
-            13.1.8. How to handle compiler bugs
-            13.1.9. How to handle incrementing versions when fixing an existing
-                package
-            13.1.10. Portability of packages
+            13.1.2. Where to install documentation
+            13.1.3. Restricted packages
+            13.1.4. Handling dependencies
+            13.1.5. Handling conflicts with other packages
+            13.1.6. Packages that cannot or should not be built
+            13.1.7. Packages which should not be deleted, once installed
+            13.1.8. Handling packages with security problems
+            13.1.9. How to handle compiler bugs
+            13.1.10. How to handle incrementing versions when fixing an
+                existing package
+            13.1.11. Portability of packages
 
         13.2. Possible downloading issues
 
@@ -1956,16 +1957,17 @@ Table of Contents
     13.1. General operation
 
         13.1.1. How to pull in variables from /etc/mk.conf
-        13.1.2. Restricted packages
-        13.1.3. Handling dependencies
-        13.1.4. Handling conflicts with other packages
-        13.1.5. Packages that cannot or should not be built
-        13.1.6. Packages which should not be deleted, once installed
-        13.1.7. Handling packages with security problems
-        13.1.8. How to handle compiler bugs
-        13.1.9. How to handle incrementing versions when fixing an existing
+        13.1.2. Where to install documentation
+        13.1.3. Restricted packages
+        13.1.4. Handling dependencies
+        13.1.5. Handling conflicts with other packages
+        13.1.6. Packages that cannot or should not be built
+        13.1.7. Packages which should not be deleted, once installed
+        13.1.8. Handling packages with security problems
+        13.1.9. How to handle compiler bugs
+        13.1.10. How to handle incrementing versions when fixing an existing
             package
-        13.1.10. Portability of packages
+        13.1.11. Portability of packages
 
     13.2. Possible downloading issues
 
@@ -2947,7 +2949,7 @@ 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
-13.1.3, "Handling dependencies" and Chapter 10, Buildlink methodology for more
+13.1.4, "Handling dependencies" and Chapter 10, Buildlink methodology for more
 information about dependencies on other packages, including the
 BUILDLINK_RECOMMENDED and RECOMMENDED definitions.
 
@@ -3615,15 +3617,17 @@ Table of Contents
 13.1. General operation
 
     13.1.1. How to pull in variables from /etc/mk.conf
-    13.1.2. Restricted packages
-    13.1.3. Handling dependencies
-    13.1.4. Handling conflicts with other packages
-    13.1.5. Packages that cannot or should not be built
-    13.1.6. Packages which should not be deleted, once installed
-    13.1.7. Handling packages with security problems
-    13.1.8. How to handle compiler bugs
-    13.1.9. How to handle incrementing versions when fixing an existing package
-    13.1.10. Portability of packages
+    13.1.2. Where to install documentation
+    13.1.3. Restricted packages
+    13.1.4. Handling dependencies
+    13.1.5. Handling conflicts with other packages
+    13.1.6. Packages that cannot or should not be built
+    13.1.7. Packages which should not be deleted, once installed
+    13.1.8. Handling packages with security problems
+    13.1.9. How to handle compiler bugs
+    13.1.10. How to handle incrementing versions when fixing an existing
+        package
+    13.1.11. Portability of packages
 
 13.2. Possible downloading issues
 
@@ -3692,7 +3696,13 @@ Using CFLAGS= (i.e. without the "+") may lead to problems with packages that
 need to add their own flags. Also, you may want to take a look at the devel/
 cpuflags package if you're interested in optimization for the current CPU.
 
-13.1.2. Restricted packages
+13.1.2. Where to install documentation
+
+Documentation should be installed into ${PREFIX}/share/doc/${PKGBASE} or $
+{PREFIX}/share/doc/${PKGNAME} (the latter includes the version number of the
+package).
+
+13.1.3. Restricted packages
 
 Some licenses restrict how software may be re-distributed. In order to satisfy
 these restrictions, the package system defines five make variables that can be
@@ -3731,7 +3741,7 @@ Please note that the use of NO_PACKAGE, IGNORE, NO_CDROM, or other generic make
 variables to denote restrictions is deprecated, because they unconditionally
 prevent users from generating binary packages!
 
-13.1.3. Handling dependencies
+13.1.4. Handling dependencies
 
 Your package may depend on some other package being present - and there are
 various ways of expressing this dependency. pkgsrc supports the BUILD_DEPENDS
@@ -3811,7 +3821,7 @@ version numbers recognized by pkg_info(1).
     different versions of binary packages installed.
 
     For security fixes, please update the package vulnerabilities file as well
-    as setting RECOMMENDED, see Section 13.1.7, "Handling packages with
+    as setting RECOMMENDED, see Section 13.1.8, "Handling packages with
     security problems" for more information.
 
  4. If your package needs some executable to be able to run correctly and if
@@ -3846,7 +3856,7 @@ gettext package. The latter adds a build dependency on either an installed
 version of an older gettext package, or if it isn't, installs the devel/
 gettext-m4 package.
 
-13.1.4. Handling conflicts with other packages
+13.1.5. Handling conflicts with other packages
 
 Your package may conflict with other packages a user might already have
 installed on his system, e.g. if your package installs the same set of files
@@ -3868,7 +3878,7 @@ Packages will automatically conflict with other packages with the name prefix
 and a different version string. "Xaw3d-1.5" e.g. will automatically conflict
 with the older version "Xaw3d-1.3".
 
-13.1.5. Packages that cannot or should not be built
+13.1.6. Packages that cannot or should not be built
 
 There are several reasons why a package might be instructed to not build under
 certain circumstances. If the package builds and runs on most platforms, the
@@ -3882,7 +3892,7 @@ PKG_FAIL_REASON to a descriptive message.
 IGNORE is deprecated because it didn't provide enough information to determine
 whether the build should fail.
 
-13.1.6. Packages which should not be deleted, once installed
+13.1.7. Packages which should not be deleted, once installed
 
 To ensure that a package may not be deleted, once it has been installed, the
 PKG_PRESERVE definition should be set in the package Makefile. This will be
@@ -3890,7 +3900,7 @@ carried into any binary package that is made from this pkgsrc entry. A
 "preserved" package will not be deleted using pkg_delete(1) unless the "-f"
 option is used.
 
-13.1.7. Handling packages with security problems
+13.1.8. Handling packages with security problems
 
 When a vulnerability is found, this should be noted in localsrc/security/
 advisories/pkg-vulnerabilities, and after the commit of that file, it should be
@@ -3905,7 +3915,7 @@ BUILDLINK_* definitions.
 Also, if the fix should be applied to the stable pkgsrc branch, be sure to
 submit a pullup request!
 
-13.1.8. How to handle compiler bugs
+13.1.9. How to handle compiler bugs
 
 Some source files trigger bugs in the compiler, based on combinations of
 compiler version and architecture and almost always relation to optimisation
@@ -3916,7 +3926,7 @@ Typically a workaround involves testing the MACHINE_ARCH and compiler version,
 disabling optimisation for that file/MACHINE_ARCH/compiler combination, and
 documenting it in pkgsrc/doc/HACKS. See that file for a number of examples!
 
-13.1.9. How to handle incrementing versions when fixing an existing package
+13.1.10. How to handle incrementing versions when fixing an existing package
 
 When making fixes to an existing package it can be useful to change the version
 number in PKGNAME. To avoid conflicting with future versions by the original
@@ -3934,14 +3944,14 @@ like:
 
 DISTNAME=   foo-17.43
 
-13.1.10. Portability of packages
+13.1.11. Portability of packages
 
 One appealing feature of pkgsrc is that it runs on many different platforms. As
 a result, it is important to ensure, where possible, that packages in pkgsrc
 are portable. There are some particular details you should pay attention to
 while working on pkgsrc.
 
-13.1.10.1. ${INSTALL}, ${INSTALL_DATA_DIR}, ...
+13.1.11.1. ${INSTALL}, ${INSTALL_DATA_DIR}, ...
 
 The BSD-compatible install supplied with some operating systems will not
 perform more than one operation at a time. As such, you should call "${INSTALL}