Paulo,

Maybe we should move this discussion off the list to not bother others that may not be so interested in it.

They should use the killfile and fill it with my name (and erverything related) :-) Seriously: the question concerning ConTeXt documentation and examples is brought up on this list quite often. This is almost worth an faq entry (there is no faq yet btw.). So I think that this is a good place to stay until it is getting really of topic. Please see also the thread around http://archive.contextgarden.net/message/20040622.145524.ddf3cdc8.html

What I am trying to say (answering your question) is that learning by example is natural to human behaviour and extremely efficient.

But not everything is only done with learning by example. Sometimes concise references are needed.

If you attend any of my classes here in Berkeley you will see examples from begining to the end, no matter what the subject is: math or programming. Even with learned programmers, examples do work well, I took, for example (no pun intended) an MSDN CD for C++ I have here by my side, 80% os the space in the disk is taken by examples, the rest is shared between the software, SDK, and manuals ...

OK, but we are only partly talking about programming languages and not at all of math. Even in math (depending on the subject) examples except for trivial ones can be worthless because the complexity of the subject. So what are we talking about? We are talking about ConTeXt, wich is: a) a macro package built on top of TeX b) a typesetting tool c) to some extent a "design tool". (a tool to create desings) a) ConTeXt on the high level aspect is mentioned in all the documents out there. You can break down the documentation in different pieces: 1: ConTeXt is there to help the user to create structured documents (\section, \cite, ...). There is absolutely no typographic meaning to these commands that are used for structuring. The same would apply to structured xml documents. 2: ConTeXt gives you the ability to give formatting instructions to the system. This is done by commands like \setuphead and alike. 3: all the add-on features that are not strictly necessary for a typesetting job but makes live much easier (references ...) All af these need to be explained and yes, I agree with you here: examples on these are instructive and good. a, part two) TeX is a nasty language (did I say nasty? Yes I mean it the way, I have used *lots* of programming languages, but only few can compete with TeX in its ugliness and obscurity.) Doing programming tasks in TeX is no fun (unless your first name is Hans :-). And reading TeX programs is impossible for beginners. TeX has nothing to do in the examples we are talking about. So the "learning by example" documents should either be TeX-free or rated R. (or whatever). And I guess (that is my experience I have with my ConTeXt styles), there are a lot of places in these manuals where low level TeX contructs are used to make things work and look right. b) a typesetting tool. Typsetting is something far beyond trivial. And it is something that needs theoretical background and much experience. TeX is very good to hide typographical issues and does things right. But it cannot take away the need for experience. What do we gain from examples in source in this respect? Nothing at all. Users might think "this looks nice", but when applying what they have found might not always be appropriate. What do we need then? Perhaps a document "(micro)typograhy in ConTeXt". c) a "design tool". Yes, and this is the worst part of what you ask for (source codes on how to create a design). A design is only good for one thing and cannot be copied. The "one thing" might be something big like coproate identity or as small as a single document (or household appliance). If it is copied, it loses much. Just like the endless same-looking power-point presentations, I have seen quite some documents, totally unrelated, with similar desings. Well, it reliefs one from using his brain, but does not make things better. -> cook up your own design or let it alone. What kind of examples do we need? Perhaps some *small* examples covering only one technical aspect of our tools. E.g. transparencies in MetaFun and alike (see for example http://levana.de/context/layout/page.pdf and the source file http://levana.de/context/layout/page.tex ).

You promptly assumed that the guy wanted to copy the examples at hand. I don't think that this is right! He may indeed end up copying it, but you can't assume it.

OK, perhaps I was too eager to say he would do so. But I know that this will be done as soon as more examples for complex stuff is available. And no, copy & paste is not always evil. Patrick (still wondering if we could just create a list of needed examples and fill in the gaps without reverse engineer original manuals) -- ConTeXt wiki: http://contextgarden.net texshow-web: http://texshow.contextgarden.net List archive: http://archive.contextgarden.net