From 5a6186cd7192c31ebf248548a538465b436275e5 Mon Sep 17 00:00:00 2001
From: Francois-Rene Rideau <tunes@google.com>
Date: Fri, 31 Jan 2014 00:35:06 -0500
Subject: [PATCH] Update the READMEs

---
 README      | 71 +++++++++++++++++++++++++++++++++++++++++------------
 uiop/README | 13 +++++++---
 2 files changed, 65 insertions(+), 19 deletions(-)

diff --git a/README b/README
index a6bb0517..1aae0cc2 100644
--- a/README
+++ b/README
@@ -1,36 +1,75 @@
-ASDF: another system definition facility
+ASDF: Another System Definition Facility
 ========================================
 
-If you cloned our git repository, bootstrap a copy of build/asdf.lisp with:
-    make
+Quick Summary
+-------------
 
-To run all the tests on your favorite Lisp implementation $L,
-choose your most elaborate installed system $S, and try:
-    make t u l=$L s=$S
+  1- Build it with::
+
+	make
+
+
+  2- Make sure you put it under a path registered by the source-registry,
+    if that isn't the case yet (see the manual). One place would be::
+
+	~/.local/share/common-lisp/source/asdf/
 
 
-To use ASDF, read our manual:
+What is ASDF?
+-------------
+
+ASDF is the de facto standard build facility for Common Lisp.
+
+If you come from the C/C++ world, the function ASDF covers a bit of what
+each of Make, autoconf, Make, dlopen and libc do for C programs:
+it orchestrates the compilation and dependency management,
+handles some of the portability issues, dynamically finds and loads code,
+and offers some portable system access.
+Except everything is different in Common Lisp, and ultimately much simpler,
+though it requires acquiring some basic concepts;
+notably, ASDF tries to make it all happen in the current Lisp image.
+
+To use ASDF, read our manual::
+
     http://common-lisp.net/project/asdf/asdf.html
+
 The first few sections, Loading ASDF, Configuring ASDF and Using ASDF,
 will get you started as a simple user.
 If you want to define your own systems, further read the section
 Defining systems with defsystem.
 
-
 ASDF 3 now includes an extensive runtime support library:
 UIOP, the Utilities for Implementation- and OS- Portability.
 Its documentation unhappily lies mainly in the source code and docstrings.
+See uiop/README for an introduction.
 
+More information and additional links can be found on ASDF's home page at::
 
-More information and additional links can be found on ASDF's home page at:
     http://common-lisp.net/project/asdf/
 
 
-Debugging tip:
-To load ASDF in such a way that M-. will work, install the source code, and run
-(asdf:load-system :uiop) ;; for uiop
-(dolist (c (asdf::required-components :asdf/defsystem
-             :keep-component 'asdf:cl-source-file))
-  (load (asdf:component-pathname c))) ;; for asdf/defsystem
+Building and testing it
+-----------------------
+
+If you cloned our git repository, bootstrap a copy of build/asdf.lisp with::
+
+    make
+
+To run all the tests on your favorite Lisp implementation $L,
+choose your most elaborate installed system $S, and try::
+
+    make t u l=$L s=$S
+
+
+Debugging tip
+-------------
+
+To load ASDF in such a way that M-. will work, install the source code, and run::
+
+  (asdf:load-system :uiop) ;; for uiop
+  (map () 'load ;; for asdf/defsystem
+   (mapcar 'asdf:component-pathname
+    (asdf::required-components :asdf/defsystem :keep-component 'asdf:cl-source-file)))
+
 
-Last updated Wednesday, January 8th, 2014.
+Last updated Wednesday, January 31st, 2014.
diff --git a/uiop/README b/uiop/README
index 20c75462..a23f7c86 100644
--- a/uiop/README
+++ b/uiop/README
@@ -75,8 +75,15 @@ If not, then it's a legitimate bug that we invite you to report.
 
 Maybe some automated tool will extract all that information and
 make a webpage from it, at which point it would be nice to insert a link here.
-Unhappily, at the time of this writing, quickdocs only extracts information
-from the first package::
+
+One tool with which you can extract all the documentation is HEΛP.
+At this time, the interface is not great, but if you use the scrollbar on the right
+of the left side panel, you can see many packages and from there the defined symbols::
+
+	http://bimib.disco.unimib.it/people/Marco.Antoniotti/Projects/CL/HELAMBDAP/tests/asdf-uiop/docs/html/dictionary/dictionary.html
+
+Another automated documentation tool is quickdocs, but unhappily, at the time of this writing,
+it only extracts information from the first package::
 
 	http://quickdocs.org/uiop/api
 
@@ -112,5 +119,5 @@ SLIME's swank-loader (UIOP has better compilation and API identification),
 TRIVIAL-BACKTRACE (UIOP/IMAGE has all of it and more), etc.
 
 UIOP also captures a large subset of the functionality from TRIVIAL-FEATURES,
-and a small subset of the functionality from ALEXANDRIA.
+and a small subset of the functionality from ALEXANDRIA or FARE-UTILS.
 
-- 
GitLab