Subject: [clisp-list] help w/ writing documentation?

From: Joe Corneli <[email-masked]>
Date: Sun Feb 8 19:24:10 2004

Hello, 

I'd like to renew my offer to help write clisp documentation -- and
ask for some pointers about how to help.

Joe

---

From: Sam Steingold <[email-masked]>
Date: Sun Feb 8 20:05:02 2004

> * Joe Corneli <[email-masked]> [2004-02-08 21:23:26 -0600]:
>

all CLISP documentation is contained in the "implementation notes" and
"man pages" in doc/clisp.xml.in and doc/imp*.xml*.
did you look at those texts?
what is inadequate?
what are your suggestions?

-- 
Sam Steingold (http://www.podval.org/~sds) running w2k
<http://www.camera.org> <http://www.iris.org.il> <http://www.memri.org/>
<http://www.mideasttruth.com/> <http://www.honestreporting.com>
Every day above ground is a good day.

---

From: Joe Corneli <[email-masked]>
Date: Sun Feb 8 21:25:01 2004

No, didn't know they were there. (Will look for this stuff, though I
installed clisp using Fink and I'm not sure where it will habe ...)

  what is inadequate?

See above... also, more online help (such as that featured in
maxima) would be swell.

One might start by making the following command more informative,
and proceed from there:

> :h

Help (abbreviated :h) = this list
Use the usual editing capabilities.
(quit) or (exit) leaves CLISP.

As a rather trivial suggestion, I think it would be nice if the help
system could be opened using (help) as well as help.

At any rate, I think it would be nice to mention

(describe (quote FUNCTION))

among the top-level help.  Continuing with this theme, it might be
nice if e.g.

(describe (quote car))

told you _something_ about how to _use_ the function car.  Even
something as oblique as

   (car LIST)
   
   Return the car of LIST.  If arg is nil, return nil.
   Error if arg is not nil and not a cons cell.
                               -- Emacs C-h f car RET

would be useful.  Indeed, a lot of useful online documentation could
be copied from the emacs cl packages.

---

From: Pascal J.Bourguignon <[email-masked]>
Date: Sun Feb 8 22:47:01 2004

> See above... also, more online help (such as that featured in

Indeed. 

        (documentation (select-a-symbol-from-common-lisp) t)

always return  NIL. It would be  nice if it  returned something useful
(like an extract of CLHS).

Note that for user defined symbols:

[18]> (defvar f "toto" "a nice variable")
F
[19]> (documentation 'f t)
NIL
[20]> (documentation 'f 'function)
"doc of f"
[21]> (documentation 'f 'variable)
"a nice variable"
[22]> 

I  think that the  definition of  (documentation t  (eql t))  does not
prevent   an  implementation   to  return   a  concatenation   of  the
documentation  of all  facets  of that  symbol.  I'd expect  something
similar to:

(documentation 'f t) --> 
"f is a function:
doc of f

f is a variable:
a nice variable
"

> system could be opened using (help) as well as help.

(ext:help)

-- 
__Pascal_Bourguignon__                     http://www.informatimago.com/
There is no worse tyranny than to force a man to pay for what he doesn't
want merely because you think it would be good for him.--Robert Heinlein
http://www.theadvocates.org/

---

From: Joe Corneli <[email-masked]>
Date: Sun Feb 8 22:55:36 2004

> (ext:help)

*** - READ from #<INPUT CONCATENATED-STREAM #<INPUT
STRING-INPUT-STREAM> #<IO SYNONYM-STREAM *TERMINAL-IO*>>: #<PACKAGE
EXT> has no external symbol with name "HELP"

---

From: Pascal J.Bourguignon <[email-masked]>
Date: Sun Feb 8 23:24:14 2004

> EXT> has no external symbol with name "HELP"

[22]> (help)
** - Continuable Error
EVAL: undefined function HELP
If you continue (by typing 'continue'): Retry
The following restarts are also available:
STORE-VALUE    :R1      You may input a new value for (FDEFINITION 'HELP).
USE-VALUE      :R2      You may input a value to be used instead of (FDEFINITION 'HELP).

Break 1 [23]> 

My point is that (help)  could be taken as (common-lisp:help) and this
cannot be. If you want to implement a help function, that should be in
an implementation dependent package such as ext.

[Note  that   my  ~/.common.lisp  which   is  loaded  by   my  various
~/.clisprc.lisp, ~/.cmuclrc, ~/.sbclrc, etc does first thing:

;; clean the imported packages:
(MAPC (LAMBDA (USED) (UNUSE-PACKAGE USED "COMMON-LISP-USER"))
      (REMOVE (FIND-PACKAGE "COMMON-LISP") 
              (COPY-SEQ (PACKAGE-USE-LIST "COMMON-LISP-USER"))))

]

---

From: Sam Steingold <[email-masked]>
Date: Mon Feb 9 06:50:05 2004

> * Joe Corneli <[email-masked]> [2004-02-08 23:24:09 -0600]:
>

http://clisp.cons.org/impnotes/
http://clisp.cons.org/clisp.html

> (quit) or (exit) leaves CLISP.

I did not realize that when you said "on-line help" you meant "help from
the running CLISP process", not "documentation on the web".  Sorry.

Indeed, it would be nice to have a better help available.

> among the top-level help.

yes.

> Continuing with this theme, it might be nice if e.g.
>
> (describe (quote car))
>

the official documentation for CAR is
<http://www.lisp.org/HyperSpec/Body/acc_carcm_cdr_darcm_cddddr.html>.
I think (describe 'car) should print the above URL.

The non-ANSI features should be documented in the impnotes and DESCRIBE
should print the reference to the appropriate place in the impnotes.

-- 
Sam Steingold (http://www.podval.org/~sds) running w2k
<http://www.camera.org> <http://www.iris.org.il> <http://www.memri.org/>
<http://www.mideasttruth.com/> <http://www.honestreporting.com>
Lisp suffers from being twenty or thirty years ahead of time.

---

From: Rick Taube <[email-masked]>
Date: Mon Feb 9 07:32:13 2004

If I save a clisp image and then boot it thusly:
	clisp -M /path/to/my.img

is it possible to discover at runtime what the value for -M  was? I had 
hoped that ext:*args* would give me this, but its always nil when my 
init-function is called as you can see in this trace  printout:

[pinhead hkt] ~> /usr/local/bin/clisp -I -q -ansi -M 
/Lisp/cm/bin/../bin/clisp_2.31_darwin-powerpc/cm.img

(*ARGS* -> NIL)

  /\\\
---\\\---------
----\\\--------
----/\\\------- Common Music 2.4.2
---/--\\\------
--/----\\\-----
  /      \\\/

[1]> (lisp-implementation-version)
"2.31 (2003-09-01) (built on cmn13.stanford.edu [171.64.197.162])"

I would like to be able to find out the -M value at runtime because one 
of the "rules" id like for my init loading in a binary release would 
allow an initfile for my program to be placed in whatever directory the 
user put the application image. I can determine this value is all Lisps 
so far but clisp which I have not been able to figure out yet so far -- 
is there any way for my program get the compelte args passed to 
lisp.run ??

Rick Taube
Associate Professor, Composition/Theory
School of Music
University of Illinois
Urbana, IL 61821 USA
net: [email-masked]
fax: 217 244 8319
vox: 217 244 2684

---

From: "John K. Hinsdale" <[email-masked]>
Date: Mon Feb 9 08:10:04 2004

# If I save a clisp image and then boot it thusly:
# 	clisp -M /path/to/my.img
# 
# is it possible to discover at runtime what the value for -M  was?

[This is somewhat tacky and does not truly answer your exact question
but it will work:]

Assuming you are on a Unix, you can pass in the info via the shell
envirnoment: call CLISP instead w/ this shell script

#----------  Cut here ------
#!/bin/sh
# Save this as clisp_wrapper
CLISP_ARGS="-q -E en -K full"
export CLISP_ARGS
clisp $CLISP_ARGS
#----------  Cut here ------

You can put the "-M <file>" in place of CLISP_ARGS.

Now when I the wrapper is run the args are accessible via GETENV

hin@van-halen /van-halen/u/hin>./clisp_wrapper 

[1]> (getenv "CLISP_ARGS")
"-q -E en -K full "
[2]> 

In your case you would see "-M /path/to/my.img" as the result
of eval'ing
	(getenv "CLISP_ARGS") 

If you needed just the the file name you'd have to parse it out, and
also make sure to ignore other args if -M was not the only one used.

See I told you it was tacky. :)

---
John Hinsdale, Alma Mater Software, Inc., Tarrytown, NY 10591-3710 USA
[email-masked] | http://www.alma.com/staff/hin | +1 914 631 4690

---

From: Russell McManus <[email-masked]>
Date: Mon Feb 9 08:13:13 2004

> Indeed, it would be nice to have a better help available.

defun, defvar, and friends could be changed to stuff the docstring if
supplied on the symbol plist, and the describe function could look
there for it.

---

From: Joe Corneli <[email-masked]>
Date: Mon Feb 9 11:55:12 2004

> installed clisp using Fink and I'm not sure where it will habe ...)

I found them in /sw/share/doc/clisp/

   The non-ANSI features should be documented in the impnotes and
   DESCRIBE should print the reference to the appropriate place in
   the impnotes.

I think it would be nice if the data was actually printed to the
screen, not just the reference. It shouldn't be too hard w/ some
text processing to get the stuff to print - assuming it can be
freely distributed.

---

From: Pascal J.Bourguignon <[email-masked]>
Date: Mon Feb 9 12:29:06 2004

> text processing to get the stuff to print - assuming it can be

There's an easy way out if the data is free but not freely distributed:

Write a program that will download the data and pre-process it for the
user in the installation stage.  It's  not too hard to parse html (but
beware: Hyperspec html is invalid).

---

From: Sam Steingold <[email-masked]>
Date: Mon Feb 9 12:36:16 2004

> * Joe Corneli <[email-masked]> [2004-02-09 13:54:49 -0600]:
>
> screen, not just the reference. It shouldn't be too hard w/ some text
> processing to get the stuff to print - assuming it can be freely
> distributed.

GCL comes with some texi docs based on it.
could you please investigate the issue?
i.e., can we distribute something based on CLHS?
then we can use lynx or elinks to convert it to text.
maybe.

-- 
Sam Steingold (http://www.podval.org/~sds) running w2k
<http://www.camera.org> <http://www.iris.org.il> <http://www.memri.org/>
<http://www.mideasttruth.com/> <http://www.honestreporting.com>
If You Want Breakfast In Bed, Sleep In the Kitchen.

---

From: Marco Antoniotti <[email-masked]>
Date: Mon Feb 9 12:42:22 2004

The GCL texi support is very nice, at least it was last I checked.  
However, I think it is based on CLTL1 (I may be wrong).

Marco

On Monday, Feb 9, 2004, at 15:35 America/New_York, Sam Steingold wrote:

> -------------------------------------------------------
> The SF.Net email is sponsored by EclipseCon 2004
> Premiere Conference on Open Tools Development and Integration
> See the breadth of Eclipse activity. February 3-5 in Anaheim, CA.
> http://www.eclipsecon.org/osdn
> _______________________________________________
> clisp-list mailing list
> [email-masked]
> https://lists.sourceforge.net/lists/listinfo/clisp-list
>
--
Marco Antoniotti					http://bioinformatics.nyu.edu
NYU Courant Bioinformatics Group		tel. +1 - 212 - 998 3488
715 Broadway 10th FL				fax. +1 - 212 - 998 3484
New York, NY, 10003, U.S.A.

---

From: Sam Steingold <[email-masked]>
Date: Mon Feb 9 13:17:18 2004

> * Rick Taube <[email-masked]> [2004-02-09 09:31:18 -0600]:
>
> is it possible to discover at runtime what the value for -M was?

it has been asked before on many occasions, so I now decided to add
this functionality.

CVS HEAD now has function EXT:ARGV which returns a (fresh) vector of
argument strings.
Note that these are the arguments that the driver (clisp) passes to
runtime (lisp.run), so it contains "-M" pretty much always.

-- 
Sam Steingold (http://www.podval.org/~sds) running w2k
<http://www.camera.org> <http://www.iris.org.il> <http://www.memri.org/>
<http://www.mideasttruth.com/> <http://www.honestreporting.com>
If your VCR is still blinking 12:00, you don't want Linux.

---

From: Joe Corneli <[email-masked]>
Date: Mon Feb 9 13:17:27 2004

There's an easy way out if the data is free but not freely
   distributed:

I don't know, that idea sounds dangerously close to
Why-CLISP-is-under-GPL :)

---

From: Joe Corneli <[email-masked]>
Date: Mon Feb 9 21:11:06 2004

It seems to be pretty clear from 

http://www.lispworks.com/reference/HyperSpec/Front/Help.htm#Legal

that it is not permissible to distribute modified versions of the
CLHS.

---

From: Pascal J.Bourguignon <[email-masked]>
Date: Mon Feb 9 22:50:04 2004

> that it is not permissible to distribute modified versions of the

Indeed, but nothing prevents you  to distribute a program that fetches
an  UNMODIFIED  copy  of  CLHS,  and  modifies  it  in  place  at  the
customer's, without ever distributing that modified version.  

Besides, we're  talking about  a modification in  the form not  in the
substance.  For one thing, modifications  of the form are done all the
time (to display, to print, to speak out, etc), and for the other, the
current form  is invalid HTML.  (There are H1  tags embeded in  A tags
which has never been valid HTML).

---

From: Joe Corneli <[email-masked]>
Date: Mon Feb 9 23:35:03 2004

Indeed, but nothing prevents you to distribute a program that
   fetches an UNMODIFIED copy of CLHS, and modifies it in place at
   the customer's, without ever distributing that modified version.

I agree that that _should_ be OK from a legal perspective.  But I'm
not a lawyer!

I think a slightly less risky and potentially more useful approach
would be to see if we could get the actual specs on which the
HyperSpec is based released under the FDL (it doesn't hurt to ask)
and then go from there. Of course, it might be more work to do
things this way, and there's no guarantee that the specs would be
released.

---

From: Rick Taube <[email-masked]>
Date: Tue Feb 10 06:51:01 2004

Sam -- ext:arv works great, its a very handy addition. Thanks so much!

best,
Rick

[1]> (ext:argv)
#("/usr/local/lib/clisp/base/lisp.run" "-B" "/usr/local/lib/clisp" "-N"
   "" "-I" "-q" "-ansi" "-M"
   "/Lisp/cm/bin/../bin/clisp_2.32_darwin-powerpc/cm.img")
[2]>

---

From: Sam Steingold <[email-masked]>
Date: Tue Feb 10 10:50:01 2004

> * Rick Taube <[email-masked]> [2004-02-10 08:49:59 -0600]:
>
> Sam -- ext:argv works great, its a very handy addition. Thanks so much!
you are welcome.
note that this feature might change in the future (before the next release)

>    "/Lisp/cm/bin/../bin/clisp_2.32_darwin-powerpc/cm.img")

when you distribute CM with a driver script invoking CLISP with the CM
image, please do not make "-q" the default - there should be a user
option for that, of course, but removing the banner by default takes
away some credit from the CLISP developers.  Of course, you should add
a CM banner after the CLISP one (just like maxima does) - which should
also be disabled when clisp is called with "-q".

Thank you.

---

From: Rick Taube <[email-masked]>
Date: Tue Feb 10 12:00:01 2004

> also be disabled when clisp is called with "-q".

yes, sorry! ill fix that!