Documentation for release 10.1.0
Documentation for release 10.1.0
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/develo ... .html#send
http://www.newlisp.org/downloads/develo ... ml#receive
In the Code Patterns document chapter 18. has been completely rewritten and expanded with more examples:
http://www.newlisp.org/downloads/develo ... processing
Chapter 19. about the messaging API is new:
http://www.newlisp.org/downloads/develo ... #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).
http://www.newlisp.org/downloads/develo ... .html#send
http://www.newlisp.org/downloads/develo ... ml#receive
In the Code Patterns document chapter 18. has been completely rewritten and expanded with more examples:
http://www.newlisp.org/downloads/develo ... processing
Chapter 19. about the messaging API is new:
http://www.newlisp.org/downloads/develo ... #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).
-
- Posts: 2038
- Joined: Tue Nov 29, 2005 8:28 pm
- Location: latiitude 50N longitude 3W
- Contact:
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:
non-sentencesWhen sync is called without parameters, it retuens a list of still active process ids:
othersSince newLISP offers a simple API which does all the work of launching processes and synchronizing collection of evaluation results in a transparent manner.
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...They can be made blocking using a loops:
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/develo ... terns.html
An updated version is online:
http://www.newlisp.org/downloads/develo ... terns.html
-
- Posts: 394
- Joined: Wed Apr 26, 2006 3:37 am
- Location: Oregon, USA
- Contact:
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.cormullion wrote: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, 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
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!
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!
-
- Posts: 2038
- Joined: Tue Nov 29, 2005 8:28 pm
- Location: latiitude 50N longitude 3W
- Contact:
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/) 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. :)m i c h a e l wrote: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.cormullion wrote: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...
Media Wiki has a <source> tag for syntax highlighting and there is more about this here:
http://www.mediawiki.org/wiki/Extension ... ghlighting
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://www.mediawiki.org/wiki/Extension ... ghlighting
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
-
- Posts: 2038
- Joined: Tue Nov 29, 2005 8:28 pm
- Location: latiitude 50N longitude 3W
- Contact:
I've done a quick conversion of the Code Patterns document into Media Wiki format.
http://newlisp-on-noodles.org/wiki/inde ... e_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.
http://newlisp-on-noodles.org/wiki/inde ... e_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.
-
- Posts: 2038
- Joined: Tue Nov 29, 2005 8:28 pm
- Location: latiitude 50N longitude 3W
- Contact:
I tried something listed here, can't remember which, but ended up doing a lot of search and replace to fix the headings.Lutz wrote:How did you do the conversion? Did it say what the maximum size was.
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/inde ... ntable=yes).Lutz wrote:Guided by the history tab I could reincorporate changes into the HTML document.
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?
One would have to write a script to manage this.
Are there other export facilities?
-
- Posts: 2038
- Joined: Tue Nov 29, 2005 8:28 pm
- Location: latiitude 50N longitude 3W
- Contact:
I thought that printable version looked good enough - http://newlisp-on-noodles.org/wiki/inde ... ntable=yes?Lutz wrote: If you just save from View/Source in a browser, you get a file without formatting and with 'edit' links in it.
There are probably a few more export facilities... http://www.mediawiki.org/wiki/Category:All_extensions.
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
Tom:
yes, just browsing dokuwiki, looks very interesting indeed, and perhaps easier to export. An I love this:
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.
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
Tom:
yes, just browsing dokuwiki, looks very interesting indeed, and perhaps easier to export. An I love this:
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.
I have DokuWiki installed here for everybody to try it out:
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.
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.
Is the manual /code patterns HTML generated from another text format? My humble suggestion is to check the docs into github in their most basic form. Then if someone sees something that needs to be changed they just click "fork", make the change (which can be done through the github web app, without ever downloading the doc to your computer), then sending the patch to Lutz who can choose to accept it or not...Cormullion wrote: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...
Nick
Thanks for the suggestion nallen05, but I think we will go with DokuWiki. I just finished bringing in the first 9 chapters:
http://www.newlisp.org/dokuwiki/doku.php?id=start
And its going smooth. A big help was the preperation Cormullion did bringing it into the http://newlisp-on-noodles.org/wiki . From there it was easy, with few changes. The Wiki format is easy to translate back into HTML too, if required. Log in/register and try it out ;-)
http://www.newlisp.org/dokuwiki/doku.php?id=start
And its going smooth. A big help was the preperation Cormullion did bringing it into the http://newlisp-on-noodles.org/wiki . From there it was easy, with few changes. The Wiki format is easy to translate back into HTML too, if required. Log in/register and try it out ;-)
-
- Posts: 2038
- Joined: Tue Nov 29, 2005 8:28 pm
- Location: latiitude 50N longitude 3W
- Contact:
I like the idea of working in simple text/markup, rather than trying to edit HTML, and documents in small sections are easier to
handle than large single documents. So a good solution would have revision-tracked marked-up text sections, which are then automatically combined and converted to various output formats. Using git would be good for the tracking but something else would probably be needed for the combine/convert phase. I think a wiki provides everything in a single package, and also gives a good on-line browsing experience (well, I use the wikipedia a lot, I'm sort of used to it...).
I'll have a go at docuwiki soon.
handle than large single documents. So a good solution would have revision-tracked marked-up text sections, which are then automatically combined and converted to various output formats. Using git would be good for the tracking but something else would probably be needed for the combine/convert phase. I think a wiki provides everything in a single package, and also gives a good on-line browsing experience (well, I use the wikipedia a lot, I'm sort of used to it...).
I'll have a go at docuwiki soon.
I have the first 10 chapters in, but not all have been converted to the <code> tags, which will allow syntax highlighting.
The subtitles are at the moment H4 (this is how they came in from MediaWiki). Perhaps we want to convert to H3. I think then they will be indexed. This is already happening automatically for the number H2 titles.
http://www.newlisp.org/dokuwiki/doku.php
Here the most important link for editors:
http://www.dokuwiki.org/syntax
The revisions methods is pretty much the same as MediaWiki with comparisons, etc.
The subtitles are at the moment H4 (this is how they came in from MediaWiki). Perhaps we want to convert to H3. I think then they will be indexed. This is already happening automatically for the number H2 titles.
http://www.newlisp.org/dokuwiki/doku.php
Here the most important link for editors:
http://www.dokuwiki.org/syntax
The revisions methods is pretty much the same as MediaWiki with comparisons, etc.
-
- Posts: 2038
- Joined: Tue Nov 29, 2005 8:28 pm
- Location: latiitude 50N longitude 3W
- Contact:
Permissions where not set up correctly in the admin panel. You should now be able to edit and create pages too.
And yes, you can edit in paragraphs. You will see an "edit" button for each chapter (H2 title).
What I did was editing the last one to add another one. You also have the optin to hit the "edit page" button for editing everything bit it is slow, and I think it also locks everybody else out for editing.
And yes, you can edit in paragraphs. You will see an "edit" button for each chapter (H2 title).
What I did was editing the last one to add another one. You also have the optin to hit the "edit page" button for editing everything bit it is slow, and I think it also locks everybody else out for editing.
-
- Posts: 2038
- Joined: Tue Nov 29, 2005 8:28 pm
- Location: latiitude 50N longitude 3W
- Contact:
Sorry about this! but I am sure it works now. I created a dummy user to try out the (somewhat complicated) permissions stuff and put it right for everybody.As of 2009-06-26 15:45:16 +0100 I can't see anything which isn't read-only...
Code Patterns is now fully imported with a two level index and syntax highlighting working too.
-
- Posts: 2038
- Joined: Tue Nov 29, 2005 8:28 pm
- Location: latiitude 50N longitude 3W
- Contact: