[pkgsrc/trunk]: pkgsrc/doc/guide/files Document PKGNAME_NOREV. Use more marku...

[wiz <wiz%pkgsrc.org@localhost>]

details:   https://anonhg.NetBSD.org/pkgsrc/rev/e6a91d96ef77
branches:  trunk
changeset: 518473:e6a91d96ef77
user:      wiz <wiz%pkgsrc.org@localhost>
date:      Sun Sep 10 19:27:34 2006 +0000

description:
Document PKGNAME_NOREV. Use more markup. Improve DIST_SUBDIR
description. Add section about programming languages. Describe
UNLIMIT_RESOURCES. Avoid extra whitespace in <para>.
Add section about emulation packages.
Add section about BROKEN and BROKEN_IN.

diffstat:

 doc/guide/files/fixes.xml |  2667 +++++++++++++++++++++++---------------------
 1 files changed, 1388 insertions(+), 1279 deletions(-)

diffs (truncated from 2984 to 300 lines):

diff -r 857096882768 -r e6a91d96ef77 doc/guide/files/fixes.xml
--- a/doc/guide/files/fixes.xml Sun Sep 10 19:11:15 2006 +0000
+++ b/doc/guide/files/fixes.xml Sun Sep 10 19:27:34 2006 +0000
@@ -1,952 +1,1036 @@
-<!-- $NetBSD: fixes.xml,v 1.70 2006/09/03 10:54:55 jmmv Exp $ -->
+<!-- $NetBSD: fixes.xml,v 1.71 2006/09/10 19:27:34 wiz Exp $ -->
 
 <chapter id="fixes"> <?dbhtml filename="fixes.html"?>
-  <title>Making your package work</title>
+<title>Making your package work</title>
 
-  <sect1 id="general-operation">
-    <title>General operation</title>
+<sect1 id="general-operation">
+  <title>General operation</title>
 
-<sect2 id="portability-of-packages">
-<title>Portability of packages</title>
+  <sect2 id="portability-of-packages">
+    <title>Portability of packages</title>
 
-       <para>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. This
-       chapter mentions some particular details you should pay
-       attention to while working on pkgsrc.</para>
+    <para>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. This
+    chapter mentions some particular details you should pay
+    attention to while working on pkgsrc.</para>
 
-</sect2>
+  </sect2>
 
-    <sect2 id="pulling-vars-from-etc-mk.conf">
-      <title>How to pull in user-settable variables from <filename>mk.conf</filename></title>
+  <sect2 id="pulling-vars-from-etc-mk.conf">
+    <title>How to pull in user-settable variables from <filename>mk.conf</filename></title>
 
-       <para>The pkgsrc user can configure pkgsrc by overriding several
-       variables in the file pointed to by <varname>MAKECONF</varname>,
-       which is <filename>/etc/mk.conf</filename> by default. When you
-       want to use those variables in the preprocessor directives of
-       &man.make.1; (for example <literal>.if</literal> or
-       <literal>.for</literal>), you need to include the file
-       <filename>../../mk/bsd.prefs.mk</filename> before, which in turn
-       loads the user preferences.</para>
+    <para>The pkgsrc user can configure pkgsrc by overriding several
+    variables in the file pointed to by <varname>MAKECONF</varname>,
+    which is <filename>/etc/mk.conf</filename> by default. When you
+    want to use those variables in the preprocessor directives of
+    &man.make.1; (for example <literal>.if</literal> or
+    <literal>.for</literal>), you need to include the file
+    <filename>../../mk/bsd.prefs.mk</filename> before, which in turn
+    loads the user preferences.</para>
 
-       <para>But note that some variables may not be completely defined
-       after <filename>../../mk/bsd.prefs.mk</filename> has been
-       included, as they may contain references to variables that are
-       not yet defined. In shell commands this is no problem, since
-       variables are actually macros, which are only expanded when they
-       are used. But in the preprocessor directives mentioned above and
-       in dependency lines (of the form <literal>target:
-       dependencies</literal>) the variables are expanded at load
-       time.</para>
+    <para>But note that some variables may not be completely defined
+    after <filename>../../mk/bsd.prefs.mk</filename> has been
+    included, as they may contain references to variables that are
+    not yet defined. In shell commands this is no problem, since
+    variables are actually macros, which are only expanded when they
+    are used. But in the preprocessor directives mentioned above and
+    in dependency lines (of the form <literal>target:
+    dependencies</literal>) the variables are expanded at load
+    time.</para>
 
-       <note><para>Currently there is no exhaustive list of all
-       variables that tells you whether they can be used at load time
-       or only at run time, but it is in preparation.</para></note>
+    <note><para>Currently there is no exhaustive list of all
+    variables that tells you whether they can be used at load time
+    or only at run time, but it is in preparation.</para></note>
 
-    </sect2>
+  </sect2>
 
-    <sect2 id="user-interaction">
-      <title>User interaction</title>
+  <sect2 id="user-interaction">
+    <title>User interaction</title>
 
-      <para>Occasionally, packages require interaction from the user, and this can be
-        in a number of ways:</para>
+    <para>Occasionally, packages require interaction from the user, and this can be
+    in a number of ways:</para>
 
-      <itemizedlist>
+    <itemizedlist>
 
-       <listitem>
-         <para>When fetching the distfiles, some packages require user
-         interaction such as entering username/password or accepting a
-         license on a web page.</para>
-       </listitem>
+      <listitem>
+       <para>When fetching the distfiles, some packages require user
+       interaction such as entering username/password or accepting a
+       license on a web page.</para>
+      </listitem>
 
-       <listitem>
-         <para>When extracting the distfiles, some packages may ask for passwords.</para>
-       </listitem>
+      <listitem>
+       <para>When extracting the distfiles, some packages may ask for passwords.</para>
+      </listitem>
 
-        <listitem>
-          <para>help to configure the package before it is built</para>
-        </listitem>
+      <listitem>
+       <para>help to configure the package before it is built</para>
+      </listitem>
 
-        <listitem>
-          <para>help during the build process</para>
-        </listitem>
+      <listitem>
+       <para>help during the build process</para>
+      </listitem>
 
-        <listitem>
-          <para>help during the installation of a package</para>
-        </listitem>
-      </itemizedlist>
+      <listitem>
+       <para>help during the installation of a package</para>
+      </listitem>
+    </itemizedlist>
 
-      <para>The <varname>INTERACTIVE_STAGE</varname> definition is provided to notify
-        the pkgsrc mechanism of an interactive stage which will be needed, and
-        this should be set in the package's <filename>Makefile</filename>, e.g.:</para>
+    <para>The <varname>INTERACTIVE_STAGE</varname> definition is provided to notify
+    the pkgsrc mechanism of an interactive stage which will be needed, and
+    this should be set in the package's <filename>Makefile</filename>, e.g.:</para>
 
-<programlisting>
-    INTERACTIVE_STAGE=      build
-</programlisting>
+    <programlisting>
+      INTERACTIVE_STAGE=      build
+    </programlisting>
 
-      <para>Multiple interactive stages can be specified:</para>
+    <para>Multiple interactive stages can be specified:</para>
 
-<programlisting>
-    INTERACTIVE_STAGE=      configure install
-</programlisting>
+    <programlisting>
+      INTERACTIVE_STAGE=      configure install
+    </programlisting>
 
-    </sect2>
+  </sect2>
 
-    <sect2 id="handling-licenses">
-      <title>Handling licenses</title>
+  <sect2 id="handling-licenses">
+    <title>Handling licenses</title>
 
-      <para>A package may be covered by a license which the user has
-        or has not agreed to accept.  For these cases, pkgsrc contains
-        a mechanism to note that a package is covered by a particular
-        license, and the package cannot be built unless the user has
-        accepted the license.  (Installation of binary packages are
-        not currently subject to this mechanism.)  Packages with
-        licenses that are either Open Source according to the Open
-        Source Initiative or Free according to the Free Software
-        Foundation will not be marked with a license tag.  Packages
-        with licenses that have not been determined to meet either
-        definition will be marked with a license tag referring to the
-        license.  This will prevent building unless pkgsrc is informed
-        that the license is acceptable, and enables displaying the
-        license.</para>
+    <para>A package may be covered by a license which the user has
+    or has not agreed to accept.  For these cases, pkgsrc contains
+    a mechanism to note that a package is covered by a particular
+    license, and the package cannot be built unless the user has
+    accepted the license.  (Installation of binary packages are
+    not currently subject to this mechanism.)  Packages with
+    licenses that are either Open Source according to the Open
+    Source Initiative or Free according to the Free Software
+    Foundation will not be marked with a license tag.  Packages
+    with licenses that have not been determined to meet either
+    definition will be marked with a license tag referring to the
+    license.  This will prevent building unless pkgsrc is informed
+    that the license is acceptable, and enables displaying the
+    license.</para>
 
-      <para>The license tag mechanism is intended to address
-       copyright-related issues surrounding building, installing and
-       using a package, and not to address redistribution issues (see
-       <varname>RESTRICTED</varname> and
-       <varname>NO_SRC_ON_FTP</varname>, etc.).  However, the above
-       definition of licenses for which tags are not needed implies
-       that packages with redistribution restrictions should have
-       tags.</para>
+    <para>The license tag mechanism is intended to address
+    copyright-related issues surrounding building, installing and
+    using a package, and not to address redistribution issues (see
+    <varname>RESTRICTED</varname> and
+    <varname>NO_SRC_ON_FTP</varname>, etc.).  However, the above
+    definition of licenses for which tags are not needed implies
+    that packages with redistribution restrictions should have
+    tags.</para>
 
-      <para>
-        Denoting that a package is covered by a particular license is
-        done by placing the license in
-        <filename>pkgsrc/licenses</filename> and setting the
-        <varname>LICENSE</varname> variable to a string identifying
-        the license, e.g. in
-       <filename role="pkg">graphics/xv</filename>: </para>
+    <para>Denoting that a package is covered by a particular license
+    is done by placing the license in
+    <filename>pkgsrc/licenses</filename> and setting the
+    <varname>LICENSE</varname> variable to a string identifying the
+    license, e.g. in <filename
+    role="pkg">graphics/xv</filename>:</para>
 
-<programlisting>
-    LICENSE=        xv-license
-</programlisting>
+    <programlisting>
+      LICENSE=        xv-license
+    </programlisting>
 
-      <para>
-       When trying to build, the user will get a notice that the
-        package is covered by a license which has not been
-        accepted:</para>
+    <para>When trying to build, the user will get a notice that the
+    package is covered by a license which has not been
+    accepted:</para>
 
-<programlisting>
-    &cprompt; <userinput>make</userinput>
-    ===> xv-3.10anb9 has an unacceptable license: xv-license.
-    ===>     To view the license, enter "/usr/bin/make show-license".
-    ===>     To indicate acceptance, add this line to your /etc/mk.conf:
-    ===>     ACCEPTABLE_LICENSES+=xv-license
-    *** Error code 1
-</programlisting>
+    <programlisting>
+      &cprompt; <userinput>make</userinput>
+      ===> xv-3.10anb9 has an unacceptable license: xv-license.
+      ===>     To view the license, enter "/usr/bin/make show-license".
+      ===>     To indicate acceptance, add this line to your /etc/mk.conf:
+      ===>     ACCEPTABLE_LICENSES+=xv-license
+      *** Error code 1
+    </programlisting>
 
-        <para>The license can be viewed with <command>make
-          show-license</command>, and if it is considered appropriate,
-          the line printed above can be added to
-          <filename>/etc/mk.conf</filename> to indicate acceptance of
-          the particular license:</para>
+    <para>The license can be viewed with <command>make
+    show-license</command>, and if it is considered appropriate,
+    the line printed above can be added to
+    <filename>/etc/mk.conf</filename> to indicate acceptance of
+    the particular license:</para>
 
-<programlisting>
-    ACCEPTABLE_LICENSES+=xv-license
-</programlisting>
+    <programlisting>
+      ACCEPTABLE_LICENSES+=xv-license
+    </programlisting>
 
-       <para>When adding a package with a new license, the license
-          text should be added to <filename>pkgsrc/licenses</filename>
-          for displaying. A list of known licenses can be seen in this
-          directory as well as by looking at the list of (commented
-          out) <varname>ACCEPTABLE_LICENSES</varname> variable
-          settings in
-          <filename>pkgsrc/mk/defaults/mk.conf</filename>.</para>
+    <para>When adding a package with a new license, the license
+    text should be added to <filename>pkgsrc/licenses</filename>
+    for displaying. A list of known licenses can be seen in this
+    directory as well as by looking at the list of (commented
+    out) <varname>ACCEPTABLE_LICENSES</varname> variable
+    settings in
+    <filename>pkgsrc/mk/defaults/mk.conf</filename>.</para>
 
-       <para>The use of <varname>LICENSE=shareware</varname>,
-         <varname>LICENSE=no-commercial-use</varname>, and similar
-         language is deprecated because it does not crisply refer to