Re: cont-enp.pdf on lulu

[Uwe Koloska <ml@koloro.de>]

Hello,

Am Montag, 28. Juli 2008 schrieb Gerben Wierda:
> I have an idea. Why not have a live ConTeXt manual.pdf where you add
> something in the proper location and compile the document every time
> you answer a question from a user? As you are the person answering
> anyway, it should be little extra work.

A good idea! But from my pov it should be clarified a bit. We must distinguish 
between:
- a user manual that tells you how to use the system and give you an overview 
of the whole system and the most important parts (pictures, math, etc.)
- and a reference manual, that describes all available commands in detail.

The user manual exists (excursion and manual) but has to be revised. The 
reference manual exists (http://texshow.contextgarden.net/) but is by far not 
complete.

As it is very difficult to make an automated process for producing the user 
manual, the candidate for the proposed semiautomatic production is the 
reference manual.
Where does the XML-files that are the basis for the existing texshow 
applications come from?  The production of this file(s) has to be somehow 
bound to the current sourcecode. Then at least all commands are present 
and "only" the documentation has to be filled in. The last commands I have 
learned by asking on this list, are all not present in texshow so that I was 
not able to add the description there ...

For the user manual(s) (in my opinion the excursion is a part of "the 
manual"), there are these steps necessary:
- provide a sourceversion that works with the current state of context
- identify the portions that are completely out of sync and cut them out (or 
mark them clearly as outdated)
- provide pointers to the more current documentation for every part (and mark 
differences between mkii and mkiv)
- add the missing main features

and as a bonus to the reference manual:
- make groups of commands that belong together and describe their interactions 
(something like the portal pages of wikipedia)

As far as I understand the situation, the completion of the reference manual 
is a realistic goal for the near future. And it is possible that everyone 
helps with this by filling the answers you get on this list into the command 
descriptions.


Wow, this has been gotten longer than I wanted it to be :-)
But let me close with a HUGE big THANK YOU to Hans and Taco and the other 
people that make context such a great tool!

Uwe
___________________________________________________________________________________
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  : https://foundry.supelec.fr/projects/contextrev/
wiki     : http://contextgarden.net
___________________________________________________________________________________