hyperspec.el

hyperspec.el

[Sam Steingold]

does anyone mind adding hyperspec.el to emacs/lisp/emacs-lisp/
(or maybe emacs/lisp/progmodes/ ?  somewhere else?)

the package is intended for viewing the CLHS (Common Lisp HyperSpec)
using browse-url.  The original version was from Eric Naggum (1996?).

I intend to write one from scratch (so there will be no licensing
issues).  The file fill be quite small since I will not have the
symbol -> file-name table hard-wired there (as was the case in the
original file and is, AFAIK, in the derivatives) but will use the table
provided by the CLHS itself.

-- 
Sam Steingold (http://www.podval.org/~sds) running RedHat7.2 GNU/Linux
Keep Jerusalem united! <http://www.onejerusalem.org/Petition.asp>
Read, think and remember! <http://www.iris.org.il> <http://www.memri.org/>
Yeah, yeah, I love cats too... wonna trade recipes?

Re: hyperspec.el

[Richard Stallman]

Could you show me this file, please?

    the package is intended for viewing the CLHS (Common Lisp HyperSpec)
    using browse-url.

Could you show me a brief description (maybe 5 or 10 lines) of CLHS?
I don't recall having heard of it before.

Re: hyperspec.el

[Sam Steingold]

> * In message <200204011638.g31GcZM11145@aztec.santafe.edu>
> * On the subject of "Re: hyperspec.el"
> * Sent on Mon, 1 Apr 2002 09:38:35 -0700 (MST)
> * Honorable Richard Stallman <rms@gnu.org> writes:
>
> Could you show me this file, please?

appended

I also suggest binding C-h C-s to `common-lisp-hyperspec' in lisp-mode.

>     the package is intended for viewing the CLHS (Common Lisp HyperSpec)
>     using browse-url.
> 
> Could you show me a brief description (maybe 5 or 10 lines) of CLHS?
> I don't recall having heard of it before.

CLHS is an HTML version of the ANSI X3.226-1994:
"American National Standard for Information Technology --
 Programming Language -- Common Lisp"

It was created by Kent Pittman, the X3J13 committee secretary, and is
available from the Association of Lisp USERS (ALU, www.lisp.org).
 
-- 
Sam Steingold (http://www.podval.org/~sds) running RedHat7.2 GNU/Linux
Keep Jerusalem united! <http://www.onejerusalem.org/Petition.asp>
Read, think and remember! <http://www.iris.org.il> <http://www.memri.org/>
Cannot handle the fatal error due to a fatal error in the fatal error handler.


;;; clhs.el -- access the Common Lisp HyperSpec (CLHS)

;; Copyright (C) 2002   Free Software Foundation, Inc.

;; Author: Sam Steingold <sds@gnu.org>
;; Maintainer: FSF
;; Keywords: lisp

;; This file is a part of GNU Emacs.

;; GNU Emacs is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation; either version 2, or (at your option)
;; any later version.

;; GNU Emacs is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.

;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs; see the file COPYING.  If not, write to
;; the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
;; Boston, MA 02111-1307, USA.

;;; Commentary:

;; Kent Pitman and the Harlequin Group (later Xanalys) have made the
;; text of American National Standard for Information Technology --
;; Programming Language -- Common Lisp, ANSI X3.226-1994 available on
;; the WWW, in the form of the Common Lisp HyperSpec.  This package
;; makes it convenient to peruse this documentation from within Emacs.

;; This is inspired by the Erik Naggum's version of 1997.

;;; Code:

(eval-when-compile (require 'cl)) ; push
(require 'browse-url)
(require 'thingatpt)
(require 'url)

(defcustom common-lisp-hyperspec-root "http://www.lisp.org/HyperSpec/"
  "*The root of the Common Lisp HyperSpec URL.
If you copy the HyperSpec to your local system, set this variable to
something like \"file:/usr/local/doc/HyperSpec/\"."
  :group 'lisp
  :type 'string
  :version "21.3")

(defvar clhs-history nil
  "History of symbols looked up in the Common Lisp HyperSpec.")

(defvar clhs-symbols nil)

(defun clhs-table-buffer (&optional root)
  (unless root (setq root common-lisp-hyperspec-root))
  (if (string-match "^file:/" root)
      (with-temp-buffer
        (insert-file-contents-literally
         (let* ((d (concat (substring root 5) "/Data/"))
                (f (concat d "Map_Sym.txt")))
           (if (file-exists-p f) f
             (setq f (concat d "Symbol-Table.text"))
             (if (file-exists-p f) f
               (error "no symbol table at ~s" root))))
         nil nil nil t)
        (goto-char 0)
        (current-buffer))
    (let* ((d (concat root "/Data/"))
           (f (concat d "Map_Sym.txt")))
      (set-buffer (url-retrieve-synchronously f))
      (goto-char 0)
      (unless (looking-at "^HTTP/.*200 OK$")
        (kill-buffer (current-buffer))
        (setq f (concat d "Symbol-Table.text"))
        (set-buffer (url-retrieve-synchronously f))
        (goto-char 0)
        (unless (looking-at "^HTTP/.*200 OK$")
          (kill-buffer (current-buffer))
          (error "no symbol table at ~s" root)))
      ;; skip to the first symbol
      (search-forward "\n\n")
      (current-buffer))))

(defun clhs-read-symbols ()
  "read `clhs-symbols' from the current position in the current buffer"
  (while (not (eobp))
    (puthash (buffer-substring-no-properties ; symbol
              (line-beginning-position) (line-end-position))
             (progn (forward-line 1) ; file name
                    (buffer-substring-no-properties ; strip "../"
                     (+ 3 (line-beginning-position)) (line-end-position)))
             clhs-symbols)
    (forward-line 1)))

(defun clhs-symbols ()
  "Get `clhs-symbols' from `common-lisp-hyperspec-root'."
  (if (and clhs-symbols (not (= 0 (hash-table-count clhs-symbols))))
      clhs-symbols
    (with-current-buffer (clhs-table-buffer)
      (unless clhs-symbols
        (setq clhs-symbols (make-hash-table :test 'equal :size 1031)))
      (clhs-read-symbols)
      (kill-buffer (current-buffer))
      clhs-symbols)))

(defun hash-table-complete (string table how)
  (let ((res nil) (st (upcase string)) (len (length string)))
    (maphash (lambda (key val)
               (when (and (<= len (length key))
                          (string= st (substring key 0 len)))
                 (push key res)))
             table)
    (if how res                 ; `all-completions'
      (if (cdr res) (try-completion st (mapcar #'list res))
        (if (string= st (car res)) t (car res))))))

;;;###autoload
(defun common-lisp-hyperspec (symbol-name)
  "Browse the Common Lisp HyperSpec documentation for SYMBOL-NAME.
Finds the HyperSpec at `common-lisp-hyperspec-root'."
  (interactive (list (let ((sym (thing-at-point 'symbol)))
                       (completing-read
                        "Look-up symbol in the Common Lisp HyperSpec: "
                        #'hash-table-complete (clhs-symbols)
                        t sym 'clhs-history))))
  (browse-url (concat common-lisp-hyperspec-root
                      (gethash (upcase symbol-name) (clhs-symbols)))))

(provide 'clhs)

Re: hyperspec.el

[Richard Stallman]

What is the license on the hyperspec?  Also, could you tell me the
authors' names and email addresses in case I need to write to them?

Re: hyperspec.el

[Sam Steingold]

> * In message <200204030456.g334umD11902@aztec.santafe.edu>
> * On the subject of "Re: hyperspec.el"
> * Sent on Tue, 2 Apr 2002 21:56:48 -0700 (MST)
> * Honorable Richard Stallman <rms@gnu.org> writes:
>
> What is the license on the hyperspec?  Also, could you tell me the
> authors' names and email addresses in case I need to write to them?

what difference does the CLHS license make?!
clhs.el is not distributing it or anything extracted from it.
just like w3 can access lots of proprietary pages on the WWW,
clhs can access the hyperspec, whatever the license is.
see
<http://www.lisp.org/HyperSpec/FrontMatter/About-HyperSpec.html#Legal>
<http://www.xanalys.com/software_tools/reference/HyperSpec/Front/Help.htm#Legal>

-- 
Sam Steingold (http://www.podval.org/~sds) running RedHat7.2 GNU/Linux
Keep Jerusalem united! <http://www.onejerusalem.org/Petition.asp>
Read, think and remember! <http://www.iris.org.il> <http://www.memri.org/>
Only adults have difficulty with child-proof caps.

Re: hyperspec.el

[Richard Stallman]

    what difference does the CLHS license make?!

There is a GNU policy of not referring to documentation that isn't
free.  People can access non-free documentation with w3, or with wget;
they don't do any filtering.  But we shouldn't recommend a non-free
documentation work specifically.

Re: hyperspec.el

[Richard Stallman]

It turns out that the Hyperspec is not free.  I wrote to Kent Pitman
about changing that, and we will see if I get anywhere.

Re: hyperspec.el

[Sam Steingold]

> * In message <200204051906.g35J6aS19064@aztec.santafe.edu>
> * On the subject of "Re: hyperspec.el"
> * Sent on Fri, 5 Apr 2002 12:06:36 -0700 (MST)
> * Honorable Richard Stallman <rms@gnu.org> writes:
>
> It turns out that the Hyperspec is not free.  I wrote to Kent Pitman
> about changing that, and we will see if I get anywhere.

that was a week ago -- did he reply?

-- 
Sam Steingold (http://www.podval.org/~sds) running RedHat7.2 GNU/Linux
Read, think and remember! <http://www.iris.org.il> <http://www.memri.org/>
<http://www.palestine-central.com/> <http://www.mideasttruth.com/>
Who is General Failure and why is he reading my hard disk?

Re: hyperspec.el

[Richard Stallman]

No reply from Pitman alas.

Re: hyperspec.el

[Sam Steingold]

> * In message <200204131907.g3DJ74Z23004@aztec.santafe.edu>
> * On the subject of "Re: hyperspec.el"
> * Sent on Sat, 13 Apr 2002 13:07:04 -0600 (MDT)
> * Honorable Richard Stallman <rms@gnu.org> writes:
>
> No reply from Pitman alas.

Okay - let me fill in for him. :-)

He was the X3J13 secretary and worked on producing the CLHS as an
employee of Harlequin.  The (c) to the CLHS belongs now to Xanalys
(which bought Harlequin).  Pitman has been laid off from there for
quite some time, so I don't think he can help you.

I have no idea about how successful you might be in convincing Xanalys
to release CLHS under the GFDL (or whatever will make you agree to
distribute my clhs.el with Emacs), but it's them who you should
contact, not Pitman.

<http://www.xanalys.com/contact.html>
Xanalys Incorporated
95 Sawyer Road
Three University Park
Waltham, MA 02453
Tel: +1 877 XANALYS
     (1 877 926 2597)
Fax: +1 781 736 1949

Will you go after them?

-- 
Sam Steingold (http://www.podval.org/~sds) running RedHat7.2 GNU/Linux
Read, think and remember! <http://www.iris.org.il> <http://www.memri.org/>
<http://www.palestine-central.com/> <http://www.mideasttruth.com/>
I don't want to be young again, I just don't want to get any older.