docs: clarify pg_upgrade's recovery behavior

The previous paragraph trying to explain --check, --link, and no --link
modes and the various points of failure was too complex.  Instead, use
bullet lists and sublists.

Reported-by: Daniel Gustafsson
Discussion: https://postgr.es/m/qtqiv7hI87s_Xvz5ZXHCaH-1-_AZGpIDJowzlRjF3-AbCr3RhSNydM_JCuJ8DE4WZozrtxhIWmyYTbv0syKyfGB6cYMQitp9yN-NZMm-oAo=@yesql.se

Backpatch-through: 9.4

diff --git a/doc/src/sgml/ref/pgupgrade.sgml b/doc/src/sgml/ref/pgupgrade.sgml
index f6d423ee13ee908d5a0c5d315a21224a147d7d6a..0c4b16d32ce1efa4ee7331e3e1f652056ce2b247 100644 (file)
--- a/doc/src/sgml/ref/pgupgrade.sgml
+++ b/doc/src/sgml/ref/pgupgrade.sgml
@@ -678,32 +678,52 @@ psql --username=postgres --file=script.sql postgres
      
       
        
-        If you ran pg_upgrade
-        with --check, no modifications were made to the old
-        cluster and you can re-use it anytime.
+        If the --check option was used, the old cluster
+        was unmodified;  it can be restarted.
        
       
 
       
        
-        If you ran pg_upgrade
-        with --link, the data files are shared between the
-        old and new cluster. If you started the new cluster, the new
-        server has written to those shared files and it is unsafe to
-        use the old cluster.
+        If the --link option was not
+        used, the old cluster was unmodified;  it can be restarted.
        
       
 
       
        
-        If you ran pg_upgrade without
-        --link or did not start the new server, the
-        old cluster was not modified except that, if linking
-        started, a .old suffix was appended to
-        $PGDATA/global/pg_control.  To reuse the old
-        cluster, possibly remove the .old suffix from
-        $PGDATA/global/pg_control; you can then restart the
-        old cluster.
+        If the --link option was used, the data
+        files might be shared between the old and new cluster:
+
+        
+         
+          
+           If pg_upgrade aborted before linking started,
+           the old cluster was unmodified;  it can be restarted.
+          
+         
+
+         
+          
+           If you did not start the new cluster, the old
+           cluster was unmodified except that, when linking started, a
+           .old suffix was appended to
+           $PGDATA/global/pg_control.  To reuse the old
+           cluster, remove the .old suffix from
+           $PGDATA/global/pg_control; you can then restart
+           the old cluster.
+          
+         
+
+         
+          
+           If you did start the new cluster, it has written to shared files
+           and it is unsafe to use the old cluster.  The old cluster will
+           need to be restored from backup in this case.
+          
+         
+
+