<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head><meta http-equiv="content-type" content="text/html; charset=utf-8" />
<title>[140804] trunk</title>
</head>
<body>
<style type="text/css"><!--
#msg dl.meta { border: 1px #006 solid; background: #369; padding: 6px; color: #fff; }
#msg dl.meta dt { float: left; width: 6em; font-weight: bold; }
#msg dt:after { content:':';}
#msg dl, #msg dt, #msg ul, #msg li, #header, #footer, #logmsg { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; }
#msg dl a { font-weight: bold}
#msg dl a:link { color:#fc3; }
#msg dl a:active { color:#ff0; }
#msg dl a:visited { color:#cc6; }
h3 { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; font-weight: bold; }
#msg pre { overflow: auto; background: #ffc; border: 1px #fa0 solid; padding: 6px; }
#logmsg { background: #ffc; border: 1px #fa0 solid; padding: 1em 1em 0 1em; }
#logmsg p, #logmsg pre, #logmsg blockquote { margin: 0 0 1em 0; }
#logmsg p, #logmsg li, #logmsg dt, #logmsg dd { line-height: 14pt; }
#logmsg h1, #logmsg h2, #logmsg h3, #logmsg h4, #logmsg h5, #logmsg h6 { margin: .5em 0; }
#logmsg h1:first-child, #logmsg h2:first-child, #logmsg h3:first-child, #logmsg h4:first-child, #logmsg h5:first-child, #logmsg h6:first-child { margin-top: 0; }
#logmsg ul, #logmsg ol { padding: 0; list-style-position: inside; margin: 0 0 0 1em; }
#logmsg ul { text-indent: -1em; padding-left: 1em; }#logmsg ol { text-indent: -1.5em; padding-left: 1.5em; }
#logmsg > ul, #logmsg > ol { margin: 0 0 1em 0; }
#logmsg pre { background: #eee; padding: 1em; }
#logmsg blockquote { border: 1px solid #fa0; border-left-width: 10px; padding: 1em 1em 0 1em; background: white;}
#logmsg dl { margin: 0; }
#logmsg dt { font-weight: bold; }
#logmsg dd { margin: 0; padding: 0 0 0.5em 0; }
#logmsg dd:before { content:'\00bb';}
#logmsg table { border-spacing: 0px; border-collapse: collapse; border-top: 4px solid #fa0; border-bottom: 1px solid #fa0; background: #fff; }
#logmsg table th { text-align: left; font-weight: normal; padding: 0.2em 0.5em; border-top: 1px dotted #fa0; }
#logmsg table td { text-align: right; border-top: 1px dotted #fa0; padding: 0.2em 0.5em; }
#logmsg table thead th { text-align: center; border-bottom: 1px solid #fa0; }
#logmsg table th.Corner { text-align: left; }
#logmsg hr { border: none 0; border-top: 2px dashed #fa0; height: 1px; }
#header, #footer { color: #fff; background: #636; border: 1px #300 solid; padding: 6px; }
#patch { width: 100%; }
#patch h4 {font-family: verdana,arial,helvetica,sans-serif;font-size:10pt;padding:8px;background:#369;color:#fff;margin:0;}
#patch .propset h4, #patch .binary h4 {margin:0;}
#patch pre {padding:0;line-height:1.2em;margin:0;}
#patch .diff {width:100%;background:#eee;padding: 0 0 10px 0;overflow:auto;}
#patch .propset .diff, #patch .binary .diff {padding:10px 0;}
#patch span {display:block;padding:0 10px;}
#patch .modfile, #patch .addfile, #patch .delfile, #patch .propset, #patch .binary, #patch .copfile {border:1px solid #ccc;margin:10px 0;}
#patch ins {background:#dfd;text-decoration:none;display:block;padding:0 10px;}
#patch del {background:#fdd;text-decoration:none;display:block;padding:0 10px;}
#patch .lines, .info {color:#888;background:#fff;}
--></style>
<div id="msg">
<dl class="meta">
<dt>Revision</dt> <dd><a href="https://trac.macports.org/changeset/140804">140804</a></dd>
<dt>Author</dt> <dd>raimue@macports.org</dd>
<dt>Date</dt> <dd>2015-10-03 08:22:54 -0700 (Sat, 03 Oct 2015)</dd>
</dl>
<h3>Log Message</h3>
<pre>doc/doc-new: Clarify updating a single port may lead to errors, closes #48909</pre>
<h3>Modified Paths</h3>
<ul>
<li><a href="#trunkbasedocportlivecheck1">trunk/base/doc/port-livecheck.1</a></li>
<li><a href="#trunkbasedocportlivecheck1txt">trunk/base/doc/port-livecheck.1.txt</a></li>
<li><a href="#trunkbasedocportupgrade1">trunk/base/doc/port-upgrade.1</a></li>
<li><a href="#trunkbasedocportupgrade1txt">trunk/base/doc/port-upgrade.1.txt</a></li>
<li><a href="#trunkbasedocport1">trunk/base/doc/port.1</a></li>
<li><a href="#trunkbasedocport1txt">trunk/base/doc/port.1.txt</a></li>
<li><a href="#trunkdocnewguidexmlprojectxml">trunk/doc-new/guide/xml/project.xml</a></li>
<li><a href="#trunkdocnewguidexmlusingxml">trunk/doc-new/guide/xml/using.xml</a></li>
</ul>
</div>
<div id="patch">
<h3>Diff</h3>
<a id="trunkbasedocportlivecheck1"></a>
<div class="modfile"><h4>Modified: trunk/base/doc/port-livecheck.1 (140803 => 140804)</h4>
<pre class="diff"><span>
<span class="info">--- 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)
</span><span class="lines">@@ -31,7 +31,7 @@
</span><span class="cx"> .sp
</span><span class="cx"> \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\&.
</span><span class="cx"> .sp
</span><del>-\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\&.
</del><ins>+\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\&.
</ins><span class="cx"> .SH "GLOBAL OPTIONS"
</span><span class="cx"> .sp
</span><span class="cx"> Please see the section \fBGLOBAL OPTIONS\fR in the \fBport\fR(1) man page for a description of global port options\&.
</span></span></pre></div>
<a id="trunkbasedocportlivecheck1txt"></a>
<div class="modfile"><h4>Modified: trunk/base/doc/port-livecheck.1.txt (140803 => 140804)</h4>
<pre class="diff"><span>
<span class="info">--- 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)
</span><span class="lines">@@ -23,7 +23,7 @@
</span><span class="cx"> *port livecheck* is useful for maintainers that want to check whether new
</span><span class="cx"> versions of their ports are available so they can be updated. It can also be
</span><span class="cx"> used by users that encounter a problem, because updating to the latest upstream
</span><del>-version is generally one of the first steps in case of an error of when
</del><ins>+version is generally one of the first steps in case of an error or when
</ins><span class="cx"> encountering a bug.
</span><span class="cx">
</span><span class="cx"> include::global-flags.txt[]
</span></span></pre></div>
<a id="trunkbasedocportupgrade1"></a>
<div class="modfile"><h4>Modified: trunk/base/doc/port-upgrade.1 (140803 => 140804)</h4>
<pre class="diff"><span>
<span class="info">--- 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)
</span><span class="lines">@@ -69,7 +69,7 @@
</span><span class="cx"> \fBvariants.conf\fR(5)
</span><span class="cx"> .RE
</span><span class="cx"> .sp
</span><del>-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\&.
</del><ins>+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\&.
</ins><span class="cx"> .SH "OPTIONS"
</span><span class="cx"> .PP
</span><span class="cx"> \fB\-\-enforce\-variants\fR
</span></span></pre></div>
<a id="trunkbasedocportupgrade1txt"></a>
<div class="modfile"><h4>Modified: trunk/base/doc/port-upgrade.1.txt (140803 => 140804)</h4>
<pre class="diff"><span>
<span class="info">--- 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)
</span><span class="lines">@@ -31,7 +31,11 @@
</span><span class="cx">
</span><span class="cx"> In most cases, you should specify the *outdated* pseudo-port expression as
</span><span class="cx"> argument to *port upgrade* to upgrade all ports where a newer version is
</span><del>-available. See man:port[1] for more information on pseudo-port expressions.
</del><ins>+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.
</ins><span class="cx">
</span><span class="cx"> OPTIONS
</span><span class="cx"> -------
</span></span></pre></div>
<a id="trunkbasedocport1"></a>
<div class="modfile"><h4>Modified: trunk/base/doc/port.1 (140803 => 140804)</h4>
<pre class="diff"><span>
<span class="info">--- 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)
</span><span class="lines">@@ -1,5 +1,5 @@
</span><span class="cx"> '\" t
</span><del>-.TH "PORT" "1" "2014\-11\-11" "MacPorts 2\&.3\&.99" "MacPorts Manual"
</del><ins>+.TH "PORT" "1" "2015\-01\-12" "MacPorts 2\&.3\&.99" "MacPorts Manual"
</ins><span class="cx"> .\" -----------------------------------------------------------------
</span><span class="cx"> .\" * Define some portability stuff
</span><span class="cx"> .\" -----------------------------------------------------------------
</span><span class="lines">@@ -807,26 +807,43 @@
</span><span class="cx"> \fB\-R\fR
</span><span class="cx"> (dependents) above\&.
</span><span class="cx"> .sp
</span><del>-Upgrade the installed
-\fIportname\fR\&. For example:
</del><ins>+Upgrade all outdated ports:
</ins><span class="cx"> .sp
</span><span class="cx"> .if n \{\
</span><span class="cx"> .RS 4
</span><span class="cx"> .\}
</span><span class="cx"> .nf
</span><del>-port upgrade vim
</del><ins>+port upgrade outdated
</ins><span class="cx"> .fi
</span><span class="cx"> .if n \{\
</span><span class="cx"> .RE
</span><span class="cx"> .\}
</span><span class="cx"> .sp
</span><del>-To upgrade all outdated ports:
</del><ins>+.if n \{\
</ins><span class="cx"> .sp
</span><ins>+.\}
+.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
</ins><span class="cx"> .if n \{\
</span><span class="cx"> .RS 4
</span><span class="cx"> .\}
</span><span class="cx"> .nf
</span><del>-port upgrade outdated
</del><ins>+port upgrade vim
</ins><span class="cx"> .fi
</span><span class="cx"> .if n \{\
</span><span class="cx"> .RE
</span></span></pre></div>
<a id="trunkbasedocport1txt"></a>
<div class="modfile"><h4>Modified: trunk/base/doc/port.1.txt (140803 => 140804)</h4>
<pre class="diff"><span>
<span class="info">--- 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)
</span><span class="lines">@@ -369,15 +369,25 @@
</span><span class="cx"> *-R* (dependents) above.
</span><span class="cx"> +
</span><span class="cx"> --
</span><del>-Upgrade the installed 'portname'. For example:
</del><ins>+Upgrade all outdated ports:
+
</ins><span class="cx"> --------
</span><del>-port upgrade vim
</del><ins>+port upgrade outdated
</ins><span class="cx"> --------
</span><span class="cx">
</span><del>-To upgrade all outdated ports:
</del><ins>+[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.
</ins><span class="cx">
</span><ins>+// Forcing a new paragraph here by inserting a dummy space
+{nbsp}
+
+Upgrade the installed 'portname'. For example:
+
</ins><span class="cx"> --------
</span><del>-port upgrade outdated
</del><ins>+port upgrade vim
</ins><span class="cx"> --------
</span><span class="cx">
</span><span class="cx"> To upgrade 'portname' and the ports that depend on it:
</span></span></pre></div>
<a id="trunkdocnewguidexmlprojectxml"></a>
<div class="modfile"><h4>Modified: trunk/doc-new/guide/xml/project.xml (140803 => 140804)</h4>
<pre class="diff"><span>
<span class="info">--- 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)
</span><span class="lines">@@ -71,6 +71,10 @@
</span><span class="cx"> then reinstall. You might also want to run 'port -nR upgrade --force
</span><span class="cx"> <replaceable>foo</replaceable>' to rebuild ports depending upon
</span><span class="cx"> port <replaceable>foo</replaceable>.
</span><ins>+ 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.
</ins><span class="cx"> </para>
</span><span class="cx"> </listitem>
</span><span class="cx"> </itemizedlist>
</span></span></pre></div>
<a id="trunkdocnewguidexmlusingxml"></a>
<div class="modfile"><h4>Modified: trunk/doc-new/guide/xml/using.xml (140803 => 140804)</h4>
<pre class="diff"><span>
<span class="info">--- 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)
</span><span class="lines">@@ -825,7 +825,9 @@
</span><span class="cx"> <programlisting><prompt>$ </prompt><userinput>sudo port upgrade outdated</userinput></programlisting>
</span><span class="cx">
</span><span class="cx"> <para>to update all ports that have an upgrade available. You can, however, selectively upgrade ports if you
</span><del>- want to delay other upgrades until later. To do that, specify the name(s) of the port(s) to upgrade:</para>
</del><ins>+ 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>
</ins><span class="cx">
</span><span class="cx"> <programlisting><prompt>$ </prompt><userinput>sudo port upgrade gnupg2</userinput></programlisting>
</span><span class="cx">
</span><span class="lines">@@ -1128,8 +1130,8 @@
</span><span class="cx">
</span><span class="cx"> <programlisting><prompt>$ </prompt><userinput>sudo port upgrade outdated</userinput></programlisting>
</span><span class="cx">
</span><del>- <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>
</del><ins>+ <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>
</ins><span class="cx">
</span><span class="cx"> <programlisting><prompt>$ </prompt><userinput>sudo port upgrade makedepend</userinput></programlisting>
</span><span class="cx">
</span></span></pre>
</div>
</div>
</body>
</html>