Documentation

[GWS]

Hi guys, we can't be completely without documentation, - so here's a start page for the User Guide.

It's just a form of words, which will probably need hacking to pieces (and I know nothing about Linux) - but hey it's a start ..

all the best,

Graham

[GWS]

Having slept on it, I'm wondering if a better approach (considering it's new to everybody), would be to have one of Jerry's wonder Wiki scratchpads somewhere.

Then whenever anybody had something to add to the notes, or any improvement of any text , they could type it in at any time.

I'll have to pester Jerry for a new password for my Wiki editor so I can scratch away at odd moments. :)ÂÃ,  I've wrecked mine again doing yet another Windows re-build due to Broadband.

Of course it's not easy, 'cos we don't know much about the language yet - but it would grow.
Then Paul could pick out any bits he thought were useful for his 'official' documentation.

Also, there's a big decision whether it would be better to keep the Linux version guide separate from the Windows one.ÂÃ,  Myself, I find combined documents a bit wearing - you have to keep skipping pages to get to the right bits.

best wishes,

Graham

[Jerry Muelver]

Graham, for language documentation work, you really need a hierarchical tree topic TOC control. I've written a tool like that for working in wxWidgets environment (runs on Win, Linux, Mac), but it's pre-alpha. It does the job, but you need some sleight-of-hand to run it.

In WikiWriter, you can work well with a TOC listing on your Home page, to jump around the project as-needed, and to rearrange sequences and tree-structure. The HTML output is, of course, cross-platform, though it can be bulky to distribute, unlike the single-file CHM (Win, and there's a work-alike Linux CHM as well) and the wxHelp system (which reads directly out of a zip file without unzipping it). Another cross-platform option is to distribute in RTF, since there are RTF readers on all platforms.

For a quick start, you might look at TreePad http://treepad.com with has the right outline structuring tools, and will import/export in CSV for migrating to other tools. TreePad Lite is freeware, and adequate to the task, and Win/Linux cross-platform. With a little standardization (like, WikiWriter markup codes), it would be easy to export the file and copile with another tool into any format you needed. XML comes to mind.

Paul is used to the HTML Help kit, and doing things the hard (geeky) way. Other contributors might not be so facile, so it would be wise to look into easy ways. Experimenting with TreePad would be a good start.

[GWS]

Hi Jerry,

I was dreaming something more along the lines of a centrally located 'scratchpad' document, that any contributor could add to, but not deleteÂÃ, 

Maybe it's not practicable.ÂÃ,  I don't mind what format is used as long as it's easy for folk to generate stuff ..

Early days yet anyway ..

all the best,

Graham

[Jerry Muelver]

Right, Graham. A wiki would be best for collaborative "scratchpad" knowledge-base building. It could be passworded, out of public view, with periodic summaries posted for public consumption. Paul, you've got SMS on your ISP (otherwise we wouldn't be posting here!), so I wonder if you've got wiki apps available for installation from your ISP? ? If not, PM me, and we'll talk.