summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/context/manuals/reference/en/co-documents.tex
blob: 8ffbce1e19c86b4eb3e1b12636ea8e725a7ad996 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
% interface=en

\startcomponent co-documents

\environment contextref-env
\product contextref


\startFLOWchart [opzet-1]

  \startFLOWcell
    \shape{procedure}
    \name{onderdeel}
    \location{1,1}
    \text{\translate[nl=onderdeel,en=component]}
  \stopFLOWcell
  \startFLOWcell
    \shape{procedure}
    \name{omgeving-3}
    \location{1,2}
    \text{\translate[nl=omgeving,en=environment]}
    \connect [tb] {onderdeel}
  \stopFLOWcell

\stopFLOWchart

\startFLOWchart [opzet-2]

  \startFLOWcell
    \shape{procedure}
    \name{produkt}
    \location{1,1}
    \text{\translate[nl=produkt,en=product]}
    \connect [rl] {onderdeel}
  \stopFLOWcell
  \startFLOWcell
    \shape{procedure}
    \name{omgeving-2}
    \location{1,2}
    \text{\translate[nl=omgeving,en=environment]}
    \connect [tb] {produkt}
  \stopFLOWcell

  \includeFLOWchart[opzet-1][x=2,y=1]

\stopFLOWchart

\startFLOWchart [opzet-3]

  \startFLOWcell
    \shape{procedure}
    \name{projekt}
    \location{1,1}
    \text{\translate[nl=projekt,en=project]}
    \connect [rl] {produkt}
  \stopFLOWcell
  \startFLOWcell
    \shape{procedure}
    \name{omgeving-1}
    \location{1,2}
    \text{\translate[nl=omgeving,en=environment]}
    \connect [tb] {projekt}
  \stopFLOWcell

  \includeFLOWchart[opzet-2][x=2,y=1]

\stopFLOWchart


\chapter[documents]{Documents}

\section{Introduction}

Why should one use \TEX\ in the first place? Many people
start using \TEX\ because they want to typeset math. Others
are charmed by the possibility of separating content and
make||up. Yet another kind of user longs for a programmable
system. And let us not forget those users that go for quality.

When using \TEX\ one does not easily run into capacity
problems. Typesetting large documents with hundreds of
pages is typically a job for \TEX. If possible, when coding
a document one should look beyond the current document.
These days we see documents that were originally typeset
for paper being published in electronic format. And how
about making a stripped version of a 700 page document? A
strict separation between content and layout (make||up) on
the one hand and an acceptable redundancy in structure on
the other is often enough to guarantee multiple use of one
document source.

A system like \CONTEXT\ is meant to make life easier.
When coding a document the feeling can surface that \quotation
{this or that should be easier}. This feeling often
reflects the truth and the answer to the question can often
be found in this manual, although sometimes obscured. It
takes some time to learn to think in structure and content,
certainly when one is accustomed to mouse driven
word processors. In this chapter we focus on the structure of
collections of documents.

\section[startstop]{Start and stop}
\index{start}
\index{stop}
\index{structure}
\macro{\tex{starttext}}

In a self contained text we use the following commands to
mark the begin and end of a text:

\startexample
\starttyping
\starttext
\stoptext
\stoptyping
\stopexample

The first command takes care of a number of initializations
and the last command tells \TEX\ that processing can stop.
When this command is left out \TEX\ will display a \type{*}
(a star) on the command line at the end of the job. \TEX\
will expect a command, for example \type{\end}.

It is advisable to type the document setups before the
\type{\start}||command, the so called setup area of the
document. In this way a clever word||processor can identify
where the text starts, and therefore can include those
setups when it partially processes the document, given of
course that it supports partial processing of files.

In the example below a very simple layout is being used.

\startexample
\starttyping
\starttext

\subject{Introduction}

\unknown\ America has always been a land set firmly not in the past, but
in the future. On a recent visit to England, I found dozens of wonderful
bookstores chock full of the past --- ancient history, rooms full of it,
and great literature in such monumental stacks as to be overwhelming. In
the usual American bookstore, history might occupy a few bookcases; great
literature has its honoured place, but this year's paperbacks dominate. The
past is not disregarded, but neither does it loom so large and run so deep
in our blood.

\blank

{\bf Greg Bear, introduction to Tangents (1989).}

\stoptext
\stoptyping
\stopexample

The commands \type{\starttext...\stoptext} may be nested.
Within a text a new text containing \type{\starttext} and
\type{\stoptext} may be loaded.

\section[structure]{Structure}
\index{structure}
\index{products}
\index{projects}
\index{environments}
\index{components}
\macro{\tex{startproject}}
\macro{\tex{startproduct}}
\macro{\tex{startenvironment}}
\macro{\tex{startlocalenvironment}}
\macro{\tex{startcomponent}}
\macro{\tex{project}}
\macro{\tex{product}}
\macro{\tex{environment}}
\macro{\tex{components}}

In this section a structured approach of managing your
documents is discussed. For very simple and self containing
documents you can use the following approach:

\starttyping
\environment this
\environment that

\starttext
... some interesting text ...
\stoptext
\stoptyping

When you have to typeset very bulky documents it is better
to divide your document in logical components. \CONTEXT\
allows you to setup a project structure to manage your
texts. You have to know that:

\startitemize

\item A group of texts that belong together have to be
      maintained as a whole. We call this a {\em project}.

\item Layout characteristics and macros have to be defined
      at the highest level. For this, the term {\em
      environment} has been reserved.

\item Texts that belong together in a project we call {\em
      products}.

\item A product can be divided into components, these
      components can be shared with other products.
      Components can be processed individually.

\stopitemize

Programmable word processors can be adapted to this
structure.

A {\em project}, {\em environment }, {\em product} or {\em
component} is started and stopped with one of the following
commands:

\showsetup{startproject}
\showsetup{startproduct}
\showsetup{startenvironment}
\showsetup{startcomponent}

Before a \type{\start}||\type{\stop}||pair commands can be
added. When a file is not found on the directory \CONTEXT\
looks for the files on higher level directories. This
enables the user to use one or more environments for
documents that are placed on several subdirectories.

\placetable
  [here][tab:structure commands]
  {The structure commands that can be used in the files that
   make up a project.}
\starttable[|l|c|c|c|c|]
\HL
\VL \bf command     \VL
    \bf project     \VL
    \bf environment \VL
    \bf product     \VL
    \bf component  \VL\SR
\HL
\VL \type{\project <<name>>}
    \VL           \VL        \VL (\yes) \VL (\yes) \VL\FR
\VL \type{\environment <<name>>}
    \VL    (\yes) \VL (\yes) \VL (\yes) \VL (\yes) \VL\MR
\VL \type{\product <<name>>}
    \VL     \yes  \VL        \VL        \VL (\yes) \VL\MR
\VL \type{\component <<name>>}
    \VL           \VL        \VL (\yes) \VL (\yes) \VL\LR
\HL
\stoptable

To treat products and components as individual documents,
the commands in \in{table}[tab:structure commands] are used.
The commands marked with \yes\ are obligatory and the
commands marked with (\yes) are optional. The content is
typed before the \type{\stop} command.

\startbuffer
\startproject documents

\environment layout

\product  teacher
\product  pupil
\product  curriculum

\stopproject
\stopbuffer

\startfiguretext[left,offset]{none}
  \startMiniFile
    \typebuffer
  \stopMiniFile
  An example of a project file.
\stopfiguretext

\startbuffer
\startproduct teacher

\project   documents

\component teacher1
\component teacher2

\stopproduct
\stopbuffer

\startfiguretext[left,offset]{none}
  \startMiniFile
    \typebuffer
  \stopMiniFile
  The product \type{teacher.tex} (a teacher manual)
  can be defined as shown on the opposite site.
\stopfiguretext

\startbuffer
\startcomponent teacher2

\project documents
\product teacher

... text ...

\stopcomponent
\stopbuffer

\startfiguretext[left,offset]{none}
  \startMiniFile
    \typebuffer
  \stopMiniFile
  Here we see the component.
\stopfiguretext

In most cases working with only \type {\starttext} and
\type {\stoptext} in combination with \type {\input} or
\type {\enviroment} is sufficient. A project structure has
advantages when you have to manage a great number of texts.
Although it is more obvious to process {\em products} as a
whole, it also enables you to process {\em components}
independently, given that the stucture is defined properly.

In principal a project file contains only a list of products
and environments. If you would process the project file all
products will be placed in one document. This is seldom
wanted.

If you have only one product, you don't really need a project file.
This manual for example has a product/component structure without a project
file. Every chapter is a component and the product file loads some
environments.

Schematically the coherence between files could be
displayed as illustrated in \in {figures} [fig:structure
1], \in [fig:structure 2] \in {and} [fig:structure 3].

\placefigure
  [here][fig:structure 1]
  {An example of project structure.}
  {\FLOWchart[opzet-3]}

\placefigure
  [here][fig:structure 2]
  {An example with only products.}
  {\FLOWchart[opzet-2]}

\placefigure
  [here][fig:structure 3]
  {An example with only one component.}
  {\FLOWchart[opzet-1]}

It is good practice to put all setups in one environment.
In case a component or product has a different layout you
could define {\em localenvironments}:

\startexample
\starttyping
\startlocalenvironment[<<names>>]
... setups ...
\stoplocalenvironment
\stoptyping
\stopexample

A local environment can be typed in an environment file or
is a separate file itself. When a separate file is used the
local environment is loaded with:

\startexample
\starttyping
\localenvironment <<name>>
\stoptyping
\stopexample

Below you will find an example of a project structure.

\startbuffer
\startproject demos

\environment environ
\product     example

\stopproject
\stopbuffer

\startfiguretext[left,offset]{none}
  \startMiniFile
    \typebuffer
  \stopMiniFile
  file: \type{demos.tex}
  \blank
  This file is used to define the products and environments.
\stopfiguretext

\startbuffer
\startenvironment environ

\setupwhitespace[big]

\setupfootertexts[part][chapter]

\stopenvironment
\stopbuffer

\startfiguretext[left,offset]{none}
  \startMiniFile
    \typebuffer
  \stopMiniFile
  file: \type{environ.tex}
  \blank
  In the environment we type the setups that relate to all
  the different products. More than one environment or local
  environments per product can be used.
\stopfiguretext

\startbuffer
\startproduct example

\project demos

\startfrontmatter
  \completecontent
\stopfrontmatter

\startbodymatter
  \component first
  \component second
\stopbodymatter

\startbackmatter
  \completeindex
\stopbackmatter

\stopproduct
\stopbuffer

\startfiguretext[left,offset]{none}
  \startMiniFile
    \typebuffer
  \stopMiniFile
  file: \type{example.tex}
  \blank
  The product file contains the structure of the product.
  Because indexes and registers can be evoked quite easily
  we do not use a separate file.
\stopfiguretext

\startbuffer
\startcomponent first

\environment environ
\product example

\part{One}

\completecontent

\chapter{First}

..... text .....

\chapter{Second}

..... text .....

\completeindex

\stopcomponent
\stopbuffer

\startfiguretext[left,offset]{none}
  \startMiniFile
    \typebuffer
  \stopMiniFile
  file: \type{first.tex}
  \blank
  In the components of a product we place the textual
  content, figures etc. It is also possible to request the
  tables of content and registers per product.
\stopfiguretext

\startbuffer
\startcomponent second

\environment environ
\product example

\part{Two}

\completecontent

\chapter{Alfa}

..... text .....

\chapter{Beta}

..... text .....

\completeindex

\stopcomponent
\stopbuffer

\startfiguretext[left,offset]{none}
  \startMiniFile
    \typebuffer
  \stopMiniFile
  file: \type{second.tex}
  \blank
  The product contains more than one component. We could have
  defined a product for each part and a component for each
  chapter.
\stopfiguretext

The files \type{first.tex}, \type{second.tex} and
\type{example.tex} can be processed separately. If you process an environment
there will be no pages of output.

\section[directories]{Directories}
\index{files+directories}
\index{directories}

Many \TEX\ implementations look for a file in all
directories and subdirectories when a requested file is not
in the current directory. This is not only time||consuming
but may lead to errors when the wrong file (a file with the
same name) is loaded.

For this reason \CONTEXT\ works somewhat differently. A file
that is not available on the working directory is searched
for on the parent directories. This means that environments
can be placed in directories that are parents to the
products that use them. For example:

\starttyping
/texfiles/course/layout.tex
/texfiles/course/teacher/manual.tex
/texfiles/course/student/learnmat.tex
/texfiles/course/otherdoc/sheets.tex
\stoptyping

The last three files (in different subdirectories) all use
the same environment \type {layout.tex}. So, instead of
putting all files into one directory, one can organize them
in subdirectories. When a project is properly set up, that
is, as long as the project file and specific environments
can be found, one can process components and products
independently.

\section[versie]{Versions}
\index{testing}
\index{references+checking}
\index{index+checking}
\macro{\tex{version}}

During the process of document production it is useful to
generate a provisional version. This version shows the
references and the typesetting failures. The provisional
version is produced when you type:

\showsetup{version}

By default the definitive version is produced. In case a
preliminary version is produced the word {\em concept} is
placed at the bottom of each page. The keyword \type
{temporary} shows some information on for instance overfull
lines, references, figure placement, and index entries. Most
messages are placed in the margin. In some cases these
messages refer to the next pages because \TEX\ is processing
in advance.

\section[modes]{Modes}
\index{selective typesetting}
\index{modes}
\index{styles}
\index{specials}
\index{output format}
\index[texexec+mode]{\TEXEXEC+mode}
\macro{\tex{setupoutput}}
\macro{\tex{startmode}}
\macro{\tex{startnotmode}}
\macro{\tex{enablemode}}
\macro{\tex{disablemode}}
\macro{\tex{doifmodeelse}}
\macro{\tex{doifmode}}
\macro{\tex{doifnotmode}}

\TEX\ can directly produce \DVI\ or \PDF. A document can be
designed for paper and screen, where the last category
often has additional functionality. From one document we
can generate different alternatives, both in size and in
design. So, from one source several alternatives can be
generated.

Processing a file in practice comes down to launching \TEX\
with the name of the file to be processed. Imagine that by
default we generate \DVI\ output. Switching to \PDF\ is
possible by enabling another output format in the file itself
or a configuration file, but both are far from comfortable.

\starttyping
\setupoutput[pdftex]
\stoptyping

for direct \PDF\ output, or for \PDF\ produced from
\POSTSCRIPT:

\starttyping
\setupoutput[dvips,acrobat]
\stoptyping

The key to the solution of this problem is \TEXEXEC. This
\PERL\ script provides \CONTEXT\ with a
command||line||interface. When we want \PDF\ instead of
\DVI, we can launch \TEXEXEC\ with:

\starttyping
texexec  --pdf  filename
\stoptyping

There are more options, like making A5||booklets; more on
these features can be found in the manual that comes with
\TEXEXEC. However, one option deserves more time: modes.

\starttyping
texexec  --pdf  --mode=screen  filename
\stoptyping

The idea behind modes is that within a style definition, at
each moment one can ask for in what mode the document is
processed. An example of a mode dependant definition is:

\starttyping
\startmode[screen]
  \setupinteraction[state=start]
  \setupcolors[state=start]
\stopmode
\stoptyping

if needed, accompanied by:

\starttyping
\startnotmode[screen]
  \setupcolors[state=start,conversion=always]
\stopnotmode
\stoptyping

One can also pass more than one mode, separated by comma's.
There are also some low level mode dependant commands.
Given that we are dealing with a screen mode, we can say:

\starttyping
\doifmodeelse {screen} {do this} {and not that}
\doifmode     {screen} {do something}
\doifnotmode  {screen} {do something else}
\stoptyping

A mode can be activated by saying:

\starttyping
\enablemode[screen]
\disablemode[screen]
\stoptyping

Again, we can pass more modes:

\starttyping
\enablemode[paper,A4]
\stoptyping

One strength of \TEXEXEC\ is that one is not forced to
enable modes in a file: one can simply pass a command line
switch. Just as with choosing the output format: the less
we spoil the document source with output and mode settings,
the more flexible we are.

To enable users to develop a style that adapts itself to
certain circumstances, \CONTEXT\ provides system modes. For
the moment there are:

\starttabulate[|lT|p|]
\NC *list         \NC the list one called for is placed indeed     \NC \NR
\NC *register     \NC the register one called for is placed indeed \NC \NR
\NC *interaction  \NC interaction (hyperlinks etc) are turned on   \NC \NR
\NC *sectionblock \NC the named sectionblock is entered            \NC \NR
\stoptabulate

System modes are prefixed by a \type {*}, so they will not
conflict with user modes. An example of a sectionblock mode
is \type {*frontmatter}. One can use these modes like:

\starttyping
\startmode[*interaction]
  \setuppapersize[S6][S6]
\stopmode
\stoptyping


\section{Modes Manual}

\todo{Merge with previous section}

Every user will at one moment run into modes. Modes are used for
conditional processing. You enable or disable modes:

\starttyping
\enablemode[screen]
\disablemode[proof]
\stoptyping

as well as prevent modes being set:

\starttyping
\preventmode[doublesided]
\stoptyping

Later on you can act upon this mode using:

\starttyping
\startmode[screen]
  \setupinteraction[state=start]
\stopmode
\stoptyping

The counterpart of this command is:

\starttyping
\startnotmode[screen]
  \setupinteraction[state=start]
\stopnotmode
\stoptyping

You can set modes in your document or in styles, but you can
also do that at runtime:

\starttyping
texexec --pdf --mode=screen --result=myfile-s myfile
texexec --pdf --mode=A4     --result=myfile-a myfile
texexec --pdf --mode=letter --result=myfile-l myfile
\stoptyping

You can test for more modes at the same time:

\starttyping
\startmode[color,colour]
  \setupcolors[state=start]
\stopmode
\stoptyping

If you want to satisfy a combination of modes, you use:

\starttyping
\startmode[final]
  \setuplayout[markings=on]
\stopmode
\startallmodes[final,color]
  \setuplayout[markings=color]
\stopallmodes
\stoptyping

The counterpart is

\starttyping
\startnotallmodes[print,proof]
  \setuplayout[markings=off]
\stopnotallmodes
\stoptyping

Instead of the \type {start}||\type {stop} variants, you can use
the \type {\doif} alternatives. These have the advantage that they
can be nested.

\starttyping
\doifmodeelse     {modes} {action} {alternative}
\doifmode         {modes} {action}
\doifnotmode      {modes} {action}
\doifallmodeselse {modes} {action} {alternative}
\doifallmodes     {modes} {action}
\doifnotallmodes  {modes} {action}
\stoptyping

Mode can be combined with variables:

\starttyping
\setupvariables[document][alternative=print]

\enablemode[document:\getvariable{document}{alternative}]

\startmode[document:print]
  ...
\stopmode

\startmode[document:screen]
  ...
\stopmode
\stoptyping

An alternative for such an selective approach is to use setups:

\starttyping
\setupvariables[document][alternative=print]

\startsetups[document:print]
  ...
\stopsetups

\startsetups[document:screen]
  ...
\stopsetups

\setups[document:\getvariable{document}{alternative}]
\stoptyping

The difference is that mode blocks are processed in the order that
the document (or style) is loaded, while setups are stored and
recalled later.

In addition to your own modes, \CONTEXT\ provides a couple
of system modes. These are preceded by a \type {*}, as in:

\starttyping
\startmode[*first]
  % this is the first run
\stopmode
\stoptyping
 The following system modes are available (more will implemented):

% \start \setuptype[color=]

\startswitch
{\type{color-c},\type{color-m},\type{color-y},\type{color-k}}

These are rather special modes related to color separation. They are
only set when channels are split off.

\stopswitch

\startswitch {\type{figure}}

This mode is set when a graphic is found. You can use this mode in
for instance figure postprocessing actions.

\stopswitch

\startswitch {\type{text}, \type{project}, \type{product},
\type{component}, \type{environment}}

These modes are set when one enters one of the associated
structuring environments. Nesting is supported.

\stopswitch

\startswitch {\type{list}}

After using \type {\determinelistcharacteristics} this mode reflects
if list entries were found.

\stopswitch

\startswitch {\type{pairedbox}} This mode is enabled when a paired
box (legenda and such) is constructed. \stopswitch

\startswitch {\type{combination}} This mode is enabled when a
combination (often used for graphics) is constructed. \stopswitch

\startswitch {\type{interaction}}

When interaction is enabled, this mode is true. You can for instance
use this mode to add different content to for instance screen and
paper versions.

\stopswitch

\startswitch {\type{register}}

After using \type {\determineregistercharacteristics} this mode
reflects if register entries were found.

\stopswitch

\startswitch {\type{sectionnumber}}

This mode is enabled when a section head is numbered. You can access
the mode while building the section head, which is true when you have
your own commands hooked into the head mechanism.

\stopswitch

\startswitch {\type{frontpart}, \type{bodypart}, \type{backpart},
\type{appendix}}

The state of main sections in a document as well as user defined
ones, are reflected in system modes.

\stopswitch

\startswitch {\type{suffix-\jobfilesuffix}}

You can use this mode to differentiate between input file types. We
use this for instance to distinguish between different XML content
variants when pretty|-|printing (given that they can be recognized
on their suffix).

\stopswitch

\startswitch {\type{first}}

Often multiple runs are needed to get a document right. Think of
cross references, object references, tables of contents, indices,
etc. You can use this mode to determine if the first run is taking
place. For instance, when you do real time graphic conversions, it
makes sense to do that only once.

\stopswitch

\startswitch {\type{last}}

This mode is set if the last run in a session is taking place.
Normally this is not known in advance, unless one has asked for an
additional imposition pass.

\stopswitch

\startswitch {\type{background}}

This mode is set when there is a (new) background defined.

\stopswitch

\startswitch {\type{postponing}}

While postponing some content using the postpone mechanism this mode
is enabled.

\stopswitch

\startswitch {\type{grid}}

When you are typesetting on a grid, special care has to be taken not
spoil grid snapping. You can use this mode to test if you are in
grid typesetting mode.

\stopswitch

\startswitch {\type{header}}

This mode is enabled when there is a page header, i.e.\ the header
has non|-|zero dimensions.

\stopswitch

\startswitch {\type{footer}}

This mode is enabled when there is a page footer, i.e.\ the header
has non|-|zero dimensions.

\stopswitch

\startswitch {\type{makeup}}

The makeup mechanisms are used to build single pages like title
pages. This mode is set during construction.

\stopswitch

\startswitch {\type{pdf}, \type{dvi}}

One of these modes is set, which one depends on the output driver
that is loaded.

\stopswitch

\startswitch {\type{*language-id}, \type{language-id}}

When a language is chosen, its id is set as mode. For example, when the main
language is English, and the current language Dutch, we can test for the
modes \type {**en} and \type {*nl} (watch the extra \type {*}).

\stopswitch

\startswitch {\type{marking}}

This flag is set when a marking (e.g.\ in a header or footer) is
being typeset (processed).

\stopswitch

\section {Regimes}

When you key in an english document, a normal \kap {QWERTY}
keyboard combined with the standard \ASCII\ character set
will do. However, in many countries dedicated keyboards and
corresponding input encodings are used. This means that
certain keystrokes correspond to non||standard \ASCII\
characters and these need to be mapped onto the characters
present in the font. Unless the input encoding matches the
output (font) encoding, intermediate steps are needed to
take care of the right mapping. For instance, input
code~145 can become command \type {\eacute} which can
result in character~123 of a certain font.

Although all kind of intermediate, direct or indirect,
mappings are possible, in \CONTEXT\ the preferred method is
to go by named glyphs. The advantage of this method is that
we can rather comfortably convert the input stream into
different output streams as needed for typesetting text (the
normal \TEX\ process) and embedding information in the file
(like annotations or font vectors needed for searching
documents).

The conversion from input characters into named glyphs is
handled by regimes. While further mapping is done
automatically and is triggered by internal processes,
regimes need to be chosen explicitly. This is because only
the user knows what he has input.

Most encodings (like \type {il2}) have an associated regime. You
can get some insight in what a regime involves by showing it:

\starttyping
\showregime[il2]
\stoptyping

In addition there are a couple of platform dependent ones:

\starttabulate[|lT|lp|]
\HL
\NC \bf regime \NC \bf platform \NC \NR
\HL
\NC ibm \NC the old standard \MSDOS\ code page       \NC \NR
\NC win \NC the western europe \MSWINDOWS\ code page \NC \NR
\HL
\stoptabulate

If you want to know what regimes are available, you can take a
look at the \type {regi-*.tex} files. A regime that becomes more
and more popular is the utf-8 regime. If you want some insight in
what vectors provide, you can use commands like:

\starttyping
\showunicodevector[001]
\stoptyping

and

\starttyping
\showunicodetable[001]
\stoptyping

where the last one produces a rather large table.


\stopcomponent