how to install ConTEXt - Pragma ADE

how to install
ConT E Xt

1
Introduction
Nowadays most T E X users will use one of the many distributions that are available for
free or commercially. This means that much of the hard work of installation is already
taken care of. When installed properly, the user will quite certainly have the binaries,
hyphenation patterns, fonts and some macro packages on the system.
This manual is therefore not targeted at installing T E X, but focusses on how to get
ConT E Xt running within an existing distribution. When, after reading this text, you
still cannot get ConT E Xt working properly, we advice you to contact the maintainer
of your distribution, or to send your questions to the ConT E Xt mailing list.
Unpacking the archives
The ConT E Xt distribution consists of several zipped archives. You need to unpack
these to the appropriate directory of you file system. The archives are zipped using
the free zip program, and can be unzipped using its counterpart. 1 Just type:
unzip -a .zip
Everything you need to get started can be found in the main ConT E Xt archive:
cont-tmf.zip
the ConT E Xt sources and programs
There are some more archives, like the one with METAPOST tools and the still experimental
T E Xwork editing environment. We just mention them here, since you don’t
need them when you fetched the main archive.
cont-mpd.zip
cont-wrk.zip
a couple of METAPOST tools
the T E Xwork editing environment
There are two more somewhat redundant archives. These can be useful for users of
packages other than ConT E Xt. If you are using the files from cont-tmf.zip, it is not
necessary to include the files from these archives.
cont-ppc.zip
cont-uti.zip
the ppchT E X only files
the T E Xutil program
To prevent duplication in files, we strongly advise to obey the path as coded in the
archives. The files in these archives will be unpacked into the appropriate directories
Shareware programs like WinZip for MSWindows also work well.
1

2
of the official texmf tree. Some files are stored in the directories for generic T E X files
or the L A T E X package, but those are not important for ConT E Xt users.
texmf/tex/context/config
texmf/tex/context/base
texmf/tex/context/extra
texmf/tex/context/sample
texmf/tex/context/user
texmf/tex/context/third
texmf/metapost/context
texmf/context/config
texmf/context/data
texmf/context/perltk
texmf/doc/context/base
some configuration files
all ConT E Xt core files, modules
some goodies
a couple of sample files
user specific files
third party contributions
the METAPOST modules
some configuratiom files
data filed used by scripts
the Perl scripts
ConT E Xt documentation
Users can best not put files in the base, extra and sample directories. That way they
can conveniently be removed and reinstalled. The files in third are to be organized
by author. 2
On unix, the Perl scripts should be installed without the .pl extension, because
these scripts and possibly other programs rely on these names. They should be
moved to the search path for binaries and scripts. On MS Windows running scripts
is not supported by the operating system. In the perltk path you can find a zipped
file with the executable runperl.exe, written by Fabrice Popineau. When copied to
.exe, this program launches the script with the same name.
The initialization files for T E Xexec go into texmf/context (teT E X) or into the same
directory as the binaries. When setting up teT E X, make sure you enable generation of
the format files, by uncommenting the lines that specify the ConT E Xt formats. You
can edit the teT E X (and fpT E X) configuration file using:
fmtutil
In teT E X you should pass the switch --edit. When you pass --all you get all formats.
When in need for patterns other than the default ones, texconfig can be used to
enable more hyphenation patterns in the file cont-usr.tex. You can also edit this
file directly.
ConT E Xt comes with a font that contains navigational symbols. These fonts go to the
corresponding places in the fonts tree, in our case:
You need to create this (yet empty) directory yourself.
2

3
texmf/fonts/tfm/hoekwater/context
texmf/fonts/afm/hoekwater/context
texmf/fonts/type1/hoekwater/context
the files with suffix tfm
the files with suffix afm
the files with suffix pfb
There is also a ConT E Xt specific encoding/map file. This one is stored in the following
path:
texmf/dvips/config
ConT E Xt fontmap file
Don’t forget to add a reference to this file context.map to the pdftex.cfg file that
resides in the pdfT E X configuration directory.
map +context.map
Setting up T E XEXEC
T E Xexec is the command line interface to ConT E Xt.
running ConT E Xt in the traditional way, like
There is nothing wrong with
pdfetex
&cont-en filename
or for a web2c bases T E X
pdfetex
&cont-en --progname=context filename
but, and this will be more clear when we provide more options, the next call is more
convenient:
texexec
filename
This not only hides the implementation specific switches, but also removes the need
for specifying the format.
T E Xexec is written in Perl, a scripting language that is available on most leading
software platforms. In order to operate well, we need to set up T E Xexec. Of course
you must have Perl running on your system. On unix systems, this is always the
case, but for MS Windows you have to install Perl yourself. 3 .
First you have to move T E Xexec and its relative T E Xutil to a location in the binaries
path. When issuing the command texexec you should get some response. Even
better, when saying:
A good choice is the Active State distribution that you can fetch from www.activestate.com
3

4
texexec
--verbose
you should get some information on how T E Xexec is set up. When generating formats
and processing files fail, you need to set up the initialization file texexec.ini. This
file comes disguised as texexec.rme, so when not present, you need to copy this
file. The initialization file should be present in the config path, or in the same path
as the script. Next you need to edit this file. The simplest way is to comment and
uncomment one of the following lines:
set TeXShell to tetex
%set TeXShell to fptex
%set TeXShell to miktex
%set TeXShell to private
When this is done, you should check to what extent the rest of the variables in this
file match the local settings. We hope that the names of the variables used are clear.
When it is not set up properly, T E Xexec tries very hard to locate the files it needs.
Normally T E Xexec should start up rather quickly. When you are under the impression
that you are waiting too long, there is probably an error in the setup.
Using TET E X
When you are using teT E X or derived distributions, you can usually stick to the regular
updates, unless you want to use the latest version of ConT E Xt. In any event, you
should make sure that only one copy is present on your system, because otherwise
files can get mixed, due to the often aggressive file searching algorithms. If you want
to update anyway, you can unzip cont-tmf.zip from within the texmf directory and
regenerate the format files.
The ppchT E X only archive is for users who maintain their own files and only want to
install this package. The T E Xutil archive is for those who want to use this script, but
don’t want to install ConT E Xt. Neither archive is needed when you install ConT E Xt
from cont-tmf.zip.
Using FPT E X
The first step in installing ConT E Xt under fpT E X, is to unzip the file cont-tmf.zip
within the texmf directory. Afterwards the texexec binaries and Perl script should

5
be copied to the directories that contain the other T E X binaries. The T E X binaries path,
that should also be part of your PATH variable, often looks like:
../tex/bin/win32
When no file texexec.exe is found, you have to unzip texexec.zip and copy
runperl.exe to texexec.exe. Don’t forget to update the ls-R file database by
running mktexlsr.
Next you need to locate the file texmf/web2c/fmtutil.cnf. In this file, which contains
documentation, you need to activate the ConT E Xt formats. Now you can run:
texexec --make
When everything is installed properly, T E X generates one or more formats.
T E Xexec fails, you have to check the file texexec.ini.
When
Using MIKT E X
This section is provided by Grzegorz Sapijaszko and Ed L. Cashin and concerns the
installation of ConT E Xt under MikT E X. Installation in the MikT E X environment isn’t
much different from the teT E X installation. Nevertheless, you should take a few steps
to achieve good results. The first one is copying a texexec.rme file to texexec.ini
and uncommenting the lines for MikT E X as follows:
%set TeXShell to tetex
%set TeXShell to fptex
set TeXShell to miktex
%set TeXShell to private
In next step you should add a string \context\perltk to your environment variable
PATH (in autoexec.bat under Win9x, or in Control Panel in WinNT), for example:
PATH=c:\miktex\context\perltk;
If you are using languages other than Dutch, German or English, you should uncomment
the lines in the cont-usr.tex file for the hyphenation patterns of the languages
you need. After that you can refresh the filename databases, for example, by using
“Refresh Filename Databases” from the “Start Programs MikTeX Maintenance” menu
or “MikT E X Options” menu, depending on the version you run. You should also generate
a format file. This is described in the next section. Notice that you should have
Perl installed on your system.

6
After generating the formats you should copy the format file cont-xx.fmt from
\context\perltk to the directory where MikT E X is storing formats (usually
\localtexmf\miktex\fmt). Another way is to add a \context\perltk directory
to miktex.ini file:
[MiKTeX]
...
...
;; Where MiKTeX searches for .fmt files.
FMTPath=.;%R\miktex\fmt;C:\localtexmf\context\perltk//
As a convenience, you can copy the runperl.exe file from the cont-wrk.zip archive
to texexec.exe. You should make sure sure that those binaries are in the same
directory as the Perl scripts.
Generating formats
From its name you can deduce that ConT E Xt is written in the typographic language
T E X. ConT E Xt is parameter driven, which means that users change its behaviour by
setting variables and changing keys. ConT E Xt comes with a multi--lingual interface.
Currently there are three such interfaces: Dutch, English and German.
Users who want complete control can edit the file cont-usr.tex and generate a
format using the main file context.tex. Users who want an Dutch, English or German
format, can stick to the files named cont-nl, cont-en, and cont-de. Again, by editing
the file cont-usr.tex, you can influence the outcome.
In the early years of T E X, generating a format was common practice and users were
pretty well aware of format files, hyphenation patterns and fonts. Nowadays, disributions
take care of the more complicated issues, so users can comfortably skip many
nasty installation steps. To make life even more comfortable, ConT E Xt comes with
T E Xexec, a command line interface to T E X. When properly set up, this Perl script can
save you much time.
For instance, generating the three formats mentioned is accomplished by:
texexec --make en de nl
When T E Xexec is set up properly, this command should work. Before you read on,
you should try to generate at least the English and Dutch format. The Dutch format
is needed by some of the postprocessing features built into T E Xexec.

7
texexec --make en nl
Additionally, you need to make the MetaFun format. This is an extension to the standard
METAPOST format which offers not only more features, but also interfaces quite
well to ConT E Xt.
texexec
--make metafun
The formats associated with the interfaces default to the language of the interface.
This is all right for Dutch, English or German users, but Polish and Czech users are
worse off. For them a format file that defaults to their own language makes more
sense. Poles will like to say:
texexec --make --language=pl --bodyfont=plr en
while Czech people will go for:
texexec --make --language=cz --bodyfont=csr en
Both produce a format called cont-en with an English interface, but the first one
defaults to Polish hyphenation patterns and fonts, and the second one to Czech ones.
If wanted, you may pass a comma separated list of languages.
texexec --make --language=pl,it,uk --bodyfont=plr en
or, to generate a english interface format with Czech and Slovak patterns and Czech--
Slovak Computer Modern Roman fonts:
texexec --make --language=cz,sk,en --bodyfont=csr en
Unfortunately, the hyphenation patterns are of hard coded in a format file and cannot
be loaded at run time. When patterns are needed other than the ones loaded by
default, you can consider adapting the file cont-usr.tex. This file is loaded at
format generation time. When for instance Italian patterns are to be used, given that
these are available either in the file lang-it.pat, or in a file onto which this filename
is mapped, you should uncomment the line:
\installlanguage [\s!it] [\c!status=\v!start] % italian
The strange looking \s! and \c! things are needed in order to support multiple
interfaces. Don’t touch these!
When using web2c, in texmf.cnf some ConT E Xt specific memory settings take place.
When directly generating a format —i.e. when you’re not using the teT E X initialization
script or T E Xexec— you should supply the program name: -progname=context

8
Make sure you read the manual to T E Xexec. Apart from the normal processing of files,
there are quite a few useful options: mode dependant processing, output selection,
generating booklets, typesetting contact sheets of figures, manipulating pdf files, and
more.
Changing defaults
The somewhat more run--time specific settings, like certain special drivers, can be
added to cont-sys.tex. This file is loaded at run time. For instance, this file can can
contain the line:
\setupoutput[pdftex]
This commands tells ConT E Xt to produce pdf output by default. For Y&Y and Acrobat
support, you just say:
\setupoutput[dviwindo,acrobat]
Of course you can also load location specific layout settings in this file. The next few
lines tell ConT E Xt to default to the ConT E Xt navigational symbols, instead of the ones
composed from other glyphs.
\usesymbols [nav]
\setupsymbolset [navigation 1]
At Pragma ADE we want to process METAPOST files at run--time, so there we also have
entries like:
\recycleMPslotstrue
\runMPgraphicstrue
\runMPTEXgraphicstrue
\useMETAFUNformattrue
The first setting leads to less intermediate files. The next two settings let ConT E Xt
process the graphics real--time. For that you need to enable write18 in the T E X
configuration file (for web2c this is texmf.cnf). The last setting only makes sense if
you have also generated a MetaFun format. If you want to know more about MetaFun,
take a look at its manual.
The verbatim environments provide pretty printing. When you want even more fancy
verbatim, for instance with in--between switching of a language interpreter, you should

9
enable this feature. If you get no idea what we’re talking about here, leave this variable
untouched since tricky code is involved.
\newprettytrue
When ConT E Xt cannot determine the dimensions of an external figure, and no
texutil.tuf file is present, you can let ConT E Xt call T E Xutil directly. If you use
pdfT E X, you can leave this switch off.
\runutilityfiletrue
Morethan one instance of T E X a single path, can lead to clashes in temporary files. The
next switch enables a filename security feature:
\protectbufferstrue
For the moment, we use these low level boolean switches instead of more readable
commands.
An important section in this file are the font defaults. You can set a default font
encoding as well as enable map file loading for pdfT E X. Soem of these features are still
experimental.
The WEB2C configuration
Although not stricktly needed, ConT E Xt will operate more smoothly when these features
are set in the file texmf.cnf.
openout_any = a
shell_escape = t
allow_multiple_suffixes = f
The first line permits ConT E Xt to open parent paths that can hold common styles.
The second line enables enables users to embed METAPOST code in their document.
As a result, METAPOST is called automatically. 4 The last line makes sure that when
opening files like somefile.tuo, T E X will not try to open somefile.tuo.tex first.
When you embed T E X code in a METAPOST definition, using btex ... etex, the next
line will use T E Xexec to process that fragment in the case of using METAPOST directly.
You can disable this feature by running T E Xexec with the switch --automp.
4

10
MPXCOMMAND=texexec --mptex
Processing files
You can test you installation with the following file.
\starttext
\framed {Let’s see if it works.}
\stoptext
If ConT E Xt is set up properly, then the command
texexec
filename
will produce a file filename.dvi. Unless a file was already processed before, you
will notice that T E Xexec processes the file at least two times. During a T E X run,
ConT E Xt saves information in the files filename.tui: cross references, entries to
the table of contents, data needed for optimization, etc. If the run is succesful, this
file is converted to a file called filename.tuo and used in the next run. T E Xexec will
reprocess the file until the tuo file is unchanged.
We strongly recommend to use pdf-ε-T E X: Peter Breitenlohners ε-T E X permits ConT E Xt
to run more efficient, while Hàn Thê´ Thành’s pdfT E X provides pdf output and pdf-ε-T E X
combined both in one program. For those unfamiliar with ε-T E X: this is an extension
of T E X that is not only more efficient and in some aspects faster, but that also offers
a few features that come in handy when writing complicated code. For the moment,
ConT E Xt adapts its behaviour to the kind of T E X that is used, but future versions may
rely on ε-T E X or other descendants completely.
By default, ConT E Xt generates dvi output for dvips, unless the output is specified
otherwise. We already mentioned the \setupoutput command. A second way of
achieving this is:
texexec --pdf filename
And yet another way is adding a comment line in the document source, like:
% interface=en output=pdftex translate=cp1250pl
or
% interface=en output=pdftex translate=cp1250cz

11
Now we can omit the --pdf switch when we launch T E Xexec. Normally T E Xexec is able
to sort out the interface itself, but in case of troubles, you can set some defaults in the
file texexec.ini. The translate key is only needed when you use the reencoding--
on--the--fly feature of web2c.
Subscribing to the list
There are two dedicated mailing lists hosted by the ntg:
the ConT E Xt mailing list
the ppchT E X mailing list
These lists are so called majordomo ones, therefore you should send a subscription
command to:
majordomo@ntg.nl
Just send a message to this address with the body text:
subscribe ntg-context
Of course you can also directly contact the authors at:
Pragma ADE: pragma@wxs.nl

PRAGMA
Advanced Document Engineering Ridderstraat 27 8061GH Hasselt NL
tel: +31 (0)38 477 53 69 email: pragma@wxs.nl internet: www.pragma-ade.com