Documentation for release 10.1.0

[Lutz]

Here are the "Users Manual and Reference" and "Code Patterns" documents of Monday's 10.1 release. Any input to the new text (improving English, understanding, etc.) is welcome:



http://www.newlisp.org/downloads/development/newlisp_manual.html#send">http://www.newlisp.org/downloads/develo ... .html#send">http://www.newlisp.org/downloads/development/newlisp_manual.html#send



http://www.newlisp.org/downloads/development/newlisp_manual.html#receive">http://www.newlisp.org/downloads/develo ... ml#receive">http://www.newlisp.org/downloads/development/newlisp_manual.html#receive



In the Code Patterns document chapter 18. has been completely rewritten and expanded with  more examples:



http://www.newlisp.org/downloads/development/CodePatterns.html#multiprocessing">http://www.newlisp.org/downloads/develo ... processing">http://www.newlisp.org/downloads/development/CodePatterns.html#multiprocessing



Chapter 19. about the messaging API is new:



http://www.newlisp.org/downloads/development/CodePatterns.html#messaging">http://www.newlisp.org/downloads/develo ... #messaging">http://www.newlisp.org/downloads/development/CodePatterns.html#messaging



I still need to translate the users manual to PDF with proper page breaks etc. Changes will not make it into the release if they come after 18:00 UTC (3:00pm ET).

[cormullion]

I didn't read this until just now, running a bit short of time this weekend. Sorry! A quick glance through one section revealed some typos -

The sync when thw timeout value specified is too short for all prcesses to finish sync will return nil. This can be use to watch progess:

When sync is called without parameters, it retuens a list of still active process ids:

non-sentences

Since newLISP offers a simple API which does all the work of launching processes and synchronizing collection of evaluation results in a transparent manner.

others

They can be made blocking using a loops:

Lutz: we still don't have a good way of doing this distributed proof-reading. I think more people would contribute if the mechanics were easier. Something like WikiBooks might be something to consider one day...

[Lutz]

Thanks a lot Cormullion, I just don't see this stuff until somebody puts it isolated in front of me.



An updated version is online:



http://www.newlisp.org/downloads/development/CodePatterns.html">http://www.newlisp.org/downloads/develo ... terns.html">http://www.newlisp.org/downloads/development/CodePatterns.html

[m i c h a e l]

we still don't have a good way of doing this distributed proof-reading. I think more people would contribute if the mechanics were easier. Something like WikiBooks might be something to consider one day...

This is something I hoped newLISP wiki could handle, but I probably underestimate the difficulty of implementing it. The ability to do spot changes really is a must. Something like changing a comma would take the time to log in and about a second. Composing an email or Club response about the comma would take ten times that. Not to mention the time and work Lutz must put into making the updates later. A collaborative environment for editing documents would make minor edits more likely and encourage more up-to-date and correct documentation. Of course, it shouldn't be completely open to changes. Anyone interested in helping to maintain the documentation could PM or email Lutz (or a trusted maintainer) for permission to contribute edits.  



Lutz, can you see your way clear to something like this? Most mistakes are caught while quickly looking-up something in the documentation. Best to be able to change it right there while you are reading it.



With that, here are some more changes:



Manual entry for send in the Messages containing code for evaluation section:

- The following example shows how a parent process acts like a message proxy receiving messages from a child process routing them do another child process.

+ The following example shows how a parent process acts like a message proxy receiving messages from a child process routing them to another child process.



Manual entry for receive:

- For a detailed discussion of this function and examples see the send function.

+ For a more detailed discussion of this function and examples, see the send function.



Code Patterns in the Multiprocessing and the Cilk API section:

- On multiprocessor CPUs the operating system will distribute processes and child processes created on to different processor cores in an optimized fashion.

+ On multiprocessor CPUs the operating system will distribute processes and child processes created on different processor cores in an optimized fashion.



- The example shows, how a range of prime number generation is split up for parallel processing in three sub-ranges.

+ The example shows how a range of prime number generation is split up for parallel processing in three sub-ranges.



Code Patterns in the Message exchange between processes section under Acting as a proxy:

- does get send from pidA to the parent,

+ does get sent from pidA to the parent,



Code Patterns in the Databases and lookup tables section under In-memory database with keyed access:



- In the following example data records are stored in a hash namespace and access with the name of the person as a key.

+ In the following example, data records are stored in a hash namespace and access is with the name of the person as a key.



- Telefone (5 uses)

+ Telephone



That's all I could see in this initial pass. I must say though, Lutz (and I hope this doesn't embarrass you too much), that your ability to write English has improved to an amazing degree. As witnessed by the minor changes offered thus far. If I wore a hat it would be off to you sir :-)



m i c h a e l

[Lutz]

Thanks for the corrections Michael, I will put them in later today and put a new version on-line later together with the PDF manual, which I still have to make.



To the general problem how to correct/update documentation quickly, I will comment later. At the moment I am still doing stuff related to the release, which it up now!

[cormullion]

we still don't have a good way of doing this distributed proof-reading. I think more people would contribute if the mechanics were easier. Something like WikiBooks might be something to consider one day...

This is something I hoped newLISP wiki could handle, but I probably underestimate the difficulty of implementing it. The ability to do spot changes really is a must. Something like changing a comma would take the time to log in and about a second.

I personally like re-inventing the wheel  (as you know!) but you don't have to go that far for a task like this. The MediaWiki (newlisp on noodles - http://newlisp-on-noodles.org/">//http://newlisp-on-noodles.org/) is designed for multi-user fine-grained editing, and already has accounts, logins, passwords, administrators, history, revision tracking, etc. Getting a reasonable stand-alone document out of it might not even be necessary - reading the wikipedia as it is is a regular activity for most of us. The only thing I'd like to see would be syntax-coloured code. :)

[Lutz]

Media Wiki has a <source> tag for syntax highlighting and there is more about this here:



http://www.mediawiki.org/wiki/Extension:Syntax_Highlighting">http://www.mediawiki.org/wiki/Extension ... ghlighting">http://www.mediawiki.org/wiki/Extension:Syntax_Highlighting



Bringing existing documentation into the wiki shouldn't be difficulty either. The newlisp_manual.html conforms to a strict HTML-tag protocol, which can be parsed and translated with a script into Media Wiki tagging.



I thinks it is a great idea, but would not be very active in this project (I have enough to do already ;-) ).



For me the media wiki history page would be a great tool to audit changes from the newLISP programming perspective and to incorporate corrections in to HTML version of the manual.



For any configuration stuff, we would have to contact ghfischer (on this forum). He has access to http://newlisp-on-noodles.org">http://newlisp-on-noodles.org

[cormullion]

I've done a quick conversion of the Code Patterns document into Media Wiki format.



http://newlisp-on-noodles.org/wiki/index.php/Code_patterns">//http://newlisp-on-noodles.org/wiki/index.php/Code_patterns



I've done no checking or proofing (html codes, etc), but at first glance it looks suitable for the purpose. A little long, it seems, judging from the warning I get from MediaWiki.



I don't think the user manual could be done this way - it has to be available in electronic form in the software package. But I think the Code Patterns document - and others - could live happily in the wiki in this form.



However, I don't think that there should be 'two' master versions of the document maintained in different systems.

[Lutz]

How did you do the conversion? Did it say what the maximum size was.



Guided by the history tab I could reincorporate changes into the HTML document.

[cormullion]

How did you do the conversion? Did it say what the maximum size was.

I tried something listed http://en.wikipedia.org/wiki/Wikipedia:Tools/Editing_Tools">here, can't remember which, but ended up doing a lot of search and replace to fix the headings.

Guided by the history tab I could reincorporate changes into the HTML document.

You wouldn't need an HTML version as well, though, would you? And it's easy to get a printable HTML copy out should you really need one (http://newlisp-on-noodles.org/wiki/index.php?title=Code_patterns&printable=yes">//http://newlisp-on-noodles.org/wiki/index.php?title=Code_patterns&printable=yes).

[Lutz]

Only that the HTML conversion is still dependent on Media Wiki support files.  You wouldn't be able to stick that file into the distribution as is. If you just save from View/Source in a browser, you get a file without formatting and with 'edit' links in it.



One would have to write a script to manage this.



Are there other export facilities?

[cormullion]

If you just save from View/Source in a browser, you get a file without formatting and with 'edit' links in it.

I thought that printable version looked good enough - http://newlisp-on-noodles.org/wiki/index.php?title=Code_patterns&printable=yes">//http://newlisp-on-noodles.org/wiki/index.php?title=Code_patterns&printable=yes?



There are probably a few more export facilities... http://www.mediawiki.org/wiki/Category:All_extensions">//http://www.mediawiki.org/wiki/Category:All_extensions.

[tom]

I'm gonna stick my 2 cents in and say that I like dokuwiki better than mediawiki.  It's no big deal, but have you ever looked at it?  Dokuwiki saves in plain text, too, no database required.   I think we have talked about this before...

[Lutz]

Corumullion:



For printing or conversion to PDF it is definitely good looking and usable.



Putting "export" in the mediawiki.org search box I get zillions of interesting export formats. One of them is probably usable to get an HTML format back, independent of external files. A format which can be shipped as part of the distribution. May be this:



http://www.mediawiki.org/wiki/DocBook_XML_export">http://www.mediawiki.org/wiki/DocBook_XML_export



Tom:



yes, just browsing dokuwiki, looks very interesting indeed, and perhaps easier to export. An I love this:



http://www.dokuwiki.org/requirements">http://www.dokuwiki.org/requirements



It seems there is now database required it is also pretty small, perhaps I can even host it on newlisp.org. It probably will also accept bigger files, like newlisp_manual.html.

[Lutz]

I have DokuWiki installed here for everybody to try it out:



http://www.newlisp.org/dokuwiki/doku.php">http://www.newlisp.org/dokuwiki/doku.php



to change content, you have to login. There is a "register' link on the login page. When registering, a password will be sent to you via email.