diff options
Diffstat (limited to 'doc')
64 files changed, 15376 insertions, 9 deletions
diff --git a/doc/context/documents/general/manuals/cld-mkiv.pdf b/doc/context/documents/general/manuals/cld-mkiv.pdf Binary files differnew file mode 100644 index 000000000..5dfa14a4a --- /dev/null +++ b/doc/context/documents/general/manuals/cld-mkiv.pdf diff --git a/doc/context/documents/general/manuals/luatex.pdf b/doc/context/documents/general/manuals/luatex.pdf Binary files differindex 43a4cf660..32d761a5e 100644 --- a/doc/context/documents/general/manuals/luatex.pdf +++ b/doc/context/documents/general/manuals/luatex.pdf diff --git a/doc/context/documents/general/manuals/workflows-mkiv.pdf b/doc/context/documents/general/manuals/workflows-mkiv.pdf Binary files differindex e156a2efc..b0af6d56e 100644 --- a/doc/context/documents/general/manuals/workflows-mkiv.pdf +++ b/doc/context/documents/general/manuals/workflows-mkiv.pdf diff --git a/doc/context/documents/general/qrcs/setup-cs.pdf b/doc/context/documents/general/qrcs/setup-cs.pdf Binary files differindex f88bb3867..27503d751 100644 --- a/doc/context/documents/general/qrcs/setup-cs.pdf +++ b/doc/context/documents/general/qrcs/setup-cs.pdf diff --git a/doc/context/documents/general/qrcs/setup-de.pdf b/doc/context/documents/general/qrcs/setup-de.pdf Binary files differindex bb8eb1917..60ed45aed 100644 --- a/doc/context/documents/general/qrcs/setup-de.pdf +++ b/doc/context/documents/general/qrcs/setup-de.pdf diff --git a/doc/context/documents/general/qrcs/setup-en.pdf b/doc/context/documents/general/qrcs/setup-en.pdf Binary files differindex 365dc0f01..42aaf874c 100644 --- a/doc/context/documents/general/qrcs/setup-en.pdf +++ b/doc/context/documents/general/qrcs/setup-en.pdf diff --git a/doc/context/documents/general/qrcs/setup-fr.pdf b/doc/context/documents/general/qrcs/setup-fr.pdf Binary files differindex de24997f2..14c3836a6 100644 --- a/doc/context/documents/general/qrcs/setup-fr.pdf +++ b/doc/context/documents/general/qrcs/setup-fr.pdf diff --git a/doc/context/documents/general/qrcs/setup-it.pdf b/doc/context/documents/general/qrcs/setup-it.pdf Binary files differindex 2423aa558..ae7ac6615 100644 --- a/doc/context/documents/general/qrcs/setup-it.pdf +++ b/doc/context/documents/general/qrcs/setup-it.pdf diff --git a/doc/context/documents/general/qrcs/setup-nl.pdf b/doc/context/documents/general/qrcs/setup-nl.pdf Binary files differindex 424862260..4c758ad3c 100644 --- a/doc/context/documents/general/qrcs/setup-nl.pdf +++ b/doc/context/documents/general/qrcs/setup-nl.pdf diff --git a/doc/context/documents/general/qrcs/setup-ro.pdf b/doc/context/documents/general/qrcs/setup-ro.pdf Binary files differindex be691d19e..617df4672 100644 --- a/doc/context/documents/general/qrcs/setup-ro.pdf +++ b/doc/context/documents/general/qrcs/setup-ro.pdf diff --git a/doc/context/sources/general/manuals/cld/cld-abitoflua.tex b/doc/context/sources/general/manuals/cld/cld-abitoflua.tex new file mode 100644 index 000000000..5716be6d6 --- /dev/null +++ b/doc/context/sources/general/manuals/cld/cld-abitoflua.tex @@ -0,0 +1,840 @@ +% language=uk + +\startcomponent cld-abitoflua + +\environment cld-environment + +\startchapter[title=A bit of Lua] + +\startsection[title=The language] + +\index[lua]{\LUA} + +Small is beautiful and this is definitely true for the programming language \LUA\ +(moon in Portuguese). We had good reasons for using this language in \LUATEX: +simplicity, speed, syntax and size to mention a few. Of course personal taste +also played a role and after using a couple of scripting languages extensively +the switch to \LUA\ was rather pleasant. + +As the \LUA\ reference manual is an excellent book there is no reason to discuss +the language in great detail: just buy \quote {Programming in \LUA} by the \LUA\ +team. Nevertheless I will give a short summary of the important concepts but +consult the book if you want more details. + +\stopsection + +\startsection[title=Data types] + +\index{functions} +\index{variables} +\index{strings} +\index{numbers} +\index{booleans} +\index{tables} + +The most basic data type is \type {nil}. When we define a variable, we don't need +to give it a value: + +\starttyping +local v +\stoptyping + +Here the variable \type {v} can get any value but till that +happens it equals \type {nil}. There are simple data types like +\type {numbers}, \type {booleans} and \type {strings}. Here are +some numbers: + +\starttyping +local n = 1 + 2 * 3 +local x = 2.3 +\stoptyping + +Numbers are always floats \footnote {This is true for all versions upto 5.2 but +following version can have a more hybrid model.} and you can use the normal +arithmetic operators on them as well as functions defined in the math library. +Inside \TEX\ we have only integers, although for instance dimensions can be +specified in points using floats but that's more syntactic sugar. One reason for +using integers in \TEX\ has been that this was the only way to guarantee +portability across platforms. However, we're 30 years along the road and in \LUA\ +the floats are implemented identical across platforms, so we don't need to worry +about compatibility. + +Strings in \LUA\ can be given between quotes or can be so called long strings +forced by square brackets. + +\starttyping +local s = "Whatever" +local t = s .. ' you want' +local u = t .. [[ to know]] .. [[--[ about Lua!]--]] +\stoptyping + +The two periods indicate a concatenation. Strings are hashed, so when you say: + +\starttyping +local s = "Whatever" +local t = "Whatever" +local u = t +\stoptyping + +only one instance of \type {Whatever} is present in memory and this fact makes +\LUA\ very efficient with respect to strings. Strings are constants and therefore +when you change variable \type {s}, variable \type {t} keeps its value. When you +compare strings, in fact you compare pointers, a method that is really fast. This +compensates the time spent on hashing pretty well. + +Booleans are normally used to keep a state or the result from an expression. + +\starttyping +local b = false +local c = n > 10 and s == "whatever" +\stoptyping + +The other value is \type {true}. There is something that you need +to keep in mind when you do testing on variables that are yet +unset. + +\starttyping +local b = false +local n +\stoptyping + +The following applies when \type {b} and \type {n} are defined this way: + +\starttabulate[|Tl|Tl|] +\NC b == false \NC true \NC \NR +\NC n == false \NC false \NC \NR +\NC n == nil \NC true \NC \NR +\NC b == nil \NC false \NC \NR +\NC b == n \NC false \NC \NR +\NC n == nil \NC true \NC \NR +\stoptabulate + +Often a test looks like: + +\starttyping +if somevar then + ... +else + ... +end +\stoptyping + +In this case we enter the else branch when \type {somevar} is either \type {nil} +or \type {false}. It also means that by looking at the code we cannot beforehand +conclude that \type {somevar} equals \type {true} or something else. If you want +to really distinguish between the two cases you can be more explicit: + +\starttyping +if somevar == nil then + ... +elseif somevar == false then + ... +else + ... +end +\stoptyping + +or + +\starttyping +if somevar == true then + ... +else + ... +end +\stoptyping + +but such an explicit test is seldom needed. + +There are a few more data types: tables and functions. Tables are very important +and you can recognize them by the same curly braces that make \TEX\ famous: + +\starttyping +local t = { 1, 2, 3 } +local u = { a = 4, b = 9, c = 16 } +local v = { [1] = "a", [3] = "2", [4] = false } +local w = { 1, 2, 3, a = 4, b = 9, c = 16 } +\stoptyping + +The \type {t} is an indexed table and \type {u} a hashed table. Because the +second slot is empty, table \type {v} is partially indexed (slot 1) and partially +hashed (the others). There is a gray area there, for instance, what happens when +you nil a slot in an indexed table? In practice you will not run into problems as +you will either use a hashed table, or an indexed table (with no holes), so table +\type {w} is not uncommon. + +We mentioned that strings are in fact shared (hashed) but that an assignment of a +string to a variable makes that variable behave like a constant. Contrary to +that, when you assign a table, and then copy that variable, both variables can be +used to change the table. Take this: + +\starttyping +local t = { 1, 2, 3 } +local u = t +\stoptyping + +We can change the content of the table as follows: + +\starttyping +t[1], t[3] = t[3], t[1] +\stoptyping + +Here we swap two cells. This is an example of a parallel assigment. However, the +following does the same: + +\starttyping +t[1], t[3] = u[3], u[1] +\stoptyping + +After this, both \type {t} and \type {u} still share the same table. This kind of +behaviour is quite natural. Keep in mind that expressions are evaluated first, so + +\starttyping +t[#t+1], t[#t+1] = 23, 45 +\stoptyping + +Makes no sense, as the values end up in the same slot. There is no gain in speed +so using parallel assignments is mostly a convenience feature. + +There are a few specialized data types in \LUA, like \type {coroutines} (built +in), \type {file} (when opened), \type {lpeg} (only when this library is linked +in or loaded). These are called \quote {userdata} objects and in \LUATEX\ we have +more userdata objects as we will see in later chapters. Of them nodes are the +most noticeable: they are the core data type of the \TEX\ machinery. Other +libraries, like \type {math} and \type {bit32} are just collections of functions +operating on numbers. + +Functions look like this: + +\starttyping +function sum(a,b) + print(a, b, a + b) +end +\stoptyping + +or this: + +\starttyping +function sum(a,b) + return a + b +end +\stoptyping + +There can be many arguments of all kind of types and there can be multiple return +values. A function is a real type, so you can say: + +\starttyping +local f = function(s) print("the value is: " .. s) end +\stoptyping + +In all these examples we defined variables as \type {local}. This is a good +practice and avoids clashes. Now watch the following: + +\starttyping +local n = 1 + +function sum(a,b) + n = n + 1 + return a + b +end + +function report() + print("number of summations: " .. n) +end +\stoptyping + +Here the variable \type {n} is visible after its definition and accessible for +the two global functions. Actually the variable is visible to all the code +following, unless of course we define a new variable with the same name. We can +hide \type {n} as follows: + +\starttyping +do + local n = 1 + + sum = function(a,b) + n = n + 1 + return a + b + end + + report = function() + print("number of summations: " .. n) + end +end +\stoptyping + +This example also shows another way of defining the function: by assignment. + +The \typ {do ... end} creates a so called closure. There are many places where +such closures are created, for instance in function bodies or branches like \typ +{if ... then ... else}. This means that in the following snippet, variable \type +{b} is not seen after the end: + +\starttyping +if a > 10 then + local b = a + 10 + print(b*b) +end +\stoptyping + +When you process a blob of \LUA\ code in \TEX\ (using \type {\directlua} or \type +{\latelua}) it happens in a closure with an implied \typ {do ... end}. So, \type +{local} defined variables are really local. + +\stopsection + +\startsection[title=\TEX's data types] + +We mentioned \type {numbers}. At the \TEX\ end we have counters as well as +dimensions. Both are numbers but dimensions are specified differently + +\starttyping +local n = tex.count[0] +local m = tex.dimen.lineheight +local o = tex.sp("10.3pt") -- sp or 'scaled point' is the smallest unit +\stoptyping + +The unit of dimension is \quote {scaled point} and this is a pretty small unit: +10 points equals to 655360 such units. + +Another accessible data type is tokens. They are automatically converted to +strings and vice versa. + +\starttyping +tex.toks[0] = "message" +print(tex.toks[0]) +\stoptyping + +Be aware of the fact that the tokens are letters so the following will come out +as text and not issue a message: + +\starttyping +tex.toks[0] = "\message{just text}" +print(tex.toks[0]) +\stoptyping + +\stopsection + +\startsection[title=Control structures] + +\index{loops} + +Loops are not much different from other languages: we have \typ {for ... do}, +\typ {while ... do} and \typ {repeat ... until}. We start with the simplest case: + +\starttyping +for index=1,10 do + print(index) +end +\stoptyping + +You can specify a step and go downward as well: + +\starttyping +for index=22,2,-2 do + print(index) +end +\stoptyping + +Indexed tables can be traversed this way: + +\starttyping +for index=1,#list do + print(index, list[index]) +end +\stoptyping + +Hashed tables on the other hand are dealt with as follows: + +\starttyping +for key, value in next, list do + print(key, value) +end +\stoptyping + +Here \type {next} is a built in function. There is more to say about this +mechanism but the average user will use only this variant. Slightly less +efficient is the following, more readable variant: + +\starttyping +for key, value in pairs(list) do + print(key, value) +end +\stoptyping + +and for an indexed table: + +\starttyping +for index, value in ipairs(list) do + print(index, value) +end +\stoptyping + +The function call to \type {pairs(list)} returns \typ {next, list} so there is an +(often neglectable) extra overhead of one function call. + +The other two loop variants, \type {while} and \type {repeat}, are similar. + +\starttyping +i = 0 +while i < 10 do + i = i + 1 + print(i) +end +\stoptyping + +This can also be written as: + +\starttyping +i = 0 +repeat + i = i + 1 + print(i) +until i = 10 +\stoptyping + +Or: + +\starttyping +i = 0 +while true do + i = i + 1 + print(i) + if i = 10 then + break + end +end +\stoptyping +\stopsection + +Of course you can use more complex expressions in such constructs. + +\startsection[title=Conditions] + +\index{expressions} + +Conditions have the following form: + +\starttyping +if a == b or c > d or e then + ... +elseif f == g then + ... +else + ... +end +\stoptyping + +Watch the double \type {==}. The complement of this is \type {~=}. Precedence is +similar to other languages. In practice, as strings are hashed. Tests like + +\starttyping +if key == "first" then + ... +end +\stoptyping + +and + +\starttyping +if n == 1 then + ... +end +\stoptyping + +are equally efficient. There is really no need to use numbers to identify states +instead of more verbose strings. + +\stopsection + +\startsection[title=Namespaces] + +\index{namespaces} + +Functionality can be grouped in libraries. There are a few default libraries, +like \type {string}, \type {table}, \type {lpeg}, \type {math}, \type {io} and +\type {os} and \LUATEX\ adds some more, like \type {node}, \type {tex} and \type +{texio}. + +A library is in fact nothing more than a bunch of functionality organized using a +table, where the table provides a namespace as well as place to store public +variables. Of course there can be local (hidden) variables used in defining +functions. + +\starttyping +do + mylib = { } + + local n = 1 + + function mylib.sum(a,b) + n = n + 1 + return a + b + end + + function mylib.report() + print("number of summations: " .. n) + end +end +\stoptyping + +The defined function can be called like: + +\starttyping +mylib.report() +\stoptyping + +You can also create a shortcut, This speeds up the process because there are less +lookups then. In the following code multiple calls take place: + +\starttyping +local sum = mylib.sum + +for i=1,10 do + for j=1,10 do + print(i, j, sum(i,j)) + end +end + +mylib.report() +\stoptyping + +As \LUA\ is pretty fast you should not overestimate the speedup, especially not +when a function is called seldom. There is an important side effect here: in the +case of: + +\starttyping + print(i, j, sum(i,j)) +\stoptyping + +the meaning of \type {sum} is frozen. But in the case of + +\starttyping + print(i, j, mylib.sum(i,j)) +\stoptyping + +The current meaning is taken, that is: each time the interpreter will access +\type {mylib} and get the current meaning of \type {sum}. And there can be a good +reason for this, for instance when the meaning is adapted to different +situations. + +In \CONTEXT\ we have quite some code organized this way. Although much is exposed +(if only because it is used all over the place) you should be careful in using +functions (and data) that are still experimental. There are a couple of general +libraries and some extend the core \LUA\ libraries. You might want to take a look +at the files in the distribution that start with \type {l-}, like \type +{l-table.lua}. These files are preloaded.\footnote {In fact, if you write scripts +that need their functionality, you can use \type {mtxrun} to process the script, +as \type {mtxrun} has the core libraries preloaded as well.} For instance, if you +want to inspect a table, you can say: + +\starttyping +local t = { "aap", "noot", "mies" } +table.print(t) +\stoptyping + +You can get an overview of what is implemented by running the following command: + +\starttyping +context s-tra-02 --mode=tablet +\stoptyping + +{\em todo: add nice synonym for this module and also add helpinfo at the to so +that we can do \type {context --styles}} + +\stopsection + +\startsection[title=Comment] + +\index{comment} + +You can add comments to your \LUA\ code. There are basically two methods: one +liners and multi line comments. + +\starttyping +local option = "test" -- use this option with care + +local method = "unknown" --[[comments can be very long and when entered + this way they and span multiple lines]] +\stoptyping + +The so called long comments look like long strings preceded by \type {--} and +there can be more complex boundary sequences. + +\stopsection + +\startsection[title=Pitfalls] + +Sometimes \type {nil} can bite you, especially in tables, as they have a dual nature: +indexed as well as hashed. + +\startbuffer +\startluacode +local n1 = # { nil, 1, 2, nil } -- 3 +local n2 = # { nil, nil, 1, 2, nil } -- 0 + +context("n1 = %s and n2 = %s",n1,n2) +\stopluacode +\stopbuffer + +\typebuffer + +results in: \getbuffer + +So, you cannot really depend on the length operator here. On the other hand, with: + +\startbuffer +\startluacode +local function check(...) + return select("#",...) +end + +local n1 = check ( nil, 1, 2, nil ) -- 4 +local n2 = check ( nil, nil, 1, 2, nil ) -- 5 + +context("n1 = %s and n2 = %s",n1,n2) +\stopluacode +\stopbuffer + +\typebuffer + +we get: \getbuffer, so the \type {select} is quite useable. However, that function also +has its specialities. The following example needs some close reading: + +\startbuffer +\startluacode +local function filter(n,...) + return select(n,...) +end + +local v1 = { filter ( 1, 1, 2, 3 ) } +local v2 = { filter ( 2, 1, 2, 3 ) } +local v3 = { filter ( 3, 1, 2, 3 ) } + +context("v1 = %+t and v2 = %+t and v3 = %+t",v1,v2,v3) +\stopluacode +\stopbuffer + +\typebuffer + +We collect the result in a table and show the concatination: + +\getbuffer + +So, what you effectively get is the whole list starting with the given offset. + +\startbuffer +\startluacode +local function filter(n,...) + return (select(n,...)) +end + +local v1 = { filter ( 1, 1, 2, 3 ) } +local v2 = { filter ( 2, 1, 2, 3 ) } +local v3 = { filter ( 3, 1, 2, 3 ) } + +context("v1 = %+t and v2 = %+t and v3 = %+t",v1,v2,v3) +\stopluacode +\stopbuffer + +\typebuffer + +Now we get: \getbuffer. The extra \type {()} around the result makes sure that +we only get one return value. + +Of course the same effect can be achieved as follows: + +\starttyping +local function filter(n,...) + return select(n,...) +end + +local v1 = filter ( 1, 1, 2, 3 ) +local v2 = filter ( 2, 1, 2, 3 ) +local v3 = filter ( 3, 1, 2, 3 ) + +context("v1 = %s and v2 = %s and v3 = %s",v1,v2,v3) +\stoptyping + +\stopsection + +\startsection[title={A few suggestions}] + +You can wrap all kind of functionality in functions but sometimes it makes no +sense to add the overhead of a call as the same can be done with hardly any code. + +If you want a slice of a table, you can copy the range needed to a new table. A +simple version with no bounds checking is: + +\starttyping +local new = { } for i=a,b do new[#new+1] = old[i] end +\stoptyping + +Another, much faster, variant is the following. + +\starttyping +local new = { unpack(old,a,b) } +\stoptyping + +You can use this variant for slices that are not extremely large. The function +\type {table.sub} is an equivalent: + +\starttyping +local new = table.sub(old,a,b) +\stoptyping + +An indexed table is empty when its size equals zero: + +\starttyping +if #indexed == 0 then ... else ... end +\stoptyping + +Sometimes this is better: + +\starttyping +if indexed and #indexed == 0 then ... else ... end +\stoptyping + +So how do we test if a hashed table is empty? We can use the +\type {next} function as in: + +\starttyping +if hashed and next(indexed) then ... else ... end +\stoptyping + +Say that we have the following table: + +\starttyping +local t = { a=1, b=2, c=3 } +\stoptyping + +The call \type {next(t)} returns the first key and value: + +\starttyping +local k, v = next(t) -- "a", 1 +\stoptyping + +The second argument to \type {next} can be a key in which case the +following key and value in the hash table is returned. The result +is not predictable as a hash is unordered. The generic for loop +uses this to loop over a hashed table: + +\starttyping +for k, v in next, t do + ... +end +\stoptyping + +Anyway, when \type {next(t)} returns zero you can be sure that the table is +empty. This is how you can test for exactly one entry: + +\starttyping +if t and not next(t,next(t)) then ... else ... end +\stoptyping + +Here it starts making sense to wrap it into a function. + +\starttyping +function table.has_one_entry(t) + t and not next(t,next(t)) +end +\stoptyping + +On the other hand, this is not that usefull, unless you can spent the runtime on +it: + +\starttyping +function table.is_empty(t) + return not t or not next(t) +end +\stoptyping + +\stopsection + +\startsection[title=Interfacing] + +We have already seen that you can embed \LUA\ code using commands like: + +\starttyping +\startluacode + print("this works") +\stopluacode +\stoptyping + +This command should not be confused with: + +\starttyping +\startlua + print("this works") +\stoplua +\stoptyping + +The first variant has its own catcode regime which means that tokens between the start +and stop command are treated as \LUA\ tokens, with the exception of \TEX\ commands. The +second variant operates under the regular \TEX\ catcode regime. + +Their short variants are \type {\ctxluacode} and \type {\ctxlua} as in: + +\starttyping +\ctxluacode{print("this works")} +\ctxlua{print("this works")} +\stoptyping + +In practice you will probably use \type {\startluacode} when using or defining % \stopluacode +a blob of \LUA\ and \type {\ctxlua} for inline code. Keep in mind that the +longer versions need more initialization and have more overhead. + +There are some more commands. For instance \type {\ctxcommand} can be used as +an efficient way to access functions in the \type {commands} namespace. The +following two calls are equivalent: + +\starttyping +\ctxlua {commands.thisorthat("...")} +\ctxcommand {thisorthat("...")} +\stoptyping + +There are a few shortcuts to the \type {context} namespace. Their use can best be +seen from their meaning: + +\starttyping +\cldprocessfile#1{\directlua{context.runfile("#1")}} +\cldloadfile #1{\directlua{context.loadfile("#1")}} +\cldcontext #1{\directlua{context(#1)}} +\cldcommand #1{\directlua{context.#1}} +\stoptyping + +Each time a call out to \LUA\ happens the argument eventually gets parsed, converted +into tokens, then back into a string, compiled to bytecode and executed. The next +example code shows a mechanism that avoids this: + +\starttyping +\startctxfunction MyFunctionA + context(" A1 ") +\stopctxfunction + +\startctxfunctiondefinition MyFunctionB + context(" B2 ") +\stopctxfunctiondefinition +\stoptyping + +The first command associates a name with some \LUA\ code and that code can be +executed using: + +\starttyping +\ctxfunction{MyFunctionA} +\stoptyping + +The second definition creates a command, so there we do: + +\starttyping +\MyFunctionB +\stoptyping + +There are some more helpers but for use in document sources they make less sense. You +can always browse the source code for examples. + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/cld/cld-afewdetails.tex b/doc/context/sources/general/manuals/cld/cld-afewdetails.tex new file mode 100644 index 000000000..6c0cf3afa --- /dev/null +++ b/doc/context/sources/general/manuals/cld/cld-afewdetails.tex @@ -0,0 +1,398 @@ +% language=uk + +\startcomponent cld-afewdetails + +\environment cld-environment + +\startchapter[title=A few Details] + +\startsection[title=Variables] + +\index{user interface} + +Normally it makes most sense to use the English version of \CONTEXT. The +advantage is that you can use English keywords, as in: + +\starttyping +context.framed( { + frame = "on", + }, + "some text" +) +\stoptyping + +If you use the Dutch interface it looks like this: + +\starttyping +context.omlijnd( { + kader = "aan", + }, + "wat tekst" +) +\stoptyping + +A rather neutral way is: + +\starttyping +context.framed( { + frame = interfaces.variables.on, + }, + "some text" +) +\stoptyping + +But as said, normally you will use the English user interface so you can forget +about these matters. However, in the \CONTEXT\ core code you will often see the +variables being used this way because there we need to support all user +interfaces. + +\stopsection + +\startsection[title=Modes] + +\index{modes} +\index{systemmodes} +\index{constants} + +Context carries a concept of modes. You can use modes to create conditional +sections in your style (and|/|or content). You can control modes in your styles +or you can set them at the command line or in job control files. When a mode test +has to be done at processing time, then you need constructs like the following: + +\starttyping +context.doifmodeelse( "screen", + function() + ... -- mode == screen + end, + function() + ... -- mode ~= screen + end +) +\stoptyping + +However, often a mode does not change during a run, and then we can use the +following method: + +\starttyping +if tex.modes["screen"] then + ... +else + ... +end +\stoptyping + +Watch how the \type {modes} table lives in the \type {tex} namespace. We also +have \type {systemmodes}. At the \TEX\ end these are mode names preceded by a +\type {*}, so the following code is similar: + +\starttyping +if tex.modes["*mymode"] then + -- this is the same +elseif tex.systemmodes["mymode"] then + -- test as this +else + -- but not this +end +\stoptyping + +Inside \CONTEXT\ we also have so called constants, and again these can be +consulted at the \LUA\ end: + +\starttyping +if tex.constants["someconstant'] then + ... +else + ... +end +\stoptyping + +But you will hardly need these and, as they are often not public, their +meaning can change, unless of course they {\em are} documented as public. + +\stopsection + +\startsection[title={Token lists}] + +\index{tokens} + +There is normally no need to mess around with nodes and tokens at the \LUA\ end +yourself. However, if you do, then you might want to flush them as well. Say that +at the \TEX\ end we have said: + +\startbuffer +\toks0 = {Don't get \inframed{framed}!} +\stopbuffer + +\typebuffer \getbuffer + +Then at the \LUA\ end you can say: + +\startbuffer +context(tex.toks[0]) +\stopbuffer + +\typebuffer + +and get: \ctxluabuffer\ In fact, token registers are exposed as strings so here, +register zero has type \type {string} and is treated as such. + +\startbuffer +context("< %s >",tex.toks[0]) +\stopbuffer + +\typebuffer + +This gives: \ctxluabuffer. But beware, if you go the reverse way, you don't get +what you might expect: + +\startbuffer +tex.toks[0] = [[\framed{oeps}]] +\stopbuffer + +\typebuffer \ctxluabuffer + +If we now say \type{\the\toks0} we will get {\tttf \the\toks0} as +all tokens are considered to be letters. + +\stopsection + +\startsection[title={Node lists}] + +\index{nodes} + +If you're not deep into \TEX\ you will never feel the need to manipulate node +lists yourself, but you might want to flush boxes. As an example we put something +in box zero (one of the scratch boxes). + +\startbuffer +\setbox0 = \hbox{Don't get \inframed{framed}!} +\stopbuffer + +\typebuffer \getbuffer + +At the \TEX\ end you can flush this box (\type {\box0}) or take a copy +(\type{\copy0}). At the \LUA\ end you would do: + +\starttyping +context.copy() +context.direct(0) +\stoptyping + +or: + +\starttyping +context.copy(false,0) +\stoptyping + +but this works as well: + +\startbuffer +context(node.copy_list(tex.box[0])) +\stopbuffer + +\typebuffer + +So we get: \ctxluabuffer\ If you do: + +\starttyping +context(tex.box[0]) +\stoptyping + +you also need to make sure that the box is freed but let's not go into those +details now. + +Here is an example if messing around with node lists that get seen before a +paragraph gets broken into lines, i.e.\ when hyphenation, font manipulation etc +take place. First we define some colors: + +\startbuffer +\definecolor[mynesting:0][r=.6] +\definecolor[mynesting:1][g=.6] +\definecolor[mynesting:2][r=.6,g=.6] +\stopbuffer + +\typebuffer \getbuffer + +Next we define a function that colors nodes in such a way that we can see the +different processing stages. + +\startbuffer +\startluacode +local enabled = false +local count = 0 +local setcolor = nodes.tracers.colors.set + +function userdata.processmystuff(head) + if enabled then + local color = "mynesting:" .. (count % 3) + -- for n in node.traverse(head) do + for n in node.traverse_id(nodes.nodecodes.glyph,head) do + setcolor(n,color) + end + count = count + 1 + return head, true + end + return head, false +end + +function userdata.enablemystuff() + enabled = true +end + +function userdata.disablemystuff() + enabled = false +end +\stopluacode +\stopbuffer + +\typebuffer \getbuffer + +We hook this function into the normalizers category of the processor callbacks: + +\startbuffer +\startluacode +nodes.tasks.appendaction("processors", "normalizers", "userdata.processmystuff") +\stopluacode +\stopbuffer + +\typebuffer \getbuffer + +We now can enable this mechanism and show an example: + +\startbuffer +\startbuffer +Node lists are processed \hbox {nested from \hbox{inside} out} which is not +what you might expect. But, \hbox{coloring} does not \hbox {happen} really +nested here, more \hbox {in} \hbox {the} \hbox {order} \hbox {of} \hbox +{processing}. +\stopbuffer + +\ctxlua{userdata.enablemystuff()} +\par \getbuffer \par +\ctxlua{userdata.disablemystuff()} +\stopbuffer + +\typebuffer + +The \type {\par} is needed because otherwise the processing is already disabled +before the paragraph gets seen by \TEX. + +\blank \getbuffer \blank + +\startbuffer +\startluacode +nodes.tasks.disableaction("processors", "userdata.processmystuff") +\stopluacode +\stopbuffer + +\typebuffer + +Instead of using an boolean to control the state, we can also do this: + +\starttyping +\startluacode +local count = 0 +local setcolor = nodes.tracers.colors.set + +function userdata.processmystuff(head) + count = count + 1 + local color = "mynesting:" .. (count % 3) + for n in node.traverse_id(nodes.nodecodes.glyph,head) do + setcolor(n,color) + end + return head, true +end + +nodes.tasks.appendaction("processors", "after", "userdata.processmystuff") +\stopluacode +\stoptyping + +\startbuffer +\startluacode +nodes.tasks.disableaction("processors", "userdata.processmystuff") +\stopluacode +\stopbuffer + +Disabling now happens with: + +\typebuffer \getbuffer + +As you might want to control these things in more details, a simple helper +mechanism was made: markers. The following example code shows the way: + +\startbuffer +\definemarker[mymarker] +\stopbuffer + +\typebuffer \getbuffer + +Again we define some colors: + +\startbuffer +\definecolor[mymarker:1][r=.6] +\definecolor[mymarker:2][g=.6] +\definecolor[mymarker:3][r=.6,g=.6] +\stopbuffer + +\typebuffer \getbuffer + +The \LUA\ code like similar to the code presented before: + +\startbuffer +\startluacode +local setcolor = nodes.tracers.colors.setlist +local getmarker = nodes.markers.get +local hlist_code = nodes.codes.hlist +local traverse_id = node.traverse_id + +function userdata.processmystuff(head) + for n in traverse_id(hlist_code,head) do + local m = getmarker(n,"mymarker") + if m then + setcolor(n.list,"mymarker:" .. m) + end + end + return head, true +end + +nodes.tasks.appendaction("processors", "after", "userdata.processmystuff") +nodes.tasks.disableaction("processors", "userdata.processmystuff") +\stopluacode +\stopbuffer + +\typebuffer \getbuffer + +This time we disabled the processor (if only because in this document we don't +want the overhead. + +\startbuffer +\startluacode +nodes.tasks.enableaction("processors", "userdata.processmystuff") +\stopluacode + +Node lists are processed \hbox \boxmarker{mymarker}{1} {nested from \hbox{inside} +out} which is not what you might expect. But, \hbox {coloring} does not \hbox +{happen} really nested here, more \hbox {in} \hbox \boxmarker{mymarker}{2} {the} +\hbox {order} \hbox {of} \hbox \boxmarker{mymarker}{3} {processing}. + +\startluacode +nodes.tasks.disableaction("processors", "userdata.processmystuff") +\stopluacode +\stopbuffer + +\typebuffer + +The result looks familiar: + +\getbuffer + +% We don't want the burden of this demo to cary on: + +% {\em If there's enough interest I will expand this section with some basic +% information on what nodes are.} + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/cld/cld-backendcode.tex b/doc/context/sources/general/manuals/cld/cld-backendcode.tex new file mode 100644 index 000000000..9c1284baa --- /dev/null +++ b/doc/context/sources/general/manuals/cld/cld-backendcode.tex @@ -0,0 +1,388 @@ +% language=uk + +\startcomponent cld-backendcode + +\environment cld-environment + +% derived from hybrid + +\startchapter[title={Backend code}] + +\startsection [title={Introduction}] + +In \CONTEXT\ we've always separated the backend code in so called driver files. +This means that in the code related to typesetting only calls to the \API\ take +place, and no backend specific code is to be used. Currently a \PDF\ backend is +supported as well as an \XML\ export. \footnote {This chapter is derived from an +article on these matters. You can find nore information in \type {hybrid.pdf}.} + +Some \CONTEXT\ users like to add their own \PDF\ specific code to their styles or +modules. However, such extensions can interfere with existing code, especially +when resources are involved. Therefore the construction of \PDF\ data structures +and resources is rather controlled and has to be done via the official helper +macros. + +\stopsection + +\startsection [title={Structure}] + +A \PDF\ file is a tree of indirect objects. Each object has a number and the file +contains a table (or multiple tables) that relates these numbers to positions in +a file (or position in a compressed object stream). That way a file can be viewed +without reading all data: a viewer only loads what is needed. + +\starttyping +1 0 obj << + /Name (test) /Address 2 0 R +>> +2 0 obj [ + (Main Street) (24) (postal code) (MyPlace) +] +\stoptyping + +For the sake of the discussion we consider strings like \type {(test)} also to be +objects. In the next table we list what we can encounter in a \PDF\ file. There +can be indirect objects in which case a reference is used (\type{2 0 R}) and +direct ones. + +It all starts in the document's root object. From there we access the page tree +and resources. Each page carries its own resource information which makes random +access easier. A page has a page stream and there we find the to be rendered +content as a mixture of (\UNICODE) strings and special drawing and rendering +operators. Here we will not discuss them as they are mostly generated by the +engine itself or dedicated subsystems like the \METAPOST\ converter. There we use +literal or \type {\latelua} whatsits to inject code into the current stream. + +\stopsection + +\startsection [title={Data types}] + +There are several datatypes in \PDF\ and we support all of them one way or the +other. + +\starttabulate[|l|l|p|] +\FL +\NC \bf type \NC \bf form \NC \bf meaning \NC \NR +\TL +\NC constant \NC \type{/...} \NC A symbol (prescribed string). \NC \NR +\NC string \NC \type{(...)} \NC A sequence of characters in pdfdoc + encoding \NC \NR +\NC unicode \NC \type{<...>} \NC A sequence of characters in utf16 + encoding \NC \NR +\NC number \NC \type{3.1415} \NC A number constant. \NC \NR +\NC boolean \NC \type{true/false} \NC A boolean constant. \NC \NR +\NC reference \NC \type{N 0 R} \NC A reference to an object \NC \NR +\NC dictionary \NC \type{<< ... >>} \NC A collection of key value pairs + where the value itself is an (indirect) object. + \NC \NR +\NC array \NC \type{[ ... ]} \NC A list of objects or references to + objects. \NC \NR +\NC stream \NC \NC A sequence of bytes either or not packaged with + a dictionary that contains descriptive data. \NC \NR +\NC xform \NC \NC A special kind of object containing an reusable + blob of data, for example an image. \NC \NR +\LL +\stoptabulate + +While writing additional backend code, we mostly create dictionaries. + +\starttyping +<< /Name (test) /Address 2 0 R >> +\stoptyping + +In this case the indirect object can look like: + +\starttyping +[ (Main Street) (24) (postal code) (MyPlace) ] +\stoptyping + +The \LUATEX\ manual mentions primitives like \type {\pdfobj}, \type {\pdfannot}, +\type {\pdfcatalog}, etc. However, in \MKIV\ no such primitives are used. You can +still use many of them but those that push data into document or page related +resources are overloaded to do nothing at all. + +In the \LUA\ backend code you will find function calls like: + +\starttyping +local d = lpdf.dictionary { + Name = lpdf.string("test"), + Address = lpdf.array { + "Main Street", "24", "postal code", "MyPlace", + } +} +\stoptyping + +Equaly valid is: + +\starttyping +local d = lpdf.dictionary() +d.Name = "test" +\stoptyping + +Eventually the object will end up in the file using calls like: + +\starttyping +local r = lpdf.immediateobject(tostring(d)) +\stoptyping + +or using the wrapper (which permits tracing): + +\starttyping +local r = lpdf.flushobject(d) +\stoptyping + +The object content will be serialized according to the formal specification so +the proper \type {<< >>} etc.\ are added. If you want the content instead you can +use a function call: + +\starttyping +local dict = d() +\stoptyping + +An example of using references is: + +\starttyping +local a = lpdf.array { + "Main Street", "24", "postal code", "MyPlace", +} +local d = lpdf.dictionary { + Name = lpdf.string("test"), + Address = lpdf.reference(a), +} +local r = lpdf.flushobject(d) +\stoptyping + +\stopsection + +We have the following creators. Their arguments are optional. + +\starttabulate[|l|p|] +\FL +\NC \bf function \NC \bf optional parameter \NC \NR +\TL +\NC \type{lpdf.null} \NC \NC \NR +\NC \type{lpdf.number} \NC number \NC \NR +\NC \type{lpdf.constant} \NC string \NC \NR +\NC \type{lpdf.string} \NC string \NC \NR +\NC \type{lpdf.unicode} \NC string \NC \NR +\NC \type{lpdf.boolean} \NC boolean \NC \NR +\NC \type{lpdf.array} \NC indexed table of objects \NC \NR +\NC \type{lpdf.dictionary} \NC hash with key/values \NC \NR +%NC \type{lpdf.stream} \NC indexed table of operators \NC \NR +\NC \type{lpdf.reference} \NC string \NC \NR +\NC \type{lpdf.verbose} \NC indexed table of strings \NC \NR +\LL +\stoptabulate + +\ShowLuaExampleString{tostring(lpdf.null())} +\ShowLuaExampleString{tostring(lpdf.number(123))} +\ShowLuaExampleString{tostring(lpdf.constant("whatever"))} +\ShowLuaExampleString{tostring(lpdf.string("just a string"))} +\ShowLuaExampleString{tostring(lpdf.unicode("just a string"))} +\ShowLuaExampleString{tostring(lpdf.boolean(true))} +\ShowLuaExampleString{tostring(lpdf.array { 1, lpdf.constant("c"), true, "str" })} +\ShowLuaExampleString{tostring(lpdf.dictionary { a=1, b=lpdf.constant("c"), d=true, e="str" })} +%ShowLuaExampleString{tostring(lpdf.stream("whatever"))} +\ShowLuaExampleString{tostring(lpdf.reference(123))} +\ShowLuaExampleString{tostring(lpdf.verbose("whatever"))} + +\stopsection + +\startsection[title={Managing objects}] + +Flushing objects is done with: + +\starttyping +lpdf.flushobject(obj) +\stoptyping + +Reserving object is or course possible and done with: + +\starttyping +local r = lpdf.reserveobject() +\stoptyping + +Such an object is flushed with: + +\starttyping +lpdf.flushobject(r,obj) +\stoptyping + +We also support named objects: + +\starttyping +lpdf.reserveobject("myobject") + +lpdf.flushobject("myobject",obj) +\stoptyping + +A delayed object is created with: + +\starttyping +local ref = pdf.delayedobject(data) +\stoptyping + +The data will be flushed later using the object number that is returned (\type +{ref}). When you expect that many object with the same content are used, you can +use: + +\starttyping +local obj = lpdf.shareobject(data) +local ref = lpdf.shareobjectreference(data) +\stoptyping + +This one flushes the object and returns the object number. Already defined +objects are reused. In addition to this code driven optimization, some other +optimization and reuse takes place but all that happens without user +intervention. Only use this when it's really needed as it might consume more +memory and needs more processing time. + +\startsection [title={Resources}] + +While \LUATEX\ itself will embed all resources related to regular typesetting, +\MKIV\ has to take care of embedding those related to special tricks, like +annotations, spot colors, layers, shades, transparencies, metadata, etc. Because +third party modules (like tikz) also can add resources we provide some macros +that makes sure that no interference takes place: + +\starttyping +\pdfbackendsetcatalog {key}{string} +\pdfbackendsetinfo {key}{string} +\pdfbackendsetname {key}{string} + +\pdfbackendsetpageattribute {key}{string} +\pdfbackendsetpagesattribute{key}{string} +\pdfbackendsetpageresource {key}{string} + +\pdfbackendsetextgstate {key}{pdfdata} +\pdfbackendsetcolorspace {key}{pdfdata} +\pdfbackendsetpattern {key}{pdfdata} +\pdfbackendsetshade {key}{pdfdata} +\stoptyping + +One is free to use the \LUA\ interface instead, as there one has more +possibilities but when code is shared with other macro packages the macro +interface makes more sense. The names of the \LUA\ functions are similar, like: + +\starttyping +lpdf.addtoinfo(key,anything_valid_pdf) +\stoptyping + +Currently we expose a bit more of the backend code than we like and +future versions will have a more restricted access. The following +function will stay public: + +\starttyping +lpdf.addtopageresources (key,value) +lpdf.addtopageattributes (key,value) +lpdf.addtopagesattributes(key,value) + +lpdf.adddocumentextgstate(key,value) +lpdf.adddocumentcolorspac(key,value) +lpdf.adddocumentpattern (key,value) +lpdf.adddocumentshade (key,value) + +lpdf.addtocatalog (key,value) +lpdf.addtoinfo (key,value) +lpdf.addtonames (key,value) +\stoptyping + +\stopsection + +\startsection [title={Annotations}] + +You can use the \LUA\ functions that relate to annotations etc.\ but normally you +will use the regular \CONTEXT\ user interface. You can look into some of the +\type {lpdf-*} modules to see how special annotations can be dealt with. + +\stopsection + +\startsection [title={Tracing}] + +There are several tracing options built in and some more will be added in due +time: + +\starttyping +\enabletrackers + [backend.finalizers, + backend.resources, + backend.objects, + backend.detail] +\stoptyping + +As with all trackers you can also pass them on the command line, for example: + +\starttyping +context --trackers=backend.* yourfile +\stoptyping + +The reference related backend mechanisms have their own trackers. When you write +code that generates \PDF, it also helps to look in the \PDF\ file so see if +things are done right. In that case you need to disable compression: + +\starttyping +\nopdfcompression +\stoptyping + +\stopsection + +\startsection[title={Analyzing}] + +The \type {epdf} library that comes with \LUATEX\ offers a userdata interface to +\PDF\ files. On top of that \CONTEXT\ provides a more \LUA-ish access, using +tables. You can open a \PDF\ file with: + +\starttyping +local mypdf = lpdf.epdf.load(filename) +\stoptyping + +When opening is successful, you have access to a couple of tables: + +\starttyping +\NC \type{pages} \NC indexed \NC \NR +\NC \type{destinations} \NC hashed \NC \NR +\NC \type{javascripts} \NC hashed \NC \NR +\NC \type{widgets} \NC hashed \NC \NR +\NC \type{embeddedfiles} \NC hashed \NC \NR +\NC \type{layers} \NC indexed \NC \NR +\stoptyping + +These provide efficient access to some data that otherwise would take a bit of +code to deal with. Another top level table is the for \PDF\ characteristic \type +{Catalog}. Watch the capitalization: as with other native \PDF\ data structures, +keys are case sensitive and match the standard. + +Here is an example of usage: + +\starttyping +local MyDocument = lpdf.epdf.load("somefile.pdf") + +context.starttext() + + local pages = MyDocument.pages + local nofpages = pages.n + + context.starttabulate { "|c|c|c|" } + + context.NC() context("page") + context.NC() context("width") + context.NC() context("height") context.NR() + + for i=1, nofpages do + local page = pages[i] + local bbox = page.CropBox or page.MediaBox + context.NC() context(i) + context.NC() context(bbox[4]-bbox[2]) + context.NC() context(bbox[3]-bbox[1]) context.NR() + end + + context.stoptabulate() + +context.stoptext() +\stoptyping + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/cld/cld-callbacks.tex b/doc/context/sources/general/manuals/cld/cld-callbacks.tex new file mode 100644 index 000000000..c449af864 --- /dev/null +++ b/doc/context/sources/general/manuals/cld/cld-callbacks.tex @@ -0,0 +1,240 @@ +% language=uk + +\startcomponent cld-callbacks + +\environment cld-environment + +\startchapter[title={Callbacks}] + +\startsection [title={Introduction}] + +\index {callbacks} + +The \LUATEX\ engine provides the usual basic \TEX\ functionality plus a bit more. +It is a deliberate choice not to extend the core engine too much. Instead all +relevant processes can be overloaded by new functionality written in \LUA. In +\CONTEXT\ callbacks are wrapped in a protective layer: on the one hand there is +extra functionality (usually interfaced through macros) and on the other hand +users can pop in their own handlers using hooks. Of course a plugged in function +has to do the right thing and not mess up the data structures. In this chapter +the layer on top of callbacks is described. + +\stopsection + +\startsection [title={Actions}] + +\index {nodelists} + +Nearly all callbacks in \LUATEX\ are used in \CONTEXT. In the following list the +callbacks tagged with \type {enabled} are used and frozen, the ones tagged \type +{disabled} are blocked and never used, while the ones tagged \type {undefined} +are yet unused. + +% \ctxlua{callbacks.table()} % \ctxlua{callbacks.report()} +\ctxcommand{showcallbacks()} + +Eventually all callbacks will be used so don't rely on undefined callbacks not +being protected. Some callbacks are only set when certain functionality is +enabled. + +It may sound somewhat harsh but if users kick in their own code, we cannot +guarantee \CONTEXT's behaviour any more and support becomes a pain. If you really +need to use a callback yourself, you should use one of the hooks and make sure +that you return the right values. + +All callbacks related to file handling, font definition and housekeeping are +frozen and cannot be overloaded. A reason for this are that we need some kind of +protection against misuse. Another reason is that we operate in a well defined +environment, the so called \TEX\ directory structure, and we don't want to mess +with that. And of course, the overloading permits \CONTEXT\ to provide extensions +beyond regular engine functionality. + +So as a fact we only open up some of the node list related callbacks and these +are grouped as follows: + +\starttabulate[|l|l|p|] +\FL +\NC \bf category \NC \bf callback \NC \bf usage \NC \NR +\TL +\NC \type{processors} \NC \type{pre_linebreak_filter} \NC called just before the paragraph is broken into lines \NC \NR +\NC \NC \type{hpack_filter} \NC called just before a horizontal box is constructed \NC \NR +\NC \type{finalizers} \NC \type{post_linebreak_filter} \NC called just after the paragraph has been broken into lines \NC \NR +\NC \type{shipouts} \NC \type{no callback yet} \NC applied to the box (or xform) that is to be shipped out \NC \NR +\NC \type{mvlbuilders} \NC \type{buildpage_filter} \NC called after some material has been added to the main vertical list \NC \NR +\NC \type{vboxbuilders} \NC \type{vpack_filter} \NC called when some material is added to a vertical box \NC \NR +%NC \type{parbuilders} \NC \type{linebreak_filter} \NC called when a paragraph is to be broken into lines \NC \NR +%NC \type{pagebuilders} \NC \type{pre_output_filter} \NC called when a page it fed into the output routing \NC \NR +\NC \type{math} \NC \type{mlist_to_hlist} \NC called just after the math list is created, before it is turned into an horizontal list \NC \NR +\BL +\stoptabulate + +Each category has several subcategories but for users only two make sense: \type +{before} and \type {after}. Say that you want to hook some tracing into the \type +{mvlbuilder}. This is how it's done: + +\starttyping +function third.mymodule.myfunction(where) + nodes.show_simple_list(tex.lists.contrib_head) +end + +nodes.tasks.appendaction("processors", "before", "third.mymodule.myfunction") +\stoptyping + +As you can see, in this case the function gets no \type {head} passed (at least +not currently). This example also assumes that you know how to access the right +items. The arguments and return values are given below. \footnote {This interface +might change a bit in future versions of \CONTEXT. Therefore we will not discuss +the few more optional arguments that are possible.} + +\starttabulate[|l|l|p|] +\FL +\NC \bf category \NC \bf arguments \NC \bf return value \NC \NR +\TL +\NC \type{processors} \NC \type{head, ...} \NC \type{head, done} \NC \NR +\NC \type{finalizers} \NC \type{head, ...} \NC \type{head, done} \NC \NR +\NC \type{shipouts} \NC \type{head} \NC \type{head, done} \NC \NR +\NC \type{mvlbuilders} \NC \NC \type{done} \NC \NR +\NC \type{vboxbuilders} \NC \type{head, ...} \NC \type{head, done} \NC \NR +\NC \type{parbuilders} \NC \type{head, ...} \NC \type{head, done} \NC \NR +\NC \type{pagebuilders} \NC \type{head, ...} \NC \type{head, done} \NC \NR +\NC \type{math} \NC \type{head, ...} \NC \type{head, done} \NC \NR +\LL +\stoptabulate + +\stopsection + +\startsection [title={Tasks}] + +\index {tasks} + +In the previous section we already saw that the actions are in fact tasks and +that we can append (and therefore also prepend) to a list of tasks. The \type +{before} and \type {after} task lists are valid hooks for users contrary to the +other tasks that can make up an action. However, the task builder is generic +enough for users to be used for individual tasks that are plugged into the user +hooks. + +Of course at some point, too many nested tasks bring a performance penalty with +them. At the end of a run \MKIV\ reports some statistics and timings and these +can give you an idea how much time is spent in \LUA. + +The following tables list all the registered tasks for the processors actions: + +\ctxlua{nodes.tasks.table("processors")} + +Some of these do have subtasks and some of these even more, so you can imagine +that quite some action is going on there. + +The finalizer tasks are: + +\ctxlua{nodes.tasks.table("finalizers")} + +Shipouts concern: + +\ctxlua{nodes.tasks.table("shipouts")} + +There are not that many mvlbuilder tasks currently: + +\ctxlua{nodes.tasks.table("mvlbuilders")} + +The vboxbuilder perform similar tasks: + +\ctxlua{nodes.tasks.table("vboxbuilders")} + +In the future we expect to have more parbuilder tasks. Here again there are +subtasks that depend on the current typesetting environment, so this is the right +spot for language specific treatments. + +\ctxlua{nodes.tasks.table("parbuilders")} + +The following actions are applied just before the list is passed on the the +output routine. The return value is a vlist. + +\ctxlua{nodes.tasks.table("pagebuilders")} + +{\em Both the parbuilders and pagebuilder tasks are unofficial and not yet meant +for users.} + +Finally, we have tasks related to the math list: + +\ctxlua{nodes.tasks.table("math")} + +As \MKIV\ is developed in sync with \LUATEX\ and code changes from experimental +to more final and reverse, you should not be too surprised if the registered +function names change. + +You can create your own task list with: + +\starttyping +nodes.tasks.new("mytasks",{ "one", "two" }) +\stoptyping + +After that you can register functions. You can append as well as prepend them +either or not at a specific position. + +\starttyping +nodes.tasks.appendaction ("mytask","one","bla.alpha") +nodes.tasks.appendaction ("mytask","one","bla.beta") + +nodes.tasks.prependaction("mytask","two","bla.gamma") +nodes.tasks.prependaction("mytask","two","bla.delta") + +nodes.tasks.appendaction ("mytask","one","bla.whatever","bla.alpha") +\stoptyping + +Functions can also be removed: + +\starttyping +nodes.tasks.removeaction("mytask","one","bla.whatever") +\stoptyping + +As removal is somewhat drastic, it is also possible to enable and disable +functions. From the fact that with these two functions you don't specify a +category (like \type {one} or \type {two}) you can conclude that the function +names need to be unique within the task list or else all with the same name +within this task will be disabled. + +\starttyping +nodes.tasks.enableaction ("mytask","bla.whatever") +nodes.tasks.disableaction("mytask","bla.whatever") +\stoptyping + +The same can be done with a complete category: + +\starttyping +nodes.tasks.enablegroup ("mytask","one") +nodes.tasks.disablegroup("mytask","one") +\stoptyping + +There is one function left: + +\starttyping +nodes.tasks.actions("mytask",2) +\stoptyping + +This function returns a function that when called will perform the tasks. In this +case the function takes two extra arguments in addition to \type {head}. +\footnote {Specifying this number permits for some optimization but is not really +needed} + +Tasks themselves are implemented on top of sequences but we won't discuss them +here. + +\stopsection + +\startsection [title={Paragraph and page builders}] + +Building paragraphs and pages is implemented differently and has no user hooks. +There is a mechanism for plugins but the interface is quite experimental. + +\stopsection + +\startsection [title={Some examples}] + +{\em todo} + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/cld/cld-contents.tex b/doc/context/sources/general/manuals/cld/cld-contents.tex new file mode 100644 index 000000000..132da7dff --- /dev/null +++ b/doc/context/sources/general/manuals/cld/cld-contents.tex @@ -0,0 +1,11 @@ +\startcomponent cld-contents + +\environment cld-environment + +\starttitle[title=Contents] + + \placelist[chapter,section][criterium=text,aligntitle=yes] + +\stoptitle + +\stopcomponent diff --git a/doc/context/sources/general/manuals/cld/cld-ctxfunctions.tex b/doc/context/sources/general/manuals/cld/cld-ctxfunctions.tex new file mode 100644 index 000000000..f71030e50 --- /dev/null +++ b/doc/context/sources/general/manuals/cld/cld-ctxfunctions.tex @@ -0,0 +1,782 @@ +% language=uk + +\startcomponent cld-ctxfunctions + +\environment cld-environment + +\startchapter[title={The \LUA\ interface code}] + +\startsection[title={Introduction}] + +There is a lot of \LUA\ code in \MKIV. Much is not exposed and a lot of what is +exposed is not meant to be used directly at the \LUA\ end. But there is also +functionality and data that can be accessed without side effects. + +In the following sections a subset of the built in functionality is discussed. +There are often more functions alongside those presented but they might change or +disappear. So, if you use undocumented features, be sure to tag them somehow in +your source code so that you can check them out when there is an update. Best +would be to have more functionality defined local so that it is sort of hidden +but that would be unpractical as for instance functions are often used in other +modules and or have to be available at the \TEX\ end. + +It might be tempting to add your own functions to namespaces created by \CONTEXT\ +or maybe overload some existing ones. Don't do this. First of all, there is no +guarantee that your code will not interfere, nor that it overloads future +functionality. Just use your own namespace. Also, future versions of \CONTEXT\ +might have a couple of protection mechanisms built in. Without doubt the +following sections will be extended as soon as interfaces become more stable. + +\stopsection + +\startsection[title={Characters}] + +% not discussed: +% +% characters.filters.utf.addgrapheme() +% characters.filters.utf.collapse() +% characters.getrange() +% characters.bidi[] +% tex.uprint() +% utf.string() +% characters.flush() + +There are quite some data tables defined but the largest is the character +database. You can consult this table any time you want but you're not supposed to +add or change its content if only because changes will be overwritten when you +update \CONTEXT. Future versions may carry more information. The table can be +accessed using an unicode number. A relative simple entry looks as follows: + +\ShowLuaExampleTableHex{characters.data[0x00C1]} + +Much of this is rather common information but some of it is specific for use with +\CONTEXT. Some characters have even more information, for instance those that +deal with mathematics: + +\ShowLuaExampleTableHex{characters.data[0x2190]} + +Not all characters have a real entry. For instance most \CJK\ characters are +virtual and share the same data: + +\ShowLuaExampleTableHex{characters.data[0x3456]} + +You can also access the table using \UTF\ characters: + +\ShowLuaExampleTable{characters.data["ä"]} + +A more verbose string access is also supported: + +\ShowLuaExampleTableHex{characters.data["U+0070"]} + +Another (less usefull) table contains information about ranges in this character +table. You can access this table using rather verbose names, or you can use +collapsed lowercase variants. + +\ShowLuaExampleTableHex{characters.blocks["CJK Compatibility Ideographs"]} + +\ShowLuaExampleTableHex{characters.blocks["hebrew"]} + +\ShowLuaExampleTableHex{characters.blocks["combiningdiacriticalmarks"]} + +Some fields can be accessed using functions. This can be handy when you need that +information for tracing purposes or overviews. There is some overhead in the +function call, but you get some extra testing for free. You can use characters as +well as numbers as index. + +\ShowLuaExampleString{characters.contextname("ä")} +\ShowLuaExampleString{characters.adobename(228)} +\ShowLuaExampleString{characters.description("ä")} + +The category is normally a two character tag, but you can also ask for a more +verbose variant: + +\ShowLuaExampleString{characters.category(228)} +\ShowLuaExampleString{characters.category(228,true)} + +The more verbose category tags are available in a table: + +\ShowLuaExampleString{characters.categorytags["lu"]} + +There are several fields in a character entry that help us to remap a character. +The \type {lccode} indicates the lowercase code point and the \type {uccode} to +the uppercase code point. The \type {shcode} refers to one or more characters +that have a similar shape. + +\ShowLuaExampleString{characters.shape ("ä")} +\ShowLuaExampleString{characters.uccode("ä")} +\ShowLuaExampleString{characters.lccode("ä")} + +\ShowLuaExampleString{characters.shape (100)} +\ShowLuaExampleString{characters.uccode(100)} +\ShowLuaExampleString{characters.lccode(100)} + +You can use these function or access these fields directly in an +entry, but we also provide a few virtual tables that avoid +accessing the whole entry. This method is rather efficient. + +\ShowLuaExampleString{characters.lccodes["ä"]} +\ShowLuaExampleString{characters.uccodes["ä"]} +\ShowLuaExampleString{characters.shcodes["ä"]} +\ShowLuaExampleString{characters.lcchars["ä"]} +\ShowLuaExampleString{characters.ucchars["ä"]} +\ShowLuaExampleString{characters.shchars["ä"]} + +As with other tables, you can use a number instead of an \UTF\ character. Watch +how we get a table for multiple shape codes but a string for multiple shape +characters. + +\ShowLuaExampleString{characters.lcchars[0x00C6]} +\ShowLuaExampleString{characters.ucchars[0x00C6]} +\ShowLuaExampleString{characters.shchars[0x00C6]} +\ShowLuaExampleTable {characters.shcodes[0x00C6]} + +These codes are used when we manipulate strings. Although there +are \type {upper} and \type {lower} functions in the \type +{string} namespace, the following ones are the real ones to be +used in critical situations. + +\ShowLuaExampleString{characters.lower("ÀÁÂÃÄÅàáâãäå")} +\ShowLuaExampleString{characters.upper("ÀÁÂÃÄÅàáâãäå")} +\ShowLuaExampleString{characters.shaped("ÀÁÂÃÄÅàáâãäå")} + +A rather special one is the following: + +\ShowLuaExampleString{characters.lettered("Only 123 letters + count!")} + +With the second argument is true, spaces are kept and collapsed. Leading and +trailing spaces are stripped. + +\ShowLuaExampleString{characters.lettered("Only 123 letters + count!",true)} + +Access to tables can happen by number or by string, although there are some +limitations when it gets too confusing. Take for instance the number \type {8} +and string \type {"8"}: if we would interpret the string as number we could never +access the entry for the character eight. However, using more verbose hexadecimal +strings works okay. The remappers are also available as functions: + +\ShowLuaExampleString{characters.tonumber("a")} +\ShowLuaExampleString{characters.fromnumber(100)} +\ShowLuaExampleString{characters.fromnumber(0x0100)} +\ShowLuaExampleString{characters.fromnumber("0x0100")} +\ShowLuaExampleString{characters.fromnumber("U+0100")} + +In addition to the already mentioned category information you can also use a more +direct table approach: + +\ShowLuaExampleString{characters.categories["ä"]} +\ShowLuaExampleString{characters.categories[100]} + +In a similar fashion you can test if a given character is in a specific category. +This can save a lot of tests. + +\ShowLuaExampleBoolean{characters.is_character[characters.categories[67]]} +\ShowLuaExampleBoolean{characters.is_character[67]} +\ShowLuaExampleBoolean{characters.is_character[characters.data[67].category]} +\ShowLuaExampleBoolean{characters.is_letter[characters.data[67].category]} +\ShowLuaExampleBoolean{characters.is_command[characters.data[67].category]} + +Another virtual table is the one that provides access to special information, for +instance about how a composed character is made up of components. + +\ShowLuaExampleString{characters.specialchars["ä"]} +\ShowLuaExampleString{characters.specialchars[100]} + +The outcome is often similar to output that uses the shapecode information. + +Although not all the code deep down in \CONTEXT\ is meant for use at the user +level, it sometimes can eb tempting to use data and helpers that are available as +part of the general housekeeping. The next table was used when looking into +sorting Korean. For practical reasons we limit the table to ten entries; +otherwise we would have ended up with hundreds of pages. + +\startbuffer +\startluacode +local data = characters.data +local map = characters.hangul.remapped + +local first, last = characters.getrange("hangulsyllables") + +last = first + 9 -- for now + +context.start() + +context.definedfont { "file:unbatang" } + +context.starttabulate { "|T||T||T||T||T|" } +for unicode = first, last do + local character = data[unicode] + local specials = character.specials + if specials then + context.NC() + context.formatted("%04V",unicode) + context.NC() + context.formatted("%c",unicode) + for i=2,4 do + local chr = specials[i] + if chr then + chr = map[chr] or chr + context.NC() + context.formatted("%04V",chr) + context.NC() + context.formatted("%c",chr) + else + context.NC() + context.NC() + end + end + context.NC() + context(character.description) + context.NC() + context.NR() + end +end +context.stoptabulate() + +context.stop() +\stopluacode +\stopbuffer + +\getbuffer \typebuffer + +\stopsection + +\startsection[title={Fonts}] + +% not discussed (as not too relevant for users): +% +% cache cache_version +% nomath +% units units_per_em +% direction embedding encodingbytes +% boundarychar boundarychar_label +% has_italic has_math +% tounicode sub +% colorscheme (will probably become a hash) +% language script +% spacer +% MathConstants and a few split_names +% +% tables.baselines + +There is a lot of code that deals with fonts but most is considered to be a black +box. When a font is defined, its data is collected and turned into a form that +\TEX\ likes. We keep most of that data available at the \LUA\ end so that we can +later use it when needed. In this chapter we discuss some of the possibilities. +More details can be found in the font manual(s) so we don't aim for completeness +here. + +A font instance is identified by its id, which is a number where zero is reserved +for the so called \type {nullfont}. The current font id can be requested by the +following function. + +\ShowLuaExampleString{fonts.currentid()} + +The \type {fonts.current()} call returns the table with data related to the +current id. You can access the data related to any id as follows: + +\starttyping +local tfmdata = fonts.identifiers[number] +\stoptyping + +Not all entries in the table make sense for the user as some are just meant to +drive the font initialization at the \TEX\ end or the backend. The next table +lists the most important ones. Some of the tables are just shortcuts to en entry +in one of the \type {shared} subtables. + +\starttabulate[|l|Tl|p|] +\NC \type{ascender} \NC number \NC the height of a line conforming the font \NC \NR +\NC \type{descender} \NC number \NC the depth of a line conforming the font \NC \NR +\NC \type{italicangle} \NC number \NC the angle of the italic shapes (if present) \NC \NR +\NC \type{designsize} \NC number \NC the design size of the font (if known) \NC \NR +\ML +\NC \type{size} \NC number \NC the size in scaled points if the font instance \NC \NR +\NC \type{factor} \NC number \NC the multiplication factor for unscaled dimensions \NC \NR +\NC \type{hfactor} \NC number \NC the horizontal multiplication factor \NC \NR +\NC \type{vfactor} \NC number \NC the vertical multiplication factor \NC \NR +\NC \type{extend} \NC number \NC the horizontal scaling to be used by the backend \NC \NR +\NC \type{slant} \NC number \NC the slanting to be applied by the backend \NC \NR +\ML +\NC \type{characters} \NC table \NC the scaled character (glyph) information (tfm) \NC \NR +\NC \type{descriptions} \NC table \NC the original unscaled glyph information (otf, afm, tfm) \NC \NR +\NC \type{indices} \NC table \NC the mapping from unicode slot to glyph index \NC \NR +\NC \type{unicodes} \NC table \NC the mapoing from glyph names to unicode \NC \NR +\NC \type{marks} \NC table \NC a hash table with glyphs that are marks as entry \NC \NR +\NC \type{parameters} \NC table \NC the font parameters as \TEX\ likes them \NC \NR +\NC \type{mathconstants} \NC table \NC the \OPENTYPE\ math parameters \NC \NR +\NC \type{mathparameters} \NC table \NC a reference to the \type {MathConstants} table \NC \NR +\NC \type{shared} \NC table \NC a table with information shared between instances \NC \NR +\NC \type{unique} \NC table \NC a table with information unique for this instance \NC \NR +\NC \type{unscaled} \NC table \NC the unscaled (intermediate) table \NC \NR +\NC \type{goodies} \NC table \NC the \CONTEXT\ specific extra font information \NC \NR +\NC \type{fonts} \NC table \NC the table with references to other fonts \NC \NR +\NC \type{cidinfo} \NC table \NC a table with special information for the backend \NC \NR +\ML +\NC \type{filename} \NC string \NC the full path of the loaded font \NC \NR +\NC \type{fontname} \NC string \NC the font name as specified in the font (limited in size) \NC \NR +\NC \type{fullname} \NC string \NC the complete font name as specified in the font \NC \NR +\NC \type{name} \NC string \NC the (short) name of the font \NC \NR +\NC \type{psname} \NC string \NC the (unique) name of the font as used by the backend \NC \NR +\ML +\NC \type{hash} \NC string \NC the hash that makes this instance unique \NC \NR +\NC \type{id} \NC number \NC the id (number) that \TEX\ will use for this instance \NC \NR +\ML +\NC \type{type} \NC string \NC an idicator if the font is \type {virtual} or \type {real} \NC \NR +\NC \type{format} \NC string \NC a qualification for this font, e.g.\ \type {opentype} \NC \NR +\NC \type{mode} \NC string \NC the \CONTEXT\ processing mode, \type {node} or \type {base} \NC \NR +\ML +\stoptabulate + +The \type {parameters} table contains variables that are used by \TEX\ itself. +You can use numbers as index and these are equivalent to the so called \type +{\fontdimen} variables. More convenient is is to access by name: + +\starttabulate[|l|p|] +\NC \type{slant} \NC the slant per point (seldom used) \NC \NR +\NC \type{space} \NC the interword space \NC \NR +\NC \type{spacestretch} \NC the interword stretch \NC \NR +\NC \type{spaceshrink} \NC the interword shrink \NC \NR +\NC \type{xheight} \NC the x|-|height (not per se the heigth of an x) \NC \NR +\NC \type{quad} \NC the so called em|-|width (often the width of an emdash)\NC \NR +\NC \type{extraspace} \NC additional space added in specific situations \NC \NR +\stoptabulate + +The math parameters are rather special and explained in the \LUATEX\ manual. +Quite certainly you never have to touch these parameters at the \LUA\ end. + +En entry in the \type {characters} table describes a character if we have entries +within the \UNICODE\ range. There can be entries in the private area but these +are normally variants of a shape or special math glyphs. + +\starttabulate[|l|p|] +\NC \type{name} \NC the name of the character \NC \NR +\NC \type{index} \NC the index in the raw font table \NC \NR +\NC \type{height} \NC the scaled height of the character \NC \NR +\NC \type{depth} \NC the scaled depth of the character \NC \NR +\NC \type{width} \NC the scaled height of the character \NC \NR +\NC \type{tounicode} \NC a \UTF-16 string representing the conversion back to unicode \NC \NR +\NC \type{expansion_factor} \NC a multiplication factor for (horizontal) font expansion \NC \NR +\NC \type{left_protruding} \NC a multiplication factor for left side protrusion \NC \NR +\NC \type{right_protruding} \NC a multiplication factor for right side protrusion \NC \NR +\NC \type{italic} \NC the italic correction \NC \NR +\NC \type{next} \NC a pointer to the next character in a math size chain \NC \NR +\NC \type{vert_variants} \NC a pointer to vertical variants conforming \OPENTYPE\ math \NC \NR +\NC \type{horiz_variants} \NC a pointer to horizontal variants conforming \OPENTYPE\ math \NC \NR +\NC \type{top_accent} \NC information with regards to math top accents \NC \NR +\NC \type{mathkern} \NC a table describing stepwise math kerning (following the shape) \NC \NR +\NC \type{kerns} \NC a table with intercharacter kerning dimensions \NC \NR +\NC \type{ligatures} \NC a (nested) table describing ligatures that start with this character \NC \NR +\NC \type{commands} \NC a table with commands that drive the backend code for a virtual shape \NC \NR +\stoptabulate + +Not all entries are present for each character. Also, in so called \type {node} +mode, the \type {ligatures} and \type {kerns} tables are empty because in that +case they are dealt with at the \LUA\ end and not by \TEX. + +% \startluacode +% local tfmdata = fonts.current() +% context.starttabulate{ "|l|pl|" } +% for k, v in table.sortedhash(tfmdata) do +% local tv = type(v) +% if tv == "string" or tv == "number" or tv == "boolean" then +% context.NC() +% string.tocontext(k) +% context.NC() +% string.tocontext(tostring(v)) +% context.NC() +% context.NR() +% end +% end +% context.stoptabulate() +% \stopluacode + +% \ShowLuaExampleTable{table.sortedkeys(fonts.current())} + +Say that you run into a glyph node and want to access the data related to that +glyph. Given that variable \type {n} points to the node, the most verbose way of +doing that is: + +\starttyping +local g = fonts.identifiers[n.id].characters[n.char] +\stoptyping + +Given the speed of \LUATEX\ this is quite fast. Another method is the following: + +\starttyping +local g = fonts.characters[n.id][n.char] +\stoptyping + +For some applications you might want faster access to critical +parameters, like: + +\starttyping +local quad = fonts.quads [n.id][n.char] +local xheight = fonts.xheights[n.id][n.char] +\stoptyping + +but that only makes sense when you don't access more than one such variable at +the same time. + +Among the shared tables is the feature specification: + +\ShowLuaExampleTable{fonts.current().shared.features} + +As features are a prominent property of \OPENTYPE\ fonts, there are a few +datatables that can be used to get their meaning. + +\ShowLuaExampleString{fonts.handlers.otf.tables.features['liga']} +\ShowLuaExampleString{fonts.handlers.otf.tables.languages['nld']} +\ShowLuaExampleString{fonts.handlers.otf.tables.scripts['arab']} + +There is a rather extensive font database built in but discussing its interface +does not make much sense. Most usage happens automatically when you use the \type +{name:} and \type {spec:} methods of defining fonts and the \type {mtx-fonts} +script is built on top of it. + +\ctxlua{fonts.names.load()} % could be metatable driven + +\ShowLuaExampleTable{table.sortedkeys(fonts.names.data)} + +You can load the database (if it's not yet loaded) with: + +\starttyping +names.load(reload,verbose) +\stoptyping + +When the first argument is true, the database will be rebuild. The second +arguments controls verbosity. + +Defining a font normally happens at the \TEX\ end but you can also do it in \LUA. + +\starttyping +local id, fontdata = fonts.definers.define { + lookup = "file", -- use the filename (file spec name) + name = "pagella-regular", -- in this case the filename + size = 10*65535, -- scaled points + global = false, -- define the font globally + cs = "MyFont", -- associate the name \MyFont + method = "featureset", -- featureset or virtual (* or @) + sub = nil, -- no subfont specifier + detail = "whatever", -- the featureset (or whatever method applies) +} +\stoptyping + +In this case the \type {detail} variable defines what featureset has to be +applied. You can define such sets at the \LUA\ end too: + +\starttyping +fonts.definers.specifiers.presetcontext ( + "whatever", + "default", + { + mode = "node", + dlig = "yes", + } +) +\stoptyping + +The first argument is the name of the featureset. The second argument can be an +empty string or a reference to an existing featureset that will be taken as +starting point. The final argument is the featureset. This can be a table or a +string with a comma separated list of key|/|value pairs. + +\stopsection + +\startsection[title={Nodes}] + +Nodes are the building blocks that make a document reality. Nodes are linked into +lists and at various moments in the typesetting process you can manipulate them. +Deep down in \CONTEXT\ we use quite some \LUA\ magic to manipulate lists of +nodes. Therefore it is no surprise that we have some tracing available. Take the +following box. + +\startbuffer +\setbox0\hbox{It's in \hbox{\bf all} those nodes.} +\stopbuffer + +\typebuffer \getbuffer + +This box contains characters and glue between the words. The box is already +constructed. There can also be kerns between characters, but of course only if +the font provides such a feature. Let's inspect this box: + +\ShowLuaExampleString{nodes.toutf(tex.box[0])} +\ShowLuaExampleString{nodes.toutf(tex.box[0].list)} + +This tracer returns the text and spacing and recurses into nested lists. The next +tracer does not do this and marks non glyph nodes as \type {[-]}: + +\ShowLuaExampleString{nodes.listtoutf(tex.box[0])} +\ShowLuaExampleString{nodes.listtoutf(tex.box[0].list)} + +A more verbose tracer is the next one. It does show a bit more detailed +information about the glyphs nodes. + +\ShowLuaExampleString{nodes.tosequence(tex.box[0])} +\ShowLuaExampleString{nodes.tosequence(tex.box[0].list)} + +The fourth tracer does not show that detail and collapses sequences of similar +node types. + +\ShowLuaExampleString{nodes.idstostring(tex.box[0])} +\ShowLuaExampleString{nodes.idstostring(tex.box[0].list)} + +The number of nodes in a list is identified with the \type {count} function. +Nested nodes are counted too. + +\ShowLuaExampleString{nodes.count(tex.box[0])} +\ShowLuaExampleString{nodes.count(tex.box[0].list)} + +There are functions to check node types and node id's: + +\starttyping +local str = node.type(1) +local num = node.id("vlist") +\stoptyping + +These are basic \LUATEX\ functions. In addition to those we also provide a few +mapping tables. There are two tables that map node id's to strings and backwards: + +\starttabulate +\NC \type{nodes.nodecodes} \NC regular nodes, some fo them are sort of private to the engine \NC \NR +\NC \type{nodes.noadcodes} \NC math nodes that later on are converted into regular nodes \NC \NR +\stoptabulate + +Nodes can have subtypes. Again we have tables that map the subtype numbers onto +meaningfull names and reverse. + +\starttabulate +\NC \type{nodes.listcodes} \NC subtypes of \type {hlist} and \type {vlist} nodes \NC \NR +\NC \type{nodes.kerncodes} \NC subtypes of \type {kern} nodes \NC \NR +\NC \type{nodes.gluecodes} \NC subtypes of \type {glue} nodes (skips) \NC \NR +\NC \type{nodes.glyphcodes} \NC subtypes of \type {glyph} nodes, the subtype can change \NC \NR +\NC \type{nodes.mathcodes} \NC math specific subtypes \NC \NR +\NC \type{nodes.fillcodes} \NC these are not really subtypes but indicate the strength of the filler \NC \NR +\NC \type{nodes.whatsitcodes} \NC subtypes of a rather large group of extension nodes \NC \NR +\stoptabulate + +Some of the names of types and subtypes have underscores but you can omit them +when you use these tables. You can use tables like this as follows: + +\starttyping +local glyph_code = nodes.nodecodes.glyph +local kern_code = nodes.nodecodes.kern +local glue_code = nodes.nodecodes.glue + +for n in nodes.traverse(list) do + local id == n.id + if id == glyph_code then + ... + elseif id == kern_code then + ... + elseif id == glue_code then + ... + else + ... + end +end +\stoptyping + +You only need to use such temporary variables in time critical code. In spite of +what you might think, lists are not that long and given the speed of \LUA\ (and +successive optimizations in \LUATEX) looping over a paragraphs is rather fast. + +Nodes are created using \type {node.new}. If you study the \CONTEXT\ code you +will notice that there are quite some functions in the \type {nodes.pool} +namespace, like: + +\starttyping +local g = nodes.pool.glyph(fnt,chr) +\stoptyping + +Of course you need to make sure that the font id is valid and that the referred +glyph in in the font. You can use the allocators but don't mess with the code in +the \type {pool} namespace as this might interfere with its usage all over +\CONTEXT. + +The \type {nodes} namespace provides a couple of helpers and some of them are +similar to ones provided in the \type {node} namespace. This has practical as +well as historic reasons. For instance some were prototypes functions that were +later built in. + +\starttyping +local head, current = nodes.before (head, current, new) +local head, current = nodes.after (head, current, new) +local head, current = nodes.delete (head, current) +local head, current = nodes.replace(head, current, new) +local head, current, old = nodes.remove (head, current) +\stoptyping + +Another category deals with attributes: + +\starttyping +nodes.setattribute (head, attribute, value) +nodes.unsetattribute (head, attribute) +nodes.setunsetattribute (head, attribute, value) +nodes.setattributes (head, attribute, value) +nodes.unsetattributes (head, attribute) +nodes.setunsetattributes(head, attribute, value) +nodes.hasattribute (head, attribute, value) +\stoptyping + +% context(typesetters.hpack("Hello World!")) +% context(typesetters.hpack("Hello World!",1,100*1024*10)) + +% nodes.firstchar +% nodes.firstcharinbox + +% maybe node-tst +% tasks and so +% number.points (to numbers) + +\stopsection + +% \startsection[title={Core}] +% {\em todo} +% \stopsection + +\startsection[title={Resolvers}] + +All \IO\ is handled by functions in the \type {resolvers} namespace. Most of the +code that you find in the \type {data-*.lua} files is of litle relevance for +users, especially at the \LUA\ end, so we won't discuss it here in great detail. + +The resolver code is modelled after the \KPSE\ library that itself implements the +\TEX\ Directory Structure in combination with a configuration file. However, we +go a bit beyond this structure, for instance in integrating support for other +resources that file systems. We also have our own configuration file. But +important is that we still support a similar logic too so that regular +configurations are dealt with. + +During a run \LUATEX\ needs files of a different kind: source files, font files, +images, etc. In practice you will probably only deal with source files. The most +fundamental function is \type {findfile}. The first argument is the filename to +be found. A second optional argument indicates the file type. + +The following table relates so called formats to suffixes and variables in the +configuration file. + +\startluacode +context.starttabulate { "|lp|lp|l|" } +context.NC() context.bold("variable") +context.NC() context.bold("format") +context.NC() context.bold("suffix") +context.NC() context.NR() +context.ML() +for k, v in table.sortedpairs(resolvers.relations.core) do + local names = v.names + local variable = v.variable + local suffixes = v.suffixes + context.NC() + if variable then + context.type(variable) + end + context.NC() + if names then + for i=1,#names do + context.type(names[i]) + context.par() + end + end + context.NC() + if suffixes then + context.type(table.concat(suffixes, " ")) + end + context.NC() + context.NR() +end +context.stoptabulate() +\stopluacode + +There are a couple of more formats but these are not that relevant in the +perspective of \CONTEXT. + +When a lookup takes place, spaces are ignored and formats are normalized to +lowercase. + +\ShowLuaExampleString{file.strip(resolvers.findfile("context.tex"),"tex/")} +\ShowLuaExampleString{file.strip(resolvers.findfile("context.mkiv"),"tex/")} +\ShowLuaExampleString{file.strip(resolvers.findfile("context"),"tex/")} +\ShowLuaExampleString{file.strip(resolvers.findfile("data-res.lua"),"tex/")} +\ShowLuaExampleString{file.strip(resolvers.findfile("lmsans10-bold"),"tex/")} +\ShowLuaExampleString{file.strip(resolvers.findfile("lmsans10-bold.otf"),"tex/")} +\ShowLuaExampleString{file.strip(resolvers.findfile("lmsans10-bold","otf"),"tex/")} +\ShowLuaExampleString{file.strip(resolvers.findfile("lmsans10-bold","opentype"),"tex/")} +\ShowLuaExampleString{file.strip(resolvers.findfile("lmsans10-bold","opentypefonts"),"tex/")} +\ShowLuaExampleString{file.strip(resolvers.findfile("lmsans10-bold","opentype fonts"),"tex/")} + +The plural variant of this function returns one or more matches. + +\ShowLuaExampleTable{resolvers.findfiles("texmfcnf.lua","cnf")} +\ShowLuaExampleTable{resolvers.findfiles("context.tex","")} + +% table.print(resolvers.instance.environment) +% table.print(resolvers.instance.variables) +% table.print(resolvers.instance.expansions) +% +% resolvers.expandbraces +% resolvers.expandpath +% resolvers.expandvar +% resolvers.showpath +% resolvers.var_value +% +% resolvers.getenv +% resolvers.variable() +% resolvers.expansion() +% resolvers.is_variable +% resolvers.is_expansion +% +% resolvers.unexpandedpathlist(str) +% resolvers.unexpandedpath(str) +% resolvers.cleanpathlist +% resolvers.expandpath +% resolvers.expandedpath +% resolvers.expandedpathlistfromvariable +% resolvers.expandpathfromvariable +% resolvers.expandbraces +% +% resolvers.findpath +% resolvers.findgivenfiles +% resolvers.findgivenfile +% resolvers.findwildcardfiles +% resolvers.findwildcardfile +% resolvers.showpath + +% data-tre as example +% schemes (data-she) +% caching (containers) +% findbinfile (open|load) +% variables / environment +% findtexfile opentexfile loadtexfile +% file:// + +% supp + +\stopsection + +\startsection[title={Mathematics (math)}] + {\em todo} +\stopsection + +\startsection[title={Graphics (grph)}] + {\em is a separate chapter} +\stopsection + +\startsection[title={Languages (lang)}] + {\em todo} +\stopsection + +\startsection[title={MetaPost (mlib)}] + {\em todo} +\stopsection + +\startsection[title={Lua\TeX\ (luat)}] + {\em todo} +\stopsection + +\startsection[title={Tracing (trac)}] + {\em todo} +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/cld/cld-environment.tex b/doc/context/sources/general/manuals/cld/cld-environment.tex new file mode 100644 index 000000000..1355110bd --- /dev/null +++ b/doc/context/sources/general/manuals/cld/cld-environment.tex @@ -0,0 +1,224 @@ +% language=uk + +\startenvironment cld-environment + +\usemodule[abr-04] + +\setuplayout + [width=middle, + height=middle, + backspace=2cm, + topspace=1cm, + footer=0pt, + bottomdistance=1cm, + bottom=1cm, + bottomspace=2cm] + +\setuppagenumbering + [alternative=doublesided] + +\definecolor[darkred] [r=.5] +\definecolor[darkgreen][g=.5] +\definecolor[darkblue] [b=.5] + +\definecolor[red] [darkred] +\definecolor[green][darkgreen] +\definecolor[blue] [darkblue] + +\definetype + [boldtypebig] + [style=\ttbfa] + +\definetype + [boldtype] + [style=\ttbf] + +\definetyping + [smalltyping] + [bodyfont=small] + +\setuptype + [color=blue] + +\setuptyping + [color=blue] + +\setupbodyfont + [palatino,11pt] + +\setuphead + [chapter] + [style=\bfc, + color=blue] + +\setuphead + [section] + [style=\bfb, + color=blue] + +\definehead + [summary] + [subsubsubsubject] + +\setuphead + [summary] + [style=, + deeptextcommand=\boldtypebig, + color=blue] + +\definehead + [subsummary] + [subsubsubsubsubject] + +\setuphead + [subsummary] + [style=, + before=\blank, + after=\blank, + deeptextcommand=\type, + command=\MySubSummaryHead, + color=blue] + +\unexpanded\def\MySummaryHead#1#2% + {\framed + [frame=off, + bottomframe=on, + offset=0cm] + {#2}} + +\unexpanded\def\MySubSummaryHead#1#2% + {\framed + [frame=off, + bottomframe=on, + offset=0cm] + {#2}} + +\setupwhitespace + [big] + +\setupheadertexts + [] + +\setupheadertexts + [] + [{\getmarking[chapter]\quad\pagenumber}] + [{\pagenumber\quad\getmarking[chapter]}] + [] + +\setupheader + [color=darkblue] + +\setuplist + [chapter,title] + [color=darkblue, + style=bold] + +\setupbottom + [style=\bfx, + color=darkred] + +\setupbottomtexts + [preliminary, uncorrected version -- \currentdate] + +% special functions + +\unexpanded\def\ShowLuaExampleOne#1#2#3% + {\bgroup + \obeyluatokens + \startsubsummary[title={#1.#2(#3)}] + \ctxlua{table.tocontext(#3)} + \stopsubsummary + \egroup} + +\unexpanded\def\ShowLuaExampleTwo#1#2#3% + {\bgroup + \obeyluatokens + \startsubsummary[title={#1.#2(#3)}] + \ctxlua{table.tocontext(#1.#2(#3))} + \stopsubsummary + \egroup} + +\unexpanded\def\ShowLuaExampleThree#1#2#3% + {\bgroup + \obeyluatokens + \startsubsummary[title={#1.#2(#3)}] + \ctxlua{string.tocontext(tostring(#1.#2(#3)))} + \stopsubsummary + \egroup} + +\unexpanded\def\ShowLuaExampleFour#1#2#3#4% + {\bgroup + \obeyluatokens + \startsubsummary[title={t=#3 #1.#2(t#4)}] + \ctxlua{local t = #3 #1.#2(t#4) table.tocontext(t)} + \stopsubsummary + \egroup} + +\unexpanded\def\ShowLuaExampleFive#1#2% + {\bgroup + \obeyluatokens + \startsubsummary[title={#1.#2}] + \ctxlua{string.tocontext(tostring(#1.#2))} + \stopsubsummary + \egroup} + +\unexpanded\def\ShowLuaExampleSix#1#2#3% + {\bgroup + \obeyluatokens + \startsubsummary[title={#1.#2(#3)}] + \ctxlua{string.tocontext(#1.#2(#3))} + \stopsubsummary + \egroup} + +\unexpanded\def\ShowLuaExampleSeven#1#2#3% + {\bgroup + \obeyluatokens + \startsubsummary[title={#1.#2(#3)}] + \ctxlua{string.tocontext(table.concat({#1.#2(#3)}," "))} + \stopsubsummary + \egroup} + +\unexpanded\def\ShowLuaExampleTable#1% + {\bgroup + \obeyluatokens + \startsubsummary[title={#1}] + \ctxlua{table.tocontext(#1,false)} + \stopsubsummary + \egroup} + +\unexpanded\def\ShowLuaExampleTableHex#1% + {\bgroup + \obeyluatokens + \startsubsummary[title={#1}] + \ctxlua{table.tocontext(#1,false,false,true,true)} % name, reduce, noquotes, hex + \stopsubsummary + \egroup} + +\unexpanded\def\ShowLuaExampleString#1% + {\bgroup + \obeyluatokens + \startsubsummary[title={#1}] + \ctxlua{string.tocontext(#1)} + \stopsubsummary + \egroup} + +\unexpanded\def\ShowLuaExampleBoolean#1% + {\bgroup + \obeyluatokens + \startsubsummary[title={#1}] + \ctxlua{boolean.tocontext(#1)} + \stopsubsummary + \egroup} + +% interaction + +\setupinteraction + [state=start, + color=, + contrastcolor=] + +\setuplist + [chapter,section] + [interaction=all] + +\stopenvironment diff --git a/doc/context/sources/general/manuals/cld/cld-files.tex b/doc/context/sources/general/manuals/cld/cld-files.tex new file mode 100644 index 000000000..38a7322b1 --- /dev/null +++ b/doc/context/sources/general/manuals/cld/cld-files.tex @@ -0,0 +1,78 @@ +% language=uk + +\startcomponent cld-macros + +\environment cld-environment + +\startchapter[title=Files] + +\startsection[title={Preprocessing}] + +Although this option must be used with care, it is possible to preprocess files +before they enter \TEX. The following example shows this. + +\starttyping +local function showline(str,filename,linenumber,noflines) + logs.simple("[lc] file: %s, line: %s of %s, length: %s", + file.basename(filename),linenumber,noflines,#str) +end + +local function showfile(str,filename) + logs.simple("[fc] file: %s, length: %s", + file.basename(filename),#str) +end + +resolvers.installinputlinehandler(showline) +resolvers.installinputfilehandler(showfile) +\stoptyping + +Preprocessors like this are rather innocent. If you want to manipulate the +content you need to be aware of the fact that modules and such also pass your +code, and manipulating them can give unexpected side effects. So, the following +code will not make \CONTEXT\ happy. + +\starttyping +local function foo() + return "bar" +end + +resolvers.installinputlinehandler(foo) +\stoptyping + +But, as we pass the filename, you can base your preprocessing on names. + +There can be multiple handlers active at the same time, and although more +detailed control is possible, the current interface does not provide that, simply +because having too many handlers active is asking for trouble anyway. What you +can do, is putting your handler in front or after the built in handlers. + +\starttyping +resolvers.installinputlinehandler("before",showline) +resolvers.installinputfilehandler("after", showfile) +\stoptyping + +Of course you can also preprocess files outside this mechanism, which in most +cases might be a better idea. However, the following example code is quite +efficient and robust. + +\starttyping +local function MyHandler(str,filename) + if file.suffix(filename) == "veryspecial" then + logs.simple("preprocessing file '%s',filename) + return MyConverter(str) + else + return str + end +end + +resolvers.installinputfilehandler("before",MyHandler) +\stoptyping + +In this case only files that have a suffix \type {.veryspecial} will get an extra +treatment. + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/cld/cld-gettingstarted.tex b/doc/context/sources/general/manuals/cld/cld-gettingstarted.tex new file mode 100644 index 000000000..5c7e1c263 --- /dev/null +++ b/doc/context/sources/general/manuals/cld/cld-gettingstarted.tex @@ -0,0 +1,437 @@ +% language=uk + +\startcomponent cld-gettingstarted + +\environment cld-environment + +\startchapter[title=Getting started] + +\startsection[title=Some basics] + +\index{processing} + +I assume that you have either the so called \CONTEXT\ standalone (formerly known +as minimals) installed or \TEXLIVE. You only need \LUATEX\ and can forget about +installing \PDFTEX\ or \XETEX, which saves you some megabytes and hassle. Now, +from the users perspective a \CONTEXT\ run goes like: + +\starttyping +context yourfile +\stoptyping + +and by default a file with suffix \type {tex}, \type {mkvi} or \type {mkvi} will +be processed. There are however a few other options: + +\starttyping +context yourfile.xml +context yourfile.rlx --forcexml +context yourfile.lua +context yourfile.pqr --forcelua +context yourfile.cld +context yourfile.xyz --forcecld +context yourfile.mp +context yourfile.xyz --forcemp +\stoptyping + +When processing a \LUA\ file the given file is loaded and just processed. This +options will seldom be used as it is way more efficient to let \type {mtxrun} +process that file. However, the last two variants are what we will discuss here. +The suffix \type {cld} is a shortcut for \CONTEXT\ \LUA\ Document. + +A simple \type {cld} file looks like this: + +\starttyping +context.starttext() +context.chapter("Hello There!") +context.stoptext() +\stoptyping + +So yes, you need to know the \CONTEXT\ commands in order to use this mechanism. +In spite of what you might expect, the codebase involved in this interface is not +that large. If you know \CONTEXT, and if you know how to call commands, you +basically can use this \LUA\ method. + +The examples that I will give are either (sort of) standalone, i.e.\ they are +dealt with from \LUA, or they are run within this document. Therefore you will +see two patterns. If you want to make your own documentation, then you can use +this variant: + +\starttyping +\startbuffer +context("See this!") +\stopbuffer + +\typebuffer \ctxluabuffer +\stoptyping + +I use anonymous buffers here but you can also use named ones. The other variant +is: + +\starttyping +\startluacode +context("See this!") +\stopluacode +\stoptyping + +This will process the code directly. Of course we could have encoded this +document completely in \LUA\ but that is not much fun for a manual. + +\stopsection + +\startsection[title=The main command] + +There are a few rules that you need to be aware of. First of all no syntax +checking is done. Second you need to know what the given commands expects in +terms of arguments. Third, the type of your arguments matters: + +\starttabulate[|||] +\NC \type{nothing} \EQ just the command, no arguments \NC \NR +\NC \type{string} \EQ an argument with curly braces \NC \NR +\NC \type{array} \EQ a list between square backets (sometimes optional) \NC \NR +\NC \type{hash} \EQ an assignment list between square brackets \NC \NR +\NC \type{boolean} \EQ when \type {true} a newline is inserted \NC \NR +\NC \EQ when \type {false}, omit braces for the next argument \NC \NR +\stoptabulate + +In the code above you have seen examples of this but here are some more: + +\starttyping +context.chapter("Some title") +context.chapter({ "first" }, "Some title") +context.startchapter({ title = "Some title", label = "first" }) +\stoptyping + +This blob of code is equivalent to: + +\starttyping +\chapter{Some title} +\chapter[first]{Some title} +\startchapter[title={Some title},label=first] +\stoptyping + +You can simplify the third line of the \LUA\ code to: + +\starttyping +context.startchapter { title = "Some title", label = "first" } +\stoptyping + +In case you wonder what the distinction is between square brackets and curly +braces: the first category of arguments concerns settings or lists of options or +names of instances while the second category normally concerns some text to be +typeset. + +Strings are interpreted as \TEX\ input, so: + +\starttyping +context.mathematics("\\sqrt{2^3}") +\stoptyping + +and if you don't want to escape: + +\starttyping +context.mathematics([[\sqrt{2^3}]]) +\stoptyping + +are both correct. As \TEX\ math is a language in its own and a de-facto standard +way of inputting math this is quite natural, even at the \LUA\ end. + +\stopsection + +\startsection[title=Spaces and Lines] + +\index{spaces} +\index{lines} + +In a regular \TEX\ file, spaces and newline characters are collapsed into one +space. At the \LUA\ end the same happens. Compare the following examples. First +we omit spaces: + +\startbuffer +context("left") +context("middle") +context("right") +\stopbuffer + +\typebuffer \ctxluabuffer + +Next we add spaces: + +\startbuffer +context("left") +context(" middle ") +context("right") +\stopbuffer + +\typebuffer \ctxluabuffer + +We can also add more spaces: + +\startbuffer +context("left ") +context(" middle ") +context(" right") +\stopbuffer + +\typebuffer \ctxluabuffer + +In principle all content becomes a stream and after that the \TEX\ parser will do +its normal work: collapse spaces unless configured to do otherwise. Now take the +following code: + +\startbuffer +context("before") +context("word 1") +context("word 2") +context("word 3") +context("after") +\stopbuffer + +\typebuffer \ctxluabuffer + +Here we get no spaces between the words at all, which is what we expect. So, how +do we get lines (or paragraphs)? + +\startbuffer +context("before") +context.startlines() +context("line 1") +context("line 2") +context("line 3") +context.stoplines() +context("after") +\stopbuffer + +\typebuffer \ctxluabuffer + +This does not work out well, as again there are no lines seen at the \TEX\ end. +Newline tokens are injected by passing \type {true} to the \type {context} +command: + +\startbuffer +context("before") +context.startlines() +context("line 1") context(true) +context("line 2") context(true) +context("line 3") context(true) +context.stoplines() +context("after") +\stopbuffer + +\typebuffer \ctxluabuffer + +Don't confuse this with: + +\startbuffer +context("before") context.par() +context("line 1") context.par() +context("line 2") context.par() +context("line 3") context.par() +context("after") context.par() +\stopbuffer + +\typebuffer \ctxluabuffer + +There we use the regular \type {\par} command to finish the current paragraph and +normally you will use that method. In that case, when set, whitespace will be +added between paragraphs. + +This newline issue is a somewhat unfortunate inheritance of traditional \TEX, +where \type {\n} and \type {\r} mean something different. I'm still not sure if +the \CLD\ do the right thing as dealing with these tokens also depends on the +intended effect. Catcodes as well as the \LUATEX\ input parser also play a role. +Anyway, the following also works: + +\startbuffer +context.startlines() +context("line 1\n") +context("line 2\n") +context("line 3\n") +context.stoplines() +\stopbuffer + +\typebuffer + +\stopsection + +\startsection[title=Direct output] + +\index{direct output} +\index{verbose} + +The \CONTEXT\ user interface is rather consistent and the use of special input +syntaxes is discouraged. Therefore, the \LUA\ interface using tables and strings +works quite well. However, imagine that you need to support some weird macro (or +a primitive) that does not expect its argument between curly braces or brackets. +The way out is to precede an argument by another one with the value \type +{false}. We call this the direct interface. This is demonstrated in the following +example. + +\startbuffer +\unexpanded\def\bla#1{[#1]} + +\startluacode +context.bla(false,"***") +context.par() +context.bla("***") +\stopluacode +\stopbuffer + +\typebuffer + +This results in: + +\getbuffer + +Here, the first call results in three \type {*} being passed, and \type {#1} +picks up the first token. The second call to \type {bla} gets \type {{***}} +passed so here \type {#1} gets the triplet. In practice you will seldom need the +direct interface. + +In \CONTEXT\ for historical reasons, combinations accept the following syntax: + +\starttyping +\startcombination % optional specification, like [2*3] + {\framed{content one}} {caption one} + {\framed{content two}} {caption two} +\stopcombination +\stoptyping + +You can also say: + +\starttyping +\startcombination + \combination {\framed{content one}} {caption one} + \combination {\framed{content two}} {caption two} +\stopcombination +\stoptyping + +When coded in \LUA, we can feed the first variant as follows: + +\startbuffer +context.startcombination() + context.direct("one","two") + context.direct("one","two") +context.stopcombination() +\stopbuffer + +\typebuffer + +To give you an idea what this looks like, we render it: + +\startlinecorrection[blank] +\ctxluabuffer +\stoplinecorrection + +So, the \type {direct} function is basically a no|-|op and results in nothing by +itself. Only arguments are passed. An equivalent but bit more ugly looking is: + +\starttyping +context.startcombination() + context(false,"one","two") + context(false,"one","two") +context.stopcombination() +\stoptyping + +\stopsection + +\startsection[title=Catcodes] + +\index{catcodes} + +If you are familiar with the inner working of \TEX, you will know that characters +can have special meanings. This meaning is determined by their catcodes. + +\startbuffer +context("$x=1$") +\stopbuffer + +\typebuffer + +This gives: \ctxluabuffer\ because the dollar tokens trigger inline math mode. If +you think that this is annoying, you can do the following: + +\startbuffer +context.pushcatcodes("text") +context("$x=1$") +context.popcatcodes() +\stopbuffer + +\typebuffer + +Now we get: \ctxluabuffer. There are several catcode regimes of +which only a few make sense in the perspective of the cld +interface. + +\starttabulate[|Tl|l|] +\NC ctx, ctxcatcodes, context \NC the normal \CONTEXT\ catcode regime \NC \NR +\NC prt, prtcatcodes, protect \NC the \CONTEXT\ protected regime, used for modules \NC \NR +\NC tex, texcatcodes, plain \NC the traditional (plain) \TEX\ regime \NC \NR +\NC txt, txtcatcodes, text \NC the \CONTEXT\ regime but with less special characters \NC \NR +\NC vrb, vrbcatcodes, verbatim \NC a regime specially meant for verbatim \NC \NR +\NC xml, xmlcatcodes \NC a regime specially meant for \XML\ processing \NC \NR +\stoptabulate + +In the second case you can still get math: + +\starttyping +context.pushcatcodes("text") +context.mathematics("x=1") +context.popcatcodes() +\stoptyping + +When entering a lot of math you can also consider this: + +\starttyping +context.startimath() +context("x") +context("=") +context("1") +context.stopimath() +\stoptyping + +Module writers of course can use \type {unprotect} and \type {protect} as they do +at the \TEX\ end. + +As we've seen, a function call to \type {context} acts like a print, as in: + +\startbuffer +context("test ") +context.bold("me") +context(" first") +\stopbuffer + +\typebuffer \ctxluabuffer + +When more than one argument is given, the first argument is considered a format +conforming the \type {string.format} function. + +\startbuffer +context.startimath() +context("%s = %0.5f",utf.char(0x03C0),math.pi) +context.stopimath() +\stopbuffer + +\typebuffer \ctxluabuffer + +This means that when you say: + +\starttyping +context(a,b,c,d,e,f) +\stoptyping + +the variables \type {b} till \type {f} are passed to the format and when the +format does not use them, they will not end up in your output. + +\starttyping +context("%s %s %s",1,2,3) +context(1,2,3) +\stoptyping + +The first line results in the three numbers being typeset, but in the second case +only the number~1 is typeset. + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/cld/cld-goodies.tex b/doc/context/sources/general/manuals/cld/cld-goodies.tex new file mode 100644 index 000000000..d5b4b5c9c --- /dev/null +++ b/doc/context/sources/general/manuals/cld/cld-goodies.tex @@ -0,0 +1,621 @@ +% language=uk + +\startcomponent cld-macros + +% \usemodule[man-01] +% \setvariables[document][title=Font Goodies, author=Hans Hagen] +% \setups[titlepage] + +\environment cld-environment + +\startchapter[title=Font goodies] + +\startsection[title=Introduction] + +One of the interesting aspects of \TEX\ is that it provides control over fonts +and \LUATEX\ provides quite some. In \CONTEXT\ we support basic functionality, +like \OPENTYPE\ features, as well as some extra functionality. We also have a +mechanism for making virtual fonts which is mostly used for the transition from +\TYPEONE\ math fonts to \OPENTYPE\ math fonts. Instead of hard coding specific +details in the core \LUA\ code, we use so called \LUA\ Font Goodies to control +them. These goodies are collected in tables and live in files. When a font is +loaded, one or more such goodie files can be loaded alongside. + +In the following typescript we load a goodies file that defines a virtual Lucida +math font. The goodie file is loaded immediately and some information in the +table is turned into a form that permits access later on: the virtual font id +\type {lucida-math} that is used as part of the font specification. + +\starttyping +\starttypescript [math] [lucida] + \loadfontgoodies[lucida-math] + \definefontsynonym[MathRoman][lucidamath@lucida-math] +\stoptypescript +\stoptyping + +Not all information is to be used directly. Some can be accessed when needed. In +the following case the file \type {dingbats.lfg} gets loaded (only once) when the +font is actually used. In that file, there is information that is used by the +\type {unicoding} feature. + +\starttyping +\definefontfeature + [dingbats] + [mode=base, + goodies=dingbats, + unicoding=yes] + +\definefont[dingbats][file:dingbats][features=dingbats] +\stoptyping + +In the following sections some aspects of goodies are discussed. We don't go into +details of what these goodies are, but just stick to the \LUA\ side of the +specification. + +\stopsection + +\startsection[title=Virtual math fonts] + +A virtual font is defined using the \type {virtuals} entry in the \type +{mathematics} subtable. As \TYPEONE\ fonts are used, an additional table \type +{mapfiles} is needed to specify the files that map filenames onto real files. + +\startsmalltyping +return { + name = "px-math", + version = "1.00", + comment = "Goodies that complement px math.", + author = "Hans Hagen", + copyright = "ConTeXt development team", + mathematics = { + mapfiles = { + "mkiv-px.map", + }, + virtuals = { + ["px-math"] = { + { name = "texgyrepagella-regular.otf", features = "virtualmath", main = true }, + { name = "rpxr.tfm", vector = "tex-mr" } , + { name = "rpxmi.tfm", vector = "tex-mi", skewchar=0x7F }, + { name = "rpxpplri.tfm", vector = "tex-it", skewchar=0x7F }, + { name = "pxsy.tfm", vector = "tex-sy", skewchar=0x30, parameters = true } , + { name = "pxex.tfm", vector = "tex-ex", extension = true } , + { name = "pxsya.tfm", vector = "tex-ma" }, + { name = "pxsyb.tfm", vector = "tex-mb" }, + { name = "texgyrepagella-bold.otf", vector = "tex-bf" } , + { name = "texgyrepagella-bolditalic.otf", vector = "tex-bi" } , + { name = "lmsans10-regular.otf", vector = "tex-ss", optional=true }, + { name = "lmmono10-regular.otf", vector = "tex-tt", optional=true }, + }, + } + } +} +\stopsmalltyping + +Here the \type {px-math} virtual font is defined. A series of fonts is loaded and +combined into one. The \type {vector} entry is used to tell the builder how to +map the glyphs onto \UNICODE. Additional vectors can be defined, for instance: + +\starttyping +fonts.encodings.math["mine"] = { + [0x1234] = 0x56, +} +\stoptyping + +Eventually these specifications wil be replaced by real \OPENTYPE\ fonts, but +even then we will keep the virtual definitions around. + +\startsection[title=Math alternates] + +In addition to the official \type {ssty} feature for enforcing usage of script +and scriptscript glyphs, some stylistic alternates can be present. + +\startsmalltyping +return { + name = "xits-math", + version = "1.00", + comment = "Goodies that complement xits (by Khaled Hosny).", + author = "Hans Hagen", + copyright = "ConTeXt development team", + mathematics = { + alternates = { + cal = { + feature = 'ss01', + value = 1, + comment = "Mathematical Calligraphic Alphabet" + }, + greekssup = { + feature = 'ss02', + value = 1, + comment = "Mathematical Greek Sans Serif Alphabet" + }, + greekssit = { + feature = 'ss03', + value = 1, + comment = "Mathematical Italic Sans Serif Digits" + }, + monobfnum = { + feature = 'ss04', + value = 1, + comment = "Mathematical Bold Monospace Digits" + }, + mathbbbf = { + feature = 'ss05', + value = 1, + comment = "Mathematical Bold Double-Struck Alphabet" + }, + mathbbit = { + feature = 'ss06', + value = 1, + comment = "Mathematical Italic Double-Struck Alphabet" + }, + mathbbbi = { + feature = 'ss07', + value = 1, + comment = "Mathematical Bold Italic Double-Struck Alphabet" + }, + upint = { + feature = 'ss08', + value = 1, + comment = "Upright Integrals" + }, + } + } +} +\stopsmalltyping + +These can be activated (in math mode) with the \type {\mathalternate} command +like: + +\starttyping +$\mathalternate{cal}Z$ +\stoptyping + +\stopsection + +\startsection[title=Math parameters] + +Another goodie related to math is the overload of some parameters (part of the +font itself) and variables (used in making virtual shapes). + +\startsmalltyping +return { + name = "lm-math", + version = "1.00", + comment = "Goodies that complement latin modern math.", + author = "Hans Hagen", + copyright = "ConTeXt development team", + mathematics = { + mapfiles = { + "lm-math.map", + "lm-rm.map", + "mkiv-base.map", + }, + virtuals = { + ["lmroman5-math"] = five, + ["lmroman6-math"] = six, + ["lmroman7-math"] = seven, + ["lmroman8-math"] = eight, + ["lmroman9-math"] = nine, + ["lmroman10-math"] = ten, + ["lmroman10-boldmath"] = ten_bold, + ["lmroman12-math"] = twelve, + ["lmroman17-math"] = seventeen, + }, + variables = { + joinrelfactor = 3, -- default anyway + }, + parameters = { -- test values + -- FactorA = 123.456, + -- FactorB = false, + -- FactorC = function(value,target,original) return 7.89 * target.factor end, + -- FactorD = "Hi There!", + }, + } +} +\stopsmalltyping + +In this example you see several virtuals defined which is due to the fact that +Latin Modern has design sizes. The values (like \type {twelve} are tables defined +before the return happens and are not shown here. The variables are rather +\CONTEXT\ specific, and the parameters are those that come with regular +\OPENTYPE\ math fonts (so the example names are invalid). + +In the following example we show two wasy to change parameters. In this case we +have a regular \OPENTYPE\ math font. First we install a patch to the font itself. +That change will be cached. We could also have changed that parameter using the +goodies table. The first method is the oldest. + +\startsmalltyping +local patches = fonts.handlers.otf.enhancers.patches + +local function patch(data,filename,threshold) + local m = data.metadata.math + if m then + local d = m.DisplayOperatorMinHeight or 0 + if d < threshold then + patches.report("DisplayOperatorMinHeight(%s -> %s)",d,threshold) + m.DisplayOperatorMinHeight = threshold + end + end +end + +patches.register( + "after", + "check math parameters", + "asana", + function(data,filename) + patch(data,filename,1350) + end +) + +local function less(value,target,original) + return 0.25 * value +end + +return { + name = "asana-math", + version = "1.00", + comment = "Goodies that complement asana.", + author = "Hans Hagen", + copyright = "ConTeXt development team", + mathematics = { + parameters = { + StackBottomDisplayStyleShiftDown = less, + StackBottomShiftDown = less, + StackDisplayStyleGapMin = less, + StackGapMin = less, + StackTopDisplayStyleShiftUp = less, + StackTopShiftUp = less, + StretchStackBottomShiftDown = less, + StretchStackGapAboveMin = less, + StretchStackGapBelowMin = less, + StretchStackTopShiftUp = less, + } + } +} +\stopsmalltyping + +We use a function so that the scaling is taken into account as the values passed +are those resulting from the scaling of the font to the requested size. + +\stopsection + +\startsection[title=Unicoding] + +We still have to deal with existing \TYPEONE\ fonts, and some of them have an +encoding that is hard to map onto \UNICODE\ without additional information. The +following goodie does that. The keys in the \type {unicodes} table are the glyph +names. Keep in mind that this only works with simple fonts. The \CONTEXT\ code +takes care of kerns but that's about it. + +\startsmalltyping +return { + name = "dingbats", + version = "1.00", + comment = "Goodies that complement dingbats (funny names).", + author = "Hans Hagen", + copyright = "ConTeXt development team", + remapping = { + tounicode = true, + unicodes = { + a1 = 0x2701, + a10 = 0x2721, + a100 = 0x275E, + a101 = 0x2761, + ............. + a98 = 0x275C, + a99 = 0x275D, + }, + }, +} +\stopsmalltyping + +The \type {tounicode} option makes sure that additional information ends ip in +the output so that cut|-|and|-|paste becomes more trustworthy. + +\stopsection + +\startsection[title=Typescripts] + +Some font collections, like antykwa, come with so many variants that defining +them all in typescripts becomes somewhat of a nuisance. While a regular font has +a typescript of a few lines, antykwa needs way more lines. This is why we provide +a nother way as well, using goodies. + +\startsmalltyping +return { + name = "antykwapoltawskiego", + version = "1.00", + comment = "Goodies that complement Antykwa Poltawskiego", + author = "Hans & Mojca", + copyright = "ConTeXt development team", + files = { + name = "antykwapoltawskiego", -- shared + list = { + ["AntPoltLtCond-Regular.otf"] = { + -- name = "antykwapoltawskiego", + weight = "light", + style = "regular", + width = "condensed", + }, + ["AntPoltLtCond-Italic.otf"] = { + weight = "light", + style = "italic", + width = "condensed", + }, + ["AntPoltCond-Regular.otf"] = { + weight = "normal", + style = "regular", + width = "condensed", + }, + + ....... + + + ["AntPoltExpd-BoldItalic.otf"] = { + weight = "bold", + style = "italic", + width = "expanded", + }, + }, + }, + typefaces = { -- for Mojca (experiment, names might change) + ["antykwapoltawskiego-light"] = { + shortcut = "rm", + shape = "serif", + fontname = "antykwapoltawskiego", + normalweight = "light", + boldweight = "medium", + width = "normal", + size = "default", + features = "default", + }, + + ....... + + }, +} +\stopsmalltyping + +This is a typical example of when a goodies file is loaded directly: + +\starttyping +\loadfontgoodies[antykwapoltawskiego] +\stoptyping + +A bodyfont is now defined by choosing from the defined combinations: + +\starttyping +\definetypeface + [name=mojcasfavourite, + preset=antykwapoltawskiego, + normalweight=light, + boldweight=bold, + width=expanded] + +\setupbodyfont + [mojcasfavourite] +\stoptyping + +This mechanism is a follow up on a discussion at a \CONTEXT\ conference, still +somewhat experimental, and a playground for Mojca. + +\stopsection + +\startsection[title=Font strategies] + +This goodie is closely related to the Oriental \TEX\ project where a dedicated +paragraph optimizer can be used. A rather advanced font is used (husayni) and its +associated goodie file is rather extensive. It defines stylistic features, +implements a couple of feature sets, provides colorschemes and most of all, +defines some strategies for making paragraphs look better. Some of the goodie +file is shown here. + +\startsmalltyping +local yes = "yes" + +local basics = { + analyze = yes, + mode = "node", + language = "dflt", + script = "arab", +} + +local analysis = { + ccmp = yes, + init = yes, medi = yes, fina = yes, +} + +local regular = { + rlig = yes, calt = yes, salt = yes, anum = yes, + ss01 = yes, ss03 = yes, ss07 = yes, ss10 = yes, ss12 = yes, ss15 = yes, ss16 = yes, + ss19 = yes, ss24 = yes, ss25 = yes, ss26 = yes, ss27 = yes, ss31 = yes, ss34 = yes, + ss35 = yes, ss36 = yes, ss37 = yes, ss38 = yes, ss41 = yes, ss42 = yes, ss43 = yes, + js16 = yes, +} + +local positioning = { + kern = yes, curs = yes, mark = yes, mkmk = yes, +} + +local minimal_stretching = { + js11 = yes, js03 = yes, +} + +local medium_stretching = { + js12=yes, js05=yes, +} + +local maximal_stretching= { + js13 = yes, js05 = yes, js09 = yes, +} + +local wide_all = { + js11 = yes, js12 = yes, js13 = yes, js05 = yes, js09 = yes, +} + +local shrink = { + flts = yes, js17 = yes, ss05 = yes, ss11 = yes, ss06 = yes, ss09 = yes, +} + +local default = { + basics, analysis, regular, positioning, -- xxxx = yes, yyyy = 2, +} + +return { + name = "husayni", + version = "1.00", + comment = "Goodies that complement the Husayni font by Idris Samawi Hamid.", + author = "Idris Samawi Hamid and Hans Hagen", + featuresets = { -- here we don't have references to featuresets + default = { + default, + }, + minimal_stretching = { + default, + js11 = yes, js03 = yes, + }, + medium_stretching = { + default, + js12=yes, js05=yes, + }, + maximal_stretching= { + default, + js13 = yes, js05 = yes, js09 = yes, + }, + wide_all = { + default, + js11 = yes, js12 = yes, js13 = yes, js05 = yes, js09 = yes, + }, + shrink = { + default, + flts = yes, js17 = yes, ss05 = yes, ss11 = yes, ss06 = yes, ss09 = yes, + }, + }, + solutions = { -- here we have references to featuresets, so we use strings! + experimental = { + less = { + "shrink" + }, + more = { + "minimal_stretching", + "medium_stretching", + "maximal_stretching", + "wide_all" + }, + }, + }, + stylistics = { + ...... + ss03 = "level-1 stack over Jiim, initial entry only", + ss04 = "level-1 stack over Jiim, initial/medial entry", + ...... + ss54 = "chopped finals", + ss55 = "idgham-tanwin", + ...... + js11 = "level-1 stretching", + js12 = "level-2 stretching", + ...... + js21 = "Haa.final_alt2", + }, + colorschemes = { + default = { + [1] = { + "Onedotabove", "Onedotbelow", ... + }, + [2] = { + "Fathah", "Dammah", "Kasrah", ... + }, + [3] = { + "Ttaa.waqf", "SsLY.waqf", "QLY.waqf", ... + }, + [4] = { + "ZeroArabic.ayah", "OneArabic.ayah", "TwoArabic.ayah", ... + }, + [5] = { + "Ayah", "Ayah.alt1", "Ayah.alt2", ... + } + } + } +} +\stopmalltyping + +Discussion of these goodies is beyond this document and happens elsewhere. + +\stopsection + +\startsection[title=Composition] + +The \type {compose} features extends a font with additional (virtual) shapes. +This is mostly used with \TYPEONE\ fonts that lack support for eastern european +languages. The type {compositions} subtable is used to control placement of +accents. This can be done per font. + +\startmalltyping +local defaultunits = 193 - 30 + +-- local compose = { +-- DY = defaultunits, +-- [0x010C] = { DY = defaultunits }, -- Ccaron +-- [0x02C7] = { DY = defaultunits }, -- textcaron +-- } + +-- fractions relative to delta(X_height - x_height) + +local defaultfraction = 0.85 + +local compose = { + DY = defaultfraction, -- uppercase compensation +} + +return { + name = "lucida-one", + version = "1.00", + comment = "Goodies that complement lucida.", + author = "Hans and Mojca", + copyright = "ConTeXt development team", + compositions = { + ["lbr"] = compose, + ["lbi"] = compose, + ["lbd"] = compose, + ["lbdi"] = compose, + } +} +\stopsmalltyping + +\stopsection + +\startsection[title=Postprocessing] + +You can hook postprocessors into the scaler. Future versions might provide more +control over where this happens. + +\startsmalltyping +local function statistics(tfmdata) + commands.showfontparameters(tfmdata) +end + +local function squeeze(tfmdata) + for k, v in next, tfmdata.characters do + v.height = 0.75 * (v.height or 0) + v.depth = 0.75 * (v.depth or 0) + end +end + +return { + name = "demo", + version = "1.00", + comment = "An example of goodies.", + author = "Hans Hagen", + postprocessors = { + statistics = statistics, + squeeze = squeeze, + }, +} +\stopsmalltyping + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/cld/cld-graphics.tex b/doc/context/sources/general/manuals/cld/cld-graphics.tex new file mode 100644 index 000000000..93ab80c2c --- /dev/null +++ b/doc/context/sources/general/manuals/cld/cld-graphics.tex @@ -0,0 +1,342 @@ +% language=uk + +\startcomponent cld-graphics + +\environment cld-environment + +\startchapter[title=Graphics] + +\startsection[title=The regular interface] + +If you are familiar with \CONTEXT, which by now probably is the case, you will +have noticed that it integrates the \METAPOST\ graphic subsystem. Drawing a +graphic is not that complex: + +\startbuffer +context.startMPcode() +context [[ + draw + fullcircle scaled 1cm + withpen pencircle scaled 1mm + withcolor .5white + dashed dashpattern (on 2mm off 2mm) ; + ]] +context.stopMPcode() +\stopbuffer + +\typebuffer + +We get a gray dashed circle rendered with an one millimeter thick line: + +\startlinecorrection +\ctxluabuffer +\stoplinecorrection + +So, we just use the regular commands and pass the drawing code as strings. +Although \METAPOST\ is a rather normal language and therefore offers loops and +conditions and the lot, you might want to use \LUA\ for anything else than the +drawing commands. Of course this is much less efficient, but it could be that you +don't care about speed. The next example demonstrates the interface for building +graphics piecewise. + +\startbuffer +context.resetMPdrawing() + +context.startMPdrawing() +context([[fill fullcircle scaled 5cm withcolor (0,0,.5) ;]]) +context.stopMPdrawing() + +context.MPdrawing("pickup pencircle scaled .5mm ;") +context.MPdrawing("drawoptions(withcolor white) ;") + +for i=0,50,5 do + context.startMPdrawing() + context("draw fullcircle scaled %smm ;",i) + context.stopMPdrawing() +end + +for i=0,50,5 do + context.MPdrawing("draw fullsquare scaled " .. i .. "mm ;") +end + +context.MPdrawingdonetrue() + +context.getMPdrawing() +\stopbuffer + +\typebuffer + +This gives: + +\startlinecorrection +\ctxluabuffer +\stoplinecorrection + +I the first loop we can use the format options associated with the simple \type +{context} call. This will not work in the second case. Even worse, passing more +than one argument will definitely give a faulty graphic definition. This is why +we have a special interface for \METAFUN. The code above can also be written as: + +\startbuffer +local metafun = context.metafun + +metafun.start() + +metafun("fill fullcircle scaled 5cm withcolor %s ;", + metafun.color("darkblue")) + +metafun("pickup pencircle scaled .5mm ;") +metafun("drawoptions(withcolor white) ;") + +for i=0,50,5 do + metafun("draw fullcircle scaled %smm ;",i) +end + +for i=0,50,5 do + metafun("draw fullsquare scaled %smm ;",i) +end + +metafun.stop() +\stopbuffer + +\typebuffer + +Watch the call to \type {color}, this will pass definitions at the \TEX\ end to +\METAPOST. Of course you really need to ask yourself \quotation {Do I want to use +\METAPOST\ this way?}. Using \LUA\ loops instead of \METAPOST\ ones makes much +more sense in the following case: + +\startbuffer +local metafun = context.metafun + +function metafun.barchart(t) + metafun.start() + local t = t.data + for i=1,#t do + metafun("draw unitsquare xyscaled(%s,%s) shifted (%s,0);", + 10, t[i]*10, i*10) + end + metafun.stop() +end + +local one = { 1, 4, 6, 2, 3, } +local two = { 8, 1, 3, 5, 9, } + +context.startcombination() + context.combination(metafun.delayed.barchart { data = one }, "one") + context.combination(metafun.delayed.barchart { data = two }, "two") +context.stopcombination() +\stopbuffer + +\typebuffer + +We get two barcharts alongside: + +\startlinecorrection +\ctxluabuffer +\stoplinecorrection + +\startbuffer +local template = [[ + path p, q ; color c[] ; + c1 := \MPcolor{darkblue} ; + c2 := \MPcolor{darkred} ; + p := fullcircle scaled 50 ; + l := length p ; + n := %s ; + q := subpath (0,%s/n*l) of p ; + draw q withcolor c2 withpen pencircle scaled 1 ; + fill fullcircle scaled 5 shifted point length q of q withcolor c1 ; + setbounds currentpicture to unitsquare shifted (-0.5,-0.5) scaled 60 ; + draw boundingbox currentpicture withcolor c1 ; + currentpicture := currentpicture xsized(1cm) ; +]] + +local function steps(n) + for i=0,n do + context.metafun.start() + context.metafun(template,n,i) + context.metafun.stop() + if i < n then + context.quad() + end + end +end + +context.hbox(function() steps(10) end) +\stopbuffer + +\typebuffer + +\startlinecorrection +\ctxluabuffer +\stoplinecorrection + +Using a template is quite convenient but at some point you can loose track of the +replacement values. Also, adding an extra value can force you to adapt the +following ones which enlarges the change for making an error. An alternative is +to use the template mechanism. Although this mechanism was originally made for +other purposes, you can use it for whatever you like. + +\startbuffer +local template = [[ + path p ; p := fullcircle scaled 4cm ; + draw p withpen pencircle scaled .5mm withcolor red ; + freedotlabel ("%lefttop%", point 1 of p,origin) ; + freedotlabel ("%righttop%", point 3 of p,origin) ; + freedotlabel ("%leftbottom%", point 5 of p,origin) ; + freedotlabel ("%rightbottom%",point 7 of p,origin) ; +]] + +local variables = { + lefttop = "one", + righttop = "two", + leftbottom = "three", + rightbottom = "four" , +} + +context.metafun.start() + context.metafun(utilities.templates.replace(template,variables)) +context.metafun.stop() +\stopbuffer + +\typebuffer + +Here we use named placeholders and pass a table with associated values to the +replacement function. Apart from convenience it's also more readable. And the +overhead is rather minimal. + +\startlinecorrection +\ctxluabuffer +\stoplinecorrection + +To some extent we fool ourselves with this kind of \LUA fication of \METAPOST\ +code. Of course we can make a nice \METAPOST\ library and put the code in a macro +instead. In that sense, doing this in \CONTEXT\ directly often gives better and +more efficient code. + +Of course you can use all relevant commands in the \LUA\ interface, like: + +\starttyping +context.startMPpage() + context("draw origin") + for i=0,100,10 do + context("..{down}(%d,0)",i) + end + context(" withcolor \\MPcolor{darkred} ;") +context.stopMPpage() +\stoptyping + +to get a graphic that has its own page. Don't use the \type {metafun} namespace +here, as it will not work here. This drawing looks like: + +\startlinecorrection +\startluacode +context.startMPcode() + context("draw origin") + for i=0,100,10 do + context("..{down}(%d,0)",i) + end + context(" withcolor red ;") +context.stopMPcode() +\stopluacode +\stoplinecorrection + +\stopsection + +\startsection[title=The \LUA\ interface] + +Messing around with graphics is normally not needed and if you do it, you'd +better know what you're doing. For \TEX\ a graphic is just a black box: a +rectangle with dimensions. You specify a graphic, in a format that the backend +can deal with, either or not apply some scaling and from then on a reference to +that graphic, normally wrapped in a normal \TEX\ box, enters the typesetting +machinery. Because the backend, the part that is responsible for translating +typeset content onto a viewable or printable format like \PDF, is built into +\LUATEX, at some point the real image has to be injected and the backend can only +handle a few image formats: \PNG, \JPG, \JBIG\ and \PDF. + +In \CONTEXT\ some more image formats are supported but in practice this boils +down to converting the image to a format that the backend can handle. Such a +conversion depends on an external programs and in order not to redo the +conversion each run \CONTEXT\ keeps track of the need to redo it. + +Some converters are built in, for example one that deals with \GIF\ images. This +is normally not a preferred format, but it happens that we have to deal with it +in cases where organizations use that format (if only because they use the web). +Here is how this works at the \LUA\ end: + +\starttyping +figures.converters.gif = { + pdf = function(oldname,newname) + os.execute(string.format("gm convert %s %s",oldname,newname)) + end +} +\stoptyping + +We use \type {gm} (Graphic Magic) for the conversion and pass the old and new +names. Given this definition at the \TEX\ end we can say: + +\starttyping +\externalfigure[whatever.gif][width=4cm] +\stoptyping + +Here is a another one: + +\starttyping +figures.converters.bmp = { + pdf = function(oldname,newname) + os.execute(string.format("gm convert %s %s",oldname,newname)) + end +} +\stoptyping + +In both examples we convert to \PDF\ because including this filetype is quite +fast. But you can also go to other formats: + +\starttyping +figures.converters.png = { + png = function(oldname,newname,resolution) + local command = string.format('gm convert -depth 1 "%s" "%s"',oldname,newname) + logs.report(string.format("running command %s",command)) + os.execute(command) + end +} +\stoptyping + +Instead of directly defining such a table, you can better do this: + +\starttyping +figures.converters.png = figures.converters.png or { } + +figures.converters.png.png = function(oldname,newname,resolution) + local command = string.format('gm convert -depth 1 "%s" "%s"',oldname,newname) + logs.report(string.format("running command %s",command)) + os.execute(command) +end +\stoptyping + +Here we check if a table exists and if not we extend the table. Such converters +work out of the box if you specify the suffix, but you can also opt for a simple: + +\starttyping +\externalfigure[whatever][width=4cm] +\stoptyping + +In this case \CONTEXT\ will check for all known supported formats, which is not +that efficient when no graphic can be found. In order to let for instance files +with suffix \type {bmp} can be included you have to register it as follows. The +second argument is the target. + +\starttyping +figures.registersuffix("bmp","bmp") +\stoptyping + +At some point more of the graphic inclusion helpers will be opened up for general +use but for now this is what you have available. + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/cld/cld-introduction.tex b/doc/context/sources/general/manuals/cld/cld-introduction.tex new file mode 100644 index 000000000..82fcb8007 --- /dev/null +++ b/doc/context/sources/general/manuals/cld/cld-introduction.tex @@ -0,0 +1,55 @@ +% language=uk + +\startcomponent cld-introduction + +\environment cld-environment + +\startchapter[title=Introduction] + +Sometimes you hear folks complain about the \TEX\ input language, i.e.\ the +backslashed commands that determine your output. Of course, when alternatives are +being discussed every one has a favourite programming language. In practice +coding a document in each of them triggers similar sentiments with regards to +coding as \TEX\ itself does. + +So, just for fun, I added a couple of commands to \CONTEXT\ \MKIV\ that permit +coding a document in \LUA. In retrospect it has been surprisingly easy to +implement a feature like this using metatables. Of course it's a bit slower than +using \TEX\ as input language but sometimes the \LUA\ interface is more readable +given the problem at hand. + +After a while I decided to use that interface in non|-|critical core \CONTEXT\ +code and in styles (modules) and solutions for projects. Using the \LUA\ approach +is sometimes more convenient, especially if the code mostly manipulates data. For +instance, if you process \XML\ files of database output you can use the interface +that is available at the \TEX\ end, or you can use \LUA\ code to do the work, or +you can use a combination. So, from now on, in \CONTEXT\ you can code your style +and document source in (a mixture of) \TEX, \XML, \METAPOST\ and in \LUA. + +In the following chapters I will introduce typesetting in \LUA, but as we rely on +\CONTEXT\ it is unavoidable that some regular \CONTEXT\ code shows up. The fact +that you can ignore backslashes does not mean that you can do without knowledge +of the underlying system. I expect that the user is somewhat familiar with this +macro package. Some chapters are follow ups on articles or earlier publications. + +Some information (and mechanism) show up in more than one chapter. This is a side +effect of \LUA\ being integrated in many places, so an isolated discussion is a +bit hard. + +In the meantime most of the code is rather stable and proven. However, this +manual will never be complete. You can find examples all over the code base, and +duplicating everything here makes no sense. If you find errors, please let me +know. If you think that something is missing, you can try to convince me to add +it. It's hard to keep up with what gets added so input is welcome. + +\blank[2*big] + +\startlines +Hans Hagen +Hasselt NL +2009 \emdash\ 2016 +\stoplines + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/cld/cld-logging.tex b/doc/context/sources/general/manuals/cld/cld-logging.tex new file mode 100644 index 000000000..cbb904a69 --- /dev/null +++ b/doc/context/sources/general/manuals/cld/cld-logging.tex @@ -0,0 +1,91 @@ +% language=uk + +% maybe this will become a section instead + +\startcomponent cld-logging + +\environment cld-environment + +\startchapter[title={Logging}] + +Logging and localized messages have always been rather standardized in \CONTEXT, +so upgrading the related mechanism had been quite doable. In \MKIV\ for a while +we had two systems in parallel: the old one, mostly targeted at messages at the +\TEX\ end, and a new one used at the \LUA\ end. But when more and more hybrid +code showed up, integrating both systems made sense. + +Most logging concerns tracing and can be turned on and off on demand. This kind +of control is now possible for all messages. Given that the right interfaces are +used, you can turn off all messages: + +\starttyping +context --silent +\stoptyping + +This was already possible in \MKII, but there \TEX's own messages still were +visible. More important is that we have control: + +\starttyping +context --silent=structure*,resolve*,font* +\stoptyping + +This will disable all reporting for these three categories. It is also possible +to only disable messages to the console: + +\starttyping +context --noconsole +\stoptyping + +In \CONTEXT\ you can use directives: + +\starttyping +\enabledirectives[logs.blocked=structure*,resolve*,font*] +\enabledirectives[logs.target=file] +\stoptyping + +As all logging is under \LUA\ control and because this (and other) kind of +control has to kick in early in the initialization the code might look somewhat +tricky. Users won't notice this because they only deal with the formal interface. +Here we will only discuss the \LUA\ interfaces. + +Messages related to tracing are done as follows: + +\starttyping +local report_whatever = logs.reporter("modules","whatever") + +report_whatever("not found: %s","this or that") +\stoptyping + +The first line defined a logger in the category \type {modules}. You can give a +second argument as well, the subcategory. Both will be shown as part of the +message, of which an example is given in the second line. + +These messages are shown directly, that is, when the function is called. However, +when you generate \TEX\ code, as we discuss in this document, you need to make +sure that the message is synchronized with that code. This can be done with a +messenger instead of a reporter. + +\starttyping +local report_numbers = logs.reporter("numbers","check") +local status_numbers = logs.messenger("numbers","check") + +status_numbers("number 1: %s, number 2: %s",123,456) +report_numbers("number 1: %s, number 2: %s",456,123) +\stoptyping + +Both reporters and messages are localized when the pattern given as first +argument can be found in the \type {patterns} subtable of the interface messages. +Categories and subcategories are also translated, but these are looked up in the +\type {translations} subtable. So in the case of + +\starttyping +report_whatever("found: %s",filename) +report_whatever("not found: %s",filename) +\stoptyping + +you should not be surprised if it gets translated. Of course the category and +subcategory provide some contextual information. + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/cld/cld-luafunctions.tex b/doc/context/sources/general/manuals/cld/cld-luafunctions.tex new file mode 100644 index 000000000..69586887d --- /dev/null +++ b/doc/context/sources/general/manuals/cld/cld-luafunctions.tex @@ -0,0 +1,2322 @@ +% language=uk + +% table.unnest : only used in special cases +% table.derive : set metatable if unset +% table.compact : remove empty subtables + +\environment cld-environment + +\startcomponent cld-luafunctions + +\startchapter[title=Lua Functions] + +\startsection[title={Introduction}] + +When you run \CONTEXT\ you have some libraries preloaded. If you look into the +\LUA\ files you will find more than is discussed here, but keep in mind that what +is not documented, might be gone or done different one day. Some extensions live +in the same namespace as those provided by stock \LUA\ and \LUATEX, others have +their own. There are many more functions and the more obscure (or never being +used) ones will go away. + +The \LUA\ code in \CONTEXT\ is organized in quite some modules. Those with names +like \type {l-*.lua} are rather generic and are automatically available when you +use \type {mtxrun} to run a \LUA\ file. These are discusses in this chapter. A +few more modules have generic properties, like some in the categories \type +{util-*.lua}, \type {trac-*.lua}, \type {luat-*.lua}, \type {data-*.lua} and +\type {lxml-*.lua}. They contain more specialized functions and are discussed +elsewhere. + +Before we move on the the real code, let's introduce a handy helper: + +\starttyping +inspect(somevar) +\stoptyping + +Whenever you feel the need to see what value a variable has you can insert this +function to get some insight. It knows how to deal with several data types. + +\stopsection + +\startsection[title={Tables}] + +\startsummary[title={[lua] concat}] + +These functions come with \LUA\ itself and are discussed in detail in the \LUA\ +reference manual so we stick to some examples. The \type {concat} function +stitches table entries in an indexed table into one string, with an optional +separator in between. If can also handle a slice of the table + +\starttyping +local str = table.concat(t) +local str = table.concat(t,separator) +local str = table.concat(t,separator,first) +local str = table.concat(t,separator,first,last) +\stoptyping + +Only strings and numbers can be concatenated. + +\ShowLuaExampleThree {table} {concat} {{"a","b","c","d","e"}} +\ShowLuaExampleThree {table} {concat} {{"a","b","c","d","e"},"+"} +\ShowLuaExampleThree {table} {concat} {{"a","b","c","d","e"},"+",2,3} + +\stopsummary + +\startsummary[title={[lua] insert remove}] + +You can use \type {insert} and \type {remove} for adding or replacing entries in +an indexed table. + +\starttyping +table.insert(t,value,position) +value = table.remove(t,position) +\stoptyping + +The position is optional and defaults to the last entry in the table. For +instance a stack is built this way: + +\starttyping +table.insert(stack,"top") +local top = table.remove(stack) +\stoptyping + +Beware, the \type {insert} function returns nothing. You can provide an +additional position: + +\starttyping +table.insert(list,"injected in slot 2",2) +local thiswastwo = table.remove(list,2) +\stoptyping + +\stopsummary + +\startsummary[title={[lua] unpack}] + +You can access entries in an indexed table as follows: + +\starttyping +local a, b, c = t[1], t[2], t[3] +\stoptyping + +but this does the same: + +\starttyping +local a, b, c = table.unpack(t) +\stoptyping + +This is less efficient but there are situations where \type {unpack} +comes in handy. + +\stopsummary + +\startsummary[title={[lua] sort}] + +Sorting is done with \type {sort}, a function that does not return a value but +operates on the given table. + +\starttyping +table.sort(t) +table.sort(t,comparefunction) +\stoptyping + +The compare function has to return a consistent equivalent of \type {true} or +\type {false}. For sorting more complex data structures there is a specialized +sort module available. + +\ShowLuaExampleFour {table} {sort} {{"a","b","c"}} {} +\ShowLuaExampleFour {table} {sort} {{"a","b","c"}} {,function(x,y) return x > y end} +\ShowLuaExampleFour {table} {sort} {{"a","b","c"}} {,function(x,y) return x < y end} + +\stopsummary + +\startsummary[title={sorted}] + +The built|-|in \type {sort} function does not return a value but sometimes it can be +if the (sorted) table is returned. This is why we have: + +\starttyping +local a = table.sorted(b) +\stoptyping + +\stopsummary + +% table.strip + +\startsummary[title={keys sortedkeys sortedhashkeys sortedhash}] + +The \type {keys} function returns an indexed list of keys. The order is undefined +as it depends on how the table was constructed. A sorted list is provided by +\type {sortedkeys}. This function is rather liberal with respect to the keys. If +the keys are strings you can use the faster alternative \type {sortedhashkeys}. + +\starttyping +local s = table.keys (t) +local s = table.sortedkeys (t) +local s = table.sortedhashkeys (t) +\stoptyping + +Because a sorted list is often processed there is also an iterator: + +\starttyping +for key, value in table.sortedhash(t) do + print(key,value) +end +\stoptyping + +There is also a synonym \type {sortedpairs} which sometimes looks more natural +when used alongside the \type {pairs} and \type {ipairs} iterators. + +\ShowLuaExampleTwo {table} {keys} {{ [1] = 2, c = 3, [true] = 1 }} +\ShowLuaExampleTwo {table} {sortedkeys} {{ [1] = 2, c = 3, [true] = 1 }} +\ShowLuaExampleTwo {table} {sortedhashkeys} {{ a = 2, c = 3, b = 1 }} + +\stopsummary + +\startsummary[title={serialize print tohandle tofile}] + +The \type {serialize} function converts a table into a verbose representation. +The \type {print} function does the same but prints the result to the console +which is handy for tracing. The \type {tofile} function writes the table to a +file, using reasonable chunks so that less memory is used. The fourth variant +\type {tohandle} takes a handle so that you can do whatever you like with the +result. + +\starttyping +table.serialize (root, name, reduce, noquotes, hexify) +table.print (root, name, reduce, noquotes, hexify) +table.tofile (filename, root, name, reduce, noquotes, hexify) +table.tohandle (handle, root, name, reduce, noquotes, hexify) +\stoptyping + +The serialization can be controlled in several ways. Often only the first two +options makes sense: + +\ShowLuaExampleOne {table} {serialize} {{ a = 2 }} +\ShowLuaExampleOne {table} {serialize} {{ a = 2 }, "name"} +\ShowLuaExampleOne {table} {serialize} {{ a = 2 }, true} +\ShowLuaExampleOne {table} {serialize} {{ a = 2 }, false} +\ShowLuaExampleOne {table} {serialize} {{ a = 2 }, "return"} +\ShowLuaExampleOne {table} {serialize} {{ a = 2 }, 12} + +\ShowLuaExampleOne {table} {serialize} {{ a = 2, [3] = "b", [true] = "6" }, nil, true} +\ShowLuaExampleOne {table} {serialize} {{ a = 2, [3] = "b", [true] = "6" }, nil, true, true} +\ShowLuaExampleOne {table} {serialize} {{ a = 2, [3] = "b", [true] = "6" }, nil, true, true, true} + +In \CONTEXT\ there is also a \type {tocontext} function that typesets the table +verbose. This is handy for manuals and tracing. + +\stopsummary + +\startsummary[title={identical are_equal}] + +These two function compare two tables that have a similar structure. The \type +{identical} variant operates on a hash while \type {are_equal} assumes an indexed +table. + +\starttyping +local b = table.identical (one, two) +local b = table.are_equal (one, two) +\stoptyping + +\ShowLuaExampleThree {table} {identical} {{ a = { x = 2 } }, { a = { x = 3 } }} +\ShowLuaExampleThree {table} {identical} {{ a = { x = 2 } }, { a = { x = 2 } }} + +\ShowLuaExampleThree {table} {are_equal} {{ a = { x = 2 } }, { a = { x = 3 } }} +\ShowLuaExampleThree {table} {are_equal} {{ a = { x = 2 } }, { a = { x = 2 } }} + +\ShowLuaExampleThree {table} {identical} {{ "one", "two" }, { "one", "two" }} +\ShowLuaExampleThree {table} {identical} {{ "one", "two" }, { "two", "one" }} + +\ShowLuaExampleThree {table} {are_equal} {{ "one", "two" }, { "one", "two" }} +\ShowLuaExampleThree {table} {are_equal} {{ "one", "two" }, { "two", "one" }} + +\stopsummary + +\startsummary[title={tohash fromhash swapped swaphash reversed reverse mirrored}] + +We use \type {tohash} quite a lot in \CONTEXT. It converts a list into a hash so +that we can easily check if (a string) is in a given set. The \type {fromhash} +function does the opposite: it creates a list of keys from a hashed table where +each value that is not \type {false} or \type {nil} is present. + +\starttyping +local hashed = table.tohash (indexed) +local indexed = table.fromhash(hashed) +\stoptyping + +The function \type {swapped} turns keys into values vise versa while the \type +{reversed} and \type {reverse} reverses the values in an indexed table. The last +one reverses the table itself (in|-|place). + +\starttyping +local swapped = table.swapped (indexedtable) +local reversed = table.reversed (indexedtable) +local reverse = table.reverse (indexedtable) +local mirrored = table.mirrored (hashedtable) +\stoptyping + +\ShowLuaExampleTwo {table} {tohash} {{ "a", "b", "c" }} +\ShowLuaExampleTwo {table} {fromhash} {{ a = true, b = false, c = true }} +\ShowLuaExampleTwo {table} {swapped} {{ "a", "b", "c" }} +\ShowLuaExampleTwo {table} {reversed} {{ "a", "b", "c" }} +\ShowLuaExampleTwo {table} {reverse} {{ 1, 2, 3, 4 }} +\ShowLuaExampleTwo {table} {mirrored} {{ a = "x", b = "y", c = "z" }} + +\stopsummary + +\startsummary[title={append prepend}] + +These two functions operate on a pair of indexed tables. The first table gets +appended or prepended by the second. The first table is returned as well. + +\starttyping +table.append (one, two) +table.prepend(one, two) +\stoptyping + +The functions are similar to loops using \type {insert}. + +\ShowLuaExampleTwo {table} {append} {{ "a", "b", "c" }, { "d", "e" }} +\ShowLuaExampleTwo {table} {prepend} {{ "a", "b", "c" }, { "d", "e" }} + +\stopsummary + +\startsummary[title={merge merged imerge imerged}] + +You can merge multiple hashes with \type {merge} and indexed tables with \type +{imerge}. The first table is the target and is returned. + +\starttyping +table.merge (one, two, ...) +table.imerge (one, two, ...) +\stoptyping + +The variants ending with a \type {d} merge the given list of tables and return +the result leaving the first argument untouched. + +\starttyping +local merged = table.merged (one, two, ...) +local merged = table.imerged (one, two, ...) +\stoptyping + +\ShowLuaExampleTwo {table} {merge} {{ a = 1, b = 2, c = 3 }, { d = 1 }, { a = 0 }} +\ShowLuaExampleTwo {table} {imerge} {{ "a", "b", "c" }, { "d", "e" }, { "f", "g" }} + +% \ShowLuaExampleTwo {table} {merged} {{ a = 1, b = 2, c = 3 }, { d = 1 }, { a = 0 }} +% \ShowLuaExampleTwo {table} {imerged} {{ "a", "b", "c" }, { "d", "e" }, { "f", "g" }} + +\stopsummary + +\startsummary[title={copy fastcopy}] + +When copying a table we need to make a real and deep copy. The \type {copy} +function is an adapted version from the \LUA\ wiki. The \type {fastopy} is faster +because it does not check for circular references and does not share tables when +possible. In practice using the fast variant is okay. + +\starttyping +local copy = table.copy (t) +local copy = table.fastcopy(t) +\stoptyping + +\stopsummary + +\startsummary[title={flattened}] + +A nested table can be unnested using \type {flattened}. Normally you will only +use this function if the content is somewhat predictable. Often using one of the +merge functions does a similar job. + +\starttyping +local flattened = table.flatten(t) +\stoptyping + +\ShowLuaExampleTwo {table} {flattened} {{ a = 1, b = 2, { c = 3 }, d = 4}} +\ShowLuaExampleTwo {table} {flattened} {{ 1, 2, { 3, { 4 } }, 5}} +\ShowLuaExampleTwo {table} {flattened} {{ 1, 2, { 3, { 4 } }, 5}, 1} +\ShowLuaExampleTwo {table} {flattened} {{ a = 1, b = 2, { c = 3 }, d = 4}} +\ShowLuaExampleTwo {table} {flattened} {{ 1, 2, { 3, { c = 4 } }, 5}} +\ShowLuaExampleTwo {table} {flattened} {{ 1, 2, { 3, { c = 4 } }, 5}, 1} + +\stopsummary + +\startsummary[title={loweredkeys}] + +The name says it all: this function returns a new table with the keys being lower +case. This is handy in cases where the keys have a change to be inconsistent, as +can be the case when users input keys and values in less controlled ways. + +\starttyping +local normalized = table.loweredkeys { a = "a", A = "b", b = "c" } +\stoptyping + +\ShowLuaExampleTwo {table} {loweredkeys} {{ a = 1, b = 2, C = 3}} + +\stopsummary + +\startsummary[title={contains}] + +This function works with indexed tables. Watch out, when you look for a match, +the number \type {1} is not the same as string \type {"1"}. The function returns +the index or \type {false}. + +\starttyping +if table.contains(t, 5 ) then ... else ... end +if table.contains(t,"5") then ... else ... end +\stoptyping + +\ShowLuaExampleThree {table} {contains} {{ "a", 2, true, "1"}, 1} +\ShowLuaExampleThree {table} {contains} {{ "a", 2, true, "1"}, "1"} + +\stopsummary + +\startsummary[title={unique}] + +When a table (can) contain duplicate entries you can get rid of them by using the +\type {unique} helper: + +\starttyping +local t = table.unique { 1, 2, 3, 4, 3, 2, 5, 6 } +\stoptyping + +\ShowLuaExampleTwo {table} {unique} { { "a", "b", "c", "a", "d" } } + +\stopsummary + +\startsummary[title={count}] + +The name speaks for itself: this function counts the number of entries in the +given table. For an indexed table \type {#t} is faster. + +\starttyping +local n = table.count(t) +\stoptyping + +\ShowLuaExampleThree {table} {count} {{ 1, 2, [4] = 4, a = "a" }} + +\stopsummary + +\startsummary[title={sequenced}] + +Normally, when you trace a table, printing the serialized version is quite +convenient. However, when it concerns a simple table, a more compact variant is: + +\starttyping +print(table.sequenced(t, separator)) +\stoptyping + +% beware: by default sequences has | as separator + +\ShowLuaExampleThree {table} {sequenced} {{ 1, 2, 3, 4}} +\ShowLuaExampleThree {table} {sequenced} {{ 1, 2, [4] = 4, a = "a" }, ", "} + +\stopsummary + +\stopsection + +\startsection[title=Math] + +In addition to the built-in math function we provide: \type {round}, \type {odd}, +\type {even}, \type {div}, \type {mod}, \type {sind}, \type {cosd} and +\type {tand}. + +At the \TEX\ end we have a helper \type {luaexpr} that you can use to do +calculations: + +\startbuffer + \luaexpr{1 + 2.3 * 4.5 + math.pi} = \cldcontext{1 + 2.3 * 4.5 + math.pi} +\stopbuffer + +\typebuffer + +Both calls return the same result, but the first one is normally faster than the +\type {context} command which has quite some overhead. + +\blank \getbuffer \blank + +The \type {\luaexpr} command can also better deal with for instance conditions, +where it returns \type {true} or \type {false}, while \type {\cldcontext} would +interpret the boolean value as a special signal. + +\stopsection + +\startsection[title=Booleans] + +\startsummary[title={tonumber}] + +This function returns the number one or zero. You will seldom need this function. + +\starttyping +local state = boolean.tonumber(str) +\stoptyping + +\ShowLuaExampleThree {boolean} {tonumber} {true} + +\stopsummary + +\startsummary[title={toboolean}] + +When dealing with configuration files or tables a bit flexibility in setting a +state makes sense, if only because in some cases it's better to say \type {yes} +than \type {true}. + +\starttyping +local b = toboolean(str) +local b = toboolean(str,tolerant) +\stoptyping + +When the second argument is true, the strings \type {true}, \type {yes}, \type +{on}, \type {1}, \type {t} and the number \type {1} all turn into \type {true}. +Otherwise only \type {true} is honoured. This function is also defined in the +global namespace. + +\ShowLuaExampleThree {string} {toboolean} {"true"} +\ShowLuaExampleThree {string} {toboolean} {"yes"} +\ShowLuaExampleThree {string} {toboolean} {"yes",true} + +\stopsummary + +\startsummary[title={is_boolean}] + +This function is somewhat similar to the previous one. It interprets the strings +\type {true}, \type {yes}, \type {on} and \type {t} as \type {true} and +\type{false}, \type {no}, \type {off} and \type {f} as \type {false}. Otherwise +\type {nil} is returned, unless a default value is given, in which case that is +returned. + +\starttyping +if is_boolean(str) then ... end +if is_boolean(str,default) then ... end +\stoptyping + +\ShowLuaExampleThree {string} {is_boolean} {"true"} +\ShowLuaExampleThree {string} {is_boolean} {"off"} +\ShowLuaExampleThree {string} {is_boolean} {"crap",true} + +\stopsummary + +\stopsection + +\startsection[title=Strings] + +\LUA\ strings are simply sequences of bytes. Of course in some places special +treatment takes place. For instance \type {\n} expands to one or more characters +representing a newline, depending on the operating system, but normally, as long +as you manipulate strings in the perspective of \LUATEX, you don't need to worry +about such issues too much. As \LUATEX\ is a \UTF-8 engine, strings normally are +in that encoding but again, it does not matter much as \LUA\ is quite agnostic +about the content of strings: it does not care about three characters reflecting +one \UNICODE\ character or not. This means that when you use for instance the +functions discussed here, or use libraries like \type {lpeg} behave as you +expect. + +Versions later than 0.75 are likely to have some basic \UNICODE\ support on board +but we can easily adapt to that. At least till \LUATEX\ version 0.75 we provided +the \type {slunicode} library but users cannot assume that that will be present for +ever. If you want to mess around with \UTF\ string, use the \type {utf} library +instead as that is the one we provide in \MKIV. It presents the stable interface to +whatever \LUA\ itself provides and|/|or what \LUATEX\ offers and|/|or what +is there because \MKIV\ implements it. + +\startsummary[title={[lua] byte char}] + +As long as we're dealing with \ASCII\ characters we can use these two functions to +go from numbers to characters and vise versa. + +\ShowLuaExampleSeven {string} {byte} {"luatex"} +\ShowLuaExampleSeven {string} {byte} {"luatex",1,3} +\ShowLuaExampleSeven {string} {byte} {"luatex",-3,-1} + +\ShowLuaExampleSeven {string} {char} {65} +\ShowLuaExampleSeven {string} {char} {65,66,67} + +\stopsummary + +\startsummary[title={[lua] sub}] + +You cannot directly access a character in a string but you can take any slice you +want using \type {sub}. You need to provide a start position and negative values +will count backwards from the end. + +\starttyping +local slice = string.sub(str,first,last) +\stoptyping + +\ShowLuaExampleThree {string} {sub} {"abcdef",2} +\ShowLuaExampleThree {string} {sub} {"abcdef",2,3} +\ShowLuaExampleThree {string} {sub} {"abcdef",-3,-2} + +\stopsummary + +\startsummary[title={[lua] gsub}] + +There are two ways of analyzing the content of a string. The more modern and +flexible approach is to use \type {lpeg}. The other one uses some functions in +the \type {string} namespace that accept so called patterns for matching. While +\type {lpeg} is more powerfull than regular expressions, the pattern matching is +less powerfull but sometimes faster and also easier to specify. In many cases it +can do the job quite well. + +\starttyping +local new, count = string.gsub(old,pattern,replacement) +\stoptyping + +The replacement can be a function. Often you don't want the number +of matches, and the way to avoid this is either to store the result +in a variable: + +\starttyping +local new = string.gsub(old,"lua","LUA") +print(new) +\stoptyping + +or to use parentheses to signal the interpreter that only one value +is return. + +\starttyping +print((string.gsub(old,"lua","LUA")) +\stoptyping + +Patterns can be more complex so you'd better read the \LUA\ manual if you want to +know more about them. + +\ShowLuaExampleThree {string} {gsub} {"abcdef","b","B"} +\ShowLuaExampleThree {string} {gsub} {"abcdef","[bc]",string.upper} + +An optional fourth argument specifies how often the replacement has to happen + +\ShowLuaExampleThree {string} {gsub} {"textextextex","tex","abc"} +\ShowLuaExampleThree {string} {gsub} {"textextextex","tex","abc",1} +\ShowLuaExampleThree {string} {gsub} {"textextextex","tex","abc",2} + +\stopsummary + +\startsummary[title={[lua] find}] + +The \type {find} function returns the first and last position of the match: + +\starttyping +local first, last = find(str,pattern) +\stoptyping + +If you're only interested if there is a match at all, it's enough to know that +there is a first position. No match returns \type {nil}. So, + +\starttyping +if find("luatex","tex") then ... end +\stoptyping + +works out okay. You can pass an extra argument to \type {find} that indicates the +start position. So you can use this function to loop over all matches: just start +again at the end of the last match. + +A fourth optional argument is a boolean that signals not to interpret the pattern +but use it as|-|is. + +\ShowLuaExampleThree {string} {find} {"abc.def","c\letterpercent.d",1,false} +\ShowLuaExampleThree {string} {find} {"abc.def","c\letterpercent.d",1,true} +\ShowLuaExampleThree {string} {find} {"abc\letterpercent.def","c\letterpercent.d",1,false} +\ShowLuaExampleThree {string} {find} {"abc\letterpercent.def","c\letterpercent.d",1,true} + +\stopsummary + +\startsummary[title={[lua] match gmatch}] + +With \type {match} you can split of bits and pieces of a string. The parenthesis +indicate the captures. + +\starttyping +local a, b, c, ... = string.match(str,pattern) +\stoptyping + +The \type {gmatch} function is used to loop over a string, for instance the +following code prints the elements in a comma separated list, ignoring spaces +after commas. + +\starttyping +for s in string.gmatch(str,"([^,%s])+") do + print(s) +end +\stoptyping + +A more detailed description can be found in the \LUA\ reference manual, so we +only mention the special directives. Characters are grouped in classes: + +\starttabulate[|lT|l|] +\HL +\NC \letterpercent a \NC letters \NC \NR +\NC \letterpercent l \NC lowercase letters \NC \NR +\NC \letterpercent u \NC uppercase letters \NC \NR +\NC \letterpercent d \NC digits \NC \NR +\NC \letterpercent w \NC letters and digits \NC \NR +\NC \letterpercent c \NC control characters \NC \NR +\NC \letterpercent p \NC punctuation \NC \NR +\NC \letterpercent x \NC hexadecimal characters \NC \NR +\NC \letterpercent s \NC space related characters \NC \NR +\HL +\stoptabulate + +You can create sets too: + +\starttabulate[|lT|l|] +\HL +\NC [\letterpercent l\letterpercent d] \NC lowercase letters and digits \NC \NR +\NC [^\letterpercent d\letterpercent p] \NC all characters except digits and punctuation \NC \NR +\NC [p-z] \NC all characters in the range \type {p} upto \type {z} \NC \NR +\NC [pqr] \NC all characters \type {p}, \type {q} and \type {r} \NC \NR +\HL +\stoptabulate + +There are some characters with special meanings: + +\starttabulate[|lT|l|] +\HL +\NC \letterhat \NC the beginning of a string \NC \NR +\NC \letterdollar \NC end of a string \NC \NR +\NC . \NC any character \NC \NR +\NC * \NC zero or more of the preceding specifier, greedy \NC \NR +\NC - \NC zero or more of the preceding specifier, least possible \NC \NR +\NC + \NC one or more of the preceding specifier \NC \NR +\NC ? \NC zero or one of the preceding specifier \NC \NR +\NC ( ) \NC encapsulate capture \NC \NR +\NC \letterpercent b \NC capture all between the following two characters \NC \NR +\HL +\stoptabulate + +You can use whatever you like to be matched: + +\starttabulate[|lT|l|] +\HL +\NC pqr \NC the sequence \type {pqr} \NC \NR +\NC my name is (\letterpercent w) \NC the word following \type {my name is} \NC \NR +\HL +\stoptabulate + +If you want to specify such a token as it is, then you can precede it with a +percent sign, so to get a percent, you need two in a row. + +\ShowLuaExampleThree {string} {match} {"before:after","^(.-):"} +\ShowLuaExampleThree {string} {match} {"before:after","^([^:])"} +\ShowLuaExampleThree {string} {match} {"before:after","bef(.*)ter"} +\ShowLuaExampleThree {string} {match} {"abcdef","[b-e]+"} +\ShowLuaExampleThree {string} {match} {"abcdef","[b-e]*"} +\ShowLuaExampleThree {string} {match} {"abcdef","b-e+"} +\ShowLuaExampleThree {string} {match} {"abcdef","b-e*"} + +\stopsummary + +Such patterns should not be confused with regular expressions, although to some +extent they can do the same. If you really want to do complex matches, you should +look into \LPEG. + +\startsummary[title={[lua] lower upper}] + +These two function spreak for themselves. + +\ShowLuaExampleThree {string} {lower} {"LOW"} +\ShowLuaExampleThree {string} {upper} {"upper"} + +\stopsummary + +\startsummary[title={[lua] format}] + +The \type {format} function takes a template as first argument and one or more +additional arguments depending on the format. The template is similar to the one +used in \CCODE\ but it has some extensions. + +\starttyping +local s = format(format, str, ...) +\stoptyping + +The following table gives an overview of the possible format directives. The +\type {s} is the most probably candidate and can handle numbers well as strings. +Watch how the minus sign influences the alignment. \footnote {There can be +differences between platforms although so far we haven't run into problems. Also, +\LUA\ 5.2 does a bit more checking on correct arguments.} + +\starttabulate[|lB|lT|lT|lT|] +\HL +\NC integer \NC \letterpercent i \NC 12345 \NC \cldcontext{"\letterpercent i", 12345 } \NC \NR +\NC integer \NC \letterpercent d \NC 12345 \NC \cldcontext{"\letterpercent d", 12345 } \NC \NR +\NC unsigned \NC \letterpercent u \NC -12345 \NC \cldcontext{"\letterpercent u", 12345 } \NC \NR +\NC character \NC \letterpercent c \NC 123 \NC \cldcontext{"\letterpercent c", 89 } \NC \NR +\NC hexadecimal \NC \letterpercent x \NC 123 \NC \cldcontext{"\letterpercent x", 123 } \NC \NR +\NC \NC \letterpercent X \NC 123 \NC \cldcontext{"\letterpercent X", 123 } \NC \NR +\NC octal \NC \letterpercent o \NC 12345 \NC \cldcontext{"\letterpercent o", 12345 } \NC \NR +\HL +\NC string \NC \letterpercent s \NC abc \NC \cldcontext{"\letterpercent s", "abcd"} \NC \NR +\NC \NC \letterpercent -8s \NC 123 \NC \cldcontext{"\letterpercent -8s", 123 } \NC \NR +\NC \NC \letterpercent 8s \NC 123 \NC \cldcontext{"\letterpercent 8s", 123 } \NC \NR +\HL +\NC float \NC \letterpercent 0.2f \NC 12.345 \NC \cldcontext{"\letterpercent 0.2f",12.345} \NC \NR +\NC exponential \NC \letterpercent 0.2e \NC 12.345 \NC \cldcontext{"\letterpercent 0.2e",12.345} \NC \NR +\NC \NC \letterpercent 0.2E \NC 12.345 \NC \cldcontext{"\letterpercent 0.2E",12.345} \NC \NR +\NC autofloat \NC \letterpercent 0.2g \NC 12.345 \NC \cldcontext{"\letterpercent 0.2g",12.345} \NC \NR +\NC \NC \letterpercent 0.2G \NC 12.345 \NC \cldcontext{"\letterpercent 0.2G",12.345} \NC \NR +\HL +\stoptabulate + +\startasciimode +\ShowLuaExampleThree {string} {format} {"U+\letterpercent 05X",2010} +\stopasciimode + +\stopsummary + +\startsummary[title={striplines}] + +The \type {striplines} function can strip leading and trailing empty lines, +collapse or delete intermediate empty lines and strips leading and trailing +spaces. We will demonstrate this with string \type {str}: + +\startluacode +local str = table.concat( { +" ", +" aap", +" noot mies", +" ", +" ", +" wim zus jet", +"teun vuur gijs", +" lam kees bok weide", +" ", +"does hok duif schapen ", +" ", +}, "\n") + +document.TempString = str + +function document.ShowStrippedString(str) + str = string.gsub(str," ","\\allowbreak<sp>\\allowbreak ") + str = string.gsub(str,"([\010])","\\allowbreak<lf>\\allowbreak ") + context.startalign { "flushleft,verytolerant" } + context("{\\tttf %s}",str) + context.stopalign() +end + +function document.ShowStrippedBuffer(name,str) + context.tobuffer(name,str) + context.typebuffer( { name }, { numbering = "line" }) + context.resetbuffer { name } +end + +function document.ShowStrippedCommand(option) + context.type( { style = "ttbf" }, [[utilities.strings.striplines(str,"]] .. option .. [[")]]) +end + +context.blank { "big" } +document.ShowStrippedString(str) +document.ShowStrippedBuffer("dummy",str) + +\stopluacode + +The different options for stripping are demonstrated below, We use verbose +descriptions instead of vague boolean flags. + +\startluacode +local str = document.TempString ; document.TempString = nil + +for option in table.sortedhash(utilities.strings.striplinepatterns) do + local s = utilities.strings.striplines(str,option) + context.blank() + document.ShowStrippedCommand(option) + context.blank { "big,samepage" } + document.ShowStrippedString(s) + context.blank { "big,samepage" } + document.ShowStrippedBuffer(option,str) +end +\stopluacode + +You can of course mix usage with the normal \type {context} helper commands, for +instance put them in buffers. Buffers normally will prune leading and trailing +empty lines anyway. + +\starttyping +context.tobuffer("dummy",utilities.strings.striplines(str)) +context.typebuffer( { "dummy" }, { numbering = "line" }) +\stoptyping + +\stopsummary + +\startsummary[title={formatters}] + +The \type {format} function discussed before is the built|-|in. As an alternative +\CONTEXT\ provides an additional formatter that has some extensions. Interesting +is that that one is often more efficient, although there are cases where the +speed is comparable. In addition to the regular \type {format} function we have +the following extra formatting keys: \footnote {As we run out of keys some are +somewhat counter intuitive, like \type {l} for booleans (logical).} + +\start \setuptype[color=] + +\starttabulate[|lB|lT|lT|lT|] +\HL +\NC utf character \NC \letterpercent c \NC 322 \NC \cldcontext{"\letterpercent c",322} \NC \NR +\HL +\NC force tostring \NC \letterpercent S \NC nil \NC \cldcontext{"\letterpercent S",nil} \NC \NR +\NC \NC \letterpercent Q \NC nil \NC \cldcontext{"\letterpercent Q",nil} \NC \NR +\NC \NC \letterpercent N \NC 0123 \NC \cldcontext{"\letterpercent N","0123"} \NC \NR +\HL +\NC signed number \NC \letterpercent I \NC 1234 \NC \cldcontext{"\letterpercent I",1234} \NC \NR +\NC rounded number \NC \letterpercent r \NC 1234.56 \NC \cldcontext{"\letterpercent r",1234.56} \NC \NR +\HL +\NC sparseexp \NC \letterpercent 0.2j \NC 12.345e120 \NC \cldcontext{"\letterpercent 0.2j",12.345e120} \NC \NR +\NC \NC \letterpercent 0.2J \NC 12.345e120 \NC \cldcontext{"\letterpercent 0.2J",12.345e120} \NC \NR +\HL +\NC unicode value 0x \NC \letterpercent h \NC ł 1234 \NC \cldcontext{"\letterpercent v \letterpercent v", "ł",1234} \NC \NR +\NC \NC \letterpercent H \NC ł 1234 \NC \cldcontext{"\letterpercent V \letterpercent V", "ł",1234} \NC \NR +\NC unicode value U+ \NC \letterpercent u \NC ł 1234 \NC \cldcontext{"\letterpercent u \letterpercent u", "ł",1234} \NC \NR +\NC \NC \letterpercent U \NC ł 1234 \NC \cldcontext{"\letterpercent U \letterpercent U", "ł",1234} \NC \NR +\HL +\NC points \NC \letterpercent p \NC 1234567 \NC \cldcontext{"\letterpercent p",1234567} \NC \NR +\NC basepoints \NC \letterpercent b \NC 1234567 \NC \cldcontext{"\letterpercent b",1234567} \NC \NR +\HL +\NC table concat \NC \letterpercent t \NC \arg{1,2,3} \NC \cldcontext{"\letterpercent t",{1,2,3}} \NC \NR +\NC \NC \letterpercent *t \NC \arg{1,2,3} \NC \cldcontext{"\letterpercent *t",{1,2,3}} \NC \NR +\NC \NC \letterpercent \arg{ AND }t \NC \arg{a=1,b=3} \NC \cldcontext{"\letterpercent +{ AND }T",{a=1,b=2}} \NC \NR +\NC table serialize \NC \letterpercent T \NC \arg{1,2,3} \NC \cldcontext{"\letterpercent *t",{1,2,3}} \NC \NR +\NC \NC \letterpercent T \NC \arg{a=1,b=3} \NC \let|\relax\cldcontext{"\letterpercent T",{a=1,b=2}} \NC \NR +\NC \NC \letterpercent +T \NC \arg{a=1,b=3} \NC \cldcontext{"\letterpercent [+T]",{a=1,b=2}} \NC \NR +\HL +\NC boolean (logic) \NC \letterpercent l \NC "a" == "b" \NC \cldcontext{"\letterpercent l","a"=="b"} \NC \NR +\NC \NC \letterpercent L \NC "a" == "b" \NC \cldcontext{"\letterpercent L","a"=="b"} \NC \NR +\HL +\NC whitespace \NC \letterpercent w \NC 3 \NC \obeyspaces\vl\cldcontext{"\letterpercent w",3}\vl \NC \NR +\NC \NC \letterpercent 2w \NC 3 \NC \obeyspaces\vl\cldcontext{"\letterpercent 2w",3}\vl \NC \NR +\NC \NC \letterpercent 4W \NC \NC \obeyspaces\vl\cldcontext{"\letterpercent 4W"}\vl \NC \NR +\HL +\NC skip \NC \letterpercent 2z \NC 1,2,3,4 \NC \obeyspaces\vl\cldcontext{"\letterpercent s\letterpercent 2z\letterpercent s",1,2,3,4}\vl \NC \NR +\HL +\stoptabulate + +\stop + +There is also a generic formatter: \type {a} and \type {A}. This one converts the +argument into a string and deals with strings, number, booleans, tables and +whatever. We mostly use these in tracing. The lowercase variant uses single +quotes, and the uppercase variant uses double quotes. + +There are two more formatters plugged in: \type {!xml!} and \type {!tex!}. These +are best demonstrated with an example: + +\starttyping +local xf = formatter["xml escaped: %!xml!"] +local xr = formatter["tex escaped: %!tex!"] + +print(xf("x > 1 && x < 10")) +print(xt("this will cost me $123.00 at least")) +\stoptyping + +weird, this fails when cld-verbatim is there as part of the big thing: +catcodetable 4 suddenly lacks the comment being a other + +The \type {context} command uses the formatter so one can say: + +\startbuffer +\startluacode +context("first some xml: %!xml!, and now some %!tex!", + "x > 1 && x < 10", "this will cost me $123.00 at least") +\stopluacode +\stopbuffer + +\typebuffer + +This renders as follows: + +\blank \getbuffer \blank + +You can extend the formatter but we advise you not to do that unless you're sure +what you're doing. You never know what \CONTEXT\ itself might add for its own +benefit. + +However, you can define your own formatter and add to that without interference. +In fact, the main formatter is just defined that way. This is how it works: + +\startbuffer[definition] +local MyFormatter = utilities.strings.formatters.new() + +utilities.strings.formatters.add ( + MyFormatter, + "upper", + "global.string.upper(%s)" +) +\stopbuffer + +\typebuffer[definition] + +Now you can use this one as: + +\startbuffer[usage] +context.bold(MyFormatter["It's %s or %!upper!."]("this","that")) +\stopbuffer + +\typebuffer[usage] + +\blank \ctxluabuffer[definition,usage] \blank + +Because we're running inside \CONTEXT, a better definition would be this: + +\startbuffer +local MyFormatter = utilities.strings.formatters.new() + +utilities.strings.formatters.add ( + MyFormatter, + "uc", + "myupper(%s)", + -- "local myupper = global.characters.upper" + { myupper = global.characters.upper } +) + +utilities.strings.formatters.add ( + MyFormatter, + "lc", + "mylower(%s)", + -- "local mylower = global.characters.lower" + { mylower = global.characters.lower } +) + +utilities.strings.formatters.add ( + MyFormatter, + "sh", + "myshaped(%s)", + -- "local myshaped = global.characters.shaped" + { myshaped = global.characters.shaped } +) + +context(MyFormatter["Uppercased: %!uc!"]("ÀÁÂÃÄÅàáâãäå")) +context.par() +context(MyFormatter["Lowercased: %!lc!"]("ÀÁÂÃÄÅàáâãäå")) +context.par() +context(MyFormatter["Reduced: %!sh!"]("ÀÁÂÃÄÅàáâãäå")) +\stopbuffer + +\typebuffer + +The last arguments creates shortcuts. As expected we get: + +\blank \ctxluabuffer \blank + +Of course you can also apply the casing functions directly so in practice you +shouldn't use formatters without need. Among the advantages of using formatters +are: + +\startitemize[packed] +\startitem They provide a level of abstraction. \stopitem +\startitem They can replace multiple calls to \type {\context}. \stopitem +\startitem Sometimes they make source code look better. \stopitem +\startitem Using them is often more efficient and faster. \stopitem +\stopitemize + +The last argument might sound strange but considering the overhead involved in +the \type {context} (related) functions, doing more in one step has benefits. +Also, formatters are implemented quite efficiently, so their overhead can be +neglected. + +In the examples you see that a formatter extension is itself a template. + +\startbuffer +local FakeXML = utilities.strings.formatters.new() + +utilities.strings.formatters.add(FakeXML,"b",[["<" ..%s..">" ]]) +utilities.strings.formatters.add(FakeXML,"e",[["</"..%s..">" ]]) +utilities.strings.formatters.add(FakeXML,"n",[["<" ..%s.."/>"]]) + +context(FakeXML["It looks like %!b!xml%!e! doesn't it?"]("it","it")) +\stopbuffer + +\typebuffer + +This gives: \ctxluabuffer. Of course we could go over the top here: + +\startbuffer +local FakeXML = utilities.strings.formatters.new() + +local stack = { } + +function document.f_b(s) + table.insert(stack,s) + return "<" .. s .. ">" +end + +function document.f_e() + return "</" .. table.remove(stack) .. ">" +end + +utilities.strings.formatters.add(FakeXML,"b",[[global.document.f_b(%s)]]) +utilities.strings.formatters.add(FakeXML,"e",[[global.document.f_e()]]) + +context(FakeXML["It looks like %1!b!xml%0!e! doesn't it?"]("it")) +\stopbuffer + +\typebuffer + +This gives: \ctxluabuffer. Such a template look horrible, although it's not too +far from the regular format syntax: just compare \type {%1f} with \type {%1!e!}. +The zero trick permits us to inject information that we've put on the stack. As +this kind of duplicate usage might occur most, a better solution is available: + +\startbuffer +local FakeXML = utilities.strings.formatters.new() + +utilities.strings.formatters.add(FakeXML,"b",[["<" .. %s .. ">"]]) +utilities.strings.formatters.add(FakeXML,"e",[["</" .. %s .. ">"]]) + +context(FakeXML["It looks like %!b!xml%-1!e! doesn't it?"]("it")) +\stopbuffer + +\typebuffer + +We get: \ctxluabuffer. Anyhow, in most cases you will never feel the need for +such hackery and the regular formatter works fine. Adding this extension +mechanism was rather trivial and it doesn't influence the performance. + +In \CONTEXT\ we have a few more extensions: + +\starttyping +utilities.strings.formatters.add ( + strings.formatters, "unichr", + [["U+" .. format("%%05X",%s) .. " (" .. utfchar(%s) .. ")"]] +) + +utilities.strings.formatters.add ( + strings.formatters, "chruni", + [[utfchar(%s) .. " (U+" .. format("%%05X",%s) .. ")"]] +) +\stoptyping + +This one is used in messages: + +\startbuffer +context("Missing character %!chruni! in font.",234) context.par() +context("Missing character %!unichr! in font.",234) +\stopbuffer + +\typebuffer + +This shows up as: + +\blank \getbuffer \blank + +If you look closely to the definition, you will notice that we use \type {%s} +twice. This is a feature of the definer function: if only one argument is +picked up (which is default) then the replacement format can use that two +times. Because we use a format in the constructor, we need to escape the +percent sign there. + +\stopsummary + +\startsummary[title={strip}] + +This function removes any leading and trailing whitespace characters. + +\starttyping +local s = string.strip(str) +\stoptyping + +\ShowLuaExampleThree {string} {strip} {" lua + tex = luatex "} + +\stopsummary + +\startsummary[title={split splitlines checkedsplit}] + +The line splitter is a special case of the generic splitter. The \type {split} +function can get a string as well an \type {lpeg} pattern. The \type +{checkedsplit} function removes empty substrings. + +\starttyping +local t = string.split (str, pattern) +local t = string.split (str, lpeg) +local t = string.checkedsplit (str, lpeg) +local t = string.splitlines (str) +\stoptyping + +\start \let\ntex\relax % hack + +\ShowLuaExampleTwo {string} {split} {"a, b,c, d", ","} +\ShowLuaExampleTwo {string} {split} {"p.q,r", lpeg.S(",.")} +\ShowLuaExampleTwo {string} {checkedsplit} {";one;;two", ";"} +\ShowLuaExampleTwo {string} {splitlines} {"lua\ntex nic"} + +\stop + +\stopsummary + +\startsummary[title={quoted unquoted}] + +You will hardly need these functions. The \type {quoted} function can normally be +avoided using the \type {format} pattern \type {%q}. The \type {unquoted} +function removes single or double quotes but only when the string starts and ends +with the same quote. + +\starttyping +local q = string.quoted (str) +local u = string.unquoted(str) +\stoptyping + +\ShowLuaExampleThree {string} {quoted} {[[test]]} +\ShowLuaExampleThree {string} {quoted} {[[test"test]]} +\ShowLuaExampleThree {string} {unquoted} {[["test]]} +\ShowLuaExampleThree {string} {unquoted} {[["t\"est"]]} +\ShowLuaExampleThree {string} {unquoted} {[["t\"est"x]]} +\ShowLuaExampleThree {string} {unquoted} {"\'test\'"} + +\stopsummary + +\startsummary[title={count}] + +The function \type {count} returns the number of times that a given pattern +occurs. Beware: if you want to deal with \UTF\ strings, you need the variant that +sits in the \type {lpeg} namespace. + +\starttyping +local n = count(str,pattern) +\stoptyping + +\ShowLuaExampleThree {string} {count} {"test me", "e"} + +\stopsummary + +\startsummary[title={limit}] + +This function can be handy when you need to print messages that can be rather +long. By default, three periods are appended when the string is chopped. + +\starttyping +print(limit(str,max,sentinel) +\stoptyping + +\ShowLuaExampleThree {string} {limit} {"too long", 6} +\ShowLuaExampleThree {string} {limit} {"too long", 6, " (etc)"} + +\stopsummary + +\startsummary[title={is_empty}] + +A string considered empty by this function when its length is zero or when it +only contains spaces. + +\starttyping +if is_empty(str) then ... end +\stoptyping + +\ShowLuaExampleThree {string} {is_empty} {""} +\ShowLuaExampleThree {string} {is_empty} {" "} +\ShowLuaExampleThree {string} {is_empty} {" ? "} + +\stopsummary + +\startsummary[title={escapedpattern topattern}] + +These two functions are rather specialized. They come in handy when you need to +escape a pattern, i.e.\ prefix characters with a special meaning by a \type {%}. + +\starttyping +local e = escapedpattern(str, simple) +local p = topattern (str, lowercase, strict) +\stoptyping + +The simple variant does less escaping (only \type {-.?*} and is for instance used +in wildcard patterns when globbing directories. The \type {topattern} function +always does the simple escape. A strict pattern gets anchored to the beginning +and end. If you want to see what these functions do you can best look at their +implementation. + +\stopsummary + +% strings.tabtospace(str,n) +% strings.striplong + +\stopsection + +\startsection[title=\UTF] + +We used to have the \type {slunicode} library available but as most of it is not +used and because it has a somewhat fuzzy state, we will no longer rely on it. In +fact we only used a few functions in the \type {utf} namespace so as \CONTEXT\ +user you'd better stick to what is presented here. You don't have to worry how +they are implemented. Depending on the version of \LUATEX\ it can be that a +library, a native function, or \LPEG is used. + +\startsummary[title={char byte}] + +As \UTF\ is a multibyte encoding the term char in fact refers to a \LUA\ +string of one upto four 8|-|bit characters. + +\starttyping +local b = utf.byte("å") +local c = utf.char(0xE5) +\stoptyping + +The number of places in \CONTEXT\ where do such conversion is not that large: +it happens mostly in tracing messages. + +\starttyping +logs.report("panic","the character U+%05X is used",utf.byte("æ")) +\stoptyping + +\ShowLuaExampleThree {utf} {byte} {"æ"} +\ShowLuaExampleThree {utf} {char} {0xE6} + +\stopsummary + +\startsummary[title={sub}] + +If you need to take a slice of an \UTF\ encoded string the \type {sub} function +can come in handy. This function takes a string and a range defined by two +numbers. Negative numbers count from the end of the string. + +\ShowLuaExampleThree {utf} {sub} {"123456àáâãäå",1,7} +\ShowLuaExampleThree {utf} {sub} {"123456àáâãäå",0,7} +\ShowLuaExampleThree {utf} {sub} {"123456àáâãäå",0,9} +\ShowLuaExampleThree {utf} {sub} {"123456àáâãäå",4} +\ShowLuaExampleThree {utf} {sub} {"123456àáâãäå",0} +\ShowLuaExampleThree {utf} {sub} {"123456àáâãäå",0,0} +\ShowLuaExampleThree {utf} {sub} {"123456àáâãäå",4,4} +\ShowLuaExampleThree {utf} {sub} {"123456àáâãäå",4,0} +\ShowLuaExampleThree {utf} {sub} {"123456àáâãäå",-3,0} +\ShowLuaExampleThree {utf} {sub} {"123456àáâãäå",0,-3} +\ShowLuaExampleThree {utf} {sub} {"123456àáâãäå",-5,-3} +\ShowLuaExampleThree {utf} {sub} {"123456àáâãäå",-3} + +\stopsummary + +\startsummary[title={len}] + +There are probably not that many people that can instantly see how many bytes the +string in the following example takes: + +\starttyping +local l = utf.len("ÀÁÂÃÄÅàáâãäå") +\stoptyping + +Programming languages use \ASCII\ mostly so there each characters takes one byte. +In \CJK\ scripts however, you end up with much longer sequences. If you ever did +some typesetting of such scripts you have noticed that the number of characters +on a page is less than in the case of a Latin script. As information is coded +in less characters, effectively the source of a Latin or \CJK\ document will not +differ that much. + +\ShowLuaExampleThree {utf} {len} {"ÒÓÔÕÖòóôõö"} + +\stopsummary + +\startsummary[title={values characters}] + +There are two iterators that deal with \UTF. In \LUATEX\ these are extensions to +the \type {string} library but for consistency we've move them to the \type {utf} +namespace. + +The following function loops over the \UTF\ characters in a string and returns +the \UNICODE\ number in \type {u}: + +\starttyping +for u in utf.values(str) do + ... -- u is a number +end +\stoptyping + +The next one returns a string \type {c} that has one or more characters as \UTF\ +characters can have upto 4 bytes. + +\starttyping +for c in utf.characters(str) do + ... -- c is a string +end +\stoptyping + +\stopsummary + +\startsummary[title={ustring xstring tocodes}] + +These functions are mostly useful for logging where we want to see the \UNICODE\ +number. + +\ShowLuaExampleThree {utf} {ustring} {0xE6} +\ShowLuaExampleThree {utf} {ustring} {"ù"} +\ShowLuaExampleThree {utf} {xstring} {0xE6} +\ShowLuaExampleThree {utf} {xstring} {"à"} +\ShowLuaExampleThree {utf} {tocodes} {"ùúü"} +\ShowLuaExampleThree {utf} {tocodes} {"àáä",""} +\ShowLuaExampleThree {utf} {tocodes} {"òóö","+"} + +\stopsummary + +\startsummary[title={split splitlines totable}] + +The \type {split} function splits a sequence of \UTF\ characters into a table +which one character per slot. The \type {splitlines} does the same but each slot +has a line instead. The \type {totable} function is similar to \type {split}, but +the later strips an optionally present \UTF\ bom. + +\ShowLuaExampleThree {utf} {split} {"òóö"} + +\stopsummary + +\startsummary[title={count}] + +This function counts the number of times that a given substring occurs in a +string. The patterns can be a string or an \LPEG\ pattern. + +\ShowLuaExampleThree {utf} {count} {"òóöòóöòóö","ö"} +\ShowLuaExampleThree {utf} {count} {"äáàa",lpeg.P("á") + lpeg.P("à")} + +\stopsummary + +\startsummary[title={remapper replacer substituter}] + +With \type {remapper} you can create a remapping function that remaps a given +string using a (hash) table. + +\starttyping +local remap = utf.remapper { a = 'd', b = "c", c = "b", d = "a" } + +print(remap("abcd 1234 abcd")) +\stoptyping + +A remapper checks each character against the given mapping table. Its cousin +\type {replacer} is more efficient and skips non matches. The \type {substituter} +function only does a quick check first and avoids building a string with no +replacements. That one is much faster when you expect not that many replacements. + +The \type {replacer} and \type {substituter} functions take table as argument +and an indexed as well as hashed one are acceptable. In fact you can even do +things like this: + +\starttyping +local rep = utf.replacer { [lpeg.patterns.digit] = "!" } +\stoptyping + +\stopsummary + +\startsummary[title={is_valid}] + +This function returns false if the argument is no valid \UTF\ string. As \LUATEX\ +is pretty strict with respect to the input, this function is only useful when +dealing with external files. + +\starttyping +function checkfile(filename) + local data = io.loaddata(filename) + if data and data ~= "" and not utf.is_valid(data) then + logs.report("error","file %q contains invalid utf",filename) + end +end +\stoptyping + +\stopsummary + +% not that relevant: +% +% -- utf.filetype +% -- string.toutf + +\stopsection + +\startsection[title=Numbers and bits] + +In the \type {number} namespace we collect some helpers that deal with numbers as +well as bits. Starting with \LUA\ 5.2 a library \type {bit32} is but the language +itself doesn't provide for them via operators: the library uses functions to +manipulate numbers upto 2\high{32}. For advanced bit manipulations you should use +the \type {bit32} library, otherwise it's best to stick to the functions +described here. + +\startsummary[title={hasbit setbit clearbit}] + +As bitsets are numbers you will also use numbers to qualify them. So, if you want to +set bits 1, 4 and 8, you can to that using the following specification: + +\starttyping +local b = 1 + 4 + 8 -- 0x1 + 0x4 + 0x8 +local b = 13 -- or 0xC +\stoptyping + +However, changing one bit by adding a number to an existing doesn't work out that well +if that number already has that bit set. Instead we use: + +\starttyping +local b = number.setbit(b,0x4) +\stoptyping + +In a similar fashion you can turn of a bit: + +\starttyping +local b = number.clearbit(b,0x4) +\stoptyping + +Testing for a bit(set) is done as follows: + +\starttyping +local okay = number.hasbit(b,0x4) +\stoptyping + +\stopsummary + +\startsummary[title={bit}] + +Where the previously mentioned helpers work with numbers representing one or more +bits, it is sometimes handy to work with positions. The \type {bit} function +returns the associated number value. + +\ShowLuaExampleThree {number} {bit} {5} + +\stopsummary + +\startsummary[title={tobitstring}] + +There is no format option to go from number to bits in terms of zeros and ones so +we provide a helper: \type {tobitsting}. + +\ShowLuaExampleThree {number} {tobitstring} {2013} +\ShowLuaExampleThree {number} {tobitstring} {2013,3} +\ShowLuaExampleThree {number} {tobitstring} {2013,1} + +\stopsummary + +\startsummary[title={bits}] + +If you ever want to convert a bitset into a table containing the set bits you can +use this function. + +\ShowLuaExampleTwo {number} {bits} {11} + +\stopsummary + +\startsummary[title={toset}] + +A string or number can be split into digits with \type {toset}. Beware, this +function does not return a function but multiple numbers + +\starttyping +local a, b, c, d = number.toset("1001") +\stoptyping + +The returned values are either numbers or \type {nil} when an valid digit is +seen. + +\ShowLuaExampleSeven {number} {toset} {100101} +\ShowLuaExampleSeven {number} {toset} {"100101"} +\ShowLuaExampleSeven {number} {toset} {"21546"} + +\stopsummary + +\startsummary[title={valid}] + +This function can be used to check or convert a number, for instance in user +interfaces. + +\ShowLuaExampleThree {number} {valid} {12} +\ShowLuaExampleThree {number} {valid} {"34"} +\ShowLuaExampleThree {number} {valid} {"ab",56} + +\stopsummary + +\stopsection + +\startsection[title=\LPEG\ patterns] + +For \LUATEX\ and \CONTEXT\ \MKIV\ the \type {lpeg} library came at the right +moment as we can use it in lots of places. An in|-|depth discussion makes no +sense as it's easier to look into \type {l-lpeg.lua}, so we stick to an overview. +\footnote {If you search the web for \type {lua lpeg} you will end up at the +official documentation and tutorial.} Most functions return an \type {lpeg} +object that can be used in a match. In time critical situations it's more +efficient to use the match on a predefined pattern that to create the pattern new +each time. Patterns are cached so there is no penalty in predefining a pattern. +So, in the following example, the \type {splitter} that splits at the asterisk +will only be created once. + +\starttyping +local splitter_1 = lpeg.splitat("*") +local splitter_2 = lpeg.splitat("*") + +local n, m = lpeg.match(splitter_1,"2*4") +local n, m = lpeg.match(splitter_2,"2*4") +\stoptyping + +\startsummary[title={[lua] match print P R S V C Cc Cs ...}] + +The \type {match} function does the real work. Its first argument is a \type +{lpeg} object that is created using the functions with the short uppercase names. + +\starttyping +local P, R, C, Ct = lpeg.P, lpeg.R, lpeg.C, lpeg.Ct + +local pattern = Ct((P("[") * C(R("az")^0) * P(']') + P(1))^0) + +local words = lpeg.match(pattern,"a [first] and [second] word") +\stoptyping + +In this example the words between square brackets are collected in a table. There +are lots of examples of \type {lpeg} in the \CONTEXT\ code base. + +\stopsummary + +\startsummary[title={anywhere}] + +\starttyping +local p = anywhere(pattern) +\stoptyping + +\ShowLuaExampleTwo {lpeg} {match} {lpeg.Ct((lpeg.anywhere("->")/"!")^0), "oeps->what->more"} + +\stopsummary + +\startsummary[title={splitter splitat firstofsplit secondofsplit}] + +The \type {splitter} function returns a pattern where each match gets an action +applied. The action can be a function, table or string. + +\starttyping +local p = splitter(pattern, action) +\stoptyping + +The \type {splitat} function returns a pattern that will return the split off +parts. Unless the second argument is \type {true} the splitter keeps splitting + +\starttyping +local p = splitat(separator,single) +\stoptyping + +When you need to split off a prefix (for instance in a label) you can use: + +\starttyping +local p = firstofsplit(separator) +local p = secondofsplit(separator) +\stoptyping + +The first function returns the original when there is no match but the second +function returns \type {nil} instead. + +\ShowLuaExampleTwo {lpeg} {match} {lpeg.Ct(lpeg.splitat("->",false)), "oeps->what->more"} +\ShowLuaExampleTwo {lpeg} {match} {lpeg.Ct(lpeg.splitat("->",false)), "oeps"} +\ShowLuaExampleTwo {lpeg} {match} {lpeg.Ct(lpeg.splitat("->",true)), "oeps->what->more"} +\ShowLuaExampleTwo {lpeg} {match} {lpeg.Ct(lpeg.splitat("->",true)), "oeps"} + +\ShowLuaExampleThree {lpeg} {match} {lpeg.firstofsplit(":"), "before:after"} +\ShowLuaExampleThree {lpeg} {match} {lpeg.firstofsplit(":"), "whatever"} +\ShowLuaExampleThree {lpeg} {match} {lpeg.secondofsplit(":"), "before:after"} +\ShowLuaExampleThree {lpeg} {match} {lpeg.secondofsplit(":"), "whatever"} + +\stopsummary + +\startsummary[title={split checkedsplit}] + +The next two functions have counterparts in the \type {string} namespace. They +return a table with the split parts. The second function omits empty parts. + +\starttyping +local t = split (separator,str) +local t = checkedsplit(separator,str) +\stoptyping + +\ShowLuaExampleTwo {lpeg} {split} {",","a,b,c"} +\ShowLuaExampleTwo {lpeg} {split} {",",",a,,b,c,"} +\ShowLuaExampleTwo {lpeg} {checkedsplit} {",",",a,,b,c,"} + +\stopsummary + +\startsummary[title={stripper keeper replacer}] + +These three functions return patterns that manipulate a string. The \type +{replacer} gets a mapping table passed. + +\starttyping +local p = stripper(str or pattern) +local p = keeper (str or pattern) +local p = replacer(mapping) +\stoptyping + +\ShowLuaExampleThree {lpeg} {match} {lpeg.stripper(lpeg.R("az")), "[-a-b-c-d-]"} +\ShowLuaExampleThree {lpeg} {match} {lpeg.stripper("ab"), "[-a-b-c-d-]"} +\ShowLuaExampleThree {lpeg} {match} {lpeg.keeper(lpeg.R("az")), "[-a-b-c-d-]"} +\ShowLuaExampleThree {lpeg} {match} {lpeg.keeper("ab"), "[-a-b-c-d-]"} +\ShowLuaExampleThree {lpeg} {match} {lpeg.replacer{{"a","p"},{"b","q"}}, "[-a-b-c-d-]"} + +\stopsummary + +\startsummary[title={balancer}] + +One of the nice things about \type {lpeg} is that it can handle all kind of +balanced input. So, a function is provided that returns a balancer pattern: + +\starttyping +local p = balancer(left,right) +\stoptyping + +\ShowLuaExampleTwo {lpeg} {match} {lpeg.Ct((lpeg.C(lpeg.balancer("{","}"))+1)^0),"{a} {b{c}}"} +\ShowLuaExampleTwo {lpeg} {match} {lpeg.Ct((lpeg.C(lpeg.balancer("((","]"))+1)^0),"((a] ((b((c]]"} + +\stopsummary + +\startsummary[title={counter}] + +The \type {counter} function returns a function that returns the length of a +given string. The \type {count} function differs from its counterpart living in +the \type {string} namespace in that it deals with \UTF\ and accepts strings as +well as patterns. + +\starttyping +local fnc = counter(lpeg.P("á") + lpeg.P("à")) +local len = fnc("äáàa") +\stoptyping + +\stopsummary + +\startsummary[title={UP US UR}] + +In order to make working with \UTF-8 input somewhat more convenient a few helpers +are provided. + +\starttyping +local p = lpeg.UP(utfstring) +local p = lpeg.US(utfstring) +local p = lpeg.UR(utfpair) +local p = lpeg.UR(first,last) +\stoptyping + +\ShowLuaExampleThree {utf} {count} {"äáàa",lpeg.UP("áà")} +\ShowLuaExampleThree {utf} {count} {"äáàa",lpeg.US("àá")} +\ShowLuaExampleThree {utf} {count} {"äáàa",lpeg.UR("aá")} +\ShowLuaExampleThree {utf} {count} {"äáàa",lpeg.UR("àá")} +\ShowLuaExampleThree {utf} {count} {"äáàa",lpeg.UR(0x0000,0xFFFF)} + +\startsummary[title={patterns}] + +The following patterns are available in the \type {patterns} table in the \type +{lpeg} namespace: + +\startluacode +context.startalignment { "flushleft" } +local done = false +for k, v in table.sortedpairs(lpeg.patterns) do + if done then + context.space() + else + done = true + end + context.type(k) +end +context.stopalignment() +\stopluacode + +There will probably be more of them in the future. + +\stopsummary + +\stopsection + +\startsection[title=IO] + +The \type {io} library is extended with a couple of functions as well and +variables but first we mention a few predefined functions. + +\startsummary[title={[lua] open popen...}] + +The IO library deals with in- and output from the console and +files. + +\starttyping +local f = io.open(filename) +\stoptyping + +When the call succeeds \type {f} is a file object. You close this file +with: + +\starttyping +f:close() +\stoptyping + +Reading from a file is done with \type {f:read(...)} and writing to a file with +\type {f:write(...)}. In order to write to a file, when opening a second argument +has to be given, often \type {wb} for writing (binary) data. Although there are +more efficient ways, you can use the \type {f:lines()} iterator to process a file +line by line. + +You can open a process with \type {io.popen} but dealing with this one depends a +bit on the operating system. + +\stopsummary + +\startsummary[title={fileseparator pathseparator}] + +The value of the following two strings depends on the operating system that is +used. + +\starttyping +io.fileseparator +io.pathseparator +\stoptyping + +\ShowLuaExampleFive {io} {fileseparator} +\ShowLuaExampleFive {io} {pathseparator} + +\stopsummary + +\startsummary[title={loaddata savedata}] + +These two functions save you some programming. The first function loads a whole +file in a string. By default the file is loaded in binary mode, but when the +second argument is \type {true}, some interpretation takes place (for instance +line endings). In practice the second argument can best be left alone. + +\starttyping +io.loaddata(filename,textmode) +\stoptyping + +Saving the data is done with: + +\starttyping +io.savedata(filename,str) +io.savedata(filename,tab,joiner) +\stoptyping + +When a table is given, you can optionally specify a string that +ends up between the elements that make the table. + +\stopsummary + +\startsummary[title={exists size noflines}] + +These three function don't need much comment. + +\starttyping +io.exists(filename) +io.size(filename) +io.noflines(fileobject) +io.noflines(filename) +\stoptyping + +\stopsummary + +\startsummary[title={characters bytes readnumber readstring}] + +When I wrote the icc profile loader, I needed a few helpers for reading strings +of a certain length and numbers of a given width. Both accept five values of +\type {n}: \type {-4}, \type {-2}, \type {1}, \type {2} and \type {4} where the +negative values swap the characters or bytes. + +\starttyping +io.characters(f,n) -- +io.bytes(f,n) +\stoptyping + +The function \type {readnumber} accepts five sizes: \type {1}, \type {2}, \type +{4}, \type {8}, \type {12}. The string function handles any size and strings zero +bytes from the string. + +\starttyping +io.readnumber(f,size) +io.readstring(f,size) +\stoptyping + +Optionally you can give the position where the reading has to start: + +\starttyping +io.readnumber(f,position,size) +io.readstring(f,position,size) +\stoptyping + +\stopsummary + +\startsummary[title={ask}] + +In practice you will probably make your own variant of the following function, +but at least a template is there: + +\starttyping +io.ask(question,default,options) +\stoptyping + +For example: + +\starttyping +local answer = io.ask("choice", "two", { "one", "two" }) +\stoptyping + +\stopsummary + +\stopsection + +\startsection[title=File] + +The file library is one of the larger core libraries that comes with +\CONTEXT. + +\startsummary[title={dirname basename extname nameonly}] + +We start with a few filename manipulators. + +\starttyping +local path = file.dirname(name,default) +local base = file.basename(name) +local suffix = file.extname(name,default) -- or file.suffix +local name = file.nameonly(name) +\stoptyping + +\ShowLuaExampleThree {file} {dirname} {"/data/temp/whatever.cld"} +\ShowLuaExampleThree {file} {dirname} {"c:/data/temp/whatever.cld"} +\ShowLuaExampleThree {file} {basename} {"/data/temp/whatever.cld"} +\ShowLuaExampleThree {file} {extname} {"c:/data/temp/whatever.cld"} +\ShowLuaExampleThree {file} {nameonly} {"/data/temp/whatever.cld"} + +\stopsummary + +\startsummary[title={addsuffix replacesuffix}] + +These functions are used quite often: + +\starttyping +local filename = file.addsuffix(filename, suffix, criterium) +local filename = file.replacesuffix(filename, suffix) +\stoptyping + +The first one adds a suffix unless one is present. When \type {criterium} is +\type {true} no checking is done and the suffix is always appended. The second +function replaces the current suffix or add one when there is none. + +\ShowLuaExampleThree {file} {addsuffix} {"whatever","cld"} +\ShowLuaExampleThree {file} {addsuffix} {"whatever.tex","cld"} +\ShowLuaExampleThree {file} {addsuffix} {"whatever.tex","cld",true} + +\ShowLuaExampleThree {file} {replacesuffix} {"whatever","cld"} +\ShowLuaExampleThree {file} {replacesuffix} {"whatever.tex","cld"} + +\stopsummary + +\startsummary[title={is_writable is_readable}] + +These two test the nature of a file: + +\starttyping +file.is_writable(name) +file.is_readable(name) +\stoptyping + +\stopsummary + +\startsummary[title={splitname join collapsepath}] + +Instead of splitting off individual components you can get them all in one go: + +\starttyping +local drive, path, base, suffix = file.splitname(name) +\stoptyping + +The \type {drive} variable is empty on operating systems other than \MSWINDOWS. +Such components are joined with the function: + +\starttyping +file.join(...) +\stoptyping + +The given snippets are joined using the \type {/} as this is +rather platform independent. Some checking takes place in order +to make sure that nu funny paths result from this. There is +also \type {collapsepath} that does some cleanup on a path +with relative components, like \type {..}. + +\ShowLuaExampleSix {file} {splitname} {"a:/b/c/d.e"} +\ShowLuaExampleThree {file} {join} {"a","b","c.d"} +\ShowLuaExampleThree {file} {collapsepath} {"a/b/../c.d"} +\ShowLuaExampleThree {file} {collapsepath} {"a/b/../c.d",true} + +\stopsummary + +\startsummary[title={splitpath joinpath}] + +By default splitting a execution path specification is done using the operating +system dependant separator, but you can force one as well: + +\starttyping +file.splitpath(str,separator) +\stoptyping + +The reverse operation is done with: + +\starttyping +file.joinpath(tab,separator) +\stoptyping + +Beware: in the following examples the separator is system dependent so +the outcome depends on the platform you run on. + +\ShowLuaExampleTwo {file} {splitpath} {"a:b:c"} +\ShowLuaExampleTwo {file} {splitpath} {"a;b;c"} +\ShowLuaExampleThree {file} {joinpath} {{"a","b","c"}} + +\stopsummary + +\startsummary[title={robustname}] + +In workflows filenames with special characters can be a pain so the following +function replaces characters other than letters, digits, periods, slashes and +hyphens by hyphens. + +\starttyping +file.robustname(str,strict) +\stoptyping + +\ShowLuaExampleThree {file} {robustname} {"We don't like this!"} +\ShowLuaExampleThree {file} {robustname} {"We don't like this!",true} + +\stopsummary + +\startsummary[title={readdata writedata}] + +These two functions are duplicates of functions with the +same name in the \type {io} library. + +\stopsummary + +\startsummary[title={copy}] + +There is not much to comment on this one: + +\starttyping +file.copy(oldname,newname) +\stoptyping + +\stopsummary + +\startsummary[title={is_qualified_path is_rootbased_path}] + +A qualified path has at least one directory component while a rootbased path is +anchored to the root of a filesystem or drive. + +\starttyping +file.is_qualified_path(filename) +file.is_rootbased_path(filename) +\stoptyping + +\ShowLuaExampleThree {file} {is_qualified_path} {"a"} +\ShowLuaExampleThree {file} {is_qualified_path} {"a/b"} +\ShowLuaExampleThree {file} {is_rootbased_path} {"a/b"} +\ShowLuaExampleThree {file} {is_rootbased_path} {"/a/b"} + +\stopsummary + +\stopsection + +\startsection[title=Dir] + +The \type {dir} library uses functions of the \type {lfs} library that is linked +into \LUATEX. + +\startsummary[title={current}] + +This returns the current directory: + +\starttyping +dir.current() +\stoptyping + +\stopsummary + +\startsummary[title={glob globpattern globfiles}] + +% not yet documented: dir.collectpattern(path,patt,recurse,result) -- collects tree + +The \type {glob} function collects files with names that match a given pattern. +The pattern can have wildcards: \type {*} (oen of more characters), \type {?} +(one character) or \type {**} (one or more directories). You can pass the +function a string or a table with strings. Optionally a second argument can be +passed, a table that the results are appended to. + +\starttyping +local files = dir.glob(pattern,target) +local files = dir.glob({pattern,...},target) +\stoptyping + +The target is optional and often you end up with simple calls like: + +\starttyping +local files = dir.glob("*.tex") +\stoptyping + +There is a more extensive version where you start at a path, and applies an +action to each file that matches the pattern. You can either or not force +recursion. + +\starttyping +dir.globpattern(path,patt,recurse,action) +\stoptyping + +The \type {globfiles} function collects matches in a table that is returned at +the end. You can pass an existing table as last argument. The first argument is +the starting path, the second arguments controls analyzing directories and the +third argument has to be a function that gets a name passed and is supposed to +return \type {true} or \type {false}. This function determines what gets +collected. + +\starttyping +dir.globfiles(path,recurse,func,files) +\stoptyping + +\stopsummary + +\startsummary[title={makedirs}] + +With \type {makedirs} you can create the given directory. If more than one +name is given they are concatinated. + +\starttyping +dir.makedirs(name,...) +\stoptyping + +\stopsummary + +\startsummary[title={expandname}] + +This function tries to resolve the given path, including relative paths. + +\starttyping +dir.expandname(str) +\stoptyping + +\ShowLuaExampleThree {dir} {expandname} {"."} + +\stopsummary + +\stopsection + +\startsection[title=URL] + +\startsummary[title={split hashed construct}] + +This is a specialized library. You can split an \type {url} into its components. +An \URL\ is constructed like this: + +\starttyping +foo://example.com:2010/alpha/beta?gamma=delta#epsilon +\stoptyping + +\starttabulate[|T|T|] +\NC scheme \NC foo:// \NC \NR +\NC authority \NC example.com:2010 \NC \NR +\NC path \NC /alpha/beta \NC \NR +\NC query \NC gamma=delta \NC \NR +\NC fragment \NC epsilon \NC \NR +\stoptabulate + +A string is split into a hash table with these keys using the following function: + +\starttyping +url.hashed(str) +\stoptyping + +or in strings with: + +\starttyping +url.split(str) +\stoptyping + +The hash variant is more tolerant than the split. In the hash +there is also a key \type {original} that holds the original \URL\ +and and the boolean \type {noscheme} indicates if there is a +scheme at all. + +The reverse operation is done with: + +\starttyping +url.construct(hash) +\stoptyping + +\startasciimode +\ShowLuaExampleTwo {url} {hashed} {"foo://example.com:2010/alpha/beta?gamma=delta#epsilon"} +\ShowLuaExampleTwo {url} {hashed} {"alpha/beta"} +\ShowLuaExampleTwo {url} {split} {"foo://example.com:2010/alpha/beta?gamma=delta#epsilon"} +\ShowLuaExampleTwo {url} {split} {"alpha/beta"} +\stopasciimode + +\startsummary[title={hasscheme addscheme filename query}] + +There are a couple of helpers and their names speaks for themselves: + +\starttyping +url.hasscheme(str) +url.addscheme(str,scheme) +url.filename(filename) +url.query(str) +\stoptyping + +\ShowLuaExampleThree {url} {hasscheme} {"http://www.pragma-ade.com/cow.png"} +\ShowLuaExampleThree {url} {hasscheme} {"www.pragma-ade.com/cow.png"} +\ShowLuaExampleThree {url} {addscheme} {"www.pragma-ade.com/cow.png","http://"} +\ShowLuaExampleThree {url} {addscheme} {"www.pragma-ade.com/cow.png"} +\ShowLuaExampleThree {url} {filename} {"http://www.pragma-ade.com/cow.png"} +\ShowLuaExampleTwo {url} {query} {"a=b&c=d"} + +\stopsection + +\startsection[title=OS] + +\startsummary[title={[lua luatex] env setenv getenv}] + +In \CONTEXT\ normally you will use the resolver functions to deal with the +environment and files. However, a more low level interface is still available. +You can query and set environment variables with two functions. In addition there +is the \type {env} table as interface to the environment. This threesome replaces +the built in functions. + +\starttyping +os.setenv(key,value) +os.getenv(key) +os.env[key] +\stoptyping + +\stopsummary + +\startsummary[title={[lua] execute}] + +There are several functions for running programs. One comes directly from \LUA, +the otheres come with \LUATEX. All of them are are overloaded in \CONTEXT\ in +order to get more control. + +\starttyping +os.execute(...) +\stoptyping + +\stopsummary + +\startsummary[title={[luatex] spawn exec}] + +Two other runners are: + +\starttyping +os.spawn(...) +os.exec (...) +\stoptyping + +The \type {exec} variant will transfer control from the current process to the +new one and not return to the current job. There is a more detailed explanation +in the \LUATEX\ manual. + +\stopsummary + +\startsummary[title={resultof launch}] + +The following function runs the command and returns the result as string. +Multiple lines are combined. + +\starttyping +os.resultof(command) +\stoptyping + +The next one launches a file assuming that the operating system knows +what application to use. + +\starttyping +os.launch(str) +\stoptyping + +\stopsummary + +\startsummary[title={type name platform libsuffix binsuffix}] + +There are a couple of strings that reflect the current machinery: \type {type} +returns either \type {windows} or \type {unix}. The variable \type {name} is more +detailed: \type {windows}, \type {msdos}, \type {linux}, \type {macosx}, etc. If +you also want the architecture you can consult \type {platform}. + +\starttyping +local t = os.type +local n = os.name +local p = os.platform +\stoptyping + +These three variables as well as the next two are used internally and normally +they are not needed in your applications as most functions that matter are aware +of what platform specific things they have to deal with. + +\starttyping +local s = os.libsuffix +local b = os.binsuffix +\stoptyping + +These are string, not functions. + +\ShowLuaExampleFive {os} {type} +\ShowLuaExampleFive {os} {name} +\ShowLuaExampleFive {os} {platform} +\ShowLuaExampleFive {os} {libsuffix} +\ShowLuaExampleFive {os} {binsuffix} + +\stopsummary + +\startsummary[title={[lua] time}] + +The built in time function returns a number. The accuracy is +implementation dependent and not that large. + +\ShowLuaExampleThree {os} {time} {} + +\stopsummary + +\startsummary[title={[luatex] times gettimeofday}] + +Although \LUA\ has a built in type {os.time} function, we normally will use the +one provided by \LUATEX\ as it is more precise: + +\starttyping +os.gettimeofday() +\stoptyping + +There is also a more extensive variant: + +\starttyping +os.times() +\stoptyping + +This one is platform dependent and returns a table with \type {utime} (use time), +\type {stime} (system time), \type {cutime} (children user time), and \type +{cstime} (children system time). + +\stopsummary + +\ShowLuaExampleThree {os} {gettimeofday} {} +\ShowLuaExampleTwo {os} {times} {} + +\startsummary[title={runtime}] + +More interesting is: + +\starttyping +os.runtime() +\stoptyping + +which returns the time spent in the application so far. + +\ShowLuaExampleThree {os} {runtime} {} + +Sometimes you need to add the timezone to a verbose time and the following +function does that for you. + +\starttyping +os.timezone(delta) +\stoptyping + +\ShowLuaExampleThree {os} {timezone} {} +\ShowLuaExampleThree {os} {timezone} {1} +\ShowLuaExampleThree {os} {timezone} {-1} + +\stopsummary + +\startsummary[title={uuid}] + +A version 4 UUID can be generated with: + +\starttyping +os.uuid() +\stoptyping + +The generator is good enough for our purpose. + +\ShowLuaExampleThree {os} {uuid} {} + +\stopsummary + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/cld/cld-macros.tex b/doc/context/sources/general/manuals/cld/cld-macros.tex new file mode 100644 index 000000000..de677e2c1 --- /dev/null +++ b/doc/context/sources/general/manuals/cld/cld-macros.tex @@ -0,0 +1,168 @@ +% language=uk + +\startcomponent cld-macros + +\environment cld-environment + +\startchapter[title=Macros] + +\startsection[title={Introduction}] + +You can skip this chapter if you're not interested in defining macros or are +quite content with defining them in \TEX. It's just an example of possible future +interface definitions and it's not the fastest mechanism around. + +\stopsection + +\startsection[title={Parameters}] + +Right from the start \CONTEXT\ came with several user interfaces. As a +consequence you need to take this into account when you write code that is +supposed to work with interfaces other than the English one. The \TEX\ command: + +\starttyping +\setupsomething[key=value] +\stoptyping + +and the \LUA\ call: + +\starttyping +context.setupsomething { key = value } +\stoptyping + +are equivalent. However, all keys at the \TEX\ end eventually become English, but +the values are unchanged. This means that when you code in \LUA\ you should use +English keys and when dealing with assigned values later on, you need to +translate them of compare with translations (which is easier). This is why in the +\CONTEXT\ code you will see: + +\starttyping +if somevalue == interfaces.variables.yes then + ... +end +\stoptyping + +instead of: + +\starttyping +if somevalue == "yes" then + ... +end +\stoptyping + +\stopsection + +\startsection[title={User interfacing}] + +Unless this is somehow inhibited, users can write their own macros and this is +done in the \TEX\ language. Passing data to macros is possible and looks like +this: + +\starttyping +\def\test#1#2{.. #1 .. #2 .. } \test{a}{b} +\def\test[#1]#2{.. #1 .. #2 .. } \test[a]{b} +\stoptyping + +Here \type {#1} and \type {#2} represent an argument and there can be at most 9 +of them. The \type{[]} are delimiters and you can delimit in many ways so the +following is also right: + +\starttyping +\def\test(#1><#2){.. #1 .. #2 .. } \test(a><b) +\stoptyping + +Macro packages might provide helper macros that for instance take care of +optional arguments, so that we can use calls like: + +\starttyping +\test[1,2,3][a=1,b=2,c=3]{whatever} +\stoptyping + +and alike. If you are familiar with the \CONTEXT\ syntax you know that we use +this syntax all over the place. + +If you want to write a macro that calls out to \LUA\ and handles things at that +end, you might want to avoid defining the macro itself and this is possible. + +\startbuffer +\startluacode +function test(opt_1, opt_2, arg_1) + context.startnarrower() + context("options 1: %s",interfaces.tolist(opt_1)) + context.par() + context("options 2: %s",interfaces.tolist(opt_2)) + context.par() + context("argument 1: %s",arg_1) + context.stopnarrower() +end + +interfaces.definecommand { + name = "test", + arguments = { + { "option", "list" }, + { "option", "hash" }, + { "content", "string" }, + }, + macro = test, +} +\stopluacode + +test: \test[1][a=3]{whatever} +\stopbuffer + +An example of a definition and usage at the \LUA\ end is: + +\typebuffer + +The call gives: + +\startpacked +\getbuffer +\stoppacked + +\startbuffer +\startluacode +local function startmore(opt_1) + context.startnarrower() + context("start more, options: %s",interfaces.tolist(opt_1)) + context.startnarrower() +end + +local function stopmore(opt_1) + context.stopnarrower() + context("stop more, options: %s",interfaces.tolist(opt_1)) + context.stopnarrower() +end + +interfaces.definecommand ( "more", { + environment = true, + arguments = { + { "option", "list" }, + }, + starter = startmore, + stopper = stopmore, +} ) +\stopluacode + +more: \startmore[1] one \startmore[2] two \stopmore one \stopmore +\stopbuffer + +If you want to to define an environment (i.e.\ a \type {start}||\type {stop} +pair, it looks as follows: + +\typebuffer + +This gives: + +\startpacked +\getbuffer +\stoppacked + +The arguments are know in both \type {startmore} and \type {stopmore} and nesting +is handled automatically. + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/cld/cld-mkiv.tex b/doc/context/sources/general/manuals/cld/cld-mkiv.tex new file mode 100644 index 000000000..5c35fa4e7 --- /dev/null +++ b/doc/context/sources/general/manuals/cld/cld-mkiv.tex @@ -0,0 +1,91 @@ +% language=uk + +% author : Hans Hagen +% copyright : PRAGMA ADE & ConTeXt Development Team +% license : Creative Commons Attribution ShareAlike 4.0 International +% reference : pragma-ade.nl | contextgarden.net | texlive (related) distributions +% origin : the ConTeXt distribution +% +% comment : Because this manual is distributed with TeX distributions it comes with a rather +% liberal license. We try to adapt these documents to upgrades in the (sub)systems +% that they describe. Using parts of the content otherwise can therefore conflict +% with existing functionality and we cannot be held responsible for that. Many of +% the manuals contain characteristic graphics and personal notes or examples that +% make no sense when used out-of-context. +% +% comment : Some chapters might have been published in TugBoat, the NTG Maps, the ConTeXt +% Group journal or otherwise. Thanks to the editors for corrections. Also thanks +% to users for testing, feedback and corrections. + +% \disabledirectives[paragraphs.normalize.global] +% \disabledirectives[paragraphs.normalize.local] + +% \usemodule[s-lan-03] +% \ctxlua{languages.words.tracers.showwords()} % no run check yet +% \page +% \setupspellchecking[state=start,method=2] + +% \enabletrackers[structures.export.spaces] +% \enabletrackers[structures.export.showtree] + +% \enabletrackers[export.trace] +% \enabletrackers[export.trace.spacing] +% \enabletrackers[export.lessstate] +% \enabletrackers[export.comment] + +% \enablemode[export] + +\startmode[export] + + \setupbackend + [export=yes] + + \setupexport + [hyphen=yes, + width=60em] + +\stopmode + +\setupinteraction + [title=Context Lua Documents, + %subtitle=preliminary version, + author=Hans Hagen] + +\startproduct cld-mkiv + +\environment cld-environment + +\component cld-titlepage + +\startfrontmatter + \component cld-contents + \component cld-introduction +\stopfrontmatter + +\startbodymatter + \component cld-abitoflua + \component cld-gettingstarted + \component cld-moreonfunctions + \component cld-afewdetails + \component cld-somemoreexamples + \component cld-graphics + \component cld-macros + \component cld-verbatim + \component cld-logging + \component cld-luafunctions + \component cld-ctxfunctions + \component cld-callbacks + \component cld-backendcode + \component cld-goodies + \component cld-nicetoknow + %\component cld-xml + \component cld-summary + \component cld-specialcommands + \component cld-files +\stopbodymatter + +% \startbackmatter +% \component cld-index +% \stopbackmatter + +\stopproduct diff --git a/doc/context/sources/general/manuals/cld/cld-moreonfunctions.tex b/doc/context/sources/general/manuals/cld/cld-moreonfunctions.tex new file mode 100644 index 000000000..fab22515e --- /dev/null +++ b/doc/context/sources/general/manuals/cld/cld-moreonfunctions.tex @@ -0,0 +1,354 @@ +% language=uk + +\startcomponent cld-moreonfunctions + +\environment cld-environment + +\startchapter[title=More on functions] + +\startsection[title=Why we need them] + +\index{functions} + +In a previous chapter we introduced functions as arguments. At first sight this +feature looks strange but you need to keep in mind that a call to a \type +{context} function has no direct consequences. It generates \TEX\ code that is +executed after the current \LUA\ chunk ends and control is passed back to \TEX. +Take the following code: + +\startbuffer +context.framed( { + frame = "on", + offset = "5mm", + align = "middle" + }, + context.input("knuth") +) +\stopbuffer + +\typebuffer + +We call the function \type {framed} but before the function body is executed, the +arguments get evaluated. This means that \type {input} gets processed before +\type {framed} gets done. As a result there is no second argument to \type +{framed} and no content gets passed: an error is reported. This is why we need +the indirect call: + +\startbuffer +context.framed( { + frame = "on", + align = "middle" + }, + function() context.input("knuth") end +) +\stopbuffer + +\typebuffer + +This way we get what we want: + +\startlinecorrection +\ctxluabuffer +\stoplinecorrection + +The function is delayed till the \type {framed} command is executed. If your +applications use such calls a lot, you can of course encapsulate this ugliness: + +\starttyping +mycommands = mycommands or { } + +function mycommands.framed_input(filename) + context.framed( { + frame = "on", + align = "middle" + }, + function() context.input(filename) end +end + +mycommands.framed_input("knuth") +\stoptyping + +Of course you can nest function calls: + +\starttyping +context.placefigure( + "caption", + function() + context.framed( { + frame = "on", + align = "middle" + }, + function() context.input("knuth") end + ) + end +) +\stoptyping + +Or you can use a more indirect method: + +\starttyping +function text() + context.framed( { + frame = "on", + align = "middle" + }, + function() context.input("knuth") end + ) +end + +context.placefigure( + "none", + function() text() end +) +\stoptyping + +You can develop your own style and libraries just like you do with regular \LUA\ +code. Browsing the already written code can give you some ideas. + +\stopsection + +\startsection[title=How we can avoid them] + +\index{delaying} +\index{nesting} + +As many nested functions can obscure the code rather quickly, there is an +alternative. In the following examples we use \type {test}: + +\startbuffer +\def\test#1{[#1]} +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +context.test("test 1 ",context("test 2a")," test 3") +\stopbuffer + +\typebuffer + +This gives: \ctxluabuffer. As you can see, the second argument is executed before +the encapsulating call to \type {test}. So, we should have packed it into a +function but here is an alternative: + +\startbuffer +context.test("test 1 ",context.delayed("test 2a")," test 3") +\stopbuffer + +\typebuffer + +Now we get: \ctxluabuffer. We can also delay functions themselves, +look at this: + +\startbuffer +context.test("test 1 ",context.delayed.test("test 2b")," test 3") +\stopbuffer + +\typebuffer + +The result is: \ctxluabuffer. This feature also conveniently permits the use of +temporary variables, as in: + +\starttyping +local f = context.delayed.test("test 2c") +context("before ",f," after") +\stoptyping + +Of course you can limit the amount of keystrokes even more by +creating a shortcut: + +\starttyping +local delayed = context.delayed + +context.test("test 1 ",delayed.test("test 2")," test 3") +context.test("test 4 ",delayed.test("test 5")," test 6") +\stoptyping + +So, if you want you can produce rather readable code and readability of code is +one of the reasons why \LUA\ was chosen in the first place. This is a good +example of why coding in \TEX\ makes sense as it looks more intuitive: + +\starttyping +\test{test 1 \test{test 2} test 3} +\test{test 4 \test{test 5} test 6} +\stoptyping + +There is also another mechanism available. In the next example the second +argument is actually a string. + +\starttyping +local nested = context.nested + +context.test("test 8",nested.test("test 9"),"test 10") +\stoptyping + +There is a pitfall here: a nested context command needs to be flushed explicitly, +so in the case of: + +\starttyping +context.nested.test("test 9") +\stoptyping + +a string is created but nothing ends up at the \TEX\ end. Flushing is up to you. +Beware: \type {nested} only works with the regular \CONTEXT\ catcode regime. + +\stopsection + +\startsection[title=Trial typesetting] + +\index {prerolls} +\index {trial typesetting} + +Some typesetting mechanisms demand a preroll. For instance, when determining the +most optimal way to analyse and therefore typeset a table, it is necessary to +typeset the content of cells first. Inside \CONTEXT\ there is a state tagged +\quote {trial typesetting} which signals other mechanisms that for instance +counters should not be incremented more than once. + +Normally you don't need to worry about these issues, but when writing the code +that implements the \LUA\ interface to \CONTEXT, it definitely had to be taken +into account as we either or not can free cached (nested) functions. + +You can influence this caching to some extend. If you say + +\starttyping +function() + context("whatever") +end +\stoptyping + +the function will be removed from the cache when \CONTEXT\ is not in the trial +typesetting state. You can prevent removal of a function by returning \type +{true}, as in: + +\starttyping +function() + context("whatever") + return true +end +\stoptyping + +Whenever you run into a situation that you don't get the outcome that you expect, +you can consider returning \type {true}. However, keep in mind that it will take +more memory, something that only matters on big runs. You can force flushing the +whole cache by: + +\starttyping +context.restart() +\stoptyping + +An example of an occasion where you need to keep the function available is in +repeated content, for instance in headers and footers. + +\starttyping +context.setupheadertexts { + function() + context.pagenumber() + return true + end +} +\stoptyping + +Of course it is not needed when you use the following method: + +\starttyping +context.pagenumber("pagenumber") +\stoptyping + +Because here \CONTEXT\ itself deals with the content driven by the keyword \type +{pagenumber}. + +\stopsection + +\startsection[title=Steppers] + +The \type {context} commands are accumulated within a \type {\ctxlua} call and +only after the call is finished, control is back at the \TEX\ end. Sometimes you +want (in your \LUA\ code) to go on and pretend that you jump out to \TEX\ for a +moment, but come back to where you left. The stepper mechanism permits this. + +A not so practical but nevertheless illustrative example is the following: + +\startbuffer +\startluacode + context.stepwise (function() + context.startitemize() + context.startitem() + context.step("BEFORE 1") + context.stopitem() + context.step("\\setbox0\\hbox{!!!!}") + context.startitem() + context.step("%p",tex.getbox(0).width) + context.stopitem() + context.startitem() + context.step("BEFORE 2") + context.stopitem() + context.step("\\setbox2\\hbox{????}") + context.startitem() + context.step("%p",tex.getbox(2).width) + context.startitem() + context.step("BEFORE 3") + context.stopitem() + context.startitem() + context.step("\\copy0\\copy2") + context.stopitem() + context.startitem() + context.step("BEFORE 4") + context.startitemize() + context.stepwise (function() + context.step("\\bgroup") + context.step("\\setbox0\\hbox{>>>>}") + context.startitem() + context.step("%p",tex.getbox(0).width) + context.stopitem() + context.step("\\setbox2\\hbox{<<<<}") + context.startitem() + context.step("%p",tex.getbox(2).width) + context.stopitem() + context.startitem() + context.step("\\copy0\\copy2") + context.stopitem() + context.startitem() + context.step("\\copy0\\copy2") + context.stopitem() + context.step("\\egroup") + end) + context.stopitemize() + context.stopitem() + context.startitem() + context.step("AFTER 1\\par") + context.stopitem() + context.startitem() + context.step("\\copy0\\copy2\\par") + context.stopitem() + context.startitem() + context.step("\\copy0\\copy2\\par") + context.stopitem() + context.startitem() + context.step("AFTER 2\\par") + context.stopitem() + context.startitem() + context.step("\\copy0\\copy2\\par") + context.stopitem() + context.startitem() + context.step("\\copy0\\copy2\\par") + context.stopitem() + context.stopitemize() +end) +\stopluacode +\stopbuffer + +\typebuffer + +This gives an (ugly) itemize with a nested one: + +\getbuffer + +As you can see in the code, the \type {step} call accepts multiple arguments, but +when more than one argument is given the first one is treated as a formatter. + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/cld/cld-nicetoknow.tex b/doc/context/sources/general/manuals/cld/cld-nicetoknow.tex new file mode 100644 index 000000000..fcc0aa26b --- /dev/null +++ b/doc/context/sources/general/manuals/cld/cld-nicetoknow.tex @@ -0,0 +1,163 @@ +% language=uk + +\startcomponent cld-nicetoknow + +\environment cld-environment + +\startchapter[title=Nice to know] + +\startsection[title=Introduction] + +As we like to abstract interfaces it is no surprise that \CONTEXT\ and +therefore it's \LUA\ libraries come with all kind of helpers. In this +chapter I will explain a few of them. Feel free to remind of adding more +here. + +\stopsection + +\startsection[title=Templates] + +{\em Eventually we will move this to the utilities section.} + +When dealing with data from tables or when order matters it can be handy +to abstract the actual data from the way it is dealt with. For this we +provide a template mechanism. The following example demonstrate its use. + +\startbuffer +require("util-ran") -- needed for this example + +local preamble = [[|l|l|c|]] +local template = [[\NC %initials% \NC %surname% \NC %length% \NC \NR]] + +context.starttabulate { preamble } + for i=1,10 do + local row = utilities.templates.replace(template, { + surname = utilities.randomizers.surname(5,10), + initials = utilities.randomizers.initials(1,3), + length = string.format("%0.2f",math.random(140,195)), + }) + context(row) + end +context.stoptabulate() +\stopbuffer + +\typebuffer + +This renders a table with random entries: + +\ctxluabuffer + +The nice thing is that when we change the order of the columns, we don't need to +change the table builder. + +\starttyping +local preamble = [[|c|l|l|]] +local template = [[\NC %length% \NC %initials% \NC %surname% \NC \NR]] +\stoptyping + +The \type {replace} function takes a few more arguments. There are also a some +more replacement options. + +\starttyping +replace("test '%[x]%' test",{ x = [[a 'x' a]] })) +replace("test '%[x]%' test",{ x = true })) +replace("test '%[x]%' test",{ x = [[a 'x' a]], y = "oeps" },'sql')) +replace("test '%[x]%' test",{ x = [[a '%y%' a]], y = "oeps" },'sql',true)) +replace([[test %[x]% test]],{ x = [[a "x" a]]})) +replace([[test %(x)% test]],{ x = [[a "x" a]]})) +\stoptyping + +The first argument is the template and the second one a table with mappings from +keys to values. The third argument can be used to inform the replace mechanism +what string escaping has to happen. The last argument triggers recursive +replacement. The above calls result in the following strings: + +\starttyping +test 'a 'x' \127 a' test +test 'true' test +test 'a ''x'' a' test +test 'a ''oeps'' a' test +test a \"x\" \127 a test +test "a \"x\" \127 a" test +\stoptyping + +These examples demonstrate that by adding a pair of square brackets we get +escaped strings. When using parenthesis the quotes get added automatically. This +is somewhat faster in case when \LUA\ is the target, but in practice it is not +that noticeable. + +% replace(str,mapping,how,recurse) + +\stopsection + +\startsection [title=Extending] + +Instead of extending tex endlessly we can also define our own extensions. Here +is an example. When you want to manipulate a box at the \LUA\ end you have the +problem that the following will not always work out well: + +\starttyping +local b = tex.getbox(0) +-- mess around with b +tex.setbox(0,b) +\stoptyping + +So we end up with: + +\starttyping +local b = node.copy_list(tex.getbox(0)) +-- mess around with b +tex.setbox(0,b) +\stoptyping + +The reason is that at the \TEX\ end grouping plays a role which means that values +are saved and restored. However, there is a save way out by defining a function +that cheats a bit: + +\starttyping +function tex.takebox(id) + local box = tex.getbox(id) + if box then + local copy = node.copy(box) + local list = box.list + copy.list = list + box.list = nil + tex.setbox(id,nil) + return copy + end +end +\stoptyping + +Now we can say: + +\starttyping +local b = tex.takebox(0) +-- mess around with b +tex.setbox(b) +\stoptyping + +In this case we first get the box content and then let \TEX\ do some housekeeping. +But, because we only keep the list node (which we copied) in the register the +overhead of copying a whole list is gone. + +\stopsection + +% require("util-sto") require("char-def") require("char-ini") + +% local myformatter = utilities.strings.formatters.new() + +% string.addformatter("upper", [[upper (%s)]],[[local upper = characters.upper ]]) -- maybe handy +% string.addformatter("lower", [[lower (%s)]],[[local lower = characters.lower ]]) -- maybe handy +% string.addformatter("shaped", [[shaped(%s)]],[[local shaped = characters.shaped]]) -- maybe handy + +% utilities.strings.formatters.add("upper", [[lpegmatch(p_toupper,%s)]],[[local p_toupper = lpeg.patterns.toupper]]) -- maybe handy +% utilities.strings.formatters.add("lower", [[lpegmatch(p_tolower,%s)]],[[local p_tolower = lpeg.patterns.tolower]]) -- maybe handy +% utilities.strings.formatters.add("shaped", [[lpegmatch(p_toshape,%s)]],[[local p_toshape = lpeg.patterns.toshape]]) -- maybe handy + +% print("\n>>>",string.formatters["Is this %s handy or not?"](characters.upper("ÀÁÂÃÄÅàáâãäå"))) +% print("\n>>>",string.formatters["Is this %!upper! handy or not?"]("ÀÁÂÃÄÅàáâãäå")) +% print("\n>>>",string.formatters["Is this %!shaped! handy or not?"]("ÀÁÂÃÄÅàáâãäå")) + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/cld/cld-somemoreexamples.tex b/doc/context/sources/general/manuals/cld/cld-somemoreexamples.tex new file mode 100644 index 000000000..a282be4e9 --- /dev/null +++ b/doc/context/sources/general/manuals/cld/cld-somemoreexamples.tex @@ -0,0 +1,753 @@ +% language=uk + +\startcomponent cld-somemoreexamples + +\environment cld-environment + +\usemodule[morse] + +\startchapter[title=Some more examples] + +\startsection[title=Appetizer] + +Before we give some more examples, we will have a look at the way the title page +is made. This way you get an idea what more is coming. + +\typefile {cld-mkiv-simple-titlepage.cld} + +This does not look that bad, does it? Of course in pure \TEX\ code it looks +mostly the same but loops and calculations feel a bit more natural in \LUA\ then +in \TEX. The result is shown in \in {figure} [fig:cover]. The actual cover page +was derived from this. + +\startplacefigure[location=here,reference=fig:cover,title={The simplified cover page.}] + \doiffileexistselse {cld-mkiv-simple-titlepage.pdf} { + \externalfigure + [cld-mkiv-simple-titlepage.pdf] + [height=.5\textheight] + } { + \scale + [height=.5\textheight] + {\cldprocessfile{cld-mkiv-simple-titlepage.cld}} + } +\stopplacefigure + +\stopsection + +\startsection[title=A few examples] + +As it makes most sense to use the \LUA\ interface for generated text, here is +another example with a loop: + +\startbuffer +context.startitemize { "a", "packed", "two" } + for i=1,10 do + context.startitem() + context("this is item %i",i) + context.stopitem() + end +context.stopitemize() +\stopbuffer + +\typebuffer + +\ctxluabuffer + +Just as you can mix \TEX\ with \XML\ and \METAPOST, you can define bits and +pieces of a document in \LUA. Tables are good candidates: + +\startbuffer +local one = { + align = "middle", + style = "type", +} +local two = { + align = "middle", + style = "type", + background = "color", + backgroundcolor = "darkblue", + foregroundcolor = "white", +} +local random = math.random +context.bTABLE { framecolor = "darkblue" } + for i=1,10 do + context.bTR() + for i=1,20 do + local r = random(99) + context.bTD(r < 50 and one or two) + context("%2i",r) + context.eTD() + end + context.eTR() + end +context.eTABLE() +\stopbuffer + +\typebuffer + +\placetable[top][tab:random]{A table generated by \LUA.}{\ctxluabuffer} + +Here we see a function call to \type {context} in the most indented line. The +first argument is a format that makes sure that we get two digits and the random +number is substituted into this format. The result is shown in +\in{table}[tab:random]. The line correction is ignored when we use this table as +a float, otherwise it assures proper vertical spacing around the table. Watch how +we define the tables \type {one} and \type {two} beforehand. This saves 198 +redundant table constructions. + +Not all code will look as simple as this. Consider the following: + +\starttyping +context.placefigure( + "caption", + function() context.externalfigure( { "cow.pdf" } ) end +) +\stoptyping + +Here we pass an argument wrapped in a function. If we would not do that, the +external figure would end up wrong, as arguments to functions are evaluated +before the function that gets them (we already showed some alternative approaches +in previous chapters). A function argument is treated as special and in this case +the external figure ends up right. Here is another example: + +\startbuffer +context.placefigure("Two cows!",function() + context.bTABLE() + context.bTR() + context.bTD() + context.externalfigure( + { "cow.pdf" }, + { width = "3cm", height = "3cm" } + ) + context.eTD() + context.bTD { align = "{lohi,middle}" } + context("and") + context.eTD() + context.bTD() + context.externalfigure( + { "cow.pdf" }, + { width = "4cm", height = "3cm" } + ) + context.eTD() + context.eTR() + context.eTABLE() +end) +\stopbuffer + +\typebuffer + +In this case the figure is not an argument so it gets flushed sequentially +with the rest. + +\ctxluabuffer + +\stopsection + +\startsection[title=Styles] + +Say that you want to typeset a word in a bold font. You can do +that this way: + +\starttyping +context("This is ") +context.bold("important") +context("!") +\stoptyping + +Now imagine that you want this important word to be in red too. As we have +a nested command, we end up with a nested call: + +\starttyping +context("This is ") +context.bold(function() context.color( { "red" }, "important") end) +context("!") +\stoptyping + +or + +\starttyping +context("This is ") +context.bold(context.delayed.color( { "red" }, "important")) +context("!") +\stoptyping + +In that case it's good to know that there is a command that combines both +features: + +\starttyping +context("This is ") +context.style( { style = "bold", color = "red" }, "important") +context("!") +\stoptyping + +But that is still not convenient when we have to do that often. So, you can wrap +the style switch in a function. + +\starttyping +local function mycommands.important(str) + context.style( { style = "bold", color = "red" }, str ) +end + +context("This is ") +mycommands.important( "important") +context(", and ") +mycommands.important( "this") +context(" too !") +\stoptyping + +Or you can setup a named style: + +\starttyping +context.setupstyle( { "important" }, { style = "bold", color = "red" } ) + +context("This is ") +context.style( { "important" }, "important") +context(", and ") +context.style( { "important" }, "this") +context(" too !") +\stoptyping + +Or even define one: + +\starttyping +context.definestyle( { "important" }, { style = "bold", color = "red" } ) + +context("This is ") +context.important("important") +context(", and ") +context.important("this") +context(" too !") +\stoptyping + +This last solution is especially handy for more complex cases: + +\startbuffer +context.definestyle( { "important" }, { style = "bold", color = "red" } ) + +context("This is ") +context.startimportant() +context.inframed("important") +context.stopimportant() +context(", and ") +context.important("this") +context(" too !") +\stopbuffer + +\typebuffer + +\ctxluabuffer + +\stopsection + +\startsection[title=A complete example] + +One day my 6 year old niece Lorien was at the office and wanted to know what I +was doing. As I knew she was practicing arithmetic at school I wrote a quick and +dirty script to generate sheets with exercises. The most impressive part was that +the answers were included. It was a rather braindead bit of \LUA, written in a +few minutes, but the weeks after I ended up running it a few more times, for her +and her friends, every time a bit more difficult and also using different +arithmetic. It was that script that made me decide to extend the basic cld manual +into this more extensive document. + +We generate three columns of exercises. Each exercise is a row in a table. The +last argument to the function determines if answers are shown. + +\starttyping +local random = math.random + +local function ForLorien(n,maxa,maxb,answers) + context.startcolumns { n = 3 } + context.starttabulate { "|r|c|r|c|r|" } + for i=1,n do + local sign = random(0,1) > 0.5 + local a, b = random(1,maxa or 99), random(1,max or maxb or 99) + if b > a and not sign then a, b = b, a end + context.NC() + context(a) + context.NC() + context.mathematics(sign and "+" or "-") + context.NC() + context(b) + context.NC() + context("=") + context.NC() + context(answers and (sign and a+b or a-b)) + context.NC() + context.NR() + end + context.stoptabulate() + context.stopcolumns() + context.page() +end +\stoptyping + +This is a typical example of where it's more convenient to write the code in +\LUA\ that in \TEX's macro language. As a consequence setting up the page also +happens in \LUA: + +\starttyping +context.setupbodyfont { + "palatino", + "14pt" +} + +context.setuplayout { + backspace = "2cm", + topspace = "2cm", + header = "1cm", + footer = "0cm", + height = "middle", + width = "middle", +} +\stoptyping + +This leave us to generate the document. There is a pitfall here: we need to use +the same random number for the exercises and the answers, so we freeze and +defrost it. Functions in the \type {commands} namespace implement functionality +that is used at the \TEX\ end but better can be done in \LUA\ than in \TEX\ macro +code. Of course these functions can also be used at the \LUA\ end. + +\starttyping +context.starttext() + + local n = 120 + + commands.freezerandomseed() + + ForLorien(n,10,10) + ForLorien(n,20,20) + ForLorien(n,30,30) + ForLorien(n,40,40) + ForLorien(n,50,50) + + commands.defrostrandomseed() + + ForLorien(n,10,10,true) + ForLorien(n,20,20,true) + ForLorien(n,30,30,true) + ForLorien(n,40,40,true) + ForLorien(n,50,50,true) + +context.stoptext() +\stoptyping + +\placefigure + [here] + [fig:lorien] + {Lorien's challenge.} + {\startcombination + {\externalfigure[cld-005.pdf][page=1,width=.45\textwidth,frame=on]} {exercises} + {\externalfigure[cld-005.pdf][page=6,width=.45\textwidth,frame=on]} {answers} + \stopcombination} + +A few pages of the result are shown in \in {figure} [fig:lorien]. In the +\CONTEXT\ distribution a more advanced version can be found in \type +{s-edu-01.cld} as I was also asked to generate multiplication and table +exercises. In the process I had to make sure that there were no duplicates on a +page as she complained that was not good. There a set of sheets is generated +with: + +\starttyping +moduledata.educational.arithematic.generate { + name = "Bram Otten", + fontsize = "12pt", + columns = 2, + run = { + { method = "bin_add_and_subtract", maxa = 8, maxb = 8 }, + { method = "bin_add_and_subtract", maxa = 16, maxb = 16 }, + { method = "bin_add_and_subtract", maxa = 32, maxb = 32 }, + { method = "bin_add_and_subtract", maxa = 64, maxb = 64 }, + { method = "bin_add_and_subtract", maxa = 128, maxb = 128 }, + }, +} +\stoptyping + +\stopsection + +\startsection[title=Interfacing] + +The fact that we can define functionality using \LUA\ code does not mean that we +should abandon the \TEX\ interface. As an example of this we use a relatively +simple module for typesetting morse code.\footnote {The real module is a bit +larger and can format verbose morse.} First we create a proper namespace: + +\starttyping + +moduledata.morse = moduledata.morse or { } +local morse = moduledata.morse +\stoptyping + +We will use a few helpers and create shortcuts for them. The first helper loops +over each \UTF\ character in a string. The other two helpers map a character onto +an uppercase (because morse only deals with uppercase) or onto an similar shaped +character (because morse only has a limited character set). + +\starttyping +local utfcharacters = string.utfcharacters +local ucchars, shchars = characters.ucchars, characters.shchars +\stoptyping + +The morse codes are stored in a table. + +\starttyping +local codes = { + + ["A"] = "·—", ["B"] = "—···", + ["C"] = "—·—·", ["D"] = "—··", + ["E"] = "·", ["F"] = "··—·", + ["G"] = "——·", ["H"] = "····", + ["I"] = "··", ["J"] = "·———", + ["K"] = "—·—", ["L"] = "·—··", + ["M"] = "——", ["N"] = "—·", + ["O"] = "———", ["P"] = "·——·", + ["Q"] = "——·—", ["R"] = "·—·", + ["S"] = "···", ["T"] = "—", + ["U"] = "··—", ["V"] = "···—", + ["W"] = "·——", ["X"] = "—··—", + ["Y"] = "—·——", ["Z"] = "——··", + + ["0"] = "—————", ["1"] = "·————", + ["2"] = "··———", ["3"] = "···——", + ["4"] = "····—", ["5"] = "·····", + ["6"] = "—····", ["7"] = "——···", + ["8"] = "———··", ["9"] = "————·", + + ["."] = "·—·—·—", [","] = "——··——", + [":"] = "———···", [";"] = "—·—·—", + ["?"] = "··——··", ["!"] = "—·—·——", + ["-"] = "—····—", ["/"] = "—··—· ", + ["("] = "—·——·", [")"] = "—·——·—", + ["="] = "—···—", ["@"] = "·——·—·", + ["'"] = "·————·", ['"'] = "·—··—·", + + ["À"] = "·——·—", + ["Å"] = "·——·—", + ["Ä"] = "·—·—", + ["Æ"] = "·—·—", + ["Ç"] = "—·—··", + ["É"] = "··—··", + ["È"] = "·—··—", + ["Ñ"] = "——·——", + ["Ö"] = "———·", + ["Ø"] = "———·", + ["Ü"] = "··——", + ["ß"] = "··· ···", + +} + +morse.codes = codes +\stoptyping + +As you can see, there are a few non \ASCII\ characters supported as well. There +will never be full \UNICODE\ support simply because morse is sort of obsolete. +Also, in order to support \UNICODE\ one could as well use the bits of \UTF\ +characters, although \unknown\ memorizing the whole \UNICODE\ table is not much +fun. + +We associate a metatable index function with this mapping. That way we can not +only conveniently deal with the casing, but also provide a fallback based on the +shape. Once found, we store the representation so that only one lookup is needed +per character. + +\starttyping +local function resolvemorse(t,k) + if k then + local u = ucchars[k] + local v = rawget(t,u) or rawget(t,shchars[u]) or false + t[k] = v + return v + else + return false + end +end + +setmetatable(codes, { __index = resolvemorse }) +\stoptyping + +Next comes some rendering code. As we can best do rendering at the \TEX\ end we +just use macros. + +\starttyping +local MorseBetweenWords = context.MorseBetweenWords +local MorseBetweenCharacters = context.MorseBetweenCharacters +local MorseLong = context.MorseLong +local MorseShort = context.MorseShort +local MorseSpace = context.MorseSpace +local MorseUnknown = context.MorseUnknown +\stoptyping + +The main function is not that complex. We need to keep track of spaces and +newlines. We have a nested loop because a fallback to shape can result in +multiple characters. + +\starttyping +function morse.tomorse(str) + local inmorse = false + for s in utfcharacters(str) do + local m = codes[s] + if m then + if inmorse then + MorseBetweenWords() + else + inmorse = true + end + local done = false + for m in utfcharacters(m) do + if done then + MorseBetweenCharacters() + else + done = true + end + if m == "·" then + MorseShort() + elseif m == "—" then + MorseLong() + elseif m == " " then + MorseBetweenCharacters() + end + end + inmorse = true + elseif s == "\n" or s == " " then + MorseSpace() + inmorse = false + else + if inmorse then + MorseBetweenWords() + else + inmorse = true + end + MorseUnknown(s) + end + end +end +\stoptyping + +We use this function in two additional functions. One typesets a file, the other +a table of available codes. + +\starttyping +function morse.filetomorse(name,verbose) + morse.tomorse(resolvers.loadtexfile(name),verbose) +end + +function morse.showtable() + context.starttabulate { "|l|l|" } + for k, v in table.sortedpairs(codes) do + context.NC() context(k) + context.NC() morse.tomorse(v,true) + context.NC() context.NR() + end + context.stoptabulate() +end +\stoptyping + +We're done with the \LUA\ code that we can either put in an external file or put +in the module file. The \TEX\ file has two parts. The typesetting macros that we +use at the \LUA\ end are defined first. These can be overloaded. + +\starttyping +\def\MorseShort + {\dontleavehmode + \vrule + width \MorseWidth + height \MorseHeight + depth \zeropoint + \relax} + +\def\MorseLong + {\dontleavehmode + \vrule + width 3\dimexpr\MorseWidth + height \MorseHeight + depth \zeropoint + \relax} + +\def\MorseBetweenCharacters + {\kern\MorseWidth} + +\def\MorseBetweenWords + {\hskip3\dimexpr\MorseWidth\relax} + +\def\MorseSpace + {\hskip7\dimexpr\MorseWidth\relax} + +\def\MorseUnknown#1 + {[\detokenize{#1}]} +\stoptyping + +The dimensions are stored in macros as well. Of course we could provide a proper +setup command, but it hardly makes sense. + +\starttyping +\def\MorseWidth {0.4em} +\def\MorseHeight{0.2em} +\stoptyping + +Finally we have arrived at the macros that interface to the \LUA\ functions. + +\starttyping +\def\MorseString#1{\ctxlua{moduledata.morse.tomorse(\!!bs#1\!!es)}} +\def\MorseFile #1{\ctxlua{moduledata.morse.filetomorse("#1")}} +\def\MorseTable {\ctxlua{moduledata.morse.showtable()}} +\stoptyping + +\startbuffer +\Morse{A more advanced solution would be to convert a node list. That +way we can deal with weird input.} +\stopbuffer + +A string is converted to morse with the first command. + +\typebuffer + +This shows up as: + +\startalignment[flushleft,tolerant]\getbuffer\stopalignment + +Reduction and uppercasing is demonstrated in the next example: + +\startbuffer +\MorseString{ÀÁÂÃÄÅàáâãäå} +\stopbuffer + +\typebuffer + +This gives: + +\startalignment[flushleft,tolerant]\getbuffer\stopalignment + +\stopsection + +\startsection[title=Using helpers] + +The next example shows a bit of \LPEG. On top of the standard functionality +a few additional functions are provided. Let's start with a pure \TEX\ +example: + +\startbuffer +\defineframed + [colored] + [foregroundcolor=red, + foregroundstyle=\underbar, + offset=.1ex, + location=low] +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\processisolatedwords {\input ward \relax} \colored +\stopbuffer + +\typebuffer \blank \getbuffer \blank + +Because this processor macro operates at the \TEX\ end it has some limitations. +The content is collected in a very narrow box and from that a regular paragraph +is constructed. It is for this reason that no color is applied: the snippets that +end up in the box are already typeset. + +An alternative is to delegate the task to \LUA: + +\startbuffer +\startluacode +local function process(data) + + local words = lpeg.split(lpeg.patterns.spacer,data or "") + + for i=1,#words do + if i == 1 then + context.dontleavehmode() + else + context.space() + end + context.colored(words[i]) + end + +end + +process(io.loaddata(resolvers.findfile("ward.tex"))) +\stopluacode +\stopbuffer + +\typebuffer \blank \getbuffer \blank + +The function splits the loaded data into a table with individual words. We use a +splitter that splits on spacing tokens. The special case for \type {i = 1} makes +sure that we end up in horizontal mode (read: properly start a paragraph). This +time we do get color because the typesetting is done directly. Here is an +alternative implementation: + +\starttyping +local done = false + +local function reset() + done = false + return true +end + +local function apply(s) + if done then + context.space() + else + done = true + context.dontleavehmode() + end + context.colored(s) +end + +local splitter = lpeg.P(reset) + * lpeg.splitter(lpeg.patterns.spacer,apply) + +local function process(data) + lpeg.match(splitter,data) +end +\stoptyping + +This version is more efficient as it does not create an intermediate table. The +next one is comaprable: + +\starttyping +local function apply(s) + context.colored("%s ",s) +end + +local splitter lpeg.splitter(lpeg.patterns.spacer,apply) + +local function process(data) + context.dontleavevmode() + lpeg.match(splitter,data) + context.removeunwantedspaces() +end +\stoptyping + +\stopsection + +\startsection[title=Formatters] + +Sometimes can save a bit of work by using formatters. By default, the \type {context} +command, when called directly, applies a given formatter. But when called as table +this feature is lost because then we want to process non|-|strings as well. The next +example shows a way out: + +\startbuffer +context("the current emwidth is %p",\number\emwidth) +context.par() +context.formatted("the current emwidth is %p",\number\emwidth) +context.par() +context.bold(string.formatters["the current emwidth is %p"](\number\emwidth)) +context.par() +context.formatted.bold("the current emwidth is %p",\number\emwidth) +\stopbuffer + +The last one is the most interesting one here: in the subnamespace \type +{formatted} (watch the \type {d}) a format specification with extra arguments is +expected. + +\ctxluabuffer + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/cld/cld-specialcommands.tex b/doc/context/sources/general/manuals/cld/cld-specialcommands.tex new file mode 100644 index 000000000..37e891019 --- /dev/null +++ b/doc/context/sources/general/manuals/cld/cld-specialcommands.tex @@ -0,0 +1,46 @@ +% language=uk + +\startcomponent cld-specialcommands + +\environment cld-environment + +\startchapter[title=Special commands] + +\index{tracing} + +There are a few functions in the \type {context} namespace that are no +macros at the \TEX\ end. + +\starttyping +context.runfile("somefile.cld") +\stoptyping + +Another useful command is: + +\starttyping +context.settracing(true) +\stoptyping + +There are a few tracing options that you can set at the \TEX\ end: + +\starttyping +\enabletrackers[context.files] +\enabletrackers[context.trace] +\stoptyping + +A few macros have special functions at the \LUA\ end. One of them is \type +{\char}. The function makes sure that the characters ends up right. The same is +true for \type {\chardef}. So, you don't need to mess around with \type {\relax} +or trailing spaces as you would do at the \TEX\ end in order to tell the scanner +to stop looking ahead. + +\starttyping +context.char(123) +\stoptyping + +Other examples of macros that have optimized functions are \type {\par}, +\type{\bgroup} and \type {\egroup}. + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/cld/cld-summary.tex b/doc/context/sources/general/manuals/cld/cld-summary.tex new file mode 100644 index 000000000..2b62597fa --- /dev/null +++ b/doc/context/sources/general/manuals/cld/cld-summary.tex @@ -0,0 +1,841 @@ +% language=uk + +\startcomponent cld-summary + +\environment cld-environment + +\usemodule[s][characters-properties] + +\startchapter[title=A sort of summary] + +In this chapter we summarize the functionality provided by the \type {context} +namespace. We repeat some of what has been explained in other chapter so that in +fact you can start with this summary. + +If you have read this manual (or seen code) you know that you can access all the +core commands using this namespace: + +\starttyping +context.somecommand("some argument") +context["somecommand"]("some argument") +\stoptyping + +These calls will eventually expand \type {\somecommand} with the given argument. +This interface has been around form the start and has proven to be quite flexible +and robust. In spite of what you might think, the \type {somecommand} is not +really defined in the \type {context} namespace, but in its own one called \type +{core}, accessible via \type {context.core}. + +Next we describe the commands that are naturally defined in the \type {context} +namespace. Some have counterparts at the macro level (like \type {bgroup}) but +many haven't (for instance \type {rule}). We tried not to polute the \type +{context} namespace too much but although we could have put the helpers in a +separate namespace it would make usage a bit more unnatural. + +\startsection[title=Access to commands] + +\startsummary[title={context(".. some text ..")}] + +The string is flushed as|-|is: + +\starttyping +.. some text .. +\stoptyping + +\stopsummary + +\startsummary[title={context("format",...)}] + +The first string is a format specification according that is passed to the \LUA\ +function \type {format} in the \type {string} namespace. Following arguments are +passed too. + +\stopsummary + +\startsummary[title={context(123,...)}] + +The numbers (and following numbers or strings) are flushed without any +formatting. + +\starttyping +123... (concatenated) +\stoptyping + +\stopsummary + +\startsummary[title={context(true)}] + +An explicit \type {endlinechar} is inserted, in \TEX\ speak: + +\starttyping +^^M +\stoptyping + +\stopsummary + +\startsummary[title={context(false,...)}] + +Strings and numbers are flushed surrounded by curly braces, an indexed table is +flushed as option list, and a hashed table is flushed as parameter set. + +\starttyping +multiple {...} or [...] etc +\stoptyping + +\stopsummary + +\startsummary[title={context(node)}] + +The node (or list of nodes) is injected at the spot. Keep in mind that you need +to do the proper memory management yourself. + +\stopsummary + +\startsummary[title={context["command"] context.core["command"]}] + +The function that implements \type {\command}. The \type{core} table is where +these functions realy live. + +\stopsummary + +\startsummary[title={context["command"](value,...)}] + +The value (string or number) is flushed as a curly braced (regular) argument. + +\starttyping +\command {value}... +\stoptyping + +\stopsummary + +\startsummary[title={context["command"]({ value },...)}] + +The table is flushed as value set. This can be an identifier, +a list of options, or a directive. + +\starttyping +\command [value]... +\stoptyping + +\stopsummary + +\startsummary[title={context["command"]({ key = val },...)}] + +The table is flushed as key|/|value set. + +\starttyping +\command [key={value}]... +\stoptyping + +\stopsummary + +\startsummary[title={context["command"](true)}] + +An explicit \type {endlinechar} is inserted. + +\starttyping +\command ^^M +\stoptyping + +\stopsummary + +\startsummary[title={context["command"](node)}] + +The node(list) is injected at the spot. Keep in mind that you need to do the +proper memory management yourself. + +\starttyping +\command {node(list)} +\stoptyping + +\stopsummary + +\startsummary[title={context["command"](false,value)}] + +The value is flushed without encapsulating tokens. + +\starttyping +\command value +\stoptyping + +\stopsummary + +\startsummary[title={context["command"]({ value }, { key = val }, val, false, val)}] + +The arguments are flushed accordingly their nature and the order can be any. + +\starttyping +\command [value][key={value}]{value}value +\stoptyping + +\stopsummary + +\startsummary[title={context.direct(...)}] + +The arguments are interpreted the same as if \type {direct} was a command, but no +\type {\direct} is injected in front. Braces are added: + +\startbuffer +regular \expandafter \bold \ctxlua{context.direct("bold")} regular +black \expandafter \color \ctxlua{context.direct({"red"})}{red} black +black \expandafter \color \ctxlua{context.direct({"green"},"green")} black +\stopbuffer + +\typebuffer + +The \type {\expandafter} makes sure that the \type {\bold} and \type {\color} +macros see the following \type{{bold}}, \type {[red]}, and \type {[green]{green}} +arguments. + +\startlines\getbuffer\stoplines + +\stopsummary + +\startsummary[title={context.delayed(...)}] + +The arguments are interpreted the same as in a \type {context} call, but instead +of a direct flush, the arguments will be flushed in a next cycle. + +\stopsummary + +\startsummary[title={context.delayed["command"](...)}] + +The arguments are interpreted the same as in a \type {command} call, but instead +of a direct flush, the command and arguments will be flushed in a next cycle. + +\stopsummary + +\startsummary[title={context.nested["command"]}] + +This command returns the command, including given arguments as a string. No +flushing takes place. + +\stopsummary + +\startsummary[title={context.nested}] + +This command returns the arguments as a string and treats them the same as a +regular \type {context} call. + +\stopsummary + +\startsummary[title={context.formatted["command"]([<regime>,]<format>,<arguments>)}] + +This command returns the command that will pass it's arguments to the string +formatter. When the first argument is a number, then it is interpreted as a +catcode regime. + +\stopsummary + +\startsummary[title={context.formatted([<regime>,]<format>,<arguments>)}] + +This command passes it's arguments to the string formatter. When the first +argument is a number, then it is interpreted as a catcode regime. + +\stopsummary + +\stopsection + +\startsection[title=\METAFUN] + +\startsummary[title={context.metafun.start()}] + +This starts a \METAFUN\ (or \METAPOST) graphic. + +\stopsummary + +\startsummary[title={context.metafun.stop()}] + +This finishes and flushes a \METAFUN\ (or \METAPOST) graphic. + +\stopsummary + +\startsummary[title={context.metafun("format",...)}] + +The argument is appended to the current graphic data but the string formatter is +used on following arguments. + +\stopsummary + +\startsummary[title={context.metafun.delayed}] + +This namespace does the same as \type {context.delayed}: it wraps the code in such +a way that it can be used in a function call. + +\stopsummary + +\startsection[title=Building blocks] + +\startsummary[title={context.bgroup() context.egroup()}] + +These are just \type {\bgroup} and \type {\egroup} equivalents and as these are +in fact shortcuts to the curly braced we output these instead. + +\stopsummary + +\startsummary[title={context.space()}] + +This one directly maps onto \type {\space}. + +\stopsummary + +\startsummary[title={context.par()}] + +This one directly maps onto \type {\par}. + +\stopsummary + +\stopsection + +\startsection[title=Basic Helpers] + +\startsummary[title={context.rule(wd,ht,dp,direction) context.rule(specification)}] + +A rule node is injected with the given properties. A specification is just a +table with the four fields. The rule gets the current attributes. + +\stopsummary + +\startsummary[title={context.glyph(fontid,n) context.glyph(n)}] + +A glyph node is injected with the given font id. When no id is given, the current font +is used. The glyph gets the current attributes. + +\stopsummary + +\startsummary[title={context.char(n) context.char(str) context.char(tab)}] + +This will inject one or more copies of \type {\char} calls. You can pass a +number, a string representing a number, or a table with numbers. + +\stopsummary + +\startsummary[title={context.utfchar(n) context.utfchar(str)}] + +This injects is \UTF\ character (one or more bytes). You can pass a number +or a string representing a numbers. You need to be aware of special +characters in \TEX, like \type {#}. + +\stopsummary + +\stopsection + +\startsection[title={Registers}] + +This is a table that hosts a couple of functions. The following \type {new} +ones are available: + +\starttyping +local n = newdimen (name) +local n = newskip (name) +local n = newcount (name) +local n = newmuskip(name) +local n = newtoks (name) +local n = newbox (name) +\stoptyping + +These define a register with name \type {name} at the \LUA\ end and \type {\name} +at the \TEX\ end. The registers' number is returned. The next function is like +\type {\chardef}: it defines \type {\name} with value \type {n}. + +\starttyping +local n = newchar(name,n) +\stoptyping + +It's not likely that you will use any of these commands, if only because when +you're operating from the \LUA\ end using \LUA\ variables is more convenient. + +\stopsection + +\startsection[title=Catcodes] + +Normally we operate under the so called \type {context} catcode regime. This +means that content gets piped to \TEX\ using the same meanings for characters as +you normally use in \CONTEXT. So, a \type {$} starts math. In \in {table} +[tab:catcodes] we show the catcode regimes. + +\startplacetable[location=page,title={Catcode regimes},reference=tab:catcodes] + \showcharactercatcodes +\stopplacetable + +\startsummary[title={context.catcodes}] + +The \type {context.catcodes} tables contains the internal numbers of the +catcode tables used. The next table shows the names that can be used. + +\starttabulate[|lT|cT|lT|] +\BC name \BC mnemonic \BC \TEX\ command \NC \NR +\NC context \NC ctx \NC ctxcatcodes \NC \NR +\NC protect \NC prt \NC prtcatcodes \NC \NR +\NC plain \NC tex \NC texcatcodes \NC \NR +\NC text \NC txt \NC txtcatcodes \NC \NR +\NC verbatim \NC vrb \NC vrbcatcodes \NC \NR +\stoptabulate + +\stopsummary + +\startsummary[title={context.newindexer(catcodeindex)}] + +This function defines a new indexer. You can think of the context command itself +as an indexer. There are two (extra) predefined indexers: + +\starttyping +context.verbatim = context.newindexer(context.catcodes.verbatim) +context.puretext = context.newindexer(context.catcodes.text) +\stoptyping + +\stopsummary + +\startsummary[title={context.pushcatcodes(n) context.popcatcodes()}] + +These commands switch to another catcode regime and back. They have to be used +in pairs. Only the regimes atthe \LUA\ end are set. + +\stopsummary + +\startsummary[title={context.unprotect() context.protect()}] + +These commands switch to the protected regime and back. They have to be used in +pairs. Beware: contrary to what its name suggests, the \type {unprotect} enables +the protected regime. These functions also issue an \type {\unprotect} and \type +{\protect} equivalent at the \TEX\ end. + +\stopsummary + +\startsummary[title={context.verbatim context.puretext}] + +The differences between these are subtle: + +\startbuffer +\startluacode + context.verbatim.bold("Why do we use $ for math?") context.par() + context.verbatim.bold("Why do we use { as start?") context.par() + context.verbatim.bold("Why do we use } as end?") context.par() + context.puretext.bold("Why do we use {\\bi $} at all?") +\stopluacode +\stopbuffer + +\typebuffer + +Verbatim makes all characters letters while pure text leaves the backslash and +curly braces special. + +\startpacked \getbuffer \stoppacked + +\stopsummary + +\startsummary[title={context.protected}] + +The protected namespace is only used for commands that are in the \CONTEXT\ +private namespace. + +\stopsummary + +\startsummary[title={context.escaped(str) context.escape(str)}] + +The first command pipes the escaped string to \TEX, while the second one just +returns an unescaped string. The characters \typ {# $ % \ \ { }} are escaped. + +\stopsummary + +\startsummary[title={context.startcollecting() context.stopcollecting()}] + +These two commands will turn flushing to \TEX\ into collecting. This can be handy +when you want to interface commands that grab arguments using delimiters and as +such they are used deep down in some table related interfacing. You probably +don't need them. + +\stopsummary + +\stopsection + +\startsection[title={Templates}] + +In addition to the regular template mechanism (part of the utilities) there is a +dedicated template feature in the \type {context} namespace. An example demonstrates +its working: + +\startbuffer +\startluacode + local MyTable = [[ + \bTABLE + \bTR + \bTD \bf %one_first% \eTD + \bTD %[one_second]% \eTD + \eTR + \bTR + \bTD \bf %two_first% \eTD + \bTD %[two_second]% \eTD + \eTR + \eTABLE + ]] + + context.templates[MyTable] { + one_first = "one", + two_first = "two", + one_second = "just one $", + two_second = "just two $", + } +\stopluacode +\stopbuffer + +\typebuffer + +This renders: + +\startlinecorrection + \getbuffer +\stoplinecorrection + +You can also use more complex tables. Watch the space before and after the keys: + +\startbuffer +\startluacode + local MyOtherTable = [[ + \bTABLE + \bTR + \bTD \bf % ['one']['first'] % \eTD + \bTD %[ ['one']['second'] ]% \eTD + \eTR + \bTR + \bTD \bf % ['two']['first'] % \eTD + \bTD %[ ['two']['second'] ]% \eTD + \eTR + \eTABLE + ]] + + local data = { + one = { first = "one", second = "only 1$" }, + two = { first = "two", second = "only 2$" }, + } + + context.templates[MyOtherTable](data) + + context.templates(MyOtherTable,data) +\stopluacode +\stopbuffer + +\typebuffer + +We get: + +\startlinecorrection + \getbuffer +\stoplinecorrection + +\stopsection + +\startsection[title={Management}] + +\startsummary[title={context.functions}] + +This is private table that hosts managament of functions. You'd better leave this +one alone! + +\stopsummary + +\startsummary[title={context.nodes}] + +Normally you will just use \type {context(<somenode>)} to flush a node and this +private table is more for internal use. + +\stopsummary + +\stopsection + +\startsection[title=String handlers] + +These two functions implement handlers that split a given string into lines and +do something with it. We stick to showing their call. They are used for special +purpose flushing, like flushing content to \TEX\ in commands discussed here. The +\XML\ subsystem also used a couple of dedicated handlers. + +\starttyping +local foo = newtexthandler { + content = function(s) ... end, + endofline = function(s) ... end, + emptyline = function(s) ... end, + simpleline = function(s) ... end, +} + +local foo = newverbosehandler { + line = function(s) ... end, + space = function(s) ... end, + content = function(s) ... end, + before = function() ... end, + after = function() ... end, +} +\stoptyping + +\startsummary[title={context.printlines(str)}] + +The low level \type {tex.print} function pipes its content to \TEX\ and thereby +terminates at at \type {\r} (cariage return, \ASCII\ 13), although it depends on +the way catcodes and line endings are set up. In fact, a line ending in \TEX\ is +not really one, as it gets replaced by a space. Only several lines in succession +indicate a new paragraph. + +\startbuffer +\startluacode + tex.print("line 1\n line 2\r line 3") +\stopluacode +\stopbuffer + +\typebuffer + +This renders only two lines: + +\getbuffer + +\startbuffer +\startluacode + context("line 1\n line 2\r line 3") +\stopluacode +\stopbuffer + +However, the \type {context} command gives all three lines: + +\typebuffer + +Like: + +\getbuffer + +The \type {context.printlines} command is a direct way to print a string in a way +similar to reading from a file. So, + +\starttyping +tex.print(io.loaddata(resolvers.findfile("tufte"))) +\stoptyping + +Gives one line, while: + +\starttyping +context.printlines(io.loaddata(resolvers.findfile("tufte"))) +\stoptyping + +gives them all, as does: + +\starttyping +context(io.loaddata(resolvers.findfile("tufte"))) +\stoptyping + +as does a na\"ive: + +\starttyping +tex.print((string.gsub(io.loaddata(resolvers.findfile("tufte")),"\r","\n"))) +\stoptyping + +But, because successive lines need to become paragraph separators as bit more +work is needed and that is what \type {printlines} and \type {context} do for +you. However, a more convenient alternative is presented next. + +\stopsummary + +\startsummary[title={context.loadfile(name)}] + +This function locates and loads the file with the given name. The leading and +trailing spaces are stripped. + +\stopsummary + +\startsummary[title={context.runfile(name)}] + +This function locates and processes the file with the given name. The assumption +is that it is a valid \LUA\ file! When no suffix is given, the suffix \type {cld} +(\CONTEXT\ \LUA\ document) is used. + +\stopsummary + +\startsummary[title={context.viafile(data[,tag])}] + +The \type {data} is saved to a (pseudo) file with the optional name \type {tag} +and read in again from that file. This is a robust way to make sure that the data +gets processed like any other data read from file. It permits all kind of +juggling with catcodes, verbatim and alike. + +\stopsummary + +\stopsection + +\startsection[title={Helpers}] + +\startsummary[title={context.tocontext(variable)}] + +For documentation or tracing it can be handy to serialize a variable. The \type +{tocontext} function does this: + +\starttyping +context.tocontext(true) +context.tocontext(123) +context.tocontext("foo") +context.tocontext(tonumber) +context.tocontext(nil) +context.tocontext({ "foo", "bar" },true) +context.tocontext({ this = { foo , "bar" } },true) +\stoptyping + +Beware, \type {tocontext} is also a table that you can assign to, but that might +spoil serialization. This property makes it possible to extend the serializer. + +\stopsummary + +\startsummary[title={context.tobuffer(name,str[,catcodes])}] + +With this function you can put content in a buffer, optionally under a catcode +regime. + +\stopsummary + +\startsummary[title={context.tolines(str[,true])}] + +This function splits the string in lines and flushes them one by one. When the +second argument is \type {true} leading and trailing spaces are stripped. Each +flushed line always gets one space appended. + +\stopsummary + +\startsummary[title={context.fprint([regime,]fmt,...),tex.fprint([regime,]fmt,...)}] + +The \type {tex.fprint} is just there to complement the other flushers in the +\type {tex} namespace and therefore we also have it in the \type {context} +namespace. + +\stopsummary + +\stopsection + +\startsection[title=Tracing] + +\startsummary[title={context.settracing(true or false))}] + +You can trace the \TEX\ code that is generated at the \TEX\ end with: + +\starttyping +\enabletrackers[context.trace] +\stoptyping + +The \LUA\ function sets the tracing from the \LUA\ end. As the \type {context} +command is used a lot in the core, you can expect some more tracing that the code +that you're currently checking. + +\stopsummary + +\startsummary[title={context.pushlogger(fnc) context.poplogger() context.getlogger()}] + +You can provide your own logger if needed. The pushed function receives one string +argument. The getter returns three functions: + +\starttyping +local flush, writer, flushdirect = context.getlogger() +\stoptyping + +The \type{flush} function is similar to \type {tex.sprint} and appends its +arguments, while \type {flushdirect} treats each argument as a line and behaves +like \type {tex.print}. The \type {flush} function adds braces and paranthesis +around its arguments, apartt from the first one, which is considered to be a +command. Examples are: + +\starttyping +flush("one",2,"three") -- catcode, strings|numbers +writer("\\color",{"red"},"this is red") +\stoptyping + +and: + +\starttyping +flush(context.catcodes.verbatim,"one",2,"three") +writer(context.catcodes.verbatim,"\\color",{"red"},"this is red") +\stoptyping + +\stopsummary + +\stopsection + +\startsection[title=States] + +There are several ways to implement alternative code paths in \CONTEXT\ but modes +and conditionals are used mostly. There area few helpers for that. + +\startsummary[title={context.conditionals context.setconditional(name,value)}] + +Conditionals are used to keep a state. You can set their value using the setter, +but their effect is not immediate but part of the current sequence of commands +which is delegated to \TEX. However, you can easily keep track of your state +at the \LUA\ end with an extra boolean. So, after + +\starttyping +if context.conditionals.whatever then + context.setconditional("dothis",false) +else + context.setconditional("dothat",true) +end +\stoptyping + +the value of \type {dothis} and \type {dothat} conditions are not yet set in +\LUA. + +\stopsummary + +\startsummary[title={context.modes context.setmode(name,value)}] + +As with conditionals, you can (re)set the modes in \LUA\ but their values +get changes as part of the command sequence which is delayed till after the +\LUA\ call. + +\stopsummary + +\startsummary[title={context.systemmodes context.setsystemmode(name,value)}] + +The same applies as for regular modes. + +\stopsummary + +\startsummary[title={context.trialtypesetting()}] + +This function returns \type {true} if we're in trial typesetting mode (used when +for instance prerolling a table). + +\stopsummary + +\stopsection + +\startsection[title=Steps] + +The stepper permits stepwise processing of \CONTEXT\ code: after a step contyrol +gets delegated to \CONTEXT\ and afterwards back to \LUA. There main limitation of +this mechanism is that it cannot exceed the number of input levels. + +\startsummary[title={context.stepwise() context.step([str])}] + +Usage is as follows: + +\starttyping +context.stepwise (function() + ... + context.step(...) + ... + context.step(...) + ... + context.stepwise (function() + ... + context.step(...) + ... + context.step(...) + ... + end) + ... + context.step(...) + ... + context.step(...) + ... +end) +\stoptyping + +\stopsummary + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/cld/cld-titlepage.tex b/doc/context/sources/general/manuals/cld/cld-titlepage.tex new file mode 100644 index 000000000..926a98952 --- /dev/null +++ b/doc/context/sources/general/manuals/cld/cld-titlepage.tex @@ -0,0 +1,14 @@ +\startcomponent cld-titlepage + +\environment cld-environment + +% \cldprocessfile{cld-mkiv-titlepage.cld} + +\startTEXpage + \externalfigure[cld-mkiv-titlepage.pdf]% +\stopTEXpage % faster during writing + +\startstandardmakeup[doublesided=no,page=no] +\stopstandardmakeup + +\stopcomponent diff --git a/doc/context/sources/general/manuals/cld/cld-verbatim.tex b/doc/context/sources/general/manuals/cld/cld-verbatim.tex new file mode 100644 index 000000000..2007f7d73 --- /dev/null +++ b/doc/context/sources/general/manuals/cld/cld-verbatim.tex @@ -0,0 +1,470 @@ +% language=uk + +\startcomponent cld-verbatim + +\environment cld-environment + +\startchapter[title=Verbatim] + +\startsection[title=Introduction] + +\index{verbatim} + +If you are familiar with traditional \TEX, you know that some characters have +special meanings. For instance a \type {$} starts and ends inline math mode: + +\starttyping +$e=mc^2$ +\stoptyping + +If we want to typeset math from the \LUA\ end, we can say: + +\starttyping +context.mathematics("e=mc^2") +\stoptyping + +This is in fact: + +\starttyping +\mathematics{e=mc^2} +\stoptyping + +However, if we want to typeset a dollar and use the \type {ctxcatcodes} regime, +we need to explicitly access that character using \type {\char} or use a command +that expands into the character with catcode other. + +One step further is that we typeset all characters as they are and this is called +verbatim. In that mode all characters are tokens without any special meaning. + +\stopsection + +\startsection[title=Special treatment] + +The formula in the introduction can be typeset verbatim as follows: + +\startbuffer +context.verbatim("$e=mc^2$") +\stopbuffer + +\typebuffer + +This gives: + +\ctxluabuffer + +You can also do things like this: + +\startbuffer +context.verbatim.bold("$e=mc^2$") +\stopbuffer + +\typebuffer + +Which gives: + +\ctxluabuffer + +So, within the \type {verbatim} namespace, each command gets its arguments +verbatim. + +\startbuffer +context.verbatim.inframed({ offset = "0pt" }, "$e=mc^2$") +\stopbuffer + +\typebuffer + +Here we get: \ctxluabuffer. So, settings and alike are processed as if the user +had used a regular \type {context.inframed} but the content comes out verbose. + +If you wonder why verbatim is needed as we also have the \type {type} function +(macro) the answer is that it is faster, easier to key in, and sometimes the only +way to get the desired result. + +\stopsection + +\startsection[title=Multiple lines] + +Currently we have to deal with linebreaks in a special way. This is due to the +way \TEX\ deals with linebreaks. In fact, when we print something to \TEX, the +text after a \type {\n} is simply ignored. + +For this reason we have a few helpers. If you want to put something in a buffer, +you cannot use the regular buffer functions unless you make sure that they are +not overwritten while you're still at the \LUA\ end. + +\starttyping +context.tobuffer("temp",str) +context.getbuffer("temp") +\stoptyping + +Another helper is the following. It splits the string into lines and feeds them +piecewise using the \type {context} function and in the process adds a space at +the end of the line (as this is what \TEX\ normally does. + +\starttyping +context.tolines(str) +\stoptyping + +Catcodes can get in the way when you pipe something to \TEX\ that itself changes +the catcodes. This happens for instance when you write buffers that themselves +have buffers or have code that changes the line endings as with \type +{startlines}. In that case you need to feed back the content as if it were a +file. This is done with: + +\starttyping +context.viafile(str) +\stoptyping + +The string can contain newlines. The string is written to a virtual file that is +input. Currently names looks like \type {virtual://virtualfile.1} but future +versions might have a different name part, so best use the variable instead. +After all, you don't know the current number in advance anyway. + +\stopsection + +\startsection[title=Pretty printing] + +In \CONTEXT\ \MKII\ there have always been pretty printing options. We needed it +for manuals and it was also handy to print sources in the same colors as the +editor uses. Most of those pretty printers work in a line|-|by|-|line basis, but +some are more complex, especially when comments or strings can span multiple +lines. + +When the first versions of \LUATEX\ showed up, rewriting the \MKII\ code to use +\LUA\ was a nice exercise and the code was not that bad, but when \LPEG\ showed +up, I put it on the agenda to reimplement them again. + +We only ship a few pretty printers. Users normally have their own preferences and +it's not easy to make general purpose pretty printers. This is why the new +framework is a bit more flexible and permits users to kick in their own code. + +Pretty printing involves more than coloring some characters or words: + +\startitemize[packed] +\startitem spaces should honoured and can be visualized \stopitem +\startitem newlines and empty lins need to be honoured as well \stopitem +\startitem optionally lines have to be numbered but \stopitem +\startitem wrapped around lines should not be numbered \stopitem +\stopitemize + +It's not much fun to deal with these matters each time that you write a pretty +printer. This is why we can start with an existing one like the default pretty +printer. We show several variants of doing the same. We start with a simple clone +of the default parser. \footnote {In the meantime the lexer of the \SCITE\ editor +that I used also provides a mechanism for using \LPEG\ based lexers. Although in +the pretty printing code we need a more liberal one I might backport the lexers I +wrote for editing \TEX, \METAPOST, \LUA, \CLD, \XML\ and \PDF\ as a variant for +the ones we use in \MKIV\ now. That way we get similar colorschemes which might +be handy sometimes.} + +\startbuffer +local P, V = lpeg.P, lpeg.V + +local grammar = visualizers.newgrammar("default", { + pattern = V("default:pattern"), + visualizer = V("pattern")^1 +} ) + +local parser = P(grammar) + +visualizers.register("test-0", { parser = parser }) +\stopbuffer + +\typebuffer \ctxluabuffer + +We distinguish between grammars (tables with rules), parsers (a grammar turned +into an \LPEG\ expression), and handlers (collections of functions that can be +applied. All three are registered under a name and the verbatim commands can +refer to that name. + +\startbuffer +\starttyping[option=test-0,color=] +Test 123, +test 456 and +test 789! +\stoptyping +\stopbuffer + +\typebuffer + +Nothing special happens here. We just get straightforward verbatim. + +\getbuffer + +Next we are going to color digits. We collect as many as possible in a row, so +that we minimize the calls to the colorizer. + +\startbuffer +local patterns, P, V = lpeg.patterns, lpeg.P, lpeg.V + +local function colorize(s) + context.color{"darkred"} + visualizers.writeargument(s) +end + +local grammar = visualizers.newgrammar("default", { + digit = patterns.digit^1 / colorize, + pattern = V("digit") + V("default:pattern"), + visualizer = V("pattern")^1 +} ) + +local parser = P(grammar) + +visualizers.register("test-1", { parser = parser }) +\stopbuffer + +\typebuffer \ctxluabuffer + +Watch how we define a new rule for the digits and overload the pattern rule. We +can refer to the default rule by using a prefix. This is needed when we define a +rule with the same name. + +\startbuffer +\starttyping[option=test-1,color=] +Test 123, +test 456 and +test 789! +\stoptyping +\stopbuffer + +\typebuffer + +This time the digits get colored. + +\getbuffer + +In a similar way we can colorize letters. As with the previous example, we use +\CONTEXT\ commands at the \LUA\ end. + +\startluacode +local patterns, P, V = lpeg.patterns, lpeg.P, lpeg.V + +local function colorize_lowercase(s) + context.color{"darkgreen"} + visualizers.writeargument(s) +end +local function colorize_uppercase(s) + context.color{"darkblue"} + visualizers.writeargument(s) +end + +local grammar = visualizers.newgrammar("default", { + + lowercase = patterns.lowercase^1 / colorize_lowercase, + uppercase = patterns.uppercase^1 / colorize_uppercase, + + pattern = + V("lowercase") + + V("uppercase") + + V("default:pattern"), + + visualizer = V("pattern")^1 + +} ) + +local parser = P(grammar) + +visualizers.register("test-2", { parser = parser }) +\stopluacode + +\startbuffer +\starttyping[option=test-2,color=] +Test 123, +test 456 and +test 789! +\stoptyping +\stopbuffer + +\typebuffer + +Again we get some coloring. + +\getbuffer + +It will be clear that the amount of rules and functions is larger when we use a +more complex parser. It is for this reason that we can group functions in +handlers. We can also make a pretty printer configurable by defining handlers at +the \TEX\ end. + +\startbuffer +\definestartstop + [MyDigit] + [style=bold,color=darkred] + +\definestartstop + [MyLowercase] + [style=bold,color=darkgreen] + +\definestartstop + [MyUppercase] + [style=bold,color=darkblue] +\stopbuffer + +\typebuffer \getbuffer + +The \LUA\ code now looks different. Watch out: we need an indirect call to for +instance \type {MyDigit} because a second argument can be passed: the settings +for this environment and you don't want that get passed to \type {MyDigit} and +friends. + +\startluacode +local patterns, P, V = lpeg.patterns, lpeg.P, lpeg.V +local pattern = visualizers.pattern +local verbatim = context.verbatim + +local MyDigit = verbatim.MyDigit +local MyLowercase = verbatim.MyLowercase +local MyUppercase = verbatim.MyUppercase + +-- local handler = newhandler("default, { +-- digit = function(s) MyDigit (s) end, +-- lowercase = function(s) MyLowercase(s) end, +-- uppercase = function(s) MyUppercase(s) end, +-- } ) + +local handler = { + digit = function(s) MyDigit (s) end, + lowercase = function(s) MyLowercase(s) end, + uppercase = function(s) MyUppercase(s) end, +} + +local grammar = visualizers.newgrammar("default", { + + digit = pattern(handler,"digit", patterns.digit ^1), + lowercase = pattern(handler,"lowercase", patterns.lowercase^1), + uppercase = pattern(handler,"uppercase", patterns.uppercase^1), + + pattern = + V("lowercase") + + V("uppercase") + + V("digit") + + V("default:pattern"), + + visualizer = V("pattern")^1 + +} ) + +local parser = P(grammar) + +visualizers.register("test-3", { parser = parser, handler = handler }) +\stopluacode + +\startbuffer +\starttyping[option=test-3,color=] +Test 123, +test 456 and +test 789! +\stoptyping +\stopbuffer + +\typebuffer + +We get digits, upper- and lowercase characters colored: + +\getbuffer + +You can also use parsers that don't use \LPEG: + +\startbuffer +local function parser(s) + visualizers.write("["..s.."]") +end + +visualizers.register("test-4", { parser = parser }) +\stopbuffer + +\typebuffer \ctxluabuffer + +\startbuffer +\starttyping[option=test-4,space=on,color=darkred] +Test 123, +test 456 and +test 789! +\stoptyping +\stopbuffer + +\typebuffer + +The function \type {visualizer.write} takes care of spaces and newlines. + +\getbuffer + +We have a few more helpers: + +\starttabulate[|||] +\NC \type{visualizers.write} \NC interprets the argument and applies methods \NC \NR +\NC \type{visualizers.writenewline} \NC goes to the next line (similar to \type {\par} \NC \NR +\NC \type{visualizers.writeemptyline} \NC inserts an empty line (similer to \type {\blank} \NC \NR +\NC \type{visualizers.writespace} \NC inserts a (visible) space \NC \NR +\NC \type{visualizers.writedefault} \NC writes the argument verbatim without interpretation \NC \NR +\stoptabulate + +These mechanism have quite some overhead in terms of function calls. In the worst +case each token needs a (nested) call. However, doing all this at the \TEX\ end +also comes at a price. So, in practice this approach is more flexible but without +too large a penalty. + +In all these examples we typeset the text verbose: what is keyed in normally +comes out (either or not with colors), so spaces stay spaces and linebreaks are +kept. + +\startbuffer +local function parser(s) + local s = string.gsub(s,"show","demonstrate") + local s = string.gsub(s,"'re"," are") + context(s) +end + +visualizers.register("test-5", { parser = parser }) +\stopbuffer + +\typebuffer \ctxluabuffer + +\startbuffer +\starttyping[option=test-5,color=darkred,style=] +This is just some text to show what we can do with this mechanism. In +spite of what you might think we're not bound to verbose text. +\stoptyping +\stopbuffer + +We can apply this visualizer as follows: + +\typebuffer + +This time the text gets properly aligned: + +\getbuffer + +It often makes sense to use a buffer: + +\startbuffer +\startbuffer[demo] +This is just some text to show what we can do with this mechanism. In +spite of what you might think we're not bound to verbose text. +\stopbuffer +\stopbuffer + +\typebuffer \getbuffer + +Instead of processing the buffer in verbatim mode you can then +process it directly: + +\startbuffer +\setuptyping[file][option=test-5,color=darkred,style=] +\ctxluabuffer[demo] +\stopbuffer + +\typebuffer + +Which gives: + +\start \getbuffer \stop + +In this case, the space is a normal space and not the fixed verbatim space, which +looks better. + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/details/back-0.tex b/doc/context/sources/general/manuals/details/back-0.tex new file mode 100644 index 000000000..137884919 --- /dev/null +++ b/doc/context/sources/general/manuals/details/back-0.tex @@ -0,0 +1,39 @@ +% content=tex +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\startenvironment back-0 + +\usemodule[simulate] + +\definecolor[shadecolor][r=.5,g=.5,b=.75] % blue +\definecolor[shadecolor][r=.5,g=.5,b=.25] % yellow + +\definecolor[red] [r=.5] +\definecolor[blue] [b=.5] +\definecolor[green][g=.5] + +\setuplayout + [width=middle,height=middle, + backspace=1cm,topspace=1cm, + header=0pt,footer=0pt,grid=yes] + +\setuprandomize + [medium] + +\setupbackgrounds + [page] + [background=color, + backgroundcolor=white] + +\setuptolerance + [verytolerant,stretch] + +\setupcolors + [state=start] + +\showgrid + +\setrandomseed{1000} + +\stopenvironment diff --git a/doc/context/sources/general/manuals/details/back-1.tex b/doc/context/sources/general/manuals/details/back-1.tex new file mode 100644 index 000000000..5f5109184 --- /dev/null +++ b/doc/context/sources/general/manuals/details/back-1.tex @@ -0,0 +1,58 @@ +\environment back-0 + +\setupindenting[big] + +\definecolumnset[two][n=3] +\definecolumnsetspan[test] + +\definetextbackground[test] + [background=color, + backgroundcolor=gray] + +\definetextbackground[more] + [background=color, + backgroundcolor=lightgray, + alternative=1,rulethickness=2pt] + +\dontcomplain + +\starttext + +\startcolumnset[two] + + \startcolumnsetspan[test] + \input tufte + \stopcolumnsetspan + + \starttextbackground[test] + + \input tufte \par + + \startnarrower + + \starttextbackground[more] + + \input tufte \par + \input tufte \par + \input tufte \par + \input tufte \par + \input tufte \par + \input tufte + + \stoptextbackground + + \stopnarrower + + \stoptextbackground + + \input tufte + + \starttextbackground[more] \input tufte \stoptextbackground + + \starttextbackground[test] \input tufte \stoptextbackground + + \starttextbackground[more] \input tufte \stoptextbackground + +\stopcolumnset + +\stoptext diff --git a/doc/context/sources/general/manuals/details/back-2.tex b/doc/context/sources/general/manuals/details/back-2.tex new file mode 100644 index 000000000..053125827 --- /dev/null +++ b/doc/context/sources/general/manuals/details/back-2.tex @@ -0,0 +1,99 @@ +\environment back-0 + +\startuseMPgraphic{mpos:par:color} + for i=1 upto nofmultipars : + fill multipars[i] withcolor + if multikind[i]="single" : "darkgray" ; + elseif multikind[i]="first" : "red" ; + elseif multikind[i]="middle" : "green" ; + elseif multikind[i]="last" : "blue" ; + else : "black" ; + fi ; + endfor ; +\stopuseMPgraphic + +\setupindenting + [medium,first] + +\definecolumnset + [four] + [n=4, + distance=7.5mm] + +\definetextbackground + [test] + [location=text, + mp=mpos:par:color, + before=\blank, + after=\blank] + +\starttext + +\starttexdefinition test #1#2#3 + \blank + \bgroup + \dontcomplain + \hangindent#1\relax + \hangafter #2\relax + \parindent #3\relax + \starttextbackground[test]% + \simulatewords[n=200,m=500,min=1,max=5,color=gray]% + \stoptextbackground + \par + \egroup + \blank +\stoptexdefinition + +\startcolumnset[four] + +\startbuffer[a] +\test {2cm} { -2} { 5mm} +\test {2cm} { -2} { 0cm} +\test {2cm} { -2} {-5mm} + +\test {2cm} { -5} { 5mm} +\test {2cm} { -5} { 0cm} +\test {2cm} { -5} {-5mm} + +\stopbuffer + +\startbuffer[b] +\test {-1cm} { -2} { 5mm} +\test {-1cm} { -2} { 0cm} +\test {-1cm} { -2} {-5mm} + +\test {-1cm} { -5} { 5mm} +\test {-1cm} { -5} { 0cm} +\test {-1cm} { -5} {-5mm} +\stopbuffer + +\startbuffer[c] +\test { 1cm} { 2} { 5mm} +\test { 1cm} { 2} { 0cm} +\test { 1cm} { 2} {-5mm} + +\test { 1cm} { 5} { 5mm} +\test { 1cm} { 5} { 0cm} +\test { 1cm} { 5} {-5mm} +\stopbuffer + +\startbuffer[d] +\test {-1cm} { 2} { 5mm} +\test {-1cm} { 2} { 0cm} +\test {-1cm} { 2} {-5mm} + +\test {-1cm} { 5} { 5mm} +\test {-1cm} { 5} { 0cm} +\test {-1cm} { 5} {-5mm} +\stopbuffer + +\dorecurse{2}{ + \dorecurse{1}{\getbuffer[a]} + \dorecurse{1}{\getbuffer[b]} + \dorecurse{1}{\getbuffer[c]} + \dorecurse{1}{\getbuffer[d]} +} + +\stopcolumnset + +\stoptext diff --git a/doc/context/sources/general/manuals/details/back-4.tex b/doc/context/sources/general/manuals/details/back-4.tex new file mode 100644 index 000000000..217525ed8 --- /dev/null +++ b/doc/context/sources/general/manuals/details/back-4.tex @@ -0,0 +1,39 @@ +\environment back-0 + +\startuseMPgraphic{mpos:par:color} + for i=1 upto nofmultipars : + fill multipars[i] withcolor + if multikind[i]="single" : "darkgray" ; + elseif multikind[i]="first" : "red" ; + elseif multikind[i]="middle" : "green" ; + elseif multikind[i]="last" : "blue" ; + else : "black" ; + fi ; + endfor ; +\stopuseMPgraphic + +\definecolumnset + [three] + [n=3, + distance=5mm] + +\definetextbackground + [shade] + [location=paragraph, + mp=mpos:par:color, + before=\blank, + after=\blank] + +\starttext + +\startcolumnset[three] + + \dorecurse {20} { + \starttextbackground[shade] + \simulatewords[n=50,m=500,min=1,max=5,color=gray]% + \stoptextbackground + } + +\stopcolumnset + +\stoptext diff --git a/doc/context/sources/general/manuals/details/back-5.tex b/doc/context/sources/general/manuals/details/back-5.tex new file mode 100644 index 000000000..a2d2c4632 --- /dev/null +++ b/doc/context/sources/general/manuals/details/back-5.tex @@ -0,0 +1,64 @@ +\environment back-0 + +\startuseMPgraphic{mpos:par:columnset:shade} + numeric h ; + for i=1 upto nofmultipars : + h := bbheight(p) ; + if multikind[i] = "single" : + fill multipars[i] topenlarged -.5h + withshademethod "linear" + withshadedirection shadedup + withcolor boxfillcolor shadedinto .8white ; + fill multipars[i] bottomenlarged -.5h + withshademethod "linear" + withshadedirection shadedup + withcolor .8white shadedinto boxfillcolor ; + elseif multikind[i] = "first" : + fill multipars[i] + withshademethod "linear" + withshadedirection shadedup + withcolor boxfillcolor shadedinto .8white ; + elseif multikind[i] = "middle" : + fill multipars[i] topenlarged -.5h + withshademethod "linear" + withshadedirection shadedup + withcolor boxfillcolor shadedinto .8white ; + fill multipars[i] bottomenlarged -.5h + withshademethod "linear" + withshadedirection shadedup + withcolor .8white shadedinto boxfillcolor ; + elseif multikind[i] = "last" : + fill multipars[i] + withshademethod "linear" + withshadedirection shadedup + withcolor .8white shadedinto boxfillcolor ; + fi ; + endfor ; +\stopuseMPgraphic + +\definecolumnset + [four] + [n=4, + distance=5mm] + +\definetextbackground + [shade] + [location=paragraph, + backgroundcolor=shadecolor, + mp=mpos:par:columnset:shade, + before=\blank, + after=\blank] + +\starttext + + \startcolumnset[four] + + \dorecurse{15} { + \starttextbackground[shade] + \simulatewords[n=10,m=500,min=1,max=5,color=text]% + \stoptextbackground + } + + \stopcolumnset + +\stoptext diff --git a/doc/context/sources/general/manuals/details/cow.pdf b/doc/context/sources/general/manuals/details/cow.pdf Binary files differnew file mode 100644 index 000000000..9cc8fb0b4 --- /dev/null +++ b/doc/context/sources/general/manuals/details/cow.pdf diff --git a/doc/context/sources/general/manuals/details/details-backpage.tex b/doc/context/sources/general/manuals/details/details-backpage.tex new file mode 100644 index 000000000..85e4d38ce --- /dev/null +++ b/doc/context/sources/general/manuals/details/details-backpage.tex @@ -0,0 +1,34 @@ +% language=uk + +\environment details-environment + +\startcomponent details-backpage + +\page[right] + +\startpagemakeup[doublesided=no,pagestate=stop,page=no] + \startMPcode + StartPage ; + fill Page withcolor \MPcolor{blue} ; % .5blue ; + StopPage ; + \stopMPcode +\stoppagemakeup + +\startpagemakeup[doublesided=no,pagestate=stop,page=no] + \startMPcode + StartPage ; + path p[] ; picture q[] ; + p[1] := Page ; + p[2] := Page xscaled .6 shifted (.2PaperWidth,0) ; + q[1] := textext.raw("\color[white]{CONTEXT}") xsized(.6PaperWidth) ; + q[2] := textext.raw("\color[white]{\currentdate}") xsized(.6PaperWidth) ; + fill p[1] withcolor \MPcolor{red} ; % .5red + fill p[2] withcolor \MPcolor{blue} ; % .5blue + q[2] := q[2] shifted (0,-1.5bbheight(q[2])) ; + draw q[1] shifted (.2PaperWidth,.15PaperHeight) ; + draw q[2] shifted (.2PaperWidth,.15PaperHeight) ; + StopPage ; + \stopMPcode +\stoppagemakeup + +\stopcomponent diff --git a/doc/context/sources/general/manuals/details/details-captiontrickery.tex b/doc/context/sources/general/manuals/details/details-captiontrickery.tex new file mode 100644 index 000000000..ccd163e20 --- /dev/null +++ b/doc/context/sources/general/manuals/details/details-captiontrickery.tex @@ -0,0 +1,290 @@ +% language=uk + +\environment details-environment + +\startcomponent details-captiontrickery + +\startchapter[title={Caption handling}] + +\start + +It's hard to predict what kind of caption placements users want. The amount of +variation if large and thereby any system of specifying them will look complex. +So, examples are the best way to show them. + +\startbuffer +\setupcaption + [figure] + [location=bottom] +\placefigure + [left] + {}{\externalfigure[dummy][lines=2,width=4cm]} +\fakewords{60}{80} \par +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +% \setupfloats[grid=yes] +% \setupfloats[grid=tolerant] +\setupcaption + [figure] + [location=top] +\placefigure + [left] + {}{\externalfigure[dummy][lines=2,width=4cm]} +\fakewords{60}{80} \par +\stopbuffer + +\typebuffer \getbuffer + +In this document we typeset on a grid. For more complex cases and when a document +is processed without any user intervention, this is often a bad idea because the +snapper can decide to make sure that there is enough space above and below an +element. You can however influence the snapper explicitly: + +\startbuffer +\setupcaption + [figure] + [location=top] +\placefigure + [left,line] + {}{\externalfigure[dummy][lines=2,width=4cm]} +\fakewords{60}{80} \par +\stopbuffer + +\typebuffer \getbuffer + +Normally a side float plus caption has a normalized (strut) depth while also +top skip gets applied. When one of the grid related options \type {height}, \type +{line}, \type {depth}, \type {grid} or \type {halfline} is given the top skip +correction is removed. The \type {grid} option removes the depth too. The \type +{grid} option removes the depth while the \type {height} and \type {depth} +options adds an extra amount of strut depth. The \type {depth} option also adds a +line and \type {halfline} removes a line but adds strut height. Indeed this sounds +complicated so best play with it a bit. + +Keep in mind that the snapper plays safe and therefore tends to add more space when +needed. You can set a grid parameter that controls it: + +\starttyping +\setupfloats[grid=tolerant] +\stoptyping + +Currently this only applies to side floats but in the future we might support it +for regular floats too. + +\startbuffer +\setupcaption + [figure] + [width=4cm,align=flushright,location={left,high}] +\placefigure + [left] + {}{\externalfigure[dummy][lines=2,width=4cm]} +\fakewords{60}{80} \par +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\setupcaption + [figure] + [width=4cm,align=flushright,location={high,lefthanging}] +\placefigure + [left] + {}{\externalfigure[dummy][lines=2,width=4cm]} +\fakewords{60}{80} \par +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\setupcaption + [figure] + [width=4cm,align=flushleft,location={high,righthanging}] +\placefigure + [right] + {}{\externalfigure[dummy][lines=2,width=4cm]} +\fakewords{60}{80} \par +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\setupcaption + [figure] + [width=4cm,align=flushleft,location={high,rightmargin}] +\placefigure + [right] + {}{\externalfigure[dummy][lines=2,width=4cm]} +\fakewords{60}{80} \par +\stopbuffer + +\typebuffer \getbuffer + +The location of a caption is determined by the keywords \type {top}, \type +{bottom} and for the side captions \type {high}, \type {middle}, \type {low}, +either or not in combination with \type {left}, \type {right}, \type +{leftmargin}, \type {rightmargin}, {lefthanging} or \type {righthanging}. + +The next series of examples shows the regular (non||side) floats. + +\startbuffer +\setupcaption + [figure] + [location={high,left}] +\placefigure + {}{\externalfigure[dummy][lines=2,width=4cm]} +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\setupcaption + [figure] + [width=4cm,align=flushright,location={high,left}] +\placefigure + {}{\externalfigure[dummy][lines=2,width=4cm]} +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\setupcaption + [figure] + [width=4cm,align=flushright,location={middle,left}] +\placefigure + {}{\externalfigure[dummy][lines=2,width=4cm]} +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\setupcaption + [figure] + [width=4cm,align=flushright,location={low,left}] +\placefigure + {}{\externalfigure[dummy][lines=2,width=4cm]} +\stopbuffer + +\startbuffer +\setupfloat + [figure] + [location=right] +\setupcaption + [figure] + [width=4cm,align=flushright,location=high] +\placefigure + {}{\externalfigure[dummy][lines=2,width=4cm]} +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\setupfloat + [figure] + [location=right] +\setupcaption + [figure] + [width=4cm,align=flushright,location={high,left}] +\placefigure + {}{\externalfigure[dummy][lines=2,width=4cm]} + +\setupfloat + [figure] + [location=left] +\setupcaption + [figure] + [width=4cm,align=flushleft, location={high,left}] +\placefigure + {}{\externalfigure[dummy][lines=2,width=4cm]} +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\setupfloat + [figure] + [location=middle] +\setupcaption + [figure] + [width=4cm,align=flushright, location={high,lefthanging}] +\placefigure + {}{\externalfigure[dummy][lines=2,width=4cm]} +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\setupfloat + [figure] + [location=middle] +\setupcaption + [figure] + [width=4cm,align=flushleft, location={high,righthanging}] +\placefigure + {}{\externalfigure[dummy][lines=2,width=4cm]} +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\setupfloat + [figure] + [location=right] +\setupcaption + [figure] + [width=4cm,align=flushleft, location={high,rightmargin}] +\placefigure + {}{\externalfigure[dummy][lines=2,width=4cm]} +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\setupfloat + [figure] + [location=left] +\setupcaption + [figure] + [width=4cm,align=flushright,location={high,leftmargin}] +\placefigure + {}{\externalfigure[dummy][lines=2,width=4cm]} +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\setupfloat + [figure] + [location=middle] +\setupcaption + [figure] + [width=4cm,align=flushright,location={high,outermargin}] +\placefigure + {}{\externalfigure[dummy][lines=2,width=4cm]} +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\setupfloat + [figure] + [location=middle] +\setupcaption + [figure] + [width=4cm,align=flushleft, location={high,innermargin}] +\placefigure + {}{\externalfigure[dummy][lines=2,width=4cm]} +\stopbuffer + +\typebuffer \getbuffer + +The \type {innermargin} and \type {outermargin} are special cases. They adapt to +the kind of page. + +\page \stop + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/details/details-colofon.tex b/doc/context/sources/general/manuals/details/details-colofon.tex new file mode 100644 index 000000000..1ceda44e7 --- /dev/null +++ b/doc/context/sources/general/manuals/details/details-colofon.tex @@ -0,0 +1,36 @@ +% language=uk + +\environment details-environment + +\startcomponent details-colofon + +\startchapter[title={About this document}] + +This document is typeset in \CONTEXT\ using \LUATEX\ with \METAPOST. We use only +one font: the Computer Modern Typewriter. The verbatim portions of the text are +typeset in its mono spaced variant. One of the reasons that I chose this font is +that we need a mono spaced font to typeset the example code, and the Computer +Modern Typewriter is one the best there is. This font combines well with many +other typefaces, but the sometimes excessive use of different fonts (and sizes) +in the styles that I have to implement made me long for simplicity. And so I +decided to stick to one font. A careful reader will notice that this document has +character protruding enabled (resulting in hanging punctuation). + +We use a couple of colors. Again, I went for simplicity and use rather primary +colors, although I do use them in transparent variants as well. + +There is not much more to say, apart from that I want to thank our customers as +well as \CONTEXT\ users for asking me to implement \DTP\ competing styles and +features. Their demands drive \CONTEXT\ in directions we could not have foreseen +when we started its development. + +We use a (transparent) gray background behind the text so that we have an +indication where the text area is positioned relative to the page. It also +enables us to comfortably turn on the grid. + +Some features shown here are relatively new and therefore they occasionally are +improved. As a result some aspects of their functionality may change. + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/details/details-contents.tex b/doc/context/sources/general/manuals/details/details-contents.tex new file mode 100644 index 000000000..737f080a0 --- /dev/null +++ b/doc/context/sources/general/manuals/details/details-contents.tex @@ -0,0 +1,13 @@ +% language=uk + +\environment details-environment + +\startcomponent details-contents + +\starttitle[title={Table of contents}] + +\placelist[chapter][criterium=text] + +\stoptitle + +\stopcomponent diff --git a/doc/context/sources/general/manuals/details/details-environment.tex b/doc/context/sources/general/manuals/details/details-environment.tex new file mode 100644 index 000000000..003ea6905 --- /dev/null +++ b/doc/context/sources/general/manuals/details/details-environment.tex @@ -0,0 +1,317 @@ +% language=uk + +% this a rather old style and made for mkii, currently the only adaption to mkiv is +% with respect to fonts + +\showgrid + +\startenvironment details-environment + +\usemodule[abr-02,simulate] % visual + +\setupsystem + [random=123] + +\setupinteraction + [state=start, + style=, + color=] + +\setuplist + [chapter] + [interaction=all] + +\setupalign + [verytolerant, + stretch, + hanging] + +\setuptolerance + [verytolerant, + stretch] + +\definefontfeature + [fullprotrusion] + [protrusion=pure] + +\definefontfeature[default][default,fullprotrusion] + +\setupbodyfont[modernvariable,12pt] + +\setuppagenumbering + [alternative=doublesided] + +\setupindenting + [medium] + +\setuptyping + [margin=standard] + +\setuptyping + [color=blue] + +\setuptype + [color=blue] + +\startmode [screen] + \definepapersize[A4-S][width=210mm,height=210mm] + \setuppapersize[A4-S][A4-S] +\stopmode + +\setuplayout + [header=3cm, + footer=0pt, + topspace=0cm, + bottomspace=2cm, + bottom=2cm, + bottomdistance=0pt, + height=middle, + margindistance=.5cm, + leftmargin=2.0cm, + rightmargin=2.5cm, + backspace=2.5cm, + cutspace=3cm, + width=middle, + lines=48, % otherwise background issue +% textdistance=\dimexpr-\topskip+\strutheight+.5cm\relax, + grid=yes] + +\setuplayout + [margindistance=.5cm, + edgedistance=.25cm, + rightmargin=1cm, + rightedge=.75cm, + leftmargin=1cm, + leftedge=.5cm] + +\setuppagenumbering + [location=] + +\definecolor[red] [r=.5] +\definecolor[blue] [b=.5] +\definecolor[green] [g=.5] +\definecolor[yellow] [r=.5,g=.5] +\definecolor[gray] [s=.5] + +\definecolor[tred] [r=.5,t=.5,a=1] +\definecolor[tblue] [b=.5,t=.5,a=1] +\definecolor[tgreen] [g=.5,t=.5,a=1] +\definecolor[tyellow] [r=.5,g=.5,t=.5,a=1] +\definecolor[twhite] [s=0,t=.5,a=1] + +\definecolor[infogray] [g=.5,t=.5,a=1] +\definecolor[infogray] [s=.7,t=.5,a=1] +\definecolor[pagegray] [y=.5,t=.5,a=1] +\definecolor[textgray] [s=.9,t=.5,a=1] +\definecolor[areafill] [g=.5,t=.125,a=1] +\definecolor[areafill] [b=.5,t=.125,a=1] + +\definecolor[fakerulecolor] [green] +\definecolor[fakeparindentcolor][blue] + +\definefont[BigNumber][RegularBold sa 4] % 5 +\definefont[BigText] [RegularBold sa 2] +\definefont[MedNumber][RegularBold sa 2] + +\startbuffer[regular:sizes] +\definefont[regular:1][Regular*default sa 1] +\definefont[regular:2][Regular*default sa 2] +\definefont[regular:3][Regular*default sa 3] +\definefont[regular:4][Regular*default sa 4] +\stopbuffer + +\getbuffer[regular:sizes] + +\useMPlibrary[dum] + +\definecolor[p-red] [r=1] +\definecolor[p-blue] [b=1] +\definecolor[p-yellow] [r=1,g=1] + +\definepalet + [placeholder] + [1=p-red,2=p-blue,3=p-yellow] + +\definelayer + [graphics] + [position=yes] + +\setupbackgrounds + [page] + [background={color,graphics}, + backgroundoffset=1cm, + backgroundcolor=pagegray] + +\definelayer + [extras] + [width=\paperwidth,height=\paperheight] + +\setupbackgrounds + [leftpage] + [background=extras] + +\setupbackgrounds + [rightpage] + [background=extras] + +\definelayer % we need to compensate the backgroundoffset + [text] + [hoffset=1cm, + voffset=1cm] + +\setupbackgrounds + [text] + [background={color,text}, + backgroundoffset=1cm, + backgroundcolor=textgray] + +% chapter head + +\setuphead + [chapter] + [placehead=empty, + header=chapter, + incrementnumber=details, + style=\BigText, + numberstyle=\BigNumber] + +% we need to check each file +% +% \setuphead +% [chapter] +% [beforesection=\page, +% aftersection=\page] + +\definetext + [chapter] + [header] + [\setups{chapter}] + [] + +\definelayer + [chapter] + [width=\dimexpr\makeupwidth+\cutspace\relax, + height=\headerheight] + +\startsetups chapter + \setups[chapter:title] + \setups[chapter:number] + \setups[chapter:finish] +\stopsetups + +% here we can use mp instead but the following is not that bad either + +\startsetups chapter:title + + \setlayerframed + [chapter] + [x=\dimexpr\makeupwidth+\cutspace\relax, + location=lb] + [height=\headerheight, + foregroundcolor=white, + background=color, + backgroundcolor=blue, + frame=off, + offset=none, + align={right,lohi}] + {\hbox spread .5\cutspace + {\hss + \doiftextelse{\placeheadtext[chapter]}% + {\placeheadtext[chapter]}% + {\placeheadtext[title]}% + \hss}\space + \vskip.5cm} + +\stopsetups + +\startsetups chapter:number + + \setlayerframed + [chapter] + [x=\dimexpr\makeupwidth+\cutspace\relax, + y=\vsize, + location=lb] + [width=\dimexpr\cutspace-\rightmargindistance\relax, + height=\dimexpr\cutspace-\rightmargindistance\relax, + foregroundcolor=white, + background=color, + backgroundcolor=red, + frame=off, + offset=none, + align={middle,lohi}] + {\hbox to \hsize + {\hskip.5cm\hss + \doifmode{*bodypart}{\placeheadnumber[chapter]}% + \hss}} + +\stopsetups + +\startsetups chapter:finish + + \framed + [width=\makeupwidth, + height=\headerheight, + background=chapter, + frame=off] + {} + +\stopsetups + +% page number + +\defineframedtext + [pagenumbertext] + [align={lohi,middle}, + width=\dimexpr\cutspace-\margindistance\relax, % \hsize, + height=\vsize, + background=color, + backgroundcolor=green, + style=\MedNumber, + color=white, + offset=none, + frame=off] + +\setupbottomtexts + [margin] + [] + [\pagenumbertext{\hbox to \hsize{\hskip.5cm\hss\placepagenumber\hss}}] + [\pagenumbertext{\hbox to \hsize{\hss\placepagenumber\hss\hskip.5cm}}] + [] + +% area + +\setupbackgrounds [text] [leftedge] [backgroundoffset=0pt,backgroundcolor=areafill] +\setupbackgrounds [text] [rightedge] [backgroundoffset=0pt,backgroundcolor=areafill] +\setupbackgrounds [text] [leftmargin] [backgroundoffset=0pt,backgroundcolor=areafill] +\setupbackgrounds [text] [rightmargin] [backgroundoffset=0pt,backgroundcolor=areafill] + +% grids + +\setuptextbackground + [grid] + [state=start] + +% intros + +% \definetextbackground +% [intro] +% [backgroundcolor=infogray, % green, +% backgroundoffset=.25cm, +% offset=.5cm, +% frame=off, +% color=white] + +\setuplist + [chapter] + [before=, + after=, + alternative=c, + aligntitle=yes] + +\startsectionblockenvironment [backpart] + + \writebetweenlist[chapter]{\blank} + +\stopsectionblockenvironment + +\stopenvironment diff --git a/doc/context/sources/general/manuals/details/details-finetuningfloats.tex b/doc/context/sources/general/manuals/details/details-finetuningfloats.tex new file mode 100644 index 000000000..71e0772d1 --- /dev/null +++ b/doc/context/sources/general/manuals/details/details-finetuningfloats.tex @@ -0,0 +1,657 @@ +% language=uk + +% todo: \setlayeranchored[text-1]{HELLO WORLD} + +\environment details-environment + +\startcomponent details-finetuningfloats + +\startchapter[title={Finetuning graphics}] + +In this chapter we will discuss a few more tricks to control float placement. +This control is needed if you want to typeset documents in a semi desk top +publishing way. + +When you combine technical graphics, you may wish to align the content optically. +This can be done with the \type {offset} command. We will demonstrate this with a +couple of \METAPOST\ graphics: + +\startbuffer +\startreusableMPgraphic{alpha} + fill fullsquare xyscaled( 2cm, 2cm) withcolor \MPcolor{red} ; + fill unitsquare xyscaled(+.5cm,+.5cm) withcolor \MPcolor{gray} ; +\stopreusableMPgraphic + +\startreusableMPgraphic{beta} + fill fullsquare xyscaled( 2cm, 2cm) withcolor \MPcolor{red} ; + fill unitsquare xyscaled(+.5cm,-.5cm) withcolor \MPcolor{gray} ; +\stopreusableMPgraphic + +\startreusableMPgraphic{gamma} + fill fullsquare xyscaled( 2cm, 2cm) withcolor \MPcolor{red} ; + fill unitsquare xyscaled(-.5cm,-.5cm) withcolor \MPcolor{gray} ; +\stopreusableMPgraphic + +\startuseMPgraphic{delta} + fill fullsquare xyscaled( 2cm, 2cm) withcolor \MPcolor{red} ; + fill unitsquare xyscaled(-.5cm,+.5cm) withcolor \MPcolor{gray} ; +\stopuseMPgraphic +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\startcombination[2*2] + {\reuseMPgraphic{alpha}} {alpha} + {\reuseMPgraphic {beta}} {beta} + {\reuseMPgraphic{gamma}} {gamma} + {\reuseMPgraphic{delta}} {delta} +\stopcombination +\stopbuffer + +\typebuffer + +In \in {figure} [fig:offset-1] we place these graphics in a \type {2*2} grid. As +you can see, the centers don't align well. + +\placefigure[here][fig:offset-1]{}{\getbuffer} + +In \in {figure} [fig:offset-2] the centers of the graphic align well. This is +accomplished by adding some space around the graphics. + +\startbuffer +\startcombination[2*2] + {\ruledhbox{\offset[rightoffset=1cm] {\reuseMPgraphic{alpha}}}} {alpha} + {\ruledhbox{\offset[bottomoffset=.5cm]{\reuseMPgraphic {beta}}}} {beta} + {\ruledhbox{\offset[bottomoffset=.5cm]{\reuseMPgraphic{gamma}}}} {gamma} + {\ruledhbox{\offset[leftoffset=1cm] {\reuseMPgraphic{delta}}}} {delta} +\stopcombination +\stopbuffer + +\placefigure[here][fig:offset-2]{}{\getbuffer} + +\starttyping +\startcombination[2*2] + {\offset[rightoffset=1cm] {\reuseMPgraphic{alpha}}} {alpha} + {\offset[bottomoffset=.5cm]{\reuseMPgraphic {beta}}} {beta} + {\offset[bottomoffset=.5cm]{\reuseMPgraphic{gamma}}} {gamma} + {\offset[leftoffset=1cm] {\reuseMPgraphic{delta}}} {delta} +\stopcombination +\stoptyping + +If we align the centers vertically, as demonstrated in \in {figure} +[fig:offset-2] we can stick to a few bottom offsets. + +\starttyping +\startcombination[4*1] + {\reuseMPgraphic{alpha}} {alpha} + {\offset[bottomoffset=.5cm]{\reuseMPgraphic {beta}}} {beta} + {\offset[bottomoffset=.5cm]{\reuseMPgraphic{gamma}}} {gamma} + {\reuseMPgraphic{delta}} {delta} +\stopcombination +\stoptyping + +\startbuffer +\startcombination[4*1] + {\ruledhbox {\reuseMPgraphic{alpha}}} {alpha} + {\ruledhbox{\offset[bottomoffset=.5cm]{\reuseMPgraphic {beta}}}} {beta} + {\ruledhbox{\offset[bottomoffset=.5cm]{\reuseMPgraphic{gamma}}}} {gamma} + {\ruledhbox {\reuseMPgraphic{delta}}} {delta} +\stopcombination +\stopbuffer + +\placefigure[here][fig:offset-3]{}{\getbuffer} + +These examples demonstrate that the dimensions change with the offset. You can +retain the dimensions but still align them by using the \type {x} and \type {y} +parameter. This kind of manipulations will often result in a ugly spacing because +the placement macros handle on the original dimensions. \in {Figure} +[fig:offset-4] demonstrates this. + +\starttyping +\startcombination[4*1] + {\reuseMPgraphic{alpha}} {alpha} + {\offset[y=-.5cm]{\reuseMPgraphic {beta}}} {beta} + {\offset[y=-.5cm]{\reuseMPgraphic{gamma}}} {gamma} + {\reuseMPgraphic{delta}} {delta} +\stopcombination +\stoptyping + +\startbuffer +\startcombination[4*1] + {\ruledhbox {\reuseMPgraphic{alpha}}} {alpha} + {\ruledhbox{\offset[y=-.5cm]{\reuseMPgraphic {beta}}}} {beta} + {\ruledhbox{\offset[y=-.5cm]{\reuseMPgraphic{gamma}}}} {gamma} + {\ruledhbox {\reuseMPgraphic{delta}}} {delta} +\stopcombination +\stopbuffer + +\placefigure[here][fig:offset-4]{}{\getbuffer} + +In the previous chapter we demonstrated how a side float can be moved up or down +by providing a placement directive or by preceding the placement with \type +{\movesidefloat}. Such a move can be used to align a graphic with particular line +of text. This command can also be used for alignment purposes similar to the +\type {\offset} command. We will demonstrate this with the following graphics. + +\startbuffer +\startreusableMPgraphic{gnu} + fill fullsquare xyscaled( 4cm, 1cm) withcolor \MPcolor{red} ; + fill unitsquare xyscaled(-1cm,.5cm) + shifted (0,-.25cm) withcolor \MPcolor{gray} ; +\stopreusableMPgraphic + +\startreusableMPgraphic{gnat} + fill fullsquare xyscaled( 4cm, 1cm) withcolor \MPcolor{red} ; + fill unitsquare xyscaled(+1cm,.5cm) + shifted (0,-.25cm) withcolor \MPcolor{gray} ; +\stopreusableMPgraphic +\stopbuffer + +\typebuffer \getbuffer + +In the next two examples we shift the \type {gnu} and \type {gnat} graphics +horizontally in order to get them aligned. The move does not change the +dimensions of the float, but they do influence the paragraph shape. + +\startbuffer[a] +\movesidefloat [x=.5cm] +\placefigure [left,none] {} {\reuseMPgraphic{gnu}} +\stopbuffer + +\startbuffer[b] +\movesidefloat [x=-.5cm] +\placefigure [left,none] {} {\reuseMPgraphic{gnat}} +\stopbuffer + +\typebuffer[a,b] + +\getbuffer[a] \fakewords{50}{100} +\getbuffer[b] \fakewords{50}{100} + +\blank + +It is possible to shift vertically by setting \type {y}, but this is often a bad +idea and definitely may spoil alignment of graphics to the grid. If you have to +revert to this trick, you are probably working in document screw||up mode. This +is why in grid mode, we automatically round to an equal number of lines. + +If you know what text you're dealing with and also can be sure about the height +of a graphic, you can trick \CONTEXT\ to ignore the dimensions of a graphic. Here +we use the graphic: + +\startbuffer +\startreusableMPgraphic{gnome} + fill fullsquare xyscaled(2cm, 1cm) withcolor \MPcolor{red} ; + fill fullsquare xyscaled(1cm,.5cm) withcolor \MPcolor{gray} ; +\stopreusableMPgraphic +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\placefigure[leftmargin,none,reset]{}{\reuseMPgraphic{gnome}} +\stopbuffer + +\typebuffer \getbuffer + +The graphic is moved into the margin (\type {leftmargin}), has no caption (\type +{none}), and all kind of tricky housekeeping is reset (\type {reset}). + +\startbuffer +\placefigure[left,none,high,low]{}{\reuseMPgraphic{gnome}} +\stopbuffer + +\getbuffer + +Now the next graphic is not influenced by the previous one, so we can place them +close to each other. Use these tricks with care, especially if your document +source is reused and the typeset products are not carefully checked. + +\typebuffer + +When \CONTEXT\ tries to determine if a float fits, it makes a couple of +assumptions, for instance that the available room equals the text height minus +the height of the text so far. You can slightly influence the way these values +are interpreted by setting the calculation method. You can set the methods as +follows: + +\starttyping +\setupfloats[textmethod=0,sidemethod=1] +\stoptyping + +Method~0 just looks at the raw dimensions, while method~1 lessens the maximum +text height by one percent, thereby playing safe. Method~2 takes a window of +1~point. This may lead to better decisions since we may run into rounding errors +of several scaled points (which is small but troublesome). Method~2 is well +suited when typesetting on a grid, because there everything has to fit in a +rounded number of lines, which leaves no room for rounding errors. + +\starttabulate[||c|c|] +\NC \bf grid mode \NC \bf yes \NC \bf no \NC \NR +\NC \type{sidemethod} \NC \type{2} \NC \type{1} \NC \NR +\NC \type{textmethod} \NC \type{2} \NC \type{0} \NC \NR +\stoptabulate + +\startusableMPgraphic{demo-1}{color} + path p ; + p := fullsquare xyscaled (3cm,2LineHeight) ; + fill p withcolor \MPvar{color} ; +\stopusableMPgraphic + +\startusableMPgraphic{demo-2}{color,morecolor} + path p ; p := fullsquare xyscaled (6cm,4LineHeight) ; + path q ; q := fullsquare xyscaled (3cm,2LineHeight) ; + fill p withcolor \MPvar{color} ; + setbounds currentpicture to q ; + fill q withcolor \MPcolor{morecolor} ; +\stopusableMPgraphic + +As you may know by now, we can use the directives \type {high}, \type {low}, +\type {height}, \type {depth} and \type {line} to influence the spacing around a +side float. A real tight spacing can be achieved with \type {fit}. + +\starttyping +\placefigure[left,fit,none]{}{some graphic} +\stoptyping + +\placefigure[left,fit,none]{}{\useMPgraphic{demo-1}{color=red}} + +This kind of placements only make sense in special situations, because normally +you don't want the graphic to touch the text. + +If you think that this is all a user may want, you're wrong. It is not imaginary +that graphics have small pieces sticking out and|/|or lots of white space as part +of their design. In that case, the bounding box can be set to a smaller size. + +\placefigure + [left,fit,none] + {} + {\setlayer + [graphics] + {\useMPgraphic{demo-2}{color=red,morecolor=tgreen}}} + +Now, when handling a side float, \CONTEXT\ first places the float, and then +starts with typesetting the paragraph, cleverly avoiding the graphic. However, +when the graphic is virtually larger than its known size, it may cover part of +the preceding paragraph. + +How come that the graphic starting this paragraph does not do that? It is because +we explicitly moved it to the background. This involves some preparation. At the +document level, we define a layer called \type {graphic}. + +\starttyping +\definelayer[graphics][position=yes] +\stoptyping + +The position directive tells \CONTEXT\ that it should honour the position of the +graphic. Next we must make sure that this layer is placed. + +\starttyping +\setupbackgounds[page][background=graphics] +\stoptyping + +Now we're ready to move graphics to this layer: + +\starttyping +\placefigure + [left,fit,none] + {}{\setlayer[graphics]{graphic}} +\stoptyping + +It's now a small step to more advanced movements. Say that you want to move the +graphic a little bit to the left. In that case you can tell the layer placement +to do so. + +\starttyping +\placefigure + [left,fit,none]{}{\setlayer[graphics][hoffset=-12pt]{graphic}} +\stoptyping + +From this you can deduce that there is also a movement in the vertical direction +using \type {voffset}. In addition you can anchor the graphic using the \type +{location} parameter and provide offsets. + +\placefigure + [left,fit,none] + {} + {\setlayer + [graphics][hoffset=-12pt] + {\useMPgraphic{demo-2}{color=red,morecolor=tgreen}}} + +As soon as you run into situations where float placement is to be consistently +enforced, you will feel the need for dedicate placement macros. For example: + +\startbuffer +\definefloat + [somefloat] + [figure] + +\setupfloat + [somefloat] + [sidespaceafter=, + sidespacebefore=, + default={left,none}] +\stopbuffer + +\typebuffer \getbuffer + +Instead of resetting the side spacing, we could have default to \type {high,low}, +but this way we can overload the default placement and still get zero spacing. + +Throughout this manual we discuss features related to overlays and layers. These +permit you to move content around in ways that either or not depend on the text +flow. We have now come to another trick based on these mechanisms: bleeding. + +When printing a document, you need to take into account that when graphics go +beyond the page boundary, you need to compensate for inaccuracies in cutting the +pages. Such graphics are called bleeding graphics and the amount of bleed is +often a few millimeters. + +The best way to handle such graphics is to use the correct dimensions and play +with the edge widths and distances in combination with backspace and cut space. In +a properly set up layout and by using a well designed set of predefined graphic +placements, you can handle this quite well. A bleeding figure can be defined as +follows: + +\startbuffer +\definefloat + [edgefigure] + [figure] + +\setupfloat + [edgefigure] + [default={inner,height,high,low,none}, + maxwidth=4cm] + +\defineexternalfigure + [edgefigure] + [width=\dimexpr\backspace+4cm-1mm\relax, + lines=4] +\stopbuffer + +\typebuffer \getbuffer + +The default placement is pre|-|configured to have no additional vertical space and +align on the height of a line (this is default behaviour so the \type {height} +key is redundant here. The 1mm in the previous definition simulates what happens +when a page is cut off slightly wrong: we get an annoying gap. + +\startbuffer[a] +\placeedgefigure + {} + {\externalfigure[hacker][edgefigure]} +\stopbuffer + +\typebuffer[a] \getbuffer[a] \fakewords{50}{100} + +One of the nice things about \TEX\ is that you can fine tune dimensions pretty +well. So, instead of the previous placement, which turns out rather ugly, we can +come up with a better one: + +\startbuffer +\setupfloat + [edgefigure] + [default={inner,height,high,low,none}, + maxwidth=4cm, + margin=\strutdepth] + +\defineexternalfigure + [edgefigure] + [width=\dimexpr\backspace+4cm+2mm\relax, + height=\dimexpr3\lineheight+\strutheight\relax] +\stopbuffer + +\typebuffer \getbuffer + +This time we take no risk and add 2mm to the dimensions so that we can be sure +that the edge of the graphic falls outside the page boundary. + +\getbuffer[a] \fakewords{50}{100} + +The \CONTEXT\ resourse library modules provide means to report back the +dimensions of graphics used in a document, so that you can develop (tune) them +with the proper dimensions. In practice a slightly wider than normal graphic +(scaling it horizontally a few millimeters more) does not harm the visual +appearance that much, so adapting a graphic to this kind of bleeding is not +really needed. + +In addition to this (rather natural) way of adding bleed to a graphic, you can +apply the \type {\bleed} macro. In the previously discussed method the figure +placement mechanisms work with the real dimensions. The \type {bleed} macro is +using scaling in a different way: from the perspective of \CONTEXT\ the graphic +remains its original dimensions and the figure placement mechanisms will act +accordingly. We will give a couple of examples of using this macro. + +Permitted bleeding locations are \type {l}, \type {r}, \type {t}, \type {b}, +\type {lr}, \type {bl}, \type {br}, \type {tl} and \type {tr}. + +\startbuffer +\placesomefloat + [left,none,fit] + {} + {\setupbleeding[offset=5mm]% + \bleed[width=5cm,height=1cm,location=l] + {\externalfigure[mill][bleed]}} +\stopbuffer + +\typebuffer \getbuffer \fakewords{50}{100} + +\startbuffer +\placesomefloat + [left,none,fit] + {} + {\setupbleeding[offset=2mm]% + \bleed[width=5cm,height=1cm,location=l] + {\externalfigure[mill][bleed]}} +\stopbuffer + +\typebuffer \getbuffer \fakewords{50}{100} + +The amount of bleeding depends on the postprocessing. In the previous paragraph +we used a bleed offset of 5mm, and here we used 2mm. Because the graphic is +scaled in order to match the bleed, it will be slightly distorted. With small +values this will go unnoticed. You can set the offset with: + +\starttyping +\setupbleeding[offset=5mm] +\stoptyping + +Bleeding itself is accomplished by the \type {\bleed} macro as in: + +\starttyping +\bleed + [width=5cm,height=1cm,location=l] + {\externalfigure[mill][width=\bleedwidth,height=\bleedheight]} +\stoptyping + +It is kind of awkward to pass those two dimensions so here is a shorter way of +doing the same: + +\starttyping +\bleed + [width=5cm,height=1cm,location=l] + {\externalfigure[mill][bleed]} +\stoptyping + +In fact, this uses the following definition: + +\starttyping +\defineexternalfigure[bleed][width=\bleedwidth,height=\bleedheight] +\stoptyping + +You can influence the scaling of a graphic by setting the \type {stretch} +parameters. The location parameter determines the direction of the stretch: \type +{l}~(left), \type {r}~(right), \type {t}~(top), \type {b}~(bottom) or a +combination of these. We will now combine the previous example code with this +knowledge. + +\startbuffer +\placefigure + [left] + {} + {\bleed + [stretch=no,voffset=0pt,hoffset=1cm] + {\externalfigure[detcow][bleed]}} +\stopbuffer + +\typebuffer \getbuffer \fakewords {100} {150} + +\startbuffer +\placefigure + [left] + {} + {\bleed + [width=5cm,height=3cm,location=l] + {\externalfigure[detcow][bleed]}} +\stopbuffer + +\typebuffer \getbuffer \fakewords {100} {150} + +\startbuffer +\placefigure + [right] + {} + {\bleed + [width=5cm,height=3cm,location=r] + {\externalfigure[detcow][bleed]}} +\stopbuffer + +\typebuffer \getbuffer \fakewords {100} {150} + +You can combine this feature with layers. We will now show a few applications +which may look like magic at first glance, but will become natural to your +repertoire once you have played with them. + +The next example moves the graphic to a layer associated with the (current) page. + +\startbuffer +\placefigure + [right,none] + {} + {\setlayer + [graphics] + {\bleed + [width=5cm,height=3cm,location=rb] + {\externalfigure[detcow][bleed]}}} +\stopbuffer + +\typebuffer \getbuffer \fakewords {100} {150} + +You can also predefine locations where graphics (or other content) needs to be +anchored. A direct call to anchor looks as follows: + +\starttyping +\placefigure + [left,none] + {} + {\anchor + [text-1] + [location=lt,hoffset=max,voffset=max] + [width=3cm,height=3cm,frame=on]% + {\externalfigure[detcow][width=5cm,frame=on]}} +\stoptyping + +This will anchor a graphic in one of the text layers, but at the cost of +specifying this in the document source. One way around this is to predefine +anchors. + +\startbuffer +\defineanchor[rightbottom][text-1][location=lt,hoffset=max,voffset=max] +\defineanchor[righttop] [text-1][location=lb,hoffset=max] +\defineanchor[leftbottom] [text-1][location=rt,voffset=max] +\defineanchor[lefttop] [text-1][location=rb] +\stopbuffer + +\startbuffer +\defineanchor[rightbottom][text-1][preset=rightbottom] +\defineanchor[righttop] [text-1][preset=righttop] +\defineanchor[leftbottom] [text-1][preset=leftbottom] +\defineanchor[lefttop] [text-1][preset=lefttop] +\stopbuffer + +\typebuffer \getbuffer + +We will apply this to a predefined float type. + +\startbuffer +\definefloat[myfigure][figure] +\setupfloat[myfigure][sidespaceafter=,sidespacebefore=] +\stopbuffer + +\typebuffer \getbuffer + +Our previous example can now be reduced to: + +\startbuffer +\placemyfigure + [left,none] + {} + {\anchor[rightbottom] + {\externalfigure[detcow][width=5cm,frame=on]}} +\stopbuffer + +\typebuffer \getbuffer \fakewords {100} {150} + +You can still specify dimensions and anchors can be combined with bleeding. Of +course this kind of mixed usage means that you need to have some feeling for what +these mechanisms do. + +\startbuffer +\placemyfigure + [left,none] + {} + {\anchor + [rightbottom] + [width=5cm,height=3cm,frame=on] + {\bleed + [width=5cm,height=3cm,location=l] + {\externalfigure[detcow][bleed]}}} +\stopbuffer + +\typebuffer \getbuffer \fakewords {100} {150} + +\startbuffer +\placemyfigure + [right,none] + {} + {\anchor + [rightbottom] + [width=5cm,height=3cm,frame=on] + {\bleed + [width=5cm,height=3cm,location=r] + {\externalfigure[detcow][bleed]}}} +\stopbuffer + +\typebuffer \getbuffer \fakewords {100} {150} + +\startbuffer +\placemyfigure + [left,none] + {} + {\anchor + [lefttop] + [width=3cm,height=3cm,frame=on] + {\externalfigure[detcow][width=5cm,frame=on]}} +\stopbuffer + +\typebuffer \getbuffer \fakewords {100} {150} + +\startbuffer +\placemyfigure + [left,none] + {} + {\anchor + [lefttop] + [width=3cm,height=3cm,frame=on] + [offset=.5cm] + {\externalfigure[detcow][width=5cm,frame=on]}} +\stopbuffer + +\typebuffer \getbuffer \fakewords {100} {150} + +\blank {\em Todo: parameter specifications of all those macros.} + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/details/details-floatingaround.tex b/doc/context/sources/general/manuals/details/details-floatingaround.tex new file mode 100644 index 000000000..11fe0601c --- /dev/null +++ b/doc/context/sources/general/manuals/details/details-floatingaround.tex @@ -0,0 +1,1137 @@ +% language=uk + +\environment details-environment + +\startcomponent details-floatingaround + +\startchapter[title={Floating around}] + +\index {floats} + +Graphics, tables and alike are often treated as floating bodies. This means that +when such a body does not fit on the current page, it will be moved to the next +one. In the examples we will use figures, but everything we demonstrate here +applies to all floats. + +A side float is a float which placement one way or another depends on the text +that follows it. In its simplest form, the text flows around it, for instance in: + +\startbuffer +\placefigure[left,none]{caption}{\framed[height=1cm]{graphic}} +\stopbuffer + +\typebuffer + +The first keyword of such a call is treated as a placement directive, so this +figure will be placed left. The \type {none} directive nils the caption. + +\getbuffer \fakewords{60}{80} + +When the figure does not fit on the page, a page break is issued. A figure can +span multiple paragraphs. When a next graphic is placed the previous figure will +be padded if needed. First an example of multiple paragraphs. + +\getbuffer \fakewords{30}{40} \par \fakewords{30}{40} + +Multiple floats in a row will lead to padding. The amount of padding is a +combination of empty lines and the normal white space following the float. The +visual quality of the result depends on the graphic itself. + +\start \tracesidefloatstrue + +\getbuffer \fakewords{30}{40} + +\getbuffer \fakewords{30}{40} \fakewords{30}{40} + +\stop + +Here we show the baseline of the first paragraph after the float as well as the +filler. The whitespace around a graphic also depends on the inter|-|paragraph +whitespace. As with many automated mechanisms, compromises are made. A one point +smaller figure may result in an extra empty line. + +Later we will demonstrate a lot of tuning options, but first we give a few more +examples. Most of the tuning options can be driven by keywords as well as +(global) settings. + +\startbuffer +\placefigure + [left,nonumber] + {caption} {\framed[height=1cm]{graphic}} +\stopbuffer + +\typebuffer + +The \type {nonumber} keyword suppresses the label and figure number. You can do +this for all figures with + +\starttyping +\setupcaption[figure][number=no] +\stoptyping + +The previous placement command results in the following side float. + +\getbuffer \fakewords{80}{100} + +Another handy keyword is \type {none}. + +\startbuffer +\placefigure + [left,none]{quoting knuth} + {\framed[height=1cm]{graphic}} +\stopbuffer + +\typebuffer \getbuffer \fakewords{80}{100} + +Control over spacing is exercised by means of the keywords \type {high}, \type +{low} and \type {fit}. + +\startbuffer +\placefigure + [left,none,high]{} + {\framed[height=1cm]{graphic}} +\stopbuffer + +\typebuffer \getbuffer \fakewords{80}{100} + +\startbuffer +\placefigure + [left,none,high,low]{} + {\framed[height=1cm]{graphic}} +\stopbuffer + +\typebuffer \getbuffer \fakewords{80}{100} + +\startbuffer +\placefigure + [left,none,fit]{} + {\framed[height=1cm]{graphic}} +\stopbuffer + +\typebuffer \getbuffer \fakewords{80}{100} + +In the examples so far, we saw additional spacing around the graphic. We will now +(for a while) disable the surrounding whitespace. + +\startbuffer +\setupfloat + [figure] + [sidespacebefore=none, + sidespaceafter=none] +\stopbuffer + +\typebuffer + +With these settings a simple left placement looks as follows. The top of the side +float aligns with the maximum height of a line. + +\start \getbuffer \tracesidefloatstrue + +\startbuffer +\placefigure + [left,none] + {} {\framed[height=1cm]{graphic}} +\stopbuffer + +\typebuffer \getbuffer \fakewords{30}{40} \par \stop + +You can change the alignment by setting the \type {sidealign} variable, for +instance: + +\starttyping +\setupfloat + [figure] + [sidealign=line] +\stoptyping + +The three keywords \type {height}, \type {line} and \type {depth} can also be +passed directly: + +\startbuffer +\placefigure + [left,none,height]{} + {\framed[height=1cm]{graphic}} +\stopbuffer + +\typebuffer + +The three alignments disable the spacing before the float and show up as follows. + +\bgroup \tracesidefloatstrue \getbuffer \fakewords{30}{40} \par \egroup + +\startbuffer +\placefigure + [left,none,line]{} + {\framed[height=1cm]{graphic}} +\stopbuffer + +\bgroup \tracesidefloatstrue \getbuffer \fakewords{30}{40} \par \egroup + +\startbuffer +\placefigure + [left,none,depth]{} + {\framed[height=1cm]{graphic}} +\stopbuffer + +\bgroup \tracesidefloatstrue \getbuffer \fakewords{30}{40} \par \egroup + +So far the floats took up space in the main text body area. In addition to the +\type {left} (or \type {right}) directive we can use \type {inner} or \type +{outer} to force left or right placement depending in the spread. + +Instead of spoiling paper in the text areas, we can use the margin and edges: +\type {leftmargin} and \type {leftedge}, \type {rightmargin} and \type +{rightedge}, but also \type {innermargin} and \type {outermargin}, \type +{inneredge} and \type {outeredge}. + +The next couple of pages we will highlight the margins and edges so that we can +see what happens. + +\setupbackgrounds [text] [leftedge] [background=color] +\setupbackgrounds [text] [rightedge] [background=color] +\setupbackgrounds [text] [leftmargin] [background=color] +\setupbackgrounds [text] [rightmargin] [background=color] + +\startbuffer +\placefigure + [leftmargin,none] + {} {\framed{!}} +\stopbuffer + +\typebuffer \getbuffer \fakewords{30}{40} + +\startbuffer +\placefigure + [leftmargin,none] + {} {\framed[width=1cm]{!}} +\stopbuffer + +\typebuffer \getbuffer \fakewords{30}{40} + +\startbuffer +\placefigure + [leftmargin,none] + {} {\framed[width=1.5cm]{!}} +\stopbuffer + +\typebuffer \getbuffer \fakewords{30}{40} + +The placement directives can be combined with setting distance and width +parameters, thereby not only opening a world of possibilities, but also creating +confusion. Therefore, we will illustrate these features by cloning floats. + +\startbuffer +\definefloat + [marginfigure] + [figure] + +\setupfloat + [marginfigure] + [leftmargindistance=-\leftmargintotal, + default={left,none,low}] +\stopbuffer + +\typebuffer \getbuffer + +The definition command clones figure into a new class of figures. There are two +ways to use such a float : + +\starttyping +\placefloat + [marginfigure] + {} {\framed[width=1.5cm]{!}} +\stoptyping + +or directly: + +\startbuffer +\placemarginfigure + {} {\framed[width=1.5cm]{!}} +\stopbuffer + +\typebuffer + +Both placement calls will result in a figure sticking into the margin. + +\getbuffer \fakewords{30}{40} + +By manipulating the margin distance, you can align graphics to vertical grid +lines, like the edge: + +\startbuffer +\definefloat + [edgefigure] + [figure] + +\setupfloat + [edgefigure] + [leftmargindistance=-\innercombitotal, + default={left,none,low,high}] +\stopbuffer + +\typebuffer \getbuffer + +The \type {\innercombitotal} is one of the many available dimensions. This +measure is the combined width of the margin and edge. + +\startbuffer +\placeedgefigure + {} {\framed[width=1.5cm]{!}} +\stopbuffer + +\typebuffer \getbuffer \fakewords{30}{40} + +\startbuffer +\placeedgefigure + {} {\framed[width=\innercombitotal]{!}} +\stopbuffer + +\typebuffer \getbuffer \fakewords{30}{40} + +You need to be aware of the fact that the margins and edges are not related to +the backspace and cut space settings. When you set up a layout, you need to think +of the right page as starting point. In a double sided layout, the margins are +swapped in the page composition stage. Unless you explicitly go to a left or +right page, you don't know if your left margin will be swapped or not. + +For this reason \CONTEXT\ provides the inner and outer margin|/|edge dimensions. +These are automatically synchronized when the float is constructed. So, if you +want to automatically adapt the float placement and width to the current left +margin in a double sided document, you can use the inner dimensions. + +\starttabulate[||||] +\NC dimension \NC left page + \NC right page \NC\NR +\NC \type{\outermarginwidth} \NC \type{\leftmarginwidth} + \NC \type{\rightmarginwidth} \NC\NR +\NC \type{\innermarginwidth} \NC \type{\rightmarginwidth} + \NC \type{\leftmarginwidth} \NC\NR +\NC \type{\outermargindistance}\NC \type{\leftmargindistance} + \NC \type{\rightmargindistance}\NC\NR +\NC \type{\innermargindistance}\NC \type{\rightmargindistance} + \NC \type{\leftmargindistance} \NC\NR +\stoptabulate + +Similar dimensions are available for the edges. You can save yourself some +calculations by using the following dimensions: + +\starttabulate[|||||] +\NC \type{\leftmargintotal} \NC left margin width \NC + \NC left margin distance \NC\NR +\NC \type{\rightmargintotal} \NC right margin width \NC + \NC right margin distance \NC\NR +\NC \type{\innermargintotal} \NC inner margin width \NC + \NC inner margin distance \NC\NR +\NC \type{\outermargintotal} \NC outer margin width \NC + \NC outer margin distance \NC\NR +\stoptabulate + +As you may expect, the edge totals are available as well, which leave a few more +totals, namely the combinations of margin and edge. + +\starttabulate[|||] +\NC \type{\leftsidetotal} \NC left margin width \NC + \NC left edge total \NC\NR +\NC \type{\rightsidetotal} \NC right margin width \NC + \NC right edge total \NC\NR +\TB +\NC \type{\innersidetotal} \NC inner margin width \NC + \NC inner edge total \NC\NR +\NC \type{\outersidetotal} \NC outer margin width \NC + \NC outer edge total \NC\NR +\TB +\NC \type{\leftcombitotal} \NC left margin total \NC + \NC left edge total \NC\NR +\NC \type{\rightcombitotal} \NC right margin total \NC + \NC right edge total \NC\NR +\TB +\NC \type{\innercombitotal} \NC inner margin total \NC + \NC inner edge total \NC\NR +\NC \type{\outercombitotal} \NC outer margin total \NC + \NC outer edge total \NC\NR +\stoptabulate + +Adaptive back- and cutspace dimensions are also available: + +\starttabulate[|||||] +\NC \type{\innerspacewidth} \NC adaptive backspace \NC\NR +\NC \type{\outerspacewidth} \NC adaptive cutspace \NC\NR +\stoptabulate + +There is one drawback in using the inner and outer dimensions: if you also change +the height of the float dynamically, you may end up in a kind of loop because a +page break may occur at a non||expected place. + +While negative values move float into the margin, positive values will move the +float into the text. It will be of no surprise that you can also set the right +margin distance. Keep in mind that this distance is not related to the text +margin, but to the float margin. + +\startbuffer +\setupfloat + [edgefigure] + [leftmargindistance=-\outercombitotal, + rightmargindistance=-\outercombitotal, + default={outer,none,low,high}] +\stopbuffer + +\typebuffer \getbuffer + +The locations \type {inner} and \type {outer} change with the left or right page. + +\startbuffer +\placeedgefigure + {} {\framed[width=\outercombitotal]{!}} +\stopbuffer + +\typebuffer \getbuffer \fakewords{30}{40} + +\startbuffer +\placeedgefigure + {} {\framed[width=8cm]{!}} +\stopbuffer + +\typebuffer \getbuffer \fakewords{30}{40} + +As a result of manipulating the floats margin settings, the side floats can start +in the margin (or edge). You should not confuse this with margin floats, i.e.\ +side floats that are explicitly placed in the margins. + +\startbuffer +\placefigure[leftmargin,none] + {} {\framed{!}} +\stopbuffer + +\typebuffer \getbuffer \fakewords{30}{40} + +\startbuffer +\placefigure[leftmargin,none] + {} {\framed[width=.5cm]{!}} +\stopbuffer + +\typebuffer \getbuffer \fakewords{30}{40} + +\startbuffer +\placefigure[leftmargin,none] + {} {\framed[width=1.5cm]{!}} +\stopbuffer + +\typebuffer \getbuffer \fakewords{30}{40} + +\startbuffer +\placefigure[leftmargin,none] + {} {\framed[width=5cm]{!}} +\stopbuffer + +\typebuffer \getbuffer \fakewords{30}{40} + +The margin side floats align to the margin and the edge floats to the edge. This +way you can create bleeding figures. + +\startbuffer +\placefigure[leftedge,none] + {} {\framed{!}} +\stopbuffer + +\typebuffer \getbuffer \fakewords{30}{40} + +There are situations where you don't know the dimensions in advance. In order to +prevent unwanted side effects, for instance part of a graphic disappearing +outside the page boundary, \CONTEXT\ provides a few options. The most crude one +is setting the \type {criterium}, as in: + +\starttyping +\setupfloat + [figure] + [criterium=.25\textwidth] +\stoptyping + +This will automatically turn figures that are wider than 25\% of the text width +into normal floats instead of side floats. But let's not fall back on that +feature now. + +You can use \type {maxwidth} and \type {minwidth} variables to control the +placement in more detail. The exact result depends on the settings of \type +{location}. By default we center, but you can set the location to \type {left} or +\type {right} to achieve a different alignment. + +\startbuffer +\definefloat + [midmarginfigure] + [figure] + +\setupfloat + [midmarginfigure] + [minwidth=\leftmarginwidth, + default={leftmargin,none}] +\stopbuffer + +\typebuffer \getbuffer + +You can use \type {maxwidth} and \type {minwidth} variables to control the +placement in more detail. The exact result depends on the settings of \type +{location}. By default we center, but you can set the location to \type {left} or +\type {right} to achieve a different alignment. + +\startbuffer +\placemidmarginfigure + {} {\framed[width=1.5cm]{!}} +\stopbuffer + +\typebuffer \getbuffer \fakewords{30}{40} + +The meaning of \type {maxwidth} depends on the kind of float. First we place a +left float with a width smaller than \type {maxwidth}. + +\start + +\startbuffer +\setupfloat[figure][maxwidth=2cm] +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\placefigure[left,none]{}{\framed[width=1cm]{!}} +\stopbuffer + +\typebuffer \getbuffer \fakewords{30}{40} + +When the width exceeds the maxwidth, the float will be centered. This is because +we have no reference alignment point. + +\startbuffer +\placefigure[left,none]{}{\framed[width=5cm]{!}} +\stopbuffer + +\typebuffer \getbuffer \fakewords{30}{40} + +In margin floats, the \type {maxwidth} settings have a different result. First we +place a small graphic. + +\startbuffer +\setupfloat[figure][maxwidth=\leftmarginwidth] +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\placefigure[leftmargin,none]{}{\framed[width=1cm]{!}} +\stopbuffer + +\typebuffer \getbuffer \fakewords{30}{40} + +Because the left and right margin of this document are the same |<|the edges +differ|>| we don't need to use inner and outer dimensions. + +\startbuffer +\setupfloat[figure][maxwidth=\leftmarginwidth] +\stopbuffer + +\typebuffer \getbuffer + +A wider than \type {maxwidth} graphic will behave like a mixture of a margin and +text side float. Watch how we align the float to the margin. + +\startbuffer +\placefigure[leftmargin,none]{}{\framed[width=5cm]{!}} +\stopbuffer + +\typebuffer \getbuffer \fakewords{30}{40} + +\stop + +Instead of setting the width you can give \type {hanging} a try. The next +examples demonstrate this. + +\startbuffer +\placefigure[leftmargin,hanging,none]{}{\framed[width=5cm]{!}} +\stopbuffer + +\typebuffer \getbuffer \fakewords{30}{40} + +\startbuffer +\placefigure[left,hanging,none]{}{\framed[width=5cm]{!}} +\stopbuffer + +\typebuffer \getbuffer \fakewords{30}{40} + +You can move down|/|up margin floats with the \type {\movesidefloat} macro. Such +shifts come in handy when you have multiple side floats near to each other. + +\startbuffer +\movesidefloat [+2*line] +\placemidmarginfigure {} {\framed{!}} +\stopbuffer + +\typebuffer \getbuffer \fakewords{30}{40} + +Given the default placement template, this is equivalent to the following +command. Watch out, a simple \type {line} has a different effect (alignment). + +\starttyping +\placemidmarginfigure + [leftmargin,none,+2*line] + {} {\framed{!}} +\stoptyping + +Another nice keyword is \type {long}: + +\startbuffer +\placefigure + [leftmargin,none,long] + {} {\framed[height=2cm,width=2cm]{!}} + +Watch how we move down. The effect is that we skip over the margin figure. + +\placefigure + [leftmargin,none] + {} {\framed[height=1cm,width=2cm]{!}} +\stopbuffer + +\typebuffer \getbuffer \fakewords{30}{40} + +\startbuffer +\placefigure + [leftmargin,none] + {} {\framed[height=2cm,width=2cm]{!}} + +Do we clash or not? + +\placefigure + [leftmargin,none] + {} {\framed[height=2cm,width=2cm]{!}} + +Did we clash or not? +\stopbuffer + +\typebuffer \getbuffer + +There are a few macros that can be of help with solving clashes in side floats: + +\starttabulate +\NC \tex {flushsidefloats} \NC + This macro moves down as much as is needed to separate the side floats of + each other. \NC \NR +\NC \tex {forgetsidefloats} \NC + this macro kind of forgets that a side float is in progress. \NC \NR +\stoptabulate + +Use these macros with care. If you change the dimensions of the graphic and|/|or +content involved, reconsider the use of these directives. + +The next couple of spreads we will demonstrate some example definitions. These +placements are taken from one of the styles we made for typesetting a series of +school math books which illustrations and tables all over the pages. + +First we fine tune the spacing around side floats and verbatim text. + +\startbuffer[setupa] +\setupfloats + [sidespacebefore=none, + sidespaceafter=depth] + +\setuptyping + [margin=] +\stopbuffer + +\typebuffer[setupa] + +The placements have rather verbose names. In this case the word \quote {edge} is +used to identify bleeding floats (with an cut||off margin of 3mm). The \quote +{text} floats are side floats positioned in the main text flow. + +\startbuffer[setupb] +\definefloat [marginfigure] [marginfigures] [figure] +\definefloat [middlemarginfigure] [middlemarginfigures] [figure] +\definefloat [middlefigure] [middlefigures] [figure] +\definefloat [textfigure] [textfigures] [figure] +\definefloat [leftfigure] [leftfigures] [figure] +\definefloat [rightfigure] [rightfigures] [figure] +\definefloat [bleedfigure] [bleedfigures] [figure] +\stopbuffer + +\typebuffer[setupa] + +Watch how we define fall backs for too wide content (\type +{criterium} as well as use \type {maxwidth} to manipulate +the placement of content that falls off the margins. + +The black rules are set up with: + +\startbuffer[setupc] +\setupblackrules[color=tred,depth=0pt,height=1.5cm] +\stopbuffer + +\typebuffer[setupc] + +\page[left] + +\startbuffer[series] + +\startbuffer +\setupfloat + [marginfigure] + [criterium=.5\textwidth, + maxwidth=\rightmarginwidth, + default={outermargin,none}] +\stopbuffer + +\getbuffer \typebuffer + +\startbuffer +\placemarginfigure{}{\blackrule[width=.25cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\startbuffer +\placemarginfigure{}{\blackrule[width=.5cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\startbuffer +\placemarginfigure{}{\blackrule[width=1cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\startbuffer +\placemarginfigure{}{\blackrule[width=2cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\startbuffer +\placemarginfigure{}{\blackrule[width=4cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\startbuffer +\placemarginfigure{}{\blackrule[width=8cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\startbuffer +\placemarginfigure{}{\blackrule[width=16cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\stopbuffer + +{\getbuffer[setupa,setupb,setupc,series]} \page +{\getbuffer[setupa,setupb,setupc,series]} \page + +\startbuffer[series] + +\startbuffer +\setupfloat + [middlemarginfigure] + [minwidth=\rightmarginwidth, + criterium=\backspace, + location=middle, + default={outermargin,none}] +\stopbuffer + +\getbuffer \typebuffer + +\startbuffer +\placemiddlemarginfigure{}{\blackrule[width=.25cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\startbuffer +\placemiddlemarginfigure{}{\blackrule[width=.5cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\startbuffer +\placemiddlemarginfigure{}{\blackrule[width=1cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\startbuffer +\placemiddlemarginfigure{}{\blackrule[width=2cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\startbuffer +\placemiddlemarginfigure{}{\blackrule[width=4cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\startbuffer +\placemiddlemarginfigure{}{\blackrule[width=8cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\startbuffer +\placemiddlemarginfigure{}{\blackrule[width=16cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\stopbuffer + +{\getbuffer[setupa,setupb,setupc,series]} \page +{\getbuffer[setupa,setupb,setupc,series]} \page + +\startbuffer[series] + +\startbuffer +\setupfloat + [middlefigure] + [default={here,none}] +\stopbuffer + +\getbuffer \typebuffer + +\startbuffer +\placemiddlefigure{}{\blackrule[width=.25cm]} +\stopbuffer + +\getbuffer \typebuffer + +\startbuffer +\placemiddlefigure{}{\blackrule[width=.5cm]} +\stopbuffer + +\getbuffer \typebuffer + +\startbuffer +\placemiddlefigure{}{\blackrule[width=1cm]} +\stopbuffer + +\getbuffer \typebuffer + +\startbuffer +\placemiddlefigure{}{\blackrule[width=2cm]} +\stopbuffer + +\getbuffer \typebuffer + +\startbuffer +\placemiddlefigure{}{\blackrule[width=4cm]} +\stopbuffer + +\getbuffer \typebuffer + +\startbuffer +\placemiddlefigure{}{\blackrule[width=8cm]} +\stopbuffer + +\getbuffer \typebuffer + +%\startbuffer +%\placemiddlefigure{}{\blackrule[width=16cm]} +%\stopbuffer +% +%\getbuffer \typebuffer + +\stopbuffer + +{\getbuffer[setupa,setupb,setupc,series]} \page +{\getbuffer[setupa,setupb,setupc,series]} \page + +\startbuffer[series] + +\startbuffer +\setupfloat + [textfigure] + [criterium=.5\textwidth, + default={outer,none}] +\stopbuffer + +\getbuffer \typebuffer + +\startbuffer +\placetextfigure{}{\blackrule[width=.25cm]} +\stopbuffer + +\getbuffer \typebuffer + +\startbuffer +\placetextfigure{}{\blackrule[width=.5cm]} +\stopbuffer + +\getbuffer \typebuffer + +\startbuffer +\placetextfigure{}{\blackrule[width=1cm]} +\stopbuffer + +\getbuffer \typebuffer + +\startbuffer +\placetextfigure{}{\blackrule[width=2cm]} +\stopbuffer + +\getbuffer \typebuffer + +\startbuffer +\placetextfigure{}{\blackrule[width=4cm]} +\stopbuffer + +\getbuffer \typebuffer + +\startbuffer +\placetextfigure{}{\blackrule[width=8cm]} +\stopbuffer + +\getbuffer \typebuffer + +\startbuffer +\placetextfigure{}{\blackrule[width=16cm]} +\stopbuffer + +\getbuffer \typebuffer + +\stopbuffer + +{\getbuffer[setupa,setupb,setupc,series]} \page +{\getbuffer[setupa,setupb,setupc,series]} \page + +\startbuffer[series] + +\startbuffer +\setupfloat + [leftfigure] + [criterium=.5\textwidth, + default={left,none}] +\stopbuffer + +\getbuffer \typebuffer + +\startbuffer +\placeleftfigure{}{\blackrule[width=.25cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\startbuffer +\placeleftfigure{}{\blackrule[width=.5cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\startbuffer +\placeleftfigure{}{\blackrule[width=1cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\startbuffer +\placeleftfigure{}{\blackrule[width=2cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\startbuffer +\placeleftfigure{}{\blackrule[width=4cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\startbuffer +\placeleftfigure{}{\blackrule[width=8cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\startbuffer +\placeleftfigure{}{\blackrule[width=16cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\stopbuffer + +{\getbuffer[setupa,setupb,setupc,series]} \page +{\getbuffer[setupa,setupb,setupc,series]} \page + +\startbuffer[series] + +\startbuffer +\setupfloat + [rightfigure] + [criterium=.5\textwidth, + default={right,none}] +\stopbuffer + +\getbuffer \typebuffer + +\startbuffer +\placerightfigure{}{\blackrule[width=.25cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\startbuffer +\placerightfigure{}{\blackrule[width=.5cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\startbuffer +\placerightfigure{}{\blackrule[width=1cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\startbuffer +\placerightfigure{}{\blackrule[width=2cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\startbuffer +\placerightfigure{}{\blackrule[width=4cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\startbuffer +\placerightfigure{}{\blackrule[width=8cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\startbuffer +\placerightfigure{}{\blackrule[width=16cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\stopbuffer + +{\getbuffer[setupa,setupb,setupc,series]} \page +{\getbuffer[setupa,setupb,setupc,series]} \page + +\startbuffer[series] + +\startbuffer +\setupfloat + [bleedfigure] + [criterium=.5\textwidth, + leftmargindistance=-1mm, + rightmargindistance=-1mm, + default={backspace,none}] +\stopbuffer + +\getbuffer \typebuffer + +\startbuffer +\placebleedfigure{}{\blackrule[width=.25cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\startbuffer +\placebleedfigure{}{\blackrule[width=.5cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\startbuffer +\placebleedfigure{}{\blackrule[width=1cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\startbuffer +\placebleedfigure{}{\blackrule[width=2cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\startbuffer +\placebleedfigure{}{\blackrule[width=4cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\startbuffer +\placebleedfigure{}{\blackrule[width=8cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\startbuffer +\placebleedfigure{}{\blackrule[width=16cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\stopbuffer + +{\getbuffer[setupa,setupb,setupc,series]} \page +{\getbuffer[setupa,setupb,setupc,series]} \page + +\startbuffer[series] + +\startbuffer +\setupfloat + [bleedfigure] + [criterium=.5\textwidth, + leftmargindistance=-1mm, + rightmargindistance=-1mm, + default={cutspace,none}] +\stopbuffer + +\getbuffer \typebuffer + +\startbuffer +\placebleedfigure{}{\blackrule[width=.25cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\startbuffer +\placebleedfigure{}{\blackrule[width=.5cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\startbuffer +\placebleedfigure{}{\blackrule[width=1cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\startbuffer +\placebleedfigure{}{\blackrule[width=2cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\startbuffer +\placebleedfigure{}{\blackrule[width=4cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\startbuffer +\placebleedfigure{}{\blackrule[width=8cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\startbuffer +\placebleedfigure{}{\blackrule[width=16cm]} +\stopbuffer + +\getbuffer \typebuffer \flushsidefloats + +\stopbuffer + +{\getbuffer[setupa,setupb,setupc,series]} \page +{\getbuffer[setupa,setupb,setupc,series]} \page + +\page + +\setupbackgrounds [text] [leftedge] [background=] +\setupbackgrounds [text] [rightedge] [background=] +\setupbackgrounds [text] [leftmargin] [background=] +\setupbackgrounds [text] [rightmargin] [background=] + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/details/details-frontpage.tex b/doc/context/sources/general/manuals/details/details-frontpage.tex new file mode 100644 index 000000000..0c7df22f5 --- /dev/null +++ b/doc/context/sources/general/manuals/details/details-frontpage.tex @@ -0,0 +1,43 @@ +% language=uk + +\environment details-environment + +\startcomponent details-frontpage + +\startpagemakeup[doublesided=no,pagestate=stop,page=no] + \startMPcode + StartPage ; + % todo: calculate p[3] from the text dimensions as now it's a gamble + path p[] ; picture q[] ; + p[1] := Page ; + p[2] := Page xscaled .60 shifted (.2PaperWidth,0) ; + p[3] := Page yscaled .22 shifted (0,.69PaperHeight) ; + q[1] := textext.raw("\color[white] {DETAILS}") xsized(.98PaperWidth) ; + q[2] := textext.raw("\color[white] {IT'S IN THE}") xsized(.98PaperWidth) ; + q[3] := textext.raw("\color[twhite]{\tt HANS HAGEN}") xsized(.60PaperWidth) ; + q[4] := textext.raw("\color[twhite]{\tt PRAGMA ADE}") xsized(.60PaperWidth) ; + q[5] := textext.raw("\color[twhite]{\tt HASSELT NL}") xsized(.60PaperWidth) ; + q[2] := q[2] shifted (0,- bbheight(q[2])) ; + q[3] := q[3] shifted (0,+1.5bbheight(q[3])) ; + q[5] := q[5] shifted (0,-1.5bbheight(q[5])) ; + fill p[1] withcolor \MPcolor{blue} ; % .5blue + fill p[2] withcolor \MPcolor{red} ; % .5red + fill p[3] withcolor \MPcolor{gray} withtransparency(1,.5) ; % .6white + draw q[1] shifted (.01PaperWidth,.7PaperHeight) ; + draw q[2] shifted (.01PaperWidth,.9PaperHeight) ; + draw q[3] shifted (.20PaperWidth,.2PaperHeight) ; + draw q[4] shifted (.20PaperWidth,.2PaperHeight) ; + draw q[5] shifted (.20PaperWidth,.2PaperHeight) ; + StopPage ; + \stopMPcode +\stoppagemakeup + +\startpagemakeup[doublesided=no,pagestate=stop,page=no] + \startMPcode + StartPage ; + fill Page withcolor \MPcolor{blue} ; % .5blue ; + StopPage ; + \stopMPcode +\stoppagemakeup + +\stopcomponent diff --git a/doc/context/sources/general/manuals/details/details-gridtrickery.tex b/doc/context/sources/general/manuals/details/details-gridtrickery.tex new file mode 100644 index 000000000..f37c7bd4b --- /dev/null +++ b/doc/context/sources/general/manuals/details/details-gridtrickery.tex @@ -0,0 +1,161 @@ +% language=uk + +\environment details-environment + +\startcomponent details-gridtrickery + +\startchapter[title={Grid trickery}] + +In this manual we pay quite some words on ways to snap your content on a grid. +When dealing with grids, we often run into conflicting situations where we have +to make the best of it. Let's again deal with an aspect of graphics. + +One of the strong points of \TEX\ is that it can deal with graphics +automatically, which means that you seldom have to tweak dimensions or placements +unless \unknown\ you're dealing with grids. In that case you need to make sure +that the height of graphics consistently match the height of lines (or multiples +of lines). It is for this purpose that the graphic inclusion macro has a \type +{grid} entry. + +We will illustrate its usage using a dedicated figure class where we have set the +space between figure and caption to zero. + +\startbuffer +\definefloat[tightfigure][tightfigures][figure] +\setupcaption[tightfigure][inbetween=] +\stopbuffer + +\typebuffer \getbuffer + +The \type {grid} parameter controls rounding of the height of a graphic in the +following way: + +\starttabulate + +\NC \type {yes} \NC safe rounding to an equal number of lines \NC \NR +\NC \type {fit} \NC tight rounding to an equal number of lines \NC \NR +\NC \type {height} \NC same as \type {yes} but incremented by linedepth \NC \NR +\stoptabulate + +On the next pages we demonstrate the effects of these settings. At the bottom of +a page we show the placement commands. On the last pages we've hidden the +captions with: + +\starttyping +\setupfloat[tightfigure][default={here,none}] +\stoptyping + +As you will notice, the \type {height} option is handy when the caption is +positioned directly under the graphic. + +\start \page + +\fakewords{20}{30} \placetightfigure{}{\externalfigure[dummy][width=.5\hsize,lines=1.3,grid=yes]} +\fakewords{20}{30} \placetightfigure{}{\externalfigure[dummy][width=.5\hsize,lines=1.4,grid=yes]} +\fakewords{20}{30} \placetightfigure{}{\externalfigure[dummy][width=.5\hsize,lines=1.5,grid=yes]} +\fakewords{20}{30} \placetightfigure{}{\externalfigure[dummy][width=.5\hsize,lines=1.6,grid=yes]} +\fakewords{20}{30} \placetightfigure{}{\externalfigure[dummy][width=.5\hsize,lines=1.7,grid=yes]} +\fakewords{20}{30} + +\starttyping +\placetightfigure{}{\externalfigure[dummy][lines=1.3,grid=yes]} +\placetightfigure{}{\externalfigure[dummy][lines=1.4,grid=yes]} +\placetightfigure{}{\externalfigure[dummy][lines=1.5,grid=yes]} +\placetightfigure{}{\externalfigure[dummy][lines=1.6,grid=yes]} +\placetightfigure{}{\externalfigure[dummy][lines=1.7,grid=yes]} +\stoptyping + +\page + +\fakewords{20}{30} \placetightfigure{}{\externalfigure[dummy][width=.5\hsize,lines=1.3,grid=fit]} +\fakewords{20}{30} \placetightfigure{}{\externalfigure[dummy][width=.5\hsize,lines=1.4,grid=fit]} +\fakewords{20}{30} \placetightfigure{}{\externalfigure[dummy][width=.5\hsize,lines=1.5,grid=fit]} +\fakewords{20}{30} \placetightfigure{}{\externalfigure[dummy][width=.5\hsize,lines=1.6,grid=fit]} +\fakewords{20}{30} \placetightfigure{}{\externalfigure[dummy][width=.5\hsize,lines=1.7,grid=fit]} +\fakewords{20}{30} + +\starttyping +\placetightfigure{}{\externalfigure[dummy][lines=1.3,grid=fit]} +\placetightfigure{}{\externalfigure[dummy][lines=1.4,grid=fit]} +\placetightfigure{}{\externalfigure[dummy][lines=1.5,grid=fit]} +\placetightfigure{}{\externalfigure[dummy][lines=1.6,grid=fit]} +\placetightfigure{}{\externalfigure[dummy][lines=1.7,grid=fit]} +\stoptyping + +\page + +\fakewords{20}{30} \placetightfigure{}{\externalfigure[dummy][width=.5\hsize,lines=1.3,grid=height]} +\fakewords{20}{30} \placetightfigure{}{\externalfigure[dummy][width=.5\hsize,lines=1.4,grid=height]} +\fakewords{20}{30} \placetightfigure{}{\externalfigure[dummy][width=.5\hsize,lines=1.5,grid=height]} +\fakewords{20}{30} \placetightfigure{}{\externalfigure[dummy][width=.5\hsize,lines=1.6,grid=height]} +\fakewords{20}{30} \placetightfigure{}{\externalfigure[dummy][width=.5\hsize,lines=1.7,grid=height]} +\fakewords{20}{30} + +\starttyping +\placetightfigure{}{\externalfigure[dummy][lines=1.3,grid=height]} +\placetightfigure{}{\externalfigure[dummy][lines=1.4,grid=height]} +\placetightfigure{}{\externalfigure[dummy][lines=1.5,grid=height]} +\placetightfigure{}{\externalfigure[dummy][lines=1.6,grid=height]} +\placetightfigure{}{\externalfigure[dummy][lines=1.7,grid=height]} +\stoptyping + +\page + +\setupfloat[tightfigure][default={here,none}] + +\fakewords{20}{30} \placetightfigure{}{\externalfigure[dummy][width=.5\hsize,lines=1.3,grid=yes]} +\fakewords{20}{30} \placetightfigure{}{\externalfigure[dummy][width=.5\hsize,lines=1.4,grid=yes]} +\fakewords{20}{30} \placetightfigure{}{\externalfigure[dummy][width=.5\hsize,lines=1.5,grid=yes]} +\fakewords{20}{30} \placetightfigure{}{\externalfigure[dummy][width=.5\hsize,lines=1.6,grid=yes]} +\fakewords{20}{30} \placetightfigure{}{\externalfigure[dummy][width=.5\hsize,lines=1.7,grid=yes]} +\fakewords{20}{30} + +\starttyping +\placetightfigure{}{\externalfigure[dummy][lines=1.3,grid=yes]} +\placetightfigure{}{\externalfigure[dummy][lines=1.4,grid=yes]} +\placetightfigure{}{\externalfigure[dummy][lines=1.5,grid=yes]} +\placetightfigure{}{\externalfigure[dummy][lines=1.6,grid=yes]} +\placetightfigure{}{\externalfigure[dummy][lines=1.7,grid=yes]} +\stoptyping + +\page + +\fakewords{20}{30} \placetightfigure{}{\externalfigure[dummy][width=.5\hsize,lines=1.3,grid=fit]} +\fakewords{20}{30} \placetightfigure{}{\externalfigure[dummy][width=.5\hsize,lines=1.4,grid=fit]} +\fakewords{20}{30} \placetightfigure{}{\externalfigure[dummy][width=.5\hsize,lines=1.5,grid=fit]} +\fakewords{20}{30} \placetightfigure{}{\externalfigure[dummy][width=.5\hsize,lines=1.6,grid=fit]} +\fakewords{20}{30} \placetightfigure{}{\externalfigure[dummy][width=.5\hsize,lines=1.7,grid=fit]} +\fakewords{20}{30} + +\starttyping +\placetightfigure{}{\externalfigure[dummy][lines=1.3,grid=fit]} +\placetightfigure{}{\externalfigure[dummy][lines=1.4,grid=fit]} +\placetightfigure{}{\externalfigure[dummy][lines=1.5,grid=fit]} +\placetightfigure{}{\externalfigure[dummy][lines=1.6,grid=fit]} +\placetightfigure{}{\externalfigure[dummy][lines=1.7,grid=fit]} +\stoptyping + +\page + +\fakewords{20}{30} \placetightfigure{}{\externalfigure[dummy][width=.5\hsize,lines=1.3,grid=height]} +\fakewords{20}{30} \placetightfigure{}{\externalfigure[dummy][width=.5\hsize,lines=1.4,grid=height]} +\fakewords{20}{30} \placetightfigure{}{\externalfigure[dummy][width=.5\hsize,lines=1.5,grid=height]} +\fakewords{20}{30} \placetightfigure{}{\externalfigure[dummy][width=.5\hsize,lines=1.6,grid=height]} +\fakewords{20}{30} \placetightfigure{}{\externalfigure[dummy][width=.5\hsize,lines=1.7,grid=height]} +\fakewords{20}{30} + +\starttyping +\placetightfigure{}{\externalfigure[dummy][lines=1.3,grid=height]} +\placetightfigure{}{\externalfigure[dummy][lines=1.4,grid=height]} +\placetightfigure{}{\externalfigure[dummy][lines=1.5,grid=height]} +\placetightfigure{}{\externalfigure[dummy][lines=1.6,grid=height]} +\placetightfigure{}{\externalfigure[dummy][lines=1.7,grid=height]} +\stoptyping + +\page \stop + +\stopchapter + +\page + +\stopcomponent diff --git a/doc/context/sources/general/manuals/details/details-index.tex b/doc/context/sources/general/manuals/details/details-index.tex new file mode 100644 index 000000000..9b6940f0b --- /dev/null +++ b/doc/context/sources/general/manuals/details/details-index.tex @@ -0,0 +1,13 @@ +% language=uk + +\environment details-environment + +\startcomponent details-index + +\startchapter[title={Document index}] + +\placeregister[index] + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/details/details-introduction.tex b/doc/context/sources/general/manuals/details/details-introduction.tex new file mode 100644 index 000000000..8e64ba4ed --- /dev/null +++ b/doc/context/sources/general/manuals/details/details-introduction.tex @@ -0,0 +1,42 @@ +% language=uk + +\startcomponent details-introduction + +\environment details-environment + +\starttitle[title={Introduction}] + +On the \CONTEXT\ mailing list, occasionally a user asks if we can post a complete +document with the associated style. One reason for not honouring this request is +that we want users to cook up their own styles. Besides that, there are a couple +of styles in the regular \CONTEXT\ distribution. + +When browsing through this document, a \CONTEXT\ user may wonder what style was +used to achieve its look and feel. We hope that while reading the text and +playing with the examples, the reader will accomplish the skills to define more +than just simple layouts. + +This document is not easy reading. Occasionally we spend some time explaining +features not described in other manuals. The design of this document is to a +large extent determined by its purpose, and as a result not always functional. +For instance, we typeset on a grid which doesn't look too good. Also the order of +presenting features, tips and tricks is kind of random and unstructured. The idea +is that the visual effects will draw you to the right trick. Also, if you really +want to benefit from these features, there is no way but to read the whole story. + +In spite of all its shortcomings, I hope that you enjoy reading this (yet +unfinished) manual. Keep in mind that this manual is far from finished. + +\blank + +\startlines +Hans Hagen +Hasselt NL +\blank +2002\high{+} MkII +2015\high{+} MkIV +\stoplines + +\stoptitle + +\stopcomponent diff --git a/doc/context/sources/general/manuals/details/details-ornaments.tex b/doc/context/sources/general/manuals/details/details-ornaments.tex new file mode 100644 index 000000000..35d23c8b4 --- /dev/null +++ b/doc/context/sources/general/manuals/details/details-ornaments.tex @@ -0,0 +1,585 @@ +% language=uk + +\environment details-environment + +\startcomponent details-ornaments + +\startchapter[title={Ornaments everywhere}] + +The background mechanisms present in \CONTEXT\ have evolved over time and with +computers becoming faster, you can expect new functionality to show up and +existing functionality to start using this technology. A simple background +consist of a colored area. Many commands accept settings like: + +\starttyping +...[background=color,backgroundcolor=red,backgroundoffset=3pt] +\stoptyping + +Instead of such an area you can define one or more so called +overlays: + +\starttyping +\defineoverlay[one][...] +\defineoverlay[two][...] + +...[background={one,two}] +\stoptyping + +The name overlay comes from the fact that you stack them on top of each other. A +special overlay is \type {foreground}, and deep down in \CONTEXT\ there are more +predefined overlays. + +In the \METAFUN\ manual you will find example of usage, so here we stick to a +simple code snippet for testing this functionality: + +\startbuffer +\defineoverlay[one][\green A] +\defineoverlay[two][\red B] + +\framed[background=one] {1} +\framed[background={one,two}] {1---2} +\stopbuffer + +\typebuffer + +The rather ugly result is: + +\startlinecorrection +\hbox{\getbuffer} +\stoplinecorrection + +You can construct overlays by using \TEX\ boxing primitives or commands like +\type {\framed}. Alternatively you can use another mechanism: layers. Layers +collect content and flush that when asked, for instance when an overlay is +constructed. Layers can be independent of a page, or bound to a specific page +number, left or right hand pages. Here we look at independent layers. + +All these mechanisms are fine tuned for cooperating with the output routine (the +part of \TEX\ that deals with composing pages) and are well interact quite well +with \METAPOST\ graphics. Details of usage and tricks are revealed in this manual +as well as in styles that come with \CONTEXT. In this chapter we will apply +layers to graphics. For this we need a few setups, like: + +\starttyping +\setupbackgrounds + [page] + [background=pagegraphics] +\stoptyping + +Here we have set up the page background to use an overlay called \type +{pagegraphics}. However, instead of an overlay, we will use a layer. This layer +will collect content that goes into the page background. Whenever a layer is +defined, an overlay is automatically defined as well. + +\startbuffer +\definelayer + [pagegraphics] + [x=-2mm, + y=-2mm, + width=\paperwidth, + height=\paperheight] +\stopbuffer + +\typebuffer \getbuffer + +When you fill a layer with content, you can influence the placement with the +\type {x} and \type {y} parameters as well as \type {hoffset} and \type +{voffset}, whichever you prefer. The reference point and alignment are set with +\type {corner} and \type {location}. + +Live can be made easier by using presets, especially for our intended usage. The +following presets are predefined. + +\startbuffer +\definelayerpreset + [lefttop] [corner={left,top}, location={right,bottom}] +\definelayerpreset + [righttop] [corner={right,top}, location={left,bottom}] +\definelayerpreset + [leftbottom] [corner={left,bottom}, location={right,top}] +\definelayerpreset + [rightbottom] [corner={right,bottom},location={left,top}] +\stopbuffer + +\typebuffer \getbuffer + +Because for this layer we have also preset the \type {x} and \type {y}, those +corners are laying a few millimeters outside the page area. We have preset the +size as well, otherwise all corners would end up in the top left corner. + +We will now fill this layer. Because the layer is hooked into the page, it will +be flushed when the page is constructed. After the page is written to the output +file, the layer is emptied, unless its \type {state} is set to \type {repeat}. + +\startbuffer +\setlayer [extras] [preset=lefttop] {\externalfigure[hacker]} +\setlayer [extras] [preset=righttop] {\externalfigure[hacker]} +\setlayer [extras] [preset=leftbottom] {\externalfigure[hacker]} +\setlayer [extras] [preset=rightbottom] {\externalfigure[hacker]} +\stopbuffer + +\testpage[5] \typebuffer \getbuffer + +Once you got the picture of layering, you will start using this mechanism for all +kind of tasks. Instead of putting layers in a background, you can also directly +place them, by using one of the two (equivalent) commands: + +\starttyping +\composedlayer{identifier} +\placelayer[identifier] +\stoptyping + +Layer are quite convenient for defining title pages, colophons, and special +section heads, especially in combination with \type {\framed}. + +On top of the layer mechanism we have build a few more mechanisms, like +ornaments. You can use ornaments to annotate graphics in such a way that the +dimensions stay unchanged. + +\startbuffer +\defineornament + [affiliation] + [rotation=90,corner={right,bottom},location={right,top}, + hoffset=-.25ex] + [frame=on,background=color,backgroundcolor=red,offset=0pt] +\stopbuffer + +\typebuffer \getbuffer + +The negative offset will overlay the text outside the graphic. The meaning of the +sign of coordinates and offsets depends on the corner. \in {Figure} [fig:affi-1] +shows the result. We have put the reference point in the right bottom corner. The +ornament is anchored at the right top corner of the dot you can picture at the +reference point. The ornament is shifted .25ex outwards. + +\starttyping +\placefigure + {} + {\affiliation{graphic}{\externalfigure[hacker][width=3cm]}} +\stoptyping + +\placefigure + [here] [fig:affi-1] {Number 1} + {\affiliation{graphic}{\externalfigure[hacker][width=3cm]}} + +There are two ways to handle the placement. Alternative \type {a} will change the +dimensions of the graphic according to the size of the ornament, while +alternative \type {b} acts as a pure overlay. In \in {figure} [fig:affi-2] the +ornament is not taken into account when calculating the dimensions of the +graphic. This is often the preferred placement, because this way the (often +small) ornament will not it will not spoil visual alignment of similar graphics. + +\startbuffer +\defineornament + [affiliation] + [rotation=90,corner={right,bottom},location={right,top}, + hoffset=-.25ex,alternative=b] + [frame=on,background=color,backgroundcolor=red,offset=0pt] +\stopbuffer + +\typebuffer \getbuffer + +\placefigure + [here] [fig:affi-2] {Number 2} + {\affiliation{graphic}{\externalfigure[hacker][width=3cm]}} + +A positive offset will place the ornament on top of the graphic (see \in {figure} +[fig:affi-3]). + +\startbuffer +\defineornament + [affiliation] + [rotation=90,corner={right,bottom},location={left,top}, + hoffset=.25ex,voffset=.25ex,alternative=a] + [background=color,style=\ss\tfxx,backgroundcolor=white,offset=0pt] +\stopbuffer + +\typebuffer \getbuffer + +\placefigure + [here] [fig:affi-3] {Number 3} + {\affiliation{graphic}{\externalfigure[hacker][width=3cm]}} + +You need to play a bit with this mechanism in order to get a feeling for what the +parameters do. + +\startbuffer +\defineornament + [affiliation] + [rotation=90,corner={right,bottom},location={left,top}, + hoffset=.25ex,voffset=.25ex,alternative=b] + [background=color,style=\ss\tfxx,backgroundcolor=white,offset=0pt] +\stopbuffer + +\typebuffer \getbuffer + +\placefigure + [here] [fig:affi-4] {Number 4} + {\affiliation{graphic}{\externalfigure[hacker][width=3cm]}} + +Because the text is normally typeset quite small, you'd better use a font that +can be scaled down a lot. + +\startbuffer +\definefont[AffiliationFont][Sans sa .25] + +\defineornament + [SomeAffiliation] + [rotation=90,corner={right,bottom},location={right,top}, + hoffset=-.125ex,alternative=b] + [style=AffiliationFont,offset=0pt] +\stopbuffer + +\typebuffer \getbuffer + +This affiliation is used as: + +\startbuffer +\placefigure + {Affiliations normally are typeset pretty small.} + {\SomeAffiliation + {author: Hester De Weert} + {\externalfigure[hacker]}} +\stopbuffer + +\typebuffer \getbuffer + +Ornaments are implemented in terms of layers and collectors. A few examples +demonstrate how these can be used. + +\startbuffer +\layeredtext + [corner={right,bottom},location={left,top}] + [background=color,backgroundcolor=white,offset=0pt] + {graphic} + {\externalfigure[hacker][width=3cm]} +\stopbuffer + +\typebuffer \startlinecorrection \getbuffer \stoplinecorrection + +\startbuffer +\layeredtext + [rotation=90,corner={right,bottom},location={right,top}] + [frame=on,offset=0pt] + {graphic} + {\externalfigure[hacker][width=3cm]} +\stopbuffer + +\typebuffer \startlinecorrection \getbuffer \stoplinecorrection + +\startbuffer +\layeredtext + [rotation=90,corner={left,bottom},location={left,top}] + [frame=on,offset=0pt] + {graphic} + {\externalfigure[hacker][width=3cm]} +\stopbuffer + +\typebuffer \startlinecorrection \getbuffer \stoplinecorrection + +\startbuffer +\collectedtext + [corner={right,bottom},location={left,top}] + [background=color,backgroundcolor=white,offset=0pt] + {graphic} + {\externalfigure[hacker][width=3cm]} +\stopbuffer + +\typebuffer \startlinecorrection \getbuffer \stoplinecorrection + +\startbuffer +\collectedtext + [rotation=90,corner={right,bottom},location={right,top}] + [frame=on,offset=0pt] + {graphic} + {\externalfigure[hacker][width=3cm]} +\stopbuffer + +\typebuffer \startlinecorrection \getbuffer \stoplinecorrection + +\startbuffer +\collectedtext + [rotation=90,corner={left,bottom},location={left,top}] + [frame=on,offset=0pt] + {graphic} + {\externalfigure[hacker][width=3cm]} +\stopbuffer + +\typebuffer \startlinecorrection \getbuffer \stoplinecorrection + +There are several methods to construct title pages, headers, and other +compositions. Of course there are the low level box constructors like \type +{\hbox}, \type {\vbox} and positioning primitives like \type {\hskip}, \type +{\hfill} and alike. + +Another option is to fall back on the low level box macros in the \CONTEXT\ +support file \type {supp-box} or the higher level \type {\framed} macro. You can +use \type {\framed} nested and by cleverly using the offsets and dimensions you +can do a lot. + +Layers are another means. You can or instance construct a title page in the +following way: + +\starttyping +\definelayer + [titlepage] + [width=\textwidth, + height=\textheight] + +\setlayer + [titlepage] + [preset=righttop,location={left,bottom},y=1cm,x=1cm] + {\definedfont[Regular at 60pt]Welcome} + +\setlayer + [titlepage] + [preset=rightbottom,location={right,top},y=2cm,x=2cm] + {\definedfont[Regular at 30pt]By Me} +\stoptyping + +This just fills the layer. Placement is done with: + +\starttyping +\startstandardmakeup + \flushlayer[titlepage] +\stopstandardmakeup +\stoptyping + +or alternatively: + +\starttyping +\setupbackgrounds[text][background=titlepage] +\startstandardmakeup \stopstandardmakeup +\setupbackgrounds[text][background=] +\stoptyping + +Another way to collect content is to use a collector. A collector starts out +empty with: + +\startbuffer +\definecollector[test][state=repeat] +\stopbuffer + +\typebuffer \getbuffer + +We can now stepwise fill this collector. For educational purposes we've turn of +tracing so that you can see what the anchor points. + +\startbuffer +\setcollector[test] + [location={right,bottom}] + {\externalfigure[detcow][frame=on,width=3cm]} +\stopbuffer + +\typebuffer {\traceboxplacementtrue \getbuffer} + +\startlinecorrection[blank] \flushcollector[test] \stoplinecorrection + +\startbuffer +\setcollector[test] + [corner={right,bottom},location={left,top}] + {\framed[background=color,backgroundcolor=tyellow]{this is a cow}} +\stopbuffer + +\typebuffer {\traceboxplacementtrue \getbuffer} + +\startlinecorrection[blank] \flushcollector[test] \stoplinecorrection + +\startbuffer +\setcollector[test] + [corner={right,bottom},location={right,bottom}] + {\framed[background=color,backgroundcolor=tblue]{that's for sure}} +\stopbuffer + +\typebuffer {\traceboxplacementtrue \getbuffer} + +\startlinecorrection[blank] \flushcollector[test] \stoplinecorrection + +\startbuffer +\setcollector[test] + [corner={left,top},location={left,top}] + {\framed[background=color,backgroundcolor=tgreen]{a dutch cow}} +\stopbuffer + +\typebuffer {\traceboxplacementtrue \getbuffer} + +\startlinecorrection[blank] \flushcollector[test] \stoplinecorrection + +\startbuffer +\setcollector[test] + [corner=middle, + location=middle] + {\framed[background=color,backgroundcolor=tred]{nearly done}} +\stopbuffer + +\typebuffer {\traceboxplacementtrue \getbuffer} + +\startlinecorrection[blank] \flushcollector[test] \stoplinecorrection + +In addition to the parameters shown here, you can also provide additional ones: +\type {x}, \type {y}, \type {offset}, \type {hoffset} and \type {voffset} for +positioning and \type {rotation} for (as expected) rotating the content in steps +of 90 degrees. As with layers, the coordinates and offsets can be used +intermixed. + +\startbuffer +\setcollector[test] + [hoffset=4cm, + voffset=-1cm, + corner=middle, + location=middle] + {\framed{now}} +\stopbuffer + +\typebuffer {\traceboxplacementtrue \getbuffer} + +\startlinecorrection[blank] \flushcollector[test] \stoplinecorrection + +We can show the intermediate results because we have set the state of this +collector to repeat. In this case you need to erase the content manually, using: + +\startbuffer +\resetcollector[test] +\stopbuffer + +\typebuffer \getbuffer + +The chapter titles of this document are (as usual in a \CONTEXT\ document) +typeset by the \type {\chapter} macro. When thinking about implementing a non +standard head, those familiar with \CONTEXT's head macros will probably first +think of using one of the hooks, like: + +\starttyping +\setuphead[chapter][command=\MyChapterHead] +\stoptyping + +Here we have followed a different approach. First we set up the chapter head. The +\type {empty} directive instructs \CONTEXT\ not to place the head itself, but +still to include the associated data in the text stream. This means that we will +not see a chapter title, but that there will be an entry in the table of +contents, that references will be set up, that so called marks will be available, +etc. + +\starttyping +\setuphead + [chapter] + [placehead=empty, + header=chapter, + style=\BigText, + numberstyle=\BigNumber] +\stoptyping + +The \type {header} parameters instructs the head handler to mark this page as +special with regards to header texts. This text is set up as follows: + +\starttyping +\definetext + [chapter] + [header] + [\setups{chapter}] + [] +\stoptyping + +The setups are just series of typesetting instructions. For the sake of +readability, we have split them up. + +\starttyping +\startsetups chapter + \setups[chapter:title] + \setups[chapter:number] + \setups[chapter:finish] +\stopsetups +\stoptyping + +The setups will use a dedicated layer for the chapter title: + +\starttyping +\definelayer + [chapter] + [width=\dimexpr\makeupwidth+\cutspace\relax, + height=\headerheight] +\stoptyping + +The following code uses a macro \type {\setlayerframed}. This is a combination +between \type {\setlayer} and \type {\framed}. We use two placement macros to +typeset the title and number. When doing so, we need to take care of both +numbered chapters and unnumbered titles. + +\starttyping +\startsetups chapter:title + + \setlayerframed + [chapter] + [x=\dimexpr\makeupwidth+\cutspace\relax,location={left,bottom}] + [height=\headerheight, + foregroundcolor=white, + background=color, + backgroundcolor=blue, + frame=off, + offset=none, + align={right,lohi}] + {\hbox spread .5\cutspace + {\hss + \doiftextelse{\placeheadtext[chapter]}% + {\placeheadtext[chapter]}% + {\placeheadtext[title]}% + \hss}\space + \vskip.5cm} + +\stopsetups +\stoptyping + +Definitions like these may look complicated but in practice you will construct +them piece|-|wise. + +\starttyping +\startsetups chapter:number + + \setlayerframed + [chapter] + [x=\dimexpr\makeupwidth+\cutspace\relax, + y=\vsize, + location={left,bottom}] + [width=\dimexpr\cutspace-\rightmargindistance\relax, + height=\dimexpr\cutspace-\rightmargindistance\relax, + foregroundcolor=white, + background=color, + backgroundcolor=red, + frame=off, + offset=none, + align={middle,lohi}] + {\hbox to \hsize + {\hskip.5cm\hss + \doifmode{*bodypart}{\placeheadnumber[chapter]}% + \hss}} + +\stopsetups +\stoptyping + +The finishing touch is just a dummy frame with the chapter background. We could +have used the header text background instead. + +\starttyping +\startsetups chapter:finish + + \framed + [width=\makeupwidth, + height=\headerheight, + background=chapter, + frame=off] + {} + +\stopsetups +\stoptyping + +As the title of this manual suggests: it's in the details. Most of our time is +spent in optimizing spacing issues. If you're designing the layout yourself, for +a large part you can fall back on the consistent spacing provided by \TEX, i.e.\ +think in terms of \type {em}'s, \type {ex}'s and fractions or multiples of \type +{\bodyfontsize}, as well as base you're dimensions on those provided by the +layout. When dealing with translating a \DTP\ layout into something \TEX, +definitions like the above will often look more messy. + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/details/details-pseudocolumns.tex b/doc/context/sources/general/manuals/details/details-pseudocolumns.tex new file mode 100644 index 000000000..f30ffaeab --- /dev/null +++ b/doc/context/sources/general/manuals/details/details-pseudocolumns.tex @@ -0,0 +1,155 @@ +% language=uk + +\environment details-environment + +\startcomponent details-pseudocolumns + +\start \page[right] + +\definelayout + [temp] + [columndistance=12pt, + columns=3] + +\setuplayout + [temp] + +\startchapter[title={Pseudo columns}] + +\index {grid snapping+columns} +\index {pseudo columns} +\index {layers} +\index {backgrounds} + +In desk top publishing applications the grid is pretty dominant in defining +layouts. On the other hand, \TEX\ is pretty good defining layouts in terms of +relative dimensions. This means that mapping a desk top publishing layout into +its \TEX\ (or \CONTEXT) counterpart takes some effort. For what it's worth, +personally I don't like grids that much, specially not in complex documents, +unless one makes sure that all elements are suitable sized for the grid used. + +We not only have to deal with vertical grids, but also with horizontal ones. Here +we focus on the second category. When implementing designs, it is best first to +look into the normal page layout areas. For most documents these are sufficient, +but occasionally we need a more detailed approach. + +When playing with grids, you need to make sure that grid snapping is turned on. +It helps if you turn on the grid so that you can see where things end up. When a +horizontal grid is defined, gray vertical rules show their boundaries. + +\starttyping +\setuplayout[grid=yes] \showgrid +\stoptyping + +The \type {\setuplayout} command has a few settings that have to do with so +called pseudo columns. These are in no sense related to multi|-|column +typesetting and only play a role in placing text on specific locations. + +\starttyping +\setuplayout + [columndistance=12pt, + columns=3] +\stoptyping + +You can use \type {\layoutcolumnoffset} for positioning relative to the left +boundary of the running text: + +\startbuffer +\hskip\layoutcolumnoffset{2}{\red Text positioned in column 2!} +\stopbuffer + +\typebuffer \getbuffer + +This mechanism is actually meant to ease the definition of complicated (title) +pages where many text and graphic elements need to be anchored at well defined +places. The layer mechanism is the most natural candidate for this. + +\startbuffer +\definelayer [text] \setupbackgrounds [text] [background=text] +\stopbuffer + +\typebuffer + +When anchoring elements on a layer, you can specify absolute positions using the +\type {x} and \type {y} keys but grid based positioning is possible with the +\type {column} and \type {line} keys. We need to pass \type {grid} as location +specifier. + +\startbuffer +\setlayer[text][column=1,line=48,location=grid]{these are not} +\setlayer[text][column=2,line=47,location=grid]{real columns} +\setlayer[text][column=3,line=48,location=grid]{but fake ones} +\stopbuffer + +\typebuffer \getbuffer + +\page + +\startbuffer +\setlayer [text] [column=1,line=32,location=grid] + {\ruledvtop {\hsize\layoutcolumnwidth + \style[regular:3]{nitty\par gritty}}} + +\setlayer [text] [column=2,line=37,location=grid] + {\ruledvbox {\hsize\layoutcolumnwidth + \style[regular:3]{nitty\par gritty}}} + +\setlayer [text] [column=3,line=42,location=grid] + {\ruledvcenter {\hsize\layoutcolumnwidth + \style[regular:3]{nitty\par gritty}}} +\stopbuffer + +\typebuffer \getbuffer + +The data that goes into the layer is collected and flushed as soon as \TEX\ +builds the page. The buffer associated to the layer is then ready for new data +(for the next page). + +In this example, you can see that the baselines of the boxes (here visualized by +dashed rules) are put at the specified lines. You can use the \TEX\ box commands +\type {\vbox}, \type {\vtop} and \type {\vcenter} to specify where the main +baseline of the box content is positioned (at the top or bottom line, or +centered). + +\startbuffer +\setlayer + [text] + [column=2,line=48,x=\layoutcolumnwidth,location=left] + {\framed + [background=color,backgroundcolor=red, + foregroundstyle=regular:2,foregroundcolor=white, + frame=off] + {Why ain't I framed?}} +\stopbuffer + +\typebuffer \getbuffer + +\page + +On the previous page we demonstrated a more complicated call to \type {\setlayer} +and more features will be introduced in later chapters. We position the framed +text in column~2 and at line~48. In addition we shift the text over the pseudo +column width, i.e. we position the text at the right of the column. The location +specifier aligns the text left from the point of positioning. + +When we have set up the pseudo columns, we have access to a couple of variables: + +\starttabulate[|l|l|l|] +\NC \type {\layoutcolumns} \NC counter \NC number of columns \NC \NR +\NC \type {\layoutlines} \NC counter \NC number of gridlines \NC \NR +\NC \type {\layoutcolumnwidth} \NC dimension \NC width of one column \NC \NR +\NC \type {\layoutcolumnoffset{n}} \NC macro \NC position of column n \NC \NR +\stoptabulate + +This is typically a feature that has been there for quite a while but that I forget +about. It's probably because I never have to use grids myself. + +In the examples before we used some predefined (font) styles: + +\typebuffer[regular:sizes] + +\page \setuplayout[reset] \stop + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/details/details-snappingheads.tex b/doc/context/sources/general/manuals/details/details-snappingheads.tex new file mode 100644 index 000000000..26f4dfbc4 --- /dev/null +++ b/doc/context/sources/general/manuals/details/details-snappingheads.tex @@ -0,0 +1,276 @@ +% language=uk + +\environment details-environment + +\startcomponent details-snappingheads + +\startchapter[title={Snapping heads}] + +The grid snapper in \MKIV\ is quite different from the one in \MKII. For not too +complex layouts the old grid snapper was quite ok, but the new one should be a +bit more robust. In the old situation the running text was assumed to fit on the +grid and the normal baseline skip should do the job in combination with the grid +aware spacing features and placement mechanisms like tables and figures. + +Snapping on a fixed grid is sort of counter intuitive in \TEX\ because it has an a +advanced spacing model with glue. Publishers however love grids so we do need to +support it. Of course when complex layouts are involved in a later stage of +document preparation the grid is often abandoned. This manual uses the grid but I +personally never use the grid. There are better ways to make your document look +good and often a grid snapped document doesn't look that great anyway, because +all elements should somehow fit in multiples of the line height. + +The \MKIV\ snapper does more analysis and therefore can compensate for the more +nasty cases. Of course it can still fail but we hope to fix those cases when we +run into them. Grids are controlled by keywords or a combination of them. + +\starttabulate[|tCT{blue}||] +\NC none \NC don't enlarge \NC \NR +\NC halfline \NC enlarge by halfline/halfline \NC \NR +\NC line \NC enlarge by line/line \NC \NR +\NC strut \NC enlarge by ht/dp (default) \NC \NR +\NC first \NC align to top line \NC \NR +\NC last \NC align to bottom line \NC \NR +\NC mindepth \NC round depth down \NC \NR +\NC maxdepth \NC round depth up \NC \NR +\NC minheight \NC round height down \NC \NR +\NC maxheight \NC round height up \NC \NR +\NC local \NC use local interline space \NC \NR +\NC offset:-3tp \NC vertical shift within box \NC \NR +\NC bottom:lines \NC \NC \NR +\NC top:lines \NC \NC \NR +\NC box \NC centers a box rounded upwards (box:.5 -> tolerance) \NC \NR +\NC min \NC centers a box rounded downwards \NC \NR +\NC max \NC centers a box rounded upwards \NC \NR +\stoptabulate + +We combine these directives in so called grid options: + +\starttyping +\definegridsnapping [normal] [maxheight,maxdepth,strut] +\definegridsnapping [standard] [maxheight,maxdepth,strut] +\definegridsnapping [yes] [maxheight,maxdepth,strut] + +\definegridsnapping [strict] [maxdepth:0.8,maxheight:0.8,strut] +\definegridsnapping [tolerant] [maxdepth:1.2,maxheight:1.2,strut] +\definegridsnapping [math] [maxdepth:1.05,maxheight:1.05,strut] + +\definegridsnapping [top] [minheight,maxdepth,strut] +\definegridsnapping [bottom] [maxheight,mindepth,strut] +\definegridsnapping [both] [minheight,mindepth,strut] + +\definegridsnapping [broad] [maxheight,maxdepth,strut,0.8] +\definegridsnapping [fit] [maxheight,maxdepth,strut,1.2] + +\definegridsnapping [first] [first] +\definegridsnapping [last] [last] +\definegridsnapping [high] [minheight,maxdepth,none] +\definegridsnapping [one] [minheight,mindepth] +\definegridsnapping [low] [maxheight,mindepth,none] +\definegridsnapping [none] [none] +\definegridsnapping [line] [line] +\definegridsnapping [strut] [strut] +\definegridsnapping [box] [box] +\definegridsnapping [min] [min] +\definegridsnapping [max] [max] + +\definegridsnapping [middle] [maxheight,maxdepth] +\stoptyping + +As you can see, keys like \type {maxdepth} can take a criterium as extra detail, +separated by a colon. These options look obscure and often you need to trial and +error a bit to get what you want. This is no real problem because most cases are +handles automatically. Only headings and structuring elements that exceed a +line height might need some treatment. For instance you might want to be more +tolerant for (fractions of) a point overflow or when you know that always a blank +follows you can decide to limit the height of some element to a line. Some of +the options, like \type {math} and \type {middle} are used internally. + +On the next pages we show how the \type {maxheight} and \type {maxdepth} +fractions work on a sample line. + +\page + +\bgroup + \page + \enabledirectives[visualizers.fraction=.5] + \dostepwiserecurse {0} {10} {1} { + \edef\one{\ifnum#1=10 10\else0.#1\fi} + \dostepwiserecurse {0} {10} {1} { + \edef\two{\ifnum##1=10 10\else0.##1\fi} + \definegridsnapping [test:\one:\two][maxdepth:\one,maxheight:\two,strut] + \par + \blackrule[height=1pt,depth=1pt,width=\textwidth,color=green] + \par + \par + \snaptogrid[test:\one:\two] + \ruledhbox{\backgroundline[red]{\white\bf maxdepth:\one,maxheight:\two}} + \par + } + } + \par + \blackrule[height=1pt,depth=1pt,width=\textwidth,color=green] + \par + \page + \enabledirectives[visualizers.fraction] +\egroup + +Next we show some of the options in action. For practical reasons we start a new +page each time. The sample is input as: + +\startbuffer +\bf none \par +\bfb \hskip2cm none \par +\bfd \hskip6cm none \par +\bf test \par +\bfb \hskip2cm test \par +\bfd \hskip6cm test \par +\bf grid \par +\bfb \hskip2cm grid \par +\bfd \hskip6cm grid \par +\bf \strut strut \par +\bfb \hskip2cm \strut strut \par +\bfd \hskip6cm \strut strut \par +\bfb \hskip2cm \setstrut \strut setstrut \par +\bfd \hskip6cm \setstrut \strut setstrut \par +\stopbuffer + +\typebuffer + +\unexpanded\def\SampleGrid#1% + {\page + \section{Grid snapping method \quotation{#1}} + This is just a line to start with but next we % + show what method \type {#1} does. \par + \start + \setuplayout[grid=#1] % the demo value + \showstruts + \getbuffer + \stop + And here we end the demo. + \setuplayout[grid=yes] % the document default + \page} + +\SampleGrid{normal} +\SampleGrid{strict} +\SampleGrid{tolerant} +\SampleGrid{top} +\SampleGrid{bottom} +\SampleGrid{both} +\SampleGrid{broad} +\SampleGrid{fit} +\SampleGrid{first} +\SampleGrid{last} +\SampleGrid{high} +\SampleGrid{one} +\SampleGrid{low} +\SampleGrid{none} +\SampleGrid{line} +\SampleGrid{strut} +\SampleGrid{box} +\SampleGrid{min} +\SampleGrid{max} +\SampleGrid{middle} + +We now come to the topic of this chapter: snapping heads. The problem with +section heads is that they often exceed the line height. Even worse, they can +be more than one line high. + +The next pages show some ways to control snapping around heads. The result can be +confusing, even when we use a font that we assume behaves like a regular style. +For instance in Latin Modern the bold style has larger heights and depths than +the regular style and even 0.1pt can force the snapper to add a line. The +examples use that font. + +The grid option of \type {setuphead} normally takes one keyword that refers to +the local snapper. However, the result gets then snapped again. This is because +the local snapper can use a different line height. Historically the local snapper is +the default but you can force global snapping by prefixing with the \type +{global} keyword. The next table summarizes the ways you can control snapping: + +\starttabulate +\NC \type {(nothing)} \NC local snapping plus global snapping \NC \NR +\NC \type {local} \NC local snapping plus global snapping \NC \NR +\NC \type {foo} \NC local \type {foo} snapping cf.\ font style plus global snapping \NC \NR +\NC \type {local:foo} \NC local \type {foo} snapping cf.\ font style plus global snapping \NC \NR +\NC \type {global} \NC global snapping \NC \NR +\NC \type {global:foo} \NC global \type {foo} snapping \NC \NR +\stoptabulate + +\startbuffer[demo] +\setuppapersize + [A5][A5] + +\setuplayout + [grid=yes, + width=middle, + height=middle, + backspace=1cm, + topspace=2mm, + lines=38, + bottomspace=2mm, + footer=0cm, + header=4mm, + headerdistance=5mm] + +\definehead + [MyHead] + [subsubsubject] + [style=\tf, + textstyle=, + numberstyle=, + before=, + after=] + +\showgrid + +\starttext + +\starttexdefinition TestHead #1 + \page + \setupheadertexts[\type{#1}] + \setuphead[MyHead][grid={#1},style=\tf,interlinespace=] + \MyHead{some head 1.1} + \hskip1cm line following 1.1 + \MyHead{some head 1.2} + \hskip1cm line following 1.2 + \MyHead{some head 1.3a\par some head 1.3b} + \hskip1cm line following 1.3 + \setuphead[MyHead][grid={#1},style=\bf,interlinespace=] + \MyHead{some head 2.1} + \hskip1cm line following 2.1 + \MyHead{some head 2.2} + \hskip1cm line following 2.2 + \MyHead{some head 2.3a\par some head 2.3b} + \hskip1cm line following 2.3 + \setuphead[MyHead][grid=,style=\bf,interlinespace=4ex] + \MyHead{some head 3.1} + \hskip1cm line following 3.1 + \MyHead{some head 3.2} + \hskip1cm line following 3.2 + \MyHead{some head 3.3a\par some head 3.3b} + \hskip1cm line following 3.3 + \setuphead[MyHead][grid={#1},style=\bfb,interlinespace=] + \MyHead{some head 4.1} + \hskip1cm line following 4.1 + \MyHead{some head 4.2} + \hskip1cm line following 4.2 + \page +\stoptexdefinition + +\TestHead{yes} +\TestHead{tolerant} +\TestHead{global:tolerant} + +\stoptext +\stopbuffer + +\typebuffer + +\placefigure[page]{}{\typesetbuffer[demo][page=1,background=color,backgroundcolor=white,width=\textwidth]} +\placefigure[page]{}{\typesetbuffer[demo][page=2,background=color,backgroundcolor=white,width=\textwidth]} +\placefigure[page]{}{\typesetbuffer[demo][page=3,background=color,backgroundcolor=white,width=\textwidth]} + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/details/details-textbackgrounds.tex b/doc/context/sources/general/manuals/details/details-textbackgrounds.tex new file mode 100644 index 000000000..0f3962fff --- /dev/null +++ b/doc/context/sources/general/manuals/details/details-textbackgrounds.tex @@ -0,0 +1,687 @@ +% language=uk + +\environment details-environment + +\startcomponent details-textbackgrounds + +\start \setuphead [chapter] [after=] \startchapter[title={Backgrounds behind text}] + +\startbuffer[setup-a] +\definetextbackground + [intro] + [backgroundcolor=infogray, + backgroundoffset=.25cm, + frame=off, + location=paragraph, + color=red] +\stopbuffer + +\startbuffer[setup-b] +\definetextbackground + [subintro] + [backgroundcolor=textgray, + backgroundoffset=0pt, + frame=off, + location=text, + color=blue] +\stopbuffer + +\startbuffer[demo-a] +\starttextbackground[intro] +A rather common way to draw attention to a passage, is to add a +background. In this chapter we will therefore discuss how to enhance your +document with \starttextbackground [subintro] those colorful areas that either +or not follow the shape of your paragraph. \stoptextbackground\ Be +warned: this chapter has so many backgrounds that you might start to +dislike them. +\stoptextbackground +\stopbuffer + +\getbuffer[setup-a,setup-b,demo-a] + +\blank + +In the previous paragraph we demonstrated two important features of the +background handler: you can nest backgrounds and backgrounds can be tight or +wide. Features like this will often be used in combination with others, like +special section headers. The raw coding of the previous paragraph is therefore +not representative. + +\typebuffer[demo-a] + +The outer background commands is defined as follows: + +\typebuffer[setup-a] + +Here, the \type {paragraph} option ensures that the background covers the width +of the body text. The inner background is defined in a similar way, but this time +we choose \type {text} location. + +\typebuffer[setup-b] + +In this document we use protruding characters (hanging punctuation) so we've +chosen a rather large offset, one that also matches the rest of the page design. + +Those who are familiar with the way \TEX\ works will probably see what problems +can occur with backgrounds like this. What happens for instance when we cross +page boundaries, and how will more complicated paragraph shapes be handled? + +The current implementation tries to handle page breaks and paragraph shapes as +good as possible. This works well in normal one||column mode as well as in +columns. + +\startbuffer[setup-c] +\definetextbackground [A] [backgroundcolor=infogray] +\definetextbackground [B] [backgroundcolor=textgray] + +\setuptextbackground + [backgroundoffset=0pt, + offset=0pt, + frame=off, + location=text] +\stopbuffer + +\getbuffer[setup-c] + +\startbuffer[demo-b] +\placefigure[left]{}{\externalfigure[detcow][width=2cm]} + +\starttextbackground [A] + In this example, the paragraph shape is determined by the graphic placed + left of the text. + \starttextbackground [B] + This feature is implemented using the \type {\hangindent} and \type + {\hangafter} primitives, which means that we need to keep track of + their state. In addition, we need to handle the indentation directives + \type {\leftskip}, \type {\rightskip} and \type {\parindent}. + \stoptextbackground\ + Because backgrounds end up in a different background overlay, nesting + them is no problem, and it is even possible to move them to the front + and back, as we will demonstrate later on. While the mechanism discussed + here will always be improved when we find border cases, the fundaments + it is built upon are quite stable. +\stoptextbackground +\stopbuffer + +{\setupalign[nothanging]\getbuffer[demo-b]\par} + +\typebuffer[demo-b] + +The backgrounds were defined as: + +\typebuffer[setup-c] + +\startbuffer[setup-d] +\setuptextbackground [B] [backgroundcolor=darkgray,level=+2] +\stopbuffer + +{\setupalign[nothanging]\getbuffer[setup-d,demo-b]\par} + +This time we moved the inner background a few levels up. By default they reside +at \type {level=-1}. This way, by using a non transparent color, we can hide +information. + +\typebuffer[setup-d] + +Unless you mess around too much with boxes, backgrounds work as expected in most +situations. According to the Merriam||Webster on the authors laptop: + +\startbuffer +\starttabulate[|l|p|l|] +\NC background \NC \starttextbackground [A] the part of a + painting representing what lies behind objects is the + \starttextbackground [B] foreground \stoptextbackground + \stoptextbackground \NC one \NC \NR +\TB [halfline] +\NC foreground \NC \starttextbackground [A] the part of a + scene or representation that is nearest to and in front + of the \starttextbackground [B] spectator + \stoptextbackground \stoptextbackground \NC two \NC \NR +\TB [halfline] +\NC spectator \NC \starttextbackground [A] one who looks + on or watches \stoptextbackground \NC three \NC \NR +\stoptabulate +\stopbuffer + +\getbuffer + +This is coded similar to normal running text. A table like this is in a way still +part of the text flow. As floating body (see \in {table} [tab:back]) it can +virtually end up everywhere. We add a frame to make clear where the boundaries are. + +\start + + \setupfloat + [table] + [frame=on,framecolor=red,rulethickness=1pt] + + \placetable + [here] [tab:back] + {} {\hsize.75\textwidth\getbuffer} + + \definefloat + [mytable] + [table] + + \setupfloat + [mytable] + [leftmargindistance=-\innermargintotal] + + \placemytable + [left,high,low] + [tab:back-m] + {} + {\hsize.5\textwidth\getbuffer} + + Keeping track of the state of a paragraph in a table in combination with + background is not entirely trivial. The current implementation evolved from + less clever ones and, unless you start doing complicated box manipulations + with the float content, works quite well. One reason why we made backgrounds + work in tables (and especially floating tables) is that is was needed for + typesetting books for primary and secundary education. In there, we want to + be able to hide the answers that students are supposed to fill in. + + \flushsidefloats + +\stop + +In \in {figure} [fig:columns:1] you can see an advanced example of backgrounds +running over columns. If you look carefully, you will notice that the background +depends on the kind of background at hand: + +\startitemize[n,packed] +\item the text starts and flows on +\item the text flows on (or stands alone) +\item the text flows on and ends +\stopitemize + +This information is available when you want to draw your own backgrounds. Here +the graphic was defined as follows: + +\startplacefigure [reference=fig:columns:1] + \startcombination[4*1] + {\externalfigure[back-4.pdf][page=1,width=\distributedhsize\textwidth\emwidth4]}{Page 1} + {\externalfigure[back-4.pdf][page=2,width=\distributedhsize\textwidth\emwidth4]}{Page 2} + {\externalfigure[back-4.pdf][page=3,width=\distributedhsize\textwidth\emwidth4]}{Page 3} + {\externalfigure[back-4.pdf][page=4,width=\distributedhsize\textwidth\emwidth4]}{Page 4} + \stopcombination +\stopplacefigure + +\starttyping +\startuseMPgraphic{mpos:par:color} + for i=1 upto nofmultipars : + fill multipars[i] withcolor + if multikind[i]="single" : "darkgray" ; + elseif multikind[i]="first" : "red" ; + elseif multikind[i]="middle" : "green" ; + elseif multikind[i]="last" : "blue" ; + else : "black" ; + fi ; + endfor ; +\stopuseMPgraphic +\stoptyping + +This graphic is hooked into the background setup by setting the \type {mp} +variable. + +\starttyping +\definetextbackground + [shade] + [location=paragraph, + mp=mpos:par:color, + before=\blank, + after=\blank] +\stoptyping + +A variant is the following. This time we use a shade: + +\starttyping +\startuseMPgraphic{mpos:par:columnset:shade} + numeric h ; + for i=1 upto nofmultipars : + h := bbheight(p) ; + if multikind[i] = "single" : + fill multipars[i] topenlarged -.5h + withshademethod "linear" + withshadedirection shadedup + withcolor boxfillcolor shadedinto .8white ; + fill multipars[i] bottomenlarged -.5h + withshademethod "linear" + withshadedirection shadedup + withcolor .8white shadedinto boxfillcolor ; + elseif multikind[i] = "first" : + fill multipars[i] + withshademethod "linear" + withshadedirection shadedup + withcolor boxfillcolor shadedinto .8white ; + elseif multikind[i] = "middle" : + fill multipars[i] topenlarged -.5h + withshademethod "linear" + withshadedirection shadedup + withcolor boxfillcolor shadedinto .8white ; + fill multipars[i] bottomenlarged -.5h + withshademethod "linear" + withshadedirection shadedup + withcolor .8white shadedinto boxfillcolor ; + elseif multikind[i] = "last" : + fill multipars[i] + withshademethod "linear" + withshadedirection shadedup + withcolor .8white shadedinto boxfillcolor ; + fi ; + endfor ; +\stopuseMPgraphic +\stoptyping + +When we hook it into the background we get \in {figure} [fig:columns:2] as result: + +\starttyping +\definetextbackground + [shade] + [location=paragraph, + backgroundcolor=shadecolor, + mp=mpos:par:columnset:shade, + before=\blank, + after=\blank] +\stoptyping + +\startplacefigure [reference=fig:columns:2] + \startcombination[4*1] + {\externalfigure[back-5.pdf][page=1,width=\distributedhsize\textwidth\emwidth4]}{Page 1} + {\externalfigure[back-5.pdf][page=2,width=\distributedhsize\textwidth\emwidth4]}{Page 2} + {\externalfigure[back-5.pdf][page=3,width=\distributedhsize\textwidth\emwidth4]}{Page 3} + {\externalfigure[back-5.pdf][page=4,width=\distributedhsize\textwidth\emwidth4]}{Page 4} + \stopcombination +\stopplacefigure + +The complexity of the backgrounds mechanism is partly due to the fact that we +want to use arbitrary \METAPOST\ code to render the background. For instance, we +want to have a proper shape so that not only the filled shape but also the drawn +shape comes out right. You can compare this to a glyph in a font: when rendered +filled the outline can be anything as it will not be drawn but when we use the +outline we can run into overlaps and such. Where glyphs can use the odd|-|even +filling methods, background can only use that for simple cases. + +When a background is rectangular it's all quite easy but as soon as some holes +occur we need to do more work. Holes can be the result of a image placed next to +the running text, or an image flushed at a page break or in the middle of a +background. Paragraph shapes are another example. Backgrounds can cross page +boundaries too. Yet another property is nesting and in such cases the shape is +a bit more complex as we cross lines partially. + +In \MKII\ the background mechanism already was quite useable but it had some +limitations. Calculating the background was mostly delegated to \METAPOST\ which +is reasonable. In \MKIV\ some work is delegated to \LUA\ instead but that doesn't +mean that the code is cleaner or easier to understand. So, to summarize, there +are several cases that we need to take into account, like: + +\startitemize + \startitem + A background can run behind a paragraph in which case the start is + leftmost and end rightmost. In this case inserts (like floats) have to be + dealt with after the shape has been calculated. + \stopitem + \startitem + A background can be in|-|line (the \type {text} location variant) in + which case we need to follow the paragraph shape, if set. In that case we + have a mix of calculating the background shape and afterwards + compensating for inserts. + \stopitem + \startitem + A third case is tabulation and tables where we have dedicated regions to + deal with. When these float we need to make sure that the backgrounds are + adapted to the where they end up. + \stopitem + \startitem + Yet another case is in columns, where we hape multiple regions to deal + with. + \stopitem + \startitem + As mentioned, floats need special treatment and they can be part of the + page flow but also end up left or right of the text (either or not + shifted) but also in the margins, edges, back- or cutspace. Their + placement influences the way backgrounds are calculated so additional + information needs to travel with them. + \stopitem + +\stopitemize + +We distinguish between a paragraph background, which runs between the left and right skip +areas and a text background which follows a shape. In \in {figure} [fig:columns:3] we see a +test case with several such shapes. + +\startplacefigure [reference=fig:columns:3] + \startcombination[4*3] + {\externalfigure[back-2.pdf][page=1, width=\distributedhsize\textwidth\emwidth4]}{Page 1} + {\externalfigure[back-2.pdf][page=2, width=\distributedhsize\textwidth\emwidth4]}{Page 2} + {\externalfigure[back-2.pdf][page=3, width=\distributedhsize\textwidth\emwidth4]}{Page 3} + {\externalfigure[back-2.pdf][page=4, width=\distributedhsize\textwidth\emwidth4]}{Page 4} + {\externalfigure[back-2.pdf][page=5, width=\distributedhsize\textwidth\emwidth4]}{Page 5} + {\externalfigure[back-2.pdf][page=6, width=\distributedhsize\textwidth\emwidth4]}{Page 6} + {\externalfigure[back-2.pdf][page=7, width=\distributedhsize\textwidth\emwidth4]}{Page 7} + {\externalfigure[back-2.pdf][page=8, width=\distributedhsize\textwidth\emwidth4]}{Page 8} + {\externalfigure[back-2.pdf][page=9, width=\distributedhsize\textwidth\emwidth4]}{Page 9} + {\externalfigure[back-2.pdf][page=10,width=\distributedhsize\textwidth\emwidth4]}{Page 10} + {\externalfigure[back-2.pdf][page=11,width=\distributedhsize\textwidth\emwidth4]}{Page 11} + {\externalfigure[back-2.pdf][page=12,width=\distributedhsize\textwidth\emwidth4]}{Page 12} + \stopcombination +\stopplacefigure + +In the case of side floats the following cases occur. Of course multiple such +cases can follow each order so in practice we have to deal with an accumulation. + +\startlinecorrection[blank] +\startMPcode + linejoin := linecap := butt ; + + numeric u ; u := 1mm ; + numeric lw ; lw := u/2 ; + + pickup pencircle scaled 2lw ; + + def example (expr n) (text t) (text l) = + path b ; b := boundingbox image ( + for i=t : draw ( 0u,i*2u) -- (20u,i*2u) ; endfor ; + for i=l : draw ( 0u,i*2u) -- (20u,i*2u) ; endfor ; + ) ; + picture p ; p := image ( + for i=t : draw ( 0u,i*2u) -- (20u,i*2u) ; endfor ; + for i=l : draw (11u,i*2u) -- (20u,i*2u) ; endfor ; + ) ; + setbounds p to b ; + path q ; q := unitsquare xysized(10u,10u) shifted (0,4u) ; + draw image ( + fill boundingbox p leftenlarged -lw rightenlarged -lw withcolor "blue" ; + draw p withcolor .5white ; + fill q withcolor "red" ; + draw textext("\bf " & decimal n) shifted (center q) withcolor white ; + ) shifted ((n-1)*30u,0) ; + enddef ; + + example (1) (1) (2,3,4) ; + example (2) (1,8) (2,3,4,5,6,7) ; + example (3) (8) (5,6,7) ; + example (4) () (3,4,5,6) ; + + currentpicture := currentpicture ysized(3*LineHeight- StrutDepth) ; + +\stopMPcode +\stoplinecorrection + +As often in \TEX\ coming up with a solution is not a the problem but interference +is. You can cook up a solution for one case that fails in another. Backgrounds +fall into this category, as do side floats. In the next pages we will demonstrate +a few cases. In practice you can probably always come up with something that +works out well, but in an automated workflow (like unattended \XML\ to \PDF\ +conversion) you can best play safe. We show some examples on the next pages. + +\blank + +\definetextbackground + [demobg] + [backgroundcolor=blue, + color=white, + frame=off, + location=paragraph] + +\setupfloatcaption + [color=black] + +\definesimulatewords + [demo] + [n=50, + m=\simulatewordsparameter{n}, + min=1, + max=5, + color=text, + line=yes, + random=100] + +\startbuffer +\placefigure + [left] + {case 1} + {\blackrule[width=12cm,height=1cm,color=red]} +\simulatewords[demo][n=10] +\starttextbackground[demobg] + \simulatewords[demo][n=30] +\stoptextbackground +\flushsidefloats + +\blank + +\starttextbackground[demobg] + \simulatewords[demo][n=40] + \placefigure + [left] + {case 2} + {\blackrule[width=12cm,height=1cm,color=red]} + \simulatewords[demo][n=40] +\stoptextbackground +\flushsidefloats + +\blank + +\placefigure + [left] + {case 3} + {\blackrule[width=4cm,height=15mm,color=red]} +\starttextbackground[demobg] + \simulatewords[demo][n=40] +\stoptextbackground +\simulatewords[demo][n=40] +\flushsidefloats + +\blank + +\simulatewords[demo][n=35] +\placefigure + [left] + {case 4} + {\blackrule[width=4cm,height=1cm,color=red]} +\simulatewords[demo][n=20] +\starttextbackground[demobg] + \simulatewords[demo][n=25] +\stoptextbackground +\simulatewords[demo][n=40] +\flushsidefloats + +\blank + +\stopbuffer + +\start \setupwhitespace[none] \getbuffer \stop \blank + +The previous examples were typeset with: + +\typebuffer + +Regular (page flow) floats are a different story. Here we have the problem that a +float might be postpones because there is no room on the current page and they +are moved forward (which is why they're called float). Again we show some +examples. + +% \page + +\startbuffer[sample] +One problem introduced by the internet is that one can view music online. Well, +it's actually not really a problem as it is fun to do, but it does interfere with +development of code: one can enter distraction mode quite easily. +\stopbuffer + +\startbuffer +\starttextbackground[demobg] + \par \getbuffer[sample] \par + \placefigure{}{\blackrule[width=4cm,height=1cm,color=red]} + \par \getbuffer[sample] \par + \placefigure{}{\blackrule[width=4cm,height=3cm,color=red]} + \par \getbuffer[sample] \par + \placefigure{}{\blackrule[width=4cm,height=2cm,color=red]} + \par \getbuffer[sample] \par +\stoptextbackground +\stopbuffer + +\blank \getbuffer \blank + +The input is: + +\typebuffer + +A combination of both background avoiding mechanisms is shown on the next page +(we flush a few more grapohics so that we cross a page boundary): + +% \page + +\startbuffer +\starttextbackground[demobg] + \placefigure{}{\blackrule[width=4cm,height=2cm,color=red]} + \par \input ward \par + \placefigure[left]{}{\blackrule[width=4cm,height=2cm,color=red]} + \par \input ward \par + \placefigure{}{\blackrule[width=4cm,height=2cm,color=red]} + \placefigure{}{\blackrule[width=4cm,height=2cm,color=red]} + \placefigure{}{\blackrule[width=4cm,height=2cm,color=red]} + \placefigure{}{\blackrule[width=4cm,height=2cm,color=red]} + \placefigure{}{\blackrule[width=4cm,height=2cm,color=red]} + \placefigure{}{\blackrule[width=4cm,height=2cm,color=red]} + \par \input ward \par + \placefigure{}{\blackrule[width=4cm,height=2cm,color=red]} + \par \input ward \par +\stoptextbackground +\stopbuffer + +\blank \getbuffer \blank + +This is the result from: + +\typebuffer + +You can control the interaction between backgrounds and floars with the \type +{freeregion} parameter. + +\startbuffer +\starttextbackground[demobg] + \simulatewords[demo][n=40] + \startplacefigure + [location=left, + title={free}] + \blackrule[width=12cm,height=1cm,color=red] + \stopplacefigure + \simulatewords[demo][n=40] + \startplacefigure + [location=left, + title={non|-|free}, + freeregion=no, + color=textcolor] + \blackrule[width=12cm,height=1cm,color=red] + \stopplacefigure + \simulatewords[demo][n=40] + \startplacefigure + [location=here, + title={free}] + \blackrule[width=12cm,height=1cm,color=red] + \stopplacefigure + \simulatewords[demo][n=40] + \startplacefigure + [location=here, + title={non|-|free}, + freeregion=no, + color=textcolor] + \blackrule[width=12cm,height=1cm,color=red] + \stopplacefigure + \simulatewords[demo][n=40] +\stoptextbackground +\stopbuffer + +\typebuffer + +The next pages show the result, first with some tracing enabled sop that you +can see what gets freed. This visual effect is enabled with: + +\starttyping +\enabletrackers[floats.freeregion] +\stoptyping + +We now move to the next page. + +\page + \getbuffer +\page + \enabletrackers[floats.freeregion] + \getbuffer + \disabletrackers[floats.freeregion] +\page + +We have some control over side float placement and of course that will interfere +with backgrounds. Say that we have this: + +\startbuffer +\definefloat + [demofigureleft] + [figure] + [default=left, + margin=1cm, + leftmargindistance=2cm, + rightmargindistance=2cm] + +\definefloat + [demofigureright] + [demofigureleft] + [default=right] +\stopbuffer + +\typebuffer \getbuffer + +Combined with the following we get the result on the next pages. + +\startbuffer +\starttextbackground[demobg] + \startplacefloat[figure][location=left] + \blackrule[width=12cm,height=1cm,color=red] + \stopplacefigure + \simulatewords[demo][n=40] + \blank + \startplacefloat[figure][location=right] + \blackrule[width=12cm,height=1cm,color=red] + \stopplacefigure + \simulatewords[demo][n=40] + \blank + \startplacefloat[demofigureleft] + \blackrule[width=10cm,height=1cm,color=red] + \stopplacefigure + \simulatewords[demo][n=40] + \blank + \startplacefloat[demofigureright] + \blackrule[width=10cm,height=1cm,color=red] + \stopplacefigure + \simulatewords[demo][n=40] + \startplacefloat[figure] % [freeregion=no] + \blackrule[width=12cm,height=1cm,color=red] + \stopplacefigure + \simulatewords[demo][n=40] +\stoptextbackground +\stopbuffer + +\typebuffer + +\page + +\start + \enabletrackers[floats.freeregion] + \setupwhitespace[none] + \getbuffer + \disabletrackers[floats.freeregion] +\stop + +\page + +\start + \setupwhitespace[none] + \getbuffer +\stop + +\page + +\stop \stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/details/details-tuningformulas.tex b/doc/context/sources/general/manuals/details/details-tuningformulas.tex new file mode 100644 index 000000000..b36320769 --- /dev/null +++ b/doc/context/sources/general/manuals/details/details-tuningformulas.tex @@ -0,0 +1,212 @@ +% language=uk + +\environment details-environment + +\startcomponent details-tuningformulas + +\startchapter[title={Tuning math formulas}] + +Because of its look and feel, a math formula can look too widely spaced when put +on a grid. There are a few ways to control this. First of all, the default grid +option bound to math is already more tolerant. But you can control it locally +too. Take the following formula: + +\startbuffer +\startformula + a = b^c +\stopformula +\stopbuffer + +\blank \fakeline \getbuffer \fakeline \blank + +This has been entered as: + +\typebuffer + +and because it is just a line of math it comes out as expected. The next code + +\startbuffer +\startformula + a = \frac {a} {b} +\stopformula +\stopbuffer + +\typebuffer + +produces a higher line: + +\blank \fakeline \getbuffer \fakeline \blank + +as does: + +\startbuffer +\startformula + a = \frac {\frac {b} {c}} {\frac {d} {e}} +\stopformula +\stopbuffer + +\typebuffer + +\blank \fakeline \getbuffer \fakeline \blank + +We will now demonstrate three ways to compensate fo rexcessive spacing. The first +variant just sets a grid parameter: + +\startbuffer +\startformula[grid=math:-halfline] + a = \frac {\frac {b} {c}} {\frac {d} {e}} +\stopformula +\stopbuffer + +\typebuffer + +\blank \fakeline \getbuffer \fakeline \blank + +You can also pass this as an option. Only a few such grid related options are +defined: \type {halfline}, \type {line}, \type {-halfline} and \type {-grid}. + +\startbuffer +\startformula[-halfline] + a = \frac {\frac {b} {c}} {\frac {d} {e}} +\stopformula +\stopbuffer + +\typebuffer + +\blank \fakeline \getbuffer \fakeline \blank + +If you need to compensate frequently you can consider defining an instance: + +\startbuffer +\defineformula[tight][grid=math:-halfline] + +\starttightformula + a = \frac {\frac {b} {c}} {\frac {d} {e}} +\stoptightformula +\stopbuffer + +\typebuffer + +\blank \fakeline \getbuffer \fakeline \blank + +The result can be somewhat unexpected at the top and bottom of a page. When we +subtract half a line from the height we can end up above the text area. This is +where the \type {split} directive comes in. So, the compensations are actually +defined as + +\starttabulate[|TCT{blue}|T|] +\NC math \NC \theexpandedsnapperset{math} \NC \NR +\NC math:line \NC \theexpandedsnapperset{math:line} \NC \NR +\NC math:halfline \NC \theexpandedsnapperset{math:halfline} \NC \NR +\NC math:-line \NC \theexpandedsnapperset{math:-line} \NC \NR +\NC math:-halfline \NC \theexpandedsnapperset{math:-halfline} \NC \NR +\stoptabulate + +You can define your own variants building on top of an existing one: + +\starttyping +\definegridsnapping[math:my][math,....] +\stoptyping + +We demonstrate the effect of the \type {split} directive here. It triggers a +check at the page boundaries but you need to keep in mind that this is not always +robust as such boundaries themselves can be triggered by and inject anything. + +\startbuffer[a] +\dorecurse {15} { + \startformula[grid={math,-halfline}] + a = \frac {\frac {b} {c}} {\frac {d} {e}} + (\hbox{top #1 default}) + \stopformula + \blank[samepage] + \fakeline +} +\stopbuffer + +\startbuffer[b] +\dorecurse {15} { + \startformula[grid={math,-halfline,split}] + a = \frac {\frac {b} {c}} {\frac {d} {e}} + (\hbox{top #1 compensated}) + \stopformula + \blank[samepage] + \fakeline +} +\stopbuffer + +\getbuffer[a] +\getbuffer[b] + +As said, the compensation is achieved with the \type {page} directive. The +previous pages were rendered using: + +\typebuffer[a] + +and + +\typebuffer[b] + +In order to get a consistent result we keep the depth of the formula the same but +effectively shift it down a bit, still honouring the grid. So what about the +bottom. + +We can decide that the snapped formula doesn't fit and force a new page but we +can also accept that it sticks out to the bottom, which is less worse than the +top|-|of|-|the|-|page case. + +\startbuffer[a] +\dorecurse{45}{\fakeline} +\startformula[grid={math,-halfline}] + a = \frac {\frac {b} {c}} {\frac {d} {e}} + (\hbox{bottom default}) +\stopformula +\stopbuffer + +\startbuffer[b] +\dorecurse{45}{\fakeline} +\startformula[grid={math,-halfline,split}] + a = \frac {\frac {b} {c}} {\frac {d} {e}} + (\hbox{bottom compensated}) +\stopformula +\stopbuffer + +\page \getbuffer[a] % fits on the page +\page \getbuffer[b] % forces a new page + +These mechanisms might be improved over time but as we don't use it frequently +that might take a while. + +The following formula was posted at the \CONTEXT\ mailing list in a grid snapping +thread and we will use it to demonstrate how you can mess a bit with the +snapping. + +\startbuffer +g(x_{*}) = \lim_{n\to\infty} g(a_{n}) \leq 0 \leq \lim_{n\to\infty} g(b_{n}) = g(x_{*}) +\stopbuffer + +\typebuffer + +We show the given grid parameter as well as its expansion into the low level grid +directives. + +\unexpanded\def\SampleFormula#1% + {\definegridsnapping[math:temp][#1] + \blank + \type{grid=#1} \hfill expanded: \normalexpanded{\type{\theexpandedsnapperset{math:temp}}} + \blank[samepage] + \fakeline + \blank[samepage] + \startformula[grid={#1}] + \getbuffer + \stopformula + \blank[samepage] + \fakeline + \blank} + +\SampleFormula{math} +\SampleFormula{low,halfline} +\SampleFormula{math,nodepth} + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/details/details.tex b/doc/context/sources/general/manuals/details/details.tex new file mode 100644 index 000000000..6319721e5 --- /dev/null +++ b/doc/context/sources/general/manuals/details/details.tex @@ -0,0 +1,50 @@ +% interface=english modes=screen + +% author : Hans Hagen +% copyright : PRAGMA ADE & ConTeXt Development Team +% license : Creative Commons Attribution ShareAlike 4.0 International +% reference : pragma-ade.nl | contextgarden.net | texlive (related) distributions +% origin : the ConTeXt distribution +% +% comment : Because this manual is distributed with TeX distributions it comes with a rather +% liberal license. We try to adapt these documents to upgrades in the (sub)systems +% that they describe. Using parts of the content otherwise can therefore conflict +% with existing functionality and we cannot be held responsible for that. Many of +% the manuals contain characteristic graphics and personal notes or examples that +% make no sense when used out-of-context. +% +% comment : Some chapters might have been published in TugBoat, the NTG Maps, the ConTeXt +% Group journal or otherwise. Thanks to the editors for corrections. Also thanks +% to users for testing, feedback and corrections. + +\startproduct details + +\environment details-environment + +\component details-frontpage + +\startfrontmatter + \component details-introduction + \component details-contents +\stopfrontmatter + +\startbodymatter + \component details-snappingheads + \component details-pseudocolumns + \component details-textbackgrounds + \component details-tuningformulas + \component details-floatingaround + \component details-finetuningfloats + \component details-ornaments + \component details-gridtrickery + \component details-captiontrickery +\stopbodymatter + +\startbackmatter + % \component details-index + \component details-colofon +\stopbackmatter + +\component details-backpage + +\stopproduct diff --git a/doc/context/sources/general/manuals/details/detcow.mp b/doc/context/sources/general/manuals/details/detcow.mp new file mode 100644 index 000000000..18fc570e5 --- /dev/null +++ b/doc/context/sources/general/manuals/details/detcow.mp @@ -0,0 +1,297 @@ +% Converted from PostScript(TM) to MetaPost by pstoedit +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +% MetaPost backend contributed by Scott Pakin <pakin@uiuc.edu> +% pstoedit is Copyright (C) 1993 - 1999 Wolfgang Glunz <wglunz@geocities.com> + +% Generate structured PostScript +prologues := 1; + +% Display a given string with its *baseline* at a given location +% and with a given rotation angle +vardef showtext(expr origin)(expr angle)(expr string) = + draw string infont defaultfont scaled defaultscale + rotated angle shifted origin; +enddef; + +beginfig(1); +drawoptions (withcolor (1,1,1)); +fill (84.3799,618.55)..controls (88.3398,624.38) and (92.5898,622.94)..(96.3398,615.67) + ..controls (101.23,615.6) and (102.46,612.43)..(104.98,610.78) + ..controls (122.62,598.39) and (147.46,607.18)..(167.9,601.92) + ..controls (180.94,598.54) and (190.87,599.76)..(200.09,602.06) + ..controls (220.32,607.25) and (246.1,596.16)..(263.74,603.86) + ..controls (274.75,608.62) and (284.76,605.66)..(292.97,600.91) + ..controls (297.58,597.96) and (299.59,596.09)..(300.96,591.26) + ..controls (306.29,572.54) and (306.29,551.02)..(309.53,530.57) + ..controls (309.53,528.84) and (312.19,526.1)..(312.48,522.07) + ..controls (315.79,511.34) and (316.08,510.12)..(317.16,502.2) + ..controls (317.16,501.34) and (326.52,488.45)..(325.01,479.02) + ..controls (323.93,481.25) and (323.86,482.83)..(321.62,481.68) + ..controls (320.33,479.3) and (320.9,473.9)..(322.56,471.74) + ..controls (320.83,470.81) and (318.46,473.47)..(317.52,475.2) + ..controls (318.17,473.04) and (317.81,470.81)..(316.73,469.3) + ..controls (315.86,472.25) and (316.58,473.18)..(315.36,473.9) + ..controls (313.99,472.9) and (314.21,469.3)..(314.28,466.2) + ..controls (313.49,468.07) and (311.47,472.46)..(312.55,476.42) + ..controls (312.48,484.2) and (308.81,489.1)..(310.32,499.1) + ..controls (310.1,504.43) and (307.3,521.06)..(304.56,524.3) + ..controls (303.12,526.25) and (306.36,510.77)..(306.36,506.16) + ..controls (306.65,500.9) and (307.08,468.72)..(306.43,463.1) + ..controls (306.43,459.22) and (306.22,453.96)..(307.08,452.16) + ..controls (308.74,450.79) and (309.38,450.5)..(309.6,447.98) + ..controls (309.24,446.62) and (308.74,446.04)..(307.73,445.54) + ..controls (306.07,444.6) and (307.37,441.79)..(306.07,439.85) + ..controls (304.49,438.77) and (304.13,441.86)..(303.34,441.86) + ..controls (302.69,441) and (303.05,437.98)..(302.47,436.18) + ..controls (299.66,433.8) and (292.18,432.5)..(289.15,434.66) + ..controls (289.73,440.64) and (291.74,441.58)..(295.63,446.62) + ..controls (298.66,452.59) and (297,460.94)..(296.93,468.14) + ..controls (295.49,480.38) and (289.22,487.3)..(289.44,496.44) + ..controls (287.86,495.72) and (286.42,494.57)..(284.26,494.86) + ..controls (283.39,489.46) and (286.42,484.56)..(284.83,480.82) + ..controls (281.95,471.96) and (277.06,446.62)..(279,437.76) + ..controls (280.01,434.74) and (278.21,433.15)..(277.06,433.94) + ..controls (276.77,433.94) and (276.55,433.94)..(276.41,433.94) + ..controls (276.41,433.94) and (276.55,431.42)..(275.69,430.92) + ..controls (274.1,430.34) and (273.67,431.71)..(272.66,432.14) + ..controls (271.22,430.85) and (272.52,429.48)..(271.15,428.04) + ..controls (267.19,428.04) and (261.36,425.38)..(257.98,428.26) + ..controls (257.33,434.16) and (263.3,436.68)..(266.47,440.71) + ..controls (268.63,446.62) and (271.08,462.89)..(267.77,474.62) + ..controls (267.77,475.56) and (264.38,485.28)..(261.43,488.66) + ..controls (258.7,487.66) and (257.33,485.5)..(253.22,486.29) + ..controls (252.58,484.34) and (253.3,482.33)..(252.22,480.1) + ..controls (251.86,479.52) and (249.34,478.58)..(249.19,481.39) + ..controls (248.98,483.05) and (248.9,486.36)..(248.26,486.72) + ..controls (243.65,486.72) and (233.71,487.08)..(231.77,493.92) + ..controls (219.89,492.34) and (215.93,491.26)..(206.57,493.42) + ..controls (196.63,489.67) and (183.24,506.16)..(174.53,502.2) + ..controls (172.51,496.15) and (173.09,485.64)..(171.65,481.39) + ..controls (169.34,474.77) and (171.14,467.14)..(171.14,456.41) + ..controls (170.57,455.4) and (169.85,454.46)..(168.48,454.46) + ..controls (168.48,453.1) and (169.34,450.86)..(168.62,449.42) + ..controls (167.18,447.62) and (165.89,451.8)..(165.02,444.6) + ..controls (163.15,443.74) and (157.75,442.22)..(155.59,445.18) + ..controls (155.88,448.99) and (158.33,451.3)..(160.13,453.38) + ..controls (161.42,456.91) and (160.99,458.28)..(160.7,461.81) + ..controls (160.99,464.98) and (161.71,468.58)..(161.86,470.09) + ..controls (161.86,473.04) and (162.5,479.3)..(161.14,481.18) + --(159.41,482.69)..controls (157.18,487.22) and (158.33,494.64)..(157.61,500.26) + ..controls (155.81,500.69) and (155.81,500.98)..(154.01,498.31) + ..controls (154.01,494.42) and (153.5,486.36)..(152.35,483.84) + ..controls (149.69,479.81) and (150.84,459.65)..(151.42,448.56) + ..controls (151.78,446.47) and (149.69,447.7)..(149.76,444.74) + ..controls (150.05,442.8) and (147.89,443.59)..(146.09,444.6) + ..controls (145.15,445.18) and (146.59,439.78)..(145.37,439.56) + ..controls (142.34,438.84) and (136.87,438.19)..(135.22,440.71) + ..controls (134.57,444.6) and (137.88,448.06)..(140.62,451.01) + ..controls (143.14,455.83) and (140.9,465.7)..(140.47,476.28) + --(138.89,478.22)..controls (134.86,483.19) and (139.61,496.94)..(136.51,506.23) + ..controls (120.02,514.87) and (122.11,519.19)..(118.73,537.62) + ..controls (115.13,557.64) and (93.3799,567.65)..(79.0598,567.65) + ..controls (73.4399,563.04) and (66.24,563.62)..(58.5398,567.65) + ..controls (55.6599,569.23) and (54.4299,573.19)..(54.5,576.5) + ..controls (52.6299,580.75) and (55.22,582.19)..(59.6199,583.49) + ..controls (62.71,587.81) and (68.6199,594.65)..(69.1899,597.74) + ..controls (70.3398,601.92) and (75.5298,608.11)..(77.7598,609.77) + ..controls (75.8198,613.01) and (74.8098,615.17)..(77.1099,618.55) + ..controls (79.5598,620.14) and (81.7898,616.61)..(84.3799,618.55) + --cycle; +drawoptions (withcolor (0,0,0)); +pickup pencircle scaled 0.636492bp; +draw (84.3799,618.55)..controls (88.3398,624.38) and (92.5898,622.94)..(96.3398,615.67) + ..controls (101.23,615.6) and (102.46,612.43)..(104.98,610.78) + ..controls (122.62,598.39) and (147.46,607.18)..(167.9,601.92) + ..controls (180.94,598.54) and (190.87,599.76)..(200.09,602.06) + ..controls (220.32,607.25) and (246.1,596.16)..(263.74,603.86) + ..controls (274.75,608.62) and (284.76,605.66)..(292.97,600.91) + ..controls (297.58,597.96) and (299.59,596.09)..(300.96,591.26) + ..controls (306.29,572.54) and (306.29,551.02)..(309.53,530.57) + ..controls (309.53,528.84) and (312.19,526.1)..(312.48,522.07) + ..controls (315.79,511.34) and (316.08,510.12)..(317.16,502.2) + ..controls (317.16,501.34) and (326.52,488.45)..(325.01,479.02) + ..controls (323.93,481.25) and (323.86,482.83)..(321.62,481.68) + ..controls (320.33,479.3) and (320.9,473.9)..(322.56,471.74) + ..controls (320.83,470.81) and (318.46,473.47)..(317.52,475.2) + ..controls (318.17,473.04) and (317.81,470.81)..(316.73,469.3) + ..controls (315.86,472.25) and (316.58,473.18)..(315.36,473.9) + ..controls (313.99,472.9) and (314.21,469.3)..(314.28,466.2) + ..controls (313.49,468.07) and (311.47,472.46)..(312.55,476.42) + ..controls (312.48,484.2) and (308.81,489.1)..(310.32,499.1) + ..controls (310.1,504.43) and (307.3,521.06)..(304.56,524.3) + ..controls (303.12,526.25) and (306.36,510.77)..(306.36,506.16) + ..controls (306.65,500.9) and (307.08,468.72)..(306.43,463.1) + ..controls (306.43,459.22) and (306.22,453.96)..(307.08,452.16) + ..controls (308.74,450.79) and (309.38,450.5)..(309.6,447.98) + ..controls (309.24,446.62) and (308.74,446.04)..(307.73,445.54) + ..controls (306.07,444.6) and (307.37,441.79)..(306.07,439.85) + ..controls (304.49,438.77) and (304.13,441.86)..(303.34,441.86) + ..controls (302.69,441) and (303.05,437.98)..(302.47,436.18) + ..controls (299.66,433.8) and (292.18,432.5)..(289.15,434.66) + ..controls (289.73,440.64) and (291.74,441.58)..(295.63,446.62) + ..controls (298.66,452.59) and (297,460.94)..(296.93,468.14) + ..controls (295.49,480.38) and (289.22,487.3)..(289.44,496.44) + ..controls (287.86,495.72) and (286.42,494.57)..(284.26,494.86) + ..controls (283.39,489.46) and (286.42,484.56)..(284.83,480.82) + ..controls (281.95,471.96) and (277.06,446.62)..(279,437.76) + ..controls (280.01,434.74) and (278.21,433.15)..(277.06,433.94) + ..controls (276.77,433.94) and (276.55,433.94)..(276.41,433.94) + ..controls (276.41,433.94) and (276.55,431.42)..(275.69,430.92) + ..controls (274.1,430.34) and (273.67,431.71)..(272.66,432.14) + ..controls (271.22,430.85) and (272.52,429.48)..(271.15,428.04) + ..controls (267.19,428.04) and (261.36,425.38)..(257.98,428.26) + ..controls (257.33,434.16) and (263.3,436.68)..(266.47,440.71) + ..controls (268.63,446.62) and (271.08,462.89)..(267.77,474.62) + ..controls (267.77,475.56) and (264.38,485.28)..(261.43,488.66) + ..controls (258.7,487.66) and (257.33,485.5)..(253.22,486.29) + ..controls (252.58,484.34) and (253.3,482.33)..(252.22,480.1) + ..controls (251.86,479.52) and (249.34,478.58)..(249.19,481.39) + ..controls (248.98,483.05) and (248.9,486.36)..(248.26,486.72) + ..controls (243.65,486.72) and (233.71,487.08)..(231.77,493.92) + ..controls (219.89,492.34) and (215.93,491.26)..(206.57,493.42) + ..controls (196.63,489.67) and (183.24,506.16)..(174.53,502.2) + ..controls (172.51,496.15) and (173.09,485.64)..(171.65,481.39) + ..controls (169.34,474.77) and (171.14,467.14)..(171.14,456.41) + ..controls (170.57,455.4) and (169.85,454.46)..(168.48,454.46) + ..controls (168.48,453.1) and (169.34,450.86)..(168.62,449.42) + ..controls (167.18,447.62) and (165.89,451.8)..(165.02,444.6) + ..controls (163.15,443.74) and (157.75,442.22)..(155.59,445.18) + ..controls (155.88,448.99) and (158.33,451.3)..(160.13,453.38) + ..controls (161.42,456.91) and (160.99,458.28)..(160.7,461.81) + ..controls (160.99,464.98) and (161.71,468.58)..(161.86,470.09) + ..controls (161.86,473.04) and (162.5,479.3)..(161.14,481.18) + --(159.41,482.69)..controls (157.18,487.22) and (158.33,494.64)..(157.61,500.26) + ..controls (155.81,500.69) and (155.81,500.98)..(154.01,498.31) + ..controls (154.01,494.42) and (153.5,486.36)..(152.35,483.84) + ..controls (149.69,479.81) and (150.84,459.65)..(151.42,448.56) + ..controls (151.78,446.47) and (149.69,447.7)..(149.76,444.74) + ..controls (150.05,442.8) and (147.89,443.59)..(146.09,444.6) + ..controls (145.15,445.18) and (146.59,439.78)..(145.37,439.56) + ..controls (142.34,438.84) and (136.87,438.19)..(135.22,440.71) + ..controls (134.57,444.6) and (137.88,448.06)..(140.62,451.01) + ..controls (143.14,455.83) and (140.9,465.7)..(140.47,476.28) + --(138.89,478.22)..controls (134.86,483.19) and (139.61,496.94)..(136.51,506.23) + ..controls (120.02,514.87) and (122.11,519.19)..(118.73,537.62) + ..controls (115.13,557.64) and (93.3799,567.65)..(79.0598,567.65) + ..controls (73.4399,563.04) and (66.24,563.62)..(58.5398,567.65) + ..controls (55.6599,569.23) and (54.4299,573.19)..(54.5,576.5) + ..controls (52.6299,580.75) and (55.22,582.19)..(59.6199,583.49) + ..controls (62.71,587.81) and (68.6199,594.65)..(69.1899,597.74) + ..controls (70.3398,601.92) and (75.5298,608.11)..(77.7598,609.77) + ..controls (75.8198,613.01) and (74.8098,615.17)..(77.1099,618.55) + ..controls (79.5598,620.14) and (81.7898,616.61)..(84.3799,618.55) + --cycle; +pickup pencircle scaled 0bp; +fill (305.28,560.95)..controls (304.63,560.95) and (299.95,561.24)..(299.38,561.24) + ..controls (302.4,550.44) and (303.98,536.47)..(304.2,525.31) + ..controls (303.7,521.35) and (299.81,517.46)..(299.38,525.67) + ..controls (295.85,530.86) and (296.42,540.07)..(293.4,540.29) + ..controls (287.35,539.64) and (285.34,513.22)..(280.01,509.33) + ..controls (276.26,512.28) and (280.73,524.02)..(275.54,524.74) + ..controls (270.5,524.02) and (264.31,526.68)..(266.69,534.46) + ..controls (270.29,543.02) and (268.34,554.76)..(266.54,561.6) + ..controls (262.37,578.59) and (264.02,587.09)..(271.58,596.09) + --(267.48,604.51)..controls (275.4,608.26) and (285.62,604.58)..(290.02,602.21) + ..controls (294.62,600.26) and (300.24,595.94)..(301.1,587.38) + ..controls (303.34,578.88) and (304.42,569.74)..(305.28,560.95) + --cycle; +fill (245.45,600.34)..controls (242.78,599.4) and (239.62,596.02)..(237.67,594.07) + ..controls (236.74,584.42) and (244.58,583.63)..(250.2,577.44) + ..controls (258.77,573.7) and (251.21,567.72)..(256.18,557.42) + ..controls (257.04,550.94) and (257.9,543.89)..(255.31,539.78) + ..controls (249.48,538.92) and (247.97,540.22)..(246.89,531.43) + ..controls (246.31,526.97) and (231.77,529.06)..(229.03,538.27) + ..controls (227.09,544.97) and (221.33,546.7)..(217.8,543.17) + ..controls (213.77,538.06) and (215.78,531.22)..(217.8,527.47) + ..controls (224.93,517.32) and (212.04,511.42)..(205.13,516.74) + ..controls (199.73,508.68) and (211.39,500.04)..(207.43,494.5) + ..controls (205.78,493.99) and (204.77,489.17)..(185.47,500.54) + ..controls (180.36,504.14) and (167.83,500.76)..(168.77,520.63) + ..controls (168.77,525.82) and (165.6,543.53)..(162.14,555.91) + ..controls (159.41,561.24) and (156.74,559.08)..(156.89,553.9) + ..controls (157.18,547.85) and (162.94,531.22)..(155.52,540.22) + ..controls (153.58,539.21) and (156.89,523.58)..(156.89,521.64) + ..controls (162,517.03) and (157.39,513.58)..(154.73,512.28) + ..controls (151.27,518.33) and (149.62,518.04)..(147.17,514.44) + ..controls (141.7,514.08) and (144.58,528.19)..(140.26,528.62) + ..controls (137.02,527.76) and (139.18,520.06)..(138.24,518.76) + ..controls (132.98,524.74) and (130.9,529.27)..(127.01,521.64) + ..controls (126.14,521.64) and (122.11,519.19)..(120.96,526.54) + ..controls (117.65,552.74) and (107.06,558.36)..(93.8198,565.13) + ..controls (92.0198,565.63) and (84.24,566.71)..(79.3398,568.15) + ..controls (73.5098,560.88) and (58.3198,565.63)..(56.23,570.31) + ..controls (54.7898,572.69) and (54.6499,575.21)..(54.7898,576.5) + ..controls (52.3398,580.1) and (55.8699,582.7)..(59.6199,583.06) + ..controls (62.8599,587.16) and (68.5398,594.94)..(71.2798,601.56) + ..controls (72.2898,603.07) and (74.95,609.34)..(78.1899,609.55) + ..controls (74.95,612.94) and (74.2998,622.51)..(82.6599,617.33) + ..controls (87.1199,624.02) and (92.0898,624.31)..(95.7598,615.82) + ..controls (102.89,615.38) and (102.31,608.69)..(115.78,605.52) + ..controls (122.76,602.86) and (132.77,604.58)..(140.26,603.72) + ..controls (136.22,596.88) and (127.44,566.86)..(132.98,559.8) + ..controls (140.76,564.7) and (141.84,605.38)..(157.03,595.66) + ..controls (160.56,593.93) and (159.91,590.04)..(164.09,590.18) + ..controls (170.42,587.45) and (169.13,600.77)..(172.51,600.77) + ..controls (176.47,599.76) and (183.02,599.04)..(186.98,599.54) + ..controls (197.71,600.77) and (206.93,604.08)..(223.92,602.5) + ..controls (231.12,601.78) and (238.25,601.06)..(245.45,600.34) + --cycle; +pickup pencircle scaled 0.636492bp; +draw (305.28,560.95)..controls (304.63,560.95) and (299.95,561.24)..(299.38,561.24) + ..controls (302.4,550.44) and (303.98,536.47)..(304.2,525.31) + ..controls (303.7,521.35) and (299.81,517.46)..(299.38,525.67) + ..controls (295.85,530.86) and (296.42,540.07)..(293.4,540.29) + ..controls (287.35,539.64) and (285.34,513.22)..(280.01,509.33) + ..controls (276.26,512.28) and (280.73,524.02)..(275.54,524.74) + ..controls (270.5,524.02) and (264.31,526.68)..(266.69,534.46) + ..controls (270.29,543.02) and (268.34,554.76)..(266.54,561.6) + ..controls (262.37,578.59) and (264.02,587.09)..(271.58,596.09) + --(267.48,604.51)..controls (275.4,608.26) and (285.62,604.58)..(290.02,602.21) + ..controls (294.62,600.26) and (300.24,595.94)..(301.1,587.38) + ..controls (303.34,578.88) and (304.42,569.74)..(305.28,560.95) + --cycle; +draw (245.45,600.34)..controls (242.78,599.4) and (239.62,596.02)..(237.67,594.07) + ..controls (236.74,584.42) and (244.58,583.63)..(250.2,577.44) + ..controls (258.77,573.7) and (251.21,567.72)..(256.18,557.42) + ..controls (257.04,550.94) and (257.9,543.89)..(255.31,539.78) + ..controls (249.48,538.92) and (247.97,540.22)..(246.89,531.43) + ..controls (246.31,526.97) and (231.77,529.06)..(229.03,538.27) + ..controls (227.09,544.97) and (221.33,546.7)..(217.8,543.17) + ..controls (213.77,538.06) and (215.78,531.22)..(217.8,527.47) + ..controls (224.93,517.32) and (212.04,511.42)..(205.13,516.74) + ..controls (199.73,508.68) and (211.39,500.04)..(207.43,494.5) + ..controls (205.78,493.99) and (204.77,489.17)..(185.47,500.54) + ..controls (180.36,504.14) and (167.83,500.76)..(168.77,520.63) + ..controls (168.77,525.82) and (165.6,543.53)..(162.14,555.91) + ..controls (159.41,561.24) and (156.74,559.08)..(156.89,553.9) + ..controls (157.18,547.85) and (162.94,531.22)..(155.52,540.22) + ..controls (153.58,539.21) and (156.89,523.58)..(156.89,521.64) + ..controls (162,517.03) and (157.39,513.58)..(154.73,512.28) + ..controls (151.27,518.33) and (149.62,518.04)..(147.17,514.44) + ..controls (141.7,514.08) and (144.58,528.19)..(140.26,528.62) + ..controls (137.02,527.76) and (139.18,520.06)..(138.24,518.76) + ..controls (132.98,524.74) and (130.9,529.27)..(127.01,521.64) + ..controls (126.14,521.64) and (122.11,519.19)..(120.96,526.54) + ..controls (117.65,552.74) and (107.06,558.36)..(93.8198,565.13) + ..controls (92.0198,565.63) and (84.24,566.71)..(79.3398,568.15) + ..controls (73.5098,560.88) and (58.3198,565.63)..(56.23,570.31) + ..controls (54.7898,572.69) and (54.6499,575.21)..(54.7898,576.5) + ..controls (52.3398,580.1) and (55.8699,582.7)..(59.6199,583.06) + ..controls (62.8599,587.16) and (68.5398,594.94)..(71.2798,601.56) + ..controls (72.2898,603.07) and (74.95,609.34)..(78.1899,609.55) + ..controls (74.95,612.94) and (74.2998,622.51)..(82.6599,617.33) + ..controls (87.1199,624.02) and (92.0898,624.31)..(95.7598,615.82) + ..controls (102.89,615.38) and (102.31,608.69)..(115.78,605.52) + ..controls (122.76,602.86) and (132.77,604.58)..(140.26,603.72) + ..controls (136.22,596.88) and (127.44,566.86)..(132.98,559.8) + ..controls (140.76,564.7) and (141.84,605.38)..(157.03,595.66) + ..controls (160.56,593.93) and (159.91,590.04)..(164.09,590.18) + ..controls (170.42,587.45) and (169.13,600.77)..(172.51,600.77) + ..controls (176.47,599.76) and (183.02,599.04)..(186.98,599.54) + ..controls (197.71,600.77) and (206.93,604.08)..(223.92,602.5) + ..controls (231.12,601.78) and (238.25,601.06)..(245.45,600.34) + --cycle; +endfig; +end diff --git a/doc/context/sources/general/manuals/details/detcow.tex b/doc/context/sources/general/manuals/details/detcow.tex new file mode 100644 index 000000000..c3698e335 --- /dev/null +++ b/doc/context/sources/general/manuals/details/detcow.tex @@ -0,0 +1,15 @@ +% content=tex +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\setupcolors[state=start] + +\starttext + +\startMPpage + loadfigure "detcow.mp" ; + refill currentpicture withcolor transparent(1,.5,.5red) ; + redraw currentpicture withcolor .5red ; +\stopMPpage + +\stoptext diff --git a/doc/context/sources/general/manuals/details/detcowmp.mps b/doc/context/sources/general/manuals/details/detcowmp.mps new file mode 100644 index 000000000..c5cb7df80 --- /dev/null +++ b/doc/context/sources/general/manuals/details/detcowmp.mps @@ -0,0 +1,295 @@ +%!PS-Adobe-3.0 EPSF-3.0 +%%BoundingBox: 53 426 326 623 +%%Creator: MetaPost +%%CreationDate: 2002.04.10:1235 +%%Pages: 1 +%%EndProlog +%%Page: 1 1 + 1 setgray +newpath 84.3799 618.55 moveto +88.3398 624.38 92.5898 622.94 96.3398 615.67 curveto +101.23 615.6 102.46 612.43 104.98 610.78 curveto +122.62 598.39 147.46 607.18 167.9 601.92 curveto +180.94 598.54 190.87 599.76 200.09 602.06 curveto +220.32 607.25 246.1 596.16 263.74 603.86 curveto +274.75 608.62 284.76 605.66 292.97 600.91 curveto +297.58 597.96 299.59 596.09 300.96 591.26 curveto +306.29 572.54 306.29 551.02 309.53 530.57 curveto +309.53 528.84 312.19 526.1 312.48 522.07 curveto +315.79 511.34 316.08 510.12 317.16 502.2 curveto +317.16 501.34 326.52 488.45 325.01 479.02 curveto +323.93 481.25 323.86 482.83 321.62 481.68 curveto +320.33 479.3 320.9 473.9 322.56 471.74 curveto +320.83 470.81 318.46 473.47 317.52 475.2 curveto +318.17 473.04 317.81 470.81 316.73 469.3 curveto +315.86 472.25 316.58 473.18 315.36 473.9 curveto +313.99 472.9 314.21 469.3 314.28 466.2 curveto +313.49 468.07 311.47 472.46 312.55 476.42 curveto +312.48 484.2 308.81 489.1 310.32 499.1 curveto +310.1 504.43 307.3 521.06 304.56 524.3 curveto +303.12 526.25 306.36 510.77 306.36 506.16 curveto +306.65 500.9 307.08 468.72 306.43 463.1 curveto +306.43 459.22 306.22 453.96 307.08 452.16 curveto +308.74 450.79 309.38 450.5 309.6 447.98 curveto +309.24 446.62 308.74 446.04 307.73 445.54 curveto +306.07 444.6 307.37 441.79 306.07 439.85 curveto +304.49 438.77 304.13 441.86 303.34 441.86 curveto +302.69 441 303.05 437.98 302.47 436.18 curveto +299.66 433.8 292.18 432.5 289.15 434.66 curveto +289.73 440.64 291.74 441.58 295.63 446.62 curveto +298.66 452.59 297 460.94 296.93 468.14 curveto +295.49 480.38 289.22 487.3 289.44 496.44 curveto +287.86 495.72 286.42 494.57 284.26 494.86 curveto +283.39 489.46 286.42 484.56 284.83 480.82 curveto +281.95 471.96 277.06 446.62 279 437.76 curveto +280.01 434.74 278.21 433.15 277.06 433.94 curveto +276.77 433.94 276.55 433.94 276.41 433.94 curveto +276.41 433.94 276.55 431.42 275.69 430.92 curveto +274.1 430.34 273.67 431.71 272.66 432.14 curveto +271.22 430.85 272.52 429.48 271.15 428.04 curveto +267.19 428.04 261.36 425.38 257.98 428.26 curveto +257.33 434.16 263.3 436.68 266.47 440.71 curveto +268.63 446.62 271.08 462.89 267.77 474.62 curveto +267.77 475.56 264.38 485.28 261.43 488.66 curveto +258.7 487.66 257.33 485.5 253.22 486.29 curveto +252.58 484.34 253.3 482.33 252.22 480.1 curveto +251.86 479.52 249.34 478.58 249.19 481.39 curveto +248.98 483.05 248.9 486.36 248.26 486.72 curveto +243.65 486.72 233.71 487.08 231.77 493.92 curveto +219.89 492.34 215.93 491.26 206.57 493.42 curveto +196.63 489.67 183.24 506.16 174.53 502.2 curveto +172.51 496.15 173.09 485.64 171.65 481.39 curveto +169.34 474.77 171.14 467.14 171.14 456.41 curveto +170.57 455.4 169.85 454.46 168.48 454.46 curveto +168.48 453.1 169.34 450.86 168.62 449.42 curveto +167.18 447.62 165.89 451.8 165.02 444.6 curveto +163.15 443.74 157.75 442.22 155.59 445.18 curveto +155.88 448.99 158.33 451.3 160.13 453.38 curveto +161.42 456.91 160.99 458.28 160.7 461.81 curveto +160.99 464.98 161.71 468.58 161.86 470.09 curveto +161.86 473.04 162.5 479.3 161.14 481.18 curveto +159.41 482.69 lineto +157.18 487.22 158.33 494.64 157.61 500.26 curveto +155.81 500.69 155.81 500.98 154.01 498.31 curveto +154.01 494.42 153.5 486.36 152.35 483.84 curveto +149.69 479.81 150.84 459.65 151.42 448.56 curveto +151.78 446.47 149.69 447.7 149.76 444.74 curveto +150.05 442.8 147.89 443.59 146.09 444.6 curveto +145.15 445.18 146.59 439.78 145.37 439.56 curveto +142.34 438.84 136.87 438.19 135.22 440.71 curveto +134.57 444.6 137.88 448.06 140.62 451.01 curveto +143.14 455.83 140.9 465.7 140.47 476.28 curveto +138.89 478.22 lineto +134.86 483.19 139.61 496.94 136.51 506.23 curveto +120.02 514.87 122.11 519.19 118.73 537.62 curveto +115.13 557.64 93.3799 567.65 79.0598 567.65 curveto +73.4399 563.04 66.24 563.62 58.5398 567.65 curveto +55.6599 569.23 54.4299 573.19 54.5 576.5 curveto +52.6299 580.75 55.22 582.19 59.6199 583.49 curveto +62.71 587.81 68.6199 594.65 69.1899 597.74 curveto +70.3398 601.92 75.5298 608.11 77.7598 609.77 curveto +75.8198 613.01 74.8098 615.17 77.1099 618.55 curveto +79.5598 620.14 81.7898 616.61 84.3799 618.55 curveto + closepath fill + 0 setgray 0 0.63649 dtransform truncate idtransform setlinewidth pop [] 0 setdash 1 setlinejoin 10 setmiterlimit +newpath 84.3799 618.55 moveto +88.3398 624.38 92.5898 622.94 96.3398 615.67 curveto +101.23 615.6 102.46 612.43 104.98 610.78 curveto +122.62 598.39 147.46 607.18 167.9 601.92 curveto +180.94 598.54 190.87 599.76 200.09 602.06 curveto +220.32 607.25 246.1 596.16 263.74 603.86 curveto +274.75 608.62 284.76 605.66 292.97 600.91 curveto +297.58 597.96 299.59 596.09 300.96 591.26 curveto +306.29 572.54 306.29 551.02 309.53 530.57 curveto +309.53 528.84 312.19 526.1 312.48 522.07 curveto +315.79 511.34 316.08 510.12 317.16 502.2 curveto +317.16 501.34 326.52 488.45 325.01 479.02 curveto +323.93 481.25 323.86 482.83 321.62 481.68 curveto +320.33 479.3 320.9 473.9 322.56 471.74 curveto +320.83 470.81 318.46 473.47 317.52 475.2 curveto +318.17 473.04 317.81 470.81 316.73 469.3 curveto +315.86 472.25 316.58 473.18 315.36 473.9 curveto +313.99 472.9 314.21 469.3 314.28 466.2 curveto +313.49 468.07 311.47 472.46 312.55 476.42 curveto +312.48 484.2 308.81 489.1 310.32 499.1 curveto +310.1 504.43 307.3 521.06 304.56 524.3 curveto +303.12 526.25 306.36 510.77 306.36 506.16 curveto +306.65 500.9 307.08 468.72 306.43 463.1 curveto +306.43 459.22 306.22 453.96 307.08 452.16 curveto +308.74 450.79 309.38 450.5 309.6 447.98 curveto +309.24 446.62 308.74 446.04 307.73 445.54 curveto +306.07 444.6 307.37 441.79 306.07 439.85 curveto +304.49 438.77 304.13 441.86 303.34 441.86 curveto +302.69 441 303.05 437.98 302.47 436.18 curveto +299.66 433.8 292.18 432.5 289.15 434.66 curveto +289.73 440.64 291.74 441.58 295.63 446.62 curveto +298.66 452.59 297 460.94 296.93 468.14 curveto +295.49 480.38 289.22 487.3 289.44 496.44 curveto +287.86 495.72 286.42 494.57 284.26 494.86 curveto +283.39 489.46 286.42 484.56 284.83 480.82 curveto +281.95 471.96 277.06 446.62 279 437.76 curveto +280.01 434.74 278.21 433.15 277.06 433.94 curveto +276.77 433.94 276.55 433.94 276.41 433.94 curveto +276.41 433.94 276.55 431.42 275.69 430.92 curveto +274.1 430.34 273.67 431.71 272.66 432.14 curveto +271.22 430.85 272.52 429.48 271.15 428.04 curveto +267.19 428.04 261.36 425.38 257.98 428.26 curveto +257.33 434.16 263.3 436.68 266.47 440.71 curveto +268.63 446.62 271.08 462.89 267.77 474.62 curveto +267.77 475.56 264.38 485.28 261.43 488.66 curveto +258.7 487.66 257.33 485.5 253.22 486.29 curveto +252.58 484.34 253.3 482.33 252.22 480.1 curveto +251.86 479.52 249.34 478.58 249.19 481.39 curveto +248.98 483.05 248.9 486.36 248.26 486.72 curveto +243.65 486.72 233.71 487.08 231.77 493.92 curveto +219.89 492.34 215.93 491.26 206.57 493.42 curveto +196.63 489.67 183.24 506.16 174.53 502.2 curveto +172.51 496.15 173.09 485.64 171.65 481.39 curveto +169.34 474.77 171.14 467.14 171.14 456.41 curveto +170.57 455.4 169.85 454.46 168.48 454.46 curveto +168.48 453.1 169.34 450.86 168.62 449.42 curveto +167.18 447.62 165.89 451.8 165.02 444.6 curveto +163.15 443.74 157.75 442.22 155.59 445.18 curveto +155.88 448.99 158.33 451.3 160.13 453.38 curveto +161.42 456.91 160.99 458.28 160.7 461.81 curveto +160.99 464.98 161.71 468.58 161.86 470.09 curveto +161.86 473.04 162.5 479.3 161.14 481.18 curveto +159.41 482.69 lineto +157.18 487.22 158.33 494.64 157.61 500.26 curveto +155.81 500.69 155.81 500.98 154.01 498.31 curveto +154.01 494.42 153.5 486.36 152.35 483.84 curveto +149.69 479.81 150.84 459.65 151.42 448.56 curveto +151.78 446.47 149.69 447.7 149.76 444.74 curveto +150.05 442.8 147.89 443.59 146.09 444.6 curveto +145.15 445.18 146.59 439.78 145.37 439.56 curveto +142.34 438.84 136.87 438.19 135.22 440.71 curveto +134.57 444.6 137.88 448.06 140.62 451.01 curveto +143.14 455.83 140.9 465.7 140.47 476.28 curveto +138.89 478.22 lineto +134.86 483.19 139.61 496.94 136.51 506.23 curveto +120.02 514.87 122.11 519.19 118.73 537.62 curveto +115.13 557.64 93.3799 567.65 79.0598 567.65 curveto +73.4399 563.04 66.24 563.62 58.5398 567.65 curveto +55.6599 569.23 54.4299 573.19 54.5 576.5 curveto +52.6299 580.75 55.22 582.19 59.6199 583.49 curveto +62.71 587.81 68.6199 594.65 69.1899 597.74 curveto +70.3398 601.92 75.5298 608.11 77.7598 609.77 curveto +75.8198 613.01 74.8098 615.17 77.1099 618.55 curveto +79.5598 620.14 81.7898 616.61 84.3799 618.55 curveto + closepath stroke +newpath 305.28 560.95 moveto +304.63 560.95 299.95 561.24 299.38 561.24 curveto +302.4 550.44 303.98 536.47 304.2 525.31 curveto +303.7 521.35 299.81 517.46 299.38 525.67 curveto +295.85 530.86 296.42 540.07 293.4 540.29 curveto +287.35 539.64 285.34 513.22 280.01 509.33 curveto +276.26 512.28 280.73 524.02 275.54 524.74 curveto +270.5 524.02 264.31 526.68 266.69 534.46 curveto +270.29 543.02 268.34 554.76 266.54 561.6 curveto +262.37 578.59 264.02 587.09 271.58 596.09 curveto +267.48 604.51 lineto +275.4 608.26 285.62 604.58 290.02 602.21 curveto +294.62 600.26 300.24 595.94 301.1 587.38 curveto +303.34 578.88 304.42 569.74 305.28 560.95 curveto + closepath fill +newpath 245.45 600.34 moveto +242.78 599.4 239.62 596.02 237.67 594.07 curveto +236.74 584.42 244.58 583.63 250.2 577.44 curveto +258.77 573.7 251.21 567.72 256.18 557.42 curveto +257.04 550.94 257.9 543.89 255.31 539.78 curveto +249.48 538.92 247.97 540.22 246.89 531.43 curveto +246.31 526.97 231.77 529.06 229.03 538.27 curveto +227.09 544.97 221.33 546.7 217.8 543.17 curveto +213.77 538.06 215.78 531.22 217.8 527.47 curveto +224.93 517.32 212.04 511.42 205.13 516.74 curveto +199.73 508.68 211.39 500.04 207.43 494.5 curveto +205.78 493.99 204.77 489.17 185.47 500.54 curveto +180.36 504.14 167.83 500.76 168.77 520.63 curveto +168.77 525.82 165.6 543.53 162.14 555.91 curveto +159.41 561.24 156.74 559.08 156.89 553.9 curveto +157.18 547.85 162.94 531.22 155.52 540.22 curveto +153.58 539.21 156.89 523.58 156.89 521.64 curveto +162 517.03 157.39 513.58 154.73 512.28 curveto +151.27 518.33 149.62 518.04 147.17 514.44 curveto +141.7 514.08 144.58 528.19 140.26 528.62 curveto +137.02 527.76 139.18 520.06 138.24 518.76 curveto +132.98 524.74 130.9 529.27 127.01 521.64 curveto +126.14 521.64 122.11 519.19 120.96 526.54 curveto +117.65 552.74 107.06 558.36 93.8198 565.13 curveto +92.0198 565.63 84.24 566.71 79.3398 568.15 curveto +73.5098 560.88 58.3198 565.63 56.23 570.31 curveto +54.7898 572.69 54.6499 575.21 54.7898 576.5 curveto +52.3398 580.1 55.8699 582.7 59.6199 583.06 curveto +62.8599 587.16 68.5398 594.94 71.2798 601.56 curveto +72.2898 603.07 74.95 609.34 78.1899 609.55 curveto +74.95 612.94 74.2998 622.51 82.6599 617.33 curveto +87.1199 624.02 92.0898 624.31 95.7598 615.82 curveto +102.89 615.38 102.31 608.69 115.78 605.52 curveto +122.76 602.86 132.77 604.58 140.26 603.72 curveto +136.22 596.88 127.44 566.86 132.98 559.8 curveto +140.76 564.7 141.84 605.38 157.03 595.66 curveto +160.56 593.93 159.91 590.04 164.09 590.18 curveto +170.42 587.45 169.13 600.77 172.51 600.77 curveto +176.47 599.76 183.02 599.04 186.98 599.54 curveto +197.71 600.77 206.93 604.08 223.92 602.5 curveto +231.12 601.78 238.25 601.06 245.45 600.34 curveto + closepath fill +newpath 305.28 560.95 moveto +304.63 560.95 299.95 561.24 299.38 561.24 curveto +302.4 550.44 303.98 536.47 304.2 525.31 curveto +303.7 521.35 299.81 517.46 299.38 525.67 curveto +295.85 530.86 296.42 540.07 293.4 540.29 curveto +287.35 539.64 285.34 513.22 280.01 509.33 curveto +276.26 512.28 280.73 524.02 275.54 524.74 curveto +270.5 524.02 264.31 526.68 266.69 534.46 curveto +270.29 543.02 268.34 554.76 266.54 561.6 curveto +262.37 578.59 264.02 587.09 271.58 596.09 curveto +267.48 604.51 lineto +275.4 608.26 285.62 604.58 290.02 602.21 curveto +294.62 600.26 300.24 595.94 301.1 587.38 curveto +303.34 578.88 304.42 569.74 305.28 560.95 curveto + closepath stroke +newpath 245.45 600.34 moveto +242.78 599.4 239.62 596.02 237.67 594.07 curveto +236.74 584.42 244.58 583.63 250.2 577.44 curveto +258.77 573.7 251.21 567.72 256.18 557.42 curveto +257.04 550.94 257.9 543.89 255.31 539.78 curveto +249.48 538.92 247.97 540.22 246.89 531.43 curveto +246.31 526.97 231.77 529.06 229.03 538.27 curveto +227.09 544.97 221.33 546.7 217.8 543.17 curveto +213.77 538.06 215.78 531.22 217.8 527.47 curveto +224.93 517.32 212.04 511.42 205.13 516.74 curveto +199.73 508.68 211.39 500.04 207.43 494.5 curveto +205.78 493.99 204.77 489.17 185.47 500.54 curveto +180.36 504.14 167.83 500.76 168.77 520.63 curveto +168.77 525.82 165.6 543.53 162.14 555.91 curveto +159.41 561.24 156.74 559.08 156.89 553.9 curveto +157.18 547.85 162.94 531.22 155.52 540.22 curveto +153.58 539.21 156.89 523.58 156.89 521.64 curveto +162 517.03 157.39 513.58 154.73 512.28 curveto +151.27 518.33 149.62 518.04 147.17 514.44 curveto +141.7 514.08 144.58 528.19 140.26 528.62 curveto +137.02 527.76 139.18 520.06 138.24 518.76 curveto +132.98 524.74 130.9 529.27 127.01 521.64 curveto +126.14 521.64 122.11 519.19 120.96 526.54 curveto +117.65 552.74 107.06 558.36 93.8198 565.13 curveto +92.0198 565.63 84.24 566.71 79.3398 568.15 curveto +73.5098 560.88 58.3198 565.63 56.23 570.31 curveto +54.7898 572.69 54.6499 575.21 54.7898 576.5 curveto +52.3398 580.1 55.8699 582.7 59.6199 583.06 curveto +62.8599 587.16 68.5398 594.94 71.2798 601.56 curveto +72.2898 603.07 74.95 609.34 78.1899 609.55 curveto +74.95 612.94 74.2998 622.51 82.6599 617.33 curveto +87.1199 624.02 92.0898 624.31 95.7598 615.82 curveto +102.89 615.38 102.31 608.69 115.78 605.52 curveto +122.76 602.86 132.77 604.58 140.26 603.72 curveto +136.22 596.88 127.44 566.86 132.98 559.8 curveto +140.76 564.7 141.84 605.38 157.03 595.66 curveto +160.56 593.93 159.91 590.04 164.09 590.18 curveto +170.42 587.45 169.13 600.77 172.51 600.77 curveto +176.47 599.76 183.02 599.04 186.98 599.54 curveto +197.71 600.77 206.93 604.08 223.92 602.5 curveto +231.12 601.78 238.25 601.06 245.45 600.34 curveto + closepath stroke +showpage +%%EOF diff --git a/doc/context/sources/general/manuals/details/hacker.jpg b/doc/context/sources/general/manuals/details/hacker.jpg Binary files differnew file mode 100644 index 000000000..cbc53a7de --- /dev/null +++ b/doc/context/sources/general/manuals/details/hacker.jpg diff --git a/doc/context/sources/general/manuals/details/mill.png b/doc/context/sources/general/manuals/details/mill.png Binary files differnew file mode 100644 index 000000000..9a1bf14e8 --- /dev/null +++ b/doc/context/sources/general/manuals/details/mill.png diff --git a/doc/context/sources/general/manuals/luatex/luatex-languages.tex b/doc/context/sources/general/manuals/luatex/luatex-languages.tex index a3790cab7..850cddb36 100644 --- a/doc/context/sources/general/manuals/luatex/luatex-languages.tex +++ b/doc/context/sources/general/manuals/luatex/luatex-languages.tex @@ -336,7 +336,7 @@ hyphenated. A side effect is that a leading hyphen can lead to a split but one will seldom run into that situation. Setting a pre and post character makes this more prominent. A value of 1 will prevent this side effect and a value of 2 will not turn the hyphen into a discretionary. Experiments with other options, like -permitting hyphenation, of the words on both sides were discarded. +permitting hyphenation of the words on both sides were discarded. \startbuffer[a] before-after \par diff --git a/doc/context/sources/general/manuals/luatex/luatex.tex b/doc/context/sources/general/manuals/luatex/luatex.tex index 6f69fadc0..79f3ba186 100644 --- a/doc/context/sources/general/manuals/luatex/luatex.tex +++ b/doc/context/sources/general/manuals/luatex/luatex.tex @@ -23,6 +23,10 @@ % "context --nodates --nocompression luatex" can be used for comparison % runs, not that we do it +% \enabledirectives[hyphenator.flatten] + +% \setupsynctex[state=start,method=max] % adds 5 pct overhead + \environment luatex-style \environment luatex-logos diff --git a/doc/context/sources/general/manuals/workflows/workflows-synctex.tex b/doc/context/sources/general/manuals/workflows/workflows-synctex.tex index 1ede3c2e4..d5b73a8e1 100644 --- a/doc/context/sources/general/manuals/workflows/workflows-synctex.tex +++ b/doc/context/sources/general/manuals/workflows/workflows-synctex.tex @@ -4,8 +4,6 @@ \startcomponent workflows-xml -\logo [SYNCTEX] {Sync\TeX} - \startchapter[title=\SYNCTEX] \startsection[title=Introduction] @@ -146,6 +144,28 @@ back to the source at all. \stopsection +\startsection[title=Methods] + +Contrary to the native \SYNCTEX\ we only deal with text which gives reasonable +efficient output. If you enable tracing (see next section) you can what has +become clickable. Instead of words you can also work with ranges, which not only +gives less runtime but also much smaller \type {.synctex} files. Just try: + +\starttyping +\setupsynctex[state=start,method=min] +\stoptyping + +to get words clickable and + +\starttyping +\setupsynctex[state=start,method=max] +\stoptyping + +to get the more efficient ranges. The overhead for \type {min} is some 10 percent +while \type {max} slows down around 5 percent. + +\stopsection + \startsection[title=Tracing] In case you want to see what gets synced you can enable a tracker: @@ -161,12 +181,12 @@ trackers only make sense for developers. \enabletrackers[system.synctex.xml] \stoptyping -At the cost of extra overhead, the next (experimental) directive can be used when -the accuracy is not optimal. - -\starttyping -\enabledirectives[system.synctex.details] -\stoptyping +% At the cost of some extra overhead, the next (experimental) directive can be used +% when the accuracy is not optimal. +% +% \starttyping +% \enabledirectives[system.synctex.details] +% \stoptyping \stopsection |
