869
edits
Changes
Jump to navigation
Jump to search
Replacing with the tugboat article
< [[The ConTeXt Way]] | [[Inside ConTeXt]] | [[Project structure]] >
{{note | I am replacing this article with a detailed article that I am writing for TugBoat. For the time being I am leaving the original article at the end. Fell free to make any changes or to merge the examples of the original article. --[[User:Adityam|Aditya]]}}
Many-a-times, you want to to generate multiple versions of the same document.
One version for printing and one for viewing on the screen; one version for
students and one version for the instructor; and so on. You can do this a
naive way. Create different files with setup for the different versions and
<code>\input</code> the common material, or create some new conditional flags using
<code>\newif</code> and set them appropriately for conditional processing. Or you
could use '''modes'''—the ConTeXt way of doing conditional processing.
= Introduction =
A mode is similar to a conditional flag, but with a few advantages. New modes
need not be explicitly defined (no need for something like <code>\newif</code>),
multiple modes can be simultaneously enabled or disabled, the status of multiple
modes can be checked easily. Moreover, modes can be set from a command line
switch. So, multiple versions of a document can be generated without changing
the source file.
The name or identifier of a mode can be any combination of letters, digits, or
spaces. Names starting with <code>*</code> are reserved for system modes.
= Setting modes =
ConTeXt has three commands for setting modes:
* <code>\enablemode [...]</code>
* <code>\disablemode[...]</code>
* <code>\preventmode[...]</code>
The names are self explanatory. <code>\enablemode</code> activates a mode,
<code>\disablemode</code> deactivates a mode, and <code>\preventmode</code> permanently
deactivates a mode. All three commands take a list of modes as an argument. For
example, you can activate <code>screen</code> and <code>solution</code> modes by
<texcode>
\enablemode[screen,solution]
</texcode>
Modes can also be activated by a command line switch <code>--modes</code> to
<code>texexec</code> and <code>context</code>. For example, to activate <code>screen</code> and
<code>solution</code> modes, you can run ConTeXt using
texexec --mode=screen,solution ...
or
context --mode=screen,solution ...
To get different pdf output for different modes, you can add <code>--result</code> switch
context --mode=screen,solution --result=solution.pdf ...
= Conditional processing based on modes =
Suppose you want to change the paper size of a document depending on whether it
is for print or screen. This can be done in multiple ways. You could either set
a default paper size for print and change it for screen:
<texcode>
\setuppapersize[letter][letter]
\startmode[screen]
\setuppapersize[S6][S6]
\stopmode
</texcode>
\noindentation
(S6 is one of the screen-optimized paper sizes in ConTeXt; the paper size has a
4:3 aspect ratio and a width equal to the width of A4 paper.) Alternatively, you
could set a default paper size for screen and change it if the screen mode is
not enabled:
<texcode>
\setuppapersize[S6][S6]
\startnotmode[screen]
\setuppapersize[letter][letter]
\stopnotmode
</texcode>
<code>\startmode</code> and <code>\startnotmode</code> can check for multiple modes. The
arguments to <code>\startmode</code> and <code>\startnotmode</code> can be a list of modes.
<code>\startmode</code> processes its contents (everything until the next
<code>\stopmode</code> which means that <code>\startmode</code> cannot be nested)
if any of the modes are enabled, otherwise (i.e., when all the modes are
disabled) <code>\startmode</code> ignores it contents. <code>\startnotmode</code> is the
opposite. It processes its contents (everything until the next
<code>\stopnotmode</code> if any of the modes are disabled, otherwise (i.e., when all
the mods are enabled) <code>\startnotmode</code> ignores its contents.
<code>\startmode</code> and <code>\startnotmode</code> are <em>or</em> environments. They
process their contents if any of the modes satisfy the required condition. Their
<em>and</em> counterparts are <code>\startallmodes</code> and <code>\startnotallmodes</code>,
which process their contents only if all the modes satisfy the required
condition. For example, suppose you want to enable interaction (hyperlinks) etc.
only when both <code>screen</code> and <code>solution</code> modes are enabled. Then you can
use:
<texcode>
\startallmodes[screen,solution]
\setupinteraction[state=start]
\stopallmodes
</texcode>
To summarize, the four start-stop environments for checking modes are:
<texcode>
\startmode[mode1, mode2, ...]
% Process if one of the modes is enabled
\stopmode
\startnotmode[mode1, mode2, ...]
% Process if one of the modes is disabled
\stopnotmode
\startallmodes[mode1, mode2, ...]
% Process if all modes are enabled
\stopallmodes
\startnotallmodes[mode1, mode2, ...]
% Process if all the modes are disabled
\stopnotallmodes
</texcode>
These environments have a <code>\doif</code> alternative that are useful for short
setups and can also be nested.
<texcode>
\doifmode {modes} {content}
\doifnotmode {modes} {content}
\doifallmodes {modes} {content}
\doifnotallmodes {modes} {content}
</texcode>
\noindentation
The logic for determining when the content is processes is exactly the same as
for the <code>start</code>-<code>stop</code> alternatives.
These <code>\doif</code> commands have a variant that can process something else if
the conditions are not satisfied (like the <code>\else</code> branch of <code>\if</code>).
<texcode>
\doifmodeelse {modes} {content} {alternative}
\doifnotmodeelse {modes} {content} {alternative}
\doifallmodeselse {modes} {content} {alternative}
\doifnotallmodeselse {modes} {content} {alternative}
</texcode>
= System modes =
In addition to user-defined modes, ConTeXt provides some system modes. These
modes start with a <code>*</code>. Here I will only explain the more commonly used
system modes. You can see the ConTeXt [http://pragma-ade.com/general/manuals/mmodes.pdf modes manual]
for a complete list of system modes.
Perhaps the most useful system modes are <code>*mkii</code> and <code>*mkiv</code> which
determine whether MkII or MkIV is being used. These modes are handy when you
want different setups for MkII and MkIV.
Other modes are useful for very specific situations. Some of these are described
below.
A document multiple times to get the cross referencing, table of contents, etc.\
right. However, sometimes you need to do some external processing (like graphic
conversion) that only needs to be done only once. In such cases, the
<code>*first</code> mode is handy, which checks for the first run of the document.
You can use the project-product-component structure for managing large projects
like a book series. See [[Project structure]]
for details. Both product and components can be compiled separately.
Sometimes you want to process a component differently depending on whether it is
being compiled directly, or if the complete product is being compiled. This can
be checked using the modes <code>*project</code>, <code>*product</code>, <code>*component</code>,
and <code>*environment</code>. For example, the <code>*product</code> mode is set whenever a
product file is read (more specifically, whenever a <code>\startproduct</code> is
encountered). Similarly, a mode <code>*text</code> is enabled whenever a
<code>\starttext</code> is encountered.
A large document is also broken down into different section blocks like
frontmatter, bodymatter, appendices, and backmatter. Internally, these section
blocks are refered as <code>frontpart</code>, <code>backpart</code>, <code>appendix</code>, and
<code>backmatter</code>. Each section block sets a system mode with the same name. So,
if you want macros that work differently for different section blocks, you can
check for <code>*fronpart</code>, <code>*backpart</code>, <code>*appendix</code>, and
<code>*backmatter</code> modes.
ConTeXt provides support for multiple language. Language are recognized by
their IETF language tags, like <code>en-us</code> for US English, <code>en-gb</code>
for British English, <code>nl</code> for Dutch, <code>de</code> for German, etc. A document
has a main language set using <code>\mainlanguage[...]</code> that is sued for
translated labels like <em>chapter</em> and <\em>figure</em>. You can also switch the
current language using <code>\language[...]</code> to change the hyphenation rules.
Whenever a language is chosen, its id is set as mode. The mode for the main
language starts with two <code>*</code>. For example, when the main language is US
English and the current language is Dutch, the modes <code>**en-us</code> and
<code>*nl</code> are set (notice the extra <code>*</code> in <code>**en-us</code>).
Other system modes are: <code>*figure</code> which is set when a graphic is found,
<code>*interaction</code> which is set when interaction is enabled, <code>*grid</code> which
is set when grid typesetting is enabled, and <code>*pdf</code> and <code>*dvi</code> which
are set depending on the whether we are generating pdf or dvi output. Others
are too esoteric to desribe here. If you are interested, see the
[http://pragma-ade.com/general/manuals/mmodes.pdf modes manual].
= Earlier Article =
Often you'd like to publish different versions of a document, say a presentation and a handout or a student's and a teacher's version.
