RFC open on newLISP documentation

[cormullion]

Michael - great job already! Sorry to give you some more manual labour. A bit like the Zen monk sweeping the gravel... ;-)

[m i c h a e l]

Michael - great job already! Sorry to give you some more manual labour. A bit like the Zen monk sweeping the gravel... ;-)

Thanks for all of your manual digging, cormullion. Unfortunately, you may have dug some post holes where the swimming pool is going, since I haven't gotten to those parts yet ;-)

For the 8.9.0 release, Melissa and I edited up to the reference section. I'm just now getting to "Functions in alphabetical order." Maybe as part of the release notes, we can indicate where the editing has left off.

I'll start making the changes cormullion mentioned and keep chipping away at the reference section.

m i c h a e l

cormullion: Is this payback for the "Introduction" side-by-side? ;-)

[cormullion]

No! :-) But I have to do something constructive after all the silly mottoes...






(newLISP (not (just (a (parenthetical (language))))))

[m i c h a e l]

silly mottoes

:-(

(newLISP (not (just (a (parenthetical (language))))))

:-)

m i c h a e l

[cormullion]

The manual gives this example for 'name':

Code: Select all

(set 'ACTX:var 123)
(set 'sym 'ACTX:var)
(string sym)         => "ACTX:var"
(name sym)           => "var"
(name sym true)      => "ACTX"

It doesn't work for me.






newLISP: "Is this really a whole language in 212KB?"*

( * comment from an email I received recently ...)

[Lutz]

The example was written before the introductin of sym as a shorter form of symbol. This is how it works using sm as variable name instead od the protected sym:

Code: Select all

(set 'ACTX:var 123) 
(set 'sm 'ACTX:var) 
(string sm)         => "ACTX:var" 
(name sm)           => "var" 
(name sm true)      => "ACTX"

Lutz

[m i c h a e l]

I changed the manual to match what Lutz has written here. Also, I think the use of 'sym in net-receive's example -- the call to net-receive-line's second argument -- should be changed, as well. Is this correct? Otherwise, the rest of the manual checks out.

m i c h a e l

[Lutz]

Yes Michael, that is corrrect, thanks

Lutz

[newdep]

Adding a missing intruction for the manual ;-)

Old ->
To exit the newLISP shell on Linux/UNIX, press Ctrl-D; on Win32, type (exit) or Ctrl-C, then the x key.

New ->
To exit the newLISP shell on Linux/UNIX, press Ctrl-D; on Win32, press Ctrl-Z and then Enter or type (exit) or Ctrl-C, then the x key.


Ctrl-Z + enter work to quit the EOF on OS/2 and Windows ;-)

[m i c h a e l]

Hi Norman,

Thanks for the change. It now reads:

To exit the newLISP shell on Linux/UNIX, press Ctrl-D. On Win32, press Ctrl-Z or type (exit), then Enter; or press Ctrl-C, then the x key.

m i c h a e l

[newdep]

Perhpas the manual should also have a summerised overview on
what a certain OS has or not has on functionality compaired to another
OS.

Like ->

(fork) This mode is not available on Win32.
(reset true) This mode is not available on Win32.
(semaphore int-id) This form is not available on Win32.
...
...
...



Norman.

[Lutz]

We will put a small chapter in the first part of the manual. Perhaps a table showing the differences.

Lutz

[nigelbrown]

The Manual 8.9.3 section on format doesn't display some text properly in IExplorer 6.0 (WinXP). It gives tiny text. It seems to be choking on the 'plus1'
Firefox 1.5 handles it OK

problem area is
a href="#string">string</a>
can be used to insure correct data types and avoid error messages.</p>

<p>The format string has the following general format:</p>

<blockquote>

<pre><span class='plus1'>"%w.pf"</span></pre>
</blockquote>

<p>The percent <tt>%</tt> sign starts a format specification. To display a
percent sign <tt>%</tt> inside a format string double it: <tt>%%</tt></p>

<blockquote>
<pre><span class="plus1">w</span></pre>
</blockquote>

<p>Width of field. Data is right aligned, else whe...

I don't know anything about span class to suggest a fix. Trying "plus1" and plus1 (no quotes) doesn't help.

Nigel

[m i c h a e l]

Hi Nigel,

Thanks for pointing this out. I'm only just now learning the ins and outs of html and css, so this suggestion may not work (also, I don't have IE). I noticed in the style section at the top, the style span.plus1 has double quotes around the +1. I removed the quotes to see if effected the browser I'm using, and it seems fine. If this does not work, maybe another way of saying +1 is possible that would make IE happy.

m i c h a e l

[Lutz]

I am puzzled that both Nigel and Michael report the opposite of what I am seeing, for me on the Mac OS X PowerBook its fine with the quotes on the latest FireFox and Safari browsers. Perhaps we should switch back to put the font spec explicitely. The CSS span.plus1 definition is only used once in the manual anyway. All other span tags seem to work fine (most of them for colors).

Lutz

[m i c h a e l]

Agreed :-)

m i c h a e l

[newdep]

·
Hi Lutz,·
·
·
Here some remark on the manual, I just pointed them out to make perhpas the difference ·
a lillte bit more clear, not that I have heard anyone complaining so far ;-) But some points·
below might be confusing and can only be discovered when digging into the C code. ·
·
·
·
*** here is what they actualy do, but what is not realy read from the manual ***·
·
(! "argument")·
The '! command determines whether or not a command-processor ("command.com","cmd.exe","sh") is present ·
and executes the argument directly on the command-processor.·
·
(exec "argument" [stdout] )·
The 'exec command pipes the command towards the command-processor and returns the stdout of the executed argument.·
·
·
(process "argument" [in] [out] )·
The 'process command executes an argument and returns directly towards newlisp without waiting, ·
the IO of the executed argument goes through the current defined stdin and stdout or if defined differently through those.·
·
***·
·
·
** Also a small remark on ->·
·
The current description of 'Exec uses the word "process" this could be confusing and intepreted as a C-Process behaviour.·
·
The current 'process function is compaired with '!, thought it is not the same.·
·
·

[newdep]

And perhpas the whole process header should be re-thought?

syntax: (process str-command)
syntax: (process str-command int-pipe-in int-pipe-out [int-win32-option])
syntax: (process str-command int-pipe-in int-pipe-out [int-pipe-error])


You are talking about pipes, but that not true (based on the manual inteprettion that is ;-) it should be device! like this ->


syntax: (process str-command)
syntax: (process str-command device-in device-out [int-win32-option])
syntax: (process str-command device-in device-out [device-error])


Because interaction trough opened files is also possible i.e. with (device .....)

like ->

>(device (open "myfile" "write"))
3
>(process "cmd" 0 3)



Norman.

[Lutz]

Actually both 'exec' and 'process' start processes doing a fork() internally. 'exec' uses popen(), which internally uses fork() and 'process' uses fork() explicitly and doing a dup() for the optional pipes specified and stdin and stdout. The difference is that 'exec' also invokes a shell process to handle the comman specified in the 'exec' parameter.

On UNIX you may use file handles instead of pipe handles and sockets will probably work too, but on Win32 I have my doubts, that file handles will work for the pipe parameters in 'process', but I have not tried it. If this really works on Win32, I can include this in the manual.

Lutz

[newdep]

Hi Lutz,

On the semaphore part..

I think the function explenation of "semaphore" could be a little
shorter... Its now quiet a long text to read where its not realy needed.

... explenation on what a semaphore is
... actions and result
... example

And something like this inside the function-text ->

;; init semaphores
(semaphore)

;; assign a semaphore to sid
(set 'sid (semaphore))

;; put sid semaphore in wait state (always -1)
(semaphore sid -1)

;; run sid semaphore previously put in wait (always 1)
(semaphore sid 1)

;; run sid semaphore with X times a skip (backward or forward) on the function
(semaphore sid X)

;; release sid semaphore system wide (always 0)
(semaphore sid 0)



Norman.

[Lutz]

I agree, those examples explain it a lot better than the words. I will put in your examples, but leave it up to Michael to shorten the English explaining the different synyaxes when he comes to letter S.

Lutz

[newdep]

Yes he's doing a nice job ;-) quite some work though!


Here is another semphore example... perhpas usefull ->


;;
;; File : sem.lsp
;; Comment : fork with semaphore
;;

;; semaphore actions
(constant 'wait -1 'run 1 'release 0)

(define (shout counter channel)
(while (<= counter 20)
(begin
(write-line (string counter) channel)
(sleep 100)
(semaphore sid wait)
(inc 'counter))))

(define (listen channel)
(setq y "")
(while (!= y "20")
(begin
(println "* " (setq y (read-line channel)))
(sleep 100)
(semaphore sid run))))

;; create io communication pipes
(map set '(in out) (pipe))

;; create a semaphore 'sid
(setq sid (semaphore))

;; init the semaphore to inactive
(semaphore sid)

;; fork the functions
(fork (shout 0 out))
(fork (listen in))

;; release the sid system wide!
(semaphore sid 0)

(exit)



The output is this ->

# newlisp sem.lsp
* 0
* 1
* 2
* 3
* 4
* 5
* 6
* 7
* 8
* 9
* 10
* 11
* 12
* 13
* 14
* 15
* 16
* 17
* 18
* 19
* 20

[HPW]

8.9.8 doc for 'int'

If str is invalid, integer returns nil as a default value if not otherwise specified.

should read:

If str is invalid, int returns nil as a default value if not otherwise specified.

since integer is deprecated.

[m i c h a e l]

Hans-Peter: Thank you for catching this. The manual has been updated with your change.

Norman: I've made a note to include your code changes and intend to add them when we get to the S's. Thanks for the great examples! (I learn best from examples :-)


m i c h a e l

[Lutz]

Rev 12 of the newLISP Users Manual and Reference is online:

http://newlisp.org/downloads/newlisp_manual.html

Its includes the changes from 'integer' -> 'int'

Thanks to Michael for edits in the 'N' letter

Lutz