Documentation for release 10.1.0

[nallen05]

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]

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">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">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]

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

[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]

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">http://www.newlisp.org/dokuwiki/doku.php



Here the most important link for editors:



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



The revisions methods is pretty much the same as MediaWiki with comparisons, etc.

[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]

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]

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]

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]

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"!

[Lutz]

Have you got plenty of bandwidth for us, Lutz?

Yes, I think we have enough. I was editing (formatting) the whole day and it went smooth.

I noticed that the "recent changes" page doesn't show who made the changes.

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.

[cormullion]

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?

[Lutz]

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">http://www.newlisp.org/introduction-to- ... 40x100.png">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">http://www.newlisp.org/introduction-to- ... editor.png">http://www.newlisp.org/introduction-to-newlisp/graphics/newlispeditor.png



There is documentation how to use the wiki, on the index page under "wiki".

[cormullion]

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

[Lutz]

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.