RFC open on newLISP documentation

[kazemori]

-- deleted

[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

[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]

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]

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]

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]

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

[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]

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">http://www.easysw.com/software.html seems to be the best solution.



Lutz

[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]

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]

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

[eddier]

Under atan2 in the document



1/4 PI != 90 degrees



1/4 PI == 45 degrees



Eddie

[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]

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