Documentation for release 10.1.0

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

Documentation for release 10.1.0

Post by 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/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).

cormullion
Posts: 2038
Joined: Tue Nov 29, 2005 8:28 pm
Location: latiitude 50N longitude 3W
Contact:

Post by 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
Posts: 5289
Joined: Thu Sep 26, 2002 4:45 pm
Location: Pasadena, California
Contact:

Post by 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/develo ... terns.html

m i c h a e l
Posts: 394
Joined: Wed Apr 26, 2006 3:37 am
Location: Oregon, USA
Contact:

Post by m i c h a e l »

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...
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
Posts: 5289
Joined: Thu Sep 26, 2002 4:45 pm
Location: Pasadena, California
Contact:

Post by 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
Posts: 2038
Joined: Tue Nov 29, 2005 8:28 pm
Location: latiitude 50N longitude 3W
Contact:

Post by cormullion »

m i c h a e l wrote:
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...
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/) 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
Posts: 5289
Joined: Thu Sep 26, 2002 4:45 pm
Location: Pasadena, California
Contact:

Post by Lutz »

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

cormullion
Posts: 2038
Joined: Tue Nov 29, 2005 8:28 pm
Location: latiitude 50N longitude 3W
Contact:

Post by cormullion »

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.

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

Post by 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
Posts: 2038
Joined: Tue Nov 29, 2005 8:28 pm
Location: latiitude 50N longitude 3W
Contact:

Post by cormullion »

Lutz wrote:How did you do the conversion? Did it say what the maximum size was.
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: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/inde ... ntable=yes).

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

Post by 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
Posts: 2038
Joined: Tue Nov 29, 2005 8:28 pm
Location: latiitude 50N longitude 3W
Contact:

Post by cormullion »

Lutz wrote: 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/inde ... ntable=yes?

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

tom
Posts: 168
Joined: Wed Jul 14, 2004 10:32 pm

Post by 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
Posts: 5289
Joined: Thu Sep 26, 2002 4:45 pm
Location: Pasadena, California
Contact:

Post by 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

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.

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

Post by Lutz »

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.

nallen05
Posts: 21
Joined: Sun Apr 19, 2009 10:12 pm

Post by nallen05 »

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...
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...

Nick

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

Post by Lutz »

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 ;-)

newdep
Posts: 2038
Joined: Mon Feb 23, 2004 7:40 pm
Location: Netherlands

Post by newdep »

I was a little sceptic about this but now that I see this it has advantages.. If it will create more or less work in the end I dont know but its better then communicating it through the forum..
..Btw quick work setting this up! ;-)
-- (define? (Cornflakes))

cormullion
Posts: 2038
Joined: Tue Nov 29, 2005 8:28 pm
Location: latiitude 50N longitude 3W
Contact:

Post by cormullion »

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.

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

Post by Lutz »

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.

cormullion
Posts: 2038
Joined: Tue Nov 29, 2005 8:28 pm
Location: latiitude 50N longitude 3W
Contact:

Post by cormullion »

This looks promising...

Everything is read-only for me, having logged in. Is that right?

In the MediaWiki, you could edit at the paragraph level. Is this possible? If not, the document will have to be split into separate sections...

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

Post by Lutz »

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.

cormullion
Posts: 2038
Joined: Tue Nov 29, 2005 8:28 pm
Location: latiitude 50N longitude 3W
Contact:

Post by cormullion »

As of 2009-06-26 15:45:16 +0100 I can't see anything which isn't read-only...

It looks like you've fixed the code syntax stuff? Looks good.

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

Post by Lutz »

As of 2009-06-26 15:45:16 +0100 I can't see anything which isn't read-only...
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.

Code Patterns is now fully imported with a two level index and syntax highlighting working too.

cormullion
Posts: 2038
Joined: Tue Nov 29, 2005 8:28 pm
Location: latiitude 50N longitude 3W
Contact:

Post by cormullion »

Yes! That works now. I did an edit. Have you got plenty of bandwidth for us, Lutz? :)

I noticed that the "recent changes" page doesn't show who made the changes. If there's a configuration option for that, it could be worth switching on.

Next: "Introduction to newLISP: the Wiki Version"!

Locked