From owner-svn-doc-all@freebsd.org Tue Jan 10 23:08:10 2017 Return-Path: Delivered-To: svn-doc-all@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 8842ACA931A; Tue, 10 Jan 2017 23:08:10 +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 650711C64; Tue, 10 Jan 2017 23:08:10 +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 v0AN89sA032669; Tue, 10 Jan 2017 23:08:09 GMT (envelope-from linimon@FreeBSD.org) Received: (from linimon@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id v0AN89l5032668; Tue, 10 Jan 2017 23:08:09 GMT (envelope-from linimon@FreeBSD.org) Message-Id: <201701102308.v0AN89l5032668@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 23:08:09 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r49829 - 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-all@freebsd.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 10 Jan 2017 23:08:10 -0000 Author: linimon Date: Tue Jan 10 23:08:09 2017 New Revision: 49829 URL: https://svnweb.freebsd.org/changeset/doc/49829 Log: Add a short section 4.5.3.1, "Tools To Upgrade And Manage Ports". This removes the assertion that only portupgrade or portmaster are suitable for upgrading ports, and provides a framework for discussing more alternatives as they become available. Synth is mentioned as an alternative. A subsequent patch will be put up for community discussion. While here, clean up some duplicate and awkward wording. This commit expands on the rework done in D8838 and D8839. Submitted by: linimon Reviewed by: wblock Approved by: wblock (mentor) 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:55:05 2017 (r49828) +++ head/en_US.ISO8859-1/books/handbook/ports/chapter.xml Tue Jan 10 23:08:09 2017 (r49829) @@ -411,7 +411,8 @@ Info: Lists information about open fil However, for those sites building from source or using their own repositories, a separate - port management tool will be needed. + port management tool + will be needed. Since pkg only works with binary packages, it @@ -1169,9 +1170,30 @@ The deinstallation will free 229 kB when performing the upgrade. - To perform the actual upgrade, use either - Portmaster or - Portupgrade. + + Tools To Upgrade And Manage Ports + + + ports + upgrading-tools + + + The Ports Collection contains several utilities to perform + the actual upgrade. Each has its strengths and weaknesses. + + Historically, most installations used either + Portmaster or + Portupgrade. + Synth is a newer + alternative. + + + The choice of which tool is best for a particular system + is up to the system administrator. It is recommended practice + to back up your data before using any of these tools. + + + Upgrading Ports Using @@ -1274,6 +1296,9 @@ The deinstallation will free 229 kB port in the Ports Collection:</para> <screen>&prompt.root; <userinput>portmaster <replaceable>shells/bash</replaceable></userinput></screen> + + <para>More information about <package>ports-mgmt/portmaster</package> + may be found in its <filename>pkg-descr</filename>.</para> </sect3> <sect3 xml:id="portupgrade"> @@ -1283,10 +1308,9 @@ The deinstallation will free 229 kB <primary>portupgrade</primary> </indexterm> - <para>Another utility that can be used to upgrade ports is - <application>Portupgrade</application>, which is available - as the <package>ports-mgmt/portupgrade</package> package - or port. This utility installs a suite of applications + <para><package>ports-mgmt/portupgrade</package> is + another utility that can be used to upgrade ports. It + installs a suite of applications which can be used to manage ports. However, it is dependent upon Ruby. To install the port:</para> @@ -1333,7 +1357,11 @@ The deinstallation will free 229 kB installing anything, use <option>-F</option>. For further information on all of the available switches, refer to the manual page for <command>portupgrade</command>.</para> + + <para>More information about <package>ports-mgmt/portupgrade</package> + may be found in its <filename>pkg-descr</filename>.</para> </sect3> + </sect2> <sect2 xml:id="ports-disk-space">