clisp-devel

Re: documentation strings

[Hoehle, Joerg-C. <Joe...@t-...>]

[taken from clisp-devel to clisp-lisp, where IMHO it'S a better fit]

Bruno Haible wrote:
>I think that doc strings with just 1 to 3 lines of text are an =
obsolete
>concept. It doesn't convey enough information. Better use URLs into =
the
>ANSI CL doc or into clisp's impnotes.html. So that SLIME can then mark
>them clickable.
You've been splitting your screen with one half for Netscape for too =
long :)
I don't need to look up the CLHS when all I need is a remainder of the =
syntax of do-symbols. Packages to point to http information have been =
around for long enough.
Even CLISP has a clhs file as part of its core.

I had a related idea:
a separate file would
(dolist
  (setf (documentation <cl-symbols>) xyz)
to point to a user-defined location, i.e. a local copy of the CLHS or =
impnotes or so.

The user could run this as part of his config.lisp,
or the function could even be run anytime the user sees fit (i.e. be =
part of the image, instead of being loaded once and then thrown away, =
like the timezone.lisp file).

Another variation on this could be for DOCUMENTATION to build the =
string at call-time??

Anyway, if such a mapping were included in the clisp image, I could =
make slime display that in apropos in addition to the documentation =
string (if available).
Well, slime or hyperspec.el probably have independent means for that, =
so CLHS support need not be built into clisp itself. It's EXT symbols =
that need documentation.

Actually, gclcvs annoys me by pulling CLHS information from its info =
file into the Lisp session. Even more so when it deviates from CLHS (or =
does not yet fully implement ANSI).


But that idea is most suitable to CLHS symbols. Symbols from EXT would =
need to know about where to find the best-fitted impnotes. Some people =
prefer the split version, others the full one. =
http://clisp.cons.org/impnotes/... would not work from behind a =
firewall, or offline.

Summary: I see a trivial possibility to add documentation URLs for CLHS =
symbols (CLISP already has all that' needed), but somehow harder for =
symbols from EXT (yet the same idea could apply, if one knows where to =
link to).

Regards,
	J=C3=B6rg H=C3=B6hle.

Re: documentation strings

[Sam S. <sd...@gn...>]

> * Hoehle, Joerg-Cyril <Wbr...@g-...> [2005-06-15 18:45:29 +0200]:
>
> to point to a user-defined location, i.e. a local copy of the CLHS or
> impnotes or so.

see *clhs-root-default*, set in config.lisp

> Another variation on this could be for DOCUMENTATION to build the
> string at call-time??

yes, we can have a meaningful
(documentation symbol 'clhs)
(documentation symbol 'impnotes)


-- 
Sam Steingold (http://www.podval.org/~sds) running w2k
<http://www.openvotingconsortium.org/> <http://pmw.org.il/>
<http://www.honestreporting.com> <http://ffii.org/> <http://www.iris.org.il>
History doesn't repeat itself, but historians do repeat each other.

Re: documentation strings

[Sam S. <sd...@gn...>]

> * Hoehle, Joerg-Cyril <Wbr...@g-...> [2005-06-15 18:45:29 +0200]:
>
> Summary: I see a trivial possibility to add documentation URLs for
> CLHS symbols (CLISP already has all that' needed), but somehow harder
> for symbols from EXT (yet the same idea could apply, if one knows
> where to link to).

I just added a file id-href.map to the impnotes chunked distribution,
see <http://www.podval.org/~sds/clisp/impnotes/id-href.map>.
now you can do this:

1. add an impnotes documentation to ext symbols, pointing to the id in
   the XML impnotes sources, e.g.,
   (documentation 'ext:expand-form 'impnotes) ==> "code-walk"

2. add a user variable *impnotes-root*, e.g.
   "http://clisp.cons.org/impnotes.html"
   "http://clisp.cons.org/impnotes/"
   "http://www.podval.org/~sds/clisp/impnotes.html"
   "http://www.podval.org/~sds/clisp/impnotes/"

3. add a system variable *impnotes-id-href-map*:

(defvar *impnotes-id-href-map*)
(defun impnotes-id-href-map ()
  (if (boundp '*impnotes-id-href-map*)
      *impnotes-id-href-map*
      (setq *impnotes-id-href-map*
        (when (char= #\/ (char *impnotes-root* (1- (length *impnotes-root*))))
          (let ((ht (make-hash-table :test 'equal)))
            (with-open-file (map (ext:string-concat *impnotes-root*
                                                    "id-href.map"))
              (loop for s = (read-line map) while s
                do (setf (gethash s ht) (read-line map))))
            ht)))))

4. modify DESCRIBE to also do

(let ((impnotes (documentation s 'impnotes))
      (map (when impnotes (impnotes-id-href-map))))
  (when impnotes
    (format t "CLISP implementation notes documentation is here:~%<~A"
            *impnotes-root*)
    (if map
        (format t "~A>%" (gethash impnotes map))
        (format t "#~A>~%" impnotes))))

-- 
Sam Steingold (http://www.podval.org/~sds) running w2k
<http://www.openvotingconsortium.org/> <http://www.jihadwatch.org/>
<http://pmw.org.il/> <http://www.memri.org/> <http://www.palestinefacts.org/>
Hard work has a future payoff.  Laziness pays off NOW.

Re: documentation strings

[Bruno H. <br...@cl...>]

Sam wrote:
> 4. modify DESCRIBE to also do

Great! Thank you, Sam.

If you want to have this in clisp, then - since we are now in pre-release
cool-down phase, where a patch of this kind is not appropriate - please
store the patch, with a ChangeLog entry, in clisp/queued/, wherefrom we
will apply it after the release.

Bruno

Re: documentation strings

[Sam S. <sd...@gn...>]

> * Bruno Haible <oe...@py...> [2005-06-16 21:42:33 +0200]:
>
> Sam wrote:
>> 4. modify DESCRIBE to also do
> Great! Thank you, Sam.
welcome.

> If you want to have this in clisp, then - since we are now in
> pre-release cool-down phase, where a patch of this kind is not
> appropriate - please store the patch, with a ChangeLog entry, in
> clisp/queued/, wherefrom we will apply it after the release.

I am not interested in this approach  (CVS is for version control, not
storing patches, so we should use a branch instead)

I will start working on the patch after the release (b'li neder) unless
someone else goes your way and puts a patch into clisp/queued/.

-- 
Sam Steingold (http://www.podval.org/~sds) running w2k
<http://www.dhimmi.com/> <http://www.palestinefacts.org/>
<http://pmw.org.il/> <http://www.mideasttruth.com/>
Let us remember that ours is a nation of lawyers and order.