Hi Peter, Thanks for your thoughts. I have wondered previously (in other projects) about the legitimacy of a distinction between manuals and command references. With a lot of effort, it can work -- but to make it work, duplication is inevitable. Manuals simply have to make references to commands, and I suspect that a 'comprehensive' user-friendly user manual is nothing but a comprehensive command reference, with the commands organised in a human way, with interspersed commentary, suggestions for use, and examples of usage. I'm in complete agreement, though, that however this is done, a VCS is necessary. (I'm plugging git as my favourite, but it's just the principle I'm arguing for here.) James On Thu, Mar 4, 2010 at 2:41 PM, Peter Münster wrote:

Hello,

These suggestions are a bit a reply to the thoughts of James Fisher.

It would be nice, to have once in the future at least 2 up to date context documentations:

- a context user manual For me, it's the merge of all scattered articles and manuals. Each chapter treats a particular subject, such as "columns" or "footnotes". It seems, that Taco is working on such a manual.

- a context command reference manual This is just the xml-database used by texshow. Each command should be described in detail with every possible options. On the one hand, texshow uses this database, on the other hand a well structured command reference can be generated as pdf-file.

Filling in all the details in both projects is a lot of work, so perhaps it would be a good idea, to set up a system, that makes it easy for users to contribute to these projects (patches) and easy for Taco and Hans to acknowledge or reject those patches.

This "system" would be nothing else as some vcs (git or svn for example) with some commit-hooks, that manage the acknowledgement by Hans and Taco (and perhaps others).

The tex-files of the user-manual are already under version control, and the xml-database is only the cont-en.xml file, that would need to be put under version control too.

So, perhaps with not too much effort, users can be easily invited to contribute to the documentation projects and the quality can be assured through the acknowledgements of the developers.

Cheers, Peter

-- Contact information: http://pmrb.free.fr/contact/

___________________________________________________________________________________ If your question is of interest to others as well, please add an entry to the Wiki!

maillist : ntg-context@ntg.nl / http://www.ntg.nl/mailman/listinfo/ntg-context webpage : http://www.pragma-ade.nl / http://tex.aanhet.net archive : http://foundry.supelec.fr/projects/contextrev/ wiki : http://contextgarden.net

___________________________________________________________________________________