tools-mkiv.tex /size: 46 Kb    last modification: 2023-12-21 09:43
1% language=us runpath=texruns:manuals/tools
2
3% author    : Hans Hagen
4% copyright : ConTeXt Development Team
5% license   : Creative Commons Attribution ShareAlike 4.0 International
6% reference : pragma-ade.nl | contextgarden.net | texlive (related) distributions
7% origin    : the ConTeXt distribution
8%
9% comment   : Because this manual is distributed with TeX distributions it comes with a rather
10%             liberal license. We try to adapt these documents to upgrades in the (sub)systems
11%             that they describe. Using parts of the content otherwise can therefore conflict
12%             with existing functionality and we cannot be held responsible for that. Many of
13%             the manuals contain characteristic graphics and personal notes or examples that
14%             make no sense when used out-of-context.
15%
16% comment   : Some chapters might have been published in TugBoat, the NTG Maps, the ConTeXt
17%             Group journal or otherwise. Thanks to the editors for corrections. Also thanks
18%             to users for testing, feedback and corrections.
19
20\usemodule[abr-02]
21
22\setuplayout
23  [width=middle,
24   height=middle,
25   backspace=2cm,
26   topspace=1cm,
27   footer=0pt,
28   bottomspace=2cm]
29
30\definecolor
31  [DocumentColor]
32  [r=.5]
33
34\setuptype
35  [color=DocumentColor]
36
37\setuptyping
38  [color=DocumentColor]
39
40\setupalign
41  [tolerant,stretch]
42
43% \usetypescript
44%   [iwona]
45%
46% \setupbodyfont
47%   [iwona]
48
49\setupbodyfont
50  [ibmplex,rm]
51
52\setuphead
53  [chapter]
54  [style=\bfc,
55   color=DocumentColor]
56
57\setuphead
58  [section]
59  [style=\bfb,
60   color=DocumentColor]
61
62\setuphead
63  [sub  section]
64  [style=\bfa,
65   color=DocumentColor]
66
67\setupinteraction
68  [hidden]
69
70\setupwhitespace
71  [big]
72
73\setupheadertexts
74  []
75
76\setupheadertexts
77  []
78  [{\DocumentColor \type {luatools mtxrun context}\quad\pagenumber}]
79
80\usesymbols[cc]
81
82\def\sTEXMFSTART{\type{texmfstart}}
83\def\sLUATOOLS  {\type{luatools}}
84\def\sMTXRUN    {\type{mtxrun}}
85\def\sCONTEXT   {\type{context}}
86\def\sKPSEWHICH {\type{kpsewhich}}
87\def\sMKTEXLSR  {\type{mktexlsr}}
88\def\sXSLTPROC  {\type{xsltproc}}
89
90\usemodule[narrowtt]
91
92\startdocument
93  [metadata:author=Hans Hagen,
94   metadata:title={Tools: luatools, mtxrun, context},
95   author=Hans Hagen,
96   affiliation=PRAGMA ADE,
97   location=Hasselt NL,
98   title=Tools,
99   extra-1=luatools,
100   extra-2=mtxrun,
101   extra-3=context,
102   support=www.contextgarden.net,
103   website=www.pragma-ade.nl]
104
105\startMPpage
106    StartPage ;
107        picture p ; p := image (
108            for i=1 upto 21 :
109                for j=1 upto 30 :
110                    drawarrow (fullcircle rotated uniformdeviate 360) scaled 10 shifted (i*15,j*15) ;
111                endfor ;
112            endfor ;
113        ) ;
114        p := p ysized (bbheight(Page)-4mm) ;
115        fill Page enlarged 2mm withcolor \MPcolor{DocumentColor} ;
116        draw p shifted (center Page - center p) withpen pencircle scaled 2 withcolor .5white ;
117        numeric dx ; dx := bbwidth(Page)/21 ;
118        numeric dy ; dy := bbheight(Page)/30 ;
119        p := textext("\tt\bf\white\documentvariable{extra-1}") xsized(14*dx) ;
120        p := p shifted (-lrcorner p) shifted lrcorner Page shifted (-1dx,8dy) ;
121        draw p ;
122        p := textext("\tt\bf\white\documentvariable{extra-2}") xsized(14*dx) ;
123        p := p shifted (-lrcorner p) shifted lrcorner Page shifted (-1dx,5dy) ;
124        draw p ;
125        p := textext("\tt\bf\white\documentvariable{extra-3}") xsized(14*dx) ;
126        p := p shifted (-lrcorner p) shifted lrcorner Page shifted (-1dx,2dy) ;
127        draw p ;
128        setbounds currentpicture to Page ;
129    StopPage
130\stopMPpage
131
132\startsubject[title=Contents]
133
134\placelist[section][alternative=a]
135
136\stopsubject
137
138\startsection[title={Remark}]
139
140This manual is work in progress. Feel free to submit additions or corrections.
141Before you start reading, it is good to know that in order to get starting with
142\CONTEXT, the easiest way to do that is to download the standalone distribution
143from \type {contextgarden.net}. After that you only need to make sure that \type
144{luatex} is in your path. The main command you use is then \sCONTEXT\ and
145normally it does all the magic it needs itself.
146
147\stopsection
148
149\startsection[title={Introduction}]
150
151Right from the start \CONTEXT\ came with programs that managed the process of
152\TEX-ing. Although you can perfectly well run \TEX\ directly, it is a fact that
153often multiple runs are needed as well as that registers need to be sorted.
154Therefore managing a job makes sense.
155
156First we had \TEXEXEC\ and \TEXUTIL, and both were written in \MODULA, and as
157this language was not supported on all platforms the programs were rewritten in
158\PERL. Following that a few more tools were shipped with \CONTEXT.
159
160When we moved on to \RUBY\ all the \PERL\ scripts were rewritten and when
161\CONTEXT\ \MKIV\ showed up, \LUA\ replaced \RUBY. As we use \LUATEX\ this means
162that currently the tools and the main program share the same language. For \MKII\
163scripts like \TEXEXEC\ will stay around but the idea is that there will be \LUA\
164alternatives for them as well.
165
166Because we shipped many scripts, and because the de facto standard \TEX\
167directory structure expects scripts to be in certain locations we not only ship
168tools but also some more generic scripts that locate and run these tools.
169
170\stopsection
171
172\startsection[title={The location}]
173
174Normally you don't need to know so many details about where the scripts
175are located but here they are:
176
177\starttyping
178<texroot>/scripts/context/perl
179<texroot>/scripts/context/ruby
180<texroot>/scripts/context/lua
181<texroot>/scripts/context/stubs
182\stoptyping
183
184This hierarchy was actually introduced because \CONTEXT\ was shipped with a bunch
185of tools. As mentioned, we nowadays focus on \LUA\ but we keep a few of the older
186scripts around in the \PERL\ and \RUBY\ paths.Now, if you're only using \CONTEXT\
187\MKIV, and this is highly recommended, you can forget about all but the \LUA\
188scripts.
189
190\stopsection
191
192\startsection[title={The traditional finder}]
193
194When you run scripts multiple times, and in the case of \CONTEXT\ they are even
195run inside other scripts, you want to minimize the startup time. Unfortunately
196the traditional way to locate a script, using \sKPSEWHICH, is not that fast,
197especially in a setup with many large trees Also, because not all tasks can be
198done with the traditional scripts (take format generation) we provided a runner
199that could deal with this: \sTEXMFSTART. As this script was also used in more
200complex workflows, it had several tasks:
201
202\startitemize[packed]
203\item locate scripts in the distribution and run them using the right
204      interpreter
205\item do this selectively, for instance identify the need for a run using
206      checksums for potentially changed files (handy for image conversion)
207\item pass information to child processes so that lookups are avoided
208\item choose a distribution among several installed versions (set the root
209      of the \TEX\ tree)
210\item change the working directory before running the script
211\item resolve paths and names on demand and launch programs with arguments
212      where names are expanded controlled by prefixes (handy for
213      \TEX-unware programs)
214\item locate and open documentation, mostly as part the help systems in
215      editors, but also handy for seeing what configuration file is used
216\item act as a \KPSEWHICH\ server cq.\ client (only used in special cases,
217      and using its own database)
218\stopitemize
219
220Of course there were the usual more obscure and undocumented features as
221well. The idea was to use this runner as follows:
222
223\starttyping
224texmfstart texexec <further arguments>
225texmfstart --tree <rootoftree> texexec <further arguments>
226\stoptyping
227
228These are just two ways of calling this program. As \sTEXMFSTART\ can initialize
229the environment as well, it is basically the only script that has to be present
230in the binary path. This is quite comfortable as this avoids conflicts in names
231between the called scripts and other installed programs.
232
233Of course calls like above can be wrapped in a shell script or batch file without
234penalty as long as \sTEXMFSTART\ itself is not wrapped in a caller script that
235applies other inefficient lookups. If you use the \CONTEXT\ minimals you can be
236sure that the most efficient method is chosen, but we've seen quite inefficient
237call chains elsewhere.
238
239In the \CONTEXT\ minimals this script has been replaced by the one we will
240discuss in the next section: \sMTXRUN\ but a stub is still provided.
241
242\stopsection
243
244\startsection[title={The current finder}]
245
246In \MKIV\ we went a step further and completely abandoned the traditional lookup
247methods and do everything in \LUA. As we want a clear separation between
248functionality we have two main controlling scripts: \sMTXRUN\ and \sLUATOOLS. The
249last name may look somewhat confusing but the name is just one on in a series.
250\footnote {We have \type {ctxtools}, \type {exatools}, \type {mpstools}, \type
251{mtxtools}, \type {pdftools}, \type {rlxtools}, \type {runtools}, \type
252{textools}, \type {tmftools} and \type {xmltools}. Most if their funtionality is
253already reimplemented.}
254
255In \MKIV\ the \sLUATOOLS\ program is nowadays seldom used. It's just a drop in
256for \sKPSEWHICH\ plus a bit more. In that respect it's rather dumb in that it
257does not use the database, but clever at the same time because it can make one
258based on the little information available when it runs. It can also be used to
259generate format files either or not using \LUA\ stubs but in practice this is not
260needed at all.
261
262For \CONTEXT\ users, the main invocation of this tool is when the \TEX\ tree is
263updated. For instance, after adding a font to the tree or after updating
264\CONTEXT, you need to run:
265
266\starttyping
267mtxrun --generate
268\stoptyping
269
270After that all tools will know where to find stuff and how to behave well within
271the tree. This is because they share the same code, mostly because they are
272started using \sMTXRUN. For instance, you process a file with:
273
274\starttyping
275mtxrun --script context <somefile>
276\stoptyping
277
278Because this happens often, there's also a shortcut:
279
280\starttyping
281context <somefile>
282\stoptyping
283
284But this does use \sMTXRUN\ as well. The help information of \sMTXRUN\ is rather
285minimalistic and if you have no clue what an option does, you probably never
286needed it anyway. Here we discuss a few options. We already saw that we can
287explicitly ask for a script:
288
289\starttyping
290mtxrun --script context <somefile>
291\stoptyping
292
293but
294
295\starttyping
296mtxrun context <somefile>
297\stoptyping
298
299also works. However, by using \type {--script} you limit te lookup to the valid
300\CONTEXT\ \MKIV\ scripts. In the \TEX\ tree these have names prefixed by \type
301{mtx-} and a lookup look for a plural as well. So, the next two lookups are
302equivalent:
303
304\starttyping
305mtxrun --script font
306mtxrun --script fonts
307\stoptyping
308
309Both will run \type {mtx-fonts.lua}. Actually, this is one of the scripts that
310you might need when your font database is somehow outdated and not updated
311automatically:
312
313\starttyping
314mtxrun --script fonts --reload --force
315\stoptyping
316
317Normally \sMTXRUN\ is all you need in order to run a script. However, there are a
318few more options:
319
320\ctxlua{os.execute("mtxrun > tools-mkiv-help.tmp")}
321
322\typefile[ntyping]{tools-mkiv-help.tmp}
323
324Don't worry,you only need those obscure features when you integrate \CONTEXT\ in
325for instance a web service or when you run large projects where runs and paths
326take special care.
327
328\stopsection
329
330\startsection[title={Updating}]
331
332There are two ways to update \CONTEXT\ \MKIV. When you manage your
333trees yourself or when you use for instance \TEXLIVE, you act as
334follows:
335
336\startitemize[packed]
337\item download the file cont-tmf.zip from \type {www.pragma-ade.com} or elsewhere
338\item unzip this file in a subtree, for instance \type {tex/texmf-local}
339\item run \type {mtxrun --generate}
340\item run \type {mtxrun --script font --reload}
341\item run \type {mtxrun --script context --make}
342\stopitemize
343
344Or shorter:
345
346\startitemize[packed]
347\item run \type {mtxrun --generate}
348\item run \type {mtxrun font --reload}
349\item run \type {context --make}
350\stopitemize
351
352Normally these commands are not even needed, but they are a nice test if your
353tree is still okay. To some extend \sCONTEXT\ is clever enough to decide if the
354databases need to be regenerated and|/|or a format needs to be remade and|/|or if
355a new font database is needed.
356
357Now, if you also want to run \MKII, you need to add:
358
359\startitemize[packed]
360\item run \type {mktexlsr}
361\item run \type {texexec --make}
362\stopitemize
363
364The question is, how to act when \sLUATOOLS\ and \sMTXRUN\ have been updated
365themselves? In that case, after unzipping the archive, you need to do the
366following:
367
368\startitemize[packed]
369\item run \type {luatools --selfupdate}
370\item run \type {mtxrun --selfupdate}
371\stopitemize
372
373For quite a while we shipped so called \CONTEXT\ minimals. These zip files
374contained only the resources and programs that made sense for running \CONTEXT.
375Nowadays the minimals are installed and synchronized via internet. \footnote
376{This project was triggered by Mojca Miklavec who is also in charge of this bit
377of the \CONTEXT\ infrastructure. More information can be found at \type
378{contextgarden.net}.} You can just run the installer again and no additional
379commands are needed. In the console you will see several calls to \sMTXRUN\ and
380\sLUATOOLS\ fly by.
381
382\stopsection
383
384\startsection[title={The tools}]
385
386We only mention the tools here. The most important ones are \sCONTEXT\ and \type
387{fonts}. You can ask for a list of installed scripts with:
388
389\starttyping
390mtxrun --script
391\stoptyping
392
393On my machine this gives:
394
395\ctxlua{os.execute("mtxrun --script > tools-mkiv-help.tmp")}
396
397\typefile[ntyping]{tools-mkiv-help.tmp}
398
399The most important scripts are \type {mtx-fonts} and \type {mtx-context}. By
400default fonts are looked up by filename (the \type {file:} prefix before font
401names in \CONTEXT\ is default). But you can also lookup fonts by name (\type
402{name:}) or by specification (\type {spec:}). If you want to use these two
403methods, you need to generate a font database as mentioned in the previous
404section. You can also use the font tool to get information about the fonts
405installed on your system.
406
407\stopsection
408
409\startsection[title={Running \CONTEXT}]
410
411The \sCONTEXT\ tool is what you will use most as it manages your
412run.
413
414\ctxlua{os.execute("context > tools-mkiv-help.tmp")}
415
416\typefile[ntyping]{tools-mkiv-help.tmp}
417
418There are few expert options too:
419
420\ctxlua{os.execute("context --expert > tools-mkiv-help.tmp")}
421
422\typefile[ntyping]{tools-mkiv-help.tmp}
423
424You might as well forget about these unless you are one of the
425\CONTEXT\ developers.
426
427\stopsection
428
429\startsection[title={Prefixes}]
430
431A handy feature of \sMTXRUN\ (and as most features an inheritance of
432\sTEXMFSTART) is that it will resolve prefixed arguments. This can be of help
433when you run programs that are unaware of the \TEX\ tree but nevertheless need to
434locate files in it.
435
436\ctxlua{os.execute("mtxrun --prefixes > tools-mkiv-help.tmp")}
437
438\typefile[ntyping]{tools-mkiv-help.tmp}
439
440An example is:
441
442\starttyping
443mtxrun --execute xsltproc file:whatever.xsl file:whatever.xml
444\stoptyping
445
446The call to \sXSLTPROC\ will get two arguments, being the complete path to the
447files (given that it can be resolved). This permits you to organize the files in
448a similar was as \TEX\ files.
449
450\stopsection
451
452\startsection[title={Stubs}]
453
454As the tools are written in the \LUA\ language we need a \LUA\ interpreter and of
455course we use \LUATEX\ itself. On \UNIX\ we can copy \sLUATOOLS\ and \sMTXRUN\ to
456files in the binary path with the same name but without suffix. Starting them in
457another way is a waste of time, especially when \sKPSEWHICH\ is used to find
458then, something which is useless in \MKIV\ anyway. Just use these scripts
459directly as they are self contained.
460
461For \sCONTEXT\ and other scripts that we want convenient access to, stubs are
462needed, like:
463
464\starttyping
465#!/bin/sh
466mtxrun --script context "$@"
467\stoptyping
468
469This is also quite efficient as the \sCONTEXT\ script \type {mtx-context} is
470loaded in \sMTXRUN\ and uses the same database.
471
472On \WINDOWS\ you can copy the scripts as|-|is and associate the suffix with
473\LUATEX\ (or more precisely: \type {texlua}) but then all \LUA\ script will be
474run that way which is not what you might want.
475
476In \TEXLIVE\ stubs for starting scripts were introduced by Fabrice Popineau. Such
477a stub would start for instance \sTEXMFSTART, that is: it located the script
478(\PERL\ or \RUBY) in the \TEX\ tree and launched it with the right interpreter.
479Later we shipped pseudo binaries of \sTEXMFSTART: a \RUBY\ interpreter plus
480scripts wrapped into a self contained binary.
481
482For \MKIV\ we don't need such methods and started with simple batch files,
483similar to the \UNIX\ startup scripts. However, these have the disadvantage that
484they cannot be used in other batch files without using the \type {start} command.
485In \TEXLIVE\ this is taken care of by a small binary written bij T.M.\ Trzeciak
486so on \TEXLIVE\ 2009 we saw a call chain from \type {exe} to \type {cmd} to \type
487{lua} which is somewhat messy.
488
489This is why we now use an adapted and stripped down version of that program that
490is tuned for \sMTXRUN, \sLUATOOLS\ and \sCONTEXT. So, we moved from the original
491\type {cmd} based approach to an \type {exe} one.
492
493\starttyping
494mtxrun.dll
495mtxrun.exe
496\stoptyping
497
498You can copy \type {mtxrun.exe} to for instance \type {context.exe} and it will
499still use \sMTXRUN\ for locating the right script. It also takes care of mapping
500\sTEXMFSTART\ to \sMTXRUN. So we've removed the intermediate \type {cmd} step,
501can run the script as any program, and most of all, we're as efficient as can be.
502Of course this program is only meaningful for the \CONTEXT\ approach to tools.
503
504It may all sound more complex than it is but once it works users will not notice
505those details. Also, in practice not that much has changed in running the tools
506between \MKII\ and \MKIV\ as we've seen no reason to change the methods.
507
508\stopsection
509
510\startsection[title={A detailed look at \sMTXRUN}]
511
512This section is derived from Taco Hoekwaters presentation and article for the
5132018 \CONTEXT\ meeting. You might want to read this is you want to benefit from
514even the most obscure features. There is a bit of repetition with the previous
515sections but so be it.
516
517% macros specific to this section
518
519\def\highlighted#1#2#3%
520  {\testpage[4]
521   \dontleavehmode
522   \backgroundline[gray]{\tt\strut #1}
523   \nowhitespace
524   \startnarrower[left]
525   \veryraggedright
526   #2\par
527   \doifsomething{#3}{{\it #3}}
528   \stopnarrower}
529
530\definestartstop
531  [options]
532  [before=\blank,
533   after=\blank]
534
535\def\option#1#2%
536  {\highlighted{--#1}{#2}{}}
537
538\definestartstop
539  [mtxrunscripts]
540  [before=\blank,after=\blank]
541
542\def\mtxrunscriptv#1#2#3#4%
543  {\highlighted{#1}{#3}{#4}}
544
545\def\mtxrunscript#1#2#3%
546  {\highlighted{#1}{#3}{}}
547
548\definestartstop
549  [mtxrunenvironment]
550  [before=\blank,
551   after=\blank]
552
553\def\mtxrunenv#1#2%
554  {\highlighted{#1}{#2}{}}
555
556\startsubsection[title=Common flags]
557
558Much of the code inside \MKIV\ can alter its behaviour based on either \quote
559{trackers} (which add debugging information to the terminal and log output) or
560\quote {directives} or \quote {experiments} (for getting code to perform some
561alternate behaviour). Since this also affects the \LUA\ code within \sMTXRUN\
562itself, it makes sense to list these options first.
563
564Trackers enable more extensive status messages on the console or in \CONTEXT\
565additional visual clues. Directives change behaviour that is not part of the
566official interface and have no corresponding commands. Experiments are like
567directives but not official (yet).
568
569\startoptions
570    \option
571        {trackers}
572        {show (known) trackers}
573    \option
574        {directives}
575        {show (known) directives}
576    \option
577        {experiments}
578        {show (known) experiments}
579\stopoptions
580
581Enabling directives, trackers and experiments:
582
583\startoptions
584    \option
585        {trackers=list}
586        {enable given trackers}
587    \option
588        {directives=list}
589        {enable given directives}
590    \option
591        {experiments=list}
592        {enable given experiments}
593\stopoptions
594
595The next tree (hidden) options are converted into \quote {directives} entries,
596that are then enabled. These are just syntactic sugar for the relevant directive.
597
598\startoptions
599    \option
600        {silent[=...]}
601        {sets \type {logs.blocked={\%s}}}
602    \option
603        {errors[=...]}
604        {sets \type {logs.errors={\%s}}}
605    \option
606        {noconsole}
607        {sets \type {logs.target=file}}
608\stopoptions
609
610As you can see here, various directives (and even some trackers) have optional
611arguments, which can make specifying such directives on the command line a bit of
612a challenge. Explaining the details of all the directives is outside of the scope
613of this article, but you can look them up in the \CONTEXT\ source by searching
614for \typ {directives.register} and \typ {trackers.register}.
615
616In verbose mode, \sMTXRUN\ itself gives more messages, and it also enables \typ
617{resolvers.locating}, which is a tracker itself:
618
619\startoptions
620    \option
621        {verbose}
622        {give a bit more info}
623\stopoptions
624
625The \type {--timedlog} (hidden) option starts the \sMTXRUN\ output with a
626timestamp line:
627
628\startoptions
629    \option
630        {timedlog}
631        {prepend output with a timestamp}
632\stopoptions
633
634\stopsubsection
635
636\startsubsection[title=Setup for finding files and configurations]
637
638The next block of options deals with the setup of \sMTXRUN\ itself. You do not
639need to deal with these options unless you are messing with the \CONTEXT\
640distribution yourself instead of relying on a prepackaged solution, or you need
641to use kpathsea for some reason (typically in a \MKII\ environment). In
642particular, \type {--progname} and \type {--tree} are often needed as well when
643using the \type {kpse} options.
644
645\startoptions
646    \option
647        {configurations}
648        {show configuration order, alias \type {--show-configurations}}
649    \option
650        {resolve}
651        {resolve prefixed arguments, see \type {--prefixes}, below}
652\stopoptions
653
654and:
655
656\startoptions
657    \option
658        {usekpse}
659        {use kpse as fallback (when no \MKIV\ and cache installed, often slower)}
660    \option
661        {forcekpse}
662        {force using kpse (handy when no \MKIV\ and cache installed but less
663         functionality)}
664    \option
665        {progname=str}
666        {format or backend}
667    \option
668        {tree=pathtotree}
669        {use given texmf tree (default file: \type {setuptex.tmf})}
670\stopoptions
671
672We don't provide such a \type {.tmf} file in the distribution.
673
674\stopsubsection
675
676\startsubsection[title=Options for finding files and reporting configurations]
677
678Once the configuration setup is done, it makes sense to have a bunch of options
679to use and|/|or query the configuration.
680
681\startoptions
682    \option
683        {locate}
684        {locate given filename in database (default) or system (uses the
685         sub||options \type {--first}, \type {--all} and \type {--detail})}
686    \option
687        {autogenerate}
688        {regenerate databases if needed (handy when used to run context in an
689         editor)}
690    \option
691        {generate}
692        {generate file database}
693    \option
694        {prefixes}
695        {show supported prefixes for file searches}
696    \option
697        {variables}
698        {show configuration variables (uses the sub||option \type {--pattern},
699         and an alias is \type {--show-variables})}
700    \option
701        {expansions}
702        {show configuration variable expansion (uses the sub||options
703         \type{--pattern}, alias \type {--show-expansions})}
704    \option
705        {expand-braces}
706        {expand complex variable}
707    \option
708        {resolve-path}
709        {expand variable (completely resolve paths)}
710    \option
711        {expand-path}
712        {expand variable (resolve paths)}
713    \option
714        {expand-var}
715        {expand variable (resolves references inside variables, alias
716         \type{--expand-variable})}
717    \option
718        {show-path}
719        {show path expansion of \type {...} (alias \type {--path-value})}
720    \option
721        {var-value}
722        {report value of variable (alias \type {--show-value})}
723    \option
724        {find-file}
725        {report file location; it uses the sub||options \type {--all}, \type
726         {--pattern}, and \type {--format}}
727    \option
728        {find-path}
729        {report path of file}
730\stopoptions
731
732Hidden option:
733
734\startoptions
735    \option
736        {format-path}
737        {report format path}
738\stopoptions
739
740\stopsubsection
741
742\startsubsection[title=Running code]
743
744Here we come to the core functionality of \sMTXRUN: running scripts. First
745there are few options that trigger how the running takes place:
746
747\startoptions
748    \option
749        {path=runpath}
750        {go to given path before execution}
751    \option
752        {ifchanged=filename}
753        {only execute when given file has changed (this loads and saves an md5
754         checksum from \type {filename.md5})}
755    \option
756        {iftouched=old,new}
757        {only execute when given file has changed (time stamp)}
758    \option
759        {timedrun}
760        {run a script or program and time its run (external)}
761\stopoptions
762
763Specifying both \type {--iftouched} and \type {--ifchanged} means both are
764tested, and when either one is false, nothing will happen. These options have to
765come before one of the next options:
766
767\startoptions
768    \option
769        {script}
770        {run an mtx script (where \LUA\ is the preferred method); it has the
771         sub||options \typ {--nofiledatabase}, \typ {--autogenerate}, \type
772         {--load}, and \type {--save}. The latter two are currently no|-|ops}
773    \option
774        {execute}
775        {run a script or program externally (\type {texmfstart} method); it has
776         sub||option \type {--noquotes}}
777    \option
778        {internal}
779        {run a script using built|-|in libraries (alias is \type {--ctxlua})}
780    \option
781        {direct}
782        {run an external program; it has the sub||option \type {--noquotes}}
783\stopoptions
784
785Since scripts potentially have their own options, any options intended for
786\sMTXRUN\ itself have to come {\it before} the option that specifies the script
787to run, and options for the script itself have to come {\it after} the option
788that gives the script name. This is especially true when using \type {--script},
789so it is important to check the order of your options.
790
791Of the four above options, \type {--script} is the most important one, since that
792is the one that finds and executes the \LUA\ \sMTXRUN\ scripts provided by the
793distribution. With \typ {--nofiledatabase}, it will not attempt to resolve any
794file names (which means you need either a local script or a full path name). On
795the opposite side, when you also provide \typ {--autogenerate}, it will not only
796attempt to resolve the file name, it will also regenerate the database if it
797cannot find the script on the first try. In a future version of \CONTEXT, the
798\type {--load} and \type {--save} will allow you to save|/|restore the current
799command line in a file for reuse.
800
801The shell return value of \sMTXRUN\ indicates whether the script was found. When
802you specify something like \type {--script base}, \sMTXRUN\ actually searches
803for \type {mtx-base.lua}, \type {mtx-bases.lua}, \type {mtx-t-base.lua}, \type
804{mtx-t-bases.lua}, and \type {base.lua}, in that order. The
805distribution||supplied scripts normally use \type {mtx-<name>.lua} as template.
806The template names with \type {mtx-t-} prefix is reserved for third||party
807scripts, and \type {<name>.lua} is just a last-ditch effort if nothing else
808works. Scripts are looked for in the local path, and in whatever directories the
809configuration variable \type {LUAINPUTS} points to.
810
811The \type {--execute} option exists mostly for the non||\LUA\ {\MKII} scripts
812that still exist in the distribution. It will try to find a matching interpreter
813for non||\LUA\ scripts, and it is aware of a number of distribution||supplied
814scripts so that if you specify \type {--execute texexec}, it knows that what you
815really want to execute is \type {ruby texexec.rb}. Support is present for \RUBY\
816(\type {.rb}, \LUA\ (\type {.lua}), python (\type {.py}) and \PERL\ (\type {.pl})
817scripts (tested in that order). File resolving uses \type {TEXMFSCRIPTS} from the
818configuration. The shell return value of \sMTXRUN\ indicates whether the script
819was found and executed.
820
821The \type {--internal} option uses the file search method of \type {--execute},
822but then assumes this is a \LUA\ script and executes it internally like \type
823{--script}. This is useful if you have a \LUA\ script in an odd location.
824
825The last of the four options, \type {--direct}, directly executes an external
826program. You need to give the full path for binaries not in the current shell
827\type {PATH}, because no searching is done at all. The shell return value of
828\sMTXRUN\ in this case is a boolean based on the return value of
829\type {os.exec()}.
830
831It is also possible to execute bare \LUA\ code directly:
832
833\startoptions
834    \option
835        {evaluate}
836        {run code passed on the command-line (between quotes)}
837\stopoptions
838
839\stopsubsection
840
841\startsubsection[title=Options for maintenance of \sMTXRUN\ itself]
842
843None of these are advertised. Normally developers should be the only ones needing
844them, but if you made a change to one of the distributed libraries (maybe because
845of a beta bug), you may need to run \type {--selfmerge} and \type {--selfupdate}.
846
847\startoptions
848    \option
849        {selfclean}
850        {remove embedded libraries}
851    \option
852        {selfmerge}
853        {update embedded libraries in \type {mtxrun.lua}}
854    \option
855        {selfupdate}
856        {copy \type {mtxlua.lua} to the executable directory, renamed \type
857         {mtxrun}}
858\stopoptions
859
860\stopsubsection
861
862\startsubsection[title=Creating stubs]
863
864Stubs are little shortcuts that live in some binaries directory. For example, the
865content of the \UNIX||style \sCONTEXT\ shell command is:
866
867\starttyping
868#!/bin/sh
869mtxrun --script context "$@"
870\stoptyping
871
872Apart from the \sCONTEXT\ command itself (which is provided by the distribution),
873use of stubs is discouraged. Still, the \sMTXRUN\ options are there because
874sometimes existing workflows depend on executable tool names like \type
875{ctxtools}.
876
877\startoptions
878    \option
879        {makestubs}
880        {create stubs for (context related) scripts}
881    \option
882        {removestubs}
883        {remove stubs (context related) scripts}
884    \option
885        {stubpath=binpath}
886        {paths where stubs will be written}
887    \option
888        {windows}
889        {create windows (mswin) stubs (alias \type {--mswin})}
890    \option
891        {unix}
892        {create unix (linux) stubs (alias \type {--linux})}
893\stopoptions
894
895\stopsubsection
896
897\startsubsection[title=Remaining options]
898
899The remaining options are hard to group into a subcategory. These are the
900advertised options:
901
902\startoptions
903    \option
904        {systeminfo}
905        {show current operating system, processor, et cetera}
906    \option
907        {edit}
908        {launch editor with found file; the editor is taken from the environment
909         variable \type {MTXRUN_EDITOR}, or \type {TEXMFSTART_EDITOR}, or
910         \type {EDITOR}, or as a last resort: \type {gvim}}
911    \option
912        {launch}
913        {launch files like manuals, assumes os support (uses the sub||options
914         \type {--all}, \type {--pattern} and \type {--list})}
915\stopoptions
916
917While these are sort of hidden options:
918
919\startoptions
920    \option
921        {ansi}
922        {colorize output to terminal using \ANSI\ escapes}
923    \option
924        {associate}
925        {launch files like manuals, assumes os support. this function does not do
926         any file searching, so you have to use either a local file or a full
927         path name}
928    \option
929        {exporthelp}
930        {output the \sMTXRUN\ \XML\ help blob (useful for creating man and \HTML\
931         help pages)}
932    \option
933        {fmt}
934        {shortcut for \type {--script base --fmt}}
935    \option
936        {gethelp}
937        {attempt to look up remote \sCONTEXT\ command help (uses the sub||options
938         \type{--command} and \type {--url})}
939    \option
940        {help}
941        {print the \sMTXRUN\ help screen}
942    \option
943        {locale}
944        {force setup of locale; unless you are certain you need this option, stay
945         away from it, because it can interfere massively with \CONTEXT's \LUA\
946         code}
947    \option
948        {make}
949        {(re)create format files (aliases are \type {--ini} and \type {--compile})}
950    \option
951        {platform}
952        {(alias is \type {--show-platform})}
953    \option
954        {run}
955        {shortcut for \type {--script base --run}}
956    \option
957        {version}
958        {print \sMTXRUN\ version}
959\stopoptions
960
961\stopsubsection
962
963\startsubsection[title=Known scripts]
964
965When you run \type {mtxrun --scripts}, it will output a list of \quote {known}
966scripts. The definition of \quote {known} is important here: the list comprises
967the scripts that are present in the same directory as \type {mtx-context.lua}
968that do not have an extra hyphen in the name (like \type {mtx-t-...}scripts would
969have). In a normal installation, this means it \quote {knows} almost all the
970scripts that are distributed with \CONTEXT. Note: it skips over any files from
971the distribution that do have an extra hyphen, like the \type {mtx-server}
972support scripts.
973
974Since this section is about \sMTXRUN, I'll just present the list of the scripts
975that are \quote {known} in the current \CONTEXT\ beta as output by \sMTXRUN\
976itself, and not get into detail about all of the script functionality (they all
977have \type {--help} options if you want to find out more). Where we still felt the
978need to explain something, there is an extra bit of text in italics.
979
980\startmtxrunscripts
981\mtxrunscript
982    {babel}
983    {1.20}
984    {Babel Input To UTF Conversion}
985\mtxrunscript
986    {base}
987    {1.35}
988    {ConTeXt TDS Management Tool (aka luatools)}
989\mtxrunscript
990    {bibtex}
991    {}
992    {bibtex helpers (obsolete)}
993\mtxrunscript
994    {cache}
995    {0.10}
996    {ConTeXt & MetaTeX Cache Management}
997\mtxrunscript
998    {chars}
999    {0.10}
1000    {MkII Character Table Generators}
1001\mtxrunscriptv
1002    {check}
1003    {0.10}
1004    {Basic ConTeXt Syntax Checking}
1005    {Occasionally useful on big projects, but be warned that it does not actually
1006     run any \TEX\ engine, so it is not 100\% reliable.}
1007\mtxrunscriptv
1008    {colors}
1009    {0.10}
1010    {ConTeXt Color Management}
1011    {This displays icc color tables by name}
1012\mtxrunscriptv
1013    {convert}
1014    {0.10}
1015    {ConTeXT Graphic Conversion Helpers}
1016    {A wrapper around ghostscript and imagemagick that offers some extra (batch
1017     processing) functionality.}
1018\mtxrunscript
1019    {dvi}
1020    {0.10}
1021    {ConTeXt DVI Helpers}
1022\mtxrunscriptv
1023    {epub}
1024    {1.10}
1025    {ConTeXt EPUB Helpers}
1026    {The EPUB manual (\type {epub-mkiv.pdf}) explains how to use this script.}
1027\mtxrunscriptv
1028    {evohome}
1029    {1.00}
1030    {Evohome Fetcher}
1031    {Evohome is a domotica system that controls your central heating}
1032\mtxrunscript
1033    {fcd}
1034    {1.00}
1035    {Fast Directory Change}
1036\mtxrunscriptv
1037    {flac}
1038    {0.10}
1039    {ConTeXt Flac Helpers}
1040    {Extracts information from \type{.flac} audio files into an \XML\ index.}
1041\mtxrunscript
1042    {fonts}
1043    {0.21}
1044    {ConTeXt Font Database Management}
1045\mtxrunscript
1046    {grep}
1047    {0.10}
1048    {Simple Grepper}
1049\mtxrunscript
1050    {interface}
1051    {0.13}
1052    {ConTeXt Interface Related Goodies}
1053\mtxrunscript
1054    {metapost}
1055    {0.10}
1056    {MetaPost to PDF processor}
1057\mtxrunscript
1058    {metatex}
1059    {0.10}
1060    {MetaTeX Process Management (obsolete)}
1061\mtxrunscript
1062    {modules}
1063    {1.00}
1064    {ConTeXt Module Documentation Generators}
1065\mtxrunscriptv
1066    {package}
1067    {0.10}
1068    {Distribution Related Goodies}
1069    {This script is used to create the generic \CONTEXT\ code used in
1070     \LUA\LATEX~c.s.}
1071\mtxrunscriptv
1072    {patterns}
1073    {0.20}
1074    {ConTeXt Pattern File Management}
1075    {Hyphenation patterns, that is \unknown}
1076\mtxrunscript
1077    {pdf}
1078    {0.10}
1079    {ConTeXt PDF Helpers}
1080\mtxrunscript
1081    {plain}
1082    {1.00}
1083    {Plain TeX Runner}
1084\mtxrunscript
1085    {profile}
1086    {1.00}
1087    {ConTeXt MkIV LuaTeX Profiler}
1088\mtxrunscript
1089    {rsync}
1090    {0.10}
1091    {Rsync Helpers}
1092\mtxrunscript
1093    {scite}
1094    {1.00}
1095    {Scite Helper Script}
1096\mtxrunscriptv
1097    {server}
1098    {0.10}
1099    {Simple Webserver For Helpers}
1100    {There are some subscripts associated with this.}
1101\mtxrunscript
1102    {synctex}
1103    {1.00}
1104    {ConTeXt SyncTeX Checker}
1105\mtxrunscript
1106    {texworks}
1107    {1.00}
1108    {TeXworks Startup Script}
1109\mtxrunscript
1110    {timing}
1111    {0.10}
1112    {ConTeXt Timing Tools}
1113\mtxrunscript
1114    {tools}
1115    {1.01}
1116    {Some File Related Goodies}
1117\mtxrunscript
1118    {unicode}
1119    {1.02}
1120    {Checker for \type{char-def.lua}}
1121\mtxrunscript
1122    {unzip}
1123    {0.10}
1124    {Simple Unzipper}
1125\mtxrunscript
1126    {update}
1127    {1.03}
1128    {ConTeXt Minimals Updater}
1129\mtxrunscript
1130    {watch}
1131    {1.00}
1132    {ConTeXt Request Watchdog}
1133\mtxrunscriptv
1134    {youless}
1135    {1.10}
1136    {YouLess Fetcher}
1137    {YouLess is a domotica system that tracks your home energy use.}
1138\stopmtxrunscripts
1139
1140\stopsubsection
1141
1142\startsubsection[title=Writing your own]
1143
1144A well|-|written script has some required internal structure. It should start with
1145a module definition block. This gives some information about the module, but more
1146importantly, it prevents double|-|loading.
1147
1148Here is an example:
1149
1150\starttyping
1151if not modules then modules = { } end
1152
1153modules ['mtx-envtest'] = {
1154    version   = 0.100,
1155    comment   = "companion to mtxrun.lua",
1156    author    = "Taco Hoekwater",
1157    copyright = "Taco Hoekwater",
1158    license   = "bsd"
1159}
1160\stoptyping
1161
1162Next up is a variable containing the help information. The help information is actually
1163a bit of \XML\ stored in \LUA\ string. In the full example listing at the end of this
1164article, you can see what the internal structure is supposed to be like.
1165
1166\starttyping
1167local helpinfo = [[
1168<?xml version="1.0"?>
1169<application>
1170  ....
1171</application>
1172]]
1173\stoptyping
1174
1175And this help information is then used to create an instance of an \type
1176{application} table.
1177
1178\starttyping
1179local application = logs.application {
1180    name     = "envtest",
1181    banner   = "Mtxrun environment demo",
1182    helpinfo = helpinfo,
1183}
1184\stoptyping
1185
1186After this call, the \type {application} table contains (amongst some other
1187things) three functions that are very useful:
1188
1189\startmtxrunenvironment
1190\mtxrunenv
1191    {identify()}
1192    {Prints out a banner identifying the current script to the user.}
1193\mtxrunenv
1194    {report(str)}
1195    {For printing information to the terminal with the script name as prefix.}
1196\mtxrunenv
1197    {export()}
1198    {Prints the \type {helpinfo} to the terminal, so it can easily be used for
1199     documentation purposes.}
1200\stopmtxrunenvironment
1201
1202Next up, it is good to define your scripts' functionality in functions in a
1203private table. This prevents namespace pollution, and looks like this:
1204
1205\starttyping
1206scripts          = scripts         or { }
1207scripts.envtest  = scripts.envtest or { }
1208
1209function scripts.envtest.runtest()
1210    application.report("script name is " .. environment.ownname)
1211end
1212\stoptyping
1213
1214And finally, identify the current script, followed by handling the provided
1215options (usually with an \type {if}||\type {else} statement).
1216
1217\starttyping
1218if environment.argument("exporthelp") then
1219   application.export()
1220elseif environment.argument('test') then
1221   scripts.envtest.runtest()
1222else
1223    application.help()
1224end
1225\stoptyping
1226
1227\stopsubsection
1228
1229\startsubsection[title=Script environment]
1230
1231\sMTXRUN\ includes lots of the internal \LUA\ helper libraries from \CONTEXT. We
1232actually maintain a version of the script without all those libraries included,
1233and before every (beta) \CONTEXT\ release, an amalgamated version of \sMTXRUN\ is
1234added to the distribution. In the merging process, all comments are stripped from
1235the embedded libraries, so if you want to know details, it is better to look in
1236the original \LUA\ source file.
1237
1238Inside \sMTXRUN, the full list of embedded libraries can be queried via the array
1239\type {own.libs}:
1240
1241\startalign[flushleft]
1242l-lua.lua l-macro.lua l-sandbox.lua l-package.lua l-lpeg.lua
1243l-function.lua l-string.lua l-table.lua l-io.lua l-number.lua l-set.lua l-os.lua
1244l-file.lua l-gzip.lua l-md5.lua l-url.lua l-dir.lua l-boolean.lua l-unicode.lua
1245l-math.lua util-str.lua util-tab.lua util-fil.lua util-sac.lua util-sto.lua
1246util-prs.lua util-fmt.lua trac-set.lua trac-log.lua trac-inf.lua trac-pro.lua
1247util-lua.lua util-deb.lua util-tpl.lua util-sbx.lua util-mrg.lua util-env.lua
1248luat-env.lua lxml-tab.lua lxml-lpt.lua lxml-mis.lua lxml-aux.lua lxml-xml.lua
1249trac-xml.lua data-ini.lua data-exp.lua data-env.lua data-tmp.lua data-met.lua
1250data-res.lua data-pre.lua data-inp.lua data-out.lua data-fil.lua data-con.lua
1251data-use.lua data-zip.lua data-tre.lua data-sch.lua data-lua.lua data-aux.lua
1252data-tmf.lua data -lst.lua util-lib.lua luat-sta.lua luat-fmt.lua
1253\stopalign
1254
1255In fact, the \LUA\ table \type {own} contains some other useful stuff like the
1256script's actual disk name and location (\type {own.name} and \type {own.path})
1257and some internal variables like a list of all the locations it searches for its
1258embedded libraries (\type {own.list}), which is used by the \type {--selfmerge}
1259option and also allows the non||amalgamated version to run (since otherwise \type
1260{--selfmerge} could not be bootstrapped).
1261
1262\sMTXRUN\ offers a programming environment that makes it easy to write \LUA\
1263script. The most important element of that environment is a \LUA\ table that is
1264conveniently called \type {environment} (\type {util-env} does the actual work of
1265setting that up).
1266
1267The bulk of \type {environment} consists of functions and variables that deal
1268with the command||line given by the user as \sMTXRUN\ does quite a bit of work on
1269the given command||line. The goal is to safely tuck all the given options into
1270the \type {arguments} and \type {files} tables. This work is done by two
1271functions called \type {initializearguments()} and \type {splitarguments()}.
1272These functions are part of the \type{environment} table, but you should not need
1273them as they have been called already once control is passed on to your script.
1274
1275\startmtxrunenvironment
1276\mtxrunenv
1277    {arguments}
1278    {These are the processed options to the current script. The keys are option
1279     names (without the leading dashes) and the value is either \type {true} or a
1280     string with one level of shell quotes removed.}
1281\mtxrunenv
1282    {files}
1283    {This array holds all the non||option arguments to the current script.
1284     Typically, those are supposed to be files, but they could be any text,
1285     really.}
1286\mtxrunenv
1287    {getargument(name,partial)}
1288    {Queries the \type {arguments} table using a function. Its main reason for
1289     existence is the \type {partial} argument, which allows scripts to accept
1290     shortened command||line options (alias: \type {argument()}).}
1291\mtxrunenv
1292    {setargument(name,value)}
1293    {Sets a value in the \type {arguments} table. This can be useful in
1294     complicated scripts with default options.}
1295\stopmtxrunenvironment
1296
1297In case you need access to the full command||line, there are some possibilities:
1298
1299\startmtxrunenvironment
1300\mtxrunenv
1301    {arguments_after}
1302    {These are the unquoted but otherwise unprocessed arguments to your script as
1303     an array.}
1304\mtxrunenv
1305    {arguments_before}
1306    {These are the unquoted but otherwise unprocessed arguments to \sMTXRUN\
1307     before your scripts' name (so the last entry is usually \type {--script}).}
1308\mtxrunenv
1309    {rawarguments}
1310    {This is the whole unprocessed command||line as an array.}
1311\mtxrunenv
1312    {originalarguments}
1313    {Like \type{rawarguments}, but with some top||level quotes removed.}
1314\mtxrunenv
1315    {reconstructcommandline(arg,noquote)}
1316    {Tries to reconstruct a command||line from its arguments. It uses \type
1317     {originalarguments} if no \type {arg} is given. Take care: due to the
1318     vagaries of shell command||line processing, this may or may not work when
1319     quoting is involved.}
1320\stopmtxrunenvironment
1321
1322\type{environment} also stores various bits of information you may find useful:
1323
1324\startmtxrunenvironment
1325\mtxrunenv
1326    {validengines}
1327    {This table contains keys for \type {luatex} and \type {luajittex}. This is
1328     only relevant when \sMTXRUN\ itself is called via \LUATEX's \type {luaonly}
1329     option.}
1330\mtxrunenv
1331    {basicengines}
1332    {This table maps executable names to \type{validengines} entries.}
1333\mtxrunenv
1334    {default_texmfcnf}
1335    {This is the \type {texmfcnf} value from \type {kpathsea}, processed for use
1336     with \MKIV\ in the unlikely event this is needed.}
1337\mtxrunenv
1338    {homedir}
1339    {The user's home directory.}
1340\mtxrunenv
1341    {ownbin}
1342    {The name of the binary used to call \sMTXRUN.}
1343\mtxrunenv
1344    {ownmain}
1345    {The mapped version of \type {ownbin}.}
1346\mtxrunenv
1347    {ownname}
1348    {Full name of this instance of \sMTXRUN.}
1349\mtxrunenv
1350    {ownpath}
1351    {The path this  instance of \sMTXRUN\ resides in.}
1352\mtxrunenv
1353    {texmfos}
1354    {Operating system root directory path.}
1355\mtxrunenv
1356    {texos}
1357    {Operating system root directory name.}
1358\mtxrunenv
1359    {texroot}
1360    {\CONTEXT\ root directory path.}
1361\stopmtxrunenvironment
1362
1363As well as some functions:
1364
1365\startmtxrunenvironment
1366\mtxrunenv
1367    {texfile(filename)}
1368    {Locates a {\TEX} file.}
1369\mtxrunenv
1370    {luafile(filename)}
1371    {Locates a \LUA\ file.}
1372\mtxrunenv
1373    {loadluafile(filename,version)}
1374    {Locates, compiles and loads a \LUA\ file, possibly in compressed \type {.luc}
1375     format. In the compressed case, it uses the \type {version} to make sure the
1376     compressed form is up||to||date.}
1377\mtxrunenv
1378    {luafilechunk(filename,silent,macros)}
1379    {Locates and compiles a \LUA\ file, returning its contents as data.}
1380\mtxrunenv
1381    {make_format(name,arguments)}
1382    {Creates a format file and stores it in the \CONTEXT\ cache, used by \type
1383     {mtxrun --make}.}
1384\mtxrunenv
1385    {relativepath(path,root)}
1386    {Returns a modified version of \type {root} based on the relative path in
1387     \type {path}.}
1388\mtxrunenv
1389    {run_format(name,data,more)}
1390    {Run a \TEX\ format file.}
1391\stopmtxrunenvironment
1392
1393\stopsubsection
1394
1395\startsubsection[title=Shell return values]
1396
1397As explained earlier, the shell return value of \sMTXRUN\ normally indicates
1398whether the script was found. If you are running a \CONTEXT\ release newer than
1399September 2018 and want to modify the shell return value from within your script,
1400you can use \type {os.exitcode}. Whatever value you assign to that variable will
1401be the shell return value of your script.
1402
1403\stopsubsection
1404
1405\stopsection
1406
1407\startsubject[title={Colofon}]
1408
1409\starttabulate[|B|p|]
1410    \NC author    \NC \documentvariable{author},
1411                      \documentvariable{affiliation},
1412                      \documentvariable{location} \NC \NR
1413    \NC           \NC Taco Hoekwater, extra \sMTXRUN\ section \NC \NR
1414    \NC version   \NC \currentdate \NC \NR
1415    \NC website   \NC \documentvariable{website} \endash\
1416                      \documentvariable{support} \NC \NR
1417    \NC copyright \NC \symbol[cc][cc-by-sa] \NC \NR
1418\stoptabulate
1419
1420\stopsubject
1421
1422\stopdocument
1423