TUGboat, Volume 38 (2017), No. 3 315 ConTEXt for beginners Willi Egger Abstract METAPOST In 2017 we had a joint meeting of BachoTEX and TUG. During this conference a workshop for Con- TEXt beginners was requested. The following article comes from this workshop. As with any typesetting system offering possi- TEX LUA bilities to handle virtually any project, ConTEXt is a huge system. As with the workshop, this article can only lift the veil a little. The workshop was a ConT Xt hands-on session for playing with basic elements to E create a document. Towards the end there was a chance to work on a small project — a single-sided 2 Availability document containing all the elements to build an invoice. ConTEXt is included in TEX Live, so you may well already have it. However, for users who wish to use Keywords: ConTEXt, beginner, workshop ConTEXt extensively or exclusively, we recommend the standalone release, which can be obtained from the ConTEXt garden wiki: wiki.contextgarden. 1 About ConT Xt E net. The garden also has information on instal- TEX, developed by Donald Knuth in the 1970s and lation of the system for current operating systems, 1980s, is still widely used. There are three principal notably Windows, Mac OS X, and Linux. flavours: Plain TEX, LATEX and ConTEXt. ConTEXt is an advanced macro package which 3 Documentation uses T X as an engine. ConT Xt is a development E E ConT Xt is a highly complex typesetting system. It of PRAGMA ADE in Hasselt, The Netherlands. The E comes with many detailed manuals, many of which code base was written and continues to be actively are included in the distribution, and all can be down- maintained by Hans Hagen. It was first developed loaded from the Pragma website (pragma-ade.com). for typesetting schoolbooks and school math. Along with this, there are a couple of printed books; At present two versions of ConT Xt are in use. E these are available from H O-books (see also sec- ConT Xt MkII makes use of the pdfT X engine. This 2 E E tion 8. version is not developed any further and the code is frozen, but bug–fixes are still applied. The current 4 Basic elements version ConTEXt MkIV makes use of LuaTEX and is under continuous development. For new users of A basic difference compared to other macro packages ConTEXt we advise starting with ConTEXt MkIV is that in ConTEXt almost all commands are defined with LuaTEX. as structured elements, enclosed by start ... stop In contrast to other macro packages ConTEXt commands. This is a prerequisite for working with is a primarily monolithic system. Essentially all XML and provides much control over the beginning facilities are provided out of the box. Nevertheless, and end of an element. some modules for add-on features, written by third Each document starts with \starttext and parties, can be installed and invoked as necessary. ends with \stoptext. Other examples of such struc- ConTEXt makes heavy use of MetaPost. The tured commands are: latter is therefore used as a library which makes it • \startchapter ... \stopchapter possible to generate graphics at runtime very effi- • \startsection ... \stopsection ciently. • \startplacefigure ... \stopplacefigure ConTEXt can be used for processing TEX-coded documents but it also provides a fully developed The system comes with a reasonable set of pre- environment to process XML-coded data. ConTEXt sets for many constructs that are needed while build- has interface capabilities with SQL databases. ing a new document. ConTEXt provides maximum Graphically the ConTEXt–typesetting system flexibility to adjust almost anything according to can be presented as follows: the user’s wishes. For this purpose most commands ConTEXt for beginners 316 TUGboat, Volume 38 (2017), No. 3 come with a \setup... command, where appropri- \setuppapersize[letter][letter] ate variables can be customized. A couple of exam- To set a custom paper size the following two ples, taking options in square brackets (common in commands are needed: ConT Xt): E \definepapersize[Mypsize][width=80mm,height=95mm] • \setupframedtext[...][...] \setuppapersize[Mypsize][A4] • \setuplayer[...][...] The \setuppapersize command accepts two It is important to note that, in case it’s needed, arguments, used to make up the page and place it ConTEXt still understands most of Plain TEX. on paper. The first argument tells ConTEXt the size of the page, and the second argument tells the 5 Export formats system how to put the page on a certain paper size When running a document with ConTEXt the output for printing. To both arguments one can add the is by default PDF. Correctly coded documents can attributes portrait or landscape. So the above also be exported as XML, HTML, XHTML and ePub. defines a small layout sized, to be placed on A4 paper. 6 A first ConTEXt document Of course one often wants the layout size and As with other TEX environments, it is best to use a printing size to be the same, so both arguments are text editor for coding. the same: For the first document we can open a TEX file, \definepapersize[Mypsize][width=80mm,height=95mm] say myfirstfile.tex and type e.g. \setuppapersize[Mypsize][Mypsize] \starttext Finally, we do not need to define our own paper Dzie´n dobry at the \CONTEXT sizes when using any of the predefined ones. For beginners tutorial! instance, to place an A4 page on an A3 in landscape: \stopptext \setuppapersize[A4][A3,landscape] After saving this file, we can compile it from the terminal with context myfirstfile. Provided that 7.2 Page layout the installation was successful it will result in a docu- Although ConTEXt comes out of the box with a ment typeset as A4 with the name myfirstfile.pdf. decent set of presets one has all sort of possibilities It is worth mentioning that ConTEXt is UTF-8 to adapt a layout of a page to the needs at hand. In aware out of the box, so typesetting accented glyphs, order to be able to work with this rather extensive as above, is no problem. command it is necessary to have a look at the division of the space of a page. 7 Elements of a document The following drawing shows all regions which Now that we know that the installation is fine, we we can manipulate individually: the outermost areas can start describing the common elements of our indicated by top and bottom as well as leftmargin documents. In a second step these elements will be and leftedge and such. The edges are normally used in a small project for creating a simple invoice. only used in interactive documents like presentations. We will deal in this first step with the paper We will not discuss those here. size, the general layout of the page, fonts, two types left left right right of table environments, headers and footers, and the edge margin text margin edge layer mechanism and the basic placement of graphical top elements. header 7.1 Paper size text By default ConTEXt produces A4 pages, but of course one is in no way bound to this format. The system comes with many predefined paper sizes including footer the DIN-A series, American paper sizes and oversized bottom paper sizes for the print industry. Figure 1: Page layout areas Because ConTEXt produces A4 by default we do not have to set up the paper size for that case. However if you are using letter size you will have The one command to set up these different re- to tell this to the system in the preamble of each gions of the page is \setuplayout. An example: document: Willi Egger TUGboat, Volume 38 (2017), No. 3 317 \setuplayout ment. For an example of how this looks, see the [topspace=15mm, appendix. backspace=15mm, If you want to know all the dimensions set for the header=0pt, page you can put \showlayout into the document. footer=1.2\bodyfontsize, It will show all dimensions on one page. The default height=middle, values of page parameters in ConT Xt are as follows. width=middle] E This command has many arguments and needs \paperheight 29.7000cm to be studied in the documentation. Designing a page \paperwidth 21.0000cm layout is done always on a right-hand (odd) page. \printpaperheight 29.7000cm When we need a double-sided document we tell this \printpaperwidth 21.0000cm 2.4998cm to ConT Xt and the system will automatically switch \topspace E \backspace 2.5000cm the backspace and eventually-determined margins to \makeupheight 25.0000cm the right position on the even page. \makeupwidth 14.9999cm • The key topspace gives the white space above \topheight 0.0000cm the content, and key backspace denotes the \topdistance 0.0000cm white space left of the content. \headerheight 1.9999cm \headerdistance 0.0000cm • Normally ConTEXt has an active header. If we \textheight 21.0002cm do not want a header we switch the key header \footerdistance 0.0000cm to zero, using any of the usual TEX dimensions, \footerheight 1.9999cm e.g. pt, mm, cm, in. When the header is zero, \bottomdistance 0.0000cm automatically the header-distance (not shown \bottomheight 0.0000cm above; it’s the space below the header and above \leftedgewidth 0.0000cm the text) is set to zero too. The same applies to \leftedgedistance 0.0000cm the footer. \leftmarginwidth 2.6564cm \leftmargindistance 0.4217cm • The key height specifies the total height in \textwidth 14.9999cm which any content can occur, i.e. it includes \rightmargindistance 0.4217cm the header, header-distance, text body, footer- \rightmarginwidth 2.6564cm distance and footer. If we give height=middle, \rightedgedistance 0.0000cm the system will calculate the height of the type- \rightedgewidth 0.0000pt setting area such that there is an even distribu- tion of white on top and bottom of the page.