Re: Best source of ConTeXt documentation?

["Patrick Gundlach" <patrick@gundla.ch>]

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