Robert STRANDH | 2 Dec 17:14 2002
Picon
Picon

Suggested improvement of documentation : Introduction

Section "Introduction"

The section should not be called `Introduction' but `Features'.  In an
introduction, one expects more substance, such as concepts.

The section lists versions of Emacs under which ILISP runs.  Is that a
complete list? (Emacs 21 is not mentioned for instance). 

"Packages are properly handled..."  Phrases like this are essentially
void of meaning.  How about something like this (assuming that is what
you mean by the phrase)

  When the user sends an expression from a Lisp source buffer for
  evaluation in an inferior Lisp process, ILISP automatically switches
  to the package that is indicated at the beginning of the buffer.
  The expression is therefore read by the inferior Lisp process with
  the correct current package. 

[I don't know what is meant by "...including the distinction between
exported and internal symbols].

A similar remark is valid for the phrase "Handle Lisp errors".  I
really can't tell what that is supposed to mean.  

"... eval and compile of files ..."

I would say "... evaluation and compilation of files ...".  Also, I
can't figure out what "optional switching and automatic calling" is
supposed to mean.  I mean, what does it mean to call a file or a
region?  And what does it mean to switch a definition?  Perhaps
(Continue reading)

Robert STRANDH | 2 Dec 17:15 2002
Picon
Picon

Suggested improvement of documentation : Files of ILISP

I would put this section in an appendix. 

--

-- 
Robert Strandh

---------------------------------------------------------------------
Greenspun's Tenth Rule of Programming: any sufficiently complicated C
or Fortran program contains an ad hoc informally-specified bug-ridden
slow implementation of half of Common Lisp.
---------------------------------------------------------------------

-------------------------------------------------------
This sf.net email is sponsored by:ThinkGeek
Welcome to geek heaven.
http://thinkgeek.com/sf
Robert STRANDH | 2 Dec 17:18 2002
Picon
Picon

Suggested improvement of documentation : Configuration...

The installer is asked to make sure LN and HyperSpec have appropriate
values in Makefile.  But he is not told what some appropriate values
would be.  This is especially upsetting since there is no variable
called HyperSpec in the Makefile.  

--

-- 
Robert Strandh

---------------------------------------------------------------------
Greenspun's Tenth Rule of Programming: any sufficiently complicated C
or Fortran program contains an ad hoc informally-specified bug-ridden
slow implementation of half of Common Lisp.
---------------------------------------------------------------------

-------------------------------------------------------
This sf.net email is sponsored by:ThinkGeek
Welcome to geek heaven.
http://thinkgeek.com/sf
Robert STRANDH | 2 Dec 17:23 2002
Picon
Picon

Suggested improvement of documentation : How to run...

"If called with a prefix you will be prompted"

However, it is not the reader that will be called with a prefix, but
one of the two functions mentioned.  I suggest:

  If one of these two functions is called with a numerical prefix, the
  user will be prompted for a buffer name and a program to run

"The default buffer name is the name of the dialect"

No, it isn't.  It is the name of the dialect with starts around it.
And if you answer `*cmulisp*'  to the prompt, you get a buffer called
`**cmulisp**'. 

The list of dialects claim that there is a dialect called `cmucl'.
But in the code it is called `cmulisp'.  In the hierarchical list on
the following page, it is referred to as `cmulisp'. 

--

-- 
Robert Strandh

---------------------------------------------------------------------
Greenspun's Tenth Rule of Programming: any sufficiently complicated C
or Fortran program contains an ad hoc informally-specified bug-ridden
slow implementation of half of Common Lisp.
---------------------------------------------------------------------

-------------------------------------------------------
This sf.net email is sponsored by:ThinkGeek
Welcome to geek heaven.
(Continue reading)

Robert STRANDH | 2 Dec 17:30 2002
Picon
Picon

Suggested improvement of documentation : Buffers used...

The list of buffers doesn't mention *Arglist-Output*.  

This section mentions the existence of the "Lisp listener buffer" and
of several "lisp-mode-buffers". 

However, later (in 4.1) a buffer called the "inferior Lisp buffer" is
mentioned.  It would be useful to use a single name consistently. 
Also later (in 4.2) the "current ILISP buffer" is mentioned.  But it
is not clear what an "ILISP buffer" is.  

--

-- 
Robert Strandh

---------------------------------------------------------------------
Greenspun's Tenth Rule of Programming: any sufficiently complicated C
or Fortran program contains an ad hoc informally-specified bug-ridden
slow implementation of half of Common Lisp.
---------------------------------------------------------------------

-------------------------------------------------------
This SF.net email is sponsored by: Get the new Palm Tungsten T 
handheld. Power & Color in a compact size! 
http://ads.sourceforge.net/cgi-bin/redirect.pl?palm0002en
Robert STRANDH | 2 Dec 16:52 2002
Picon
Picon

Suggested improvement of documentation : How to get ...

Section "How to get the latest ILISP distribution"

"The precise conditions appears following this section."

1. "appears" -> appear

2. The conditions don't appear following that section. 

"See the file `HISTORY' for a list of known bugs and problems"

That file does not mainly contain a list of known bugs and problems.
The known bugs in that file are associated with releases.  Therefore
according to the HISTORY file, there are no known bugs in any release
later than 5.9.3.  

--

-- 
Robert Strandh

---------------------------------------------------------------------
Greenspun's Tenth Rule of Programming: any sufficiently complicated C
or Fortran program contains an ad hoc informally-specified bug-ridden
slow implementation of half of Common Lisp.
---------------------------------------------------------------------

-------------------------------------------------------
This SF.net email is sponsored by: Get the new Palm Tungsten T 
handheld. Power & Color in a compact size! 
http://ads.sourceforge.net/cgi-bin/redirect.pl?palm0002en
Paolo Amoroso | 3 Dec 13:23 2002
Picon

Re: Suggested improvement of documentation : Files of ILISP

On Mon, 2 Dec 2002 17:15:32 +0100, Robert STRANDH wrote:

> Subject: [Ilisp-help] Suggested improvement of documentation : Files of ILISP
[...]
> I would put this section in an appendix. 

What about removing that section completely? It duplicates information
available at the top of each source file. If a user needs that info, he is
likely to be familiar with reading and accessing source code anyway.

Paolo
--

-- 
EncyCMUCLopedia * Extensive collection of CMU Common Lisp documentation
http://www.paoloamoroso.it/ency/README

-------------------------------------------------------
This SF.net email is sponsored by: Get the new Palm Tungsten T 
handheld. Power & Color in a compact size! 
http://ads.sourceforge.net/cgi-bin/redirect.pl?palm0002en
Paolo Amoroso | 3 Dec 13:23 2002
Picon

Re: Suggested improvement of documentation : How to get ...

Thanks for this and your other suggestions. I will apply them to the
manual.

Paolo
--

-- 
EncyCMUCLopedia * Extensive collection of CMU Common Lisp documentation
http://www.paoloamoroso.it/ency/README

-------------------------------------------------------
This SF.net email is sponsored by: Get the new Palm Tungsten T 
handheld. Power & Color in a compact size! 
http://ads.sourceforge.net/cgi-bin/redirect.pl?palm0002en
Robert STRANDH | 3 Dec 20:26 2002
Picon
Picon

Re: Suggested improvement of documentation : Files of ILISP

Paolo Amoroso writes:
 > On Mon, 2 Dec 2002 17:15:32 +0100, Robert STRANDH wrote:
 > 
 > > Subject: [Ilisp-help] Suggested improvement of documentation : Files of ILISP
 > [...]
 > > I would put this section in an appendix. 
 > 
 > What about removing that section completely? It duplicates information
 > available at the top of each source file. If a user needs that info, he is
 > likely to be familiar with reading and accessing source code anyway.

That would be fine.  It also is not very helpful to explain the
contents, like in "`ilisp-imenu.el' Ilisp specific code for imenu".

--

-- 
Robert Strandh

---------------------------------------------------------------------
Greenspun's Tenth Rule of Programming: any sufficiently complicated C
or Fortran program contains an ad hoc informally-specified bug-ridden
slow implementation of half of Common Lisp.
---------------------------------------------------------------------

-------------------------------------------------------
This SF.net email is sponsored by: Microsoft Visual Studio.NET 
comprehensive development tool, built to increase your 
productivity. Try a free online hosted session at:
http://ads.sourceforge.net/cgi-bin/redirect.pl?micr0003en
Paolo Amoroso | 4 Dec 17:02 2002
Picon

Re: Suggested improvement of documentation : Files of ILISP

On Tue, 03 Dec 2002 13:23:49 +0100, Paolo Amoroso wrote:

> On Mon, 2 Dec 2002 17:15:32 +0100, Robert STRANDH wrote:
> 
> > Subject: [Ilisp-help] Suggested improvement of documentation : Files of ILISP
> [...]
> > I would put this section in an appendix. 
> 
> What about removing that section completely? It duplicates information

If there are no objections, I will remove section "Files of ILISP" from the
manual.

Paolo
--

-- 
EncyCMUCLopedia * Extensive collection of CMU Common Lisp documentation
http://www.paoloamoroso.it/ency/README

-------------------------------------------------------
This SF.net email is sponsored by: Microsoft Visual Studio.NET 
comprehensive development tool, built to increase your 
productivity. Try a free online hosted session at:
http://ads.sourceforge.net/cgi-bin/redirect.pl?micr0003en

Gmane