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/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
Chapter 19. about the messaging API is new:
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).
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 -
Quote
Quote
non-sentences
Quote
others
Quote
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...
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
Quote from: "cormullion"
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
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
- 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
- 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
- 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
- does get send from pidA to the parent,
+ does get sent from pidA to the parent,
Code Patterns in the
- 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!
Quote from: "m i c h a e l"
Quote from: "cormullion"
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
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 (//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. :)
Media Wiki has a <source> tag for syntax highlighting and there is more about this here:
http://www.mediawiki.org/wiki/Extension:Syntax_Highlighting
Bringing existing documentation
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
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
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.
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.
Quote from: "Lutz"
I tried something listed
Quote from: "Lutz"
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).
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?
Quote from: "Lutz"
I thought that printable version looked good enough - //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.
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...
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.
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.
Quote from: "Cormullion"
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
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 ;-)
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! ;-)
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.
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.
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...
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.
As of 2009-06-26 15:45:16 +0100 I can't see anything which
It looks like you've fixed the code syntax stuff? Looks good.
Quote
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.
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"!
Quote
Yes, I think we have enough. I was editing (formatting) the whole day and it went smooth.
Quote
It shows it very faint in a light grey, even if not logged in. It is hard to see. I haven't found the place yet to change that color.
The admin page is pretty big, I am just know getting familiarized with it.
I've put the Introduction to newLISP on the docuwiki. I'm finding it hard to work with large documents; I suppose I should really split them up into small sections, but that's a lot of work, unless I'm missing some obvious feature. Sometimes I'm waiting over a minute for a response...
If it looks OK, this will be the new master version, and I'll archive the others.
Just a few pictures to upload: how do I do that?
Your images are already up there from the HTML version of the introduction, e.g. this one:
http://www.newlisp.org/introduction-to-newlisp/graphics/newlisp-logo-horizontal-240x100.png
or this one:
http://www.newlisp.org/introduction-to-newlisp/graphics/newlispeditor.png
There is documentation how to use the wiki, on the index page under "wiki".
Of course, thanks! The links were easily fixed.
You've done a great job, Lutz - it's all looking pretty good, and I hope that it will help us improve our documentation further.
I realise that these long documents are not suitable for the wiki approach. I cut the Introduction into two, but they're both still way too big - although the loading time for viewing is much quicker than that for editing. Ideally each section would have its own page - presumably there would be some mechanism for outputting or printing the whole lot at once. However, it's a real pain chopping up long documents, so I've chickened out of doing it for now. :)
Yes, bigger pages are a pain. But the CodePatterns doc is smaller and not fast but usable. These are the workarounds, I have used:
- Click the "Edit this page" button, and then wait only twice at the beginning and the end of an editing session.
- Copy the whole page out of the edit control, then edit it offline, then past it back into the edit control. The advantage is, you can edit with your own familiar editor, which has all the facilities one is accustomed too.
So I hope that someone in UK ( or anywhere else ;-) ) fixes some problems in that Code Patterns document. And I will do all new stuff at first in the wiki for public editing.
Lutz
Are you still going to support the "Manual and Reference" document distributed with newLISP? In its current format (strict HTML with or without index frame) it is probably the nicest lisp manuals I have ever seen...
Nick
Yes, absolutely!
And this is true for both CodePatterns.html and newlisp_manual.html (The Users Manual and Reference).
Both can be read even with very old browsers or console text browsers (lynx). An both are easy to parse (for online help, translation etc), because they use a simple HTML tagging syntax.
I am still working on CodePatterns.html to perfect it in this respect. Probably it will be translated from the wiki back into HTML with a script, after somebody made edits. CodePatterns.html has never been edited by anybody else than me, and has some pretty horrible English in there (that's what they tell me ;-) at least ).
Now that we have the wiki it should be possible to review a few sections here and there, rather than try to read the whole lot in one go. I hope everyone here lends a minute or two!
I'm hoping to get round to it soon, but time slips through my fingers like sand at the moment... :)
just want to point out that we could use dokuwiki namespaces too, which just sort into directories. [[manual:introduction]] makes a file "introduction" in the directory "manual".
You probably already knew that...
Thanks Tom. I just stuck some colons in, like I was using newLISP.. :)
Do you know how to split up large documents into smaller sections? (Without doing it all by hand and getting totally lost while doing so.) It would be cool if there was a "split into sections" command.
Is it an Idea to add an extra "Sign" to the functions inside the manual for
an even quicker reverence on functions..
Currently the "!" is used to point on Destructive functions.
I was thinking of adding ->
"L" returns a list
"E" returns elements
"N" retuns nil
"T" returns true
Hello Lutz,
I dont find the manual very clear on FOOP as it currently is,
a little chaotic explained havnig examples floating between lines..
Here is the small version on how to explain the FOOP construction,
perhpas a better addon for inside the manual?
;; A little help for the mindset on FOOP.
;;
;; The following are exactly the same,
;; This is to point out the construction of FOOP
;; FOOP from within the 'MAIN context
(new Class 'Rectangle)
(set 'myrect (Rectangle 5 5 10 20))
(define (Rectangle:area p) (mul (p 3) (p 4)))
(:area myrect)
;; FOOP from within other then the 'MAIN context
(new Class 'MAIN:Rectangle)
(set 'myrect (Rectangle 5 5 10 20))
(define (Rectangle:area p) (mul (p 3) (p 4)))
(:area myrect)
;; FOOP simplyfied ->
(define (Rectangle:Rectangle) (cons (context) (args)))
(define (Rectangle:area p) (mul (p 3) (p 4)))
(Rectangle:area (Rectangle 5 5 10 20))
;; FOOP the namespace way ->
(context 'Rectangle)
(define (Rectangle) (cons (context) (args)))
(define (area p) (mul (p 3) (p 4)))
(context 'MAIN)
(Rectangle:area (Rectangle 5 5 10 20))