The definitive guide to ConTeXt MkIV and LMTX documentation

Question

On the mailing list (sign up, do it!) and on TeX - LaTeX Stack Exchange (abbr.: TeX.SX) I often read the complaint that the ConTeXt documentation is bad/old/incomplete. I wholeheartedly disagree. However, I have to admit that ConTeXt documentation is actually quite hard to find. That is why I have come to the conclusion that a definitive guide to the, in my opinion outstanding, ConTeXt documentation is necessary. I structured this guide in such a way that a beginner can start reading the linked resources from top to bottom.

Even though you read the words “beta” and “experimental” in many places, the versions provided can be considered production quality because Pragma ADE relies on these versions for commercial purposes. If you have a deadline coming up, I would recommend not updating ConTeXt until you have finished your work, because some mechanisms are moving targets anyway.

Answer 1

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.

1. 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:

1. 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...

2. 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.

3. 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:

  1. The history of LuaTeX
  2. MkIV Hybrid Technology
  3. about LuaTeX and ConTeXt
  4. Still going on
  5. on and on
  6. following up
  7. 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.

Answer 2

Definitively "A not so short introduction to ConTeXt". There are English, French and Spanish version. It's not official, but it's good enough on my opinion.

This is inspired surely from "The Not So Short Introduction to LATEX2ε"