Re: State of documentation of ConTeXt?

[Henning Hraban Ramm <texml@fiee.net>]

Am 2014-07-21 um 03:07 schrieb Gerben Wierda <gerben.wierda@rna.nl>:

>> My estimate would be that a complete context reference with
>> well-described options and including trivial examples would require
>> cca. 10.000-50.000 pages. Maybe others have different estimates, but
>> now do the math. (Existing manuals like MetaFun or the old cont-en.pdf
>> are roughly 400 pages. But that's nowhere near 10 % of the ConTeXt
>> functionality. One would need to document the whole TeX part, the
>> whole metapost part, the whole lua part, the whole xml, all perl, ruby
>> and lua scripts, write better man pages, probably list the whole
>> Unicode to show the ConTeXt names in one appendix …)
> 
> If a tool needs 50.000 pages to document its use, you are in trouble (in more ways than one). 
> 
> I think in reality a set of manuals, with core functionality and all kinds of extras a manual of 500 pages and maybe a reference manual of the same size would be something useful and thus meaningful. Stuff like MetaFun can have its own manual and doesn’t need to be in a core ConTeXt manual.
> 
> A user manual is enough. You don’t need a developer manual. So, documenting all the development you can do with ConTeXt (programming in lua and whatnot) would for me not be what is needed for a user manual. What a user manual does is what cont-en.pdf does, but then up to date and complete.

If I might chime in …

What we really need (and what „simple“ users like me cannot write, even if I sometimes look into the sources) is a usable command reference, covering all „usable“ commands and all their „usable“ options (i.e. omit too experimental stuff).
What we have on the wiki now is much too incomplete in all regards. I don’t know if there’s something (more?) that can be automated.

I don’t know if Hans, Taco or Wolfgang (any other candidates?) would be able and willing to do that work, if e.g. DANTE would fund it. Would you, and what do you think how much funding would be required to at least document the current state of MkIV?

I would not try to write a (printed/printable) reference manual for ConTeXt, that really makes not much sense.
We don’t need to argue about page estimates, that depends too much on layout anyway …

I thought the previous ConTeXt meeting was about documentation? Didn’t you agree on a better wiki structure?


Greetlings, Hraban
---
http://www.fiee.net/texnique/
http://wiki.contextgarden.net
https://www.cacert.org (I'm an assurer)

___________________________________________________________________________________
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
___________________________________________________________________________________