summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/context/manuals/reference/en/co-introduction.tex
diff options
context:
space:
mode:
authorTaco Hoekwater <taco@elvenkind.com>2009-08-23 11:11:32 +0000
committerTaco Hoekwater <taco@elvenkind.com>2009-08-23 11:11:32 +0000
commit8fc3039c82d48605b5ca8b2eda3f4fdd755681e1 (patch)
tree3cd9bbdd599bc4d1ac0409e167fee2136e4c0ec9 /Master/texmf-dist/doc/context/manuals/reference/en/co-introduction.tex
parent850fc99b7cd3ae7a20065531fe866ff7bae642ec (diff)
this is context 2009.08.19 17:10
git-svn-id: svn://tug.org/texlive/trunk@14827 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/context/manuals/reference/en/co-introduction.tex')
-rw-r--r--Master/texmf-dist/doc/context/manuals/reference/en/co-introduction.tex668
1 files changed, 668 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/context/manuals/reference/en/co-introduction.tex b/Master/texmf-dist/doc/context/manuals/reference/en/co-introduction.tex
new file mode 100644
index 00000000000..81d598a2e35
--- /dev/null
+++ b/Master/texmf-dist/doc/context/manuals/reference/en/co-introduction.tex
@@ -0,0 +1,668 @@
+% 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
+