From owner-svn-doc-head@freebsd.org Tue Jan 10 22:55:07 2017 Return-Path: Delivered-To: svn-doc-head@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 2FF2DCAAD83; Tue, 10 Jan 2017 22:55:07 +0000 (UTC) (envelope-from linimon@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id E2DA31512; Tue, 10 Jan 2017 22:55:06 +0000 (UTC) (envelope-from linimon@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id v0AMt6lO028001; Tue, 10 Jan 2017 22:55:06 GMT (envelope-from linimon@FreeBSD.org) Received: (from linimon@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id v0AMt6mv028000; Tue, 10 Jan 2017 22:55:06 GMT (envelope-from linimon@FreeBSD.org) Message-Id: <201701102255.v0AMt6mv028000@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: linimon set sender to linimon@FreeBSD.org using -f From: Mark Linimon Date: Tue, 10 Jan 2017 22:55:06 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r49828 - head/en_US.ISO8859-1/books/handbook/ports X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 10 Jan 2017 22:55:07 -0000 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 @@ - 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;. - - 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 - pkg commands, such as - pkg install. - - A &os; port is a collection of files designed to automate + A &os; port 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. - The ports system can also be used to generate packages which + 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. + + However, over + &os.numports; + third-party applications have already been + ported to &os;. When feasible, these applications are made + available for download as pre-compiled packages. + + Packages can be manipulated with the &os; package management commands. @@ -120,6 +119,12 @@ dependent library is not already installed, the library will automatically be installed first. + 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 + pkg install. + 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 Using the Ports Collection The Ports Collection is a set of - Makefiles, patches, and description files - stored in /usr/ports. This set of files is - used to compile and install applications on &os;. Before an + Makefiles, patches, and description files. + Each set of these files is used to compile and install an individual + application on &os;, and is called a port. + + By default, the Ports Collection itself is stored as a subdirectory + of /usr/ports. + + 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 - 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 + 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 ports skeleton. Each port skeleton includes these files and directories: