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.
Contents
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:
| Argument | Description |
|---|---|
| --run | process (one or more) files (default action) |
| --make | create context formats |
| --ctx=name | use ctx file (process management specification) |
| --noctx | ignore ctx directives and flags |
| --interface | use specified user interface (default: en) |
| --autopdf | close pdf file in viewer and start pdf viewer afterwards |
| --purge | purge files either or not after a run (--pattern=...) |
| --purgeall | purge all files either or not after a run (--pattern=...) |
| --usemodule=list | load the given module or style, normally part of the distribution |
| --environment=list | load the given environment file first (document styles) |
| --mode=list | enable given the modes (conditional processing in styles) |
| --path=list | also consult the given paths when files are looked for |
| --arguments=list | set variables that can be consulted during a run (key/value pairs), for example:
\doifdocumentargument {bodyfont} {\setupbodyfont[\getdocumentargument{bodyfont}]} \starttext This document uses \quote{% \doifdocumentargumentelse {bodyfont} {\getdocumentargument{bodyfont}} {Latin Modern}} as bodyfont. \stoptext For LUA, you can access it through the environment.arguments table. \startluacode context(environment.arguments.bodyfont) \stopluacode |
| --randomseed=number | set the randomseed |
| --result=name | rename the resulting output to the given name |
| --trackers=list | set tracker variables (show list with --showtrackers) |
| --directives=list | set directive variables (show list with --showdirectives) |
| --silent=list | disable logcatgories (show list with --showlogcategories) |
| --strip | strip Lua code (only meant for production where no errors are expected) |
| --errors=list | show errors at the end of a run, quit when in list (also when --silent) |
| --htmlerrorpage | generate html error page instead (optional: =scite) |
| --noconsole | disable logging to the console (logfile only) |
| --nodummy | don't create a dummy file (can confuse pdf viewers that keep file in view) |
| --purgeresult | purge result file before run |
| --find=string | search for the given pattern in the documentation sources |
| --forcexml | force xml stub |
| --forcecld | force cld (context lua document) stub |
| --forcelua | force lua stub (like texlua) |
| --forcemp | force mp stub |
| --arrange | run extra imposition pass, given that the style sets up imposition |
| --noarrange | ignore imposition specifications in the style |
| --pages | report pagenumbers of names pages and list references (--page=... or --page=...) |
| --jit | use luajittex with jit turned off (only use the faster virtual machine) |
| --jiton | use luajittex with jit turned on (in most cases not faster, even slower) |
| --once | only run once (no multipass data file is produced) |
| --runs | process at most this many times |
| --forcedruns | process this many times (permits for optimization trial runs) |
| --batchmode | run without stopping and do not show messages on the console |
| --nonstopmode | run without stopping |
| --nosynctex | never initializes synctex (for production runs) |
| --synctex | run with synctex enabled (better use \setupsynctex[state=start] |
| --nodates | omit runtime dates in pdf file (optional value: a number (this 1970 offset time) or string "YYYY-MM-DD HH:MM") |
| --nocompression | forcefully turns off compression in the backend |
| --trailerid | alternative trailer id (or constant one) |
| --generate | generate file database etc. (as luatools does) |
| --paranoid | do not descend to .. and ../.. |
| --version | report installed context version |
| --global | assume given file present elsewhere |
| --nofile | use dummy file as jobname |
Expert options
The following table lists additional command-line options:
| Argument | Description |
|---|---|
| --touch | update context version number (also provide --expert, optionally provide --basepath) |
| --nostatistics | omit runtime statistics at the end of the run |
| --profile | profile job (use: mtxrun --script profile --analyze) |
| --timing | generate timing and statistics overview |
| --keeptuc | keep previous tuc files (jobname-tuc-[run].tmp) |
| --keeplog | keep previous log files (jobname-log-[run].tmp) |
| --lmtx | force lmtx mode (when available) |
| --overloadmode=error,warning,0--6,255 | enable csname overload checking |
Special options
The following table lists command-line options that are not commonly used:
| Argument | Description |
|---|---|
| --pdftex | process file with texexec using pdftex |
| --xetex | process file with texexec using xetex |
| --mkii | process file with texexec |
| --pipe | do not check for file and enter scroll mode (--dummyfile=whatever.tmp) |
| --sandbox | process file in a limited environment |
| --addbinarypath | prepend the (found) binarypath to runners |
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)
Noteworthy remarks
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 optionfindcan 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.
