--- a/Autoload.st	Wed Nov 26 09:47:42 2014 +0100
+++ b/Autoload.st	Wed Nov 26 10:08:21 2014 +0100
@@ -36,28 +36,46 @@
 
 documentation
 "
-    In memory limited systems (as my 8Mb 386 is) all seldom-used classes are made
-    subclasses of this class. 
-    Autoload catches all messages and files-In the corresponding code
-    when first used. 
-    Then the caught message is resent to the (now existing) class.
+    Autoload is a stub for an 'as yet unloaded' class.
+
+    In memory limited systems (as my original 8Mb 386 system was), 
+    all seldom-used classes were made subclasses of this class. 
+    Autoload catches all messages sent to it, and files-in the real class's 
+    code when first used. Then the caught message is resent to the (now existing) class.
 
+    A note from later days:
+        Theses days, systems usually have enough memory to allow
+        having all classes present, so many of the classes which used to be
+        autoloaded are no longer these days. However, a number of examples or
+        very seldom used frameworks are still present as autoloaded.
+        Instead of using autoloaded classes, it is now recommended to bundle
+        extra classes into packages, which are loaded en-bloque.
+        Packages can be compiled to a shared class library and thus be loaded
+        much faster (there is no need to parse and compile source files).
+
+    Lazy loading:
     Class files are searched along the searchPath (see Smalltalk),
-    and any of binary-classFile, byteCode-classFile or sourceFile are
-    loaded, whichever is found first. For binaries to be loaded,
-    these must be found in the 'bin' directory. Sources must be found
-    in the 'source' directory.
-    (Usually, Autoload classes finds the source file and loads that one).
+    and any of binary-classFile, byteCode-classFile or sourceFile are loaded, 
+    whichever is found first. 
+    For binaries to be loaded, these must be found in a package-subdirectory
+    along the so called package path. 
+    Sources in a package directory along the source path.
+    In practice, most Autoloaded classes are found and loaded as source file.
 
-    When started, the patches startup script arranges for the abbreviation
-    file 'include/abbrev.stc' to be read and installs autoload stubs for
-    all classes listed in that file, which do not exist already.
-    The abbreviation file is maintained by the production environment
-    and updated by makefile rules - therefore, it should not be edited
-    manually.
+    Initial Setup of Auoload Stubs:
+    At initial startup (i.e. when ST/X is NOT coming up with an image),
+    the 'patches' startup script recursively walks along all directories
+    below the TOP directory (that is one above the stx folder),
+    and installs autoload stubs for all .st class files found, for which no
+    corresponding class is already present.
+    As you can imagine, this takes a long time and makes the initial startup quite slow.
+    Therefore, this scheme is no longer the recommended one and we (at exept)
+    always start ST/X with the '--quick' option, which skips this scan operation.
 
-    Late addition: above comment is no longer true - I have made now almost
-    all Demos & Goodies be autoloaded ... even for big systems.
+    Advantage of Autoload stubs:
+    Autoload stubs make it easier for a beginner to ST/X, to see what frameworks and classes
+    are there, as they appear in the browser with category and class name (although no
+    more details are initially visible.
 
     [class variables:]
         
@@ -822,11 +840,11 @@
 !Autoload class methodsFor:'documentation'!
 
 version
-    ^ '$Header: /cvs/stx/stx/libbasic/Autoload.st,v 1.168 2014-02-13 18:43:02 cg Exp $'
+    ^ '$Header: /cvs/stx/stx/libbasic/Autoload.st,v 1.169 2014-11-26 09:08:21 cg Exp $'
 !
 
 version_CVS
-    ^ '$Header: /cvs/stx/stx/libbasic/Autoload.st,v 1.168 2014-02-13 18:43:02 cg Exp $'
+    ^ '$Header: /cvs/stx/stx/libbasic/Autoload.st,v 1.169 2014-11-26 09:08:21 cg Exp $'
 ! !