[pkgsrc/trunk]: pkgsrc/doc/guide/files doc/guide: clean up formatting, wordin...

To: pkgsrc-changes-hg%NetBSD.org@localhost
Subject: [pkgsrc/trunk]: pkgsrc/doc/guide/files doc/guide: clean up formatting, wordin...
From: rillig <rillig%pkgsrc.org@localhost>
Date: Thu, 12 May 2022 00:24:34 +0000
details:   https://anonhg.NetBSD.org/pkgsrc/rev/bb51274bae6e
branches:  trunk
changeset: 379130:bb51274bae6e
user:      rillig <rillig%pkgsrc.org@localhost>
date:      Wed May 11 22:48:43 2022 +0000

description:
doc/guide: clean up formatting, wording, obsolete notes

diffstat:

 doc/guide/files/devfaq.xml |  58 +++++++++++++++++++++++----------------------
 doc/guide/files/fixes.xml  |  46 ++++++++++++++++++------------------
 doc/guide/files/gnome.xml  |  26 +++++---------------
 3 files changed, 60 insertions(+), 70 deletions(-)

diffs (275 lines):

diff -r a83963b28a70 -r bb51274bae6e doc/guide/files/devfaq.xml
--- a/doc/guide/files/devfaq.xml        Wed May 11 22:30:17 2022 +0000
+++ b/doc/guide/files/devfaq.xml        Wed May 11 22:48:43 2022 +0000
@@ -1,4 +1,4 @@
-<!-- $NetBSD: devfaq.xml,v 1.16 2020/02/24 21:13:56 rillig Exp $ -->
+<!-- $NetBSD: devfaq.xml,v 1.17 2022/05/11 22:48:43 rillig Exp $ -->
 
 <chapter id="devfaq"> <?dbhtml filename="devfaq.html"?>
 <title>Frequently Asked Questions</title>
@@ -17,10 +17,15 @@
        <varname>MAKE_FLAGS</varname>?</para></question>
 
        <answer><para><varname>MAKEFLAGS</varname> are the flags passed
-       to the pkgsrc-internal invocations of &man.make.1;, while
-       <varname>MAKE_FLAGS</varname> are the flags that are passed to
-       the <varname>MAKE_PROGRAM</varname> when building the
-       package. [FIXME: What is .MAKEFLAGS for?]</para></answer>
+       to the pkgsrc-internal invocations of &man.make.1;.</para>
+
+       <para><varname>MAKE_FLAGS</varname> are the flags that are
+       passed to the <varname>MAKE_PROGRAM</varname> when building the
+       package.</para>
+
+       <para><varname>.MAKEFLAGS</varname> is an internal variable of
+       <command>bmake</command> and should not be used by
+       packages.</para></answer>
 
 </qandaentry>
 <qandaentry id="devfaq.make">
@@ -31,11 +36,14 @@
 
        <answer><para><varname>MAKE</varname> is the path to the
        &man.make.1; program that is used in the pkgsrc
-       infrastructure. <varname>GMAKE</varname> is the path to GNU
-       Make, but you need to say <varname>USE_TOOLS+=gmake</varname> to
-       use that. <varname>MAKE_PROGRAM</varname> is the path to the
-       Make program that is used for building the
-       package.</para></answer>
+       infrastructure.</para>
+
+       <para><varname>GMAKE</varname> is the path to GNU Make, but you
+       need to say <varname>USE_TOOLS+=gmake</varname> to use
+       that.</para>
+
+       <para><varname>MAKE_PROGRAM</varname> is the path to the Make
+       program that is used for building the package.</para></answer>
 
 </qandaentry>
 <qandaentry id="devfaq.cc">
@@ -45,22 +53,16 @@
        <varname>PKGSRC_COMPILER</varname>?</para></question>
 
        <answer><para><varname>CC</varname> is the path to the real C
-       compiler, which can be configured by the pkgsrc user.
-       <varname>PKG_CC</varname> is the path to the compiler wrapper.
-       <varname>PKGSRC_COMPILER</varname> is <emphasis>not</emphasis> a
-       path to a compiler, but the type of compiler that should be
-       used. See <filename>mk/compiler.mk</filename> for more
-       information about the latter variable.</para></answer>
+       compiler, which can be configured by the pkgsrc user.</para>
+
+       <para><varname>PKG_CC</varname> is the path to the compiler
+       wrapper.</para>
 
-</qandaentry>
-<qandaentry id="devfaq.bl3flags">
-
-       <question id="devfaq.bl3flags.q"><para>What is the difference between
-       <varname>BUILDLINK_LDFLAGS</varname>,
-       <varname>BUILDLINK_LDADD</varname> and
-       <varname>BUILDLINK_LIBS</varname>?</para></question>
-
-       <answer><para>[FIXME]</para></answer>
+       <para><varname>PKGSRC_COMPILER</varname> is
+       <emphasis>not</emphasis> a path to a compiler, but the type of
+       compiler that should be used. See
+       <filename>mk/compiler.mk</filename> for more information about
+       the latter variable.</para></answer>
 
 </qandaentry>
 <qandaentry id="devfaq.bl3prefix">
@@ -83,8 +85,8 @@
        don't understand the <code>:=</code> inside
        it.</para></question>
 
-       <answer><para>The <code>:=</code> is not really an
-       assignment operator, although it looks like it.
+       <answer><para>The <code>:=</code> is not an
+       assignment operator, even though it may look like one.
        Instead, it is a degenerate form of
        <code>${LIST:<replaceable>old_string</replaceable>=<replaceable>new_string</replaceable>}</code>,
        which is documented in the &man.make.1; man page and which is
@@ -181,7 +183,7 @@
 </qandaentry>
 
 <qandaentry id="devfaq.too-much-time">
-<question id="devfaq.too-much-time.q"><para>I have a little time to kill. 
+<question id="devfaq.too-much-time.q"><para>I have a little time to kill.
 What shall I do?</para></question>
 
 <answer><para>This is not really an FAQ yet, but here's the answer
diff -r a83963b28a70 -r bb51274bae6e doc/guide/files/fixes.xml
--- a/doc/guide/files/fixes.xml Wed May 11 22:30:17 2022 +0000
+++ b/doc/guide/files/fixes.xml Wed May 11 22:48:43 2022 +0000
@@ -1,4 +1,4 @@
-<!-- $NetBSD: fixes.xml,v 1.169 2022/05/11 22:10:50 rillig Exp $ -->
+<!-- $NetBSD: fixes.xml,v 1.170 2022/05/11 22:48:43 rillig Exp $ -->
 
 <chapter id="fixes"> <?dbhtml filename="fixes.html"?>
 <title>Making your package work</title>
@@ -1783,11 +1783,11 @@
 various hard to diagnose build errors. To clean up the situation:</para>
 
 <programlisting>
-&uprompt; (cd ../../ && test -f mk/bsd.pkg.mk && rm -rf */*/work)
+&uprompt; (cd ../../ && cat mk/bsd.pkg.mk >/dev/null && rm -rf */*/work)
 </programlisting>
 
-<para>(The test for <filename>bsd.pkg.mk</filename> just prevents running
-this command in the wrong directory.)</para>
+<para>(The only purpose of the <filename>bsd.pkg.mk</filename> is to
+prevent running this command in the wrong directory.)</para>
 
 <para>If you have set <varname>WRKOBJDIR</varname> in &mk.conf;, remove
 that directory as well.</para>
@@ -1841,14 +1841,14 @@
       </tgroup>
     </informaltable>
 
-    <para>To fix these linker errors, it is often sufficient to say
+    <para>To fix these linker errors, it is often sufficient to add
     <literal>LIBS.<replaceable>OperatingSystem</replaceable>+=
     -l<replaceable>foo</replaceable></literal> to the package
-    <filename>Makefile</filename> and then say <command>bmake clean;
+    <filename>Makefile</filename> and then run <command>bmake clean;
     bmake</command>.</para>
 
 <sect3 id="undefined-reference-sunpro">
-<title>Special issue: The SunPro compiler</title>
+<title>The SunPro compiler and inline functions</title>
 
 <para>When you are using the SunPro compiler, there is another
 possibility. That compiler cannot handle the following code:</para>
@@ -1884,9 +1884,12 @@
     <para>Sometimes packages fail to build because the compiler runs
     into an operating system specific soft limit.  With the
     <varname>UNLIMIT_RESOURCES</varname> variable pkgsrc can be told
-    to unlimit the resources.  Currently, the allowed values are any combination of
-    <quote>cputime</quote>, <quote>datasize</quote>,
-    <quote>memorysize</quote>, and <quote>stacksize</quote>.
+    to unlimit the resources.  The allowed values are any combination of
+    <quote>cputime</quote>,
+    <quote>datasize</quote>,
+    <quote>memorysize</quote>,
+    <quote>stacksize</quote> and
+    <quote>virtualsize</quote>.
     Setting this variable is similar to running the shell builtin
     <command>ulimit</command> command to raise the maximum data
     segment size or maximum stack size of a process, respectively, to
@@ -1910,10 +1913,10 @@
 ${INSTALL_DATA_DIR} ${PREFIX}/dir2
 </programlisting>
 
-    <para>You can also just append <quote><literal>dir1
-    dir2</literal></quote> to the
-    <varname>INSTALLATION_DIRS</varname> variable, which will
-    automatically do the right thing.</para>
+    <para>Instead of running the <command>install</command> commands
+    directly, you can also append <quote><literal>dir1
+    dir2</literal></quote> to the <varname>INSTALLATION_DIRS</varname>
+    variable, which will automatically do the right thing.</para>
 
   </sect2>
   <sect2 id="where-to-install-documentation">
@@ -1921,15 +1924,16 @@
 
     <para>In general, documentation should be installed into
     <filename>${PREFIX}/share/doc/${PKGBASE}</filename> or
-    <filename>${PREFIX}/share/doc/${PKGNAME}</filename> (the latter
+    <filename>${PREFIX}/share/doc/${PKGNAME_NOREV}</filename> (the latter
     includes the version number of the package).</para>
 
     <para>Many modern packages using GNU autoconf allow to set the
     directory where HTML documentation is installed with the
-    <quote>--with-html-dir</quote> option. Sometimes using this flag
-    is needed because otherwise the documentation ends up in
-    <filename>${PREFIX}/share/doc/html</filename> or other
-    places.</para>
+    <quote>--with-html-dir</quote> option. Sometimes using this flag is
+    needed because otherwise the documentation ends up in
+    <filename>${PREFIX}/share/doc/html</filename> or other places. In
+    pkgsrc, the HTML documentation should go into the package-specific
+    directory, just like any other documentation.</para>
 
     <para>An exception to the above is that library API documentation
     generated with the <filename
@@ -2053,10 +2057,6 @@
 # relative to ${WRKSRC}, just as in REPLACE_PERL
 </programlisting>
 
-    <note><para>Before March 2006, these variables were called
-    <varname>_REPLACE.*</varname> and
-    <varname>_REPLACE_FILES.*</varname>.</para></note>
-
   </sect2>
 
 
diff -r a83963b28a70 -r bb51274bae6e doc/guide/files/gnome.xml
--- a/doc/guide/files/gnome.xml Wed May 11 22:30:17 2022 +0000
+++ b/doc/guide/files/gnome.xml Wed May 11 22:48:43 2022 +0000
@@ -1,4 +1,4 @@
-<!-- $NetBSD: gnome.xml,v 1.14 2021/06/11 15:09:51 nia Exp $ -->
+<!-- $NetBSD: gnome.xml,v 1.15 2022/05/11 22:48:43 rillig Exp $ -->
 
 <chapter id="gnome"> <?dbhtml filename="gnome.html"?>
 <title>GNOME packaging and porting</title>
@@ -32,18 +32,6 @@
 provides instructions on how to manage the existing packages and some
 important information regarding their internals.</para>
 
-<note>
-  <title>We need your help!</title>
-
-  <para>Should you have some spare cycles to devote to NetBSD, pkgsrc
-  and GNOME and are willing to learn new exciting stuff, please jump
-  straight to the <ulink
-  url="https://www.NetBSD.org/contrib/projects.html#gnome";>pending
-  work</ulink> list!  There is still a long way to go to get a
-  fully-functional GNOME desktop under NetBSD and we need your help to
-  achieve it!</para>
-</note>
-
 <sect1 id="meta-packages">
 <title>Meta packages</title>
 
@@ -106,9 +94,9 @@
     package:</para>
 
 <programlisting>
-GNU_CONFIGURE=yes
-USE_LIBTOOL=yes
-USE_TOOLS+=gmake
+GNU_CONFIGURE=  yes
+USE_LIBTOOL=    yes
+USE_TOOLS+=     gmake
 </programlisting>
   </listitem>
 
@@ -117,7 +105,7 @@
     tool to the list of required utilities:</para>
 
 <programlisting>
-USE_TOOLS+=pkg-config
+USE_TOOLS+=     pkg-config
 </programlisting>
 
     <para>Also use <filename role="pkg">pkgtools/verifypc</filename> at
@@ -142,7 +130,7 @@
     the default):</para>
 
 <programlisting>
-CONFIGURE_ARGS+=--disable-gtk-doc
+CONFIGURE_ARGS+=        --disable-gtk-doc
 </programlisting>
 
     <para>The default location of installed HTML files
@@ -153,7 +141,7 @@
     do that with an entry similar to:</para>
 
 <programlisting>
-CONFIGURE_ARGS+=--with-html-dir=${PREFIX}/share/gtk-doc/...
+CONFIGURE_ARGS+=        --with-html-dir=${PREFIX}/share/gtk-doc/...
 </programlisting>
 
   </listitem>
Prev by Date: [pkgsrc/trunk]: pkgsrc/audio/py-music21 py-music21: update to 7.3.3
Next by Date: [pkgsrc/trunk]: pkgsrc/doc doc: Updated audio/py-music21 to 7.3.3
Previous by Thread: [pkgsrc/trunk]: pkgsrc/audio/py-music21 py-music21: update to 7.3.3
Next by Thread: [pkgsrc/trunk]: pkgsrc/doc doc: Updated audio/py-music21 to 7.3.3
Indexes:
Home | Main Index | Thread Index | Old Index