Best source of ConTeXt documentation?

Best source of ConTeXt documentation?

[Brooks Moses]

In my efforts to learn ConTeXt, I'm continually getting stuck by a lack of 
having complete documentation.  For example, consider the \definestartstop 
command, which I was recently looking at.

* In the cont-enp.pdf manual, it's not mentioned.

* In the mp-cp-en.pdf manual, there's an example of it, but it's not really 
very clear what the difference is between what the "commands=" and 
"before=" options do.  In addition, there's no indication whether these are 
all the possible options or not, or whether there's any way to define a 
start/stop pair that takes an argument.

* In the source, I can find the definitions, but for that particular one 
there seems to be very little commentary, and I also suspect I'd need to be 
rather familiar with the ConTeXt core before I could understand it -- I 
certainly can't see where the "before=" goes in, for instance.

And that's about all I know about, other than doing a Google search on the 
mailing-list archives, which rarely addresses the general stuff.

Is this all due to an actual lack of documentation for ConTeXt itself, or 
is there something large and important that I'm missing?

Thanks,
- Brooks

Re: Best source of ConTeXt documentation?

[Gary Pajer]

I would guess that it boils down to the fact that Hans, despite a
staggeringly remarkable likeness in appearance, is not Superman.

But I, and others, share your pain.    The efforts of Hans and the regulars
on this group make up for it in large measure.  (BTW,  Thank You to all the
regulars) and the Wiki and Texshow-web have great potential to help ... if
they really catch fire.

-gary


----- Original Message ----- 
From: "Brooks Moses" <bmoses@stanford.edu>
To: "ConTeXt users list" <ntg-context@ntg.nl>
Sent: Sunday, August 01, 2004 6:23 PM
Subject: [NTG-context] Best source of ConTeXt documentation?


> In my efforts to learn ConTeXt, I'm continually getting stuck by a lack of
> having complete documentation.  For example, consider the \definestartstop
> command, which I was recently looking at.
>
> * In the cont-enp.pdf manual, it's not mentioned.
>
> * In the mp-cp-en.pdf manual, there's an example of it, but it's not
really
> very clear what the difference is between what the "commands=" and
> "before=" options do.  In addition, there's no indication whether these
are
> all the possible options or not, or whether there's any way to define a
> start/stop pair that takes an argument.
>
> * In the source, I can find the definitions, but for that particular one
> there seems to be very little commentary, and I also suspect I'd need to
be
> rather familiar with the ConTeXt core before I could understand it -- I
> certainly can't see where the "before=" goes in, for instance.
>
> And that's about all I know about, other than doing a Google search on the
> mailing-list archives, which rarely addresses the general stuff.
>
> Is this all due to an actual lack of documentation for ConTeXt itself, or
> is there something large and important that I'm missing?
>
> Thanks,
> - Brooks
>
> _______________________________________________
> 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: Best source of ConTeXt documentation?

[Nikolai Weibull]

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

--
::: name: Nikolai Weibull    :: aliases: pcp / lone-star / aka :::
::: born: Chicago, IL USA    :: loc atm: Gothenburg, Sweden    :::
::: page: www.pcppopper.org  :: fun atm: gf,lps,ruby,lisp,war3 :::
main(){printf(&linux["\021%six\012\0"],(linux)["have"]+"fun"-97);}

Re: Best source of ConTeXt documentation?

[Hans Hagen]

skhilji@tampabay.rr.com wrote:

>And of course, once we learn the tool, then making small changes here and there to make it look slightly different is no big deal.
>  
>
for that the s-* files (and sometimes x-* files) makr a good starting point 

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: Best source of ConTeXt documentation?

[Patrick Gundlach]

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

Re: Best source of ConTeXt documentation?

[Patrick Gundlach]

Hello Salman,

> The problem with "normal
> users" cooking up new styles is the lack of artistic abilities in
> some people (like me). 

But you will never gain artistic abilities by simple copy/paste. 

> One can, obviously go thru the manual cover the cover, but if one
> does not have creative thinking, then creating professional looking
> styles would be hard. That is why, users like me really do not care
> if our documents look like everybody else's (just as long as they
> look professional).

The ability to know how to program/use a text editor/use photoshop
can only help you with the technical difficulties in making a
professional cover and style. Not more. 

> And of course, once we learn the tool, then making small changes
>here and there to make it look slightly different is no big deal.

Each LaTeX document looks slighlty different. But overall they are
extremely easy to classify as a LaTeX document. And why? The
distances and parameters are all given so it looks "right" and there
is no reason to change them.

Patrick
-- 
ConTeXt wiki: http://contextgarden.net
texshow-web:  http://texshow.contextgarden.net
List archive: http://archive.contextgarden.net

Re: Best source of ConTeXt documentation?

[Patrick Gundlach]

Hello again,

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

No, actually I am not. You wrote "People at Pragma are willing to show
off but not willing to share code and teach by example..." 

Willing to show off -> that is right. The talks etc. are really
   impressive (but more than that).
"but not willing to share code" -> this is, as you know, mostly
   wrong. How many thousands of lines do they share? How many lines
   do you share?
"...and teach by example". There *are* a few examples online. Did you
   look at the magazines? Did you look at the pdftex manual? 

I just guess you did not find them. (Or know about.) 

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

Styles are examples. Did you have a look? And yes, howtos are missing. 


[...]

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

You were talking about reverse engeneering. What is wrong about
making up your own style and publish it? You obviously lack experience
(which is not ment negative) (or are too unwilling to do so) in style
design with ConTeXt, or you would do the first step and publish *your*
styles somewhere, together with sources. Then you will find out that
publishing source code is not always trivial.

So my conclusion is something like this: write down your questions
you have and we can fill in the gap. As long as people are only
complaining and whining, nothing will change. Constructive criticism
is much better than the messages you sent.

And if we continue this conversation: please point out which styles
you would like to see available. There too many documents at PRAGMA,
so we might talk about different items. 

Patrick
-- 
ConTeXt wiki: http://contextgarden.net
texshow-web:  http://texshow.contextgarden.net
List archive: http://archive.contextgarden.net

Re: Best source of ConTeXt documentation?

[Paulo Ney de Souza]

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.

Paulo Ney

    >From ntg-context-bounces@ntg.nl  Mon Aug  2 20:05:20 2004
    >From: skhilji@tampabay.rr.com
    >Subject: Re: [NTG-context] Best source of ConTeXt documentation?
    >To: ntg-context@ntg.nl
    >
    >Adding to this thread (I don't mean a reply to Paulo, but rather a reply to what Hans was saying earlier)...The problem with "normal users" cooking up new styles is the lack of artistic abilities in some people (like me).  One can, obviously go thru the manual cover the cover, but if one does not have creative thinking, then creating professional looking styles would be hard.  That is why, users like me really do not care if our documents look like everybody else's (just as long as they look professional).
    >
    >Its kind of like learning Photoshop and knowing what each toolbar button does....but not knowing how to mix all the available tools create a professional looking graphic.
    >
    >And of course, once we learn the tool, then making small changes here and there to make it look slightly different is no big deal.
    >
    >Salman
    >
    >_______________________________________________
    >ntg-context mailing list
    >ntg-context@ntg.nl
    >http://www.ntg.nl/mailman/listinfo/ntg-context
    >

Re: Best source of ConTeXt documentation?

[skhilji]

Adding to this thread (I don't mean a reply to Paulo, but rather a reply to what Hans was saying earlier)...The problem with "normal users" cooking up new styles is the lack of artistic abilities in some people (like me).  One can, obviously go thru the manual cover the cover, but if one does not have creative thinking, then creating professional looking styles would be hard.  That is why, users like me really do not care if our documents look like everybody else's (just as long as they look professional).

Its kind of like learning Photoshop and knowing what each toolbar button does....but not knowing how to mix all the available tools create a professional looking graphic.

And of course, once we learn the tool, then making small changes here and there to make it look slightly different is no big deal.

Salman

Re: Best source of ConTeXt documentation?

[Paulo Ney de Souza]

    >From ntg-context-bounces@ntg.nl  Mon Aug  2 09:08:22 2004
    >From: Hans Hagen <pragma@wxs.nl>
    >To: mailing list for ConTeXt users <ntg-context@ntg.nl>
    >Subject: Re: [NTG-context] Best source of ConTeXt documentation?
    >Cc: 
    >
    >- it would take a lot of effort to keep such a source code repository up 
    >to date and in sync (else too many questions) with the pdf repositoty

If we are talking about examples, ones does not need to have the latest
manual and the latest source in sync. Just one copy of the manual (that
will eventually go old) and one copy of the source.

For example, the Calculator, mixing TeX and JavaScript

	http://www.tug.org/applications/pdftex/calculat.pdf

has NOT changed in many years now, so there is no problem maitaining the
PDF and the source in sync...

    >- we only publish documented sources

That is an important point ... and the only one I can give credit to, 
but I still think the abundance of examples, even without documentation,
is better than the short of examples.

    >- i want to stimulate users to writ etheir own styles not to mimick 
    >existing ones (i.e. avoid the 'all tex files look the same' problem)
	....
    >so ... there are no hidden tricks (unless it would bother/confuse 
    >users); and .. things like cover designs i wanna keep for myself if only 
    >to avoid cutting and pasting
    >Hans

Hans: Imitation is indeed the truest form of flattery!

Paulo Ney

Re: Best source of ConTeXt documentation?

[Hans Hagen]

Paulo Ney de Souza wrote:

>This is one of the sore points of ConTeXt and of the development
>  
>
i addition to patricks remarks:

- it would take a lot of effort to keep such a source code repository up 
to date and in sync (else too many questions) with the pdf repositoty
- we only publish documented sources
- i want to stimulate users to writ etheir own styles not to mimick 
existing ones (i.e. avoid the 'all tex files look the same' problem)
- also: most examples in manuals are typeset using

\startbuffer
...
\stopbuffer

\typebuffer \getbuffer

so ... there are no hidden tricks (unless it would bother/confuse 
users); and .. things like cover designs i wanna keep for myself if only 
to avoid cutting and pasting

in due time, probably more sources will go on line, but only when i have 
a system/method of keeping things in sync; i don't like the idea to go 
on-line for each change that i want to make (we only have dsl for half a 
year, before that i had to do all on 64 lines which is no fun)

Hans

Re: Best source of ConTeXt documentation?

[Patrick Gundlach]

Hello, 

> This is one of the sore points of ConTeXt and of the development
> effort. People at Pragma are willing to show off but not willing
> to share code and teach by example... contrary to most opensource
> projects I have seen.

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.

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. 

> Maybe it is time for us to start an group to reverse-engineer some
> of these files and post them into a public archive.

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.

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.


Paulo,

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

(btw: looking for some beta testers for a new service)

-- 
ConTeXt wiki: http://contextgarden.net
texshow-web:  http://texshow.contextgarden.net
List archive: http://archive.contextgarden.net

Re: Best source of ConTeXt documentation?

[Paulo Ney de Souza]

This is one of the sore points of ConTeXt and of the development
effort. People at Pragma are willing to show off but not willing
to share code and teach by example... contrary to most opensource
projects I have seen.

There is another gallery of examples without source for some pdfTeX
material at:

	http://www.tug.org/applications/pdftex/index.html

and as you can see there is a large intersection with the some of
the familiar developers at Pragma.

Maybe it is time for us to start an group to reverse-engineer some
of these files and post them into a public archive.

Paulo Ney de Souza

    >From ntg-context-bounces@ntg.nl  Sun Aug  1 19:55:39 2004
    >From: skhilji@tampabay.rr.com
    >Subject: Re: [NTG-context] Best source of ConTeXt documentation?
    >To: ntg-context@ntg.nl
    >
    >I'd like to see the sources of all the PDF files available at pragma-ade.  Its much easier to look at examples and learn from it than to ask for complete documentation.
    >
    >Salman
    >
    >
    >_______________________________________________
    >ntg-context mailing list
    >ntg-context@ntg.nl
    >http://www.ntg.nl/mailman/listinfo/ntg-context
    >

Re: Best source of ConTeXt documentation?

[skhilji]

I'd like to see the sources of all the PDF files available at pragma-ade.  Its much easier to look at examples and learn from it than to ask for complete documentation.

Salman