svn commit: r49828 - head/en_US.ISO8859-1/books/handbook/ports

[Mark Linimon]

Author: linimon
Date: Tue Jan 10 22:55:05 2017
New Revision: 49828
URL: https://svnweb.freebsd.org/changeset/doc/49828

Log:
  Shuffle some text in the ports section of the Handbook.
  
  The presentation assumes more knowledge on the part of a new user to
  FreeBSD than it should.
  
  In good writing, concepts should always be introduced before being
  discussed. The current presentation mixes them. The new order introduces
  applications, then ports, then packages, and then elaborates on the
  difference between packages and ports.
  
  90% of the content is merely moved. Some editing for clarity is included.
  
  Submitted by:	linimon
  Reviewed by:	wblock
  Approved by:	wblock (mentor)
  Differential Revision:	https://reviews.freebsd.org/D8839

Modified:
  head/en_US.ISO8859-1/books/handbook/ports/chapter.xml

Modified: head/en_US.ISO8859-1/books/handbook/ports/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/handbook/ports/chapter.xml	Tue Jan 10 22:49:38 2017	(r49827)
+++ head/en_US.ISO8859-1/books/handbook/ports/chapter.xml	Tue Jan 10 22:55:05 2017	(r49828)
@@ -93,25 +93,24 @@
       </step>
     </procedure>
 
-    <para>If the software package was not deliberately ported, or
-      tested to work, on &os;, the source code may need editing in
-      order for it to install and run properly.  At the time of this
-      writing, over &os.numports; third-party applications have been
-      ported to &os;.</para>
-
-    <para>A &os; package contains pre-compiled copies of all the
-      commands for an application, as well as any configuration files
-      and documentation.  A package can be manipulated with the
-      <application>pkg</application> commands, such as
-      <command>pkg install</command>.</para>
-
-    <para>A &os; port is a collection of files designed to automate
+    <para>A &os; <emphasis>port</emphasis> is a collection of files
+      designed to automate
       the process of compiling an application from source code.  The
       files that comprise a port contain all the necessary information
       to automatically download, extract, patch, compile, and install
       the application.</para>
 
-    <para>The ports system can also be used to generate packages which
+    <para>If the software has not already been adapted and tested
+      on &os;, the source code might need editing in
+      order for it to install and run properly.</para>
+
+    <para>However, over
+      <link xlink:href="&url.base;/ports/index.html">&os.numports;</link>
+      third-party applications have already been
+      ported to &os;.  When feasible, these applications are made
+      available for download as pre-compiled <emphasis>packages</emphasis>.</para>
+
+    <para>Packages
       can be manipulated with the &os; package management
       commands.</para>
 
@@ -120,6 +119,12 @@
       dependent library is not already installed, the library will
       automatically be installed first.</para>
 
+    <para>A &os; package contains pre-compiled copies of all the
+      commands for an application, as well as any configuration files
+      and documentation.  A package can be manipulated with the
+      &man.pkg.8; commands, such as
+      <command>pkg install</command>.</para>
+
     <para>While the two technologies are similar, packages and
       ports each have their own strengths.  Select the technology that
       meets your requirements for installing a particular
@@ -734,9 +739,14 @@ Deinstalling ca_root_nss-3.15.1_1... don
     <title>Using the Ports Collection</title>
 
     <para>The Ports Collection is a set of
-      <filename>Makefiles</filename>, patches, and description files
-      stored in <filename>/usr/ports</filename>.  This set of files is
-      used to compile and install applications on &os;.  Before an
+      <filename>Makefiles</filename>, patches, and description files.
+      Each set of these files is used to compile and install an individual
+      application on &os;, and is called a <emphasis>port</emphasis>.</para>
+
+    <para>By default, the Ports Collection itself is stored as a subdirectory
+      of <filename>/usr/ports</filename>.</para>
+
+    <para>Before an
       application can be compiled using a port, the Ports Collection
       must first be installed.  If it was not installed during the
       installation of &os;, use one of the following methods to
@@ -830,11 +840,12 @@ Deinstalling ca_root_nss-3.15.1_1... don
       </step>
     </procedure>
 
-    <para>The Ports Collection installs a series of directories
-      representing software categories with each category having
-      a subdirectory for each application.  Each subdirectory, also
-      referred to as a ports skeleton, contains a set of files that
-      tell &os; how to compile and install that program.  Each port
+    <para>The Ports Collection contains directories
+      for software categories.  Inside each category are
+      subdirectories for individual applications.  Each application
+      subdirectory contains a set of files that
+      tells &os; how to compile and install that program,
+      called a <emphasis>ports skeleton</emphasis>.  Each port
       skeleton includes these files and directories:</para>
 
     <itemizedlist>