# ConTeXt and pdfTeX Beginners Help Page

Best Viewed With Any Browser

Last updated: July 28, 2003

## Introduction

I am a beginner at TeX myself, and wanted to use this page to record those little hints and examples which helped me over the rough spots, in the hope that they may help others. I'll refine and extend the examples as I gain more experience.

The techniques I describe here are used to produce all of the Sattre Press titles.

I presume the reader has all the documents available from the ConTeXt and pdfTeX web pages. Other sources of information: both packages have email support lists which are archived on the web. Searching the usenet group comp.text.tex can be useful also.

Here is an easy way to fetch a copy of all the ConTeXt online documents. Fetch this file:

You may want to edit it to remove lines refering to languages and documents you know you don't want. Then, this will fetch copies of the documents into the current directory:
wget -Nxi context.www

I use SuSE Linux and TeXLive. However, it seems that TeX knowledge is rather portable across systems, and it should be possible to adapt the examples to other platforms.

• ConTeXt
• pdfTeX
• TUG and TeXLive

## File Locations

Everything in the TeX world has its place. There is a vast amount of material in the TeX directory tree, which on my system starts at /usr/TeX/.

Further, you can customize local and auxiliary directory structures. Look at texmf.cnf.

Experiment with the kpsewhich utility, particularly with the --show-path option, which shows all the different places in which TeX will look for different files.

Using this, I see that the current directory is always first in the path, meaning I can make all sorts of "system" changes which effect only the current project. As far as I can tell, all files of interest are treated this way: .cfg, .cnf, .tex, .map, .tfm, .pfb, etc.

Once a new file becomes stable it can be promoted to later ("higher") directories in the search path. kpsewhich shows that I have a personal TeX directory tree in my home directory: /home/wmcclain/texmf. Then there are site-specific directories, etc.

Remember: if you add or delete any files in the TeX tree (see the list of directories $TEXMFDBS in texmf.cnf), you must rebuild the filename database with mktexlsr. On my system, texhash is a synonym for this command. On Linux, I run updatedb daily, and use locate to find all those pesky configuration files. ## Installation Originally I used the TeX distribution that came with SuSE Linux, but have since switched to the TeXLive distribution. My original installation notes for SuSE are available here. ### TeXLive TeXLive CDs are available to TUG members and can also been downloaded (by anyone) as ISO images from the TUG site shown above. I follow the instructions given on the disk, using the default directory structure which has /usr/TeX/ as the top level: su root export CDPATH= # this causes problems if set mount /cdrom cd /cdrom sh install-cd.sh (select packages and languages) (run "Install") export PATH=$PATH:/usr/TeX/bin/i386-linux
export TEXMFCNF=/usr/TeX/texmf/web2c/
texhash
exit # from su

Then I edit the .bashrc in my home directory and add these lines:
export PATH=$PATH:/usr/TeX/bin/i386-linux export TEXMFCNF=/usr/TeX/texmf/web2c/ export MANPATH=$MANPATH:/usr/TeX/man
export INFOPATH=$INFOPATH:/usr/TeX/info The last two lines are omitted from the TeXLive instructions. ### ConTeXt ConTeXt is under rapid development and we need to install updated versions from time to time. The zipped archives are available from the Pragma site listed above. Here is how I install new versions: su root mv cont-tmf.zip /usr/TeX/texmf cd /usr/TeX/texmf rm tex/context/base/* # safer to clean out old files first rm metapost/context/base/* # ...also remove metafun files rm metapost/context/*.mp # ...and any from an obsolete version unzip -a -L -o cont-tmf.zip # overwrites existing files # Edit texexec.ini afterwards? cp context/config/texexec.rme context/config/texexec.ini # Edit cont-sys.tex afterwards? Specifically: uncomment the line: # # \autoloadmapfilestrue # # For Metapost use, make sure these lines are uncommented: # # \runMPgraphicstrue # \runMPTEXgraphicstrue # \useMETAFUNformattrue cp tex/context/user/cont-sys.rme tex/context/user/cont-sys.tex # # Edit /usr/TeX/texmf/web2c/texmf.cnf and ensure that "shell_escape = t". This # is what TeX people somewhat obscurely call "write18 enabled". # export PATH=$PATH:/usr/TeX/bin/i386-linux # root doesn't have this on my system

texhash
texexec --make en  # en = english
texexec --make --alone metafun
mv metafun.mem /usr/TeX/texmf-var/web2c/metafun.mem
texhash

exit # from "su root"

## Using TeXLive fonts

TeXLive comes with a number of Type1 fonts. This section shows how to reference them from ConTeXt.

### Predefined fonts

Font Declaration Notes
"Bluesky" Computer Modern This is the default when no font declarations are used.
"CM-Super" Computer Modern \usetypescript[modern][ec]
\setupbodyfont[modern]
Palatino \usetypescript[berry][ec] % or [8r]
\usetypescript[palatino][ec] %
\setupbodyfont[palatino]
This is actually URW Palladio, a copy of Hermann Zapf's Palatino.
Times, Helvetica and Courier \usetypescript[berry][ec] % or [8r]
\setupbodyfont[pos]
These are all from the URW Nimbus package. Times is the default serif face, \ss produces Helvetica, and \tt produces Courier.
Bookman \usetypescript[berry][ec] % or [8r]
\definetypeface[bookman][rm][serif][bookman][default][encoding=ec]
\setupbodyfont[bookman]
URW Bookman
Charter \usetypescript[berry][ec] % or [8r]
\definetypeface[charter][rm][serif][charter][default][encoding=ec]
\setupbodyfont[charter]
Bitstream Charter
Utopia \usetypescript[berry][ec]
\definetypeface[utopia][rm][serif][utopia][default][encoding=ec]
\setupbodyfont[utopia]
Because of a bug in TeXLive 7, the tfm and vf files for Adobe Utopia are not installed correctly. To fix this:

cd ~/texmf
wget http://www.gutenberg.eu.org/pub/gut/distribs/texlive/7/utopia.tar.gz
tar zxvf utopia.tar.gz
texhash

## Selecting Fonts

Fonts are a complicated business, but become easier to deal with once you have run a few experiments. The primary document is Fonts in ConTeXt (mfonts.pdf).

Note that we tend to be spoiled by the default Computer Modern font which has a large number of good features which just work automatically. Emulating that capability with a new font requires a good deal of setup.

### Simple (and not very useful) method

You can simply specify a font file and use it, either in plain TeX or by using ConTeXt macros. This is not very useful because it does not give you the convenient switching to italic, bold, small caps, math mode, etc, which a well-defined typeface will do. However, it is instructive to try it, just to prove that the system is setup correctly and that the maps and font files can be found.

You can (for a start) use any font listed in pdftex.map, presuming both the .tfm and .pfb font files exist. (This is not always the case on my system).

For example, here is the first data line in my pdftex.map file:

bchb8r CharterBT-Bold "TeXBase1Encoding ReEncodeFont" <8r.enc <bchb8a.pfb
The contents of pdftex.map are documented in The pdfTeX User Manual (pdftexman.pdf). For now, just note that this line refers to "Bitstream Charter Bold." The first field, bchb8r, is the name of a .tfm (TeX Font Metric) file, and bchb8a.pfb is a Type1 font file. In TeX programs, fonts are identified by their .tfm names.

Since both bchb8r.tfm and bchb8a.pfb exist on my system, I can use the font as follows.

Using just plain TeX:

\font\myfirstfont=bchb8r
\myfirstfont Of wind I sang, a wind there came, and in the branches blew.

Using ConTeXt macros:

\definefontsynonym[CharterBT-Bold][bchb8r][encoding=8r]
\definefont[MySecondFont][CharterBT-Bold]
\starttext
\MySecondFont I sang of leaves, of leaves of gold, and leaves of gold there grew.
\stoptext

### Using Typescripts

ConTeXt now uses typescripts to define and select fonts. This is the way to go for maximum flexibility.

"Typescripts are in fact just organized definitions" says mfonts.pdf. They are a way of building a database of names which provides layers of abstraction. The TeX document can be written so that it will continue to be "correct" even as major changes in fonts, families and styles are made at the deeper levels.

#### typescript files

Typescripts are definitions contained between \starttypescript and \stoptypescript. The typescripts are found in and loaded from several file sources:
• Several type-*.tex files are automatically searched. See the list in mfonts.pdf.
• A file type-loc.tex in the search path will be searched automatically.
• Any file in the search path, for example, myscripts.tex, can be loaded with \usetypescriptfile[myscripts].

#### A simple example

For example, using Bitstream Charter again, I have these fonts on my system:
 bchr8r roman bchb8r bold bchri8r italic bchbi8r bold italic
I can create this typescript file, type-charter.tex:

\starttypescript [serif] [charter] [8r]
\definefontsynonym [Charter-Roman]       [bchr8r]  [encoding=8r]
\definefontsynonym [Charter-Bold]        [bchb8r]  [encoding=8r]
\definefontsynonym [Charter-Italic]      [bchri8r] [encoding=8r]
\definefontsynonym [Charter-Bold-Italic] [bchbi8r] [encoding=8r]
\stoptypescript

\starttypescript [serif] [charter] [name]
\usetypescript[serif][fallback]
\definefontsynonym [Serif]           [Charter-Roman]
\definefontsynonym [SerifBold]       [Charter-Bold]
\definefontsynonym [SerifItalic]     [Charter-Italic]
\definefontsynonym [SerifBoldItalic] [Charter-Bold-Italic]
\stoptypescript

\starttypescript [Charter]
\definetypeface [MyCharter] [rm] [serif] [charter] [default] [encoding=8r]
\stoptypescript

And use it like this:
\usetypescriptfile[type-charter]
\usetypescript[Charter]
\setupbodyfont[MyCharter]

\starttext
This is roman, {\bf bold}, {\it italic}, {\bi bold-italic},
{\tfa bigger} and {\tfx smaller}.
\stoptext

#### Multiple fonts

I also have Adobe Utopia, so I can make a type-utopia.tex typescript file very similar to the Charter example above:

\starttypescript [serif] [utopia] [8r]
\usetypescript[serif][fallback]
\definefontsynonym [Utopia-Roman]       [putr8r]  [encoding=8r]
\definefontsynonym [Utopia-Bold]        [putb8r]  [encoding=8r]
\definefontsynonym [Utopia-Italic]      [putri8r] [encoding=8r]
\definefontsynonym [Utopia-Bold-Italic] [putbi8r] [encoding=8r]
\stoptypescript

\starttypescript [serif] [utopia] [name]
\definefontsynonym [Serif]           [Utopia-Roman]
\definefontsynonym [SerifBold]       [Utopia-Bold]
\definefontsynonym [SerifItalic]     [Utopia-Italic]
\definefontsynonym [SerifBoldItalic] [Utopia-Bold-Italic]
\stoptypescript

\starttypescript [Utopia]
\definetypeface [MyUtopia] [rm] [serif] [utopia] [default] [encoding=8r]
\stoptypescript

And then use both fonts in the same job:
\usetypescriptfile[type-charter]
\usetypescript[Charter]
\usetypescriptfile[type-utopia]
\usetypescript[Utopia]
\setupbodyfont[MyCharter]

\starttext
This is Charter roman, {\bf bold}, {\it italic}, {\bi bold-italic},
{\tfa bigger} and {\tfx smaller}.

\switchtobodyfont[MyUtopia]
This is Utopia roman, {\bf bold}, {\it italic}, {\bi bold-italic},
{\tfa bigger} and {\tfx smaller}.
\stoptext

Note that the default Computer Modern font is always available, even when the job defines other fonts: declare it with \usetypescript[modern][default] and select it with \switchtobodyfont[modern].

#### Questions

What does the \usetypescriptfile[type-buy] do? It loads a typescript which contains the definition of the [serif][fallback] typescript which I use later.

What does the \usetypescript[serif][fallback] do? It simplifies the definition of my new typescript. My example fonts are very simple and do not have slanted or smallcaps variants. ConTeXt requires those variants to be defined. I could add dummy declarations and define SerifSlanted to be the same as SerifItalic, SerifBoldSlanted to be SerifBoldItalic, and SerifCaps to be simply Serif. However, if you look at the definition of the [serif][fallback] typescript in type-buy.tex, you will see that those declarations have already been made. My typescript can "inherit" from the predefined fallback typescript.

What about the encoding=8r references? I specified these because that was what was listed for these fonts in pdftex.map. I'll try to add more on encodings to this document someday.

What are the parameters to \starttypescript? Typescripts can have up to three "specifiers". It is like having a database where you can use up to three keys to find a record. You can make up your own values. For example, if I have:

\starttypescript[A][B][C]
% ...various statements
\stoptypescript

I can find and execute the typescript with:
\usetypescript[A][B][C]

The keyword all matches any value:
\usetypescript[A][B][all]

These examples will not match typescript [A][B][C]:
\usetypescript[A]
\usetypescript[A][B]
\usetypescript[A][B][D]

You can have lists of key values to match. If I have:
\starttypescript[A][B][C]
% ...various statements
\stoptypescript

\starttypescript[A][B][Z]
% ...various statements
\stoptypescript

Then I can execute both typescripts with:
\usetypescript[A][B][C,Z]

Note that the search for typescript matches has a cumulative effect. Our database allows duplicate key values and the search will find and execute all the matches.

What are the parameters to \definetypeface? This is where it all comes together. Suppose we have:

\definetypeface[A][B][C][D][E][F]

This means:
• Define typeface A (any name you like) in its variant B, where the common variants are:
• rm: roman (normal)
• ss: sans serif
• tt: monospaced
• mm: math mode
• cg: calligraphy
• Use typescript [C][D][name] to define the styles for this variant. C can be any name you like, but by convention is commonly one or more of:
• serif
• sans
• mono
• math
• handwriting
D can be any name you like. Usually it is some variation on the font name.
• Use typescript [C][E][size] to define the size information for this typeface.
• Use F for other options, typically encoding and rscale.
Example. Now we can interpret the setup of the font Charter as given above:
\starttypescript [serif] [charter] [name]
\usetypescript[serif][fallback]
\definefontsynonym [Serif]           [Charter-Roman]
\definefontsynonym [SerifBold]       [Charter-Bold]
\definefontsynonym [SerifItalic]     [Charter-Italic]
\definefontsynonym [SerifBoldItalic] [Charter-Bold-Italic]
\stoptypescript

\starttypescript [Charter]
\definetypeface [MyCharter] [rm] [serif] [charter] [default] [encoding=8r]
\stoptypescript

This means:
• Create a typescript Charter which packages all the following.
• Define a font "MyCharter" in its normal (roman) variant.
• Use typescript [serif][charter][name] to define its styles.
• Use typescript [serif][fallback] for any styles we haven't defined.
• Use typescript [serif][default] for the size information. (Found in type-siz.tex).
• Use encoding 8r.
What are the predefined style names? The style names used in the \definefontsynonym are special in that ConTeXt uses them to implement the font switching macros such as \bf, \it, \sc, etc. The predefined names are:
• [Serif,Sans,Mono]
• [Serif,Sans,Mono]Bold
• [Serif,Sans,Mono]Italic
• [Serif,Sans,Mono]BoldItalic
• [Serif,Sans,Mono]Slanted
• [Serif,Sans,Mono]BoldSlanted
• [Serif,Sans,Mono]Caps

We also have these styles:

• MathAlpha
• MathAlphaBold
• MathBeta
• MathExtension
• MathExtensionBold
• MathGamma
• MathItalic
• MathItalicBold
• MathRoman
• MathRomanBold
• MathSymbol
• MathSymbolBold
• OldStyle

## Installing New Fonts

### Type1

#### Using texfont

The texfont utility is part of the ConTeXt package. It can be used instead of fontinst to install new fonts. The manual is Texfont Explained (mtexfont.pdf).

I purchased Adobe Sabon from Eyewire (now defunct) because the Adobe site was not happy with my browser that day. (And now I see that Adobe requires a custom download manager. Forget that). The typeface was in two packages: "Sabon" and "Sabon SC+OSF". I chose the Windows Type1 variants and downloaded these two files:

17100088.exe
17100197.exe
I had been told that these .exe files were actually zip archives. Not true. They were MS Windows executables. I had to take them to an MS machine to unpack them.

The Sabon files:

Install instructions.txt
sab_____.afm
sabi____.afm
sabi____.inf
sab_____.inf
sabi____.pfb
sabi____.pfm
sab_____.pfb
sab_____.pfm
sai_____.afm
sai_____.inf
sai_____.pfb
sai_____.pfm
sar_____.afm
sar_____.inf
sar_____.pfb
sar_____.pfm

The Sabon SC+OSF files:

Install instructions.txt
sabio___.afm
sabio___.inf
sabio___.pfb
sabio___.pfm
sabof___.afm
sabof___.inf
sabof___.pfb
sabof___.pfm
saiof___.afm
saiof___.inf
saiof___.pfb
saiof___.pfm
sarsc___.afm
sarsc___.inf
sarsc___.pfb
sarsc___.pfm
Only the .afm and .pfb files are needed for TeX.

I put the originals in a safe place and copied all the files into a temporary directory: /tmp/fonts. I decided to use the TeX root under my home directory for installing new fonts: /home/wmcclain/texmf.

Then, installing the font is a simple matter of:
texfont --fontroot=/home/wmcclain/texmf --sourcepath=/tmp/fonts --vendor=adobe --collection=sabon --makepath --install
I find these new paths and files created:

texnansi-raw-sabio.tfm
texnansi-raw-sabi.tfm
texnansi-raw-sabof.tfm
texnansi-raw-sab.tfm
texnansi-raw-saiof.tfm
texnansi-raw-sai.tfm
texnansi-raw-sarsc.tfm
texnansi-raw-sar.tfm
texnansi-sabio.tfm
texnansi-sabi.tfm
texnansi-sabof.tfm
texnansi-sab.tfm
texnansi-saiof.tfm
texnansi-sai.tfm
texnansi-sarsc.tfm
texnansi-sar.tfm
sabio___.pfb
sabi____.pfb
sabof___.pfb
sab_____.pfb
saiof___.pfb
sai_____.pfb
sar_____.pfb
sarsc___.pfb
texnansi-sabio.vf
texnansi-sabi.vf
texnansi-sabof.vf
texnansi-sab.vf
texnansi-saiof.vf
texnansi-sai.vf
texnansi-sarsc.vf
texnansi-sar.vf
And finally, this file:
which contains the lines:
% This file is generated by the TeXFont Perl script.
%
% You need to add the following line to pdftex.cfg:
%
%
% Alternatively in your TeX source you can say:
%
%
% In ConTeXt you can best use:
%

texnansi-raw-sab Sabon-Bold 4 < sab_____.pfb texnansi.enc
texnansi-raw-sabi Sabon-BoldItalic 4 < sabi____.pfb texnansi.enc
texnansi-raw-sabio Sabon-BoldItalicOsF 4 < sabio___.pfb texnansi.enc
texnansi-raw-sabof Sabon-BoldOsF 4 < sabof___.pfb texnansi.enc
texnansi-raw-sai Sabon-Italic 4 < sai_____.pfb texnansi.enc
texnansi-raw-saiof Sabon-ItalicOsF 4 < saiof___.pfb texnansi.enc
texnansi-raw-sar Sabon-Roman 4 < sar_____.pfb texnansi.enc
texnansi-raw-sarsc Sabon-RomanSC 4 < sarsc___.pfb texnansi.enc
That's the complete installation. We still have to define the typeface to ConTeXt, using the techniques shown above in "Selecting Fonts - Using Typescripts".

I create a file type-sabon.tex in the TeX path, which contains:

%
%

\starttypescript [serif] [sabon] [texnansi]
\definefontsynonym [Sabon-Roman]          [texnansi-sar]  [encoding=texnansi]
\definefontsynonym [Sabon-Bold]           [texnansi-sab]  [encoding=texnansi]
\definefontsynonym [Sabon-Italic]         [texnansi-sai]  [encoding=texnansi]
\definefontsynonym [Sabon-Bold-Italic]    [texnansi-sabi] [encoding=texnansi]
\definefontsynonym [Sabon-Roman-SmallCaps][texnansi-sarsc]  [encoding=texnansi]
\definefontsynonym [Sabon-Italic-OSF]     [texnansi-saiof]  [encoding=texnansi]
\definefontsynonym [Sabon-Bold-OSF]       [texnansi-sabof]  [encoding=texnansi]
\definefontsynonym [Sabon-Bold-Italic-OSF][texnansi-sabio]  [encoding=texnansi]
\stoptypescript

\starttypescript [serif] [sabon] [name]
\usetypescript[serif][fallback]
\definefontsynonym [Serif]           [Sabon-Roman]
\definefontsynonym [SerifBold]       [Sabon-Bold]
\definefontsynonym [SerifItalic]     [Sabon-Italic]
\definefontsynonym [SerifBoldItalic] [Sabon-Bold-Italic]
\definefontsynonym [SerifCaps]       [Sabon-Roman-SmallCaps]
% the regular old-style figures are in the small-caps file
\definefontsynonym [OldStyle]        [Sabon-Roman-SmallCaps]
\stoptypescript

\starttypescript [Sabon]
\definetypeface [Sabon] [rm] [serif] [sabon] [default] [encoding=texnansi]
\stoptypescript
Important: the \loadmapfile macro will not work unless the \autoloadmapfilestrue line is uncommented in cont-sys.tex.

Important: note that we do not reference the texnansi-raw-* files in the font declaration. I made that mistake in the first version. That usage works for many characters, but not for ligatures and some other things. The right way to do it is to reference the virtual font files, as shown.

Using the font is easy:

\usetypescriptfile[type-sabon]
\usetypescript[Sabon]
\setupbodyfont[Sabon]

\starttext
This is Sabon roman, {\it italic,} {\bf bold,} and {\bi bold-italic.}

{\em \bf This is also bold-italic.}

We have {\sc small caps} and old-style figures: {\os 0123456789}.
\stoptext
The font files defined in the typescript give us a palette for assembling new typefaces. For example, I bought eight font files, but three are not being used, the ones that have bold and italic old-style figures:
[Sabon-Italic-OSF]     [texnansi-saiof]
[Sabon-Bold-OSF]       [texnansi-sabof]
[Sabon-Bold-Italic-OSF][texnansi-sabio]
Indeed, ConTeXt does not provide a way of combining both old-style and bold or italic; this does not do what you think it might:
{\em \os 0123456789}
The figures will be old-style regular, not italic. The way to use these fonts is to define a new typeface that always uses old-style figures in the bold and italic forms. We add some lines to type-sabon.tex which now looks like:
%
%

\starttypescript [serif] [sabon, sabon-oldstyle] [texnansi]
\definefontsynonym [Sabon-Roman]          [texnansi-sar]  [encoding=texnansi]
\definefontsynonym [Sabon-Bold]           [texnansi-sab]  [encoding=texnansi]
\definefontsynonym [Sabon-Italic]         [texnansi-sai]  [encoding=texnansi]
\definefontsynonym [Sabon-Bold-Italic]    [texnansi-sabi] [encoding=texnansi]
\definefontsynonym [Sabon-Roman-SmallCaps][texnansi-sarsc]  [encoding=texnansi]
\definefontsynonym [Sabon-Italic-OSF]     [texnansi-saiof]  [encoding=texnansi]
\definefontsynonym [Sabon-Bold-OSF]       [texnansi-sabof]  [encoding=texnansi]
\definefontsynonym [Sabon-Bold-Italic-OSF][texnansi-sabio]  [encoding=texnansi]
\stoptypescript

\starttypescript [serif] [sabon] [name]
\usetypescript[serif][fallback]
\definefontsynonym [Serif]           [Sabon-Roman]
\definefontsynonym [SerifBold]       [Sabon-Bold]
\definefontsynonym [SerifItalic]     [Sabon-Italic]
\definefontsynonym [SerifBoldItalic] [Sabon-Bold-Italic]
\definefontsynonym [SerifCaps]       [Sabon-Roman-SmallCaps]
% the regular old-style figures are in the small-caps file
\definefontsynonym [OldStyle]        [Sabon-Roman-SmallCaps]
\stoptypescript

\starttypescript [Sabon]
\definetypeface [Sabon] [rm] [serif] [sabon] [default] [encoding=texnansi]
\stoptypescript

\starttypescript [serif] [sabon-oldstyle] [name]
\usetypescript[serif][fallback]
\definefontsynonym [Serif]           [Sabon-Roman]
\definefontsynonym [SerifBold]       [Sabon-Bold-OSF]
\definefontsynonym [SerifItalic]     [Sabon-Italic-OSF]
\definefontsynonym [SerifBoldItalic] [Sabon-Bold-Italic-OSF]
\definefontsynonym [SerifCaps]       [Sabon-Roman-SmallCaps]
% the regular old-style figures are in the small-caps file
\definefontsynonym [OldStyle]        [Sabon-Roman-SmallCaps]
\stoptypescript

\starttypescript [SabonOldStyle]
\definetypeface [SabonOldStyle] [rm] [serif] [sabon-oldstyle] [default] [encoding=texnansi]
\stoptypescript
Then we can see our old-style figures:
\usetypescriptfile[type-sabon]
\usetypescript[SabonOldStyle]
\setupbodyfont[SabonOldStyle]

\starttext
This is Sabon roman 0123456789,
old-style \os 0123456789,
{\it italic 0123456789,}
{\bf bold 0123456789,}
and {\bi bold-italic 0123456789.}

{\em \bf This is also bold-italic 0123456789.}

\stoptext

Note that the usage is a bit inconsistent: bold and italic use old-style figures by default and do not require \os, but the regular font uses the standard "lining" figures and does require \os for the old-style figures. It would be more consistent to make old-style the default for the regular font, but we would need to make a virtual font to do that. (Reason: the regular old-style figures are contained in the small-caps font file. Virtual fonts allow us to assemble portions of existing font files into a new "view").

Using the scheme shown here, if we want both lining and old-style figures in bold or italic, we have to use both typefaces and switch between them as necessary.

This example does not provide any math mode definitions.

### TrueType

Truetype fonts are supported by pdfTeX. No special setup is required for ConTeXt. The font definitions within ConTeXt are identical for all font formats, since TeX needs only a reference to a tfm file describing the font metrics.

In the TeXLive support directory is a utility ttf2tex which automates the installation of Truetype font files. I haven't used it because it is limited to 8-character file names.

Here is the manual method I've used; this could be worked into an installation script.

As an example, I'll use the Bergamo (Bembo) Roman font from the FontSite collection (even though a Type1 version is also provided). The encoding is up to you; I always use texnansi.enc by default. I use a naming convention similar to that used by texfont.

My habit is to rename font files so that the extensions at least are in lower case. This would also be good time to eliminate spaces and other "strange" characters in the file names:

mv BERGAMO_.TTF bergamo_.ttf
Generate a tfm file for the Truetype font file, and a "virtual property list" file. Note that I specify the complete path of the encoding file because ttf2tfm does not seem to find it automatically:
ttf2tfm bergamo_.ttf -T /usr/TeX/texmf/dvips/ly1/texnansi.enc -v texnansi-bergamo.vpl texnansi-raw-bergamo.tfm
Create the vf virtual font file and a tfm to go with it:
vptovf texnansi-bergamo.vpl texnansi-bergamo.vf texnansi-bergamo.tfm
You may wonder why we need this virtual font file. We could use the "raw" tfm directly, but we lose ligature and kerning information if we do. The virtual font definition fixes that.

Move the files into their proper places. I use the texmf directory tree under my home directory:

mkdir -p ~/texmf/fonts/truetype/fontsite/bergamo
mkdir -p ~/texmf/fonts/tfm/fontsite/bergamo
mkdir -p ~/texmf/fonts/vf/fontsite/bergamo
mv bergamo_.ttf ~/texmf/fonts/truetype/fontsite/bergamo
mv texnansi-raw-bergamo.tfm ~/texmf/fonts/tfm/fontsite/bergamo
mv texnansi-bergamo.tfm ~/texmf/fonts/tfm/fontsite/bergamo
mv texnansi-bergamo.vf ~/texmf/fonts/vf/fontsite/bergamo

Finally we need a map file entry which connects the tfm file to the ttf file. We could add this to the global pdftex.map file, but I prefer to make a separate map file for each typeface set. Create the file ~/texmf/pdftex/config/texnansi-bergamo.map and add this line:
texnansi-raw-bergamo <bergamo_.ttf texnansi.enc
Refresh the filename database:
texhash
Then this simple test should use the font:
\pdfmapfile{+texnansi-bergamo.map}
\font\Myfont=texnansi-bergamo
\Myfont This is a test.
\bye

Or, you can display all the glyphs in the font with this ConTeXt program:
\usemodule[fnt-01]
\starttext
\ShowFont[Bergamo][texnansi-bergamo][texnansi]
\stoptext

If you have multiple font files in the typeface (bold, italic, small caps, etc) then each must be processed by the steps shown above. Any number of mapping lines can be placed in one map file. Creating a typescript definition for ConTeXt is described elsewhere on this page; the process is the same regardless of the font file format.

How do the tfm, vf and map files work together? It goes something like this:

• The TeX document references texnansi-bergamo. This is the metric file texnansi-bergamo.tfm.
• By magic, TeX sees that this metric file is matched with a virtual font file: texnansi-bergamo.vf.
• This virtual font file gets its metric information from another file: texnansi-raw-bergamo.tfm. You can verify this by looking at the FONTNAME field in the .vpl file, or by running vftovp texnansi-bergamo.vf and searching the result for the same field.
• Finally, when pdfTeX needs to access the shape information for the glyphs, it searches texnansi-bergamo.map for texnansi-raw-bergamo (the tfm name) in the first field, and uses bergamo_.ttf for the glyph shapes, and texnansi.enc for the encoding.

### Metafont

The pdftex documents recommend against using bitmapped fonts because Adobe Acrobat does not render them very well. They are also not resolution-independent and have to be generated for every font variety and size used.

Nevertheless they are supported. I don't know much about using Metafont, but here is an example using the Duerer font available on both CTAN and TeXLive.

The collection consists of a series of .mf and .tfm files. The .mf files go in:

fonts/source/public/duerer
and the .tfm files belong in:
fonts/tfm/public/duerer
I note that TeXLive comes with the .tfm files, but that they are not included on CTAN, and that the CTAN Metafont directories often do not have .tfm files. They can be generated from the .mf files with Metafont, but I don't give an example here because I haven't had to do it yet. Consult the Metafont documentation.

We can now run a quick test with a script like this (note that Duerer contains only the 26 uppercase letters):

\font\Bold=cdb10
\font\Informal=cdi10
\font\Roman=cdr10
\font\Slanted=cdsl10
\font\Sans=cdss10
\font\Typewriter=cdtt10

\starttext
\Roman THIS IS COMPUTER DUERER ROMAN
\Bold BOLD
\Slanted SLANTED
\Informal INFORMAL
\Sans SANS SERIF
\Typewriter AND TYPEWRITER
\stoptext

Note that we cannot yet get PDF output from pdftex with this. If we try, using texexec --pdf example.tex, we get messages like:
The .pk bitmap files have not yet been created and pdftex doesn't do it automatically. The files can be created with Metafont utilities, but I've found it easiest just to make a .dvi version of the document and let xdvi create the files automatically:
texexec example.tex
xdvi example.dvi
We see a series of messages like so:
kpathsea: Running mktexpk --mfmode ljfour --bdpi 600 --mag 1+0/600 --dpi 600 cdtt10
mktexpk: Running mf \mode:=ljfour; mag:=1+0/600; nonstopmode; input cdtt10

On my system the .pk files are created in texmf-var/fonts/pk/ljfour/public/duerer. The xdvi window should show the test document with the Duerer fonts.

Now we can get a PDF version using texexec --pdf example.tex. Don't zoom in too much!

Here is a typescript for Duerer, using the techniques described elsewhere on this page. I don't specify any encodings because I'm not sure of how encodings work with Metafont files:

% Typescript for the Duerer metafont typeface.
%
% The Informal'' is a serifed variation; I assign it to
% italic so that we can access both it and slanted in the same
% setup.
%
\starttypescript [serif] [duerer]
\definefontsynonym [Duerer-Roman]       [cdr10]
\definefontsynonym [Duerer-Bold]        [cdb10]
\definefontsynonym [Duerer-Slanted]     [cdsl10]
\definefontsynonym [Duerer-Informal]    [cdi10]
\stoptypescript

\starttypescript [sans] [duerer]
\definefontsynonym [Duerer-Sans]        [cdss10]
\stoptypescript

\starttypescript [mono] [duerer]
\definefontsynonym [Duerer-Mono]        [cdtt10]
\stoptypescript

\starttypescript [serif] [duerer] [name]
\definefontsynonym [Serif]              [Duerer-Roman]
\definefontsynonym [SerifBold]          [Duerer-Bold]
\definefontsynonym [SerifSlanted]       [Duerer-Slanted]
\definefontsynonym [SerifItalic]        [Duerer-Informal]
\stoptypescript

\starttypescript [sans] [duerer] [name]
\definefontsynonym [Sans]               [Duerer-Sans]
\stoptypescript

\starttypescript [mono] [duerer] [name]
\definefontsynonym [Mono]               [Duerer-Mono]
\stoptypescript

\starttypescript [Duerer]
\definetypeface [Duerer] [rm] [serif] [duerer] [default]
\definetypeface [Duerer] [ss] [sans] [duerer] [default]
\definetypeface [Duerer] [tt] [mono] [duerer] [default]
\stoptypescript

Name this type-duerer.tex and place in the tex directory tree where .tex files are found. On my system I put typescripts in ~/texmf/tex/generic.

Run texhash.

And here is a test document similar to the one above:

\usetypescriptfile[type-duerer]
\usetypescript[Duerer]
\setupbodyfont[Duerer]

\starttext
THIS IS COMPUTER DUERER ROMAN
{\bf BOLD}
{\sl SLANTED}
{\it INFORMAL}
{\ss SANS SERIF}
{\tt AND TYPEWRITER}
\stoptext

Important: before we can produce a PDF version we must again do the trick of making a .dvi version and having xdvi produce the .pk files. This is because the first plain tex example expects fonts at 600dpi, and the ConTeXt version at 720dpi. No doubt these defaults are configurable, but I haven't looked into that. If you set font sizes, say with \setupbodyfont[30pt] you must again generate the .pk files. This is cumbersome, but needs to be done only once for each font and size.

## Typography

I use TeX to typeset books for print publication. Just as I am a beginning TeX user, so am I a beginning typographer and book designer (but a very serious one).

My interest is in traditional forms suitable for novels and the like. All the examples I give below are intended for that use. I have generally followed the advice given by these authors:

• Robert Bringhurst, The Elements of Typographic Style
• Jan Tschichold, The Form of the Book
• Geoffrey Dowding, Finer Points in the Spacing & Arrangement of Type

### Tight word spacing

Do not insert extra space at the end of sentences. Use small paragraph indententation and do not use vertical spacing between parapgraphs.

In plain TeX, tight spacing at the end of sentences is called \frenchspacing.

\setupspacing[packed]   % normal word space at the end of sentences
\setupindenting[small]  % small paragraph indent; about 1em?
\setupwhitespace[none]  % no space between paragraphs

### Indenting

You can bring in the margins for a quotation or extract with \startnarrower ... \stopnarrower. The amount of indentation is in predefined units which are established separately for the left, right, and middle (which does both left and right by the same amount). For example, I could do something like:
\setupnarrower[left=4em,right=2in,middle=3cm]
And then:
\startnarrower[3*left]   % indents left margin 12em
\startnarrower[right]    % indents right margin 2 inches
\startnarrower[2*middle] % indents both margins 6 cm

The manual shows how to combine parameters.

\startnarrower without parameters is the same as \startnarrower[middle].

There is a reasonable default indentation size, but I don't know its exact dimension.

### Using smaller symbols

Dowding says that "&" can be substituted for "and" wherever doing so improves the page. This is not a license to globally replace all such occurances; I use the technique only as a last resort to eliminate an overfull box.

In the fonts I have used the full-height "&" seems too large in body text, so I use a smaller version:

\def\Ampersand{{\tfx \&}}
The italic "&" is often a fancier glyph and might be useful; or it might be too fancy for body text use. I would use the italic version in Computer Modern, but the regular glyph in Adobe Sabon.

I also think the full-size "$" is too big in body text, and use a reduced version: \def\Dollar{{\tfx \$}}

### Dashes

The em-dash is too wide. Use a spaced en-dash instead: " -- ". Depending on the context, it might be necessary to use a non-breaking space (~) on either side to prevent an unwanted line break.

### Letterspacing capitals and small caps

The experts say that strings of uppercase and small-cap words should be slightly letterspaced. I find that a very little spacing is "plenty." Sometimes it does not look right at all, and I omit it. Note that it is an offence against typography to letterspace lowercase letters.

Since getting a tip from Hans Hagen, I have used these macros:

\def\CapStretchAmount{.08em}
\def\CapStretch#1{\def\stretchedspaceamount{\CapStretchAmount}\stretchednormalcase{#1}}
Which is used as so:
\CapStretch{\sc The King in Yellow}

### Margin kerning: Hanging punctuation and protruding characters

The typography references say that a justified margin does not look "optically" straight when the characters are "mechanically" aligned to that margin, because some characters are too light to color the margin. The margin looks straighter if they are pushed farther into it.

I have seen very few examples of this technique in the real world (other than photos of Gutenberg's Bible) so it is hard to judge its proper use. Experimentation and considered judgement are required.

The technique is supported by pdfTeX and ConTeXt. See Hàn Thê Thành's dissertation: Micro-typographic extensions to the TEX typesetting system, and Fonts in ConTeXt (mfonts.pdf).

Note that in TeX the technique does not merely stretch the whitespace between words; it actually enters into the line-breaking algorithm and can greatly alter a paragraph's setting.

ConTeXt comes with a couple of prededefined settings. You can see the definitions in type-exa.tex and hand-def.tex. To move the small puncuation marks a full em into the margin, use:

\usetypescript [serif,sans,mono] [hanging] [pure]
To use a slightly less drastic style which also shifts alphabetic characters very slightly, use:
\usetypescript [serif,sans,mono] [hanging] [thanh]
Margin kerning is enabled with something like:
\usetypescript [serif,sans,mono] [hanging] [thanh]
\usetypescriptfile[type-sabon]
\usetypescript[Sabon]
\setupbodyfont[Sabon]
\setupalign[hanging]
Important: The case for the default font, Computer Modern, is more complicated. Hanging alignment must be defined before the font is loaded, but Computer Modern is loaded before our definitions. The solution is to load it again after the definitions:
\setupfontsynonym[cmr10][handling=pure]
\setupfontsynonym[Serif][handling=pure]
\setupfonthandling[normal][left=1,right=1]
\usetypescript[cmr]
\setupbodyfont[10pt]
You can customize your own settings. In fact, different fonts need different settings. For example, I added these lines to my type-sabon.tex file (stolen from hand-def.tex, still to be adapted):
\startfonthandling [sabon]

\defineprotrudefactor !  0  .2
\defineprotrudefactor '  0  .7
\defineprotrudefactor  .7   0
\defineprotrudefactor ( .05  0
\defineprotrudefactor )  0  .05
\defineprotrudefactor [ .05  0
\defineprotrudefactor ]  0  .05
\defineprotrudefactor ,  0  .7
\defineprotrudefactor -  0  .7
\defineprotrudefactor .  0  .7
\defineprotrudefactor :  0  .5
\defineprotrudefactor ;  0  .5

\defineprotrudefactor rightupperninequote  0 .5
\defineprotrudefactor leftupperninequote  .5  0
\defineprotrudefactor endash               0 .3
\defineprotrudefactor emdash               0 .2

\defineprotrudefactor hyphen               0 .7

\defineprotrudefactor A .05 .05
\defineprotrudefactor F  0  .05
\defineprotrudefactor J .05   0
\defineprotrudefactor K  0  .05
\defineprotrudefactor L  0  .05
\defineprotrudefactor T .05 .05
\defineprotrudefactor V .05 .05
\defineprotrudefactor W .05 .05
\defineprotrudefactor X .05 .05
\defineprotrudefactor Y .05 .05

\defineprotrudefactor k  0  .05
\defineprotrudefactor r  0  .05
\defineprotrudefactor t  0  .05
\defineprotrudefactor v .05 .05
\defineprotrudefactor w .05 .05
\defineprotrudefactor x .05 .05
\defineprotrudefactor y .05 .05

% accented chars omitted from this example

\stopfonthandling

\starttypescript [serif] [hanging] [sabon]
\setupfontsynonym [Serif]            [handling=sabon]
% not handling these yet
%\setupfontsynonym [SerifBold]        [handling=bold]
%\setupfontsynonym [SerifSlanted]     [handling=slanted]
%\setupfontsynonym [SerifItalic]      [handling=italic]
%\setupfontsynonym [SerifBoldSlanted] [handling=boldslanted]
%\setupfontsynonym [SerifBoldItalic]  [handling=bolditalic]
\stoptypescript
Using these custom settings is just a matter of:
\usetypescriptfile[type-sabon]
\usetypescript [serif] [hanging] [sabon]
\usetypescript[Sabon]
\setupbodyfont[Sabon]
\setupalign[hanging]

## ConTeXt Techniques

### Using \definestartstop for blockquotes

New block structures can be defined with \definestartstop. For example, I use block quotes in text, and want:
• a blank line before and after
• an indent on the left
• ragged right justification
I define this with:
\definestartstop[blockquote][
before={\blank
\startnarrower[left]
\startalignment[right]}, % I lost this comma once and spent a day looking for it
after={\stopalignment
\stopnarrower
\blank}]

Then, using a block quote is just a matter of:
\startblockquote
...lots of text here
\stopblockquote

### Margin notes

Here is how I use margin notes.

First, reserve some space for them:

\setuplayout[backspace=0.9375in, width=3.25in,
rightmargindistance=.25in, rightmargin=1.125in,
leftmargindistance=.25in, leftmargin=1.125in]

\setuppagenumbering[alternative=doublesided]

I define a useful macro:
% marginal note, takes buffer name as argument
\def\MN#1{\strut\inmargin{\getbuffer[#1]}\strut}

Note: I'm not sure the \strut macros are required, but I put them in during development and have left them.

I keep one document containing all of my margin notes as buffers, for example:

\startbuffer[nebulae-m51]
\Messier{51} is in Canes Venatici and is about {\os 35} million
light years distant.
\stopbuffer

Then in the main document I place the note using the buffer name:
This form, previously known in Lord Rosse's great \quote{Whirlpool
be exceptional; now the photographs, far excelling telescopic views in
the revelation of nebular forms, showed the spiral to be the typical
shape.

Here are sample pages showing how it comes out. Hint: best viewed with "Continuous -- Facing" in Adobe Acrobat Reader.

Note: I use the named buffers because it helps organize a large project. You can use \inmargin directly, supplying the note text as the argument.

Note: I put \MN at the end of the source lines to make them easy to find when browsing with an editor. Perhaps that is wrong; it might be better to put them in line and adjacent to a following work like so:

had been supposed to \MN{nebulae-m51}be exceptional

This is based on my experience with \index placement where care must be taken so that the macros do not disturb line breaking. That was what I was working on when I put the (possibly unneeded) \strut macros in my \MN macro.

Often I need a Table of Contents where the entries are formatted differently depending on the part of the document they refer to. I first define some variations of \chapter so that each type has its own list:
\def\Midpoint{\char183}

\def\FrontChapterCommand#1#2{\startframedtext[frame=off, width=3.25in,
offset=0pt, align=middle]#2\stopframedtext}

[number=yes,
style={\switchtobodyfont[15pt]},
page=yes,
after={\blank[20pt]},
align=middle,
command=\FrontChapterCommand]

\def\BackChapterCommand#1#2{\startframedtext[frame=off, width=3.25in,
offset=0pt, align=middle]#2\stopframedtext}

[number=yes,
style={\switchtobodyfont[15pt]},
page=yes,
after={\blank[20pt]},
align=middle,
command=\BackChapterCommand]

\def\ChapterCommand#1#2{\startframedtext[frame=off, width=3.25in,
offset=0pt, align=middle, margin=no]#1~{\Midpoint}~#2\stopframedtext}

[number=yes,
style={\switchtobodyfont[15pt]},
page=yes,
after={\blank[20pt]},
align=middle,
command=\ChapterCommand]

\def\TitleCommand#1#2{\startframedtext[frame=off, width=3.25in,
offset=0pt, align=middle]#2\stopframedtext}

[number=yes,
style={\switchtobodyfont[15pt]},
page=yes,
after={\blank[20pt]},
align=middle,
command=\TitleCommand]

In the document I use the types of chapter as needed:
\FrontChapter{Introduction to the Annotated Edition}
...
\FrontChapter{Preface}
...
\startbodymatter
\chapter{The Windows of Absolute Night}
...etc...
\stopbodymatter
\BackChapter{Index}
...

\def\ContentFormat#1#2#3%
{\startframedtext[frame=off, width=3.25in, offset=0pt]#1~{\Midpoint}~#2~{\Midpoint}~{\os #3}\stopframedtext}

\def\FrontContentFormat#1#2#3%
{\startframedtext[frame=off, width=3.25in, offset=0pt]#2~{\Midpoint}~{\os #3}\stopframedtext}

\def\BackContentFormat#1#2#3%
{\startframedtext[frame=off, width=3.25in, offset=0pt]#2~{\Midpoint}~{\os #3}\stopframedtext}

\title[Contents]{Contents}

\placelist[FrontChapter]
[criterium=content,
alternative=none,
command=\FrontContentFormat]

\placelist[chapter]
[criterium=content,
alternative=none,
command=\ContentFormat]

\placelist[BackChapter]
[criterium=content,
alternative=none,
command=\BackContentFormat]

Which produces something like this:
Contents

Introduction to the Annotated Edition * 5

Preface * 12

1 * The Windows of Absolute Night * 15

2 * Star-Clouds, Star-Clusters, and Star-Streams * 26

3 * Stellar Migrations * 41

4 * The Passing of the Constellations * 52

5 * Conflagrations in the Heavens * 63

6 * Explosive and Whirling Nebulae * 76

7 * The Banners of the Sun * 91

8 * The Zodiacal Light Mystery * 103

9 * Marvels of the Aurora * 113

10 * Strange Adventures of Comets * 125

11 * Meteors, Fire-Balls, and Meteorites * 138

12 * The Wrecking of the Moon * 154

13 * The Great Mars Problem * 168

14 * The Riddle of the Asteroids * 180

Index * 189

Note: in this example the FrontChapter and BackChapter have the same structure, but they could have been different. Any number of lists can be used.

### Dropped caps

The ConTeXt source file supp-fun.tex contains macros for formatting dropped capital initials. For example, see the sample pages referenced previously. The first text line was formatted with:
\def\MyDroppedCaps%
{\DroppedCaps
{} {texnansi-sar} {2\baselineskip} {2pt} {1\baselineskip} {2}}
...

\MyDroppedCaps O{\sc ne} of the most surprising triumphs of celestial photography was

See the source code for documentation. Briefly, \MyDroppedCaps says:
• Use my Adobe Sabon Roman (texnansi-sar) font
• Make the letter two lines (2\baselineskip) high
• Offset text from the letter 2pts horizontally
• Offset the letter 1 line vertically
• Indent two lines following the letter
Note that if you are using the typescript definitions described elsewhere in this document, this macro works just as well and is typeface independent:
\def\MyDroppedCaps%
{\DroppedCaps
{} {Serif} {2\baselineskip} {2pt} {1\baselineskip} {2}}

### Positioning graphics with layers

It is possible to directly position graphics by x-y coordinates on a page. I use this for creating book covers, as in this thumbnail graphic. This is the source for that image:

\setuplayout[backspace=0in, width=6in]

\setupcolors[state=start]
\input color

\useexternalfigure[cover-front-background][cover-front-background][type=pdf, width=6in]
\useexternalfigure[m51][m0051][type=png, width=2.6784in, height=3.9672in]
\useexternalfigure[daniels][daniels][type=png, width=1.6049in, height=4.795in]
\useexternalfigure[theophilus][theophilus][type=png, width=2.6784in, height=2.43280in]
\useexternalfigure[mars][marsphoto][type=png, width=1.6049in, height=1.6049in]

\definelayer[cover-front-background]
\definelayer[m51]
\definelayer[daniels]
\definelayer[theophilus]
\definelayer[mars]

\defineoverlay[cover-front-background][\composedlayer{cover-front-background}]
\defineoverlay[m51][\composedlayer{m51}]
\defineoverlay[daniels][\composedlayer{daniels}]
\defineoverlay[theophilus][\composedlayer{theophilus}]
\defineoverlay[mars][\composedlayer{mars}]

\setupbackgrounds[page][background={cover-front-background,m51,daniels,mars,theophilus}]

\setlayer[cover-front-background][x=0in,y=0in]{\externalfigure[cover-front-background]}
\setlayer[daniels][x=0.8333in,y=1.5in]{\externalfigure[daniels]}
\setlayer[m51][x=2.5382in,y=1.5in]{\externalfigure[m51]}
\setlayer[theophilus][x=2.5382in,y=5.5672in]{\externalfigure[theophilus]}
\setlayer[mars][x=0.8333in,y=6.395in]{\externalfigure[mars]}

\starttext
...lettering...
\stoptext

The above is perhaps confusing because I reuse the same labels for different purposes: graphics, layers, overlays. ConTeXt doesn't mind, so it is convenient in use, but not in learning.

I believe names like these would work as well and possibly be more intelligible (not tested):

\useexternalfigure[mars-graphic][marsphoto][type=png, width=1.6049in, height=1.6049in]
\definelayer[mars-layer]
\defineoverlay[mars-overlay][\composedlayer{mars-layer}]
\setupbackgrounds[page][background={...,mars-overlay,...}]
\setlayer[mars-layer][x=0.8333in,y=6.395in]{\externalfigure[mars-graphic]}

Note: I did not see a way to have both color and overlay backgrounds, so I created cover-front-background.pdf which is just a blank page with the proper color. I include it as the first overlay and the others get placed on top of it.

### \index placement

This is a small issue but I spent a bit of time on it. The first time I added \index entries to my document I noticed that lines in some of the paragraphs were breaking differently, and not as well as before. Hans Hagen explained:
List enties, index entries, color changes, marks, etc, all introduce nodes in the MVL. Since tex cannot look back when such a node is encountered, it will badly interfere with spacing. Also, since you want an index on the page where you are, by default a nobreak is added, which also interferes with spacing.

The solution is simple: attach the index entry to the word that it belongs to.

So, do not do this:
the one in the constellation Triangulum. \index{Triangulum} % WRONG

the one in the constellation \index{Triangulum}Triangulum.  % Correct

### Passing variables on the command line

You can pass command-line variables to a TeX job and read them with the \envvar macro, which takes two arguments:
1. The name of the variable.
2. Value to use if the variable is not defined.
For example, if I have this in my job:
\envvar{alpha} {there is no alpha}

I can pass a value with:
texexec --arguments="alpha=Hello I am here"

Multiple variables can be specified like so:
texexec --arguments="alpha=Hello I am here,beta=Goodbye I am going"

Question: It seems to me that a comma cannot be part of the variable text, else the parser becomes confused. Is there another level of quoting that would allow this?

### Line numbers

Lines can be numbered with \startlinenumbering ... \stoplinenumbering around the text of interest.

However, there is a limit to how many lines can be numbered because the technique builds a vbox which has a maximum size. Exceeding that generates a run-time error. The solution is simple: every so often break the text into blocks with \startlinenumbering[continue] ... \stoplinenumbering. This will produce continuous line numbering without limit.

### Using italics for default emphasis

By default, for fonts that have slanted variants, the \em directive will produce slanted characters. If you would rather have italic characters:
\setupbodyfontenvironment[default][em=italic]
Note that in many typefaces the slanted definitions are synonyms for the italic variants, so that \em and \it and \sl all produce the same italic characters.

## FontSite-500 CD

FontSite sells a large collection of Type1 and TrueType fonts for \$29.95. You can see both PDF and text catalogs of the fonts included.

I've developed a set of scripts to automatically define these fonts for ConTeXt, using texfont. All of the scripts described in this section are packaged together into this archive. (On Linux unpack with unzip -a).

I was inspired by Christopher League's TeX support for the FontSite 500 CD which provides LaTeX support for the fonts. He also has a PDF catalog of the fonts his package supports.

Important Note: My effort is much less ambitious than Christopher League's. Where he has collected the fonts into useful family packages, I have simply done a direct coversion of the FontSite directories into a form that ConTeXt can access. Making more complex family definitions requires hand editing that I do not have time for. However, the basic definitions provide the components needed for family definitions and I will try to provide better examples of such later.

The effort is limited by what can reasonably be automated:

• The original font directories each have at most four font files. With some effort these are mapped to regular, italic, bold and bold-italic styles.
• All fonts are represented as Serif in the typescripts, even the sans serif, blackletter and decorative fonts. I think this is reasonable, if inelegant. None of the fonts fit into a multi-style family, so switching between \rm, \ss, etc, is not important.

The fonts are mainly derived from Softmaker/ATF. Several are "near" copies of famous fonts and are given new names. Apparently this is legal. Whether or not it is ethical I will leave for another day. Here is a table giving the FontSite and more common names of some of the fonts (mostly taken from Christopher League's notes). If anyone knows of other "alias" copies on the CD, please let me know.

FontSite Common name
Avalon Avant Garde Gothic
Basel Basilia
Benjamin Gothic Benguiat Gothic
Bergamo Bembo
Chantilly Gill Sans
Function Futura
Gareth Galliard
Glytus Glypha
Jenson Recut Centaur
Jessica Joanna
Latino Melior
Melville Murray Hill ATF
Microsquare Eurostyle, Microgamma
Opus Optima
Savoy Sabon
Schnittger Schneidler
Serific Serifa
Struktur Syntax
Typewriter American Typewriter ITC
Unitas Univers
University Old Style Berkeley Old Style
I use Python programs to generate shell scripts which do the actual installation. I have included the generated shell scripts themselves for those who don't want to run Python. They are specific to my Linux system, but might be useful to someone who wanted to do global search-and-replace on the directory names, or to cut out the sections dealing with specific fonts and experiment with them. Note that it would be easy to adapt the Python programs to do the installation directly, but I thought it would be convenient to have the shell scripts.

A note on encoding: The Python scripts take an optional --encoding= flag. texnansi is the default and is the only encoding I have used.

I also include the generated .map and .tex typescript files so you can see what is in them. Obviously, you need to buy the FontSite CD to get the .pfb and .afm files. Running texfont will recreate the .map files, but after that you can use the supplied .tex typescript files or generate your own with the scripts.

My invoice from FontSite contained a link to two updated fonts. Instructions for dealing with them are given below.

### Archive file list

Here is a summary of the files in the archive:
fontsite.py
Generate a shell script which will run texfont on a series of font directories. Run without parameters or with --help to see a usage display.
fontsite-cd.sh
Shell script generated by fontsite.py which installs all fonts on the FontSite CD.
fontsite-opussmallcaps.sh, fontsite-urwgrotesk.sh
Shell scripts generated by fontsite.py which install updated fonts downloaded from the FontSite web pages.
fontsite-typescripts.py
Create ConTeXt .tex typescript files for all FontSite fonts in a directory struture. Run without parameters or with --help to see a usage display.
fontsite-sampler.py
Generate a .tex file which prints a sample line for each FontSite font. Does not use typescripts in an effort to save time and memory. Run with --help to see a usage display.
fontsite-sampler-ah.tex, fontsite-sampler-iz.tex
These are outputs from fontsite-sampler.py. I use two output files because all the fonts in one job together cause some sort of overflow and I'm too lazy to figure out how to expand my TeX resources. In these versions I have commented out the fonts that aren't working yet.
config/*
The pdftex .map files generated by texfont during the installation.
generic/*
The ConTeXt typescript .tex files generated by fontsite-typescripts.py during the installation.

### Installation

Here is how I installed the FontSite fonts on my system. There are some error messages; see Problems below.

Note these directories:

~
/home/wmcclain, my home directory
~/texmf
my local TeX tree
~/install/fonts/fontsite
contains the Python programs
~/install/fonts/fontsite/logs
working directory, contains shell scripts, logs, and texfont sample job files
/tmp/fonts
scratch directory for temporary files
This will run texfont on all Type1 fonts on the CD. It copies the .pfb files and creates the .tfm and .map files:
mount /cdrom
cd ~/installs/fonts/fontsite/logs
rm /tmp/fonts/*
../fontsite.py --sourcepath="/cdrom/Type 1" --fontroot=~/texmf --scratch=/tmp/fonts > fontsite-cd.sh
chmod +x fontsite-cd.sh
./fontsite-cd.sh > fontsite-cd.log 2>&1
umount /cdrom

I downloaded the FontSite archive of two updated fonts to ~/installs/fonts/fontsite/updated_fonts_PC.zip. Note there is a trick to unzipping this file. All the contents are marked "text" but the .pfb files must be unzipped as binary and the .afm files must be unzipped as text. We do it in two steps:
cd ~/installs/fonts/fontsite
unzip updated_fonts_PC.zip *.pfb
unzip -a updated_fonts_PC.zip *.afm

The update files are not named consistently with the CD and we have to fix the names. This is easier than making fontsite.py try to understand all the variations.

Note that "Opus Sm Caps" had some name changes from the CD, so we first delete the original files in the ~/texmf tree, else confusion reigns.

Fix the names and install the fonts as for the CD:

cd "updated_fonts_PC/Opus Sm Caps"
mv OPUSSCB_.pfb OPUSSCB_.PFB
mv OPUSSC__.pfb OPUSSC__.PFB

cd ~/installs/fonts/fontsite/logs
../fontsite.py --sourcepath="/home/wmcclain/installs/fonts/fontsite/updated_fonts_PC/Opus Sm Caps" --fontroot=~/texmf --scratch=/tmp/fonts > fontsite-opussmallcaps.sh
chmod +x fontsite-opussmallcaps.sh
rm -r ~/texmf/fonts/*/fontsite/opussmcaps
./fontsite-opussmallcaps.sh > fontsite-opussmallcaps.log 2>&1

cd "/home/wmcclain/installs/fonts/fontsite/updated_fonts_PC/URWGrotesk/"
mkdir afm
mv *.afm afm
mv URWGBI__.pfb URWGBI__.PFB
mv URWGB___.pfb URWGB___.PFB
mv URWGHHI_.pfb URWGHHI_.PFB
mv URWGHH__.pfb URWGHH__.PFB
mv URWGI___.pfb URWGI___.PFB
mv URWGRG__.pfb URWGRG__.PFB
mv URWGSCB_.pfb URWGSCB_.PFB
mv URWGSCRG.pfb URWGSCRG.PFB

cd ~/installs/fonts/fontsite/logs
../fontsite.py --sourcepath="/home/wmcclain/installs/fonts/fontsite/updated_fonts_PC/URWGrotesk" --fontroot=~/texmf --scratch=/tmp/fonts > fontsite-urwgrotesk.sh
chmod +x fontsite-urwgrotesk.sh
./fontsite-urwgrotesk.sh > fontsite-urwgrotesk.log 2>&1

Lines in the FSBaskerville .map file were missing the postscript name field. This confuses fontsite-typescripts.py so I make a new version of the file. However: the font doesn't work, so there is another problem as yet unresolved.
% Postscript names added by Bill McClain, Oct 18 2002
%
% This file is generated by the TeXFont Perl script.
%
% You need to add the following line to pdftex.cfg:
%
%
% Alternatively in your TeX source you can say:
%
%
% In ConTeXt you can best use:
%

EOD

Same for Toxica. Also doesn't work.
cat > ~/texmf/pdftex/config/texnansi-fontsite-toxica.map <<EOD
% Postscript name added by Bill McClain, Oct 18 2002
%
% This file is generated by the TeXFont Perl script.
%
% You need to add the following line to pdftex.cfg:
%
%   map +texnansi-fontsite-toxica.map
%
% Alternatively in your TeX source you can say:
%
%   \pdfmapfile{+texnansi-fontsite-toxica.map}
%
% In ConTeXt you can best use:
%

texnansi-raw-toxica Toxica 4 < toxica__.pfb texnansi.enc
EOD

Generate the ConTeXt typescript file for every FontSite font. Note that we have to specify directories within the ~/texmf tree.
cd ~/installs/fonts/fontsite/logs
../fontsite-typescripts.py --maproot=~/texmf/pdftex/config --tfmroot=~/texmf/fonts/tfm/fontsite --outdir=~/texmf/tex/generic/
texhash

Create jobs to display a sample line of each font. These jobs don't use the typescripts, but the typescript techniques described elsewhere in this document may now be used to access the fonts.
ls ~/texmf/tex/generic/type-fontsite-[a-h]*.tex | ./fontsite-sampler.py --size=30 --phrase="Curiosities of the Sky" > fontsite-sampler-ah.tex
ls ~/texmf/tex/generic/type-fontsite-[i-z]*.tex | ./fontsite-sampler.py --size=30 --phrase="Curiosities of the Sky" > fontsite-sampler-iz.tex

### Problems

• When running texfont many fonts produce messages like this:
KPX .notdef A -33

I presume these are diagnostics from afm2tfm which refer to missing glyphs. The resulting fonts are still usuable, but perhaps not complete?
• Font "Celt" does not work. When I access it with \font= or by running the example job that texfont produces I get:
Error: pdfetex (file /home/wmcclain/texmf/fonts/type1/fontsite/celt/celt____.pf
b): buffer overflow [8192 bytes]

Perhaps I need to expand some resource?
• As mentioned in the Installation section above, these fonts did not have postscript names in their .map files:
• Toxica
I added postscript name fields, but when accessing with \font= the output is blank, and when running the example job that texfont produces I get:
! Arithmetic overflow.

\dogetnoflines ...\noflinesheight \openlineheight
\noflines \noflinesheight ...

\setvsize ...linsertionheight \getnoflines \vsize
\vsize \noflines \openline...

\flushcolumnedpage ...height \zeropoint \setvsize
\dosomebreak \nobreak \pre...

\balancedmulticolumnsout ...ue \flushcolumnedpage
\allowbreak \egroup
<output> {\balancedmulticolumnsout
}
...

Note: the "FSBaskerville-Expert" fonts are ok, and the collection also contains "NewBaskerville" fonts which work.
• The font "DeannaBorders" also shows the previous errors, even though its .map file looks ok.

## Old Installation

I originally used the TeX installation that came with the SuSE Linux distribution. I have since switched to the TexLive distribution to be more in line with the rest of the TeX world.

Here are my original installation notes. SuSE 8.1 was the last time I used the TeX provided with that installation.

SuSE Linux comes with both ConTeXt and pdfTeX, but these packages are updated rather frequently and it is necessary to upgrade without waiting for SuSE.

These notes are not a replacement for the real installation docs! I just show what I actually do when upgrading.

I do the upgrade in the main TeX tree: /usr/share/texmf. If I were ambitious I would test in some auxiliary directory first, but I haven't had much trouble yet. I have backups and am able to reinstall pretty quickly.

### ConTeXt

su root

mv cont-tmf.zip /usr/share/texmf
cd /usr/share/texmf
rm /usr/share/texmf/tex/context/base/*
unzip -a -L -o cont-tmf.zip  # overwrites existing files!

# SuSE wants the executables here...
# Note: in SuSE 7.2 the files were placed in .../i386-linux-glibc/
#       As of SuSE 8.1, they are in .../i386-linux-libc6/
#
#       Also in 8.1, the links seemed incorrect to me, so I have added
#       a few new steps to try to correct them.
#
rm /usr/share/texmf/teTeX/bin/i386-linux-libc6/texexec
rm /usr/share/texmf/teTeX/bin/i386-linux-libc6/texshow
rm /usr/share/texmf/teTeX/bin/i386-linux-libc6/texutil
rm /usr/share/texmf/teTeX/bin/i386-linux-libc6/texfont
rm /usr/share/texmf/teTeX/bin/i386-linux-libc6/texfind
rm /usr/share/texmf/teTeX/bin/i386-linux-libc6/fdf2tan
rm /usr/share/texmf/teTeX/bin/i386-linux-libc6/makempy
rm /usr/share/texmf/teTeX/bin/i386-linux-libc6/mptopdf
cp context/perltk/texexec.pl /usr/share/texmf/teTeX/bin/i386-linux-libc6/texexec
cp context/perltk/texshow.pl /usr/share/texmf/teTeX/bin/i386-linux-libc6/texshow
cp context/perltk/texutil.pl /usr/share/texmf/teTeX/bin/i386-linux-libc6/texutil
cp context/perltk/texfont.pl /usr/share/texmf/teTeX/bin/i386-linux-libc6/texfont
cp context/perltk/texfind.pl /usr/share/texmf/teTeX/bin/i386-linux-libc6/texfind
cp context/perltk/fdf2tan.pl /usr/share/texmf/teTeX/bin/i386-linux-libc6/fdf2tan
cp context/perltk/makempy.pl /usr/share/texmf/teTeX/bin/i386-linux-libc6/makempy
cp context/perltk/mptopdf.pl /usr/share/texmf/teTeX/bin/i386-linux-libc6/mptopdf
chmod +x /usr/share/texmf/teTeX/bin/i386-linux-libc6/texexec
chmod +x /usr/share/texmf/teTeX/bin/i386-linux-libc6/texshow
chmod +x /usr/share/texmf/teTeX/bin/i386-linux-libc6/texutil
chmod +x /usr/share/texmf/teTeX/bin/i386-linux-libc6/texfont
chmod +x /usr/share/texmf/teTeX/bin/i386-linux-libc6/texfind
chmod +x /usr/share/texmf/teTeX/bin/i386-linux-libc6/fdf2tan
chmod +x /usr/share/texmf/teTeX/bin/i386-linux-libc6/makempy
chmod +x /usr/share/texmf/teTeX/bin/i386-linux-libc6/mptopdf

# Edit texexec.ini afterwards?
cp /usr/share/texmf/context/config/texexec.rme /usr/share/texmf/context/config/texexec.ini

# Edit cont-sys.tex afterwards?
cp /usr/share/texmf/tex/context/user/cont-sys.rme /usr/share/texmf/tex/context/user/cont-sys.tex

texhash
texexec --make en  # en = english
texhash

exit # from "su root"

### pdfTeX

cp pdftex-20010417.tgz /tmp   # or whatever the latest snapshot is called
cd /tmp
tar zxvf pdftex-20010417.tgz  # or whatever the latest snapshot is called
cd src
configure
cd texk/web2c
make pdftexbin # may need "tangle" from previous build

su root

cp *.pool /usr/share/texmf/web2c

# SuSE wants the executables here...
# Note: in SuSE 7.2 the files were placed in .../i386-linux-glibc/
#       As of SuSE 8.1, they are in .../i386-linux-libc6/
#
cp pdftex /usr/share/texmf/teTeX/bin/i386-linux-libc6
cp pdfetex /usr/share/texmf/teTeX/bin/i386-linux-libc6
cp ttf2afm /usr/share/texmf/teTeX/bin/i386-linux-libc6

# first time only, add this to /etc/profile.local:
#
#    export TEXMFCNF=kpsewhich -show-path=.cnf`

texhash
texexec --make en
texhash

exit # from "su root"