Date: Tue, 10 Jan 2017 23:08:09 +0000 (UTC) From: Mark Linimon <linimon@FreeBSD.org> 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 Message-ID: <201701102308.v0AN89l5032668@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
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 <para>However, for those sites building from source or using their own repositories, a separate - <emphasis>port management tool</emphasis> will be needed.</para> + <link linkend="ports-upgrading-tools">port management tool</link> + will be needed.</para> <para>Since <application>pkg</application> only works with binary packages, it @@ -1169,9 +1170,30 @@ The deinstallation will free 229 kB when performing the upgrade.</para> </important> - <para>To perform the actual upgrade, use either - <application>Portmaster</application> or - <application>Portupgrade</application>.</para> + <sect3 xml:id="ports-upgrading-tools"> + <title>Tools To Upgrade And Manage Ports</title> + + <indexterm> + <primary>ports</primary> + <secondary>upgrading-tools</secondary> + </indexterm> + + <para>The Ports Collection contains several utilities to perform + the actual upgrade. Each has its strengths and weaknesses.</para> + + <para>Historically, most installations used either + <application>Portmaster</application> or + <application>Portupgrade</application>. + <application>Synth</application> is a newer + alternative.</para> + + <note> + <para>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.</para> + </note> + + </sect3> <sect3 xml:id="portmaster"> <title>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">
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201701102308.v0AN89l5032668>