% interface=en

\startcomponent co-introduction

\environment contextref-env
\product contextref


\MPinclusions
  {color gray;
   gray := (.95,.95,.95);}

\def\MPcircle#1#2#3#4#5%
  {\startuseMPgraphic{circle}
     path p;
     p := fullcircle xscaled #1\space yscaled #2;
     pickup pencircle scaled #3;
     fill p withcolor \MPcolor{#5};
     draw p withcolor \MPcolor{#4};
   \stopuseMPgraphic
   \useMPgraphic{circle}}

\defineoverlay
  [MPcircleA]
  [\MPcircle{\overlaywidth}{\overlayheight}{2pt}{FrameColor}{GrayColor}]

\startbuffer[fig-cont]

\unprotect

\setupframed[\c!background=MPcircleA,\c!frame=\v!off,\c!offset=\v!none]

\framed
  [\c!width=6cm,\c!height=5cm]
  {\vfil \ConTeXt \vfil \vfil
   \leavevmode\framed[\c!width=.5\hsize,\c!height=.3\hsize]
     {\vfil \TeX \vfil }
   \vfil\vfil}

\protect

\stopbuffer


\chapter{Introduction}

\section{\TEX}
\index[tex]{\TEX}
\index{Knuth}

\TEX\ was developed at Stanford University during the
seventies. The designer, developer and spiritual father of
\TEX\ is Donald E. Knuth. Knuth developed \TEX\ to typeset
his own publications and to give an example of a
systematically developed and annotated program.

The \TEX\ project was supported by the American Mathematical
Society and resulted in the programming language and program
\TEX, the programming language and program \METAFONT, the
Computer Modern typefaces and a number of tools and
publications.

\TEX\ is used worldwide, supports many languages, runs on
almost every platform and is stable since 1982, which is
rather unique in today's information technology.

\TEX\ is a batch||oriented typesetting system. This means
that the complete text is processed from beginning to end
during which typesetting commands are interpreted. Because
you tell your typesetting intentions to \TEX, the system can
also be qualified as an intentional typesetting system.

\fixme{Next paragraph is messy, and introduces \CONTEXT\ prematurely}

In most documents one can stick to commands that define the
structure and leave the typographic details to \CONTEXT. One
can concentrate on the content, instead of on makeup; the
author can concentrate on his reader and his intentions with
the text. In this respect one can classify \CONTEXT\ as an
intentional system. We prefer such a system over a
page||oriented system, especially in situations where you
have to process bulky documents of with regularly changing
content. Furthermore an intentional typesetting system is
rather flexible and makes it possible to change layout
properties depending on its application. It can also
cooperate quite well with other text||processing programs
and tools.

\section[context]{\CONTEXT}
\index[context]{\CONTEXT}

The development of \CONTEXT\ started in 1990. A number
of \TEX\ based macro packages had been used to our
satisfaction. However, the non||technical users at our
company were not accustomed to rather complex and non||Dutch
interfaces. For this reason we initiated the development of
\CONTEXT\ with a parameter driven interface and commands
that are easy to understand. Initially the user interface
was only available in Dutch.

The functionality of \CONTEXT\ was developed during the
production of many complex educational
materials, workplace manuals and handbooks. In 1994 the
package was stable enough to warrant a Dutch user manual.
Over the years many new features and 
a multi-lingual interface have been added (currently 
English, German, \unknown\ interfaces are supported).
Though \CONTEXT\ is as (un|)|stable as any other
macro package there are still a great number of wishes. These
will be implemented in the spirit of the existing \CONTEXT\
commands.

\starthiding
\CONTEXT\ comes with a number of \PERL\ scripts, like
\TEXUTIL\ and \TEXEXEC. Also a number of modules are
available, like \PPCHTEX\ for typesetting chemical
structures.
\stophiding

\todo{Add some text about recent developments, especially the split between mkii and mkiv}

\section{Commands}
\index{commands}
\index{macros}
\index{brackets}

A \CONTEXT\ document is normally coded in \UTF\ or another plain text encoding like ISO~Latin1. Inside such a file,
the actual document text is interspersed with \CONTEXT\ commands.
These commands tell the system how the text should be
typeset. A \CONTEXT\ command begins with a backslash 
(\type {\}). An example of a command is \type {\italic}. Most
of the time a command does something with the text that
comes after the command. The text after the command \type
{\italic} will be typeset {\italic text it italic}.

When you use a command like \type{\italic} you acting as a  typesetter,
and when you are writing paragraphs you are acting as an author.
Typesetting and writing are conflicting activities; as an
author you would probably rather spend as little time as possible
typesetting. When you are actually writing text and you have 
to indicate that something special has to happen with the text, 
it is therefore best to use generic commands than specific typesetting commands. 
An example of such a generic command is \type{\em} ({\em emphasis}). 
By using \type{\em} instead of \type{\italic}, you enable the typesetter 
(who could also be you) to change the typeset result without him or her having to alter the text.

{\setupcaption[figure][width=fit]
\placefigure[right][fig:cohesion tex]
  {}{\getbuffer[fig-cont]}}


A \TEX\ user normally speaks of macros instead of commands.
A macro is a (normally small) program. Although this manual uses
both \quote {command} and \quote {macro},  we will try
consistently use the word command for users and macro for
programmers. A collection of macros is called a macro package. 

A command is often followed by setups and / or 
argument text. Setups are placed between brackets (\type{[]},
there may be more than one sets of those).  The scope or range
of the command (the text acted upon) is placed between curly
brackets (\type{{}}, there may be more than one of those as well). 

An example of a command with setups and an argument text is

\startbuffer
\framed[width=3cm,height=1cm]{that's it}
\stopbuffer

\typebuffer

When this input is processed by \CONTEXT, the result will look like this:

\startbaselinecorrection
\getbuffer
\stopbaselinecorrection

Setups in \CONTEXT\ come in two possible formats. First, 
there can be a list of comma-separated key||value pairs 
like we saw already

\startbuffer
\setupsomething [variable=value, variable=value, ...]
\stopbuffer

\typebuffer

Second, there can be a comma-separated list of just values

\startbuffer
\setupsomething [option, option,...]
\stopbuffer

\typebuffer

In both cases the setups are placed between \type{[]}.  Spaces, tabs and  even a newline between the command and the opening \type{[} or after any of the separation commas are ignored. But multiple newlines are disallowed, and whitespace before commas, around the equals sign and before the closing~\type{]} is significant. 

Some practical examples of correct command invocations are:

\startbuffer
\setupwhitespace [big]
\setupitemize  [packed, columns]
\setuplayout   [backspace=4cm,
                topspace=2.5cm]
\stopbuffer

\typebuffer

Many typographical operations are performed on a text that
is enclosed within a \type{start-stop} construction:

\startbuffer
\startsomething
.............................
\stopsomething
\stopbuffer

\typebuffer

And often keywords or key||value pairs can be passed, that inform
\CONTEXT\ of the users wishes like

\startbuffer
\startnarrower[2*left,right]
.............................
\stopnarrower
\stopbuffer
\typebuffer

or

\startbuffer
\startitemize[n,broad,packed]
\item .......................
\item .......................
\stopitemize
\stopbuffer
\typebuffer

The simplest \CONTEXT\ document is

\startbuffer
\starttext
Hello World!
\stoptext
\stopbuffer

\typebuffer

\section {Running \CONTEXT}

\todo{Explain basic use of \type{texexec} and \type{context} here, maybe from a text editor or environment like texworks. }

\section{Advanced commands}

There are also commands that are used to define new commands.
For example:

\startbuffer
\definesomething[name]
\stopbuffer

\typebuffer

Sometimes a definition inherits its characteristics from
another (existing) one. In those situations a definition
looks like:

\startbuffer
\definesomething[clone][original]
\stopbuffer

\typebuffer

In many cases one can also pass settings to these commands.
In that case a definition looks like:

\startbuffer
\definesomething[name][variable=value,...]
\stopbuffer

\typebuffer

These setups can also be defined in a later stage with:

\startbuffer
\setupsomething[name][variable=value,...]
\stopbuffer

\typebuffer

An example of such a name coupled definition and setup is:

\startbuffer
\definehead[section][chapter]
\setuphead[section][textstyle=bold]
\stopbuffer

\typebuffer

The alternatives shown above are the most common appearances
of the commands. But there are exceptions:

\startbuffer
\defineenumeration[Question][location=inmargin]
\useexternalfigure[Logo][FIG-0001][width=4cm]
\definehead[Procedure][section]
\setuphead[Procedure][textstyle=slanted]
\stopbuffer

\typebuffer

After the first command the newly defined command \type
{\Question} is available which we can use for numbered
questions and to place numbers in the margin. With the
second command we define a picture that is scaled to a \type
{width} of 4cm. After the third command a new command \type
{\procedure} is available that inherits its characteristics
from the predefined command \type {\section}. The last
command alters the characteristics of the newly defined
head. Later we will discuss these commands in more detail.


We use \type{begin-end} constructions to mark textblocks.
Marked textblocks can be typeset, hidden, replaced or
called up at other locations in the document.

\startbuffer
\beginsomething
.............................
\endsomething
\stopbuffer

\typebuffer

These commands enable the author to type questions and
answers in one location and place them at another location
in the document. Answers could be placed at the end of a
chapter with:

\startbuffer
\defineblock[Answer]
\setupblock[Answer][bodyfont=small]
\hideblocks[Answer]
.............................
\chapter{........}
.............................
\beginofAnswer
.............................
\endofAnswer
.............................
\stopbuffer

\typebuffer

In this case answers will be typeset in a smaller bodyfont
size, but only when asked for. They are hidden by default,
but stored in such a way, that they can later be typeset.

Commands come in many formats. Take for example:

\startbuffer
\placefigure
  [left]
  [fig:logo]
  {This is an example of a logo.}
  {\externalfigure[Logo]}
\stopbuffer

\typebuffer

This command places a picture at the left hand side of a
text while the text flows around the picture. The picture
has a reference \type {fig:logo}, i.e. a logical name. The
third argument contains the title and the fourth calls the
picture. In this case the picture is a figure defined
earlier as \type {Logo}. \in {Figure} [fig:cohesion tex] is
typeset this way.

The last example has arguments between optional brackets
(\type{[]}). Many commands have optional arguments. In case
these optional arguments are left out the default values
become operative.

You may have noticed that a spacy layout of your \ASCII\
text is allowed. In our opinion, this increases readability
considerably, but you may of course decide to format your
document otherwise. When the \CONTEXT\ commands in this
manual are discussed they are displayed in the following
way:

\showsetup{setupfootertexts}

The command \type{\setupfootertexts}, which we will discuss
in detail in a later chapter, has three arguments of which
the first is optional. The first argument defaults to
\type{[text]}. Optional arguments are displayed with the word
 {\ttxx OPTIONAL} below the brackets. Default values are
\underbar{underlined} and placeholders (as opposed to literal
keywords) are typeset in {\ttx UPPERCASE}. In this example {\ttx TEXT}
means that you can provide any footer text. \CONTEXT\ is able to keep
track of the status of information on the page, for instance the name of the
current chapter. We call this kind of information {\ttx
MARK}, so the command \type {\setupfootertexts} accepts
references to marks, like those belonging to sectioning
commands: \type{chapter}, \type{section}, etc. The argument
\type{date} results in the current system date.

When the setup of some commands are displayed you will
notice a $\blacktriangleleft \blacktriangleright$ in the
right hand top corner of the frame. This indicates that this
command has a special meaning in interactive or screen
documents. Commands for the interactive mode only show solid
arrows, commands with an additional functionality show
gray arrows.

\section{Programs}
\index[texutil]{\TEXUTIL}
\index[texexec]{\TEXEXEC}

\TEX\ does a lot of text manipulations during document
processing. However, some manipulations are carried out by
\TEXUTIL. This program helps \TEX\ to produce registers,
lists, tables of contents, tables of formulas, pictures etc.
This program is a \PERL\ script.

Document processing can best be done with \TEXEXEC. This
\PERL\ script enables the user to use different processing
modes and to produce different output formats. It also keeps
track of changes and processes the files as many times as
needed to get the references and lists right.

\section{Files}
\index{files}
\index{extensions}
\index[ascii]{\ASCII}
\index[table]{\TABLE}

\TEX\ is used with \ASCII\ source files. \ASCII\ is an
international standardized computer alphabet. The \ASCII\
file with the prescribed extension \type{tex} is processed
by \TEX. During this process \TEX\ produces a file with
graphical commands. This file has the extension \type{dvi}.
A machine||specific driver transforms this file into a
format that is accepted by photosetters and printers.
Usually, \POSTSCRIPT\ drivers are used to produce
\POSTSCRIPT\ files.

\CONTEXT\ relies on plain \TEX. Plain \TEX, \CONTEXT\ and a
third package \TABLE\ are brought together in a so called
format file. \TABLE\ is a powerful package for typesetting
tables. A format file can be recognized by its suffix
\type{fmt}. \TEX\ can load format files rather fast and
efficiently.

A \type{dvi} file can be viewed on screen with a dedicated
program. For electronic distribution \POSTSCRIPT\ files can
be transformed (distilled) into Portable Document Format
(\PDF) files. \PDF\ files are of high graphical quality and
are also interactive (hyperlinked). \CONTEXT\ fully supports
\PDFTEX, which means that you can generate \PDF\ output
directly.

\section{Texts}

\subsection{Characters}
\index{characters}

A \TEX\ text contains \ASCII\ characters. Higher \ASCII\
values to produce characters like \"e, \^o and \~n can also
be used in this version of \TEX. Some characters in \TEX\
have a special meaning. These characters can be typeset by
putting a \type {\} in front of it. A \% is obtained by
typing \type {\%}. If one would type only a \type {%} the
result would be undesirable because \TEX\ interprets text
after a \% as comment that should not be processed. A \$ is
produced by \type {\$}. A \type {$} without a \type {\}
indicates the beginning of the mathemathical mode.

\subsection{Paragraphs}
\index{paragraphs}

\TEX\ performs its operations mostly upon the text element
{\em paragraph}. A paragraph is ended by \type{\par} or
preferably by an empty line. Empty lines in an \ASCII\ text
are preferred because of readability.

\subsection{Boxes}
\index{boxes}

In this manual we will sometimes talk about boxes. Boxes are
the building blocks of \TEX. \TEX\ builds a page in
horizontal and vertical boxes. Every {\handletokens
character\with \ruledhbox} is a box, a \ruledhbox
{\handletokens word\with \ruledhbox} is also a box
{\handletokens built\with \ruledhbox} out of a number of
boxes, a line is \unknown

When \TEX\ is processing a document many messages may occur
on the screen. Some of these messages relate to overfull or
underful boxes. Horizontal and vertical boxes can be typeset
by the \TEX\ commands \type{\hbox} and \type{\vbox}.
Displacements can be achieved by using \type {\hskip} and
\type {\vskip}. It does not hurt to know a bit about the
basics of \TEX, because that way one can far more easilly
write his or her own alternatives to, for instance, chapter
headers.

\subsection{Fonts}
\index{fonts}

\TEX\ is one of the few typesetting systems that does math
typesetting right. To do so \TEX\ needs a complete
fontfamily. This means not only the characters and numbers
but also the mathematical symbols. Complete fontfamilies are
Computer Modern Roman and Lucida Bright. Both come in serif
and sans serif characters and a monospaced character is also
available. Other fontfamilies are available.

\subsection{Dimensions}
\index{dimensions}
\index{\type{pt}}
\index{\type{ex}}
\index{\type{em}}
\index{\type{cm}}

Characters have dimensions. Spacing between words and lines
have dimensions. These dimensions are related to one of the
units of \in{table}[tab:dimensions]. For example the
linespacing in this document is \the\baselineskip.

\placetable[here][tab:dimensions]{Dimensions in \TEX.}
\starttable[|c|l|l|]
\HL
\VL \bf dimension  \VL \bf meaning \VL \bf equivalent   \VL \SR
\HL
\VL \type{pt} \VL point         \VL $\rm 72.27pt=1in$   \VL \FR
\VL \type{pc} \VL pica          \VL $\rm 1pc=12pt$      \VL \MR
\VL \type{in} \VL inch          \VL $\rm 1in=2.54cm$    \VL \MR
\VL \type{bp} \VL big point     \VL $\rm 72bp=1in$      \VL \MR
\VL \type{cm} \VL centimeter    \VL $\rm 2.54cm=1in$    \VL \MR
\VL \type{mm} \VL millimeter    \VL $\rm 10mm=1cm$      \VL \MR
\VL \type{dd} \VL didot point   \VL $\rm 1157dd=1238pt$ \VL \MR
\VL \type{cc} \VL cicero        \VL $\rm 1cc=12dd$      \VL \MR
\VL \type{sp} \VL scaled point  \VL $\rm 65536sp=1pt$   \VL \LR
\HL
\stoptable

We will often specify layout dimensions in points or
centimeters or milimeters. A point is about $\rm.35 mm$.
Most dimensions are rather American. The European Didot
point is equivalent to $\rm 1/2660 m = 3.759398496 mm$.

Next to the mentioned dimension \TEX\ also uses \type{em}
and \type{ex}. Both are font dependant. An \type {ex} has
the height of an x, and an \type{em} the width of an M. In
the Computer Modern Roman typefaces, numbers have a width of
$1/2$em, while a --- (\type{---}) is one em.

\subsection{Error messages}
\index{error messages}
\index{stopping}

While processing a document, \TEX\ generates status messages
(what is \TEX\ doing), warning messages (what could \TEX\ do
better) and error messages (what considers \TEX\ wrong). An
error message is always followed by a \type{halt} and
processing will be stopped. A linenumber and a \type{?} will
appear on screen. At the commandline you can type \type{H}
for help and the available commands will be displayed.

Some fatal errors will lead to an * on the screen. \TEX\ is
expecting a filename and you have to quit processing. You
can type \type{stop} or \type{exit} and if that doesn't work
you can always try \type{ctrl-z} or \type{ctrl-c}.

\section{Version numbers}
\index[TeX+version]{\TEX+version}
\index[ETeX]{\ETEX}
\index[NTS]{\NTS}
\index[PDFTEX]{\PDFTEX}

\TEX\ was frozen in 1982. This meant that no functionality
would be added from that time on. However, exceptions were
made for the processing of multi||language documents, the
use of 8-bits \ASCII||values and composed characters.
Additionally some bugs were corrected. At this moment \TEX\
version 3.141592 is being used. The final \TEX\ version
number will be~$\pi$, while \METAFONT\ will become the Euler
number~$e$.

\CONTEXT\ can handle both \ETEX\ and \PDFTEX, which are
extensions to \TEX. Both are still under development, so we
suggest using the latest versions available. This manual is
typeset using \ifx \eTeXversion \undefined \else \PDFETEX,
with \ETEX\ version \the \eTeXversion \eTeXrevision\ and
\fi \PDFTEX\ version \the \pdftexversion \pdftexrevision.

\CONTEXT\ is still under development. Macros are continually
improved in terms of functionality and processing speed.
Improvements are made within existing macros. For example
the possibility to produce highly interactive \PDF\
documents has altered some low||level functionality of
\CONTEXT\ but did not alter the interface. We hope that in
due time \CONTEXT\ will be a reasonable complete document
processing system, and we hope this manual shows enough of
its possibilities. This document was processed with version
\contextversion.

\section{Top ten}

A novice user might be shooed away by the number of
\CONTEXT\ commands. Satisfying results can be obtained by
only using the next ten groups of commands:

\startitemize[n,packed,broad]
\item  \type {\starttext},
       \type {\stoptext}
\item  \type {\chapter},
       \type {\section},
       \type {\title},
       \type {\subject},
       \type {\setuphead},
       \type {\completecontent}
\item  \type {\em},
       \type {\bf},
       \type {\cap}
\item  \type {\startitemize},
       \type {\stopitemize},
       \type {\item},
       \type {\head}
\item  \type {\abbreviation},
       \type {\infull},
       \type {\completelistofabbreviations}
\item  \type {\placefigure},
       \type {\externalfigure},
       \type {\useexternalfigures}
\item  \type {\placetable},
       \type {\starttable},
       \type {\stoptable}
\item  \type {\definedescription},
       \type {\defineenumeration}
\item  \type {\index},
       \type {\completeindex}
\item  \type {\setuplayout},
       \type {\setupfootertexts},
       \type {\setupheadertexts}
\stopitemize

\section{Warning}

\CONTEXT\ users can define their own commands. These newly
defined commands may conflict with plain \TEX\ or \CONTEXT\
commands. Therefore it is advisable to use capital characters
in your own command definitions.

\startexample
\starttyping
\def\MyChapter#1%
  {\chapter{#1}\index{#1}}
\stoptyping
\stopexample

This command starts a new chapter and defines an index entry
with the same name.

\stopcomponent

