cld-gettingstarted.tex /size: 11 Kb    last modification: 2021-10-28 13:50
1% language=us runpath=texruns:manuals/cld
2
3\startcomponent cld-gettingstarted
4
5\environment cld-environment
6
7\startchapter[title=Getting started]
8
9\startsection[title=Some basics]
10
11\index{processing}
12
13I assume that you have either the so called \CONTEXT\ standalone (formerly known
14as minimals) installed or \TEXLIVE. You only need \LUATEX\ and can forget about
15installing \PDFTEX\ or \XETEX, which saves you some megabytes and hassle. Now,
16from the users perspective a \CONTEXT\ run goes like:
17
18\starttyping
19context yourfile
20\stoptyping
21
22and by default a file with suffix \type {tex}, \type {mkvi} or \type {mkvi} will
23be processed. There are however a few other options:
24
25\starttyping
26context yourfile.xml
27context yourfile.rlx --forcexml
28context yourfile.lua
29context yourfile.pqr --forcelua
30context yourfile.cld
31context yourfile.xyz --forcecld
32context yourfile.mp
33context yourfile.xyz --forcemp
34\stoptyping
35
36When processing a \LUA\ file the given file is loaded and just processed. This
37options will seldom be used as it is way more efficient to let \type {mtxrun}
38process that file. However, the last two variants are what we will discuss here.
39The suffix \type {cld} is a shortcut for \CONTEXT\ \LUA\ Document.
40
41A simple \type {cld} file looks like this:
42
43\starttyping
44context.starttext()
45context.chapter("Hello There!")
46context.stoptext()
47\stoptyping
48
49So yes, you need to know the \CONTEXT\ commands in order to use this mechanism.
50In spite of what you might expect, the codebase involved in this interface is not
51that large. If you know \CONTEXT, and if you know how to call commands, you
52basically can use this \LUA\ method.
53
54The examples that I will give are either (sort of) standalone, i.e.\ they are
55dealt with from \LUA, or they are run within this document. Therefore you will
56see two patterns. If you want to make your own documentation, then you can use
57this variant:
58
59\starttyping
60\startbuffer
61context("See this!")
62\stopbuffer
63
64\typebuffer \ctxluabuffer
65\stoptyping
66
67I use anonymous buffers here but you can also use named ones. The other variant
68is:
69
70\starttyping
71\startluacode
72context("See this!")
73\stopluacode
74\stoptyping
75
76This will process the code directly. Of course we could have encoded this
77document completely in \LUA\ but that is not much fun for a manual.
78
79\stopsection
80
81\startsection[title=The main command]
82
83There are a few rules that you need to be aware of. First of all no syntax
84checking is done. Second you need to know what the given commands expects in
85terms of arguments. Third, the type of your arguments matters:
86
87\starttabulate[|||]
88\NC \type{nothing} \EQ just the command, no arguments \NC \NR
89\NC \type{string}  \EQ an argument with curly braces \NC \NR
90\NC \type{array}   \EQ a list between square backets (sometimes optional) \NC \NR
91\NC \type{hash}    \EQ an assignment list between square brackets \NC \NR
92\NC \type{boolean} \EQ when \type {true} a newline is inserted \NC \NR
93\NC                \EQ when \type {false}, omit braces for the next argument \NC \NR
94\stoptabulate
95
96In the code above you have seen examples of this but here are some more:
97
98\starttyping
99context.chapter("Some title")
100context.chapter({ "first" }, "Some title")
101context.startchapter({ title = "Some title", label = "first" })
102\stoptyping
103
104This blob of code is equivalent to:
105
106\starttyping
107\chapter{Some title}
108\chapter[first]{Some title}
109\startchapter[title={Some title},label=first]
110\stoptyping
111
112You can simplify the third line of the \LUA\ code to:
113
114\starttyping
115context.startchapter { title = "Some title", label = "first" }
116\stoptyping
117
118In case you wonder what the distinction is between square brackets and curly
119braces: the first category of arguments concerns settings or lists of options or
120names of instances while the second category normally concerns some text to be
121typeset.
122
123Strings are interpreted as \TEX\ input, so:
124
125\starttyping
126context.mathematics("\\sqrt{2^3}")
127\stoptyping
128
129and if you don't want to escape:
130
131\starttyping
132context.mathematics([[\sqrt{2^3}]])
133\stoptyping
134
135are both correct. As \TEX\ math is a language in its own and a de-facto standard
136way of inputting math this is quite natural, even at the \LUA\ end.
137
138\stopsection
139
140\startsection[title=Spaces and Lines]
141
142\index{spaces}
143\index{lines}
144
145In a regular \TEX\ file, spaces and newline characters are collapsed into one
146space. At the \LUA\ end the same happens. Compare the following examples. First
147we omit spaces:
148
149\startbuffer
150context("left")
151context("middle")
152context("right")
153\stopbuffer
154
155\typebuffer \ctxluabuffer
156
157Next we add spaces:
158
159\startbuffer
160context("left")
161context(" middle ")
162context("right")
163\stopbuffer
164
165\typebuffer \ctxluabuffer
166
167We can also add more spaces:
168
169\startbuffer
170context("left ")
171context(" middle ")
172context(" right")
173\stopbuffer
174
175\typebuffer \ctxluabuffer
176
177In principle all content becomes a stream and after that the \TEX\ parser will do
178its normal work: collapse spaces unless configured to do otherwise. Now take the
179following code:
180
181\startbuffer
182context("before")
183context("word 1")
184context("word 2")
185context("word 3")
186context("after")
187\stopbuffer
188
189\typebuffer \ctxluabuffer
190
191Here we get no spaces between the words at all, which is what we expect. So, how
192do we get lines (or paragraphs)?
193
194\startbuffer
195context("before")
196context.startlines()
197context("line 1")
198context("line 2")
199context("line 3")
200context.stoplines()
201context("after")
202\stopbuffer
203
204\typebuffer \ctxluabuffer
205
206This does not work out well, as again there are no lines seen at the \TEX\ end.
207Newline tokens are injected by passing \type {true} to the \type {context}
208command:
209
210\startbuffer
211context("before")
212context.startlines()
213context("line 1") context(true)
214context("line 2") context(true)
215context("line 3") context(true)
216context.stoplines()
217context("after")
218\stopbuffer
219
220\typebuffer \ctxluabuffer
221
222Don't confuse this with:
223
224\startbuffer
225context("before") context.par()
226context("line 1") context.par()
227context("line 2") context.par()
228context("line 3") context.par()
229context("after")  context.par()
230\stopbuffer
231
232\typebuffer \ctxluabuffer
233
234There we use the regular \type {\par} command to finish the current paragraph and
235normally you will use that method. In that case, when set, whitespace will be
236added between paragraphs.
237
238This newline issue is a somewhat unfortunate inheritance of traditional \TEX,
239where \type {\n} and \type {\r} mean something different. I'm still not sure if
240the \CLD\ do the right thing as dealing with these tokens also depends on the
241intended effect. Catcodes as well as the \LUATEX\ input parser also play a role.
242Anyway, the following also works:
243
244\startbuffer
245context.startlines()
246context("line 1\n")
247context("line 2\n")
248context("line 3\n")
249context.stoplines()
250\stopbuffer
251
252\typebuffer
253
254\stopsection
255
256\startsection[title=Direct output]
257
258\index{direct output}
259\index{verbose}
260
261The \CONTEXT\ user interface is rather consistent and the use of special input
262syntaxes is discouraged. Therefore, the \LUA\ interface using tables and strings
263works quite well. However, imagine that you need to support some weird macro (or
264a primitive) that does not expect its argument between curly braces or brackets.
265The way out is to precede an argument by another one with the value \type
266{false}. We call this the direct interface. This is demonstrated in the following
267example.
268
269\startbuffer
270\unexpanded\def\bla#1{[#1]}
271
272\startluacode
273context.bla(false,"***")
274context.par()
275context.bla("***")
276\stopluacode
277\stopbuffer
278
279\typebuffer
280
281This results in:
282
283\getbuffer
284
285Here, the first call results in three \type {*} being passed, and \type {#1}
286picks up the first token. The second call to \type {bla} gets \type {{***}}
287passed so here \type {#1} gets the triplet. In practice you will seldom need the
288direct interface.
289
290In \CONTEXT\ for historical reasons, combinations accept the following syntax:
291
292\starttyping
293\startcombination % optional specification, like [2*3]
294  {\framed{content one}} {caption one}
295  {\framed{content two}} {caption two}
296\stopcombination
297\stoptyping
298
299You can also say:
300
301\starttyping
302\startcombination
303  \combination {\framed{content one}} {caption one}
304  \combination {\framed{content two}} {caption two}
305\stopcombination
306\stoptyping
307
308When coded in \LUA, we can feed the first variant as follows:
309
310\startbuffer
311context.startcombination()
312  context.direct("one","two")
313  context.direct("one","two")
314context.stopcombination()
315\stopbuffer
316
317\typebuffer
318
319To give you an idea what this looks like, we render it:
320
321\startlinecorrection[blank]
322\ctxluabuffer
323\stoplinecorrection
324
325So, the \type {direct} function is basically a no|-|op and results in nothing by
326itself. Only arguments are passed. An equivalent but bit more ugly looking is:
327
328\starttyping
329context.startcombination()
330  context(false,"one","two")
331  context(false,"one","two")
332context.stopcombination()
333\stoptyping
334
335\stopsection
336
337\startsection[title=Catcodes]
338
339\index{catcodes}
340
341If you are familiar with the inner working of \TEX, you will know that characters
342can have special meanings. This meaning is determined by their catcodes.
343
344\startbuffer
345context("$x=1$")
346\stopbuffer
347
348\typebuffer
349
350This gives: \ctxluabuffer\ because the dollar tokens trigger inline math mode. If
351you think that this is annoying, you can do the following:
352
353\startbuffer
354context.pushcatcodes("text")
355context("$x=1$")
356context.popcatcodes()
357\stopbuffer
358
359\typebuffer
360
361Now we get: \ctxluabuffer. There are several catcode regimes of
362which only a few make sense in the perspective of the cld
363interface.
364
365\starttabulate[|Tl|l|]
366\NC ctx, ctxcatcodes, context   \NC the normal \CONTEXT\ catcode regime \NC \NR
367\NC prt, prtcatcodes, protect   \NC the \CONTEXT\ protected regime, used for modules \NC \NR
368\NC tex, texcatcodes, plain     \NC the traditional (plain) \TEX\ regime \NC \NR
369\NC txt, txtcatcodes, text      \NC the \CONTEXT\ regime but with less special characters \NC \NR
370\NC vrb, vrbcatcodes, verbatim  \NC a regime specially meant for verbatim \NC \NR
371\NC xml, xmlcatcodes            \NC a regime specially meant for \XML\ processing \NC \NR
372\stoptabulate
373
374In the second case you can still get math:
375
376\starttyping
377context.pushcatcodes("text")
378context.mathematics("x=1")
379context.popcatcodes()
380\stoptyping
381
382When entering a lot of math you can also consider this:
383
384\starttyping
385context.startimath()
386context("x")
387context("=")
388context("1")
389context.stopimath()
390\stoptyping
391
392Module writers of course can use \type {unprotect} and \type {protect} as they do
393at the \TEX\ end.
394
395As we've seen, a function call to \type {context} acts like a print, as in:
396
397\startbuffer
398context("test ")
399context.bold("me")
400context(" first")
401\stopbuffer
402
403\typebuffer \ctxluabuffer
404
405When more than one argument is given, the first argument is considered a format
406conforming the \type {string.format} function.
407
408\startbuffer
409context.startimath()
410context("%s = %0.5f",utf.char(0x03C0),math.pi)
411context.stopimath()
412\stopbuffer
413
414\typebuffer \ctxluabuffer
415
416This means that when you say:
417
418\starttyping
419context(a,b,c,d,e,f)
420\stoptyping
421
422the variables \type {b} till \type {f} are passed to the format and when the
423format does not use them, they will not end up in your output.
424
425\starttyping
426context("%s %s %s",1,2,3)
427context(1,2,3)
428\stoptyping
429
430The first line results in the three numbers being typeset, but in the second case
431only the number~1 is typeset.
432
433\stopsection
434
435\stopchapter
436
437\stopcomponent
438