Difference between revisions of "Context"

From Wiki
Jump to navigation Jump to search
m (→‎All options: add expert help)
m
 
(12 intermediate revisions by 2 users not shown)
Line 1: Line 1:
The '''`context`''' script has two main uses: (1) compiling ConTeXt MkIV documents, and (2) recompiling the ConTeXt core format after you change one of the source files. It is one of ConTeXt's four command-line scripts, together with `[[mtxrun]]` for running general ('meta-TeX') helper scripts, `[[first-setup]]` for installation and updating, and `[[texexec]]` for compiling MkII documents.
+
The '''`context`''' script has the following main uses:
 +
 
 +
* compiling ConTeXt MkIV documents; and
 +
* recompiling the ConTeXt core format after changing a source file.
 +
 
 +
It is one of ConTeXt's four command-line scripts, together with `[[Mtxrun]]` for running general ('meta-TeX') helper scripts, `[[First-setup]]` for installation and updating, and `[[texexec]]` for compiling MkII documents.
  
 
== Compiling ==
 
== Compiling ==
Line 6: Line 11:
  
 
  context ''myfile.tex''
 
  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:
 +
 +
{| class="wikitable"
 +
! 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)
 +
|-
 +
| --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
 +
|-
 +
| --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:
 +
 +
{| class="wikitable"
 +
! 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:
 +
 +
{| class="wikitable"
 +
! 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 ==
 
== Remaking the format ==
Line 28: Line 252:
  
  
== All options ==
+
[[Category:Tools]]
 
 
--run                process (one or more) files (default action)
 
--make                create context formats
 
 
--ctx=name            use ctx file (process management specification)
 
--interface          use specified user interface (default: en)
 
 
--autopdf            close pdf file in viewer and start pdf viewer afterwards
 
--purge(all)          purge 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)
 
--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)
 
--nostatistics        disable runtime statistics at the end of the run (--expert option)
 
--noconsole          disable logging to the console (logfile only)
 
--purgeresult        purge result file before run
 
 
--forcexml            force xml stub
 
--forcecld            force cld (context lua document) stub
 
 
--arrange            run extra imposition pass, given that the style sets up imposition
 
--noarrange          ignore imposition specifications in the style
 
 
--once                only run once (no multipass data file is produced)
 
--batchmode          run without stopping and don't show messages on the console
 
--nonstopmode        run without stopping
 
 
--generate            generate file database etc. (as luatools does)
 
--paranoid            don't descend to .. and ../..
 
--version            report installed context version
 
 
--global              assume given file present elsewhere
 
--nofile              use dummy file as jobname
 
 
--help                show this help
 
--help --expert      show help for expert options
 

Latest revision as of 01:45, 31 March 2021

The context script has the following main uses:

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

It is one of ConTeXt's four command-line scripts, together with Mtxrun for running general ('meta-TeX') helper scripts, First-setup for installation and updating, and texexec for compiling MkII documents.

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)
--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
--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)