First half of User Manual edits prompted by Phillip Marek's review

ABCL/DOCUMENTATION reformatting with the only intentional function
change being the introduction of the exported INDEX function to grind
the documentation from available runtime symbols.  Something is still
funky about parameter lists for generic functions and macros.
parent 987f2662
......@@ -149,7 +149,11 @@ be in a directory named '../ansi-test/'."
:description "Tools to generate LaTeX source from docstrings."
:depends-on (swank)
:components
((:module grovel :pathname "doc/manual/" :serial t
:components ((:file "package")
((:module package
:pathname "doc/manual/" :components ((:file "package")))
(:module grovel
:depends-on (package)
:pathname "doc/manual/"
:components ((:file "index" :depends-on (grovel))
(:file "grovel")))))
......@@ -10,20 +10,13 @@ abcl.pdf: abcl.tex abcl.bib java.tex extensions.tex threads.tex
#ABCL = abcl
ABCL = ../../abcl
#ABCL = /Users/evenson/work/abcl-1.1.x/abcl
# XXX TODO 1) use more compact iterated form, 2) pare down to using --noinit
# XXX TODO pare down to using --noinit
grovel:
$(ABCL) --batch --noinform \
--eval '(require :abcl-contrib)' \
--eval '(require :jss)' \
--eval '(asdf:load-system :abcl/documentation)' \
--eval '(in-package :abcl/documentation)' \
--eval '(grovel-docstrings-as-tex :package :java)' \
--eval '(grovel-docstrings-as-tex :package :extensions)' \
--eval '(grovel-docstrings-as-tex :package :threads)' \
--eval '(grovel-docstrings-as-tex :package :system)' \
--eval '(grovel-docstrings-as-tex :package :jss)'
--eval '(asdf:make :abcl/documentation)' \
--eval '(abcl/documentation:index)'
clean:
rm -f *.aux *.bbl *.blg *.idx *.ilg *.ind *.log *.out *.toc abcl.pdf
(in-package :abcl/documentation)
(defun grovel-docstrings-as-tex (&key
(package (find-package :java))
(directory (asdf:component-pathname (asdf:find-component :abcl/documentation 'grovel))))
(package
(find-package :java))
(directory
(asdf:component-pathname
(asdf:find-component :abcl/documentation 'grovel))))
"Transform exported symbols documentation in PACKAGE to DIRECTORY."
(let ((output-file (merge-pathnames (format nil "~A.tex" (string-downcase (package-name package))) directory))
(let ((output-file (merge-pathnames
(format nil "~A.tex" (string-downcase (package-name package)))
directory))
(symbols (loop :for symbol :being :each :external-symbol :of package :collecting symbol)))
(with-open-file (stream output-file :direction :output)
(format t "Writing output to '~A'.~%" output-file)
(loop :for symbol :in (sort symbols (lambda (a b) (string-lessp (symbol-name a) (symbol-name b))))
(loop :for symbol :in (sort symbols
(lambda (a b)
(string-lessp (symbol-name a) (symbol-name b))))
:doing (let ((documentation (symbol-as-tex symbol)))
(when documentation
(format stream "~&~A~%~%" documentation)))))))
......
;;; bootstrap documentation rendering
(in-package abcl/documentation)
#+elisp
#+elisp ;; huh?
(slime-apropos-package "JAVA")
(defun index ()
"Regenerate TeX markup from symbol introspection."
(dolist (package '(:extensions
:system
:threads
:mop
:java
:jss ))
(grovel-docstrings-as-tex :package package)))
(defpackage #:abcl/documentation
(in-package :cl-user)
(defpackage abcl/documentation
(:use :cl)
(:export #:grovel-docstrings-as-tex))
(:export
#:index
#:grovel-docstrings-as-tex))
......@@ -656,7 +656,7 @@ public final class Java
private static final Primitive JARRAY_REF = new pf_jarray_ref();
@DocString(name="jarray-ref", args="java-array &rest indices",
doc="Dereferences the Java array JAVA-ARRAY using the given INDICIES, " +
doc="Dereferences the Java array JAVA-ARRAY using the given INDICES, " +
"coercing the result into a Lisp object, if possible.")
private static final class pf_jarray_ref extends Primitive
{
......@@ -674,7 +674,7 @@ public final class Java
private static final Primitive JARRAY_REF_RAW = new pf_jarray_ref_raw();
@DocString(name="jarray-ref-raw", args="java-array &rest indices",
doc="Dereference the Java array JAVA-ARRAY using the given INDICIES. " +
doc="Dereference the Java array JAVA-ARRAY using the given INDICES. " +
"Does not attempt to coerce the result into a Lisp object.")
private static final class pf_jarray_ref_raw extends Primitive
{
......@@ -692,7 +692,7 @@ public final class Java
private static final Primitive JARRAY_SET = new pf_jarray_set();
@DocString(name="jarray-set", args="java-array new-value &rest indices",
doc="Stores NEW-VALUE at the given index in JAVA-ARRAY.")
doc="Stores NEW-VALUE at the given INDICES in JAVA-ARRAY.")
private static final class pf_jarray_set extends Primitive
{
pf_jarray_set()
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or sign in to comment