On 06-09-29 12:50 -0400, Philip Schuchardt wrote:

Sweet! Awesome documention. To me, it feels like Therion is documented far better then any other cave mapping software.

That's because everyone who uses it seriously has to write some user-level documentation to help themselves :-) It is indeed a remarkable piece of work Marco - it must have taken weeks! The diagrams are hugely useful. I have only had a quick read, so missed a lot of detail, but I found a number of things that could be fixed/imporved, and some that need discussion about the best way to do things. For the text that is easy to just do, but the pictures are harder to modify without the original source files. It seems to me that this set of docs go a long way to replacing the thbook. I wonder where we should go from here. Currently the thbook is a complete reference to the syntax and a developer reference (with some user-level info), whilst the wiki contains a full 'user guide' plus much (most?) of the reference material. Ideally we could get one set of documentation which contained everything that is known, probably split into 'user guide' and 'reference' and 'developer info' sections. Does anyone have any suggestions for how to keep the benefits of wikified documentation, yet still be able to produce standalone docs in PDF or whatever form? I have used Docbook (SGML, now XML is preferred) to easily produce docs in multiple output forms: (HTML/PDF/DOC etc), but I don't know how to integrate that with wiki markup, or even if it is usefully possible. Somehow having the original exmaple files and diagrams around so they can easily be updated would also be good. Perhaps all we need is a way to generate static html from the wiki docs (for inclusion with therion source/binary/package distribution) and forget about a PDF version? I am interested in helping with such an activity, especially with english grammar improvements and general corrections. What does everyone else think? Wookey -- Aleph One Ltd, Bottisham, CAMBRIDGE, CB5 9BA, UK Tel +44 (0) 1223 811679 work: http://www.aleph1.co.uk/ play: http://wookware.org/

First HTML export attempt... http://wiki.speleo.cz/therion-wiki/export/ Each namespace can be exported separately. Lada Olly Betts wrote:

On Fri, Sep 29, 2006 at 10:52:45PM +0100, Wookey wrote:

...

Does anyone have any suggestions for how to keep the benefits of wikified documentation, yet still be able to produce standalone docs in PDF or whatever form? I have used Docbook (SGML, now XML is preferred) to easily produce docs in multiple output forms: (HTML/PDF/DOC etc), but I don't know how to integrate that with wiki markup, or even if it is usefully possible. Somehow having the original exmaple files and diagrams around so they can easily be updated would also be good.

There are various conversion filters around which allow you to convert various wiki markup styles to/from other formats (just google for the wiki software name and the format you want to convert to to find some).

So you could probably keep documentation in a wiki format so it's easy for anyone to edit and just find (or even write) filters to convert it to all the formats you want (or just to something like docbook which can then be converted to those formats).

After all, wiki markup generally provides most of what you really need from a markup language, is easier to learn and less intrusive than docbook, and some wikis allow macros so it can probably be extended to cover any special requirements.

Cheers, Olly _______________________________________________ Therion mailing list Therion@speleo.cz http://www.speleo.cz/mailman/listinfo/therion