From 9aba99254a0506204427b484b451657759765d28 Mon Sep 17 00:00:00 2001
From: "Robert P. Goldman" <rpgoldman@real-time.com>
Date: Mon, 5 Oct 2009 09:43:16 -0500
Subject: [PATCH] Mostly completed the getting started/using ASDF component.

---
 asdf.texinfo | 154 ++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 114 insertions(+), 40 deletions(-)

diff --git a/asdf.texinfo b/asdf.texinfo
index 8dd39531..f879ebd5 100644
--- a/asdf.texinfo
+++ b/asdf.texinfo
@@ -64,15 +64,15 @@ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 @insertcopying
 
 @menu
-* Introduction::
+* Introduction::                
 * Using asdf to load systems::  
 * Defining systems with defsystem::  
 * The object model of asdf::    
+* Controlling where ASDF saves compiled files::  
+* Special variables::           
 * Error handling::              
-* Controlling where ASDF saves compiled files::
-* Special variables::
 * Compilation error and warning handling::  
-* Miscellaneous additional functionality::
+* Miscellaneous additional functionality::  
 * Getting the latest version::  
 * TODO list::                   
 * missing bits in implementation::  
@@ -84,11 +84,16 @@ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 @detailmenu
  --- The Detailed Node Listing ---
 
+Using ASDF
+
+@c * Installing ASDF::             
+
 Defining systems with defsystem
 
 * The defsystem form::          
 * A more involved example::     
 * The defsystem grammar::       
+* Other code in .asd files::    
 
 The object model of asdf
 
@@ -137,23 +142,37 @@ and how to extend ASDF.
 
 @node  Using asdf to load systems, Defining systems with defsystem, Introduction, Top
 @comment  node-name,  next,  previous,  up
-@chapter Using asdf to load systems
-@cindex system directory designator
+@chapter Using ASDF
 @vindex *central-registry*
+@findex load-system
+@findex compile-system
+@findex test-system
+@cindex system directory designator
+@findex operate
+@findex oos
 
-This chapter describes how to use asdf to compile and load ready-made
-Lisp programs and libraries.
+@c @menu
+@c * Installing ASDF::             
+@c @end menu
+
+@section Installing ASDF
+
+Many Lisp implementations include a copy of ASDF. You can
+usually load this copy using Common-Lisp's @code{require}
+function: 
 
-@section Downloading asdf
+@kbd{(require 'asdf)}
 
-Some Lisp implementations (such as SBCL and OpenMCL) come with asdf
-included already, so you don't need to download it separately.1
-Consult your Lisp system's documentation.  If you need to download
-asdf and install it by hand, the canonical source is the cCLan CVS
-repository at
-@url{http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/cclan/asdf/}.
+Consult your Lisp implementation's documentation for details. If ASDF
+doesn't come bundled with your Lisp or if you want to make
+sure that you have the most recent version, then you'll want
+to download it from the @url{http://common-lisp.net/project/asdf/,asdf-home} website.
 
-@section Setting up asdf
+@section Loading ASDF
+
+If your CL implementation does @emph{not} provide ASDF through the
+@code{require} feature, then you need to download ASDF and load it
+yourself.
 
 The single file @file{asdf.lisp} is all you need to use asdf normally.
 Once you load it in a running Lisp, you're ready to use asdf.  For
@@ -162,6 +181,41 @@ start your Lisp implementation, for example by loading it from the
 startup script or dumping a custom core -- check your Lisp
 implementation's manual for details.
 
+@section Setting up a system to be loaded
+
+To compile and load a system, you need to ensure that its
+system definition can be found in one of the directories in
+@code{*central-registry*}@footnote{It is possible to customize the
+system definition file search.  That's considered advanced use, and
+covered later: search forward for
+@code{*system-definition-search-functions*}.  @xref{Defining systems
+with defsystem}.}.
+
+There are two ways that you can make a system definition findable
+through @code{*central-registry*}.  One is to simply insert into 
+@code{*central-registry*} an entry that specifies the pathname of for
+the directory containing the system definition file (a file whose name
+is of the form @code{*.asd}).  
+For example, if we had a
+system @var{foo} that is stored in a directory
+@file{/home/me/src/foo/}, containing  @file{/home/me/src/foo/}, we could
+make the foo system asdf-operable by doing @kbd{(push
+"/home/me/src/foo/" asdf:*central-registry*)}.
+
+ASDF will also properly handle the case where the
+@code{*central-registry*} points to a directory containing a
+@emph{symbolic link} to the system definition file.
+
+For example, if @code{#p"/home/me/cl/systems/"} (note the trailing
+slash) is a member of @code{*central-registry*}, you could set up the
+system @var{foo} for loading with asdf with the following
+commands at the shell:
+
+@example
+$ cd /home/me/cl/systems/
+$ ln -s ~/src/foo/foo.asd .
+@end example
+
 The variable @code{asdf:*central-registry*} is a list of ``system
 directory designators''@footnote{When we say ``directory'' here, we
 mean ``designator for a pathname with a supplied DIRECTORY
@@ -178,44 +232,64 @@ to a directory to look in.  You might want to set or augment
          asdf:*central-registry*))
 @end lisp
 
-@section Setting up a system to be loaded
-
-To compile and load a system, you need to ensure that a symbolic link to its
-system definition is in one of the directories in
-@code{*central-registry*}@footnote{It is possible to customize the
-system definition file search.  That's considered advanced use, and
-covered later: search forward for
-@code{*system-definition-search-functions*}.  @xref{Defining systems
-with defsystem}.}.
-
-For example, if @code{#p"/home/me/cl/systems/"} (note the trailing
-slash) is a member of @code{*central-registry*}, you would set up a
-system @var{foo} that is stored in a directory
-@file{/home/me/src/foo/} for loading with asdf with the following
-commands at the shell (this has to be done only once):
-
-@example
-$ cd /home/me/cl/systems/
-$ ln -s ~/src/foo/foo.asd .
-@end example
-
 @section Loading a system
 
+@c{FIXME:  Add Gary's material about loading system definitions by hand.}
+@c{FIXME:  Introduce ASDF-binary-locations.}
+
 The system @var{foo} is loaded (and compiled, if necessary) by
 evaluating the following form in your Lisp implementation:
 
 @example
-(asdf:operate 'asdf:load-op '@var{foo})
+(asdf:load-system '@var{foo})
 @end example
 
+(In older versions of ASDF, you may need to use @code{asdf:oos}, instead.)
+
 Output from asdf and asdf extensions are supposed to be sent to the CL
 stream @code{*standard-output*}, and so rebinding that stream around
 calls to @code{asdf:operate} should redirect all output from asdf
 operations.
 
+ASDF provides three commands for the most common system
+operations: @code{load-system}, @code{compile-system} or @code{test-system}.
+
+Because ASDF is an extensible system for defining
+@emph{operations} on @emph{components} also provides a generic
+function: @code{operate} (which is usually abbreviated by
+@code{oos}). You'll use @code{oos} whenever you want to do something
+beyond compiling, loading and testing.
+
+Reminder: before ASDF can operate on a system, however, it must be able
+to find and load that system's definition.
+
+@section Summary
+
+To use ASDF:
+
+@itemize
+@item 
+load @file{asdf.lisp} into your Lisp image, either through
+@code{require} or @code{load}.
+
+@item 
+make sure ASDF can find system definitions by loading them
+yourself or setting up @code{*central-registry*}.
+
+@item 
+use @code{operate} (or shorthand @code{oos})
+to tell ASDF what you'd like to do to what systems.
+For simple operations, you can use @code{load-system}, @code{compile-system} or @code{test-system}
+instead.
+
+@end itemize
+
+@section Moving on 
+
 That's all you need to know to use asdf to load systems written by
 others.  The rest of this manual deals with writing system
-definitions for Lisp software you write yourself.
+definitions for Lisp software you write yourself, including how to
+extend ASDF to define new operation and component types.
 
 @node   Defining systems with defsystem, The object model of asdf, Using asdf to load systems, Top
 @comment  node-name,  next,  previous,  up
@@ -229,7 +303,7 @@ software.
 * The defsystem form::          
 * A more involved example::     
 * The defsystem grammar::       
-* Other code in .asd files::
+* Other code in .asd files::    
 @end menu
 
 @node  The defsystem form, A more involved example, Defining systems with defsystem, Defining systems with defsystem
-- 
GitLab