The PracTEX Journal

TPJ 2005 No 01, 2005–01–15

Rev. 2005–01–13

\starttext
Steve Peter

1 Introduction

Welcome to the first installment of the \starttext column. Together we’ll explore the
vast world that ConTEXt offers. If you don’t already have ConTEXt installed on your
system, head over to the Pragma website at [Link], and grab it. You
can get just ConTEXt, or a complete system with the underlying TEX distribution. If you
have no version of TEX whatsoever, you might find Doug Waud and Tim Null’s notes
on installing TEX to be useful.
Michael Guravage offers a good definition of what ConTEXt is (over in the Ask Nelly
section), so I’ll concentrate here on how to use ConTEXt. We’ll start out with a traditional
first document, and then we’ll have some fun tweaking it.
To get the most out of this column, you should have ConTEXt running on your
system, and you should type in the examples as we go. If you don’t have TEX, don’t
have a computer, 1 or are just curious about ConTEXt, and don’t want to take the plunge
yet, I’ve also supplied some illustrations.
Let’s get started!

2 Hello, World!
Since ConTEXt is a TEX macro package, we’ll follow the standard workflow by first
entering the text of our document into a plain text file, interspersed with commands
that tell TEX to do something with the text (like make it bold, or format it like a footnote).

1
Hey, then how are you reading this?

1
 Then we run TEX on the file, and finally we look at the beautiful output.
So fire up your favorite text editor 2 and enter the following:
\starttext

Hello, World! This is \ConTeXt.

\stoptext
The body of your document is enclosed in a \start—\stop pair. \starttext handles
various setup details for you. Save the file as [Link].
If you’ve used any variety of TEX before, the next step is slightly different, so watch out.
(And be amazed!) To run this document through TEX, we’ll use texexec, a perl script
that greatly simplifies life. More about that a bit later. For now, just type the following in
a shell window (if you’re not using one of the editing environments discussed above):
texexec document
You should now have a new file, [Link], in your directory. You can view the
file with xdvi on Unix, TEXniscope on Mac, or yap on Windows. You can convert the dvi
(DeVice Independent) file to pdf with the dvipdfm utility. However, your machine may
be configured to run pdfTEX automatically (as my machine is). In that case, simply open
the resulting [Link] file. Whether dvi or pdf, the result should look something
like this:
1 .5 C .5 M .5 Y .5 K C G Y R M B K 1

1.00 1.00

0.95 0.95
1
0.75 0.75

0.50
Hello, World! This is ConTEXt. 0.50

0.25 0.25

0.05 0.05

C R

1.00 1.00

Figure 1 (The top

0.95 of) your first
0.95

ConTEXt document!
0.75 0.75

0.50 0.50

0.25 0.25

0.05 0.05

M G

1.00 1.00

2
You can use any editor that outputs plain text, such as emacs, vi, Text Edit, or Notepad. Don’t use a
0.95 0.95

word processor like Word or OpenOffice Writer. There are also complete TEX editing environments like
0.75 0.75

TeXShop for Mac OS X or TEXnicCenter on Windows that allow you to edit your files, run TEX, and view
0.50 0.50

the output from within a single application.

0.25 0.25

0.05 0.05

Y B

1 1.00 0.95 0.90 0.85 0.80 0.75 0.70 0.60 0.50 0.40 0.30 0.20 0.10 0.00 1

2
 The page number at the top tells us that this is a default ConTEXt document, and not
simply a Plain TEX one. Let’s put the number into the footer.
Setting up something like the location of the page number is done with a \setup
command in ConTEXt. Don’t worry right now about the exact form of the command.
We’ll go over them in much greater detail in a later column. So, to put the number in
the footer, add the following line to the top of your document, before the \starttext.
Run it through texexec and look at the file produced.
\setuppagenumbering [location=footer]
Now the folio is in the footer, like in this article.
Text of any length is usually subdivided. Let’s put in some sections. This time after
\starttext, put the line
\section{First section}
Add a few more \sections and some text. 3 We’ll need them for the next section.

3 texexec
I mentioned before that texexec greatly simplifies life. Why is that? Well, typesetting
is a complicated business, and TEX frequently has to collect information on one pass to
use in a later pass. For example, let’s add a table of contents. Just after \starttext,
add
\completecontent
But how does TEX know what page \section two is on until after it has typeset
the document? The answer, of course, is that it doesn’t. TEX gathers up information
from all the \sections you have in the document and writes that information to an
auxiliary file. Normally, you have to then run TEX a second time so that TEX can read
that information in and set the table of contents. (And if the TOC is long, it will push
everything down, meaning that you have to rerun TEX again!)
Sometimes you find yourself rerunning TEX needlessly just to make certain there
aren’t any unresolved references. But texexec changes that. It automatically reruns
TEX as many times as necessary, so you can go refill your coffee.

3
To get a bunch of text quickly, try \dorecurse{20}{\input knuth \par}.

3
 4 Fun and fancy
Just to whet your appetite, let’s take a quick look at a couple of fancier things ConTEXt
can do. We’ll go into details in future columns, both here and in TUGboat. I realize these
are a bit of a jump from the basic formatting considered in the other sections, but since
we’re just setting out, I thought I’d give you a glimpse of some really fancy stuff.
To maintain high typographic standards, 4 you often have to align text, graphics,
etc., to a grid, and your text should maintain a consistent position on the baseline grid.
Add this to the top of your document and process it with texexec.
\setuplayout[width=middle,location=middle,grid=yes,marking=color]
\moveongrid[both]
\showgrid

1 .5 C .5 M .5 Y .5 K C G Y R M B K 1

1.00 1.00

0.95 0.95

0.75 0.75

0.50
\starttext 1
0.50
2

Steve Peter 3

0.25 4 0.25

6
0.05 0.05
7

1 Introduction 8
C R
9

Welcome to the first installment of the \starttext column. Together we’ll explore the 10

vast world that ConTEXt offers. If you don’t already have ConTEXt installed on your 11

1.00 1.00
system, head over to the Pragma website at [Link], and grab it. You 12

can get just ConTEXt, or a complete system with the underlying TEX distribution. If you 13

0.95 have no version of TEX whatsoever, you might find Doug Waud and Tim Null’s notes 14
0.95
on installing TEX to be useful. 15

Michael Guravage offers a good definition of what ConTEXt is (over in the Ask Nelly 16
0.75 0.75
section), so I’ll concentrate here on how to use ConTEXt. We’ll start out with a traditional 17

first document, and then we’ll have some fun tweaking it. 18

0.50 To get the most out of this column, you should have ConTEXt running on your 19 0.50

system, and you should type in the examples as we go. If you don’t have TEX, don’t 20

0.25 have a computer, 1 or are just curious about ConTEXt, and don’t want to take the plunge 21
0.25
yet, I’ve also supplied some illustrations. 22

Let’s get started! 23

0.05 24 0.05

25

26
M G

2 Hello, World! 27

28

1.00 Since ConTEXt is a TEX macro package, we’ll follow the standard workflow by first 29
1.00
entering the text of our document into a plain text file, interspersed with commands 30

that tell TEX to do something with the text (like make it bold, or format it like a footnote). 31

0.95 0.95
Then we run TEX on the file, and finally we look at the beautiful output. 32

So fire up your favorite text editor 2 and enter the following: 33

34
0.75 0.75
35

1
Hey, then how are you reading this? 36
0.50 2 0.50
You can use any editor that outputs plain text, such as emacs, vi, Text Edit, or Notepad. Don’t use a 37

word processor like Word or OpenOffice Writer. There are also complete TEX editing environments like
0.25 0.25

0.05 1 0.05

Y B

1 1.00 0.95 0.90 0.85 0.80 0.75 0.70 0.60 0.50 0.40 0.30 0.20 0.10 0.00 1

Figure 2 The matrix?

No, it’s the grid.

4
See the discussion, for example, in Robert Bringhurst, The Elements of Typographic Style.

4
 1
.5 C .5 M .5 Y .5 K C

1.00 If you’ve ever tried to do that with Plain TEX, or even LATEX, you know what a pain it
can be. However, ConTEXt does it easily, and even shows you where the grid is, so you
can debug troublesome documents.
After all TEX is, when you get down to it, a programming language. That means at

0.95 some point you’ll need to debug your documents. The grid feature is but one of several
nice visual debugging tools provided with ConTEXt. Add this to the beginning of your
document to gain a view of how TEX puts boxes and glue together.
\showmakeup
0.75
0.50
TEX
0.25
Figure 3 What TEX

0.05 might look like to TEX

Here we can see the bounding box for the E in TEX, along with the negative kerns, shown
as the thicker boxes near the base of the E. One more useful visualization command
shows you the layout on the page of your text block, margins, headers and footers. 5
C \showframe

1.005 Links
I hope you’ve enjoyed this first look at ConTEXt. There are numerous topics we haven’t
addressed yet, such as cross references, hyperlinks, indexes, figures and other graphics,
0.95 and ConTEXt’s incredible support for PDF trickery.

5
For more on this aspect of visual debugging, see Hans Hagen’s paper in TUGboat Volume 19, Number 3.

0.75
5

0.50
 There’s a lot of information out there, and there’s plenty to explore. Start with the
documentation on the Pragma website ([Link]). For examples, check
the ConTEXt wiki at [Link] and Bill McClain’s excellent beginner’s help
page. Last, but certainly not least, you can jump into the never-ending discussion on
the official mailing list at [Link]
Join us here and in the pages of TUGboat for more on the practical use of ConTEXt.

Steve Peter is president and typographer at Beech Stave Press, where he has the joy and frustration of
making multilingual text look good. Send him compliments at speter@[Link].