[140804] trunk

raimue at macports.org raimue at macports.org
Sat Oct 3 08:22:54 PDT 2015 

Revision: 140804
          https://trac.macports.org/changeset/140804
Author:   raimue at macports.org
Date:     2015-10-03 08:22:54 -0700 (Sat, 03 Oct 2015)
Log Message:
-----------
doc/doc-new: Clarify updating a single port may lead to errors, closes #48909

Modified Paths:
--------------
    trunk/base/doc/port-livecheck.1
    trunk/base/doc/port-livecheck.1.txt
    trunk/base/doc/port-upgrade.1
    trunk/base/doc/port-upgrade.1.txt
    trunk/base/doc/port.1
    trunk/base/doc/port.1.txt
    trunk/doc-new/guide/xml/project.xml
    trunk/doc-new/guide/xml/using.xml

Modified: trunk/base/doc/port-livecheck.1
===================================================================
--- trunk/base/doc/port-livecheck.1	2015-10-03 13:11:42 UTC (rev 140803)
+++ trunk/base/doc/port-livecheck.1	2015-10-03 15:22:54 UTC (rev 140804)
@@ -31,7 +31,7 @@
 .sp
 \fBport livecheck\fR checks whether a newer version of a given port is available upstream\&. It (usually) does that by automatically downloading a web page and applying a regular expression that extracts a version number\&. If the version number is different from the one the port packages, a message is printed\&.
 .sp
-\fBport livecheck\fR is useful for maintainers that want to check whether new versions of their ports are available so they can be updated\&. It can also be used by users that encounter a problem, because updating to the latest upstream version is generally one of the first steps in case of an error of when encountering a bug\&.
+\fBport livecheck\fR is useful for maintainers that want to check whether new versions of their ports are available so they can be updated\&. It can also be used by users that encounter a problem, because updating to the latest upstream version is generally one of the first steps in case of an error or when encountering a bug\&.
 .SH "GLOBAL OPTIONS"
 .sp
 Please see the section \fBGLOBAL OPTIONS\fR in the \fBport\fR(1) man page for a description of global port options\&.

Modified: trunk/base/doc/port-livecheck.1.txt
===================================================================
--- trunk/base/doc/port-livecheck.1.txt	2015-10-03 13:11:42 UTC (rev 140803)
+++ trunk/base/doc/port-livecheck.1.txt	2015-10-03 15:22:54 UTC (rev 140804)
@@ -23,7 +23,7 @@
 *port livecheck* is useful for maintainers that want to check whether new
 versions of their ports are available so they can be updated. It can also be
 used by users that encounter a problem, because updating to the latest upstream
-version is generally one of the first steps in case of an error of when
+version is generally one of the first steps in case of an error or when
 encountering a bug.
 
 include::global-flags.txt[]

Modified: trunk/base/doc/port-upgrade.1
===================================================================
--- trunk/base/doc/port-upgrade.1	2015-10-03 13:11:42 UTC (rev 140803)
+++ trunk/base/doc/port-upgrade.1	2015-10-03 15:22:54 UTC (rev 140804)
@@ -69,7 +69,7 @@
 \fBvariants.conf\fR(5)
 .RE
 .sp
-In most cases, you should specify the \fBoutdated\fR pseudo\-port expression as argument to \fBport upgrade\fR to upgrade all ports where a newer version is available\&. See \fBport\fR(1) for more information on pseudo\-port expressions\&.
+In most cases, you should specify the \fBoutdated\fR pseudo\-port expression as argument to \fBport upgrade\fR to upgrade all ports where a newer version is available\&. This is the recommended upgrade method for end users\&. See \fBport\fR(1) for more information on pseudo\-port expressions\&. Upgrading individual packages should only be performed by expert users who know what they are doing, since a mix of upgraded and non\-upgraded packages can lead to various software errors\&.
 .SH "OPTIONS"
 .PP
 \fB\-\-enforce\-variants\fR

Modified: trunk/base/doc/port-upgrade.1.txt
===================================================================
--- trunk/base/doc/port-upgrade.1.txt	2015-10-03 13:11:42 UTC (rev 140803)
+++ trunk/base/doc/port-upgrade.1.txt	2015-10-03 15:22:54 UTC (rev 140804)
@@ -31,7 +31,11 @@
 
 In most cases, you should specify the *outdated* pseudo-port expression as
 argument to *port upgrade* to upgrade all ports where a newer version is
-available. See man:port[1] for more information on pseudo-port expressions.
+available. This is the recommended upgrade method for end users.
+See man:port[1] for more information on pseudo-port expressions.
+Upgrading individual packages should only be performed by expert users who
+know what they are doing, since a mix of upgraded and non-upgraded packages
+can lead to various software errors.
 
 OPTIONS
 -------

Modified: trunk/base/doc/port.1
===================================================================
--- trunk/base/doc/port.1	2015-10-03 13:11:42 UTC (rev 140803)
+++ trunk/base/doc/port.1	2015-10-03 15:22:54 UTC (rev 140804)
@@ -1,5 +1,5 @@
 '\" t
-.TH "PORT" "1" "2014\-11\-11" "MacPorts 2\&.3\&.99" "MacPorts Manual"
+.TH "PORT" "1" "2015\-01\-12" "MacPorts 2\&.3\&.99" "MacPorts Manual"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -807,26 +807,43 @@
 \fB\-R\fR
 (dependents) above\&.
 .sp
-Upgrade the installed
-\fIportname\fR\&. For example:
+Upgrade all outdated ports:
 .sp
 .if n \{\
 .RS 4
 .\}
 .nf
-port upgrade vim
+port upgrade outdated
 .fi
 .if n \{\
 .RE
 .\}
 .sp
-To upgrade all outdated ports:
+.if n \{\
 .sp
+.\}
+.RS 4
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+.ps +1
+\fBNote\fR
+.ps -1
+.br
+It is recomended to always upgrade all ports with the command indicated above\&. Upgrading single ports as indicated in the subsequent examples should only be performed if you know what you are doing, since this might lead to unexpected software errors from ports that have not yet been upgraded\&.
+.sp .5v
+.RE
+\ \&
+.sp
+Upgrade the installed
+\fIportname\fR\&. For example:
+.sp
 .if n \{\
 .RS 4
 .\}
 .nf
-port upgrade outdated
+port upgrade vim
 .fi
 .if n \{\
 .RE

Modified: trunk/base/doc/port.1.txt
===================================================================
--- trunk/base/doc/port.1.txt	2015-10-03 13:11:42 UTC (rev 140803)
+++ trunk/base/doc/port.1.txt	2015-10-03 15:22:54 UTC (rev 140804)
@@ -369,15 +369,25 @@
     *-R* (dependents) above.
 +
 --
-Upgrade the installed 'portname'. For example:
+Upgrade all outdated ports:
+
 --------
-port upgrade vim
+port upgrade outdated
 --------
 
-To upgrade all outdated ports:
+[NOTE]
+It is recommended to always upgrade all ports with the command indicated above.
+Upgrading single ports as indicated in the subsequent examples should only be
+performed if you know what you are doing, since this might lead to unexpected
+software errors from ports that have not yet been upgraded.
 
+// Forcing a new paragraph here by inserting a dummy space
+{nbsp}
+
+Upgrade the installed 'portname'. For example:
+
 --------
-port upgrade outdated
+port upgrade vim
 --------
 
 To upgrade 'portname' and the ports that depend on it:

Modified: trunk/doc-new/guide/xml/project.xml
===================================================================
--- trunk/doc-new/guide/xml/project.xml	2015-10-03 13:11:42 UTC (rev 140803)
+++ trunk/doc-new/guide/xml/project.xml	2015-10-03 15:22:54 UTC (rev 140804)
@@ -71,6 +71,10 @@
             then reinstall. You might also want to run 'port -nR upgrade --force
             <replaceable>foo</replaceable>' to rebuild ports depending upon
             port <replaceable>foo</replaceable>.
+            Note that it is safest and recommended that most users always upgrade
+            with 'port upgrade outdated' to update all ports at once. Upgrading a
+            single port can lead to software errors in other ports that have not
+            yet been upgraded.
           </para>
         </listitem>
       </itemizedlist>

Modified: trunk/doc-new/guide/xml/using.xml
===================================================================
--- trunk/doc-new/guide/xml/using.xml	2015-10-03 13:11:42 UTC (rev 140803)
+++ trunk/doc-new/guide/xml/using.xml	2015-10-03 15:22:54 UTC (rev 140804)
@@ -825,7 +825,9 @@
             <programlisting><prompt>$ </prompt><userinput>sudo port upgrade outdated</userinput></programlisting>
 
             <para>to update all ports that have an upgrade available. You can, however, selectively upgrade ports if you
-                want to delay other upgrades until later. To do that, specify the name(s) of the port(s) to upgrade:</para>
+                want to delay other upgrades until later. This is not recommended unless you know what you are doing,
+                since you might experience software errors for the ports that have not yet been upgraded. To upgrade
+                individual ports, specify the name(s) of the port(s) to upgrade:</para>
 
             <programlisting><prompt>$ </prompt><userinput>sudo port upgrade gnupg2</userinput></programlisting>
 
@@ -1128,8 +1130,8 @@
 
             <programlisting><prompt>$ </prompt><userinput>sudo port upgrade outdated</userinput></programlisting>
 
-            <para>In case you want to upgrade only a specific port, replace <quote>outdated</quote> in the command given
-                above with the port's name:</para>
+            <para>In case you want to upgrade only a specific port (not recommended unless you know what you are doing),
+                replace <quote>outdated</quote> in the command given above with the port's name:</para>
 
             <programlisting><prompt>$ </prompt><userinput>sudo port upgrade makedepend</userinput></programlisting>
 
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.macosforge.org/pipermail/macports-changes/attachments/20151003/f9bbf696/attachment.html>

More information about the macports-changes mailing list