Re: State of documentation of ConTeXt?

[Gerben Wierda <gerben.wierda@rna.nl>]

On 20 Jul 2014, at 22:24, Mojca Miklavec <mojca.miklavec.lists@gmail.com> wrote:

> On Sun, Jul 20, 2014 at 2:14 PM, Gerben Wierda wrote:
>> 
>> Sorry, you can’t expect users to be able to do that. Lamport
>> created LaTeX *and* wrote the “LaTeX User’s Guide and Reference manual”.
> 
> <teasing>
> Indeed. Sorry, you can't do that to users. Christian Schenk also
> created MikTeX (I still have MikTeX files from 23 years ago) *and* is
> still developing it actively and answering emails from users.
> </teasing>
> 
>> The authors mentioned below were all developers too. You need that level of
>> understanding to write a manual.
> 
> What kind of developers? Did they contribute to the LaTeX core? (Many
> ConTeXt users are developers, but it highly depends what you count as
> a developer.)

Some contributed packages, some other stuff (even printer drivers). They all were deeply involved with the inside of TeX and LaTeX at a level that they would have to understand TeX and LaTeX to the core as they were developers in that environment

>> Hans & Taco: how much money would need to be raised to produce something of
>> the quality of Kopka & Daly’s “Guide to LaTeX”?  or Goossens, Mittelbach &
>> Samarin’s “The LaTeX Companion”?
> 
> What do you mean with "of the quality of these books"? Having a
> similar number of pages written in comparable quality (something like
> a revised beginner's manual) or so complete in description of the
> functionality as the mentioned manuals?

I agree these are now outdated in several areas and less useful as they were half a decade ago. But something that is complete enough for a user (not a TeXnician), doesn’t contain too many white spots and certainly does not contain stuff that isn’t true anymore.

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

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