Input and compilation/Executable scripts and auxiliary files/context script

The context script has the following main uses:

• compiling ConTeXt MkIV documents; and
• recompiling the ConTeXt core format after changing a source file.

Compiling

To compile a document myfile.tex, simply pass it as an argument to context:

context myfile.tex

Lists

Tables in the following sections may reference a "list" parameter to the command-line option. In such cases, the value may be a comma-separated list enclosed in straight single- or double-quotes. For example:

context --environment="setups,styles,classes" myfile.tex

Basic options

The following table lists common command-line options:

\doifdocumentargument
  {bodyfont}
  {\setupbodyfont[\getdocumentargument{bodyfont}]}

\starttext

This document uses
\quote{%
\doifdocumentargumentelse
  {bodyfont}
  {\getdocumentargument{bodyfont}}
  {Latin Modern}}
as bodyfont.

\stoptext

\startluacode
context(environment.arguments.bodyfont)
\stopluacode

Expert options

The following table lists additional command-line options:

Special options

The following table lists command-line options that are not commonly used:

Remaking the format

When you change one of ConTeXt's core files – as a temporary patch, or to try out something new, or for whatever reason – the change won't take effect immediately. Instead, you must first recompile ConTeXt, a process known as '(re)making the format'. In fact, ConTeXt has several formats: the English-language interface is a separate format from the English or the Persian one.

To make all formats:

context --make

To make just the format for a single interface language:

context --make cont-en    # English
context --make cont-uk    # British English
context --make cont-de    # German
context --make cont-fr    # French
context --make cont-nl    # Dutch
context --make cont-cs    # Czech
context --make cont-it    # Italian
context --make cont-ro    # Romanian
context --make cont-pe    # Farsi (Persian)

This section provides additional information for command-line options.

--run

Process one or more files; this is the default action and may be omitted.

--autopdf

Reopen the generated PDF file in the system's default PDF file viewer after recompiling a document.

--purgeall

Delete all build artifacts generated during compiling of a document, such as .tuc and .log files.

--path=list

Provide a comma-separated list of paths for ConTeXt to search when processing. For example:

context --path="$HOME/writing/common/styles,$HOME/writing/amazing-novel/styles"

--result

Changes the output document file name. ConTeXt creates the output document file in the current working directory; this option cannot create or move the output document in a different directory. Instead, change the working directory before running ConTeXt and use the --path option to configure where ConTeXt searches for files to process.

--errors

ConTeXt is sometimes quite liberal when it comes to non-syntactical errors in the source files. Missing fonts, missing characters in a font, missing references do not automatically abort a run or exit with a non-successful return value. To report possible issues, either compile with --errors or use

\enabledirectives
  [logs.errors]

in the source file. Example:

\starttext
%% missing figure
\externalfigure [nonexistent]
\stoptext

Compiling with context --noconsole --silent --nostatistics file.tex would result in no output (as well as a successful return value). If, on the other hand, compiled with context --noconsole --silent --nostatistics --errors file.tex the output would be:

error logging   > start possible issues
graphics        > start missing figures
graphics        >       foo
graphics        > stop missing figures
error logging   > stop possible issues

The return value would still be zero (success), though. To have the return value reflect possible found issues, patterns can be used. Example:

\enabledirectives
  [logs.errors=*]

Alternatively the patterns can be provided as a compile switch --errors='*'. The quotes are required to prevent shell expansion. With these options, the context would return 1 (failure) if problems are found.

Note that only some of the problems are reported, some of which might not be critical and other, possibly critical problems, are not detected.

--find

• find  : Beginning with ConTeXt version 2024.02.22, the following new option find can be used to check a command in the sources:

  context --find="%\starttabulate"

  In this example the result will be a list of the files and line numbers where the command \starttabulate appears.

ctxfile to store preferences

Beginning with ConTeXt version 2013.09.03 10:22, there is a new possibility to pass such options when typesetting, both with a Terminal command line or a dedicated editor such as TeXShop on Mac OS X, or TeXWorks on Mac OS X or Windows. In order to use this new capability of ConTeXt, one can create a file named for instance

 my-preferences.ctx 

which contains for instance the following lines:

<?xml version='1.0' standalone='yes'?>
<ctx:job>
   <ctx:message>default flags</ctx:message>
   <ctx:flags>
       <ctx:flag>purgeall</ctx:flag>
       <ctx:flag>synctex=zipped</ctx:flag>
   </ctx:flags>
</ctx:job>

This file has to be put for instance in your

 texmf-local/tex/context 

directory. Then on top of the file my-jobname.tex one has to say:

 % ctxfile=my-preferences 

in order to pass all the optional flags contained in my-preferences.ctx to the mkiv engine. By having several preferences.ctx files, one can have different environments for the typesetting.