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

3 files changed, 59 insertions, 69 deletions

diff --git a/doc/guide/files/devfaq.xml b/doc/guide/files/devfaq.xml
index caa84ae43b4..28935dff82f 100644
--- a/doc/guide/files/devfaq.xml
+++ b/doc/guide/files/devfaq.xml
@@ -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>
-
-</qandaentry>
-<qandaentry id="devfaq.bl3flags">
+	compiler, which can be configured by the pkgsrc user.</para>
 
-	<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>
+	<para><varname>PKG_CC</varname> is the path to the compiler
+	wrapper.</para>
 
-	<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 --git a/doc/guide/files/fixes.xml b/doc/guide/files/fixes.xml
index 61d5852b236..e6372fa03bf 100644
--- a/doc/guide/files/fixes.xml
+++ b/doc/guide/files/fixes.xml
@@ -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 @@ package is built and then pkgsrc is updated. This situation can provoke
 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 @@ far and what any error messages were.</para>
       </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 @@ of functions.</para>
     <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}/dir1
 ${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 @@ ${INSTALL_DATA_DIR} ${PREFIX}/dir2
 
     <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 @@ REPLACE_FILES.tcl=      # list of tcl scripts which need to be fixed,
 # 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 --git a/doc/guide/files/gnome.xml b/doc/guide/files/gnome.xml
index 69031baa60a..52395b82fa2 100644
--- a/doc/guide/files/gnome.xml
+++ b/doc/guide/files/gnome.xml
@@ -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 @@ interested in helping our GNOME porting and packaging efforts.  It
 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 @@ give you a general idea on the minimum required tools:</para>
     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 @@ USE_TOOLS+=gmake
     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 @@ USE_TOOLS+=pkg-config
     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 @@ CONFIGURE_ARGS+=--disable-gtk-doc
     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>