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 <pmlists@free.fr> 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
___________________________________________________________________________________