From db3ce3960f26dc2902dbc545a9ab7f4551fd3bb0 Mon Sep 17 00:00:00 2001
From: Francois-Rene Rideau <tunes@google.com>
Date: Fri, 28 Feb 2014 20:27:36 -0500
Subject: [PATCH] Manual: remove a bunch of obsolete remarks. Replace by a
 bibliography. Move a few items to TODO. Tweaks.

---
 TODO             |  14 +++-
 doc/asdf.texinfo | 199 ++++++++++++-----------------------------------
 2 files changed, 62 insertions(+), 151 deletions(-)

diff --git a/TODO b/TODO
index de7daf3b..6f328292 100644
--- a/TODO
+++ b/TODO
@@ -188,7 +188,15 @@
   A run of quicklisp is necessary, with an eye also for warnings
   from .asd's that might be overriding definitions in UIOP(!)
 
-* have a mode to explain WHY a component needs to be recompiled.
+* Diagnostics
+** have a mode to explain WHY a component needs to be recompiled.
+** A ``dry run'' of an operation can be made with the following form:
+     (let ((asdf:*verbose-out* *standard-output*))
+       (loop :for (op . comp) :in
+         (asdf/plan:plan-actions
+          (asdf/plan:make-plan nil '<operation-name> '<system-name> :force t))
+         :do (asdf:explain op comp)))
+   What would be a nice interface for this functionality?
 
 * have with-input-file use the encodings mechanism?
 ** Import asdf-encodings into UIOP? Sounds a lot of code for no users.
@@ -328,8 +336,10 @@ It looks like SWANK can be fixed soon, though, so we'll see.
 
 * ASDF4: search for this tag, rename things (incompatibly, thus) and cleanup code.
 
-* See message from 2014-01-27 05:26:44 GMT for stuff to document.
+* Documentation
+** See message from 2014-01-27 05:26:44 GMT for stuff to document.
    http://thread.gmane.org/gmane.lisp.asdf.devel/3675/focus=3695
+** style guide for .asd files
 
 * UIOP
 ** deferred-warnings support probably needs to be redone better.
diff --git a/doc/asdf.texinfo b/doc/asdf.texinfo
index 15a06525..d6029e90 100644
--- a/doc/asdf.texinfo
+++ b/doc/asdf.texinfo
@@ -99,8 +99,8 @@ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 * Miscellaneous additional functionality::
 * Getting the latest version::
 * FAQ::
-* TODO list::
-* Inspiration::
+* Ongoing Work::
+* Bibliography::
 * Concept Index::
 * Function and Class Index::
 * Variable Index::
@@ -4127,7 +4127,7 @@ mailing list
 @url{http://common-lisp.net/cgi-bin/mailman/listinfo/asdf-devel}
 
 
-@node FAQ, TODO list, Getting the latest version, Top
+@node FAQ, Ongoing Work, Getting the latest version, Top
 @comment  node-name,  next,  previous,  up
 @chapter FAQ
 
@@ -4495,7 +4495,7 @@ You may consult with the maintainer for which specific version they recommend,
 but the latest @code{release} should be correct.
 Though we do try to test ASDF releases against all implementations that we can,
 we may not be testing against all variants of your implementation,
-and we may not be running enough tetst;
+and we may not be running enough tests;
 we trust you to thoroughly test it with your own implementation
 before you release it.
 If there are any issues with the current release,
@@ -4678,13 +4678,10 @@ discussion.
 
 @subsection ``How can I cater for documentation generation in my system?''
 
-The ASDF developers are currently working to add a @code{doc-op}
-to the set of predefined ASDF operations.
-@xref{Predefined operations of ASDF}.
+Various ASDF extensions provide some kind of @code{doc-op} operation.
 See also @url{https://bugs.launchpad.net/asdf/+bug/479470}.
 
 
-
 @subsection ``How can I maintain non-Lisp (e.g. C) source files?''
 
 See @code{cffi}'s @code{cffi-grovel}.
@@ -4841,156 +4838,60 @@ Here's the procedure for experimenting with tests in a REPL:
 
 @comment FIXME: Add a FAQ about how to use a new system class...
 
-
-@node  TODO list, Inspiration, FAQ, Top
 @comment  node-name,  next,  previous,  up
-@chapter TODO list
+@node  Ongoing Work, Bibliography, FAQ, Top
+@unnumbered Ongoing Work
+For an active list of things to be done,
+see the @file{TODO} file in the source repository.
 
-Here is an old list of things to do,
-in addition to the bugs that are now tracked on launchpad:
+Also, bugs that are now tracked on launchpad:
 @url{https://launchpad.net/asdf}.
 
-@section Outstanding spec questions, things to add
-
-** packaging systems
-
-*** manual page component?
-
-** style guide for .asd files
-
-You should either use keywords or be careful
-with the package that you evaluate defsystem forms in.
-Otherwise @code{(defsystem partition ...)}
-being read in the @code{cl-user} package
-will intern a @code{cl-user:partition} symbol,
-which will then collide with the @code{partition:partition} symbol.
-
-Actually there's a hairier packages problem to think about too.
-@code{in-order-to} is not a keyword:
-if you read @code{defsystem} forms in a package that doesn't use ASDF,
-odd things might happen.
-
-
-** extending defsystem with new options
-
-You might not want to write a whole parser,
-but just to add options to the existing syntax.
-Reinstate @code{parse-option} or something akin.
-
-
-** Diagnostics
-
-A ``dry run'' of an operation can be made with the following form:
-
-@lisp
-(let ((asdf::*verbose-out* *standard-output*))
-  (loop :for (op . comp) :in
-    (asdf::traverse (make-instance '<operation-name> :force t)
-                    (asdf:find-system <system-name>))
-    :do (asdf:explain op comp)))
-@end lisp
-
-This uses unexported symbols.
-What would be a nice interface for this functionality?
-
-@section Missing bits in implementation
-
-** reuse the same scratch package whenever a system is reloaded from disk
-
-Have a package ASDF-USER instead of all these temporary packages?
-
-** proclamations probably aren't
-
-** A revert function
-
-Other possible interface: have a ``revert'' function akin to @code{make clean}.
-
-@lisp
-(asdf:revert 'asdf:compile-op 'araneida)
-@end lisp
-
-would delete any files produced by @code{(compile-system :araneida)}.
-Of course, it wouldn't be able to do much about stuff in the image itself.
-
-How would this work?
-
-@code{traverse}
-
-There's a difference between a module's dependencies (peers)
-and its components (children).
-Perhaps there's a similar difference in operations?
-For example, @code{(load "use") depends-on (load "macros")} is a peer,
-whereas @code{(load "use") depends-on (compile "use")}
-is more of a ``subservient'' relationship.
-
-@node  Inspiration, Concept Index, TODO list, Top
-@comment  node-name,  next,  previous,  up
-@chapter Inspiration
-
-@section mk-defsystem (defsystem-3.x)
-
-We aim to solve basically the same problems as @code{mk-defsystem} does.
-However, our architecture for extensibility
-better exploits CL language features (and is documented),
-and we intend to be portable rather than just widely-ported.
-No slight on the @code{mk-defsystem} authors and maintainers is intended here;
-that implementation has the unenviable task
-of supporting pre-ANSI implementations, which is no longer necessary.
-
-The surface defsystem syntax of asdf is more-or-less compatible with
-@code{mk-defsystem}, except that we do not support
-the @code{source-foo} and @code{binary-foo} prefixes
-for separating source and binary files, and
-we advise the removal of all options to specify pathnames.
-
-The @code{mk-defsystem} code for topologically sorting
-a module's dependency list was very useful.
-
-@section defsystem-4 proposal
-
-Marco and Peter's proposal for defsystem 4 served as the driver for
-many of the features in here.  Notable differences are:
+@node Bibliography, Concept Index, Ongoing Work, Top
+@unnumbered Bibliography
 
 @itemize
-@item
-We don't specify output files or output file extensions
-as part of the system.
-
-If you want to find out what files an operation would create,
-ask the operation.
-
-@item
-We don't deal with CL packages
-
-If you want to compile in a particular package, use an @code{in-package} form
-in that file (ilisp / SLIME will like you more if you do this anyway)
-
-@item
-There is no proposal here that @code{defsystem} does version control.
-
-A system has a given version which can be used to check dependencies,
-but that's all.
+@item Zach Beane:
+  ``Quicklisp'', 2011.
+  The Quicklisp blog and Xach's livejournal contain information on Quicklisp.
+  @url{http://blog.quicklisp.org/}
+  @url{http://xach.livejournal.com/}
+@item Francois-Rene Rideau and Robert Goldman:
+  ``Evolving ASDF: More Cooperation, Less Coordination'', 2010.
+  This article describes the main issues solved by ASDF 2.
+  @url{http://common-lisp.net/project/asdf/doc/ilc2010draft.pdf}
+  @url{http://www.common-lisp.org/gitweb?p=projects/asdf/ilc2010.git}
+@item Francois-Rene Rideau and Spencer Brody:
+  ``XCVB: an eXtensible Component Verifier and Builder for Common Lisp'', 2009.
+  This article describes XCVB, a proposed competitor for ASDF,
+  many ideas of which have been incorporated into ASDF 2 and 3,
+  though many other of which still haven't.
+  @url{http://common-lisp.net/projects/xcvb/}
+@item Dan Barlow: ``ASDF Manual'', 2004
+  Older versions of this document from the days of ASDF 1;
+  they include ideas laid down by Dan Barlow,
+  and comparisons with older defsystems (@code{mk-defsystem})
+  and defsystem (@code{defsystem-4}, kmp's Memo 801).
+@item Marco Antoniotti and Peter Van Eynde:
+ ``@code{DEFSYSTEM}: A @code{make} for Common Lisp, A Thoughtful Re-Implementation of an Old Idea'', 2002.
+  The @file{defsystem-4} proposal available in the CLOCC repository.
+@item Mark Kantrovitz: ``Defsystem: A Portable Make Facility for Common Lisp'', 1990.
+  The classic @file{mk-defsystem}, later variants of which
+  are available in the CLOCC repository as @code{defsystem-3.x}.
+@item Richard Elliot Robbins:
+  ``BUILD: A Tool for Maintaining Consistency in Modular Systems'', MIT AI TR 874, 1985.
+  @url{ftp://publications.ai.mit.edu/ai-publications/pdf/AITR-874.pdf}
+@item Kent M. Pitman (kmp): ``The Description of Large Systems'', MIT AI Memo 801, 1984.
+  Available in updated-for-CL form on the web at
+  @url{http://nhplace.com/kent/Papers/Large-Systems.html}
+@item Dan Weinreb and David Moon:
+  ``Lisp Machine Manual'', MIT, 1981.
+  The famous CHINE NUAL describes one of the earliest variants of DEFSYSTEM.
+  @url{https://bitsavers.trailing-edge.com/pdf/mit/cadr/chinual_4thEd_Jul81.pdf}
 @end itemize
 
-The defsystem 4 proposal tends to look more at the external features,
-whereas this one centres on a protocol for system introspection.
-
-@section kmp's ``The Description of Large Systems'', MIT AI Memo 801
-
-Available in updated-for-CL form on the web at
-@url{http://nhplace.com/kent/Papers/Large-Systems.html}
-
-In our implementation we borrow kmp's overall @code{PROCESS-OPTIONS}
-and concept to deal with creating component trees
-from @code{defsystem} surface syntax.
-[ this is not true right now, though it used to be and
-probably will be again soon ]
-
-
-@c -------------------
-
 
-@node Concept Index, Function and Class Index, Inspiration, Top
+@node Concept Index, Function and Class Index, Bibliography, Top
 @unnumbered Concept Index
 
 @printindex cp
-- 
GitLab