From a1e01f1dec2fc9c6323489cde1979da5ab998d6b Mon Sep 17 00:00:00 2001
From: Francois-Rene Rideau <tunes@google.com>
Date: Tue, 27 Nov 2012 23:39:59 -0500
Subject: [PATCH] Quickly document force-not, require-system,
 *load-system-operation*.

---
 doc/asdf.texinfo | 67 +++++++++++++++++++++++++++++++++---------------
 1 file changed, 47 insertions(+), 20 deletions(-)

diff --git a/doc/asdf.texinfo b/doc/asdf.texinfo
index 83eb9aa4..35cc9df4 100644
--- a/doc/asdf.texinfo
+++ b/doc/asdf.texinfo
@@ -644,7 +644,8 @@ by evaluating the following Lisp form:
 @end example
 
 On some implementations (namely recent versions of
-ABCL, Allegro CL, Clozure CL, CMUCL, ECL, GNU CLISP, LispWorks, MKCL, SBCL and XCL),
+ABCL, Allegro CL, Clozure CL, CMUCL, ECL, GNU CLISP,
+LispWorks, MKCL, SBCL and XCL),
 ASDF hooks into the @code{CL:REQUIRE} facility
 and you can just use:
 
@@ -695,6 +696,13 @@ Reminder: before ASDF can operate on a system, however,
 it must be able to find and load that system's definition.
 @xref{Configuring ASDF,,Configuring ASDF to find your systems}.
 
+For the advanced users, note that
+@code{require-system} calls @code{load-system}
+with keyword arguments @code{:force-not (loaded-systems)}.
+@code{loaded-systems} returns a list of the names of loaded systems.
+@code{load-system} applies @code{operate} with the operation from
+@code{*load-system-operation*}, which by default is @code{load-op},
+the system, and any provided keyword arguments.
 
 @section Summary
 
@@ -1316,8 +1324,8 @@ and easier than having them all be @code{EQL} methods.
 
 Operations are invoked on systems via @code{operate}.
 @anchor{operate}
-@deffn {Generic function} @code{operate} @var{operation} @var{system} @&rest @var{initargs}
-@deffnx {Generic function} @code{oos} @var{operation} @var{system} @&rest @var{initargs}
+@deffn {Generic function} @code{operate} @var{operation} @var{system} @&rest @var{initargs} @&key @code{force} @code{force-not} @code{verbose} @&allow-other-keys
+@deffnx {Generic function} @code{oos} @var{operation} @var{system} @&rest @var{initargs} @&key @&allow-other-keys
 @code{operate} invokes @var{operation} on @var{system}.
 @code{oos} is a synonym for @code{operate}.
 
@@ -1332,6 +1340,16 @@ to invoke other operations on the system or its components:
 the new operations will be created
 with the same @var{initargs} as the original one.
 
+If @var{force} is @code{t}, then all systems
+are forced to be recompiled even if not modified since last compilation.
+If @var{force} is a list, then it specifies a list of systems that
+are forced to be recompiled even if not modified since last compilation.
+If @var{force-not} is @code{t}, then all systems
+are forced not to be recompiled even if modified since last compilation.
+If @var{force-not} is a list, then it specifies a list of systems that
+are forced not to be recompiled even if modified since last compilation.
+@var{force} takes precedences over @var{force-not};
+both of them apply to systems that are dependencies and were already compiled.
 @end deffn
 
 @menu
@@ -3256,9 +3274,9 @@ ASDF-dependent code you may check for this feature
 to see if the new API is present.
 @emph{All} versions of ASDF should have the @code{:asdf} feature.
 
-Additionally, all versions of asdf 2
+Additionally, all versions of ASDF 2
 define a function @code{(asdf:asdf-version)} you may use to query the version;
-and the source code of recent versions of asdf 2 features the version number
+and the source code of recent versions of ASDF 2 features the version number
 prominently on the second line of its source code.
 
 If you are experiencing problems or limitations of any sort with ASDF 1,
@@ -3477,7 +3495,8 @@ It is trivial to disable output translations.
 @xref{FAQ,,``How can I wholly disable the compiler output cache?''}.
 
 @item
-Some systems in the large have been known not to play well with output translations.
+Some systems in the large have been known
+not to play well with output translations.
 They were relatively easy to fix.
 Once again, it is also easy to disable output translations,
 or to override its configuration.
@@ -3497,9 +3516,11 @@ Other issues include the following:
 @itemize
 
 @item
-ASDF pathname designators are now specified in places where they were unspecified,
+ASDF pathname designators are now specified
+in places where they were unspecified,
 and a few small adjustments have to be made to some non-portable defsystems.
-Notably, in the @code{:pathname} argument to a @code{defsystem} and its components,
+Notably, in the @code{:pathname} argument
+to a @code{defsystem} and its components,
 a logical pathname (or implementation-dependent hierarchical pathname)
 must now be specified with @code{#p} syntax
 where the namestring might have previously sufficed;
@@ -3527,20 +3548,26 @@ when recursing through directories.
 On Windows, only LispWorks supports proper default configuration pathnames
 based on the Windows registry.
 Other implementations make do with environment variables,
-that you may have to define yourself if you're using an older version of Windows.
+that you may have to define yourself
+if you're using an older version of Windows.
 Windows support is somewhat less tested than Unix support.
 Please help report and fix bugs.
+@emph{Update}: As of ASDF 2.21, all implementations
+should now use the same proper default configuration pathnames
+and they should actually work, though they haven't all been tested.
 
 @item
 The mechanism by which one customizes a system so that Lisp files
 may use a different extension from the default @file{.lisp} has changed.
-Previously, the pathname for a component was lazily computed when operating on a system,
+Previously, the pathname for a component
+was lazily computed when operating on a system,
 and you would
 @code{(defmethod source-file-type ((component cl-source-file) (system (eql (find-system 'foo))))
   (declare (ignorable component system)) "lis")}.
 Now, the pathname for a component is eagerly computed when defining the system,
 and instead you will @code{(defclass cl-source-file.lis (cl-source-file) ((type :initform "lis")))}
-and use @code{:default-component-class cl-source-file.lis} as argument to @code{defsystem},
+and use @code{:default-component-class cl-source-file.lis}
+as argument to @code{defsystem},
 as detailed in a @pxref{FAQ,How do I create a system definition where all the source files have a .cl extension?} below.
 
 @findex source-file-type
@@ -3568,7 +3595,8 @@ Starting with current candidate releases of ASDF 2,
 it should always be a good time to upgrade to a recent ASDF.
 You may consult with the maintainer for which specific version they recommend,
 but the latest @code{release} should be correct.
-We trust you to thoroughly test it with your implementation before you release it.
+We trust you to thoroughly test it with your implementation
+before you release it.
 If there are any issues with the current release,
 it's a bug that you should report upstream and that we will fix ASAP.
 
@@ -3586,6 +3614,7 @@ if you allow such configuration.
 If your system provides a mechanism to hook into @code{CL:REQUIRE},
 then it would be nice to add ASDF to this hook the same way that
 ABCL, CCL, CLISP, CMUCL, ECL, SBCL and SCL do it.
+Please send us appropriate code to this end.
 
 @item
 You may, like SBCL, have ASDF be implicitly used to require systems
@@ -3949,13 +3978,9 @@ What would be a nice interface for this functionality?
 
 ** reuse the same scratch package whenever a system is reloaded from disk
 
-** proclamations probably aren't
-
-** when a system is reloaded with fewer components than it previously had, odd things happen
+Have a package ASDF-USER instead of all these temporary packages?
 
-We should do something inventive when processing a @code{defsystem} form,
-like take the list of kids and @code{setf} the slot to @code{nil},
-then transfer children from old to new list as they're found.
+** proclamations probably aren't
 
 ** (stuff that might happen later)
 
@@ -3965,9 +3990,11 @@ then transfer children from old to new list as they're found.
 
         @code{(asdf:compile-system :araneida :force t)}
 
-also forces compilation of every other system the @code{:araneida} system depends on.
+also forces compilation of every other system
+the @code{:araneida} system depends on.
 This is rarely useful to me;
-usually, when I want to force recompilation of something more than a single source file,
+usually, when I want to force recompilation
+of something more than a single source file,
 I want to recompile only one system.
 So it would be more useful to have @code{make-sub-operation}
 refuse to propagate @code{:force t} to other systems, and
-- 
GitLab