Issue #241: checkpoint in user guide docs and tests

.travis.yml

@@ -24,8 +24,8 @@ env:
 
 #   - ST=Pharo-2.0 LoadList="'TravisCI_1' 'TravisCI_2'" TRAVIS_SCRIPT=travisCI.st
 #   - ST=Pharo-2.0 LoadList="'TravisCI_3'" TRAVIS_SCRIPT=travisCI.st
-   - ST=GemStone-3.2.2 LoadList="'TravisCI_1' 'TravisCI_2'" TRAVIS_SCRIPT=travisCI.st
-   - ST=GemStone-3.2.2 LoadList="'TravisCI_3'" TRAVIS_SCRIPT=travisCI.st
+#   - ST=GemStone-3.2.2 LoadList="'TravisCI_1' 'TravisCI_2'" TRAVIS_SCRIPT=travisCI.st
+#   - ST=GemStone-3.2.2 LoadList="'TravisCI_3'" TRAVIS_SCRIPT=travisCI.st
 #   - ST=Squeak-4.5 LoadList="'TravisCI_1' 'TravisCI_2'" TRAVIS_SCRIPT=travisCI.st 
 #   - ST=Squeak-4.5 LoadList="'TravisCI_3'" TRAVIS_SCRIPT=travisCI.st # until Issue 
 #

docs/MetacelloUserGuide.md

@@ -70,8 +70,6 @@ Metacello new
   load.
 ```
 
-#PROGRESS MARKER
-
 ##Listing
 
 Once you've loaded one or more projects into your image, you may want to
@@ -97,7 +95,7 @@ specifying the names of the projects you'd like to select:
 
 ```Smalltalk
 Metacello registry
-  configuration: #('Seaside30' 'MetacelloPreview');
+  configuration: #('Seaside3' 'MetacelloPreview');
   list.
 ```
 
@@ -126,7 +124,7 @@ with `Seaside` in the
 Once you've loaded a project into your image the next logical step is
 upgrading your project to a new version. 
 
-Let's say that a new `#stable` version of Seaside30 has been released
+Let's say that a new `#stable` version of Seaside3 has been released
 and that you want to upgrade. This is a two step process: 
 
 * [get a new version of the configuration][11]
@@ -147,7 +145,7 @@ By using the `image` message, you can leverage the fact that the [registry][8] r
 from which repository you loaded the original version of the configuration.
 
 The `get` command simply downloads the latest version of the
-configuration package from the repository.
+configuration package from that repository.
 
 You may download the configuration from a different repository:
 
@@ -166,12 +164,12 @@ into your image without actually loading the project itself:
 
 ```Smalltalk
 Metacello image
-  configuration: 'SeasideRest';
-  repository: 'http://smalltalkhub.com/mc/Seaside/MetacelloConfigurations/main';
+  configuration: 'Magritte3';
+  repository: 'http://smalltalkhub.com/mc/Magritte/Magritte3/main';
   get.
 ```
 
-The 'SeasideRest' project information will be registered in the [registry][8] and marked
+The 'Magritte3' project information will be registered in the [registry][8] and marked
 as *unloaded*.
 
 ### Load the new version
@@ -194,11 +192,11 @@ command operation.
 Of course, the `load` command updates the [registry][8].
 
 If you want to load a project for which you've already done a `get`
-(like the SeasideRest project earlier), you can do the following:
+(like the Magritte project earlier), you can do the following:
 
 ```Smalltalk
 Metacello registry
-  configuration: 'SeasideRest';
+  configuration: 'Magritte';
   version: #stable;
   load.
 ```
@@ -208,21 +206,21 @@ interested in both *loaded* and *unloaded* projects.
 
 ##Locking
 
-Let's say that you are using an older version of Seaside30 (say 3.0.5)
-instead of the #stable version (3.0.7) and that your application doesn't
-work with newer versions of Seaside30 (you've tried and it's more work
-to get you application to work with the newer version of Seaside30 than
+Let's say that you are using an older version of Seaside3 (say 3.1.1)
+instead of the #stable version (3.1.3) and that your application doesn't
+work with newer versions of Seaside3 (you've tried and it's more work
+to get you application to work with the newer version of Seaside3 than
 it's worth).
 
 Let's also say that you want to try out something in the
-SeasideRest project, but when you try loading SeasideRest, you end up
-having Seaside 3.0.7 loaded as well. 
+Magritte project, but when you try loading Magritte, you end up
+having Seaside 3.1.3 loaded as well. 
 
 This is an unfortunate side effect of Metacello trying to *do the right
 thing*, only in your case it is the wrong thing.
 
 Fortunately, the [`lock` command][9] can give you control. First you
-need to `lock` the Seaside30 project:
+need to `lock` the Seaside3 project:
 
 ```Smalltalk
 Metacello image
@@ -256,8 +254,7 @@ you can use `onWarning:` to log and resume the Warning:
 
 ```Smalltalk
 Metacello registry
-  configuration: 'SeasideRest';
-  version: #stable;
+  configuration: 'Magritte3';
   onWarning: [:ex | 
     Transcript cr; show: 'Warning: ', ex description.
     ex resume ];
@@ -269,29 +266,27 @@ which is only triggered when a locked project is involved:
 
 ```Smalltalk
 Metacello registry
-  configuration: 'SeasideRest';
-  version: #stable;
+  configuration: 'Magritte3';
   onLock: [:ex :existing :new | 
     Transcript cr; show: 'Locked project: ', existing projectName printString.
-    ex pass ];
+    ex honor];
   load.
 ```
 
-### Bypassing locks
+### Breaking locks
 
-Let's say that when you load the SeasideRest project you have decided
+Let's say that when you load the Magritte3 project you have decided
 that in this particular case you would like to bypass the lock and let
-the version of Seaside specified by the SeasideRest project to be loaded.
+the version of Seaside specified by the Magritte3 project to be loaded.
 
-We'll use `onLock:` to `break` the new version of the Seaside project to
+We'll use `onLock:` to `break` the lock and allow the new version of the Seaside project to
 be loaded:
 
 ```Smalltalk
 Metacello registry
-  configuration: 'SeasideRest';
-  version: #stable;
+  configuration: 'Magritte3';
   onLock: [:ex :existing :new | 
-    existing baseName = 'Seaside31'
+    existing baseName = 'Seaside3'
       ifTrue: [ ex break ].
     ex pass ];
   load.

tests/userGuide.st

@@ -79,40 +79,30 @@ Smalltalk at: #ConfigurationOfGLASS ifPresent: [:ignored |
 "Run smattering of expressions used in Metacello User Guide ... 
  not all expressions are implemented yet...
  We just want these expressions to run without error"
-
+[
 Transcript cr; show: '---Start running documentation script..'.
 
+"Loading"
 Transcript cr; show: '---get (default)'.
 Metacello new
   configuration: 'Seaside3';
   get.
 
 Transcript cr; show: '---load (default)'.
-[
   Metacello new
     configuration: 'Seaside3';
-    load ] 
-      on: Warning
-      do: [:ex | 
-        Transcript cr; show: ex description.
-        ex resume ].
-
-Transcript cr; show: '---get'.
-Metacello new
-  configuration: 'Seaside3';
-  smalltalkhubUser: 'Seaside' project: 'MetacelloConfigurations';
-  get.
+    load.
 
 Transcript cr; show: '---load'.
 Metacello registry
   configuration: 'Seaside3';
   version: #stable;
-  onWarning: [:ex | 
-    Transcript cr; show: 'WARNING: ', ex description.
-    ex resume];
-  onUpgrade: [:ex | ex allow ];
+  onConflict: [:ex | ex allow ];
+  smalltalkhubUser: 'Seaside' project: 'MetacelloConfigurations';
+  get;
   load.
 
+"Listing"
 Transcript cr; show: '---list (1)'.
 Metacello image
   configuration: [:spec | true ];
@@ -128,6 +118,7 @@ Metacello new
   smalltalkhubUser: 'Seaside' project: 'Seaside31';
   list.
 
+"Getting"
 Transcript cr; show: '---get (image)'.
 Metacello image
   configuration: 'Seaside3';
@@ -139,10 +130,33 @@ Metacello image
   smalltalkhubUser: 'Seaside' project: 'MetacelloConfigurations';
   get.
 
+Transcript cr; show: '---get (Magritte3)'.
+Metacello image
+  configuration: 'Magritte3';
+  repository: 'http://smalltalkhub.com/mc/Magritte/Magritte3/main';
+  get.
+
+"Load the new version"
+Transcript cr; show: '---load (Seaside3)'.
+Metacello image
+  configuration: 'Seaside3';
+  version: #stable;
+  load.
+
+Transcript cr; show: '---load (Magritte3)'.
+Metacello image
+  configuration: 'Seaside3';
+  lock. "lock to preserve currently loaded Seaside..."
+
+Metacello registry
+  configuration: 'Magritte';
+  version: #stable;
+  load.
+
+"Locking"
 Transcript cr; show: '---lock'.
 Metacello image
   configuration: 'Seaside3';
-  version: #'stable';
   lock.
 
 Transcript cr; show: '---lock (3.1.2)'.
@@ -151,19 +165,45 @@ Metacello image
   version: '3.1.2';
   lock.
 
-Transcript cr; show: '---load (Zinc)'.
-Metacello new
-  baseline: 'Zinc';
-  repository: 'github://glassdb/zinc:gemstone3.1/repository';
-  get;
-  load: 'Tests'.
+Transcript cr; show: '---lock warning'.
+Metacello registry
+  configuration: 'Magritte3';
+  onWarning: [:ex | 
+    Transcript cr; show: 'Warning: ', ex description.
+    ex resume ];
+  load.
 
-Transcript cr; show: '---load (Zinc onConflict)'.
+Transcript cr; show: '---lock tracking'.
 Metacello registry
-  baseline: 'Zinc';
-  onConflict: [:ex | ex useNew ];
-  get;
-  load: 'Tests'.
+  configuration: 'Magritte3';
+  onLock: [:ex :existing :new | 
+    Transcript cr; show: 'Locked project: ', existing projectName printString.
+    ex pass ];
+  load.
+
+Transcript cr; show: '---lock breaking'.
+Metacello registry
+  configuration: 'Magritte3';
+  onLock: [:ex :existing :new | 
+    existing baseName = 'Seaside3'
+      ifTrue: [ ex break ].
+    ex pass ];
+  load.
+
+"upgrading a locked project"
+Transcript cr; show: '---lock upgrading'.
+Metacello image
+  configuration: 'Seaside3';
+  version: '3.1.2';
+  lock.
+
+"locking example"
+
+] 
+  on: Warning
+  do: [:ex | 
+    Transcript cr; show: ex description.
+    ex resume ]
 
 TravisCISuccessNoFailure
       value: 'TravisCISuccess.txt'.