A wee while ago, Sheldon Newhouse inquired if users could add to
maxima's online documentation
(http://www.math.utexas.edu/pipermail/maxima/2009/017266.html). I have
taken a look at src/cl-info.lisp where maxima's online help functions
are defined. It is quite easy to add a user-generated component that
maxima treats in paralle to its own online help, so I have done so.
Attached is the diff file for cl-info.lisp, a sample session
showing how one can generate one's own online documentation,
and a database that I generated (in a more extended bout of typing).
As you can see, one can easily document one's own work and even add
comments/tips/gotchas to maxima's own documentation.
------
If you wish to incorporate this into your version of maxima at the
moment, copy your src/cl-info.lisp and the cl-info.lisp.diff file to a
safe location and do
patch cl-info.lisp cl-info.lisp.diff -o cl-info-patch.lisp
in a terminal. You can then load this patched file into your maxima
session.
------
Here's a sample of how it works:
(%i2) load("cl-info.lisp")$
(%i3) load_userinfo_lisp()$
(%i4) ? user_doc
-- Usage: user_doc(name,doc,created)
user_doc(name,doc)
user_doc(name)
The args name and doc should be strings, created a boolean. In the final
form
the user is prompted to input a documentation string. This may stretch
over
several lines.
Each user-generated documentation event is appended to the file named by
the
maxima variable 'maxima_userinfo_lisp' in the directory named by
'maxima_userdir'.
This file may also be edited manually. Entries in this file are never
overwritten.
The user can load maxima_userinfo_lisp into a Maxima session by calling
'load_userinfo_lisp();'.
Examples:
(%i1) user_doc("sin","sin(x)=x-x^3/6+...");
(%i1) user_doc("sin");
Enter documentation string surrounded by quotes '"'. End input with ';'.
"sin(x) = x - x^3/6 + ...";
Source: src/cl-info.lisp
See also: ?, ??, maxima_userinfo_lisp, maxima_userdir,
load_userinfo_lisp.
Created: 2009-06-10 15:22:35+01:00
--------
Leo
--
The University of Edinburgh is a charitable body, registered in
Scotland, with registration number SC005336.
-------------- next part --------------
5,6d4
< (defvar *info-user-doc-hashtable* (make-hash-table :test 'equal))
< (defvar *user-doc-key* "user-documentation")
94,95c92
< (find-regex-matches topic *info-deffn-defvr-hashtable*)
< (find-regex-matches topic *info-user-doc-hashtable*)))
---
> (find-regex-matches topic *info-deffn-defvr-hashtable*)))
137,138c134
< (find-regex-matches topic *info-deffn-defvr-hashtable*)
< (find-regex-matches topic *info-user-doc-hashtable*)))
---
> (find-regex-matches topic *info-deffn-defvr-hashtable*)))
170d165
< (cond ((string/= (nth 4 x) *user-doc-key*)
186,188d180
< (t
< (let ((text (nth 1 x)))
< text))))
209,241d200
<
<
< (in-package :maxima)
< (defvar *maxima-userinfo-lisp* "maxima-userinfo.lisp")
< (def-lisp-shadow maxima-userinfo-lisp)
<
<
< (defun $user_doc (name &optional (doc-string "stdin") (created t))
< (cond ((and (stringp name) (stringp doc-string))
< (when (equal doc-string "stdin")
< (format *standard-output* "Enter documentation string surrounded by quotes '\"'. End input with ';'.~%")
< (setf doc-string (mread-noprompt *standard-input*)))
< (when created
< (setf doc-string (format nil "~a~%~%Created: ~a" doc-string ($timedate))))
< (setf (gethash name cl-info::*info-user-doc-hashtable*) (list doc-string nil nil cl-info::*user-doc-key*))
< (update-user-doc name doc-string))
< (t
< (error "Usage: user_doc(name,doc_string) where both arguments are strings")))
< name)
<
< (defun update-user-doc (name doc-string)
< (let* ((user-info-file (concatenate 'string *maxima-userdir* "/" *maxima-userinfo-lisp*)) (user-info-pn (pathname user-info-file)) strm)
< (with-open-file (strm user-info-pn :direction :output :if-exists :append :if-does-not-exist :create)
< (format strm "(setf (gethash ~S cl-info::*info-user-doc-hashtable*) '(~S nil nil ~S))~%" name doc-string cl-info::*user-doc-key*))))
<
< (defun $load_userinfo_lisp ()
< (let* ((user-info-file (concatenate 'string *maxima-userdir* "/" *maxima-userinfo-lisp*)) (user-info-pn (pathname user-info-file)))
< (load user-info-pn)))
<
< (defun $print_user_doc ()
< (let* ((user-info-file (concatenate 'string *maxima-userdir* "/" *maxima-userinfo-lisp*)) (user-info-pn (pathname user-info-file)) strm)
< (with-open-file (strm user-info-pn :direction :output :if-exists :supersede)
< (maphash #'(lambda (k v) (format strm "(setf (gethash ~S cl-info::*info-user-doc-hashtable*) '~S)~%" k v)) cl-info::*info-user-doc-hashtable*))))
-------------- next part --------------
(%i2) load("/knoppix-home/work/maxima/maxima-5.18.1-clisp/src/cl-info.lisp");
(%o2) "/knoppix-home/work/maxima/maxima-5.18.1-clisp/src/cl-info.lisp"
(%i3) load_userinfo_lisp();
(%o3) true
(%i4) ? tan
-- Function: tan (<x>)
- Tangent.
There are also some inexact matches for `tan'.
Try `?? tan' to see them.
(%o4) true
(%i5) user_doc("tan","opposite/adjacent");
(%o5) "tan"
(%i6) ? tan
-- Function: tan (<x>)
- Tangent.
opposite/adjacent
Created: 2009-06-10 17:37:50+01:00
There are also some inexact matches for `tan'.
Try `?? tan' to see them.
(%o6) true
(%i7) ? user_doc
-- Usage: user_doc(name,doc,created)
user_doc(name,doc)
user_doc(name)
The args name and doc should be strings, created a boolean. In the final form
the user is prompted to input a documentation string. This may stretch over
several lines.
Each user-generated documentation event is appended to the file named by the
maxima variable 'maxima_userinfo_lisp' in the directory named by 'maxima_userdir'.
This file may also be edited manually. Entries in this file are never overwritten.
The user can load maxima_userinfo_lisp into a Maxima session by calling
'load_userinfo_lisp();'.
Examples:
(%i1) user_doc("sin","sin(x)=x-x^3/6+...");
(%i1) user_doc("sin");
Enter documentation string surrounded by quotes '"'. End input with ';'.
"sin(x) = x - x^3/6 + ...";
Source: src/cl-info.lisp
See also: ?, ??, maxima_userinfo_lisp, maxima_userdir, load_userinfo_lisp.
Created: 2009-06-10 15:22:35+01:00
(%o7) true
(%i8) infix(":::")$ ":::"(a,b):=user_doc(string(a),b)$
(%i10) sin ::: "Recall: exp(%i*x) = cos(x)+%i*sin(x)"$
(%i11) ? sin
-- Function: sin (<x>)
- Sine.
Recall: exp(%i*x) = cos(x)+%i*sin(x)
Created: 2009-06-10 17:40:01+01:00
There are also some inexact matches for `sin'.
Try `?? sin' to see them.
-------------- next part --------------
(setf (gethash "user_doc" cl-info::*info-user-doc-hashtable*) '(
" -- Usage: user_doc(name,doc,created)
user_doc(name,doc)
user_doc(name)
The args name and doc should be strings, created a boolean. In the final form
the user is prompted to input a documentation string. This may stretch over
several lines.
Each user-generated documentation event is appended to the file named by the
maxima variable 'maxima_userinfo_lisp' in the directory named by 'maxima_userdir'.
This file may also be edited manually. Entries in this file are never overwritten.
The user can load maxima_userinfo_lisp into a Maxima session by calling
'load_userinfo_lisp();'.
Examples:
(%i1) user_doc(\"sin\",\"sin(x)=x-x^3/6+...\");
(%i1) user_doc(\"sin\");
Enter documentation string surrounded by quotes '\"'. End input with ';'.
\"sin(x) = x - x^3/6 + ...\";
Source: src/cl-info.lisp
See also: ?, ??, maxima_userinfo_lisp, maxima_userdir, load_userinfo_lisp.
Created: 2009-06-10 15:22:35+01:00" nil nil "user-documentation"))
(setf (gethash "maxima_userinfo_lisp" cl-info::*info-user-doc-hashtable*) '(
" -- maxima_userinfo_lisp: variable defined in cl-info.lisp shadowed by lisp variable
*maxima-userinfo-lisp*.
Name of file where user-generated documentation is stored.
Default: maxima-userinfo.lisp
Source: src/cl-info.lisp
See also: user_doc
Created: 2009-06-10 15:34:08+01:00" nil nil "user-documentation"))
(setf (gethash "load_userinfo_lisp" cl-info::*info-user-doc-hashtable*) '(
" -- Usage: load_userinfo_lisp()
Loads the user-generated documentation file named in 'maxima_userinfo_lisp' in
'maxima_tempdir'.
Source: src/cl-info.lisp
See also: ?, ??, maxima_userinfo_lisp, maxima_userdir, user_doc.
Created: 2009-06-10 15:44:53+01:00" nil nil "user-documentation"))
(setf (gethash "?" cl-info::*info-user-doc-hashtable*) '(
"
See also: user_doc, a function that lets the user generate online documentation.
" nil nil "user-documentation"))
(setf (gethash "??" cl-info::*info-user-doc-hashtable*) '("See also: user_doc, a function that lets the user generate online documentation." nil nil "user-documentation"))