source: trunk/abcl/doc/manual/grovel.lisp

Last change on this file was 15067, checked in by Mark Evenson, 5 years ago

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.

File size: 4.1 KB
Line 
1(in-package :abcl/documentation)
2
3(defun grovel-docstrings-as-tex (&key
4                                   (package
5                                    (find-package :java))
6                                   (directory
7                                    (asdf:component-pathname
8                                     (asdf:find-component :abcl/documentation 'grovel))))
9  "Transform exported symbols documentation in PACKAGE to DIRECTORY."
10  (let ((output-file (merge-pathnames
11                      (format nil "~A.tex" (string-downcase (package-name package)))
12                      directory))
13        (symbols (loop :for symbol :being :each :external-symbol :of package :collecting symbol)))
14    (with-open-file (stream output-file :direction :output)
15      (format t "Writing output to '~A'.~%" output-file)
16      (loop :for symbol :in (sort symbols
17                                  (lambda (a b)
18                                    (string-lessp (symbol-name a) (symbol-name b))))
19         :doing (let ((documentation (symbol-as-tex symbol)))
20                  (when documentation
21                    (format stream "~&~A~%~%" documentation)))))))
22
23(defun texify-string (string &optional remove)
24  (with-output-to-string (s)
25    (loop for char across string
26         do (if (find char '(#\& #\% #\# #\_))
27                (unless remove
28                  (write-char #\\ s)
29                  (write-char char s))
30                (write-char char s)))))
31
32(defun texify (thing)
33  "Return STRING with LaTeX-sensitive characters escaped.
34Downcase symbol names but leave strings alone."
35  (cond ((listp thing)
36         (format nil "~A" (mapcar #'texify thing)))
37        ((stringp thing) (texify-string thing))
38        ((symbolp thing) (texify-string (string-downcase (symbol-name thing))))))
39
40(defun arglist-as-tex (symbol)
41  (handler-case 
42      (loop :for arg :in (ext:arglist symbol)
43         :collecting (texify arg))
44    (t (e) 
45      (progn (warn "Failed to form arglist for ~A: ~A" symbol e)
46             (list "")))))
47
48(defvar *type-alist* 
49  '((:function 
50     . "Function")
51    (:macro 
52     . "Macro")
53    (:variable 
54     . "Variable")
55    (:class 
56     . "Class")
57    (:special-operator
58     . "Special Operator")
59    (:generic-function 
60     . "Generic Function")))
61
62(defun symbol-as-tex (symbol)
63  "Return the TeX representation of a SYMBOL as Tex."
64  (let (type documentation arglist doc symbol-name package-name)
65    (when (setf doc (swank-backend:describe-symbol-for-emacs symbol))
66        (cond 
67          ((find :function doc)
68           (setf type :function
69                 documentation (second doc)
70                 arglist (format nil "~{~A~^ ~}" (arglist-as-tex symbol))))
71          ((find :variable doc)
72           (setf type :variable 
73                 documentation (second doc)))
74          ((find :macro doc)
75           (setf type :macro
76                 documentation (second doc)))
77          ((find :generic-function doc)
78           (setf type :generic-function
79                 documentation (second doc)))
80          ((find :class doc)
81           (setf type :class
82                 documentation (second doc)))
83          ((find :special-operator doc)
84           (setf type :special-operator
85                 documentation (second doc)))
86          (t 
87           (warn "Unknown type of documentation for symbol ~A: ~A"
88                 symbol doc)))
89        (setf symbol-name (string-downcase 
90                           symbol)
91              package-name (string-downcase 
92                            (package-name (find-package (symbol-package symbol)))))
93        (format nil "~&\\paragraph{}
94\\label{~A:~A}
95\\index{~A}
96--- ~A: \\textbf{~A} [\\textbf{~A}] \\textit{~A}
97
98\\begin{adjustwidth}{5em}{5em}
99~A
100\\end{adjustwidth}"
101                (texify-string (package-name (find-package (symbol-package symbol))) t)
102                (texify-string (symbol-name symbol) t)
103                (texify-string (symbol-name symbol) t)
104                (cdr (assoc type *type-alist*))
105                (texify symbol-name)
106                (texify package-name)
107                (if arglist arglist "")
108                (if documentation (texify documentation) "")))))
109               
110               
111
112
113
114 
115         
116   
117     
Note: See TracBrowser for help on using the repository browser.