[120903] trunk/doc-new/guide/xml/using.xml

[cal at macports.org]

Revision: 120903
          https://trac.macports.org/changeset/120903
Author:   cal at macports.org
Date:     2014-06-11 04:26:31 -0700 (Wed, 11 Jun 2014)
Log Message:
-----------
guide: using: rework selfupdate section

Modified Paths:
--------------
    trunk/doc-new/guide/xml/using.xml

Modified: trunk/doc-new/guide/xml/using.xml
===================================================================
--- trunk/doc-new/guide/xml/using.xml	2014-06-11 10:56:08 UTC (rev 120902)
+++ trunk/doc-new/guide/xml/using.xml	2014-06-11 11:26:31 UTC (rev 120903)
@@ -1,6 +1,9 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
+<!ENTITY macports-prev-version "2.2.1">
+<!ENTITY macports-version "2.3.0">
+]>
 <chapter id="using">
   <title>Using MacPorts</title>
 
@@ -39,41 +42,53 @@
       base, and upgrades it when necessary.</para>
 
       <note>
-        <para>Selfupdate runs only on Mac OS X. If you are running MacPorts on
-        another platform, you must use the <link
-        linkend="using.port.sync">sync</link> action to update the ports tree; to
-        update MacPorts base you must manually install a newer version from
-        source.</para>
+        <para>Selfupdate is only tested on OS X. If you are running MacPorts on
+          another platform, <option>selfupdate</option> may not work correctly.
+          In this case, you should use the <link
+            linkend="using.port.sync">sync</link> action to update the ports
+          tree; to update MacPorts base you must manually install a newer
+          version from source.</para>
       </note>
 
       <programlisting><prompt>%%</prompt> <userinput>sudo port selfupdate</userinput></programlisting>
 
-      <para>Use the debug flag for verbose output.</para>
+      <screen>
+--->  Updating MacPorts base sources using rsync
+MacPorts base version &macports-version; installed,
+MacPorts base version &macports-version; downloaded.
+--->  Updating the ports tree
+--->  MacPorts base is already the latest version
+</screen>
 
+      <para>As always, you can use the debug flag for verbose output. This is
+        useful to debug problems with <option>selfupdate</option>.</para>
+
       <programlisting><prompt>%%</prompt> <userinput>sudo port -d selfupdate</userinput></programlisting>
 
-      <screen>DEBUG: Rebuilding the MacPorts base system if needed.
-DEBUG: Synchronizing ports tree(s)
-Synchronizing from rsync://rsync.macports.org/release/ports/
-DEBUG: /usr/bin/rsync -rtzv --delete-after rsync://rsync.macports.org/release/ports/
-receiving file list ... done
+      <para>If <option>selfupdate</option> detects that a newer version of
+      MacPorts base is available, it automatically updates the installed copy
+      of MacPorts base to the latest released version. In that case, you will
+      see this message:</para>
 
-[ ... trimmed ... ]
+      <screen>
+--->  Updating MacPorts base sources using rsync
+MacPorts base version &macports-prev-version; installed,
+MacPorts base version &macports-version; downloaded.
+--->  Updating the ports tree
+--->  MacPorts base is outdated, installing new version &macports-version;
+Installing new MacPorts release in /opt/local as root:admin; permissions 755
+</screen>
 
+      <para>If the <option>selfupdate</option> procedure fails you'll see
+      a message like this:</para>
 
-The MacPorts installation is not outdated and so was not updated
-DEBUG: Setting ownership to root
-selfupdate done!</screen>
+      <screen>Error installing new MacPorts base: command execution failed</screen>
 
-      <para>If selfupdate detects that a newer version of MacPorts base is
-      available, it automatically updates the installed copy of MacPorts base
-      to the latest released version. In that case, you will see the upgrade
-      Makefile execute, and when it finishes you will see this message:</para>
-
-      <screen>DEBUG: Updating using rsync
-receiving file list ... done
-
-Congratulations, you have successfully installed the MacPorts system.</screen>
+      <para>Re-run <option>selfupdate</option> with the <option>-d</option>
+      flag to see all output generated by the build system. The output may give
+      you an idea why the build failed. If it doesn't, please <link
+        linkend="project.tickets">file a ticket</link> and attach the output
+      generated by <command>sudo port -d selfupdate</command>.</para>
     </section>
 
     <section id="using.port.sync">
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.macosforge.org/pipermail/macports-changes/attachments/20140611/0fb5564c/attachment.html>