diff options
Diffstat (limited to 'doc/context/sources/general/manuals/tools/tools-mkiv.tex')
| -rw-r--r-- | doc/context/sources/general/manuals/tools/tools-mkiv.tex | 501 |
1 files changed, 501 insertions, 0 deletions
diff --git a/doc/context/sources/general/manuals/tools/tools-mkiv.tex b/doc/context/sources/general/manuals/tools/tools-mkiv.tex new file mode 100644 index 000000000..5f20e6985 --- /dev/null +++ b/doc/context/sources/general/manuals/tools/tools-mkiv.tex @@ -0,0 +1,501 @@ +% language=uk + +% author : Hans Hagen, PRAGMA ADE, NL +% license : Creative Commons, Attribution-NonCommercial-ShareAlike 3.0 Unported + +\usemodule[abr-02] + +\setuplayout + [width=middle, + height=middle, + backspace=2cm, + topspace=1cm, + footer=0pt, + bottomspace=2cm] + +\definecolor + [DocumentColor] + [r=.5] + +\setuptype + [color=DocumentColor] + +\setuptyping + [color=DocumentColor] + +\usetypescript + [iwona] + +\setupbodyfont + [iwona] + +\setuphead + [chapter] + [style=\bfc, + color=DocumentColor] + +\setuphead + [section] + [style=\bfb, + color=DocumentColor] + +\setupinteraction + [hidden] + +\setupwhitespace + [big] + +\setupheadertexts + [] + +\setupheadertexts + [] + [{\DocumentColor \type {luatools mtxrun context}\quad\pagenumber}] + +\usesymbols[cc] + +\def\sTEXMFSTART{\type{texmfstart}} +\def\sLUATOOLS {\type{luatools}} +\def\sMTXRUN {\type{mtxrun}} +\def\sCONTEXT {\type{context}} +\def\sKPSEWHICH {\type{kpsewhich}} +\def\sMKTEXLSR {\type{mktexlsr}} +\def\sXSLTPROC {\type{xsltproc}} + +\usemodule[narrowtt] + +\startdocument + [metadata:author=Hans Hagen, + metadata:title={Tools: luatools, mtxrun, context}, + author=Hans Hagen, + affiliation=PRAGMA ADE, + location=Hasselt NL, + title=Tools, + extra-1=luatools, + extra-2=mtxrun, + extra-3=context, + support=www.contextgarden.net, + website=www.pragma-ade.nl] + +\startMPpage + StartPage ; + picture p ; p := image ( + for i=1 upto 21 : + for j=1 upto 30 : + drawarrow (fullcircle rotated uniformdeviate 360) scaled 10 shifted (i*15,j*15) ; + endfor ; + endfor ; + ) ; + p := p ysized (bbheight(Page)-4mm) ; + fill Page enlarged 2mm withcolor \MPcolor{DocumentColor} ; + draw p shifted (center Page - center p) withpen pencircle scaled 2 withcolor .5white ; + numeric dx ; dx := bbwidth(Page)/21 ; + numeric dy ; dy := bbheight(Page)/30 ; + p := textext("\tt\bf\white\getvariable{document}{extra-1}") xsized(14*dx) ; + p := p shifted (-lrcorner p) shifted lrcorner Page shifted (-1dx,8dy) ; + draw p ; + p := textext("\tt\bf\white\getvariable{document}{extra-2}") xsized(14*dx) ; + p := p shifted (-lrcorner p) shifted lrcorner Page shifted (-1dx,5dy) ; + draw p ; + p := textext("\tt\bf\white\getvariable{document}{extra-3}") xsized(14*dx) ; + p := p shifted (-lrcorner p) shifted lrcorner Page shifted (-1dx,2dy) ; + draw p ; + setbounds currentpicture to Page ; + StopPage +\stopMPpage + +\startsubject[title=Contents] + +\placelist[section][alternative=a] + +\stopsubject + +\startsection[title={Remark}] + +This manual is work in progress. Feel free to submit additions or corrections. +Before you start reading, it is good to know that in order to get starting with +\CONTEXT, the easiest way to do that is to download the standalone distribution +from \type {contextgarden.net}. After that you only need to make sure that \type +{luatex} is in your path. The main command you use is then \type {context} and +normally it does all the magic it needs itself. + +\stopsection + +\startsection[title={Introduction}] + +Right from the start \CONTEXT\ came with programs that managed the process of +\TEX-ing. Although you can perfectly well run \TEX\ directly, it is a fact that +often multiple runs are needed as well as that registers need to be sorted. +Therefore managing a job makes sense. + +First we had \TEXEXEC\ and \TEXUTIL, and both were written in \MODULA, and as +this language was not supported on all platforms the programs were rewritten in +\PERL. Following that a few more tools were shipped with \CONTEXT. + +When we moved on to \RUBY\ all the \PERL\ scripts were rewritten and when +\CONTEXT\ \MKIV\ showed up, \LUA\ replaced \RUBY. As we use \LUATEX\ this means +that currently the tools and the main program share the same language. For \MKII\ +scripts like \TEXEXEC\ will stay around but the idea is that there will be \LUA\ +alternatives for them as well. + +Because we shipped many scripts, and because the de facto standard \TEX\ +directory structure expects scripts to be in certain locations we not only ship +tools but also some more generic scripts that locate and run these tools. + +\stopsection + +\startsection[title={The location}] + +Normally you don't need to know so many details about where the scripts +are located but here they are: + +\starttyping +<texroot>/scripts/context/perl +<texroot>/scripts/context/ruby +<texroot>/scripts/context/lua +<texroot>/scripts/context/stubs +\stoptyping + +This hierarchy was actually introduced because \CONTEXT\ was shipped with a bunch +of tools. As mentioned, we nowadays focus on \LUA\ but we keep a few of the older +scripts around in the \PERL\ and \RUBY\ paths.Now, if you're only using \CONTEXT\ +\MKIV, and this is highly recommended, you can forget about all but the \LUA\ +scripts. + +\stopsection + +\startsection[title={The traditional finder}] + +When you run scripts multiple times, and in the case of \CONTEXT\ they are even +run inside other scripts, you want to minimize the startup time. Unfortunately +the traditional way to locate a script, using \sKPSEWHICH, is not that fast, +especially in a setup with many large trees Also, because not all tasks can be +done with the traditional scripts (take format generation) we provided a runner +that could deal with this: \sTEXMFSTART. As this script was also used in more +complex workflows, it had several tasks: + +\startitemize[packed] +\item locate scripts in the distribution and run them using the right + interpreter +\item do this selectively, for instance identify the need for a run using + checksums for potentially changed files (handy for image conversion) +\item pass information to child processes so that lookups are avoided +\item choose a distribution among several installed versions (set the root + of the \TEX\ tree) +\item change the working directory before running the script +\item resolve paths and names on demand and launch programs with arguments + where names are expanded controlled by prefixes (handy for + \TEX-unware programs) +\item locate and open documentation, mostly as part the help systems in + editors, but also handy for seeing what configuration file is used +\item act as a \KPSEWHICH\ server cq.\ client (only used in special cases, + and using its own database) +\stopitemize + +Of course there were the usual more obscure and undocumented features as +well. The idea was to use this runner as follows: + +\starttyping +texmfstart texexec <further arguments> +texmfstart --tree <rootoftree> texexec <further arguments> +\stoptyping + +These are just two ways of calling this program. As \sTEXMFSTART\ can initialize +the environment as well, it is basically the only script that has to be present +in the binary path. This is quite comfortable as this avoids conflicts in names +between the called scripts and other installed programs. + +Of course calls like above can be wrapped in a shell script or batch file without +penalty as long as \sTEXMFSTART\ itself is not wrapped in a caller script that +applies other inefficient lookups. If you use the \CONTEXT\ minimals you can be +sure that the most efficient method is chosen, but we've seen quite inefficient +call chains elsewhere. + +In the \CONTEXT\ minimals this script has been replaced by the one we will +discuss in the next section: \sMTXRUN\ but a stub is still provided. + +\stopsection + +\startsection[title={The current finder}] + +In \MKIV\ we went a step further and completely abandoned the traditional lookup +methods and do everything in \LUA. As we want a clear separation between +functionality we have two main controlling scripts: \sMTXRUN\ and \sLUATOOLS. The +last name may look somewhat confusing but the name is just one on in a series. +\footnote {We have \type {ctxtools}, \type {exatools}, \type {mpstools}, \type +{mtxtools}, \type {pdftools}, \type {rlxtools}, \type {runtools}, \type +{textools}, \type {tmftools} and \type {xmltools}. Most if their funtionality is +already reimplemented.} + +In \MKIV\ the \sLUATOOLS\ program is nowadays seldom used. It's just a drop in +for \sKPSEWHICH\ plus a bit more. In that respect it's rather dumb in that it +does not use the database, but clever at the same time because it can make one +based on the little information available when it runs. It can also be used to +generate format files either or not using \LUA\ stubs but in practice this is not +needed at all. + +For \CONTEXT\ users, the main invocation of this tool is when the \TEX\ tree is +updated. For instance, after adding a font to the tree or after updating +\CONTEXT, you need to run: + +\starttyping +mtxrun --generate +\stoptyping + +After that all tools will know where to find stuff and how to behave well within +the tree. This is because they share the same code, mostly because they are +started using \sMTXRUN. For instance, you process a file with: + +\starttyping +mtxrun --script context <somefile> +\stoptyping + +Because this happens often, there's also a shortcut: + +\starttyping +context <somefile> +\stoptyping + +But this does use \sMTXRUN\ as well. The help information of \sMTXRUN\ is rather +minimalistic and if you have no clue what an option does, you probably never +needed it anyway. Here we discuss a few options. We already saw that we can +explicitly ask for a script: + +\starttyping +mtxrun --script context <somefile> +\stoptyping + +but + +\starttyping +mtxrun context <somefile> +\stoptyping + +also works. However, by using \type {--script} you limit te lookup to the valid +\CONTEXT\ \MKIV\ scripts. In the \TEX\ tree these have names prefixed by \type +{mtx-} and a lookup look for a plural as well. So, the next two lookups are +equivalent: + +\starttyping +mtxrun --script font +mtxrun --script fonts +\stoptyping + +Both will run \type {mtx-fonts.lua}. Actually, this is one of the scripts that +you might need when your font database is somehow outdated and not updated +automatically: + +\starttyping +mtxrun --script fonts --reload --force +\stoptyping + +Normally \sMTXRUN\ is all you need in order to run a script. However, there are a +few more options: + +\ctxlua{os.execute("mtxrun > tools-mkiv-help.tmp")} + +\typefile[ntyping]{tools-mkiv-help.tmp} + +Don't worry,you only need those obscure features when you integrate \CONTEXT\ in +for instance a web service or when you run large projects where runs and paths +take special care. + +\stopsection + +\startsection[title={Updating}] + +There are two ways to update \CONTEXT\ \MKIV. When you manage your +trees yourself or when you use for instance \TEXLIVE, you act as +follows: + +\startitemize[packed] +\item download the file cont-tmf.zip from \type {www.pragma-ade.com} or elsewhere +\item unzip this file in a subtree, for instance \type {tex/texmf-local} +\item run \type {mtxrun --generate} +\item run \type {mtxrun --script font --reload} +\item run \type {mtxrun --script context --make} +\stopitemize + +Or shorter: + +\startitemize[packed] +\item run \type {mtxrun --generate} +\item run \type {mtxrun font --reload} +\item run \type {context --make} +\stopitemize + +Normally these commands are not even needed, but they are a nice test if your +tree is still okay. To some extend \sCONTEXT\ is clever enough to decide if the +databases need to be regenerated and|/|or a format needs to be remade and|/|or if +a new font database is needed. + +Now, if you also want to run \MKII, you need to add: + +\startitemize[packed] +\item run \type {mktexlsr} +\item run \type {texexec --make} +\stopitemize + +The question is, how to act when \sLUATOOLS\ and \sMTXRUN\ have been updated +themselves? In that case, after unzipping the archive, you need to do the +following: + +\startitemize[packed] +\item run \type {luatools --selfupdate} +\item run \type {mtxrun --selfupdate} +\stopitemize + +For quite a while we shipped so called \CONTEXT\ minimals. These zip files +contained only the resources and programs that made sense for running \CONTEXT. +Nowadays the minimals are installed and synchronized via internet. \footnote +{This project was triggered by Mojca Miklavec who is also charge of this bit of +the \CONTEXT\ infrastructure. More information can be found at \type +{contextgarden.net}.} You can just run the installer again and no additional +commands are needed. In the console you will see several calls to \sMTXRUN\ and +\sLUATOOLS\ fly by. + +\stopsection + +\startsection[title={The tools}] + +We only mention the tools here. The most important ones are \sCONTEXT\ and \type +{fonts}. You can ask for a list of installed scripts with: + +\starttyping +mtxrun --script +\stoptyping + +On my machine this gives: + +\ctxlua{os.execute("mtxrun --script > tools-mkiv-help.tmp")} + +\typefile[ntyping]{tools-mkiv-help.tmp} + +The most important scripts are \type {mtx-fonts} and \type {mtx-context}. By +default fonts are looked up by filename (the \type {file:} prefix before font +names in \CONTEXT\ is default). But you can also lookup fonts by name (\type +{name:}) or by specification (\type {spec:}). If you want to use these two +methods, you need to generate a font database as mentioned in the previous +section. You can also use the font tool to get information about the fonts +installed on your system. + +\stopsection + +\startsection[title={Running \CONTEXT}] + +The \sCONTEXT\ tool is what you will use most as it manages your +run. + +\ctxlua{os.execute("context > tools-mkiv-help.tmp")} + +\typefile[ntyping]{tools-mkiv-help.tmp} + +There are few exert options too: + +\ctxlua{os.execute("context --expert > tools-mkiv-help.tmp")} + +\typefile[ntyping]{tools-mkiv-help.tmp} + +You might as well forget about these unless you are one of the +\CONTEXT\ developers. + +\stopsection + +\startsection[title={Prefixes}] + +A handy feature of \sMTXRUN\ (and as most features an inheritance of +\sTEXMFSTART) is that it will resolve prefixed arguments. This can be of help +when you run programs that are unaware of the \TEX\ tree but nevertheless need to +locate files in it. + +\ctxlua{os.execute("mtxrun --prefixes > tools-mkiv-help.tmp")} + +\typefile[ntyping]{tools-mkiv-help.tmp} + +An example is: + +\starttyping +mtxrun --execute xsltproc file:whatever.xsl file:whatever.xml +\stoptyping + +The call to \sXSLTPROC\ will get two arguments, being the complete path to the +files (given that it can be resolved). This permits you to organize the files in +a similar was as \TEX\ files. + +\stopsection + +\startsection[title={Stubs}] + +As the tools are written in the \LUA\ language we need a \LUA\ interpreter and or +course we use \LUATEX\ itself. On \UNIX\ we can copy \sLUATOOLS\ and \sMTXRUN\ to +files in the binary path with the same name but without suffix. Starting them in +another way is a waste of time, especially when \sKPSEWHICH\ is used to find +then, something which is useless in \MKIV\ anyway. Just use these scripts +directly as they are self contained. + +For \sCONTEXT\ and other scripts that we want convenient access to, stubs are +needed, like: + +\starttyping +#!/bin/sh +mtxrun --script context "$@" +\stoptyping + +This is also quite efficient as the \sCONTEXT\ script \type {mtx-context} is +loaded in \sMTXRUN\ and uses the same database. + +On \WINDOWS\ you can copy the scripts as|-|is and associate the suffix with +\LUATEX\ (or more precisely: \type {texlua}) but then all \LUA\ script will be +run that way which is not what you might want. + +In \TEXLIVE\ stubs for starting scripts were introduced by Fabrice Popineau. Such +a stub would start for instance \sTEXMFSTART, that is: it located the script +(\PERL\ or \RUBY) in the \TEX\ tree and launched it with the right interpreter. +Later we shipped pseudo binaries of \sTEXMFSTART: a \RUBY\ interpreter plus +scripts wrapped into a self contained binary. + +For \MKIV\ we don't need such methods and started with simple batch files, +similar to the \UNIX\ startup scripts. However, these have the disadvantage that +they cannot be used in other batch files without using the \type {start} command. +In \TEXLIVE\ this is taken care of by a small binary written bij T.M.\ Trzeciak +so on \TEXLIVE\ 2009 we saw a call chain from \type {exe} to \type {cmd} to \type +{lua} which is somewhat messy. + +This is why we now use an adapted and stripped down version of that program that +is tuned for \sMTXRUN, \sLUATOOLS\ and \sCONTEXT. So, we moved from the original +\type {cmd} based approach to an \type {exe} one. + +\starttyping +mtxrun.dll +mtxrun.exe +\stoptyping + +You can copy \type {mtxrun.exe} to for instance \type {context.exe} and it will +still use \sMTXRUN\ for locating the right script. It also takes care of mapping +\sTEXMFSTART\ to \sMTXRUN. So we've removed the intermediate \type {cmd} step, +can not run the script as any program, and most of all, we're as efficient as can +be. + +Of course this program is only meaningful for the \CONTEXT\ approach to tools. + +It may all sound more complex than it is but once it works users will not notice +those details. Als, in practice not that much has changed in running the tools +between \MKII\ and \MKIV\ as we've seen no reason to change the methods. + +\stopsection + +\startsubject[title={Colofon}] + +\starttabulate[|B|p|] + \NC author \NC \documentvariable{author}, + \documentvariable{affiliation}, + \documentvariable{location} \NC \NR + \NC version \NC \currentdate \NC \NR + \NC website \NC \documentvariable{website} \endash\ + \documentvariable{support} \NC \NR + \NC copyright \NC \symbol[cc][cc-by-sa-nc] \NC \NR +\stoptabulate + +\stopsubject + +\stopdocument |