diff options
author | Taco Hoekwater <taco@elvenkind.com> | 2009-08-23 11:11:32 +0000 |
---|---|---|
committer | Taco Hoekwater <taco@elvenkind.com> | 2009-08-23 11:11:32 +0000 |
commit | 8fc3039c82d48605b5ca8b2eda3f4fdd755681e1 (patch) | |
tree | 3cd9bbdd599bc4d1ac0409e167fee2136e4c0ec9 /Master/texmf-dist/doc/context/manuals/reference/en/co-introduction.tex | |
parent | 850fc99b7cd3ae7a20065531fe866ff7bae642ec (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.tex | 668 |
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 + |