Introductory material
This is the part of the documentation where ConTeXt is indeed seriously
lacking. There does not exist much in terms of good and complete
introductory books for ConTeXt, while there exist literally hundreds of
more or less good books for LaTeX. But do not despair,
there is still a way for a beginner to start getting into ConTeXt and
here is how.
- A not so short introduction to ConTeXt This introductory text
was originally created by Joaquín Ataz-López in Spanish but has since been
translated as a community effort into several different languages. The book
does not assume that the reader knows anythin about TeX/LaTeX/ConTeXt, so for
already experienced readers it might be going a bit slow in the beginning.
Other than that it is exactly what you would expect from an introductory
textbook, as it has plenty of examples and goes into both depth and breadth
with a large number of ConTeXt features that are accessible from the macro
level.
When I first studied ConTeXt this book did not exist yet and I had to resort to
other resources which even in hindsight I still consider very valuable:
- ConTeXt Mark IV an excursion This is the successor
of ConTeXt an excursion which is often put forward as
the beginner's guide. However, ConTeXt an excursion
was written in 1999 for ConTeXt MkII and therefore contains a lot
of information which is outdated in MkIV. Some people have
complained that the layout is horrible but I think this document
gives a very nice overview over the most frequently used commands
on about 100 pages. Unfortunately I still couldn't typeset
ConTeXt documents after reading this. I now knew what the
building blocks are but I still had no idea how to put them
together. That is where the next resource enters...
- Creating a clean presentation style in 40 commits
An amazing tutorial by Aditya Mahajan where a set of presentation
slides is built step by step. You can either browse the commits
on GitHub, use the
git-walk
tool (instructions provided
on Aditya's blog), or view all the details on a single page.
This tutorial equipped me with the
basic understanding of how to customize the most relevant elements
of the document.
- ConTeXt command reference Now that you know how to
customize your documents, you of course want to try out all the
different settings. But wait, what are actually all the
settings? What are the possible keys of, e.g.
\setuphead
? That
is where the ConTeXt command reference comes in. This extremely
minimalistic document is the most helpful I have encountered so
far. On over 300 pages every setup command with all accepted keys
is listed.
This concludes the section on introductory material. From here on we
dive into more complicated topics. Nevertheless after reading the
references (1) and (2) and having (3) at hand you should be able to
compose your first documents.
Advanced
I don't recommend that you try to read these references as a whole.
There is no way you can memorize all that stuff. Just skim through it
to get an idea of what is there, so you can come back and read in
detail when you actually need it.
You have probably started writing your own macros and are getting in
contact with the ConTeXt core and are wondering what all those weird
\s!
, \c!
, \v!
, \??
and \@@
are. Then you might enjoy the
System Macros page in the ConTeXt Garden Wiki.
Fonts
- Fonts out of ConTeXt a.k.a “the new font manual”
supersedes the old Fonts chapter. Once in a while you
want to tweak things like ligatures, kerning, protrusion, or even
want to do complicated things like defining a virtual font to
display your custom characters. This is the go-to resource for
all those complicated font-related questions.
- Typescript files If you only want to implement a
typescript for a font which does not have one provided you are
much better off just browsing the ConTeXt source for the
type-imp-*.mkiv
files and see how it's done there.
Mathematics
- ConTeXt rehab for amsmath addicts This is a short
article which appeared in 2006 in the MAPS journal of the Dutch
TeX user group. It details how to achieve similar alignments to
the ones known from the LaTeX
amsmath
package. (This article
appeared also in My Way)
- math This manual discusses some advanced math stuff,
like automatic replacements (the input
/=
is automatically
converted to ≠
), interplay with grid typesetting, custom
numbering, and some tricks for deficient math fonts.
Bibliographies (BibTeX)
- Bibliographies the ConTeXt way Probably
you read about
\setupbibtex
in ConTeXt Mark IV an
excursion. This mechanism has been superseded by the
new btx
mechanism which acts as a replacement for BibTeX,
entirely implemented in Lua. Thanks to btx
ConTeXt does not
depend on external programs for processing bibliographies.
However, it only provides two different styles: apa
as an
author-year style and aps
as a numeric style. A verbose style
named ieee
is in development.
Interaction with Lua
- ConTeXt Lua Documents ConTeXt MkIV is based on
LuaTeX and LuaTeX development is driven solely by ConTeXt. It is
not surprising to find that there is amazing interaction between
ConTeXt and Lua and in principle you can typeset whole documents
in Lua. Some things, like the PDF backend, have spare or don't
have macro-level interfaces at all. Such low-level mechanisms are
usually accessible in Lua.
Graphics
Metafun Metafun is a set of MetaPost macros,
specifically tailored for the interaction with ConTeXt. You can
do a lot of fun things, like overlays, drawing font outlines, or
just basic shapes. A LaTeX user would use TikZ for that (which
is also available in ConTeXt) but Metafun runs orders of
magnitudes faster and integrates quite naturally with everything
related to frames, such as backgrounds, tables, and plain frames
of course.
Flowcharts Macro-level interfaces for drawing
flow charts in Metafun. Flowcharts are not part of the core
functionality and have to be imported using \usemodule[chart]
.
Nodes Macro-level and MetaPost interfaces for drawing
commutative diagrams.
Layout
- It's in the details I consider this to be one of the
most important documents for the advanced ConTeXt user. It is a
visual guide to all the cool features which made you switch from
LaTeX to ConTeXt, namely grid typesetting and sidefloats. As
already noted, this is a visual guide and not really a manual
which explains a lot of things. Rather it lists different options
and shows the visual effects of setting those options.
- Pages Behind this rather misleading title hides
a manual on how to typeset magazine style columns with floats
which can span several columns.
Expert
The progress reports A lot of features which get added to
ConTeXt are rather minor or affect the core directly, so they do
not have dedicated manuals. Nevertheless, Hans tirelessly
documents these features in his progress reports on LuaTeX and
ConTeXt development. In chronological order these are:
- The history of LuaTeX
- MkIV Hybrid Technology
- about LuaTeX and ConTeXt
- Still going on
- on and on
- following up
- on target (current working report)
The history of LuaTeX has mostly historical relevance
because a lot of features described in there are documented
elsewhere in much more detail, like OpenType fonts,
Metafun, and XML.
The other documents give a very in-depth view of all the internals of
ConTeXt MkIV and LMTX and it is definitely worth skimming through them to
see what is available. Whenever I open these manuals and read a few
paragraphs I find new hidden features.
- Dealing with XML in ConTeXt MkIV ConTeXt can export
documents to XML. This is possible thanks to the monolithic core
and unified interfaces. It is also possible to generate typeset
output from XML input. This manual details all the XML
interaction with the macro and the Lua level.
- LuaTeX and LuaMetaTeX Because the relationship
between ConTeXt MkIV and Lua(Meta)TeX is so close it is absolutely necessary
for the expert user to know the details of the underlying engine. The links
point to the LuaTeX and LuaMetaTeX manuals hosted on Pragma ADE which always
covers the latest development version used as a basis for ConTeXt MkIV and
LMTX, respectively.
Further resources
All the manuals listed above are also shipped with the installation of
ConTeXt standalone and TeX Live. The PDFs can be found in
doc/context/documents/general/manuals/
, the corresponding
sources in doc/context/sources/general/manuals/
(the
links point to the ConTeXt GitHub mirror).
In TeX Live, manuals can also be opened using the texdoc
tool by
providing the name of the PDF as an argument, e.g. texdoc metafun-p
will open the MetaFun manual.
There are two other manuals which I see mentioned in some places and I
want to give my comments on these.
Typographic Programming This is supposed to grow into a
manual about general aspects of document design and how to
translate design into style by the means of automated typesetting.
At the moment it is unfinished and is mostly about
microtypographic features and page layout but doesn't go beyond
the much more complete Fonts out of ConTeXt and
It's in the details. It also hasn't been updated in
a while.
ConTeXt reference manual This was supposed to be a
comprehensive introduction to ConTeXt and could have evolved into
a complete introductory user manual but got stuck somewhere
halfway between MkII and MkIV with a few missing chapters. I
don't recommend reading it before you have a solid understanding
of the difference between MkII and MkIV, because otherwise it is
just too confusing.
There is also the command reference on the ConTeXt Garden
Wiki. This is a total hit and miss because some commands are
documented really well, others not at all. The good thing is that it
is publicly editable, so if you encounter bad documentation you should
log in and fix it.