The 9.4.0 newLISP manual

[Lutz]

Find the 9.4.0 manual and reference here:



http://www.newlisp.org/download/development/newlisp_manual.html">http://www.newlisp.org/download/develop ... anual.html">http://www.newlisp.org/download/development/newlisp_manual.html



... still changing, to make this the best quality manual ever released with newLISP. All corrections and suggestions are welcome.

[m35]

Pointed this out before. Maybe it was missed, or not really important.



The description for read-line doesn't explicitly mentioned that it will ever return nil (although the example suggests that it will).

[Lutz]

Thanks  Michael, updated here:



http://www.newlisp.org/download/development/newlisp_manual.html">http://www.newlisp.org/download/develop ... anual.html">http://www.newlisp.org/download/development/newlisp_manual.html

[Kazimir Majorinc]

Good to see new version is coming. User manual and reference is comprehensive and pretty easy to read. Unfortunately, I'm not capable to say anything about 90% of the document because I do not know Newlisp that good, however, I have few proposals.



* consider to add example (or explicit claim) that "eval" has access to the local variables.



(let ((x 3)(y 7))(eval '(+ x y))) ;=> 10



* consider extending introduction with few sentences explaining "what is Newlisp"  and "what is the purpose of this document."



* consider Unix instead of UNIX.



* consider to put "Functions in alphabetical order" as a 4th chapter of "Function reference".

[Lutz]

Thanks for the input Kazimir, revision 6:



http://www.newlisp.org/download/development/newlisp_manual.html">http://www.newlisp.org/download/develop ... anual.html">http://www.newlisp.org/download/development/newlisp_manual.html

[Kazimir Majorinc]

Good examples for eval, just I think quote is omitted in all three eval examples with (+ x y) so these examples are true, but trivial. And one less important typo: "expi" in sentence "eval evaluates the result of evaluating expi in the current variable environment."

[DrDave]

One of my previous jobs was as a technical writer dealing mainly with preparing user guides for software. I am a nOOb to newLISP, so can't address much on the technical merit of the text. However, I can offer some suggestions for style changes as well as some grammar and spelling corrections. In some matters of grammar, there is no consensus by the "experts" as to which form is correct. Therefore, you may find some of my suggestions more a matter of "preferred by school of thought XYZ"  than as correcting an error. (For example, "since" and "because" are often used as synonyms. I adhere to the shchool of thought that if a clause or phrase is dealing with cause-and-effect, "because" should be used rather than "since". "Since" should be used as a time reference. For example. "It has been raining non-stop since yesterday." It is not possible to replace "since" with "because" because there is no "cause-and-effect" here, but rather "since" is making a time reference.)



You'll find  below  my suggestions for the first two sections. I copied the original text first, and then placed the suggested text below the original.

========================================

Consider using numbered sub-headings. For example

  1. Introduction

     1.1 newLISP-GS

     1.2 Licensing

 (You'll see as you go through the suggested changes that it would be much easier to reference by simply stating "section 1.2 para x" than to have to write out the sub-heading.)



Consider using a style for top-level headings of mixed case. For example:

    instead of

      2. Deprecated functions and futures changes

    use

      2. Deprecated Functions and Future Changes

=====================================================

1. Introduction

para.5

In this way, contexts can serve as dynamically created objects packaging symbols and  methods.



In this way, contexts can serve as dynamically created objects that package symbols and methods.



para. 10 (Better to use "because" than "since" when a casue-and-effect is described.)

Since strings can contain null characters in newLISP, they can be used to process binary data.



Because strings can contain null characters in newLISP, they can be used to process binary data.



para. 14

On 64-bit Linux, SUN Solaris and True64Unix newLISP can be compiled as a 64-bit LP64...



On 64-bit Linux, SUN Solaris, and True64Unix, newLISP can be compiled as a 64-bit LP64...



1. Introduction

   newLISP-GS

para. 1

newLISP-GS is a graphical user interface front-end written in newLISP and a Java based library  server using the standard Java runtime environment installed on all Windows and Mac OS X platforms.



newLISP-GS comprises a graphical user interface (GUI) and library server. The GUI front-end is written in newLISP, whereas the library server is Java based and implements the standard Java  runtime environment installed on all Windows and Mac OS X platforms.



para.2

This makes newLISP-GS is a platform-independent solution for writing GUI applications.



This makes newLISP-GS a platform-independent solution for writing GUI applications.



1. Introduction

   Licensing

para. 1

Both the newLISP and other documentation packaged with newLISP are licensed under the GNU Free  Documentation License.



The newLISP documentaiton as well as other documentation packaged with newLISP are licensed under  the GNU Free Documentation License.



2. Deprecated functions and future changes

sub-heading 1 (don't use periods)

Flat and parenthesized syntax rules for index and keyed lsit access.



Flat and parenthesized syntax rules for index and keyed lsit access



para. 1

With release 9.3.0 the number of functions in the nth, assoc and ref families of functions has grown substantially through introduction of setter and multiple key access function for association lists. Some of these functions support both, the flat and the parenthesized syntax, other functions only support the newer parenthesized forms.



With release 9.3.0, the number of functions in the nth, assoc and ref families of functions has grown substantially through introduction of setter and multiple key access function for association lists. Some of these functions support both the flat and the parenthesized syntax; other functions only support the newer parenthesized forms.



para. 2

No rules existed to remember which of both syntax forms where supported in a given function. The parenthesized syntax groups the list or string together with the indices or keys for better readability and faster parseing by the interpreter routines. This is similar to the usage of parenthesis in the for, doargs, dolist, dotimes and dotree functions. Flat forms are faster to type, because they don't require additional parentheses and can be used with curry.



Previously, no rules existed to remember which of the two syntax forms, parenthesized or flat, were supported in a given function. The parenthesized syntax groups the list or string together with the indices or keys for better readability and faster parseing by the interpreter routines. This is similar to the usage of parentheses in the for, doargs, dolist, dotimes and dotree functions. Flat forms are faster to type because they don't require additional parentheses and can be used with curry.



para. 4

Where flat syntax forms exists in setter functions, i.e. nth-set and set-nth, they are not documented anymore and may be eliminated in the future.



Although flat syntax forms exist in some setter functions, e.g. nth-set and set-nth, they are not documented anymore and may be eliminated in the future.



2. Deprecated functions and future changes

    Other changes

para. 1

The set-assoc or pop-assoc functions should be used instead of the deprecated replace-assoc, to replace or remove an association in an association list. The old replace-assoc has been removed from the documentation, and will be removed in a a future version.



The set-assoc or pop-assoc functions should be used instead of the deprecated replace-assoc to replace or remove an association in an association list. The deprecated replace-assoc has been removed from the documentation and will be removed in a a future version.



para. 3

The command-line function has been eliminated, command-event should be used instead to modify behavior of the command-line.



The command-line function has been eliminated; command-event should be used instead to modify behavior of the command-line.

[cormullion]

Consider using a style for top-level headings of mixed case. For example:

instead of

2. Deprecated functions and futures changes

use

2. Deprecated Functions and Future Changes

If we're voting, I vote against making this change...:)  I see no advantage in adopting this style.



Lutz - I'd like to go through the document again, but it will probably be over the weekend. When's your deadline?



Oh - and here's a typo I noticed yesterday while playing with bayes-query:

But small data sets may be used when then the frequency of symbols just describe already-known proportions.

[Lutz]

Thanks DrDave, changes are here in revision 8:



http://newlisp.nfshost.com/download/development/newlisp_manual.html">http://newlisp.nfshost.com/download/dev ... anual.html">http://newlisp.nfshost.com/download/development/newlisp_manual.html

I'd like to go through the document again, but it will probably be over the weekend. When's your deadline?

Thankyou very much, that would be great, deadline is June 27th. If you want you can edit directly into the file using a text editor (e.g. BBEdit, Taco etc). I have TextWrangler, the free version of BBEdit installed. Don't use any word processor, because they screw up the HTML, which I have under tight control for reliable PDF conversion, usage in shell help functions, etc.. After you are done I use FileMerge.app (Apple developer utility) to see all your changes.



Since Michael and Melissa made the last complete pass through the manual, a few releases have gone by with changes and additions made by me, introducing new ways to misspell and mangle the English language :).



The good news is, that the manual has much improved eliminating inconsistencies in the HTML, so that it is easier to parse it programatically.



The chapter "15. The context default functor" is a regrouping and rewriting of older content in this new chapter.

[Kazimir Majorinc]

There is undocumented form of let in Newlisp. Like in  Common Lisp, but unlike in Scheme, let does not necessarily contain initialization parts.



(let ((x) (y "y"))

     (println x y))



=> nily



There is a small practical, but I'd say significant aesthetic advantage of that form - because declaration is essential, initialization is only handy, so I think it could be good to document it. You need only this:



syntax: (let ((sym1 [exp-init1]) [(sym2 [exp-init2]) ... ]) body)



And perhaps to insert something like "if some exp-init is omitted, default value of nil is used instead" because few lines later, you explain that let is optimized equivalent of



    ((lambda (sym1 [sym2 ... ]) exp-body ) exp-init1 [ exp-init2 ])



and here exp-init cannot be just omitted, it has to be replaced with nil.

[xytroxon]

The atan entry is broken... (also in v.9.3.14)

Missing: (syntax:(atan... etc...

Code Select Expand

atan
5,900,000 (atan num-radians)

The arctangent of num-radians is calculated and returned.
example:

    (atan 1)  → 0.7853981634
    (tan (atan 1)) → 1


-- xytroxon

[DrDave]

In section 3 of the manual, there is this example to test starting  a newLISP server in Unix and then making a Telnet connection. (local domain socket connetions.)

Code Select Expand

newlisp -p 4711 &

The & indicates to a Unix shell to run the process in the background.

I found at the very end of the section

This mode is not available on Win32.

I program in Win32. It would be a lot more useful to have this remark placed at the start of the section rather than at the end. It really does not make sense for us Win32 users to read an interesting and maybe useful bit of information only to be taken by surprise at the very end of it.

[Kirill]

Consider using a style for top-level headings of mixed case. For example:

instead of

2. Deprecated functions and futures changes

use

2. Deprecated Functions and Future Changes

If we're voting, I vote against making this change...:)  I see no advantage in adopting this style.

I second that.



K.

[Lutz]

Thanks to everyone for all the help, here revision 9:



http://www.newlisp.org/download/development/newlisp_manual.html">http://www.newlisp.org/download/develop ... anual.html">http://www.newlisp.org/download/development/newlisp_manual.html



For DrDave: on Windows just start the server in the foreground (can also use -d ):

Code Select Expand

newlisp -p 4711

then open a second command window window for the telnet application.



This also has been added to the documentation.

[xytroxon]

Found a few more...



3. Functions in groups



List processing, flow control, and integer arithmetic

Code Select Expand

<TD><A HREF="#dolist">dostring</A></TD>
Should be:

Code Select Expand

<TD><A HREF="#dostring">dostring</A></TD>

String and conversion functions

Code Select Expand

<TD><A HREF="#utf8len">utf8</A></TD>
Should be:

Code Select Expand

<TD><A HREF="#utf8len">utf8len</A></TD>

Importing libraries

Code Select Expand

<TD><A HREF="#get-long">get-int</A>&nbsp;&nbsp;</TD>
Should be:

Code Select Expand

<TD><A HREF="#get-long">get-long</A>&nbsp;&nbsp;</TD>