Removed unnecessary complexity and super-special corner cases from the

documentation.

7 files changed, 45 insertions, 140 deletions

diff --git a/doc/guide/files/components.xml b/doc/guide/files/components.xml
index c3b28680675..43a25729ffc 100644
--- a/doc/guide/files/components.xml
+++ b/doc/guide/files/components.xml
@@ -1,4 +1,4 @@
-<!-- $NetBSD: components.xml,v 1.51 2015/07/04 16:12:54 joerg Exp $ -->
+<!-- $NetBSD: components.xml,v 1.52 2016/06/11 14:58:26 rillig Exp $ -->
 
 <chapter id="components"> <?dbhtml filename="components.html"?>
 <title>Package components - files, directories and contents</title>
@@ -190,9 +190,9 @@ converters    games         mbone         print         x11
   digest, or checksum, of each distfile needed for the package. This
   ensures that the distfiles retrieved from the Internet have not been
   corrupted during transfer or altered by a malign force to introduce
-  a security hole. Due to recent rumor about weaknesses of digest
-  algorithms, all distfiles are protected using both SHA1 and RMD160
-  message digests, as well as the file size.</para>
+  a security hole. To provide maximum security, all distfiles are
+  protected using three different message digest algorithms (SHA1,
+  RMD160, SHA512), as well as the file size.</para>
 
   <para>The <filename>distinfo</filename> file also contains the
   checksums for all the patches found in the
@@ -200,8 +200,7 @@ converters    games         mbone         print         x11
   linkend="components.patches"/>).</para>
 
   <para>To regenerate the <filename>distinfo</filename> file, use the
-  <command>make makedistinfo</command> or <command>make mdi</command>
-  command.</para>
+  <command>make distinfo</command> command.</para>
 
   <para>Some packages have different sets of distfiles depending on
   the platform, for example <filename
@@ -213,18 +212,16 @@ converters    games         mbone         print         x11
 </sect1>
 
 <sect1 id="components.patches">
-  <title>patches/*</title>
+  <title><filename>patches/*</filename></title>
 
-  <para>Many packages still don't work out-of-the box on the various
-  platforms that are supported by pkgsrc. Therefore, a number of custom
-  patch files are needed to make the package work. These patch files are
+  <para>Some packages don't work out-of-the box on the various
+  platforms that are supported by pkgsrc. These packages need
+  to be patched to make them work. The patch files can be
   found in the <filename>patches/</filename> directory.</para>
 
   <para>In the <emphasis>patch</emphasis> phase, these patches are
   applied to the files in <varname>WRKSRC</varname> directory after
-  extracting them, in <ulink
-  url="http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#tag_02_13_03">alphabetic
-  order</ulink>.</para>
+  extracting them, in alphabetic order.</para>
 
 <sect2 id="components.patch.structure">
 <title>Structure of a single patch file</title>
@@ -254,7 +251,7 @@ converters    games         mbone         print         x11
 
   </itemizedlist>
 
-  <para>In all, the patch should be commented so that any
+  <para>The patch should be commented so that any
   developer who knows the code of the application can make some use of
   the patch. Special care should be taken for the upstream developers,
   since we generally want that they accept our patches, so we have less
diff --git a/doc/guide/files/configuring.xml b/doc/guide/files/configuring.xml
index 0f88e8341bb..129ccf57c38 100644
--- a/doc/guide/files/configuring.xml
+++ b/doc/guide/files/configuring.xml
@@ -1,4 +1,4 @@
-<!-- $NetBSD: configuring.xml,v 1.48 2016/04/10 16:02:02 joerg Exp $ -->
+<!-- $NetBSD: configuring.xml,v 1.49 2016/06/11 14:58:26 rillig Exp $ -->
 
 <chapter id="configuring">
   <title>Configuring pkgsrc</title>
@@ -90,7 +90,7 @@ works.</para>
 
   <sect1 id="variables-affecting-build">
     <title>Variables affecting the build process</title>
-    <para>XXX
+    <para>
       <itemizedlist>
 	<listitem><para><varname>PACKAGES</varname>: The top level
 	    directory for the binary packages. The default is
diff --git a/doc/guide/files/faq.xml b/doc/guide/files/faq.xml
index 1b5ccabb612..742f4bf79bf 100644
--- a/doc/guide/files/faq.xml
+++ b/doc/guide/files/faq.xml
@@ -1,4 +1,4 @@
-<!-- $NetBSD: faq.xml,v 1.52 2016/06/11 13:19:54 rillig Exp $ -->
+<!-- $NetBSD: faq.xml,v 1.53 2016/06/11 14:58:26 rillig Exp $ -->
 
 <chapter id="faq"> <?dbhtml filename="faq.html"?>
 <title>Frequently Asked Questions</title>
@@ -222,25 +222,16 @@ utilities)</para>
 <sect1 id="non-root-pkgsrc">
 <title>How to use pkgsrc as non-root</title>
 
-<para>If you want to use pkgsrc as non-root user, you can set some
-variables to make pkgsrc work under these conditions.  At the very least,
-you need to set <varname>UNPRIVILEGED</varname> to <quote>yes</quote>; this
-will turn on unprivileged mode and set multiple related variables to allow
-installation of packages as non-root.</para>
-
-<para>In case the defaults are not enough, you may want to tune some other
-variables used.  For example, if the automatic user/group detection leads
-to incorrect values (or not the ones you would like to use), you can change
-them by setting <varname>UNPRIVILEGED_USER</varname> and
-<varname>UNPRIVILEGED_GROUP</varname> respectively.</para>
-
-<para>As regards bootstrapping, please note that the
-<command>bootstrap</command> script will ease non-root configuration when
-given the <quote>--ignore-user-check</quote> flag, as it will choose and
-use multiple default directories under <filename>~/pkg</filename> as the
-installation targets.  These directories can be overridden by the
-<quote>--prefix</quote> flag provided by the script, as well as some others
-that allow finer tuning of the tree layout.</para>
+<para>To install packages from source as a non-root user, download
+pkgsrc as described in <xref linkend="getting"/>, cd into that
+directory and run the command <command>./bootstrap/bootstrap
+--unprivileged</command>.</para>
+
+<para>This will install the binary part of pkgsrc to
+<filename>~/pkg</filename> and put the pkgsrc configuration &mk.conf;
+into <filename>~/pkg/etc</filename>.</para>
+
+<para>For more details, see <filename>mk/unprivileged.mk</filename>.</para>
 
 </sect1>
 
diff --git a/doc/guide/files/introduction.xml b/doc/guide/files/introduction.xml
index 86f5786a383..98ca3e40179 100644
--- a/doc/guide/files/introduction.xml
+++ b/doc/guide/files/introduction.xml
@@ -1,4 +1,4 @@
-<!-- $NetBSD: introduction.xml,v 1.37 2016/01/17 22:06:16 sevan Exp $ -->
+<!-- $NetBSD: introduction.xml,v 1.38 2016/06/11 14:58:26 rillig Exp $ -->
 
 <chapter id="introduction">
   <title>What is pkgsrc?</title>
@@ -39,7 +39,7 @@ packages for himself, which is a time-costly task.</para>
       </listitem>
     </itemizedlist>
 
-    <para>...just to name a few.</para>
+    <para>&#x2026; just to name a few.</para>
 
     <para>pkgsrc has built-in support for handling varying dependencies,
       such as pthreads and X11, and extended features such as IPv6 support on
diff --git a/doc/guide/files/makefile.xml b/doc/guide/files/makefile.xml
index 8a70796a672..a6292c69efe 100644
--- a/doc/guide/files/makefile.xml
+++ b/doc/guide/files/makefile.xml
@@ -1,4 +1,4 @@
-<!-- $NetBSD: makefile.xml,v 1.24 2014/12/03 07:05:05 ryoon Exp $ -->
+<!-- $NetBSD: makefile.xml,v 1.25 2016/06/11 14:58:26 rillig Exp $ -->
 
 <chapter id="makefile"> <?dbhtml filename="makefile.html"?>
   <title>Programming in <filename>Makefile</filename>s</title>
@@ -78,28 +78,15 @@ correct:
     not preceded by a backslash starts a comment that continues upto the
     end of the logical line.</para>
 
-    <para><emphasis>Note:</emphasis> Because of this parsing algorithm
-    the only way to create a variable consisting of a single backslash
-    is using the ``!='' operator, for example: <!-- FIXME
-    --><varname>BACKSLASH!=echo "\\"</varname>.</para>
-
-    <para>So far for defining variables. The other thing you can do with
-    variables is evaluating them. A variable is evaluated when it is
-    part of the right side of the ``:='' or the ``!='' operator, or
-    directly before executing a shell command which the variable is part
-    of. In all other cases, &man.make.1; performs lazy evaluation, that
-    is, variables are not evaluated until there's no other way. The
-    ``modifiers'' mentioned in the man page also evaluate the
-    variable.</para>
+    <para>The evaluation of variables either happens immediately or lazy.
+    It happens immediately when the variable occurs
+    on the right-hand side of the ``:='' or the ``!='' operator, in a
+    <varname>.if</varname> condition or a <varname>.for</varname> loop.
+    In the other cases, it is evaluated lazily.</para>
 
     <para>Some of the modifiers split the string into words and then
     operate on the words, others operate on the string as a whole. When
-    a string is split into words, it is split as you would expect
-    it from &man.sh.1;.</para>
-
-    <para>No rule without exception&mdash;the <command>.for</command>
-    loop does not follow the shell quoting rules but splits at sequences
-    of whitespace.</para>
+    a string is split into words, it is split like in &man.sh.1;.</para>
 
     <para>There are several types of variables that should be handled
     differently. Strings and two types of lists.</para>
@@ -183,24 +170,6 @@ EXT_LIST+=              ${ANOTHER_EXT_LIST}     # 4
 
     </sect2>
 
-    <sect2 id="converting-internal-to-external">
-      <title>Converting an internal list into an external list</title>
-
-<programlisting>
-EXT_LIST=       # empty
-.for i in ${INT_LIST}
-EXT_LIST+=      ${i:Q}""
-.endfor
-</programlisting>
-
-      <para>This code converts the internal list
-      <varname>INT_LIST</varname> into the external list
-      <varname>EXT_LIST</varname>. As the elements of an internal list
-      are unquoted they must be quoted here. The reason for appending
-      <varname>""</varname> is explained below.</para>
-
-    </sect2>
-
     <sect2 id="passing-variable-to-shell">
       <title>Passing variables to a shell command</title>
 
@@ -210,50 +179,26 @@ EXT_LIST+=      ${i:Q}""
 
 <programlisting>
 STRING=         foo bar &lt;    &gt; * `date` $$HOME ' "
-EXT_LIST=       string=${STRING:Q} x=second\ item
+EXAMPLE_ENV=    string=${STRING:Q} x=multiple\ quoted\ words
 
 all:
         echo ${STRING}                  # 1
-        echo "${STRING}"                # 2
-        echo "${STRING:Q}"              # 3
-        echo ${STRING:Q}                # 4
-        echo x${STRING:Q} | sed 1s,.,,  # 5
-        printf "%s\\n" ${STRING:Q}""    # 6
-        env ${EXT_LIST} /bin/sh -c 'echo "$$string"; echo "$$x"'
+        echo ${STRING:Q}                # 2
+        printf '%s\n' ${STRING:Q}''     # 3
+        env ${EXAMPLE_ENV} sh -c 'echo "$$string"; echo "$$x"' # 4
 </programlisting>
 
       <para>Example 1 leads to a syntax error in the shell, as the
       characters are just copied.</para>
 
-      <para>Example 2 leads to a syntax error too, and if you leave out
-      the last " character from <varname>${STRING}</varname>,
-      &man.date.1; will be executed. The <varname>$HOME</varname> shell
-      variable would be evaluated, too.</para>
-
-      <para>Example 3 outputs each space character preceded by a
-      backslash (or not), depending on the implementation of the
-      &man.echo.1; command.</para>
-
-      <para>Example 4 handles correctly every string that does not start
-      with a dash. In that case, the result depends on the
-      implementation of the &man.echo.1; command. As long as you can
-      guarantee that your input does not start with a dash, this form is
-      appropriate.</para>
+      <para>Example 2 can handle all strings, except those starting
+      with a dash or those containing backslashes.</para>
 
-      <para>Example 5 handles even the case of a leading dash
-      correctly.</para>
-
-      <para>Example 6 also works with every string and is the
-      light-weight solution, since it does not involve a pipe, which has
-      its own problems.</para>
-
-      <para>The <varname>EXT_LIST</varname> does not need to be quoted
-      because the quoting has already been done when adding elements to
-      the list.</para>
-
-      <para>As internal lists shall not be passed to the shell, there is
-      no example for it.</para>
+      <para>Example 3 can handle arbitrary strings.</para>
 
+      <para>In example 4, the <varname>EXT_LIST</varname> does not
+      need to be quoted because the quoting has already been done
+      when adding elements to the list.</para>
     </sect2>
 
     <sect2 id="quoting-guideline">
@@ -344,24 +289,5 @@ for_test:
 
       </itemizedlist>
     </sect2>
-
-    <sect2 id="bsd-make-bug-workaround">
-      <title>Workaround for a bug in BSD Make</title>
-
-      <para>The pkgsrc bmake program does not handle the following
-      assignment correctly. In case <varname>_othervar_</varname>
-      contains a ``-'' character, one of the closing braces is included
-      in <varname>${VAR}</varname> after this code executes.</para>
-
-<programlisting>
-VAR:=   ${VAR:N${_othervar_:C/-//}}
-</programlisting>
-
-      <para>For a more complex code snippet and a workaround, see the
-      package <filename role="pkg">regress/make-quoting</filename>, testcase
-      <varname>bug1</varname>.</para>
-
-    </sect2>
-
   </sect1>
 </chapter>
diff --git a/doc/guide/files/platforms.xml b/doc/guide/files/platforms.xml
index 157237b1786..475e6e0cf94 100644
--- a/doc/guide/files/platforms.xml
+++ b/doc/guide/files/platforms.xml
@@ -1,4 +1,4 @@
-<!-- $NetBSD: platforms.xml,v 1.85 2015/12/29 19:27:34 sevan Exp $ -->
+<!-- $NetBSD: platforms.xml,v 1.86 2016/06/11 14:58:26 rillig Exp $ -->
 
 <chapter id="platforms">
   <title>Using pkgsrc on systems other than &os;</title>
@@ -67,8 +67,6 @@
   <sect1 id="platform-specific-notes">
     <title>Platform-specific notes</title>
 
-    <para>Here are some platform-specific notes you should be aware of.</para>
-
     <sect2 id="cygwin">
       <title>Cygwin</title>
 
diff --git a/doc/guide/files/porting.xml b/doc/guide/files/porting.xml
index 1555d3bfeea..af9897d9621 100644
--- a/doc/guide/files/porting.xml
+++ b/doc/guide/files/porting.xml
@@ -1,4 +1,4 @@
-<!-- $NetBSD: porting.xml,v 1.5 2014/05/09 06:52:15 obache Exp $ -->
+<!-- $NetBSD: porting.xml,v 1.6 2016/06/11 14:58:26 rillig Exp $ -->
 
 <chapter id="porting"> <?dbhtml filename="porting.html"?>
 <title>Porting pkgsrc</title>
@@ -51,11 +51,4 @@
 
 </sect1>
 
-<sect1 id="porting.compiler">
-<title>Adding support for a new compiler</title>
-
-	<para>TODO</para>
-
-</sect1>
-
 </chapter>