Clementson's Blog

SLIME Tips and Techniques - Part 4 (Library Documentation)

Monday, January 29, 2007

If you use SLIME, the key chord "C-c C-d h" (which brings up the Common Lisp Hyperspec (CLHS) documentation for the CL symbol that is at "point" in the current SLIME buffer) is probably used quite frequently. However, the hyperspec.el code that ships with SLIME is limited in that it only looks up documentation for symbols that are defined in the CL standard.

In my .emacs file, I re-bind "C-c C-d h" to the cl-lookup function. This is an elisp package created by Yuji Minejima and it builds on and extends the hyperspec.el functionality provided by SLIME. Out-of-the-box, cl-lookup provides lookup for:

• hyperspec symbols (e.g. defun, dolist)
• hyperspec chapters (e.g. [index], [syntax])
• format control characters (e.g. "~C: Character", "~%: Newline")
• reader macro characters (e.g. "(", "#'", "#b", "#+")
• loop (e.g. loop:with, loop:collect)
• arguments (e.g. :test, :key, :eof-error-p)
• concepts (e.g. "lambda lists:", "character names:")
• glossary (e.g. {absolute}, {binding})
• MOP (e.g. add-dependent, ensure-class)
• Implementation-specific help for some CLISP functions (e.g. ext:cd)
• Library-specific help for the CL-PPCRE regular expression package (e.g. cl-ppcre:parse-tree-synonym)

(require :asdf)

(defparameter *packages-to-process*
  '((cl-ppcre "http://www.weitz.de/cl-ppcre/")
    (cl-fad "http://weitz.de/cl-fad/")
    (hunchentoot "http://weitz.de/hunchentoot/")
    (chunga "http://weitz.de/chunga/")
    (url-rewrite "http://weitz.de/url-rewrite/")
    (cl-who "http://weitz.de/cl-who/"))
  "List of packages and their documentation root urls.")

(defvar *base-code*
"(require 'cl-lookup)
(defvar cl-lookup-~a-root ~s)

(mapc #'(lambda (entry)
	  (destructuring-bind (name path) entry
	    (let ((symbol (intern (downcase name) cl-lookup-obarray)))
	      (if (boundp symbol)
		  (pushnew path (symbol-value symbol) :test #'equal)
		  (set symbol `(,path))))))
      '((~s (cl-lookup-~a-root ""))~%")

(defun create-lookup-file (&optional (packages *packages-to-process*))
  (dolist (p packages)
    (let* ((package (progn (asdf:oos 'asdf:load-op (first p)) (first p)))
	   (package-name (string-downcase (symbol-name package)))
	   (url (second p))
	   (output-file (format nil "cl-lookup-~a.el" package-name))
	   (symbols (sort (loop for sym being each external-symbol of package
			     collect (list (string-downcase (symbol-name sym))))
			  #'string-lessp :key #'car)))
      (with-open-file (s output-file :direction :output :if-exists :supersede)
	(format s *base-code* package-name url package-name package-name)
	(mapcar (lambda (sym)
		  (format s "~8t("~a:~a" (cl-lookup-~a-root "#~a"))~%"
			  package-name
			  (string-downcase (car sym))
			  package-name
			  (string-downcase (car sym))))
		symbols)
	(format s "~8t))~%~%(provide 'cl-lookup-~a)" package-name)))))

1. In the *packages-to-process* variable, I set the package names and base URL's (where the documentation for the package is located) for a number of Edi's libraries (in this case, it's for HUNCHENTOOT and its dependencies).
2. The *base-code* variable contains the elisp code that needs to be written out to add the library mappings to the cl-lookup object array.
3. In the create-lookup-file function:
   1. I use ASDF to load each library so that I can process the library's externally-visible symbols.
   2. I write out the base code needed for any documentation that will be added to the cl-lookup documentation lookup.
   3. I write out a sexp linking each of the library's symbols to the place in the HTML documentation where the documentation for the symbol is located.

;; Set up load path
(setq load-path (append (list "/path/to/slime"
			      "/path/to/mcomplete"
			      "/path/to/w3m"
			      "/path/to/cl-lookup")
			load-path))

(autoload 'slime "slime" "Start SLIME." t)
    
(add-hook 'lisp-mode-hook (lambda ()
                            (cond ((not (featurep 'slime))
                                   (require 'slime)
                                   (normal-mode)))))

(eval-after-load "slime"
  '(progn
     ;; SLIME setup
     (setq slime-lisp-implementations
	   `((openmcl ("dppccl"))
	     (sbcl ("sbcl"))
	     ,@slime-lisp-implementations))
     (slime-setup)
     ;; Use w3m for viewing HTML documentation
     (require 'w3m-load)
     (setq browse-url-browser-function 'w3m-browse-url)   
     ;; Use mcomplete for partial completions
     (require 'mcomplete)
     (turn-on-mcomplete-mode)  
     ;; Setup CL-LOOKUP for enhanced documentation access
     (setq cl-lookup-categories
	   ;; basic CL documentation
	   '(:hyperspec-index
	     :hyperspec-chapters
	     :format-control-characters
	     :reader-macro-characters
	     :loop
	     :arguments
	     :concepts
	     "cl-lookup-glossary"
	     "cl-lookup-mop"
	     ;; non-CLHS library documentation
	     "cl-lookup-cl-ppcre"
	     "cl-lookup-cl-fad"
	     "cl-lookup-chunga"
	     "cl-lookup-cl-who"
	     "cl-lookup-hunchentoot"
	     "cl-lookup-url-rewrite"
	     ))
     (put 'cl-lookup
	  'mcomplete-mode
	  '(:method-set (mcomplete-substr-method mcomplete-prefix-method)
			:exhibit-start-chars 1))
     (require 'cl-lookup)
     (defun cl-lookup (entry)
       "View the documentation on ENTRY from the Common Lisp HyperSpec, et al."
       (interactive (list (let ((default (cl-lookup-default-entry)))
			    (completing-read
			     (concat "Look up Common Lisp info"
				     (when default (format " (%s)" default))
				     ": ")
			     cl-lookup-obarray #'boundp t (thing-at-point 'symbol)
			     'cl-lookup-history default))))
       (let* ((symbol (intern-soft (downcase entry) cl-lookup-obarray))
	      (paths (if (and symbol (boundp symbol))
			 (symbol-value symbol)
		       (error "cl-lookup internal error: the path of %s is not defined"
			      name))))
	 (loop for (path . rest) on paths
	       do (cl-lookup-browse path)
	       if rest do (sleep-for 1.5))))
     ;; Override SLIME hyperspec lookup key bindings
     (define-key slime-mode-map (kbd "C-c C-d h") 'cl-lookup)
     (define-key slime-repl-mode-map (kbd "C-c C-d h") 'cl-lookup)))

• I use w3m for browsing documentation in SLIME. I generally use Firefox for normal Internet browsing but prefer to use an Emacs-based browser when working with Lisp code in SLIME as it's easier to copy/paste things and I don't have to leave Emacs to view the docs. However, w3m is not really needed if you prefer to use a different browser.
• I use mcomplete.el for minibuffer completion and substring matching with cl-lookup. The reasons for this will become apparent in my comments below. Even though mcomplete is not really needed, it is really convenient to use as it provides partial-string searches, an iswitchb-like interface and is generally useful for many minibuffer-completion requirements (not just cl-lookup).
• In the "non-CLHS library documentation" part of the cl-lookup-categories definition, you'll see that I've specified the names of the 6 libraries that I generated documentation for using my create-lookup-file function. These 6 files can be placed anywhere in the load-path.
• I have overridden the definition of cl-lookup. The only change I made was so that the text at point is displayed in the minibuffer for completion purposes (this makes it easy to do either partial name entry and complete with mcomplete or to enter symbols that aren't prefixed with their package name). The existing cl-lookup function needs to either be patched locally or the new definition loaded (as is done here) after the base cl-lookup is loaded.
• I override the "C-c C-d h" SLIME bindings for hyperspec lookup so that they call cl-lookup instead.