[alexandria.git] updated branch master: bb423c6... documentation baby-steps

[Nikodemus Siivola]

The branch master has been updated:
       via  bb423c64814e13537262cfa799d16ea9447411ed (commit)
      from  829db7c7cb06d0a1693af9d25292d666be3eb487 (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit bb423c64814e13537262cfa799d16ea9447411ed
Author: Nikodemus Siivola <nikodemus at random-state.net>
Date:   Tue Mar 23 09:05:29 2010 +0200

    documentation baby-steps
    
     * Default doc/Makefile command now generates all docs and cleans up
       temporary files.
    
     * Generate info as well, and use makeinfo to generate the html.
    
     * Spit out a ifnottex.include for @&key macros, etc for the benefit
       of makeinfo.
    
     * Clean up &WHOLE and &ENVIRONMENT from the lambda-lists.
    
     * MAKE-CIRCULAR-LIST was documented twice, oops.

-----------------------------------------------------------------------

Summary of changes:
 doc/Makefile           |   21 +++++++++++++++------
 doc/alexandria.texinfo |    5 +++--
 doc/docstrings.lisp    |   17 +++++++++++++++++
 3 files changed, 35 insertions(+), 8 deletions(-)

diff --git a/doc/Makefile b/doc/Makefile
index 0782a87..56e794a 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -1,10 +1,16 @@
-.PHONY: clean html pdf
+.PHONY: clean html pdf include clean-include clean-crap info doc
 
-clean:
-	rm -rf include *.aux *.cp *.fn *.fns *.ky *.log *.pg *.toc *.tp *.tps *.vr *.pdf *.html
+doc: pdf html info clean-crap
+
+clean-include:
+	rm -rf include
+
+clean-crap:
+	rm -f *.aux *.cp *.fn *.fns *.ky *.log *.pg *.toc *.tp *.tps *.vr
+
+clean: clean-include
+	rm -f  *.pdf *.html *.info
 
-# Hook into the super sekrit texinfo generator in the SBCL tree -- this is just a quick way
-# to bootrap documentation for now.
 include:
 	sbcl --eval '(progn (require :asdf) (require :alexandria))' \
 	--load docstrings.lisp \
@@ -15,4 +21,7 @@ pdf: include
 	texi2pdf alexandria.texinfo
 
 html: include
-	texi2html alexandria.texinfo
+	makeinfo --html --no-split alexandria.texinfo
+
+info: include
+	makeinfo alexandria.texinfo
diff --git a/doc/alexandria.texinfo b/doc/alexandria.texinfo
index d9b23ce..0158525 100644
--- a/doc/alexandria.texinfo
+++ b/doc/alexandria.texinfo
@@ -72,9 +72,11 @@ terms and conditions:
 
 @ifnottex
 
+ at include include/ifnottex.texinfo
+
 @node Top
 @comment  node-name,  next,  previous,  up
- at top sbcl
+ at top Alexandria
 
 @insertcopying
 
@@ -166,7 +168,6 @@ terms and conditions:
 @include include/fun-alexandria-lastcar.texinfo
 @include include/fun-alexandria-setf-lastcar.texinfo
 @include include/fun-alexandria-proper-list-length.texinfo
- at include include/fun-alexandria-make-circular-list.texinfo
 @include include/fun-alexandria-mappend.texinfo
 @include include/fun-alexandria-map-product.texinfo
 @include include/fun-alexandria-remove-from-plist.texinfo
diff --git a/doc/docstrings.lisp b/doc/docstrings.lisp
index 2ff7dff..51dda07 100644
--- a/doc/docstrings.lisp
+++ b/doc/docstrings.lisp
@@ -383,6 +383,9 @@ there is no corresponding docstring."
                      (cons (car x) (clean (cdr x) :optional t)))
                     ((cons (member &key))
                      (cons (car x) (clean (cdr x) :key t)))
+                    ((cons (member &whole &environment))
+                     ;; Skip these
+                     (clean (cdr x) :optional optional :key key))
                     ((cons cons)
                      (cons
                       (cond (key (if (consp (caar x))
@@ -824,6 +827,18 @@ package, as well as for the package itself."
                                     :if-exists :supersede)
     , at forms))
 
+(defun write-ifnottex ()
+  ;; We use @&key, etc to escape & from TeX in lambda lists -- so we need to
+  ;; define them for info as well.
+  (flet ((macro (name)
+                 (let ((string (string-downcase name)))
+                   (format *texinfo-output* "@macro ~A~%~A~%@end macro~%" string string))))
+    (macro '&allow-other-keys)
+    (macro '&optional)
+    (macro '&rest)
+    (macro '&key)
+    (macro '&body)))
+
 (defun generate-includes (directory packages &key (base-package :cl-user))
   "Create files in `directory' containing Texinfo markup of all
 docstrings of each exported symbol in `packages'. `directory' is
@@ -841,6 +856,8 @@ markup, you lose."
         (dolist (doc (collect-documentation (find-package package)))
           (with-texinfo-file (merge-pathnames (include-pathname doc) directory)
             (write-texinfo doc))))
+      (with-texinfo-file (merge-pathnames "ifnottex.texinfo" directory)
+        (write-ifnottex))
       directory)))
 
 (defun document-package (package &optional filename)
-- 
Alexandria hooks/post-receive