Re: Re: Best source of ConTeXt documentation?

Re: Re: Best source of ConTeXt documentation?

[Paulo Ney de Souza]

Patrick,

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

What I am trying to say (answering your question) is that learning by
example is natural to human behaviour and extremely efficient. 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 ... 

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.

Paulo Ney

    >From ntg-context-bounces@ntg.nl  Mon Aug  2 23:40:12 2004
    >From: "Patrick Gundlach" <patrick@gundla.ch>
    >To: ntg-context@ntg.nl
    >Subject: [NTG-context] Re: Best source of ConTeXt documentation?
    >
    >Hello Paulo,
    >
    >> Everyone learns a language by example, if you try to teach one you 
    >> will see, even Patrick, when he was a baby learned his first language
    >> by example (real language), it is only natural, it is only human. To
    >> argue the contrary is just lack of experience in teaching.
    >
    >Right, but what do you want to say? Typography and design is not a
    >matter of learning a language. 
    >
    >Patrick
    >-- 
    >ConTeXt wiki: http://contextgarden.net
    >texshow-web:  http://texshow.contextgarden.net
    >List archive: http://archive.contextgarden.net
    >_______________________________________________
    >ntg-context mailing list
    >ntg-context@ntg.nl
    >http://www.ntg.nl/mailman/listinfo/ntg-context
    >

Re: Best source of ConTeXt documentation?

[Patrick Gundlach]

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

Re: Re: Best source of ConTeXt documentation?

[Hans Hagen]

Nikolai Weibull wrote:

>* Paulo Ney de Souza <desouza@Math.Berkeley.EDU> [Aug 03, 2004 11:21]:
>  
>
>>Everyone learns a language by example...
>>    
>>
>
>What you should really be doing is asking specific questions to problems
>you're having with ConTeXt on this list.  I have gotten almost all my
>questions answered by now.
>  
>
... and after that write MyWays, or add info to the wiki or write an article for tugboat or the maps or dtk or ... 

Hans 

-----------------------------------------------------------------
                                          Hans Hagen | PRAGMA ADE
              Ridderstraat 27 | 8061 GH Hasselt | The Netherlands
     tel: 038 477 53 69 | fax: 038 477 53 74 | www.pragma-ade.com
                                             | www.pragma-pod.nl
-----------------------------------------------------------------

Re: Re: Best source of ConTeXt documentation?

[Paulo Ney de Souza]

    >From ntg-context-bounces@ntg.nl  Mon Aug  2 08:46:53 2004
    >From: "Patrick Gundlach" <patrick@gundla.ch>
    >To: ntg-context@ntg.nl
    >Subject: [NTG-context] Re: Best source of ConTeXt documentation?
    >
    >Oh come on, this is completely crap. The people at PRAGMA (i.e. Hans)
    >share ConTeXt, wich is the holy grail that PRAGMA is based on
    >(besides the knowledge). It is such a generous gift to the community.
    >Please think about if you write stuff like that.

I realize better that you do Hans contibutions to the Open Source community
and I never complained about the sharing of ConTeXt, which is indeed the 
best typesetting system I have seen. You are taking my comment into a 
completely different context, pun not intended!

    >You are right, that not all (only few) manuals are available in .tex
    >format. See pdftex manual and the magazines. Putting source
    >code online needs time, a lot of time. Source code needs to get
    >documented. And I don't know Hans very well, but I'd guess that his
    >day only has 24h.
    >
    >There are already some styles in the ConTeXt wiki. And there are
    >styles that come with the distribution. 

The discussion is not about styles, it is about examples and how-to.

    >Why reverse-engineer? Just cook up the style you want. If you have
    >questions doing this, ask on the ConTeXt list. If you are ready, put
    >the style onto the Wiki. The styles at pragma are very good, but
    >definitely not the only way to go. Making a good style is not
    >copy/paste. It is a matter of experience. Experience is something you
    >have to gain yourself.

We are not talking about experience and or copy/paste, if you are assuming 
that I don't have the experience or that the guy that posted the initial
message wants to copy and paste, again you are on the wrong track.

    >And yes, it is time for us to put examples online. But the ConTeXt
    >community is still rather small. So there won't be many results in a
    >short time.

I certainly will welcome the day we have a minimal how-to posted in there.

    >You can do the first step. Go to the wiki, edit a page that states
    >your questions regarding style development. Put a table of contents
    >or something similar there, which steps you would like to see, which
    >things you would like to have explained and so on. After that "we"
    >(the more experienced ConTeXt users) can fill in the gaps. And
    >finally we all have a small manual on style design. This is much
    >better than being so aggressive on the unwillingness to share source.
    >
    >Patrick

I'll give it a try, the wiki is certainly the way to go ...

Paulo Ney