Clarify wording in the ports section of the Handbook.

The presentation assumes more knowledge on the part of a new user to
FreeBSD than it should. Some of the text, while correct, is still too
easy to misunderstand.

The overall sense of the text does not change.

Add note about ports not running their startup scripts upon installation
as being by design.

Submitted by:	linimon
Reviewed by:	wblock
Approved by:	wblock (mentor)
Differential Revision:		https://reviews.freebsd.org/D8838

1 files changed, 77 insertions, 48 deletions

diff --git a/en_US.ISO8859-1/books/handbook/ports/chapter.xml b/en_US.ISO8859-1/books/handbook/ports/chapter.xml
index 9fc6e03e9a..4bbf289e44 100644
--- a/en_US.ISO8859-1/books/handbook/ports/chapter.xml
+++ b/en_US.ISO8859-1/books/handbook/ports/chapter.xml
@@ -70,8 +70,8 @@
 
       <step>
 	<para>Unpack the software from its distribution format.  This
-	  is typically a tarball compressed with &man.compress.1;,
-	  &man.gzip.1;, or &man.bzip2.1;.</para>
+	  is typically a tarball compressed with a program such as
+	  &man.compress.1;, &man.gzip.1;, &man.bzip2.1; or &man.xz.1;.</para>
       </step>
 
       <step>
@@ -400,11 +400,18 @@ Info:   Lists information about open files (similar to fstat(1))</screen>
       offering many features that make dealing with binary packages
       faster and easier.</para>
 
-    <para><application>pkg</application> is not a replacement for
-      port management tools like
-      <package>ports-mgmt/portmaster</package> or
-      <package>ports-mgmt/portupgrade</package>.  These tools can be
-      used to install third-party software from both binary packages
+    <para>For sites wishing to only use prebuilt binary packages
+      from the &os; mirrors, managing packages with
+      <application>pkg</application> can be sufficient.</para>
+
+    <para>However, for those sites building from source or using
+      their own repositories, a separate
+      <emphasis>port management tool</emphasis> will be needed.</para>
+
+    <para>Since <application>pkg</application> only works with
+      binary packages, it
+      is not a replacement for such tools.  Those tools can be
+      used to install software from both binary packages
       and the Ports Collection, while
       <application>pkg</application> installs only binary
       packages.</para>
@@ -414,25 +421,36 @@ Info:   Lists information about open files (similar to fstat(1))</screen>
 	<application>pkg</application></title>
 
       <para>&os; includes a bootstrap utility which can be used to
-	download and install <application>pkg</application>, along
-	with its manual pages.</para>
+	download and install <application>pkg</application>
+	and its manual pages.  This utility is designed to work
+	with versions of &os; starting with
+	10.<replaceable>X</replaceable>.</para>
+
+      <note>
+	<para>Not all &os; versions and architectures
+	  support this bootstrap process.  The current list is at
+	  <link xlink:href="http://pkg.freebsd.org/"></link>.
+	  For other cases,
+	  <application>pkg</application> must instead be installed
+	  from the Ports Collection or as a binary package.</para>
+
+      </note>
 
       <para>To bootstrap the system, run:</para>
 
       <screen>&prompt.root; <userinput>/usr/sbin/pkg</userinput></screen>
 
-      <para>For earlier &os; versions,
-	<application>pkg</application> must instead be installed
-	from the Ports Collection or as a binary package.</para>
+      <para>You must have a working Internet connection for the
+	bootstrap process to suceed.</para>
 
-      <para>To install the port, run:</para>
+      <para>Otherwise, to install the port, run:</para>
 
       <screen>&prompt.root; <userinput>cd /usr/ports/ports-mgmt/pkg</userinput>
 &prompt.root; <userinput>make</userinput>
 &prompt.root; <userinput>make install clean</userinput></screen>
 
       <para>When upgrading an existing system that originally used the
-	older package system, the database must be converted to the
+	older pkg_* tools, the database must be converted to the
 	new format, so that the new tools are aware of the already
 	installed packages.  Once <application>pkg</application> has
 	been installed, the
@@ -456,23 +474,25 @@ Info:   Lists information about open files (similar to fstat(1))</screen>
 	<para>The package database conversion may emit errors as the
 	  contents are converted to the new version.  Generally, these
 	  errors can be safely ignored.  However, a list of
-	  third-party software that was not successfully converted
-	  will be listed after <command>pkg2ng</command> has finished
-	  and these applications must be manually reinstalled.</para>
+	  software that was not successfully converted
+	  is shown after <command>pkg2ng</command> finishes.
+	  These applications must be manually reinstalled.</para>
       </note>
 
-      <para>To ensure that the &os;&nbsp;Ports Collection registers
-	new software with <application>pkg</application>, and not
-	the traditional packages format, &os; versions earlier than
+      <para>To ensure that the Ports Collection registers
+	new software with <application>pkg</application> instead of
+	the traditional packages database, &os; versions earlier than
 	10.<replaceable>X</replaceable> require this line in
 	<filename>/etc/make.conf</filename>:</para>
 
       <programlisting>WITH_PKGNG=	yes</programlisting>
 
-      <para>By default <application>pkg</application> uses the &os;
-	package mirrors.  For information about building a custom
-	package repository, see <xref
-	  linkend="ports-poudriere"/></para>
+      <para>By default, <application>pkg</application> uses the
+	binary packages from the &os;
+	package mirrors (the <emphasis>repository</emphasis>).
+	For information about building a custom
+	package repository, see
+	<xref linkend="ports-poudriere"/>.</para>
 
       <para>Additional <application>pkg</application> configuration
 	options are described in &man.pkg.conf.5;.</para>
@@ -589,7 +609,7 @@ Proceed with deleting packages [y/N]: <userinput>y</userinput>
     <sect2 xml:id="pkgng-auditing">
       <title>Auditing Installed Packages</title>
 
-      <para>Occasionally, software vulnerabilities may be discovered
+      <para>Software vulnerabilities are regularly discovered
 	in third-party applications.  To address this,
 	<application>pkg</application> includes a built-in auditing
 	mechanism.  To determine if there are any known
@@ -1152,7 +1172,8 @@ The deinstallation will free 229 kB
 
 	<para><package>ports-mgmt/portmaster</package> is a very
 	  small utility for upgrading installed ports.
-	  It is designed to use the tools installed with &os;
+	  It is designed to use the tools installed with the &os;
+	  base system
 	  without depending on other ports or databases.
 	  To install this utility
 	  as a port:</para>
@@ -1325,15 +1346,15 @@ The deinstallation will free 229 kB
 
       <screen>&prompt.root; <userinput>portsclean -C</userinput></screen>
 
-      <para>In addition, a lot of out-dated source distribution files
-	will collect in <filename>/usr/ports/distfiles</filename> over
-	time.  If <application>Portupgrade</application> is installed,
-	this command will delete all the distfiles that are no longer
+      <para>In addition, outdated source distribution files
+	accumulate in <filename>/usr/ports/distfiles</filename> over
+	time.  To use <application>Portupgrade</application> to
+	delete all the distfiles that are no longer
 	referenced by any ports:</para>
 
       <screen>&prompt.root; <userinput>portsclean -D</userinput></screen>
 
-      <para>To use <application>Portupgrade</application> to remove
+      <para><application>Portupgrade</application> can remove
 	all distfiles not referenced by any port currently installed
 	on the system:</para>
 
@@ -1344,11 +1365,11 @@ The deinstallation will free 229 kB
 
       <screen>&prompt.root; <userinput>portmaster --clean-distfiles</userinput></screen>
 
-      <para>By default, this command is interactive and will prompt
+      <para>By default, this command is interactive and prompts
 	the user to confirm if a distfile should be deleted.</para>
 
-      <para>In addition to these commands, the
-	<package>ports-mgmt/pkg_cutleaves</package> package or port
+      <para>In addition to these commands,
+	<package>ports-mgmt/pkg_cutleaves</package>
 	automates the task of removing installed ports that are no
 	longer needed.</para>
     </sect2>
@@ -1393,9 +1414,9 @@ The deinstallation will free 229 kB
       other configuration values are adequate.</para>
 
     <para>The number of processor cores detected is used to define how
-      many builds should run in parallel.  Supply enough virtual
+      many builds will run in parallel.  Supply enough virtual
       memory, either with <acronym>RAM</acronym> or swap space.  If
-      virtual memory runs out, compiling jails will stop and be torn
+      virtual memory runs out, the compilation jails will stop and be torn
       down, resulting in weird error messages.</para>
 
     <sect2 xml:id="poudriere-initialization">
@@ -1496,7 +1517,7 @@ ports-mgmt/pkg
 
       <screen>&prompt.root; <userinput>poudriere bulk -j <replaceable>10amd64</replaceable> -p <replaceable>local</replaceable> -z <replaceable>workstation</replaceable> -f <replaceable>10amd64-local-workstation-pkglist</replaceable></userinput></screen>
 
-      <para><keycombo
+      <para>While running, pressing <keycombo
 	  action="simul"><keycap>Ctrl</keycap><keycap>t</keycap></keycombo>
 	displays the current state of the build.
 	<application>Poudriere</application> also builds files in
@@ -1504,7 +1525,7 @@ ports-mgmt/pkg
 	that can be used with a web server to display build
 	information.</para>
 
-      <para>Packages are now available for
+      <para>After completion, the new packages are now available for
 	installation from the <application>poudriere</application>
 	repository.</para>
 
@@ -1530,11 +1551,11 @@ ports-mgmt/pkg
 }</screen>
 
       <para>Usually it is easiest to serve a poudriere repository to
-	the client machines via HTTP.  Setup a webserver to serve up
-	the package directory, usually something like:
-	<filename>/usr/local/poudriere/data/packages/<replaceable>10amd64</replaceable></filename>.
-	Where <filename>10amd64</filename> is the name of the
-	build.</para>
+	the client machines via HTTP.  Set up a webserver to serve up
+	the package directory, for instance:
+	<filename>/usr/local/poudriere/data/packages/<replaceable>10amd64</replaceable></filename>,
+	where <filename><replaceable>10amd64</replaceable></filename>
+	is the name of the build.</para>
 
       <para>If the URL to the package repository is:
 	<literal>http://pkg.example.com/10amd64</literal>, then the
@@ -1562,7 +1583,7 @@ ports-mgmt/pkg
       <listitem>
 	<para>Most applications install at least one default
 	  configuration file in <filename>/usr/local/etc</filename>.
-	  In the case where an application has a large number of
+	  In cases where an application has a large number of
 	  configuration files, a subdirectory will be created to hold
 	  them.  Often, sample configuration files are installed which
 	  end with a suffix such as <filename>.sample</filename>.  The
@@ -1586,6 +1607,14 @@ ports-mgmt/pkg
 	  script in <filename>/usr/local/etc/rc.d</filename>.  See
 	  <link linkend="configtuning-starting-services">Starting
 	    Services</link> for more information.</para>
+
+	<note>
+	  <para>By design, applications do not run their startup
+	    script upon installation, nor do they run their stop
+	    script upon deinstallation or upgrade.  This decision
+	    is left to the individual system administrator.</para>
+	</note>
+
       </listitem>
 
       <listitem>
@@ -1628,14 +1657,14 @@ ports-mgmt/pkg
 
 	<note>
 	  <para>Some ports are not maintained by an individual but
-	    instead by a <link
+	    instead by a group maintainer represented by a <link
 	      xlink:href="&url.articles.mailing-list-faq;/article.html">mailing
 	      list</link>.  Many, but not all, of these addresses look
 	    like <email
-	      role="nolink">freebsd-listname@FreeBSD.org</email>.
-	    Take this into account when sending an email.</para>
+	      role="nolink">freebsd-<replaceable>listname</replaceable>@FreeBSD.org</email>.
+	    Please take this into account when sending an email.</para>
 
-	  <para>In particular, ports shown as maintained by
+	  <para>In particular, ports maintained by
 	    <email role="nolink">ports@FreeBSD.org</email> are not
 	    maintained by a specific individual.  Instead, any fixes
 	    and support come from the general community who subscribe