RFC open on newLISP documentation

Notices and updates
Locked
kazemori
Posts: 21
Joined: Fri Aug 22, 2003 1:42 am
Location: Vancouver BC | Portland OR

RFC open on newLISP documentation

Post by kazemori »

-- deleted
Last edited by kazemori on Fri Apr 15, 2005 6:10 am, edited 1 time in total.

kazemori
Posts: 21
Joined: Fri Aug 22, 2003 1:42 am
Location: Vancouver BC | Portland OR

RFC open on newLISP documentation

Post by kazemori »

hello, everyone!

as some of you may know, i am helping out with the newLISP documentation. continuing from this weekend i will be correcting and updating the newLISP manual (and the newLISP-tk introduction) in preparation for the upcoming release (and ultimately, newLISP 8.0).

if you have any "typo's", "transpo's", and|or "pet-peeves" that you want Lutz and i to know about, please post them to this forum (Win32|Linux sub-forums). i will try to incorporate as much as possible (and with Lutz's approval, of course); however, producing a easy-to-read and consistent set of documentation is the priority for now.

i may be back with a poll on things like "built-in" vs. "builtin"... ;-)

thanks in advance for your kind cooperation!

kazemori
Last edited by kazemori on Fri Apr 15, 2005 6:11 am, edited 1 time in total.

Sammo
Posts: 180
Joined: Sat Dec 06, 2003 6:11 pm
Location: Loveland, Colorado USA

Post by Sammo »

A few things noticed in the HTML version of the newLISP manual v.7.3.15 downloaded and printed 12/6/2003 (180 pages):

page 3: paragraph 8: first sentence: should the phrase "are completely type polymorph" be "are completely type polymorphic" ..?

page 11: paragraph 1: "..., that than can be used" should be "..., that then can be used"

page 12: paragraph 3: need space character between last sentence and next to last sentence; that is, "... may contain a basic data type.cdr and car where ..." should be "... may contain a basic data type. cdr and car were ..." -- notice that I also changed the last word in this quote from "where" to "were".

page 16: second paragraph from bottom: last sentence: "To execute these function from ..." should be "To execute these functions from ..."

page 21: first paragraph in the "Switching the locale" section: second sentence: "newLISP start up trting to set ..." should read "newLISP starts up trying to set ..."

page 26: section "body": last sentence should end with "... then they get ..." instead of "... than they get ..."

page 35: section "<,>,=,<=,>=,!=>": third paragraph: "... more significant then elements ..." should be "... more significant than elements ..."

page 40: section "atan": just a request that (atan2 num-y num-x) would be a useful addition

page 41: section "begin": second sentence: "... more than one expressions in a row ..." should be "... more than one expression in a row ..."

page 43: section "catch": some weird line breaks going on between the words "... returns nil" and "and stores the error"; also need to separate the "example:" section from the body of the text

page 44: second paragraph from bottom: should not end in two periods; that is, "etc.." should be "etc."

page 46: section "collect": first sentence after the example should read (in part) "and do not have to appear in order" instead of "and no not have to appear in order"

page 53: very last line: should read "... dec will always return an integer ..." instead of "... dec will always return and integer ..."

page 63: top most example: should be '(error-text 5) => "Not an expression"'

page 82: section "intersect": second sentence should be "The two sets ... need not be unique ..." instead of "The two sets ... need not to be unique ..."

page 86: section "load": the "e.g.:" (meaning "for example") should be "i.e.:" (meaning "that is")

page 101: section "new": first sentence needs a space between "syn-new-context" and "is"

page 105: section "pack": first sentence should read "Pack one or more ..." instead of "Pack on or more ..."

page 107: section "parse": next to last paragraph in section: "... would have to bee used ..." should read "... would have to be used ..." (change "bee" to "be"); also the next sentence beginning "For further options numbers for ..." doesn't sound right to me.

page 107: section "pipe": first paragraph: last sentence "... compiles and not working on ..." should be "... compiles and is not working on ..."

page 116: section "quote": the result of the third example should be "(a b c)" instead of "(q b c)"

That as far as I got tonight.
-- Sam

P.S., Regarding "builtin" vs. "built-in" -- I vote for "built-in" because it is much more readable. In the "builtin" form, the last "i" gets visually absorbed by the neighboring "t".

Sammo
Posts: 180
Joined: Sat Dec 06, 2003 6:11 pm
Location: Loveland, Colorado USA

Post by Sammo »

A few more observations:

page 118: section "read-buffer": first paragraph: "... previous to reading get deleted." should be "... previous to reading gets deleted."

page 119: section "read-line": A question -- on UNIX-like systems, lines are delimited by linefeed (ASCII 10); in most Windows text file, lines are delimited by carriage-return/linefeed (ASCII 13+ASCII 10); does (read-line ...) swallow both the CR and LF characters on Windows systems? What about Windows files with lines delimited with only (ASCII 10) or (ASCII 13)?

page 119: section "ref": last line on page: "ref searchers for ..." should be "ref searches for ..."

page 129: section "select": last paragraph: "Selected elements can be repeated and no not ..." should be "Selected elements can be repeated and do not ..."

page 133: section "set-nth": following "This can be used in the replacement expression:" the code set 'lst '(1 2 3 4)) is missing the open left paren.

page 135: section "sort": In the first sentence, the second occurrence of the word "list" should be italicized.

page 137: section "swap": first sentence: "... is returned in there order ..." should be "... is returned in their order ..." -- but probably better as "... is returned in their original order."

page 139: section "sys-info": "The list has 6 integers ..." but I counted 7, and I'm unclear to what "depending on the host operating system" refers to unless it is the last of the 7 integers.

page 139: section "tan": "... is calculated on the result." should be "... is calculated as the result."

page 140: section "time": Does (time exp) really return the time spent on evaluation or simply the elapsed time from beginning to end of computation?

page 141: section "trace": second paragraph: "This can be changes to ..." should be "This can be changed to ..."

page 153: section "TCP/IP Socket error codes": the explanation of error 13 would read better as "Badly formed IP number"

Sammo
Posts: 180
Joined: Sat Dec 06, 2003 6:11 pm
Location: Loveland, Colorado USA

Post by Sammo »

newLISP Manual v.7.3.15 Additions Requested

page 38: section "and": would like example showing (and) with no arguments assuming that it is legal

page 105: section "or": would like example showing (or) with no arguments assuming that it is legal

Lutz
Posts: 5289
Joined: Thu Sep 26, 2002 4:45 pm
Location: Pasadena, California
Contact:

Post by Lutz »

Sam, thankyou very, very much for your corrections, all your notes will be worked in by the next development version.

About 'built-in' versus 'builtin', we just changed from one to the other a some versions ago. I am fine with either, is there seems to be no official rule on this?

About 'read-line': at this moment 'read-line' works the same on Win32 and Unix-like systems. The line will always break on a LF and swallow the LF. A line will break on CR only if followed by LF and then swallow both. A CR alone will only break and be swallowed if last character in the stream. (I will add this to the documentaion).

About 'atan2': this will be added to the next development version (allthough there is a feature freeze until 8.0, but this is simple and isolated enougth to add it now)

About 'time': the time is measured from calling the 'C' evaluateExpression(expr) function until it returned. Note, that once newLISP source is loaded (compiled to an internal binary format) there is no other overhead involved. So the time returned by (time (dotimes (x 1000000) expr)) does not include the translation of expr neither the overhead of 'time' but of course in this example the over head of 'dotimes'.

If you want the pure netto time of 'expr' without the 'dotimes' overhead you would do:

(- (time (dotimes (x 1000000) expr)) (time (dotimes (x 1000000))))

=> result in nano seconds per one evaluation of expr

Lutz

Ryon
Posts: 248
Joined: Thu Sep 26, 2002 12:57 am

Builtin vs. built-in

Post by Ryon »

According to both Webster and the OED, the word is 'built-in'.

nigelbrown
Posts: 429
Joined: Tue Nov 11, 2003 2:11 am
Location: Brisbane, Australia

Post by nigelbrown »

Correction:
in Input/output and file operations (7.3.16) the list has
device twice - the second should be exec.

Request:
Could the newlisp-tk manual be available as .pdf too.

Nigel

Lutz
Posts: 5289
Joined: Thu Sep 26, 2002 4:45 pm
Location: Pasadena, California
Contact:

Post by Lutz »

thanks to all for the manual corrections, the manuals are so important, not only from it's functional value but also as a 'visitors card' for the whole newLISP package. I always thougth, that most Open Source software lacks good documentation and always wanted to make docs a distinguishing feature in newLISP.

This is the first time I feel a bit better about it, thanks to you all! What is still pending is to check all the examples, cutting and pasting them into newLISP for execution, but that will take a longer time. I did it once several years ago, so most stuff should be Ok.

There are PDF versions of both the newlisp_manual.html and newlisp-tk.html in the development directory, ready for double sided printing.

The idea is to cut off 1 inch from the top and bottom and 3/4 inch from the sides. That gives you 7x9 manuals for binding at your local copy shop. You can use the files newlisp_manual.book and newlisp-tk.book in the distribution for customizing PDF conversion to your own gusto.

I am still looking for a HTML->PDF conversion program which gives me more control over page breaks, keeping syntax headers together etc. In the past I would import the manuals into MS Word for editing the print version, but its simply to much work, I need something automatic. At this moment HTMLDOC from http://www.easysw.com/software.html seems to be the best solution.

Lutz

eddier
Posts: 289
Joined: Mon Oct 07, 2002 2:48 pm
Location: Blue Mountain College, MS US

Post by eddier »

Good documentation makes things much nicer, especially the one or two line examples.

I do a bunch of documentation in LaTeX. I can convert latex files to both pdf (use the ae fonts or the text will be horrible) and html. Although no frills, I have no complaints.

Eddie

kazemori
Posts: 21
Joined: Fri Aug 22, 2003 1:42 am
Location: Vancouver BC | Portland OR

newLISP manual

Post by kazemori »

hello Lutz!

wow! you close your eyes for a few days and whammo! a host of corrections!

Lutz, if you have not already integrated the suggestions from Sammo and nigelbrown, i will take care of these. some of the suggestions are actually questions, which may require something more than an edit; for these items, please let me know what you are going to do...

as it is tuesday afternoon in vancouver, i will start with this batch of corrections tonight or wednesday (at the latest). i will use the 7.3.17 text, unless you already have something "fresh from the oven".

kazemori

Lutz
Posts: 5289
Joined: Thu Sep 26, 2002 4:45 pm
Location: Pasadena, California
Contact:

Post by Lutz »

All of Sam's and Nigel's changes are already in 7.3.17 and all their questions have already been answered in this thread ;-).

I will release a new development release probably tomorrow Wednesday. If possible this will be the 7.4 by the coming weekend.

Lutz
Last edited by Lutz on Thu Dec 11, 2003 3:39 pm, edited 1 time in total.

eddier
Posts: 289
Joined: Mon Oct 07, 2002 2:48 pm
Location: Blue Mountain College, MS US

Post by eddier »

Under atan2 in the document

1/4 PI != 90 degrees

1/4 PI == 45 degrees

Eddie

Lutz
Posts: 5289
Joined: Thu Sep 26, 2002 4:45 pm
Location: Pasadena, California
Contact:

Post by Lutz »

Thanks Eddie, will be corrected.

Also, before anybody asks why sequence of parameters is Y,X instead of X,Y: that seems to be a convention for that function.

Lutz

nigelbrown
Posts: 429
Joined: Tue Nov 11, 2003 2:11 am
Location: Brisbane, Australia

Post by nigelbrown »

In 7.3.17 Function Reference:
"bool
true, nil, or expressions evaluating to true or nil.
true, nil, (X <= 10)"
example should be (<= x 10)

Nigel

eddier
Posts: 289
Joined: Mon Oct 07, 2002 2:48 pm
Location: Blue Mountain College, MS US

Post by eddier »

The definition for atan2 in the manual doesn't make any sense. How could you possibly determine an angle from the X-axis to a point (y,x). There are infinitely many points to start from along the X-axis. I looked up atan2 and found the following definition.

The atan2() and atan2f() functions compute the principal value of the arc tangent of y/x, using the signs of both arguments to determine the quadrant of the return value. (http://www.mkssoftware.com/docs/man3/atan2.3.asp)
Also, before anybody asks why sequence of parameters is Y,X instead of X,Y: that seems to be a convention for that function.
The definition given at www.mkssoftware.comd/docs/man3/atan2.3.asp makes sense.
Because tangents are slopes and a slope is defined as the change in Y over the change in X, Y should go first. The difference in atan, and atan2 is simple. Atan takes a slope and converts it to a radian angle within -pi to pi (principle arc tangent). Atan2 takes the signs of y and x to determine the proper quadrant, takes the principle arc tangent of |y/x| and gives it the proper sign for the quadrant.

Eddie[/quote]

Lutz
Posts: 5289
Joined: Thu Sep 26, 2002 4:45 pm
Location: Pasadena, California
Contact:

Post by Lutz »

thanks corrections, Nigel and Eddie

Lutz

eddier
Posts: 289
Joined: Mon Oct 07, 2002 2:48 pm
Location: Blue Mountain College, MS US

changes

Post by eddier »

in the changes section on the Web

atan2 takes the arc tangent of Y/X not X/Y.

Eddier

Lutz
Posts: 5289
Joined: Thu Sep 26, 2002 4:45 pm
Location: Pasadena, California
Contact:

Post by Lutz »

thanks Eddie

Lutz

Sammo
Posts: 180
Joined: Sat Dec 06, 2003 6:11 pm
Location: Loveland, Colorado USA

Post by Sammo »

missing from newlist_keywords.txt (win32)

irr
set-nth

Lutz
Posts: 5289
Joined: Thu Sep 26, 2002 4:45 pm
Location: Pasadena, California
Contact:

Post by Lutz »

I didn't include the keywords file in the latest 7400rc release because I always forgot to update it and it was never current.

But here is a quick way to make it yourself:

(1) start newlisp in a shell, so there are only built-in symbols available without all the newlisp-tk stuff

(2) execute the following 3 statements from the commandline:

(device (open "keywords.txt" "w"))

(dolist (s (symbols)) (println s))

(close (device))

Now your keywords.txt file is ready in the curent directory.

The 'device' function sets the device used for the 'print' and 'println' function.

I am still looking for a nice LISP editor with keyword highlighting and avalable on Win32 and Unix platforms, you know anything? I used to work with 'J', written in Java and usable on all platforms, but I got frustrated with the long startup times.

Lutz

eddier
Posts: 289
Joined: Mon Oct 07, 2002 2:48 pm
Location: Blue Mountain College, MS US

Post by eddier »

I modified the scheme.el in emacs to use some of the newLisp keywords. Everytime I use one that isn't highlighted, I put it in scheme.el and compile it so that it will be highlighted the next time. The only bad thing is that I have to have the extension .scm at the end of the files. If someone were willing to learn elisp (not me) they could write a special mode for newLisp. If I remember correctly, Emacs works on Windows and Unix.

There is also the SciTe editor. Works on Windows and Unix and adding keywords is very simple -- just put them into the lisp properties file. I'm not too wild about the way it indents however.

Eddie

HPW
Posts: 1390
Joined: Thu Sep 26, 2002 9:15 am
Location: Germany
Contact:

Post by HPW »

I use my alltime-editor UltraEdit on WIN. No problem with syntax-highlighting and paranthesis checking. My only problem is that I had not decided to use a own extension for newlisp. Now I have a mix of alisp, common lisp and newlisp running with one highlight-definition. I have considered to use *.nlsp extension for newlisp.
Hans-Peter

eddier
Posts: 289
Joined: Mon Oct 07, 2002 2:48 pm
Location: Blue Mountain College, MS US

Post by eddier »

Under the section "Floating point math and special functions," atan is listed twice. The second one should be gammaln.

Eddie

Lutz
Posts: 5289
Joined: Thu Sep 26, 2002 4:45 pm
Location: Pasadena, California
Contact:

Post by Lutz »

Thanks - I think I will release on Wednesday

Lutz

Locked