diff options
Diffstat (limited to 'doc/context/sources/general/manuals')
223 files changed, 60425 insertions, 1028 deletions
diff --git a/doc/context/sources/general/manuals/about/about-metafun.tex b/doc/context/sources/general/manuals/about/about-metafun.tex index 8daff05a7..d289dd803 100644 --- a/doc/context/sources/general/manuals/about/about-metafun.tex +++ b/doc/context/sources/general/manuals/about/about-metafun.tex @@ -389,7 +389,7 @@ By using some \METAPOST\ magic we can even go a step further in readability: Here we demonstrate that it also works well in \type {double} mode, which makes much sense when processing data from other sources. Note how we omit the -type {lua.} prefix: the \type {MP} macro will deal with that. +type {lua} prefix: the \type {MP} macro will deal with that. \startlinecorrection[blank] \getbuffer diff --git a/doc/context/sources/general/manuals/bidi/bidi.tex b/doc/context/sources/general/manuals/bidi/bidi.tex new file mode 100644 index 000000000..abd3f64fa --- /dev/null +++ b/doc/context/sources/general/manuals/bidi/bidi.tex @@ -0,0 +1,505 @@ +% language=uk + +% \showglyphs + +\usemodule[abr-04] + +\dontcomplain + +\startbuffer[preamble-fonts] +\definefontfallback + [Serif] [scheherazaderegular*arabic] + [arabic] [force=yes,rscale=1.5] +\definefontfallback + [SerifBold] [scheherazadebold*arabic] + [arabic] [force=yes,rscale=1.5] +\definefontfallback + [SerifItalic] [scheherazaderegular*arabic] + [arabic] [force=yes,rscale=1.5] +\definefontfallback + [SerifBoldItalic] [scheherazadebold*arabic] + [arabic] [force=yes,rscale=1.5] + +\definefontfallback + [Serif] [sileot*hebrew] + [hebrew] [force=yes] +\definefontfallback + [SerifBold] [sileot*hebrew] + [hebrew] [force=yes] +\definefontfallback + [SerifItalic] [sileot*hebrew] + [hebrew] [force=yes] +\definefontfallback + [SerifBoldItalic] [sileot*hebrew] + [hebrew] [force=yes] + +\definefontfallback + [Mono] [almfixed*none] + [arabic] [force=yes] + +\definefontfallback + [Mono] [sileot*none] + [hebrew] [force=yes,factor=1] % factor forces a monospace + +\setupbodyfont + [dejavu,10pt] +\stopbuffer + +\startbuffer[preamble-languages] +\setuplanguage[ar][font=arabic,bidi=right] +\setuplanguage[he][font=hebrew,bidi=right] +\stopbuffer + +\getbuffer[preamble-fonts] +\getbuffer[preamble-languages] + +\setuplayout + [backspace=15mm, + topspace=15mm, + footer=0pt, + width=middle, + height=middle] + +\setuptyping + [color=middleblue] + +\setuptype + [color=middleblue] + +\definecolor + [maincolor] + [middleblue] + +\setupwhitespace + [big] + +\setuphead + [color=darkyellow] + +\setuphead + [chapter] + [style=\bfc] + +\setuphead + [section] + [style=\bfb] + +\setuphead + [subsection] + [style=\bfa] + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\startluacode + local report = logs.reporter("directions","check") + local line = 0 + function nodes.tracers.checkdirections(head) + line = line + 1 + report("line: %i",line) + for n in nodes.traverse_id(nodes.nodecodes.dir,head) do + report(" %s (%i,%i)",n.dir,n.subtype,n.direction) + end + return head, false + end + + nodes.tasks.appendaction("contributers","after","nodes.tracers.checkdirections") + nodes.tasks.disableaction("contributers","nodes.tracers.checkdirections") +\stopluacode + +\installtextracker + {directions.check} + {\ctxlua{nodes.tasks.enableaction("contributers","nodes.tracers.checkdirections")}} + {\ctxlua{nodes.tasks.disableaction("contributers","nodes.tracers.checkdirections")}} + +% \enabletrackers[directions.check] +% \disabletrackers[directions.check] + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\starttext + +\startMPpage + + picture p, q, r, s ; + + p := textext("l2r") xsized .9PaperWidth ; + q := textext("r2l") xsized .9PaperWidth ; + r := textext("a few tips") xsized .9PaperWidth ; + s := textext("\bf\ss hans\quad\space\quad hagen") xsized .5bbheight(p); + + p := p shifted - llcorner p ; + q := q shifted - llcorner q ; + r := r shifted - llcorner r ; + s := s shifted - llcorner s ; + + fill Page withcolor "darkyellow" ; + + p := p shifted (.05PaperWidth,ypart .5[ulcorner Page, urcorner Page]-1.1bbheight(p)) ; + q := q shifted (.05PaperWidth,ypart .5[ulcorner Page, urcorner Page]-1.1bbheight(p)-1.15bbheight(q)) ; + r := r shifted (.05PaperWidth,ypart .5[llcorner Page, lrcorner Page]+0.3bbheight(r)) ; + s := s shifted (.66PaperWidth,ypart .5[llcorner Page, lrcorner Page]+1.5bbheight(s)) ; + + draw p withcolor "lightgray" ; + draw q withcolor "lightgray" ; + draw r withcolor "middleblue" ; + draw s withcolor "lightgray" ; + +\stopMPpage + +\startchapter[title=Introduction] + +With \CONTEXT\ you can typeset in two directions: from left to right and from +right to left. In fact you can also combine these two directions, like this: + +\startbuffer +There are many {\righttoleft \maincolor \it scripts in use} and some run into the +other direction. However, there is {\righttoleft \maincolor \it no fixed relation +{\lefttoright \black \it between the} direction of the script} and cars being +driven left or right of the road. +\stopbuffer + +\typebuffer + +\getbuffer + +Even someone not familiar with right to left typesetting can see what happens +here, or not? In fact Luigi Scarso pointed out that the \type {fixed} reversed +into {\righttoleft \type {fixed}} but not in the example where {\bf fixed} +becomes {\righttoleft \bf fixed}. This signals an important property of the way +the text gets processed: you input something, at some points font features get +applied (like ligatures) and in the end the resulting glyph stream is reversed. +By that time the combination of {\bf f}+{\bf i} has become {\bf fi}! So, be +prepared for surprises. + +This manual is written by a left to right user so don't expect a manual on +semitic typesetting. Also don't expect a (yet) complete manual. I'll add whatever +comes to mind. This is not a manual about Hebrew or Arabic, if only because I +can't read any of those scripts (languages). I leave that to others to cover. + +{\em This is work in progress! So expect errors and typos.} + +\startlines +Hans Hagen +Hasselt, NL +\stoplines + +\stopchapter + +\startchapter[title={Setting up fonts}] + +So let's see how Arabic and Hebrew come out: + +\startbuffer +The sentence \quotation {I have no clue what this means.} is translated (by +Google Translate) into \quotation {\ar \righttoleft ليس لدي أي فكرة عما يعنيه هذا.} +which is then translated back to \quotation {I have no idea what this means.} so +maybe arabic has no clue what a clue is. The suggested Arabic pronunciation is +\quotation {lays laday 'ayu fikrat eamaa yaenih hadha}. Hebrew also likes ideas +more: \quotation {\he \righttoleft אין לי מושג מה זה אומר}. +\stopbuffer + +\typebuffer + +\getbuffer + +According to Idris Hamid the Arabic should actually be this: \quotation {\ar +لَيْسَ لَدَيَّ أَيُّ فِكْرَةٍ عَمَّا يَعْنِيهِ هٰذَا} and the transliteration \quotation {Laysa +ladayya ayyu fikratin ʿammā yaʿnihi hādhā}. + +The \CONTEXT\ (or any \TEX) ecosystem deals with languages and fonts. Languages +(that relate to scripts) have specific characteristics, like running from right +to left, and fonts provide a repertoire of glyphs and features. There is no real +(standard) relationship between these. In for instance browsers, there are +automatic fallback systems for missing characters in a font: another font is +taken. These fallbacks are often not easy to tweak. + +In this document we use Dejavu and although that font has Arabic shapes in its +monospace variant, the serifs come without them (at least when I write this +down). Before we actually define the bodyfont we hook in some fallbacks. The +typescript for Dejavu has lines like this: + +\starttyping +\definefontsynonym + [SerifBoldItalic] + [name:dejavuserifbolditalic] + [features=default, + fallbacks=SerifBoldItalic] +\stoptyping + +This permits us to do this: + +\typebuffer[preamble-fonts] + +In addition we set up the languages: + +\typebuffer[preamble-languages] + +The following example demonstrates what the effects of these commands are: + +\startbuffer +{لَيْسَ لَدَيَّ أَيُّ فِكْرَةٍ عَمَّا يَعْنِيهِ هٰذَا.} +{אין לי מושג מה זה אומר.} +{\righttoleft لَيْسَ لَدَيَّ أَيُّ فِكْرَةٍ عَمَّا يَعْنِيهِ هٰذَا.} +{\righttoleft אין לי מושג מה זה אומר.} +{\ar \righttoleft لَيْسَ لَدَيَّ أَيُّ فِكْرَةٍ عَمَّا يَعْنِيهِ هٰذَا.} +{\he \righttoleft אין לי מושג מה זה אומר.} +{\ar لَيْسَ لَدَيَّ أَيُّ فِكْرَةٍ عَمَّا يَعْنِيهِ هٰذَا.} +{\he אין לי מושג מה זה אומר.} +\stopbuffer + +\typebuffer + +\startlines +\getbuffer +\stoplines + +In principle you can also rely on automatic direction changes, for instance +by using the following command: + +\starttyping +\setupdirections + [bidi=global, + method=three] +\stoptyping + +But that doesn't do a font switch for you, nor does it do any of the other +language related settings. It really helps if you properly tag your +document content, as in: + +\starttyping +{\ar لَيْسَ لَدَيَّ أَيُّ فِكْرَةٍ عَمَّا يَعْنِيهِ هٰذَا.} +{\he אין לי מושג מה זה אומר.} +\stoptyping + +One reason to set the \type {font} parameter for a language is that it will +activate the right features in a font. Instead of falling back on some default, +we can be very specific in what we want to enable. + +\stopchapter + +\startchapter[title=A mixed layout] + +The typesetting engine normally works from left to right and top to bottom. Going +from right to left actually involved two decisions: + +\startitemize[packed] +\startitem the direction of the display elements, the paragraphs \stopitem +\startitem the direction of the inline text, the lines \stopitem +\stopitemize + +The first one is kept track of in a state variable. Every paragraph starts with +a node that carries, among other information, that state. This node is added +automatically and does not interfere with the typesetting. The inline direction +is more intrusive as it is marked by nodes that indicate the beginning and end +of a reversed strip. This mechanism is rather reliable and normally works out +well. Take this: + +\startbuffer +left {\righttoleft right} left +left{ \righttoleft right} left +left {\righttoleft right }left +left{ \righttoleft right }left +\stopbuffer + +\typebuffer + +You can see that we need to be careful with spaces as they can end up inside or +outside a substream and by swapping next to each other: + +\startlines +\getbuffer +\stoplines + +We can wrap the lines in boxes as in: + +\startbuffer +\hbox{left\space{\bf\righttoleft right}\space left} +\hbox{left{\bf\space \righttoleft right}\space left} +\hbox{left\space{\bf\righttoleft right\space}left} +\hbox{left{\bf\space\righttoleft right\space}left} +\stopbuffer + +\typebuffer + +\definecolor[ShineThrough][s=0,a=1,t=.2] + +When visualize the spaces we get this: + +\startlines\ShineThrough +\showmakeup[space,hbox]\getbuffer +\stoplines + +The space of a normal and bold font in the same family normally is the same but +let's mix with a larger size: + +\startbuffer +\hbox{left {\bfa\righttoleft right} left} +\hbox{left{\bfa\space \righttoleft right} left} +\hbox{left {\bfa\righttoleft right }left} +\hbox{left{\bfa\space\righttoleft right }left} +\stopbuffer + +\typebuffer + +Now we get the following. As you can see, it really matters where we put the +braces. + +\startlines +\ShineThrough\showmakeup[space,hbox]\getbuffer +\stoplines + +Once you are accustomed to tagging and \TEX\ you will probably not fall into +these traps. In \in {figure} [fig:spaces] we show a large version. + +\startplacefigure[location=top,title={Watch your spaces!},reference=fig:spaces] + \scale + [width=\hsize] + {\vbox{\ShineThrough\showmakeup[space,hbox]\getbuffer}} +\stopplacefigure + + +The \type {\righttoleft} command actually has two meanings. This can best be seen +from an example. + +\startbuffer +\righttoleft \bf How will this come out? +\stopbuffer + +\typebuffer + +\start \getbuffer \par \stop + +\startbuffer +And \righttoleft \bf how will this come out? +\stopbuffer + +\typebuffer + +\start \getbuffer \par \stop + +When we start a paragraph (or in \TEX\ speak: when we are still in vertical mode) +the paragraph direction as well as the inline direction is set. Otherwise only +the inline direction is set. There are low level \TEX\ commands (primitives) to +set the direction but you can best {\em not} use these because we need to do a +bit more than that. + +There are quite some low level commands related to changing directions. Some deal +with the layout, some with boxes. We might provide more in the future. + +\starttabulate[|l|p|] +\FL +\NC \type {\lefttoright} \NC l2r dir node or paragraph property \NC \NR +\NC \type {\righttoleft} \NC r2l dir node or paragraph property \NC \NR +\NC \type {\checkedlefttoright} \NC l2r dir node or paragraph property (unless already set) \NC \NR +\NC \type {\checkedrighttoleft} \NC r2l dir node or paragraph property (unless already set) \NC \NR +\ML +\NC \type {\synchronizeinlinedirection} \NC pickup a (possibly) reset state \NC \NR +\NC \type {\synchronizelayoutdirection} \NC pickup a (possibly) reset state \NC \NR +\NC \type {\synchronizedisplaydirection} \NC pickup a (possibly) reset state \NC \NR +\ML +\NC \type {\righttolefthbox} \NC r2l \type {\hbox} \NC \NR +\NC \type {\lefttorighthbox} \NC l2r \type {\hbox} \NC \NR +\NC \type {\righttoleftvbox} \NC r2l \type {\vbox} \NC \NR +\NC \type {\lefttorightvbox} \NC l2r \type {\vbox} \NC \NR +\NC \type {\righttoleftvtop} \NC r2l \type {\vtop} \NC \NR +\NC \type {\lefttorightvtop} \NC l2r \type {\vtop} \NC \NR +\ML +\NC \type {\leftorrighthbox} \NC l2r or r2l \type {\hbox} \NC \NR +\NC \type {\leftorrightvbox} \NC l2r or r2l \type {\vbox} \NC \NR +\NC \type {\leftorrightvtop} \NC l2r or r2l \type {\vtop} \NC \NR +\ML +\NC \type {\autodirhbox} \NC l2r or r2l \type {\hbox} (a bit more clever) \NC \NR +\NC \type {\autodirvbox} \NC l2r or r2l \type {\vbox} (a bit more clever) \NC \NR +\NC \type {\autodirvtop} \NC l2r or r2l \type {\vtop} (a bit more clever) \NC \NR +\ML +\NC \type {\bidilre} \NC character \type {U+202A}, enforce l2r state \NC \NR +\NC \type {\bidirle} \NC character \type {U+202B}, enforce r2l state \NC \NR +\NC \type {\bidipop} \NC character \type {U+202C}, return to last state \NC \NR +\NC \type {\bidilro} \NC character \type {U+202D}, override l2r state \NC \NR +\NC \type {\bidirlo} \NC character \type {U+202E}, override r2l state \NC \NR +\NC \type {\lefttorightmark} \type {\lrm} \NC character \type {U+200E}, l2r indicator \NC \NR +\NC \type {\righttoleftmark} \type {\rlm} \NC character \type {U+200F}, r2l indicator \NC \NR +\ML +\NC \type {\dirlre} \NC switch to l2r mode using \type {\bidilre} or \lefttoright \NC \NR +\NC \type {\dirrle} \NC switch to r2l mode using \type {\bidirle} or \righttoleft \NC \NR +\NC \type {\dirlro} \NC enforce l2r mode using \type {\bidilro} or \lefttoright \NC \NR +\NC \type {\dirrlo} \NC enforce r2l mode using \type {\bidirlo} or \righttoleft \NC \NR +\ML +\NC \type {\naturalhbox} \NC a normal l2r \type {hbox} \NC \NR +\NC \type {\naturalvbox} \NC a normal l2r \type {vbox} \NC \NR +\NC \type {\naturalvtop} \NC a normal l2r \type {vtop} \NC \NR +\NC \type {\naturalhpack} \NC a normal l2r \type {hpack} \NC \NR +\NC \type {\naturalvpack} \NC a normal l2r \type {vpack} \NC \NR +\LL +\stoptabulate + +When we talk about layout, we mean the overall layout, concerning the document as +a whole. We can have a dominantly l2r, dominantly r2l or mixed setup. In a next +chapter we will give more details on the dominant setup. Here we stick to +mentioning that the document flow direction is set with + +\starttyping +\setupalign[r2l] % or r2l +\stoptyping + +When a command to setup an environment has a \type {align} parameter, the same +keywords can be uses as part of the specification. \footnote {We haven't tested +all situations and possible interferences. Just report anomalies to the mailing +list.} + +\stopchapter + +\startchapter[title={Numbering and positioning}] + +todo: columns (direction key), numbers (conversionsets), margins (begin/end), etc + +\stopchapter + +\startchapter[title={The \LUA\ interface}] + +We assume that you run \CONTEXT\ \MKIV\ in combination with \LUATEX. Direction +support in this engine has been improved over time. Originally the \OMEGA\ +(\ALEPH) direction model was used but in the meantime it has been stripped to the +basics, and what used to be so called whatsits (extension nodes) are now first +class nodes. In the \LUA\ interface we still support the: + +\startitemize[packed] +\startitem + \type {TLT} and \type {TRT} keywords for local par nodes +\stopitem +\startitem + \type {+TLT}, \type {-TLT}, \type {+TRT} and \type {-TRT} keywords for + direction nodes +\stopitem +\stopitemize + +However, because we use dedicated nodes, and because nodes actually store numbers +and not strings we also expose the numeric model: + +\starttabulate[|l|l|l|] +\NC 0 \NC \type {TLT} \NC left to right \NC \NR +\NC 1 \NC \type {TRT} \NC right to left \NC \NR +\NC 2 \NC \type {LTL} \NC not used in context \NC \NR +\NC 3 \NC \type {RTT} \NC not used in context \NC \NR +\stoptabulate + +These values are used for local par nodes as well as direction nodes. In addition +a direction node has a subtype: + +\starttabulate[|l|l|l|] +\NC 0 \NC \type {normal} \NC comparable to \type {+} \NC \NR +\NC 1 \NC \type {cancel} \NC comparable to \type {-} \NC \NR +\stoptabulate + +The \type {dir} field uses the strings, the \type {direction} field the number +(both of course share the same internal node variable). + +\stopchapter + +\stoptext + +% \defineconversionset [\s!default] [] [numbers] +% \defineconversionset [\v!number] [] [numbers] +% \defineconversionset [\v!pagenumber] [] [numbers] +% \defineconversionset [\v!appendix:\s!default] [Romannumerals,Characters] [numbers] +% \defineconversionset [\v!formula] [numbers,characters] % no \v! ? 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..e61507929 --- /dev/null +++ b/doc/context/sources/general/manuals/cld/cld-abitoflua.tex @@ -0,0 +1,869 @@ +% 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 + +The \type {\directlua{}} command can also be implemented using the token parser +and \LUA\ itself. A variant is therefore \type {\luascript{}} which can be +considered an alias but with a bit different error reporting. A variant on this +is the \type {\luathread {name} {code}} command. Here is an example of their +usage: + +\startbuffer +\luascript { context("foo 1:") context(i) } \par +\luathread {test} { i = 10 context("bar 1:") context(i) } \par +\luathread {test} { context("bar 2:") context(i) } \par +\luathread {test} {} % resets +\luathread {test} { context("bar 3:") context(i) } \par +\luascript { context("foo 2:") context(i) } \par +\stopbuffer + +\typebuffer + +These commands result in: + +\startpacked \getbuffer \stoppacked + +% \testfeatureonce{100000}{\directlua {local a = 10 local a = 10 local a = 10}} % 0.53s +% \testfeatureonce{100000}{\luascript {local a = 10 local a = 10 local a = 10}} % 0.62s +% \testfeatureonce{100000}{\luathread {test} {local a = 10 local a = 10 local a = 10}} % 0.79s + +The variable \type {i} is local to the thread (which is not really a thread in +\LUA\ but more a named piece of code that provides an environment which is shared +over the calls with the same name. You will probably never need these. + +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..11600b847 --- /dev/null +++ b/doc/context/sources/general/manuals/cld/cld-ctxfunctions.tex @@ -0,0 +1,786 @@ +% 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 {countall} function. +Nested nodes are counted too. + +\ShowLuaExampleString{nodes.countall(tex.box[0])} +\ShowLuaExampleString{nodes.countall(tex.box[0].list)} + +There are a lot of helpers in the \type {nodes} namespace. In fact, we map all the +helpers provided by the engine itself under \type {nodes} too. These are described +in the \LUATEX\ manual. There are for instance 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 more +helpers as well as +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..b2760e05b --- /dev/null +++ b/doc/context/sources/general/manuals/cld/cld-luafunctions.tex @@ -0,0 +1,2367 @@ +% 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 and \LUA\ 5.3 is more +picky on integers.} + +\starttabulate[|lB|lT|lT|lT|] +\HL +\NC integer \NC \letterpercent i \NC 12345 \NC \cldcontext{string.format("\letterpercent i", 12345 )} \NC \NR +\NC integer \NC \letterpercent d \NC 12345 \NC \cldcontext{string.format("\letterpercent d", 12345 )} \NC \NR +\NC unsigned \NC \letterpercent u \NC -12345 \NC \cldcontext{string.format("\letterpercent u", 12345 )} \NC \NR +\NC character \NC \letterpercent c \NC 123 \NC \cldcontext{string.format("\letterpercent c", 89 )} \NC \NR +\NC hexadecimal \NC \letterpercent x \NC 123 \NC \cldcontext{string.format("\letterpercent x", 123 )} \NC \NR +\NC \NC \letterpercent X \NC 123 \NC \cldcontext{string.format("\letterpercent X", 123 )} \NC \NR +\NC octal \NC \letterpercent o \NC 12345 \NC \cldcontext{string.format("\letterpercent o", 12345 )} \NC \NR +\HL +\NC string \NC \letterpercent s \NC abc \NC \cldcontext{string.format("\letterpercent s", "abcd")} \NC \NR +\NC \NC \letterpercent -8s \NC 123 \NC \cldcontext{string.format("\letterpercent -8s", 123 )} \NC \NR +\NC \NC \letterpercent 8s \NC 123 \NC \cldcontext{string.format("\letterpercent 8s", 123 )} \NC \NR +\HL +\NC float \NC \letterpercent 0.2f \NC 12.345 \NC \cldcontext{string.format("\letterpercent 0.2f",12.345)} \NC \NR +\NC exponential \NC \letterpercent 0.2e \NC 12.345 \NC \cldcontext{string.format("\letterpercent 0.2e",12.345)} \NC \NR +\NC \NC \letterpercent 0.2E \NC 12.345 \NC \cldcontext{string.format("\letterpercent 0.2E",12.345)} \NC \NR +\NC autofloat \NC \letterpercent 0.2g \NC 12.345 \NC \cldcontext{string.format("\letterpercent 0.2g",12.345)} \NC \NR +\NC \NC \letterpercent 0.2G \NC 12.345 \NC \cldcontext{string.format("\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. As we run out of keys, some extra ones are a bit 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 string \NC \letterpercent s \NC foo \NC \cldcontext{"\letterpercent s","foo"} \NC \NR +\NC force tostring \NC \letterpercent S \NC nil \NC \cldcontext{"\letterpercent S",nil} \NC \NR +\NC quoted string \NC \letterpercent q \NC foo \NC \cldcontext{"\letterpercent q","foo"} \NC \NR +\NC force quoted string \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 +\NC automatic quoted \NC \letterpercent a \NC true \NC \cldcontext{"\letterpercent a",true} \NC \NR\NC \NR +\NC \NC \letterpercent A \NC true \NC \cldcontext{"\letterpercent A",true} \NC \NR\NC \NR +\NC left aligned utf \NC \letterpercent 30< \NC xx½xx \NC \cldcontext{"\letterpercent 30<","xx½xx"} \NC \NR\NC \NR +\NC right aligned utf \NC \letterpercent 30> \NC xx½xx \NC \cldcontext{"\letterpercent 30>","xx½xx"} \NC \NR\NC \NR +\HL +\NC integer \NC \letterpercent i \NC 1234 \NC \cldcontext{"\letterpercent i",1234} \NC \NR +\NC integer \NC \letterpercent d \NC 1234 \NC \cldcontext{"\letterpercent d",1234} \NC \NR +\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 +\NC stripped number \NC \letterpercent N \NC 000123 \NC \cldcontext{"\letterpercent N","000123"} \NC \NR +\NC comma/period float \NC \letterpercent m \NC 12.34 \NC \cldcontext{"\letterpercent m",12.34} \NC \NR +\NC period/comma float \NC \letterpercent M \NC 12.34 \NC \cldcontext{"\letterpercent M",12.34} \NC \NR +\HL +\NC hexadecimal \NC \letterpercent x \NC 1234 \NC \cldcontext{"\letterpercent x",1234} \NC \NR +\NC \NC \letterpercent X \NC 1234 \NC \cldcontext{"\letterpercent X",1234} \NC \NR +\NC octal \NC \letterpercent o \NC 1234 \NC \cldcontext{"\letterpercent o",1234} \NC \NR +\HL +\NC float \NC \letterpercent 0.2f \NC 12.345 \NC \cldcontext{"\letterpercent 0.2f",12.345} \NC \NR +\NC formatted float \NC \letterpercent 2.3k \NC 12.3456 \NC \cldcontext{"\letterpercent 2.3f",12.3456} \NC \NR +\NC checked float \NC \letterpercent 0.2F \NC 12.30 \NC \cldcontext{"\letterpercent 0.2F",12.3} \NC \NR +\NC exponential \NC \letterpercent .2e \NC 12.345e120 \NC \cldcontext{"\letterpercent 0.2j",12.345e120} \NC \NR +\NC \NC \letterpercent .2E \NC 12.345e120 \NC \cldcontext{"\letterpercent 0.2J",12.345e120} \NC \NR +\NC sparse exp \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 +\NC autofloat \NC \letterpercent g \NC 12.345 \NC \cldcontext{"\letterpercent 0.2J",12.345} \NC \NR +\NC \NC \letterpercent G \NC 12.345 \NC \cldcontext{"\letterpercent 0.2J",12.345} \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 + +The generic formatters \type {a} and \type {A} convert 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. + +A special one is the alignment formatter, which is a variant on the \type {s} one +that also takes an optional positive of negative number: + +\startbuffer +\startluacode +context.start() +context.tttf() +context.verbatim("[[% 30<]]","xxaxx") context.par() +context.verbatim("[[% 30<]]","xx½xx") context.par() +context.verbatim("[[% 30>]]","xxaxx") context.par() +context.verbatim("[[% 30>]]","xx½xx") context.par() +context.verbatim("[[%-30<]]","xxaxx") context.par() +context.verbatim("[[%-30<]]","xx½xx") context.par() +context.verbatim("[[%-30>]]","xxaxx") context.par() +context.verbatim("[[%-30>]]","xx½xx") context.par() +context.stop() +\stopluacode +\stopbuffer + +\typebuffer \getbuffer + +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}. In the latest \LUATEX\ you can use the new +bit related operators. + +% 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..a177db9f8 --- /dev/null +++ b/doc/context/sources/general/manuals/cld/cld-macros.tex @@ -0,0 +1,224 @@ +% 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 + +\startsection[title=Looking inside] + +If needed you can access the body of a macro. Take for instance: + +\startbuffer +\def\TestA{A} +\def\TestB{\def\TestC{c}} +\def\TestC{C} +\stopbuffer + +\typebuffer \getbuffer + +The following example demonsttaies how we can look inside these macros. You need +to be aware of the fact that the whole blob of \LUA\ codes is finished before we +return to \TEX, so when we pipe the meaning of \type {TestB} back to \TEX\ it +only gets expanded afterwards. We can use a function to get back to \LUA. It's +only then that the meaning of \type {testC} is changed by the (piped) expansion +of \type {TestB}. + +\startbuffer +\startluacode +context(tokens.getters.macro("TestA")) +context(tokens.getters.macro("TestB")) +context(tokens.getters.macro("TestC")) +tokens.setters.macro("TestA","a") +context(tokens.getters.macro("TestA")) +context(function() + context(tokens.getters.macro("TestA")) + context(tokens.getters.macro("TestB")) + context(tokens.getters.macro("TestC")) +end) +\stopluacode +\stopbuffer + +\typebuffer \getbuffer + +Here is another example: + +\startbuffer +\startluacode +if tokens.getters.macro("fontstyle") == "rm" then + context("serif") +else + context("unknown") +end +\stopluacode +\stopbuffer + +\typebuffer + +Of course this assumes that you have some knowledge of the \CONTEXT\ internals. + +\getbuffer + +\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..37ecf45c6 --- /dev/null +++ b/doc/context/sources/general/manuals/cld/cld-specialcommands.tex @@ -0,0 +1,257 @@ +% language=uk + +\startcomponent cld-specialcommands + +\environment cld-environment + +\startchapter[title=Special commands] + +\index{tracing} + +\startsection[title=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 + +\stopsection + +\startsection[title=Overloads] + +A few macros have special functions (overloads) 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}. Or take this: + +\startbuffer +1: \ctxlua{commands.doif(true)}{one} +2: \cldcommand{doif("a","a","two")} +3: \ctxcommand{doif(true)}{three} +\stopbuffer + +\typebuffer + +\startlines +\getbuffer +\stoplines + +\stopsection + +\startsection[title=Steps] + +% added and extended in sync with an article about a generic 'execute' +% feature + +We already mentioned the stepper as a very special trick so let's give +some more explanation here. When you run the following code: + +\setbox0\emptybox + +\starttyping +\startluacode + context.startitemize() + context.startitem() + context("BEFORE 1") + context.stopitem() + context("\\setbox0\\hbox{!!!!}") + context.startitem() + context("%p",tex.getbox(0).width) + context.stopitem() + context.stopitemize() +\stopluacode +\stoptyping + +You get a message like: + +\starttyping +[ctxlua]:8: attempt to index a nil value +... +10 context("\\setbox0\\hbox{!!!!}") +11 context.startitem() +12 >> context("%p",tex.getbox(0).width) +... +\stoptyping + +due to the fact that the box is still void. All that the \CONTEXT\ commands feed +into \TEX\ happens when the code snippet has finished. You can however run a +snippet of code the following way: + +\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.stopitemize() + end) +\stopluacode +\stopbuffer + +\typebuffer + +and get: + +\getbuffer + +A more extensive example is: + +\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 + +which gives: + +\getbuffer + +A step returns control to \TEX\ immediately and after the \TEX\ code that it +feeds back is expanded, returns to \LUA. There are some limitations due to the +input stack but normally that is no real issue. + +You can run the following code: + +\starttyping +\definenumber[LineCounter][way=bypage] +\starttext +\startluacode +for i=1,2000 do + context.incrementnumber { "LineCounter" } + context.getnumber { "LineCounter" } + context.par() +end +\stopluacode +\stoptext +\stoptyping + +You will notice however that the number is not right on each page. This is +because \TEX\ doesn't know yet that there is no room on the page. The next will +work better: + +\starttyping +\definenumber[LineCounter][way=bypage] +\starttext +\startluacode +context.stepwise(function() + for i=1,2000 do + context.testpage { 0 } + context.incrementnumber { "LineCounter" } + context.getnumber { "LineCounter" } + context.par() + context.step() + end +end) +\stopluacode +\stoptext +\starttyping + +Instead of the \type {testpage} function you can also play directly with +registers, like: + +\starttyping +if tex.pagegtotal + tex.count.lineheight > tex.pagetotal then +\starttyping + +but often an already defined helper does a better job. Of course you will +probably never need this kind of hacks anyway, if only because much more is going +on and there are better ways then. + +\stopsection + +\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/columnsets/columnsets-000.tex b/doc/context/sources/general/manuals/columnsets/columnsets-000.tex index 429a067de..4f254e2ae 100644 --- a/doc/context/sources/general/manuals/columnsets/columnsets-000.tex +++ b/doc/context/sources/general/manuals/columnsets/columnsets-000.tex @@ -40,6 +40,9 @@ \setupfooter [style=\tttf] +\setupheader + [style=\tttf] + \setuptolerance [verytolerant,stretch] diff --git a/doc/context/sources/general/manuals/columnsets/columnsets.tex b/doc/context/sources/general/manuals/columnsets/columnsets.tex index 0cb95229d..6df706d90 100644 --- a/doc/context/sources/general/manuals/columnsets/columnsets.tex +++ b/doc/context/sources/general/manuals/columnsets/columnsets.tex @@ -107,6 +107,11 @@ \definecolor[color-5][.5(white,color-4)] \definecolor[color-6][.2(white,color-4)] +\usemodule[typesetting] + +\setupcombination + [style=mono] + \startuseMPgraphic{page} StartPage ; path p ; @@ -143,144 +148,6 @@ StopPage ; \defineoverlay[frame] [\useMPgraphic{frame}] \defineoverlay[contrast][\useMPgraphic{contrast}] -\setupexternalfigures - [background=frame] - -\definecombination - [sixpages] - [%inbetween=\blank, - style=mono, - distance=.5\bodyfontsize, - width=\textwidth] - -\definecombination - [fourpages] - [%inbetween=\blank, - style=mono, - distance=.5\bodyfontsize, - width=\textwidth] - -\definecombination - [twopages] - [style=mono] - -\definemeasure[twopages] [\dimexpr\dimexpr\textwidth-3 \bodyfontsize\relax/4\relax] -\definemeasure[fourpages] [\dimexpr\dimexpr\textwidth-3 \bodyfontsize\relax/4\relax] -\definemeasure[eightpages][\dimexpr\dimexpr\textwidth-3 \bodyfontsize\relax/4\relax] -\definemeasure[sixpages] [\dimexpr\dimexpr\textwidth-2.5\bodyfontsize\relax/6\relax] - -\starttexdefinition unexpanded OnePage #1 - \startlinecorrection[blank] - \startcombination[twopages][1*1] - {\typesetfile[#1.tex][page=1,lines=15]} {1} - \stopcombination - \stoplinecorrection -\stoptexdefinition - -\starttexdefinition unexpanded OneSpread #1 - \startlinecorrection[blank] - \startcombination[twopages][1*1] - {\typesetfile[#1.tex][page=2,lines=15]} {2} - \stopcombination - \stoplinecorrection -\stoptexdefinition - -\starttexdefinition unexpanded TwoPages #1 - \startlinecorrection[blank] - \startcombination[twopages][2*1] - {\typesetfile[#1.tex][page=1,width=\measure{twopages}]} {1} - {\typesetfile[#1.tex][page=2,width=\measure{twopages}]} {2} - \stopcombination - \stoplinecorrection -\stoptexdefinition - -\starttexdefinition unexpanded TwoSpread #1 - \startlinecorrection[blank] - \startcombination[twopages][2*1] - {\typesetfile[#1.tex][page=2,width=\measure{twopages}]} {2} - {\typesetfile[#1.tex][page=3,width=\measure{twopages}]} {3} - \stopcombination - \stoplinecorrection -\stoptexdefinition - -\starttexdefinition unexpanded FourPages #1 - \startlinecorrection[blank] - \startcombination[fourpages][4*1] - {\typesetfile[#1.tex][page=1,width=\measure{fourpages}]} {1} - {\typesetfile[#1.tex][page=2,width=\measure{fourpages}]} {2} - {\typesetfile[#1.tex][page=3,width=\measure{fourpages}]} {3} - {\typesetfile[#1.tex][page=4,width=\measure{fourpages}]} {4} - \stopcombination - \stoplinecorrection -\stoptexdefinition - -\starttexdefinition unexpanded FourSpread #1 - \startlinecorrection[blank] - \startcombination[fourpages][4*1] - {\typesetfile[#1.tex][page=2,width=\measure{fourpages}]} {2} - {\typesetfile[#1.tex][page=3,width=\measure{fourpages}]} {3} - {\typesetfile[#1.tex][page=4,width=\measure{fourpages}]} {4} - {\typesetfile[#1.tex][page=5,width=\measure{fourpages}]} {5} - \stopcombination - \stoplinecorrection -\stoptexdefinition - -\starttexdefinition unexpanded SixPages #1 - \startlinecorrection[blank] - \startcombination[sixpages][6*1] - {\typesetfile[#1.tex][page=1,width=\measure{sixpages}]} {1} - {\typesetfile[#1.tex][page=2,width=\measure{sixpages}]} {2} - {\typesetfile[#1.tex][page=3,width=\measure{sixpages}]} {3} - {\typesetfile[#1.tex][page=4,width=\measure{sixpages}]} {4} - {\typesetfile[#1.tex][page=5,width=\measure{sixpages}]} {5} - {\typesetfile[#1.tex][page=6,width=\measure{sixpages}]} {6} - \stopcombination - \stoplinecorrection -\stoptexdefinition - -\starttexdefinition unexpanded SixSpread #1 - \startlinecorrection[blank] - \startcombination[sixpages][6*1] - {\typesetfile[#1.tex][page=2,width=\measure{sixpages}]} {2} - {\typesetfile[#1.tex][page=3,width=\measure{sixpages}]} {3} - {\typesetfile[#1.tex][page=4,width=\measure{sixpages}]} {4} - {\typesetfile[#1.tex][page=5,width=\measure{sixpages}]} {5} - {\typesetfile[#1.tex][page=6,width=\measure{sixpages}]} {6} - {\typesetfile[#1.tex][page=7,width=\measure{sixpages}]} {7} - \stopcombination - \stoplinecorrection -\stoptexdefinition - -\starttexdefinition unexpanded EightPages #1 - \startlinecorrection[blank] - \startcombination[fourpages][4*2] - {\typesetfile[#1.tex][page=1,width=\measure{eightpages}]} {#1 / 1} - {\typesetfile[#1.tex][page=2,width=\measure{eightpages}]} {#1 / 2} - {\typesetfile[#1.tex][page=3,width=\measure{eightpages}]} {#1 / 3} - {\typesetfile[#1.tex][page=4,width=\measure{eightpages}]} {#1 / 4} - {\typesetfile[#1.tex][page=5,width=\measure{eightpages}]} {#1 / 5} - {\typesetfile[#1.tex][page=6,width=\measure{eightpages}]} {#1 / 6} - {\typesetfile[#1.tex][page=7,width=\measure{eightpages}]} {#1 / 7} - {\typesetfile[#1.tex][page=8,width=\measure{eightpages}]} {#1 / 8} - \stopcombination - \stoplinecorrection -\stoptexdefinition - -\starttexdefinition unexpanded EightSpread #1 - \startlinecorrection[blank] - \startcombination[fourpages][4*2] - {\typesetfile[#1.tex][page=2,width=\measure{eightpages}]} {#1 / 2} - {\typesetfile[#1.tex][page=3,width=\measure{eightpages}]} {#1 / 3} - {\typesetfile[#1.tex][page=4,width=\measure{eightpages}]} {#1 / 4} - {\typesetfile[#1.tex][page=5,width=\measure{eightpages}]} {#1 / 5} - {\typesetfile[#1.tex][page=6,width=\measure{eightpages}]} {#1 / 6} - {\typesetfile[#1.tex][page=7,width=\measure{eightpages}]} {#1 / 7} - {\typesetfile[#1.tex][page=8,width=\measure{eightpages}]} {#1 / 8} - {\typesetfile[#1.tex][page=9,width=\measure{eightpages}]} {#1 / 9} - \stopcombination - \stoplinecorrection -\stoptexdefinition - \setuphead [chapter] [style=\QuiteLarge, @@ -352,23 +219,15 @@ StartPage ; fill p shifted sh withcolor \MPcolor{color-3} withtransparency(1,.5) ; draw q xysized (bbwidth(p),bbheight(p)) shifted sh ; enddef ; - if true : - do_it ((2w/10,17d),(.1w,20d)) ; - do_it ((2w/10,15d),(.1w,56d)) ; - do_it ((2w/10,21d),(.4w,66d)) ; - do_it ((2w/10,13d),(.7w,38d)) ; - do_it ((5w/10,13d),(.4w,13d)) ; - draw textext.urt("\ssbf Hans Hagen") - xysized (5w/10,5d) - shifted (.4w,6d) - withcolor \MPcolor{color-5} ; - else : - do_it ((2w/10,17d),(.1w,15d)) ; - do_it ((2w/10,15d),(.1w,51d)) ; - do_it ((2w/10,21d),(.4w,61d)) ; - do_it ((2w/10,13d),(.7w,31d)) ; - do_it ((5w/10,13d),(.4w, 7d)) ; - fi ; + do_it ((2w/10,17d),(.1w,20d)) ; + do_it ((2w/10,15d),(.1w,56d)) ; + do_it ((2w/10,21d),(.4w,66d)) ; + do_it ((2w/10,13d),(.7w,38d)) ; + do_it ((5w/10,13d),(.4w,13d)) ; + draw textext.urt("\ssbf Hans Hagen") + xysized (5w/10,5d) + shifted (.4w,6d) + withcolor \MPcolor{color-5} ; StopPage ; \stopMPpage 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..91d853098 --- /dev/null +++ b/doc/context/sources/general/manuals/details/details-floatingaround.tex @@ -0,0 +1,1485 @@ +% 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 much of what 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=] + +At \CONTEXT\ and Bacho\TEX meetings it is now a tradition that Harald König and I +spend some time on figuring out what happens with border cases and interfences +with user intervention. As it's hard to nail down I decided to add some more +tracing and control. So, the remainder of this chapter is dedicated to Harald. + +We will now demonstrate some features in a way that makes it possible to +compare to the simple default case. Options can be passed as keywords: + +\starttyping +\placefigure + [left,...] + [fig:whatever] + {caption} + {content} +\stoptyping + +or as settings: + +\starttyping +\startplacefigure + [default={left,...}, + title=caption, + reference=fig:whatever] + + content + +\stopplacefigure +\stoptyping + +It is important to realize that all that spacing can interfere with additional +hard coded corrections at the users end. We don't show the effects of \type +{sidespacebefore} and \type {sidespaceafter}, the two general vertical spacing +hooks. These are currently set to {\tttf \rootfloatparameter {sidespacebefore}} +and {\tttf \rootfloatparameter {sidespaceafter}} respectively. The \type +{sidealign} parameter is always winning from a keyword doing the same. + +The last few examples demonstrate that you can define an instance. Often that's +the best way to deal with special cases in a consistent way. For instance: + +\starttyping +\definefloat + [LeftTwo] + [figure] + +\setupfloat + [LeftTwo] + [default=left, + sidealign=line] +\stoptyping + +First we show some keyword variant, next some parameter driven versions. + +\def\SampleKeyword#1% + {\setbuffer[foo] + \useMPlibrary[dum] + \setupbodyfont[dejavu] + \setuplayout[page] + \placefigure[left]{}{\externalfigure[dummy]} \samplefile{sapolsky} \samplefile{sapolsky} + \placefigure[#1] {}{\externalfigure[dummy]} \samplefile{sapolsky} \samplefile{sapolsky} + \endbuffer + \framed + [background=color,backgroundcolor=white,offset=overlay] + {\scale + [width=.45\textwidth] + {\typesetbuffer[foo]}}} + +\def\SampleSettings#1#2#3% + {\setbuffer[foo] + \useMPlibrary[dum] + \setupbodyfont[dejavu] + \setuplayout[page] + \definefloat[#1][figure] + \setupfloat[#1][default=left] + \definefloat[#2][figure] + \setupfloat[#2][#3] + \startplacefloat[#1] \externalfigure[dummy] \stopplacefloat \samplefile{sapolsky} \samplefile{sapolsky} + \startplacefloat[#2] \externalfigure[dummy] \stopplacefloat \samplefile{sapolsky} \samplefile{sapolsky} + \endbuffer + \framed + [background=color,backgroundcolor=white,offset=overlay] + {\scale + [width=.45\textwidth] + {\typesetbuffer[foo]}}} + +\startbuffer[LeftOne] +\definefloat[LeftOne][figure] + +\setupfloat + [LeftOne] + [default=left] +\stopbuffer + +\startbuffer[LeftTwo] +\definefloat[LeftTwo][figure] + +\setupfloat + [LeftTwo] + [default=left, + sidealign=line] +\stopbuffer + +\startbuffer[LeftThree] +\definefloat[LeftThree][figure] + +\setupfloat + [LeftThree] + [default={left,2*line}] +\stopbuffer + +\startbuffer[LeftFour] +\definefloat[LeftFour][figure] + +\setupfloat + [LeftFour] + [default={left}, + topoffset=5pt] +\stopbuffer + +\startbuffer[LeftFive] +\definefloat[LeftFive][figure] + +\setupfloat + [LeftFive] + [default={left}, + bottomoffset=5pt, + topoffset=5pt] +\stopbuffer + +\startlinecorrection +\startcombination[2*2] + {\SampleKeyword{left,high}} {\type{left,high}} + {\SampleKeyword{left,low}} {\type{left,low}} + {\SampleKeyword{left,high,low}} {\type{left,high,low}} + {\SampleKeyword{left,fit}} {\type{left,fit}} +\stopcombination +\stoplinecorrection + +\startlinecorrection +\startcombination[2*2] + {\SampleKeyword{left,halfline}} {\type{left,halfline}} + {\SampleKeyword{left,height}} {\type{left,height}} + {\SampleKeyword{left,depth}} {\type{left,depth}} + {\SampleKeyword{left,grid}} {\type{left,grid}} +\stopcombination +\stoplinecorrection + +\startlinecorrection +\startcombination[2*2] + {\SampleKeyword{left,line}} {\type{left,line}} + {\SampleKeyword{left,1*line}} {\type{left,1*line}} + {\SampleKeyword{left,2*line}} {\type{left,2*line}} + {\SampleKeyword{left,3*line}} {\type{left,3*line}} +\stopcombination +\stoplinecorrection + +\startlinecorrection +\startcombination[2*2] + {\SampleSettings{LeftOne}{LeftTwo} {default={left,line}}} + {\typ{default={left,line}}} + {\SampleSettings{LeftOne}{LeftThree}{default={left,2*line}}} + {\typ{default={left,2*line}}} + {\SampleSettings{LeftOne}{LeftFour} {default=left,topoffset=5pt}} + {\typ{default=left, topoffset=5pt}} + {\SampleSettings{LeftOne}{LeftFive} {default=left, topoffset=5pt, bottomoffset=5pt}} + {\typ{default=left, topoffset=5pt, bottomoffset=5pt}} +\stopcombination +\stoplinecorrection + +There is some tracing built in but as this mechanism is rather complex it only +gives an idea about what is going on. Here is an example: + +\startbuffer[one] +\enabletrackers[floats.anchoring] + +\showframe + +\setupfloat + [sidespacebefore=big, + sidespaceafter=big] + +\starttext + \dorecurse{10}{ + \placefigure[left]{#1.1}{} + a small sentence \par + \placefigure[left]{#1.2}{} + a small sentence \par + \input klein \par + } +\stoptext +\stopbuffer + +\typebuffer[one] + +In \in {figure} [fig:side:one:1] and \in {figure} [fig:side:one:2] you see the +first two pages of the typeset result. + +The anchor to the text is showed in orange and an optional shift in red. The content +is in green and a depth compensation in magenta. Dummy lines added for proper +spacing as well as progressing beyond a previous float are in blue. + +\startplacefigure[title={Side float tracing example 1, page 1.},reference=fig:side:one:1] + \scale[width=\textwidth]{\typesetbuffer[one][page=1]} +\stopplacefigure + +\startplacefigure[title={Side float tracing example 1, page 2.},reference=fig:side:one:2] + \scale[width=\textwidth]{\typesetbuffer[one][page=2]} +\stopplacefigure + +A second example that uses different settings is shown in \in {figure} +[fig:side:two:1] and \in {figure} [fig:side:two:2]. + +\startbuffer[two] +\enabletrackers[floats.anchoring] + +\setupfloat + [sidespacebefore=, + sidespaceafter=big, + step=small] + +\showframe + +\starttext + \dorecurse{10}{ + \placefigure[left]{#1.1}{} + a small sentence \par + \placefigure[left]{#1.2}{} + a small sentence \par + \input klein \par + } +\stoptext +\stopbuffer + +\typebuffer[two] + +\startplacefigure[title={Side float tracing example 2, page 1.},reference=fig:side:two:1] + \framed + [background=color,backgroundcolor=white,offset=overlay] + {\scale[width=\textwidth]{\typesetbuffer[two][page=1]}} +\stopplacefigure + +\startplacefigure[title={Side float tracing example 2, page 2.},reference=fig:side:two:2] + \framed + [background=color,backgroundcolor=white,offset=overlay] + {\scale[width=\textwidth]{\typesetbuffer[two][page=2]}} +\stopplacefigure + +\startbuffer[three] +\usemodule[simulate] + +\setuplayout + [tight] + +\setupbodyfont + [dejavu] + +\enabletrackers + [floats.anchoring] + +\setupfloats + [sidethreshold=.5\strutdp, % default, use "old" for previous implementation + step=small] + +\definemeasure[MyHeight][3cm] +\definemeasure[MyWidth] [3cm] + +% \setupheadertexts +% [width=\measure{MyWidth}\quad height=\measure{MyHeight}] + +\unexpanded\def\FakeWords#1% + {\simulatewords + [n=#1,m=#1,min=1,max=5,hyphen=no,color=text,line=yes,random=1234]} + +\starttext + +\startbuffer + \FakeWords{100}\par + \placefigure + [left] {oeps} + {\framed[width=\measure{MyWidth},height=\measure{MyHeight}]{}} + \FakeWords {2}\par + \FakeWords {3}\par + \FakeWords {5}\par + \FakeWords {4}\par + \FakeWords{200}\par + \placefigure + [left] {oeps} + {\framed[width=\measure{MyWidth},height=\measure{MyHeight}]{}} + \FakeWords{200}\par +\stopbuffer + +\dostepwiserecurse {\number\dimexpr3cm} {\number\dimexpr4cm} {\number\dimexpr0.25cm} { + \definemeasure[MyWidth][#1sp] + \dostepwiserecurse {\number\dimexpr3cm} {\number\dimexpr4cm} {\number\dimexpr0.25cm} { + \definemeasure[MyHeight][##1sp] + \start + \setupwhitespace[none] + \getbuffer \page + \stop + \start + \setupwhitespace[big] + \getbuffer \page + \stop + } +} +\stoptext +\stopbuffer + +Progressing next to a side float and determining how many lines to indent is a +somewhat complex mechamism because many factors play a role and spacing can +interfere badly. The decision about the number of lines to hang is to some extend +controllable but there are cases when you need to steer it (for instance by +scaling an image). In the next overviews we see the result of the following +somewhat complex setup: + +\typebuffer[three] + +The \type {step} parameter controls how we fill up the space when we need to +progress beyond it for instance because another float shows up or because we +issue a \type {\flushsidefloats}. Its value can be \type {big}, \type {medium} or +\type {small} and defaults to \type {small} which gives of enough precision. The +\type {sidethreshold} parameter controls the number of lines that we hang around +the float. Here we only show the consequence of the the threshold. A larger +threshold result in mode whitespace below the side float. You can zoom in to see +what happens at the bottom of the float (or run the examples yourself). + +\def\ShowSample#1% + {\framed + [background=color,backgroundcolor=white,offset=overlay] + {\scale + [width=\dimexpr(\textwidth-2\emwidth)/3\relax] + {\typesetbuffer[three][page=#1]}}} + +\startplacefigure[title={The working of default step and side threshold (no whitespace.},reference=fig:side:three:1] + \startcombination[3*3] + {\ShowSample {1}} {} {\ShowSample {3}} {} {\ShowSample {5}} {} + {\ShowSample {7}} {} {\ShowSample {9}} {} {\ShowSample {9}} {} + {\ShowSample{11}} {} {\ShowSample{13}} {} {\ShowSample{15}} {} + \stopcombination +\stopplacefigure + +\startplacefigure[title={The working of default step and side threshold (whitespace).},reference=fig:side:three:2] + \startcombination[3*3] + {\ShowSample {2}} {} {\ShowSample {4}} {} {\ShowSample {6}} {} + {\ShowSample {8}} {} {\ShowSample{10}} {} {\ShowSample{12}} {} + {\ShowSample{12}} {} {\ShowSample{14}} {} {\ShowSample{15}} {} + \stopcombination +\stopplacefigure + +\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/libraries/libraries-mkiv.tex b/doc/context/sources/general/manuals/libraries/libraries-mkiv.tex new file mode 100644 index 000000000..67ca75966 --- /dev/null +++ b/doc/context/sources/general/manuals/libraries/libraries-mkiv.tex @@ -0,0 +1,199 @@ +% 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. + +\usemodule[art-01,abr-02] + +\definecolor + [maincolor] + [r=.4] + +\definecolor + [extracolor] + [g=.4] + +\setupbodyfont + [11pt] + +\setuptype + [color=maincolor] + +\setuptyping + [color=maincolor] + +\definefontsynonym + [TitlePageMono] + [file:lmmonoproplt10-bold*default] + +\setuphead + [color=maincolor] + +\usesymbols + [cc] + +\setupinteraction + [hidden] + +\loadfontgoodies[lm] + +\startdocument + [metadata:author=Hans Hagen, + metadata:title=Libraries in ConTeXt, + author=Hans Hagen, + affiliation=PRAGMA ADE, + location=Hasselt NL, + title=Libraries in \ConTeXt, + support=www.contextgarden.net, + website=www.pragma-ade.nl] + +\startluasetups[swiglib] + context.nohyphens() + for i=1,640 do + context.definedfont { string.formatters["TitlePageMono at %p"](65536*(10+math.random(5))) } + context("Libraries ") + end + context.removeunwantedspaces() +\stopluasetups + +\startMPpage + +StartPage ; + + fill Page enlarged 1cm withcolor \MPcolor{extracolor} ; + + draw textext("\framed[loffset=2pt,roffset=2pt,frame=off,width=\paperwidth,align={normal,paragraph,verytolerant,stretch}]{\luasetup{swiglib}}") + xysized (PaperWidth,PaperHeight) + shifted center Page + withcolor .8white ; + + draw textext.ulft("\definedfont[TitlePageMono]basics") + xsized .75PaperWidth + shifted lrcorner Page + shifted (-1cm,2cm) + withcolor \MPcolor{maincolor} ; + + % draw textext.ulft("\definedfont[TitlePageMono]in context mkiv") + % xsized .6PaperWidth + % shifted lrcorner Page + % shifted (-1cm,6cm) + % withcolor \MPcolor{maincolor} ; + +StopPage ; + +\stopMPpage + +\dontcomplain + +\startsubject[title=Contents] + +\placelist[section][alternative=a] + +\stopsubject + +\startsection[title=Introduction] + +Not long after we released \LUATEX\ 1.0, we started experimenting a bit more with +so called foreign function interface: \FFI. Originally that interface to external +libraries was only available in \LUAJITTEX, but a good and compatible alternative +is now also available in the normal engine too. For users it is not that relevant +to know how it works, as long as it works. It means that in addition to \SWIGLIB\ +we have a method that doesn't demand compilation as it uses normal (public) +libraries. + +Of course one needs to make sure that the right version of a library is used. +And, as there is the danger of the \API\ having been changed in an incompatible +way one can wonder if such a dependency is really what one wants. On the other +hand one can expect \CONTEXT\ to keep up. + +Do you really need libraries? For instance does it really make sense to use curl, +ghostscript or graphicmagic libraries while the command line version is +(normally) just as efficient and avoids a dependency. This is even more true if +you realizes that for instance a fetch or conversion only needs to happen once +per run or in fact only when there is some change in the resource. + +On the other hand, when accessing databases one can avoid the often slower +command line calls and save the hassle of intermediate files. Here efficiency +wins. Also, when \CONTEXT\ is used in a high performance database backend +application a distribution and the used libraries are not updated on a daily +basis. + +\stopsection + +\startsection[title=Supported] + +Apart from some experiments we currently can use \FFI\ interfaced libraries in: + +\starttabulate[|l|l|l|l|l|] +\FL +\BC module \BC library \BC windows \BC unix \NC \NR +\ML +\NC util-crl \NC curl \NC libcurl \NC libcurl \NC \NR % todo: client and ffi +\NC util-sql-imp-ffi \NC mysql \NC libmysql \NC libmysqlclient \NC \NR +\NC util-sql-imp-sqlite \NC sqlite \NC sqlite3 \NC sqlite3 \NC \NR +%NC font-phb-imp-library \NC harfbuzz \NC libharfbuzz \NC libharfbuzz \NC \NR % for testing uniscribe (idris fonts) +%NC \NC ghostscript \NC \NC \NC \NR % only a few experiments +%NC \NC graphicmagick \NC \NC \NC \NR % only a few experiments +\LL +\stoptabulate + +The profiler that we occasionally use to identify bottlenecks in the engine (for +instance when we upgrade \LUA) uses \FFI\ to provide access to the high resolution +timers but this is typically different per platform. + +One problem with libraries, especially on \WINDOWS\ is that the library is found on +some system path and it can happen that multiple programs ship the same library but in +different versions. You can try to play safe and put libraries in the \TEX\ tree, for +instance on my system they are in: + +\starttyping +c:/data/tex-context/tex/texmf-win64/bin/lib/luatex/lua/whatever/libwhatever.dll +\stoptyping + +You can trace where libraries are looked for with: + +\starttyping +\enabletrackers[resolvers.ffilib] +\stoptyping + +or in \LUA\ with: + +\starttyping +trackers.enable("resolvers.ffilib") +\stoptyping + +The library is first located on one of the valid \TDS\ paths (these are sort of +standardized in \TEX\ distributions) and then using the normal \FFI\ loader. + +As this is all still experimental in \LUATEX\ there is not much more to say about +it now. Of course this kind of specialized support to a large degree depends on +the need to use it. + +\stopsection + +\startsection[title=Colofon] + +\starttabulate[|B|p|] +\NC author \NC \getvariable{document}{author}, \getvariable{document}{affiliation}, \getvariable{document}{location} \NC \NR +\NC version \NC \currentdate \NC \NR +\NC website \NC \getvariable{document}{website} \endash\ \getvariable{document}{support} \NC \NR +\NC comment \NC many thanks to Luigi Scarso for taking care of ffi support in the engines \NC \NR +\stoptabulate + +\stopsection + +\stopdocument diff --git a/doc/context/sources/general/manuals/luatex/luatex-enhancements.tex b/doc/context/sources/general/manuals/luatex/luatex-enhancements.tex index 19f88234a..d1da33878 100644 --- a/doc/context/sources/general/manuals/luatex/luatex-enhancements.tex +++ b/doc/context/sources/general/manuals/luatex/luatex-enhancements.tex @@ -55,7 +55,7 @@ chapters on fonts and math we discuss a few more new ones. There are three new primitives to test the version of \LUATEX: \starttabulate[|l|pl|pl|] -\NC \bf primitive \NC \bf explanation \NC \bf value \NC \NR +\BC primitive \BC explanation \BC value \NC \NR \NC \type {\luatexbanner} \NC the banner reported on the command line \NC \luatexbanner \NC \NR \NC \type {\luatexversion} \NC a combination of major and minor number \NC \the\luatexversion \NC \NR \NC \type {\luatexrevision} \NC the revision number, the current value is \NC \luatexrevision \NC \NR @@ -550,6 +550,16 @@ $ x + 1 = a $ \stoptyping +\subsection{\type {\suppressprimitiveerror}} + +When set to a non|-|zero value the following command will not issue an error: + +\starttyping +\suppressprimitiveerror = 1 + +\primitive\notaprimitive +\stoptyping + \section {Math} \subsection{Extensions} @@ -881,6 +891,20 @@ ignores the value. This allows for embedded spaces, without the need for double quotes. Macro expansion takes place inside the argument. +The \type {\tracingfonts} primitive that has been inherited from \PDFTEX\ has +been adapted to support variants in reporting the font. The reason for this +extension is that a csname not always makes sense. The zero case is the default. + +\starttabulate[|T||] +\NC 0 \EQ \type{\foo xyz} \NC \NR +\NC 1 \EQ \type{\foo (bar)} \NC \NR +\NC 2 \EQ \type{<bar> xyz} \NC \NR +\NC 3 \EQ \type{<bar @ ..pt> xyz} \NC \NR +\NC 4 \EQ \type{<id>} \NC \NR +\NC 5 \EQ \type{<id: bar>} \NC \NR +\NC 6 \EQ \type{<id: bar @ ..pt> xyz} \NC \NR +\stoptabulate + \subsection{Writing to file} You can now open upto 127 files with \type {\openout}. When no file is open diff --git a/doc/context/sources/general/manuals/luatex/luatex-fonts.tex b/doc/context/sources/general/manuals/luatex/luatex-fonts.tex index 221c0ce85..ddb64d946 100644 --- a/doc/context/sources/general/manuals/luatex/luatex-fonts.tex +++ b/doc/context/sources/general/manuals/luatex/luatex-fonts.tex @@ -22,92 +22,106 @@ The column \quote {\VF} means that this key will be created by the \type The top|-|level keys in the table are as follows: -\starttabulate[|Tl|c|c|c|l|p|] -\NC \rmbf key \NC \bf vf \NC \bf tfm \NC \bf used \NC \bf value type \NC \bf description \NC \NR -\NC name \NC yes \NC yes \NC yes \NC string \NC metric (file) name \NC \NR -\NC area \NC no \NC yes \NC yes \NC string \NC (directory) location, typically empty \NC \NR -\NC used \NC no \NC yes \NC yes \NC boolean\NC indicates usage (initial: false) \NC \NR -\NC characters \NC yes \NC yes \NC yes \NC table \NC the defined glyphs of this font \NC \NR -\NC checksum \NC yes \NC yes \NC no \NC number \NC default: 0 \NC \NR -\NC designsize \NC no \NC yes \NC yes \NC number \NC expected size (default: 655360 == 10pt) \NC \NR -\NC direction \NC no \NC yes \NC yes \NC number \NC default: 0 \NC \NR -\NC encodingbytes \NC no \NC no \NC yes \NC number \NC default: depends on \type {format} \NC \NR -\NC encodingname \NC no \NC no \NC yes \NC string \NC encoding name \NC \NR -\NC fonts \NC yes \NC no \NC yes \NC table \NC locally used fonts \NC \NR -\NC psname \NC no \NC no \NC yes \NC string \NC This is the \POSTSCRIPT\ fontname in the incoming font - source, and it's used as fontname identifier in the \PDF\ - output. This has to be a valid string, e.g.\ no spaces - and such, as the backend will not do a cleanup. This gives - complete control to the loader. \NC \NR -\NC fullname \NC no \NC no \NC yes \NC string \NC output font name, used as a fallback in the \PDF\ output - if the \type {psname} is not set \NC \NR -\NC header \NC yes \NC no \NC no \NC string \NC header comments, if any \NC \NR -\NC hyphenchar \NC no \NC no \NC yes \NC number \NC default: \TEX's \type {\hyphenchar} \NC \NR -\NC parameters \NC no \NC yes \NC yes \NC hash \NC default: 7 parameters, all zero \NC \NR -\NC size \NC no \NC yes \NC yes \NC number \NC loaded (at) size. (default: same as designsize) \NC \NR -\NC skewchar \NC no \NC no \NC yes \NC number \NC default: \TEX's \type {\skewchar} \NC \NR -\NC type \NC yes \NC no \NC yes \NC string \NC basic type of this font \NC \NR -\NC format \NC no \NC no \NC yes \NC string \NC disk format type \NC \NR -\NC embedding \NC no \NC no \NC yes \NC string \NC \PDF\ inclusion \NC \NR -\NC filename \NC no \NC no \NC yes \NC string \NC the name of the font on disk \NC \NR -\NC tounicode \NC no \NC yes \NC yes \NC number \NC When this is set to~1 \LUATEX\ assumes per|-|glyph - tounicode entries are present in the font. \NC \NR -\NC stretch \NC no \NC no \NC yes \NC number \NC the \quote {stretch} value from \type - {\expandglyphsinfont} \NC \NR -\NC shrink \NC no \NC no \NC yes \NC number \NC the \quote {shrink} value from \type - {\expandglyphsinfont} \NC \NR -\NC step \NC no \NC no \NC yes \NC number \NC the \quote {step} value from \type - {\expandglyphsinfont} \NC \NR -\NC auto_expand \NC no \NC no \NC yes \NC boolean\NC the \quote {autoexpand} keyword from \crlf - \type {\expandglyphsinfont} \NC \NR -\NC expansion_factor \NC no \NC no \NC no \NC number \NC the actual expansion factor of an expanded font \NC \NR -\NC attributes \NC no \NC no \NC yes \NC string \NC the \type {\pdffontattr} \NC \NR -\NC cache \NC no \NC no \NC yes \NC string \NC This key controls caching of the \LUA\ table on the - \TEX\ end where \type {yes} means: use a reference to - the table that is passed to \LUATEX\ (this is the - default), and no \type {no} means: don't store the - table reference, don't cache any \LUA\ data for this - font while \type {renew} means: don't store the table - reference, but save a reference to the table that is - created at the first access to one of its fields in font. - Note: the saved reference is thread|-|local, so be - careful when you are using coroutines: an error will be - thrown if the table has been cached in one thread, but - you reference it from another thread. \NC \NR -\NC nomath \NC no \NC no \NC yes \NC boolean\NC This key allows a minor speedup for text fonts. If it - is present and true, then \LUATEX\ will not check the - character entries for math|-|specific keys. \NC \NR -\NC oldmath \NC no \NC no \NC yes \NC boolean\NC This key flags a font as representing an old school \TEX\ - math font and disables the \OPENTYPE\ code path. \NC \NR -\NC slant \NC no \NC no \NC yes \NC number \NC This has the same semantics as the \type {SlantFont} - operator in font map files. \NC \NR -\NC extent \NC no \NC no \NC yes \NC number \NC This has the same semantics as the \type {ExtendFont} - operator in font map files. \NC \NR +\starttabulate[|l|c|c|c|l|p|] +\BC key \BC vf \BC tfm \BC used \BC value type \BC description \NC \NR +\NC \type{name} \NC yes \NC yes \NC yes \NC string \NC metric (file) name \NC \NR +\NC \type{area} \NC no \NC yes \NC yes \NC string \NC (directory) location, typically empty \NC \NR +\NC \type{used} \NC no \NC yes \NC yes \NC boolean \NC indicates usage (initial: false) \NC \NR +\NC \type{characters} \NC yes \NC yes \NC yes \NC table \NC the defined glyphs of this font \NC \NR +\NC \type{checksum} \NC yes \NC yes \NC no \NC number \NC default: 0 \NC \NR +\NC \type{designsize} \NC no \NC yes \NC yes \NC number \NC expected size (default: 655360 == 10pt) \NC \NR +\NC \type{direction} \NC no \NC yes \NC yes \NC number \NC default: 0 \NC \NR +\NC \type{encodingbytes} \NC no \NC no \NC yes \NC number \NC default: depends on \type {format} \NC \NR +\NC \type{encodingname} \NC no \NC no \NC yes \NC string \NC encoding name \NC \NR +\NC \type{fonts} \NC yes \NC no \NC yes \NC table \NC locally used fonts \NC \NR +\NC \type{psname} \NC no \NC no \NC yes \NC string \NC This is the \POSTSCRIPT\ fontname in the incoming font + source, and it's used as fontname identifier in the \PDF\ + output. This has to be a valid string, e.g.\ no spaces + and such, as the backend will not do a cleanup. This gives + complete control to the loader. \NC \NR +\NC \type{fullname} \NC no \NC no \NC yes \NC string \NC output font name, used as a fallback in the \PDF\ output + if the \type {psname} is not set \NC \NR +\NC \type{header} \NC yes \NC no \NC no \NC string \NC header comments, if any \NC \NR +\NC \type{hyphenchar} \NC no \NC no \NC yes \NC number \NC default: \TEX's \type {\hyphenchar} \NC \NR +\NC \type{parameters} \NC no \NC yes \NC yes \NC hash \NC default: 7 parameters, all zero \NC \NR +\NC \type{size} \NC no \NC yes \NC yes \NC number \NC loaded (at) size. (default: same as designsize) \NC \NR +\NC \type{skewchar} \NC no \NC no \NC yes \NC number \NC default: \TEX's \type {\skewchar} \NC \NR +\NC \type{type} \NC yes \NC no \NC yes \NC string \NC basic type of this font \NC \NR +\NC \type{format} \NC no \NC no \NC yes \NC string \NC disk format type \NC \NR +\NC \type{embedding} \NC no \NC no \NC yes \NC string \NC \PDF\ inclusion \NC \NR +\NC \type{filename} \NC no \NC no \NC yes \NC string \NC the name of the font on disk \NC \NR +\NC \type{tounicode} \NC no \NC yes \NC yes \NC number \NC When this is set to~1 \LUATEX\ assumes per|-|glyph + tounicode entries are present in the font. \NC \NR +\NC \type{stretch} \NC no \NC no \NC yes \NC number \NC the \quote {stretch} value from \type + {\expandglyphsinfont} \NC \NR +\NC \type{shrink} \NC no \NC no \NC yes \NC number \NC the \quote {shrink} value from \type + {\expandglyphsinfont} \NC \NR +\NC \type{step} \NC no \NC no \NC yes \NC number \NC the \quote {step} value from \type + {\expandglyphsinfont} \NC \NR +\NC \type{expansion_factor} \NC no \NC no \NC no \NC number \NC the actual expansion factor of an expanded font \NC \NR +\NC \type{attributes} \NC no \NC no \NC yes \NC string \NC the \type {\pdffontattr} \NC \NR +\NC \type{cache} \NC no \NC no \NC yes \NC string \NC This key controls caching of the \LUA\ table on the + \TEX\ end where \type {yes} means: use a reference to + the table that is passed to \LUATEX\ (this is the + default), and no \type {no} means: don't store the + table reference, don't cache any \LUA\ data for this + font while \type {renew} means: don't store the table + reference, but save a reference to the table that is + created at the first access to one of its fields in font. + Note: the saved reference is thread|-|local, so be + careful when you are using coroutines: an error will be + thrown if the table has been cached in one thread, but + you reference it from another thread. \NC \NR +\NC \type{nomath} \NC no \NC no \NC yes \NC boolean \NC This key allows a minor speedup for text fonts. If it + is present and true, then \LUATEX\ will not check the + character entries for math|-|specific keys. \NC \NR +\NC \type{oldmath} \NC no \NC no \NC yes \NC boolean \NC This key flags a font as representing an old school \TEX\ + math font and disables the \OPENTYPE\ code path. \NC \NR +\NC \type{slant} \NC no \NC no \NC yes \NC number \NC This has the same semantics as the \type {SlantFont} + operator in font map files. \NC \NR +\NC \type{extent} \NC no \NC no \NC yes \NC number \NC This has the same semantics as the \type {ExtendFont} + operator in font map files. \NC \NR \stoptabulate The key \type {name} is always required. The keys \type {stretch}, \type -{shrink}, \type {step} and optionally \type {auto_expand} only have meaning when -used together: they can be used to replace a post|-|loading \type -{\expandglyphsinfont} command. The \type {expansion_factor} is value that can be -present inside a font in \type {font.fonts}. It is the actual expansion factor (a -value between \type {-shrink} and \type {stretch}, with step \type {step}) of a -font that was automatically generated by the font expansion algorithm. The key -\type {attributes} can be used to set font attributes in the \PDF\ file. The key -\type {used} is set by the engine when a font is actively in use, this makes sure -that the font's definition is written to the output file (\DVI\ or \PDF). The -\TFM\ reader sets it to false. The \type {direction} is a number signalling the -\quote {normal} direction for this font. There are sixteen possibilities: - -\starttabulate[|Tc|Tc|Tc|Tc|] -\NC \rmbf number \NC \rmbf meaning \NC \rmbf number \NC \rmbf meaning \NC\NR -\NC 0 \NC LT \NC 8 \NC TT \NC\NR -\NC 1 \NC LL \NC 9 \NC TL \NC\NR -\NC 2 \NC LB \NC 10 \NC TB \NC\NR -\NC 3 \NC LR \NC 11 \NC TR \NC\NR -\NC 4 \NC RT \NC 12 \NC BT \NC\NR -\NC 5 \NC RL \NC 13 \NC BL \NC\NR -\NC 6 \NC RB \NC 14 \NC BB \NC\NR -\NC 7 \NC RR \NC 15 \NC BR \NC\NR +{shrink}, \type {step} only have meaning when used together: they can be used to +replace a post|-|loading \type {\expandglyphsinfont} command. The \type +{auto_expand} option is not supported in \LUATEX. In fact, the primitives +that create expanded or protruding copies are probably only useful when used with +traditional fonts because all these extra \OPENTYPE\ properties are kept out of +the picture. The \type {expansion_factor} is value that can be present inside a +font in \type {font.fonts}. It is the actual expansion factor (a value between +\type {-shrink} and \type {stretch}, with step \type {step}) of a font that was +automatically generated by the font expansion algorithm. + +Because we store the actual state of expansion with each glyph and don't have +special font instances, we can change some font related parameters before lines +are constructed, like: + +\starttyping +font.setexpansion(font.current(),100,100,20) +\stoptyping + +This is mostly meant for experiments (or an optimizing routing written in \LUA) +so there is no primitive. + +The key \type {attributes} can be used to set font attributes in the \PDF\ file. +The key \type {used} is set by the engine when a font is actively in use, this +makes sure that the font's definition is written to the output file (\DVI\ or +\PDF). The \TFM\ reader sets it to false. The \type {direction} is a number +signalling the \quote {normal} direction for this font. There are sixteen +possibilities: + +\starttabulate[|c|c|c|c|] +\BC number \BC meaning \BC number \BC meaning \NC \NR +\NC \type{0} \NC \type{LT} \NC \type {8} \NC \type{TT} \NC \NR +\NC \type{1} \NC \type{LL} \NC \type {9} \NC \type{TL} \NC \NR +\NC \type{2} \NC \type{LB} \NC \type{10} \NC \type{TB} \NC \NR +\NC \type{3} \NC \type{LR} \NC \type{11} \NC \type{TR} \NC \NR +\NC \type{4} \NC \type{RT} \NC \type{12} \NC \type{BT} \NC \NR +\NC \type{5} \NC \type{RL} \NC \type{13} \NC \type{BL} \NC \NR +\NC \type{6} \NC \type{RB} \NC \type{14} \NC \type{BB} \NC \NR +\NC \type{7} \NC \type{RR} \NC \type{15} \NC \type{BR} \NC \NR \stoptabulate These are \OMEGA|-|style direction abbreviations: the first character indicates @@ -123,15 +137,15 @@ gives a nicer user interface. The names and their internal remapping are: -\starttabulate[|lT|c|] -\NC \rmbf name \NC \rmbf remapping \NC\NR -\NC slant \NC 1 \NC\NR -\NC space \NC 2 \NC\NR -\NC space_stretch \NC 3 \NC\NR -\NC space_shrink \NC 4 \NC\NR -\NC x_height \NC 5 \NC\NR -\NC quad \NC 6 \NC\NR -\NC extra_space \NC 7 \NC\LR +\starttabulate[|l|c|] +\BC name \BC remapping \NC \NR +\NC \type {slant} \NC 1 \NC \NR +\NC \type {space} \NC 2 \NC \NR +\NC \type {space_stretch} \NC 3 \NC \NR +\NC \type {space_shrink} \NC 4 \NC \NR +\NC \type {x_height} \NC 5 \NC \NR +\NC \type {quad} \NC 6 \NC \NR +\NC \type {extra_space} \NC 7 \NC \NR \stoptabulate The keys \type {type}, \type {format}, \type {embedding}, \type {fullname} and @@ -182,29 +196,29 @@ Each character hash itself is a hash. For example, here is the character \quote The following top|-|level keys can be present inside a character hash: -\starttabulate[|lT|c|c|c|l|p|] -\NC \rmbf key \NC \bf vf \NC \bf tfm \NC \bf used \NC \bf type \NC \bf description \NC\NR -\NC width \NC yes \NC yes \NC yes \NC number \NC character's width, in sp (default 0) \NC\NR -\NC height \NC no \NC yes \NC yes \NC number \NC character's height, in sp (default 0) \NC\NR -\NC depth \NC no \NC yes \NC yes \NC number \NC character's depth, in sp (default 0) \NC\NR -\NC italic \NC no \NC yes \NC yes \NC number \NC character's italic correction, in sp (default zero) \NC\NR -\NC top_accent \NC no \NC no \NC maybe \NC number \NC character's top accent alignment place, in sp (default zero) \NC\NR -\NC bot_accent \NC no \NC no \NC maybe \NC number \NC character's bottom accent alignment place, in sp (default zero) \NC\NR -\NC left_protruding \NC no \NC no \NC maybe \NC number \NC character's \type {\lpcode} \NC\NR -\NC right_protruding \NC no \NC no \NC maybe \NC number \NC character's \type {\rpcode} \NC\NR -\NC expansion_factor \NC no \NC no \NC maybe \NC number \NC character's \type {\efcode} \NC\NR -\NC tounicode \NC no \NC no \NC maybe \NC string \NC character's \UNICODE\ equivalent(s), in \UTF|-|16BE hexadecimal format \NC\NR -\NC next \NC no \NC yes \NC yes \NC number \NC the \quote {next larger} character index \NC\NR -\NC extensible \NC no \NC yes \NC yes \NC table \NC the constituent parts of an extensible recipe \NC\NR -\NC vert_variants \NC no \NC no \NC yes \NC table \NC constituent parts of a vertical variant set \NC \NR -\NC horiz_variants \NC no \NC no \NC yes \NC table \NC constituent parts of a horizontal variant set \NC \NR -\NC kerns \NC no \NC yes \NC yes \NC table \NC kerning information \NC\NR -\NC ligatures \NC no \NC yes \NC yes \NC table \NC ligaturing information \NC\NR -\NC commands \NC yes \NC no \NC yes \NC array \NC virtual font commands \NC\NR -\NC name \NC no \NC no \NC no \NC string \NC the character (\POSTSCRIPT) name \NC\NR -\NC index \NC no \NC no \NC yes \NC number \NC the (\OPENTYPE\ or \TRUETYPE) font glyph index \NC\NR -\NC used \NC no \NC yes \NC yes \NC boolean \NC typeset already (default: false)? \NC\NR -\NC mathkern \NC no \NC no \NC yes \NC table \NC math cut-in specifications \NC\NR +\starttabulate[|l|c|c|c|l|p|] +\BC key \BC vf \BC tfm \BC used \BC type \BC description \NC\NR +\NC \type{width} \NC yes \NC yes \NC yes \NC number \NC character's width, in sp (default 0) \NC\NR +\NC \type{height} \NC no \NC yes \NC yes \NC number \NC character's height, in sp (default 0) \NC\NR +\NC \type{depth} \NC no \NC yes \NC yes \NC number \NC character's depth, in sp (default 0) \NC\NR +\NC \type{italic} \NC no \NC yes \NC yes \NC number \NC character's italic correction, in sp (default zero) \NC\NR +\NC \type{top_accent} \NC no \NC no \NC maybe \NC number \NC character's top accent alignment place, in sp (default zero) \NC\NR +\NC \type{bot_accent} \NC no \NC no \NC maybe \NC number \NC character's bottom accent alignment place, in sp (default zero) \NC\NR +\NC \type{left_protruding} \NC no \NC no \NC maybe \NC number \NC character's \type {\lpcode} \NC\NR +\NC \type{right_protruding} \NC no \NC no \NC maybe \NC number \NC character's \type {\rpcode} \NC\NR +\NC \type{expansion_factor} \NC no \NC no \NC maybe \NC number \NC character's \type {\efcode} \NC\NR +\NC \type{tounicode} \NC no \NC no \NC maybe \NC string \NC character's \UNICODE\ equivalent(s), in \UTF|-|16BE hexadecimal format \NC\NR +\NC \type{next} \NC no \NC yes \NC yes \NC number \NC the \quote {next larger} character index \NC\NR +\NC \type{extensible} \NC no \NC yes \NC yes \NC table \NC the constituent parts of an extensible recipe \NC\NR +\NC \type{vert_variants} \NC no \NC no \NC yes \NC table \NC constituent parts of a vertical variant set \NC \NR +\NC \type{horiz_variants} \NC no \NC no \NC yes \NC table \NC constituent parts of a horizontal variant set \NC \NR +\NC \type{kerns} \NC no \NC yes \NC yes \NC table \NC kerning information \NC\NR +\NC \type{ligatures} \NC no \NC yes \NC yes \NC table \NC ligaturing information \NC\NR +\NC \type{commands} \NC yes \NC no \NC yes \NC array \NC virtual font commands \NC\NR +\NC \type{name} \NC no \NC no \NC no \NC string \NC the character (\POSTSCRIPT) name \NC\NR +\NC \type{index} \NC no \NC no \NC yes \NC number \NC the (\OPENTYPE\ or \TRUETYPE) font glyph index \NC\NR +\NC \type{used} \NC no \NC yes \NC yes \NC boolean \NC typeset already (default: false)? \NC\NR +\NC \type{mathkern} \NC no \NC no \NC yes \NC table \NC math cut-in specifications \NC\NR \stoptabulate The values of \type {top_accent}, \type {bot_accent} and \type {mathkern} are @@ -236,26 +250,26 @@ present. It in in turn can be overruled by \type {vert_variants}. The \type {extensible} table is very simple: -\starttabulate[|lT|l|p|] -\NC \rmbf key \NC \bf type \NC \bf description \NC\NR -\NC top \NC number \NC top character index \NC\NR -\NC mid \NC number \NC middle character index \NC\NR -\NC bot \NC number \NC bottom character index \NC\NR -\NC rep \NC number \NC repeatable character index \NC\NR +\starttabulate[|l|l|p|] +\BC key \BC type \BC description \NC\NR +\NC \type{top} \NC number \NC top character index \NC\NR +\NC \type{mid} \NC number \NC middle character index \NC\NR +\NC \type{bot} \NC number \NC bottom character index \NC\NR +\NC \type{rep} \NC number \NC repeatable character index \NC\NR \stoptabulate The \type {horiz_variants} and \type {vert_variants} are arrays of components. Each of those components is itself a hash of up to five keys: -\starttabulate[|lT|l|p|] -\NC \rmbf key \NC \bf type \NC \bf explanation \NC\NR -\NC glyph \NC number \NC The character index. Note that this is an encoding number, not a name. \NC \NR -\NC extender \NC number \NC One (1) if this part is repeatable, zero (0) otherwise. \NC \NR -\NC start \NC number \NC The maximum overlap at the starting side (in scaled points). \NC \NR -\NC end \NC number \NC The maximum overlap at the ending side (in scaled points). \NC \NR -\NC advance \NC number \NC The total advance width of this item. It can be zero or missing, - then the natural size of the glyph for character \type {component} - is used. \NC \NR +\starttabulate[|l|l|p|] +\BC key \BC type \BC explanation \NC \NR +\NC \type{glyph} \NC number \NC The character index. Note that this is an encoding number, not a name. \NC \NR +\NC \type{extender} \NC number \NC One (1) if this part is repeatable, zero (0) otherwise. \NC \NR +\NC \type{start} \NC number \NC The maximum overlap at the starting side (in scaled points). \NC \NR +\NC \type{end} \NC number \NC The maximum overlap at the ending side (in scaled points). \NC \NR +\NC \type{advance} \NC number \NC The total advance width of this item. It can be zero or missing, + then the natural size of the glyph for character \type {component} + is used. \NC \NR \stoptabulate The \type {kerns} table is a hash indexed by character index (and \quote @@ -268,10 +282,10 @@ The \type {ligatures} table is a hash indexed by character index (and \quote value \type {right_boundary}), with the values being yet another small hash, with two fields: -\starttabulate[|lT|l|p|] -\NC \rmbf key \NC \bf type \NC \bf description \NC \NR -\NC type \NC number \NC the type of this ligature command, default 0 \NC \NR -\NC char \NC number \NC the character index of the resultant ligature \NC \NR +\starttabulate[|l|l|p|] +\BC key \BC type \BC description \NC \NR +\NC \type{type} \NC number \NC the type of this ligature command, default 0 \NC \NR +\NC \type{char} \NC number \NC the character index of the resultant ligature \NC \NR \stoptabulate The \type {char} field in a ligature is required. @@ -285,15 +299,15 @@ forward one or two places. The glyph that ends up to the right of the insertion point will become the next \quote {left}. \starttabulate[|l|c|l|l|] -\NC \bf textual (Knuth) \NC \bf number \NC \bf string \NC result \NC\NR -\NC \type{l + r =: n} \NC 0 \NC \type{=:} \NC \type{|n} \NC\NR -\NC \type{l + r =:| n} \NC 1 \NC \type{=:|} \NC \type{|nr} \NC\NR -\NC \type{l + r |=: n} \NC 2 \NC \type{|=:} \NC \type{|ln} \NC\NR -\NC \type{l + r |=:| n} \NC 3 \NC \type{|=:|} \NC \type{|lnr} \NC\NR -\NC \type{l + r =:|> n} \NC 5 \NC \type{=:|>} \NC \type{n|r} \NC\NR -\NC \type{l + r |=:> n} \NC 6 \NC \type{|=:>} \NC \type{l|n} \NC\NR -\NC \type{l + r |=:|> n} \NC 7 \NC \type{|=:|>} \NC \type{l|nr} \NC\NR -\NC \type{l + r |=:|>> n} \NC 11 \NC \type{|=:|>>} \NC \type{ln|r} \NC\NR +\BC textual (Knuth) \BC number \BC string \BC result \NC\NR +\NC \type{l + r =: n} \NC 0 \NC \type{=:} \NC \type{|n} \NC\NR +\NC \type{l + r =:| n} \NC 1 \NC \type{=:|} \NC \type{|nr} \NC\NR +\NC \type{l + r |=: n} \NC 2 \NC \type{|=:} \NC \type{|ln} \NC\NR +\NC \type{l + r |=:| n} \NC 3 \NC \type{|=:|} \NC \type{|lnr} \NC\NR +\NC \type{l + r =:|> n} \NC 5 \NC \type{=:|>} \NC \type{n|r} \NC\NR +\NC \type{l + r |=:> n} \NC 6 \NC \type{|=:>} \NC \type{l|n} \NC\NR +\NC \type{l + r |=:|> n} \NC 7 \NC \type{|=:|>} \NC \type{l|nr} \NC\NR +\NC \type{l + r |=:|>> n} \NC 11 \NC \type{|=:|>>} \NC \type{ln|r} \NC\NR \stoptabulate The default value is~0, and can be left out. That signifies a \quote {normal} @@ -310,10 +324,10 @@ structure. If the value is \type {real}, then this is a proper font, and the inclusion mechanism will attempt to add the needed font object definitions to the \PDF. Values for \type {type} are: -\starttabulate[|Tl|p|] -\NC \rmbf value \NC \rmbf description \NC\NR -\NC real \NC this is a base font \NC\NR -\NC virtual \NC this is a virtual font \NC\NR +\starttabulate[|l|p|] +\BC value \BC description \NC\NR +\NC \type{real} \NC this is a base font \NC\NR +\NC \type{virtual} \NC this is a virtual font \NC\NR \stoptabulate The actions to be taken depend on a number of different variables: @@ -354,12 +368,12 @@ the separate characters. Values for \type {format} are: -\starttabulate[|Tl|p|] -\NC \rmbf value \NC \rmbf description \NC \NR -\NC type1 \NC this is a \POSTSCRIPT\ \TYPEONE\ font \NC \NR -\NC type3 \NC this is a bitmapped (\PK) font \NC \NR -\NC truetype \NC this is a \TRUETYPE\ or \TRUETYPE|-|based \OPENTYPE\ font \NC \NR -\NC opentype \NC this is a \POSTSCRIPT|-|based \OPENTYPE\ font \NC \NR +\starttabulate[|l|p|] +\BC value \BC description \NC \NR +\NC \type{type1} \NC this is a \POSTSCRIPT\ \TYPEONE\ font \NC \NR +\NC \type{type3} \NC this is a bitmapped (\PK) font \NC \NR +\NC \type{truetype} \NC this is a \TRUETYPE\ or \TRUETYPE|-|based \OPENTYPE\ font \NC \NR +\NC \type{opentype} \NC this is a \POSTSCRIPT|-|based \OPENTYPE\ font \NC \NR \stoptabulate \type {type3} fonts are provided for backward compatibility only, and do not @@ -367,11 +381,11 @@ support the new wide encoding options. Values for \type {embedding} are: -\starttabulate[|Tl|p|] -\NC \rmbf value \NC \rmbf description \NC \NR -\NC no \NC don't embed the font at all \NC \NR -\NC subset \NC include and atttempt to subset the font \NC \NR -\NC full \NC include this font in its entirety \NC \NR +\starttabulate[|l|p|] +\BC value \BC description \NC \NR +\NC \type{no} \NC don't embed the font at all \NC \NR +\NC \type{subset} \NC include and atttempt to subset the font \NC \NR +\NC \type{full} \NC include this font in its entirety \NC \NR \stoptabulate The other fields are used as follows: The \type {fullname} will be the @@ -453,25 +467,28 @@ The \type {commands} array is a hash where each item is another small array, with the first entry representing a command and the extra items being the parameters to that command. The allowed commands and their arguments are: -\starttabulate[|Tl|l|l|p|] -\NC \rmbf command name \NC \bf arguments \NC \bf type \NC \bf description \NC\NR -\NC font \NC 1 \NC number \NC select a new font from the local \type {fonts} table\NC\NR -\NC char \NC 1 \NC number \NC typeset this character number from the current font, - and move right by the character's width\NC\NR -\NC node \NC 1 \NC node \NC output this node (list), and move right - by the width of this list\NC\NR -\NC slot \NC 2 \NC number \NC a shortcut for the combination of a font and char command\NC\NR -\NC push \NC 0 \NC \NC save current position\NC\NR -\NC nop \NC 0 \NC \NC do nothing \NC\NR -\NC pop \NC 0 \NC \NC pop position \NC\NR -\NC rule \NC 2 \NC 2 numbers \NC output a rule $ht*wd$, and move right.\NC\NR -\NC down \NC 1 \NC number \NC move down on the page\NC\NR -\NC right \NC 1 \NC number \NC move right on the page\NC\NR -\NC special \NC 1 \NC string \NC output a \type {\special} command\NC\NR -\NC lua \NC 1 \NC string \NC execute a \LUA\ script (at \type {\latelua} time)\NC\NR -\NC image \NC 1 \NC image \NC output an image (the argument can be either an \type - {<image>} variable or an \type {image_spec} table)\NC\NR -\NC comment \NC any \NC any \NC the arguments of this command are ignored\NC\NR +\starttabulate[|l|l|l|p|] +\BC command name \BC arguments \BC type \BC description \NC \NR +\NC \type{font} \NC 1 \NC number \NC select a new font from the local \type {fonts} table \NC \NR +\NC \type{char} \NC 1 \NC number \NC typeset this character number from the current font, + and move right by the character's width \NC \NR +\NC \type{node} \NC 1 \NC node \NC output this node (list), and move right + by the width of this list\NC \NR +\NC \type{slot} \NC 2 \NC 2 numbers \NC a shortcut for the combination of a font and char command\NC \NR +\NC \type{push} \NC 0 \NC \NC save current position\NC \NR +\NC \type{nop} \NC 0 \NC \NC do nothing \NC \NR +\NC \type{pop} \NC 0 \NC \NC pop position \NC \NR +\NC \type{rule} \NC 2 \NC 2 numbers \NC output a rule $ht*wd$, and move right. \NC \NR +\NC \type{down} \NC 1 \NC number \NC move down on the page \NC \NR +\NC \type{right} \NC 1 \NC number \NC move right on the page \NC \NR +\NC \type{special} \NC 1 \NC string \NC output a \type {\special} command \NC \NR +\NC \type{pdf} \NC 2 \NC 2 strings \NC output a \PDF\ literal, the first string is one of \type {origin}, + \type {page}, \type {text}, \type {font}, \type {direct} or \type {raw}; if you + have one string only \type {origin} is assumed \NC \NR +\NC \type{lua} \NC 1 \NC string \NC execute a \LUA\ script (at \type {\latelua} time) \NC \NR +\NC \type{image} \NC 1 \NC image \NC output an image (the argument can be either an \type + {<image>} variable or an \type {image_spec} table) \NC \NR +\NC \type{comment} \NC any \NC any \NC the arguments of this command are ignored \NC \NR \stoptabulate When a font id is set to~0 then it will be replaced by the currently assigned @@ -479,20 +496,43 @@ font id. This prevents the need for hackery with future id's (normally one could use \type {font.nextid} but when more complex fonts are built in the meantime other instances could have been loaded. +The \type {pdf} option also accepts a \type {mode} keyword in which case the +third argument sets the mode. That option will change the mode in an efficient +way (passing an empty string would result in an extra empty lines in the \PDF\ +file. This option only makes sense for virtual fonts. The \type {font} mode only +makes sense in virtual fonts. + +These modes are somewhat fuzzy and partially inherited from \PDFTEX. + +\starttabulate[|l|p|] +\BC mode \BC description \NC \NR +\NC \type {origin} \NC enter page mode and set the position \NC \NR +\NC \type {page} \NC enter page mode \NC \NR +\NC \type {text} \NC enter text mode \NC \NR +\NC \type {font} \NC enter font mode (kind of text mode, only in virtual fonts) \NC \NR +\NC \type {always} \NC finish the current string and force a transform if needed \NC \NR +\NC \type {raw} \NC finish the current string \NC \NR +\stoptabulate + +You always need to check what \PDF\ code is generated because there can be all kind of +interferences with optimizations in the backend and fonts are complicated anyway. + Here is a rather elaborate glyph commands example: \starttyping ... commands = { - { 'push' }, -- remember where we are - { 'right', 5000 }, -- move right about 0.08pt - { 'font', 3 }, -- select the fonts[3] entry - { 'char', 97 }, -- place character 97 (ASCII 'a') - { 'pop' }, -- go all the way back - { 'down', -200000 }, -- move upwards by about 3pt - { 'special', 'pdf: 1 0 0 rg' } -- switch to red color - { 'rule', 500000, 20000 } -- draw a bar - { 'special','pdf: 0 g' } -- back to black + { "push" }, -- remember where we are + { "right", 5000 }, -- move right about 0.08pt + { "font", 3 }, -- select the fonts[3] entry + { "char", 97 }, -- place character 97 (ASCII 'a') + { "pop" }, -- go all the way back + { "down", -200000 }, -- move upwards by about 3pt + { "special", "pdf: 1 0 0 rg" } -- switch to red color + -- { "pdf", "origin", "1 0 0 rg" } -- switch to red color (alternative) + { "rule", 500000, 20000 } -- draw a bar + { "special", "pdf: 0 g" } -- back to black + -- { "pdf", "origin", "0 g" } -- back to black (alternative) } ... \stoptyping @@ -511,6 +551,10 @@ output pointer will always move by exactly the width that was given in the \type {width} key of the character hash. Any movements that take place inside the \type {commands} array are ignored on the upper level. +The special can have a \type {pdf:}, \type {pdf:origin:}, \type {pdf:page:}, +\type {pdf:direct:} or \type {pdf:raw:} prefix. When you have to concatenate +strings using the \type {pdf} command might be more efficient. + \subsection{Artificial fonts} Even in a \quote {real} font, there can be virtual characters. When \LUATEX\ @@ -564,6 +608,18 @@ Finally, here is a plain \TEX\ input file with a virtual font demonstration: \typebuffer +\section{The \type {vf} library} + +The \type {vf} library can be used when \LUA\ code, as defined in the \type +{commands} of the font, is executed. The functions provided are similar as the +commands: \type {char}, \type {down}, \type {fontid}, \type {image}, \type +{node}, \type {nop}, \type {pop}, \type {push}, \type {right}, \type {rule}, +\type {special} and \type {pdf}. This library has been present for a while but +not been advertised and tested much, if only because it's easy to define an +invalid font (or mess up the \PDF\ stream). Keep in mind that the \LUA\ snippets +are executed each time when a character is output. + + \section{The \type {font} library} The font library provides the interface into the internals of the font system, @@ -662,7 +718,32 @@ You can define your own font into \type {font.fonts} by calling this function: The return value is the internal id number of the defined font (the index into \type {font.fonts}). If the font creation fails, an error is raised. The table -is a font structure, as explained in \in {chapter} [fonts]. +is a font structure, as explained in \in {chapter} [fonts]. An alternative call +is: + +\startfunctioncall +<number> i = + font.define(<number> n, <table> f) +\stopfunctioncall + +Where the first argument is a reserved font id (see below). + +\subsection{Extending a font} + +Within reasonable bounds you can extend a font after it has been defined. Because +some properties are best left unchanged this is limited to adding characters. + +\startfunctioncall +font.addcharacters(<number n>, <table> f) +\stopfunctioncall + +The table passed can have the fields \type {characters} which is a (sub)table +like the one used in define, and for virtual fonts a \type {fonts} table can be +added. The characters defined in the \type {characters} table are added (when not +yet present) or replace an existing entry. Keep in mind that replacing can have +side effects because a character already can have been used. Instead of posing +restrictions we expect the user to be careful. (The \type {setfont} helper is +a more drastic replacer.) \subsection{Projected next font id} @@ -673,7 +754,14 @@ is a font structure, as explained in \in {chapter} [fonts]. This returns the font id number that would be returned by a \type {font.define} call if it was executed at this spot in the code flow. This is useful for virtual -fonts that need to reference themselves. +fonts that need to reference themselves. If you pass \type {true} as argument, +the id gets reserved and you can pass to \type {font.define} as first argument. +This can be handy when you create complex virtual fonts. + +\startfunctioncall +<number> i = + font.nextid(true) +\stopfunctioncall \subsection{Font id} diff --git a/doc/context/sources/general/manuals/luatex/luatex-introduction.tex b/doc/context/sources/general/manuals/luatex/luatex-introduction.tex index 196a9af4f..d0899147d 100644 --- a/doc/context/sources/general/manuals/luatex/luatex-introduction.tex +++ b/doc/context/sources/general/manuals/luatex/luatex-introduction.tex @@ -72,11 +72,10 @@ code in \TEX\ engines (especially code that is not needed any longer). \IO\ can be intercepted. \stopitem \startitem - We currently use \LUA\ 5.2.*. At some point we might decide to move to - 5.3.* but that is yet to be decided. There are few \LUA\ libraries that - we consider part of the core \LUA\ machinery, for instance \type {lpeg}. + We currently use \LUA\ 5.3.*. There are few \LUA\ libraries that we + consider part of the core \LUA\ machinery, for instance \type {lpeg}. There are additional \LUA\ libraries that interface to the internals of - \TEX. + \TEX. We also keep the \LUA\ 5.2 \type {bit32} library around. \stopitem \startitem There are various \TEX\ extensions but only those that cannot be done diff --git a/doc/context/sources/general/manuals/luatex/luatex-languages.tex b/doc/context/sources/general/manuals/luatex/luatex-languages.tex index 54a7b390d..365e87f26 100644 --- a/doc/context/sources/general/manuals/luatex/luatex-languages.tex +++ b/doc/context/sources/general/manuals/luatex/luatex-languages.tex @@ -224,45 +224,104 @@ node. But by default also a hlist, vlist, rule, dir, whatsit, ins, and adjust no indicate a start or end. You can omit the last set from the test by setting \type {\hyphenationbounds} to a non|-|zero value: -\starttabulate[|Tl|l|] -\NC 0 \NC not strict \NC \NR -\NC 1 \NC strict start \NC \NR -\NC 2 \NC strict end \NC \NR -\NC 3 \NC strict start and strict end \NC \NR +\starttabulate[|l|l|] +\NC \type{0} \NC not strict \NC \NR +\NC \type{1} \NC strict start \NC \NR +\NC \type{2} \NC strict end \NC \NR +\NC \type{3} \NC strict start and strict end \NC \NR \stoptabulate The word start is determined as follows: -\starttabulate[|Bl|l|] -\NC boundary \NC yes when wordboundary \NC \NR -\NC hlist \NC when hyphenationbounds 1 or 3 \NC \NR -\NC vlist \NC when hyphenationbounds 1 or 3 \NC \NR -\NC rule \NC when hyphenationbounds 1 or 3 \NC \NR -\NC dir \NC when hyphenationbounds 1 or 3 \NC \NR -\NC whatsit \NC when hyphenationbounds 1 or 3 \NC \NR -\NC glue \NC yes \NC \NR -\NC math \NC skipped \NC \NR -\NC glyph \NC exhyphenchar (one only) : yes (so no -- ---) \NC \NR -\NC otherwise \NC yes \NC \NR +\starttabulate[|l|l|] +\BC boundary \NC yes when wordboundary \NC \NR +\BC hlist \NC when hyphenationbounds 1 or 3 \NC \NR +\BC vlist \NC when hyphenationbounds 1 or 3 \NC \NR +\BC rule \NC when hyphenationbounds 1 or 3 \NC \NR +\BC dir \NC when hyphenationbounds 1 or 3 \NC \NR +\BC whatsit \NC when hyphenationbounds 1 or 3 \NC \NR +\BC glue \NC yes \NC \NR +\BC math \NC skipped \NC \NR +\BC glyph \NC exhyphenchar (one only) : yes (so no -- ---) \NC \NR +\BC otherwise \NC yes \NC \NR \stoptabulate The word end is determined as follows: -\starttabulate[|Bl|l|] -\NC boundary \NC yes \NC \NR -\NC glyph \NC yes when different language \NC \NR -\NC glue \NC yes \NC \NR -\NC penalty \NC yes \NC \NR -\NC kern \NC yes when not italic (for some historic reason) \NC \NR -\NC hlist \NC when hyphenationbounds 2 or 3 \NC \NR -\NC vlist \NC when hyphenationbounds 2 or 3 \NC \NR -\NC rule \NC when hyphenationbounds 2 or 3 \NC \NR -\NC dir \NC when hyphenationbounds 2 or 3 \NC \NR -\NC whatsit \NC when hyphenationbounds 2 or 3 \NC \NR -\NC ins \NC when hyphenationbounds 2 or 3 \NC \NR -\NC adjust \NC when hyphenationbounds 2 or 3 \NC \NR +\starttabulate[|l|l|] +\BC boundary \NC yes \NC \NR +\BC glyph \NC yes when different language \NC \NR +\BC glue \NC yes \NC \NR +\BC penalty \NC yes \NC \NR +\BC kern \NC yes when not italic (for some historic reason) \NC \NR +\BC hlist \NC when hyphenationbounds 2 or 3 \NC \NR +\BC vlist \NC when hyphenationbounds 2 or 3 \NC \NR +\BC rule \NC when hyphenationbounds 2 or 3 \NC \NR +\BC dir \NC when hyphenationbounds 2 or 3 \NC \NR +\BC whatsit \NC when hyphenationbounds 2 or 3 \NC \NR +\BC ins \NC when hyphenationbounds 2 or 3 \NC \NR +\BC adjust \NC when hyphenationbounds 2 or 3 \NC \NR \stoptabulate +\in{Figures}[hb:1] upto \in[hb:5] show some examples. In all cases we set the min +values to 1 and make sure that the words hyphenate at each character. + +\hyphenation{o-n-e t-w-o} + +\def\SomeTest#1#2% + {\lefthyphenmin \plusone + \righthyphenmin \plusone + \parindent \zeropoint + \everypar \emptytoks + \dontcomplain + \hbox to 2cm {% + \vtop {% + \hsize 1pt + \hyphenationbounds#1 + #2 + \par}}} + +\startplacefigure[reference=hb:1,title={\type{one}}] + \startcombination[4*1] + {\SomeTest{0}{one}} {\type{0}} + {\SomeTest{1}{one}} {\type{1}} + {\SomeTest{2}{one}} {\type{2}} + {\SomeTest{3}{one}} {\type{3}} + \stopcombination +\stopplacefigure +\startplacefigure[reference=hb:2,title={\type{one\null two}}] + \startcombination[4*1] + {\SomeTest{0}{one\null two}} {\type{0}} + {\SomeTest{1}{one\null two}} {\type{1}} + {\SomeTest{2}{one\null two}} {\type{2}} + {\SomeTest{3}{one\null two}} {\type{3}} + \stopcombination +\stopplacefigure +\startplacefigure[reference=hb:3,title={\type{\null one\null two}}] + \startcombination[4*1] + {\SomeTest{0}{\null one\null two}} {\type{0}} + {\SomeTest{1}{\null one\null two}} {\type{1}} + {\SomeTest{2}{\null one\null two}} {\type{2}} + {\SomeTest{3}{\null one\null two}} {\type{3}} + \stopcombination +\stopplacefigure +\startplacefigure[reference=hb:4,title={\type{one\null two\null}}] + \startcombination[4*1] + {\SomeTest{0}{one\null two\null}} {\type{0}} + {\SomeTest{1}{one\null two\null}} {\type{1}} + {\SomeTest{2}{one\null two\null}} {\type{2}} + {\SomeTest{3}{one\null two\null}} {\type{3}} + \stopcombination +\stopplacefigure +\startplacefigure[reference=hb:5,title={\type{\null one\null two\null}}] + \startcombination[4*1] + {\SomeTest{0}{\null one\null two\null}} {\type{0}} + {\SomeTest{1}{\null one\null two\null}} {\type{1}} + {\SomeTest{2}{\null one\null two\null}} {\type{2}} + {\SomeTest{3}{\null one\null two\null}} {\type{3}} + \stopcombination +\stopplacefigure + % (Future versions of \LUATEX\ might provide more granularity.) In traditional \TEX\ ligature building and hyphenation are interwoven with the @@ -277,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 @@ -432,18 +491,18 @@ have been added: The first parameter has the following consequences for automatic discs (the ones resulting from an \type {\exhyphenchar}: -\starttabulate[|Tc|l|l|] -\BC mode \BC automatic disc \type{-} \BC explicit disc \type{\-} \NC \NR +\starttabulate[|c|l|l|] +\BC mode \BC automatic disc \type{-} \BC explicit disc \type{\-} \NC \NR \HL -\NC 0 \NC \type {\exhyphenpenalty} \NC \type {\exhyphenpenalty} \NC \NR -\NC 1 \NC \type {\hyphenpenalty} \NC \type {\hyphenpenalty} \NC \NR -\NC 2 \NC \type {\exhyphenpenalty} \NC \type {\hyphenpenalty} \NC \NR -\NC 3 \NC \type {\hyphenpenalty} \NC \type {\exhyphenpenalty} \NC \NR -\NC 4 \NC \type {\automatichyphenpenalty} \NC \type {\explicithyphenpenalty} \NC \NR -\NC 5 \NC \type {\exhyphenpenalty} \NC \type {\explicithyphenpenalty} \NC \NR -\NC 6 \NC \type {\hyphenpenalty} \NC \type {\explicithyphenpenalty} \NC \NR -\NC 7 \NC \type {\automatichyphenpenalty} \NC \type {\exhyphenpenalty} \NC \NR -\NC 8 \NC \type {\automatichyphenpenalty} \NC \type {\hyphenpenalty} \NC \NR +\NC \type{0} \NC \type {\exhyphenpenalty} \NC \type {\exhyphenpenalty} \NC \NR +\NC \type{1} \NC \type {\hyphenpenalty} \NC \type {\hyphenpenalty} \NC \NR +\NC \type{2} \NC \type {\exhyphenpenalty} \NC \type {\hyphenpenalty} \NC \NR +\NC \type{3} \NC \type {\hyphenpenalty} \NC \type {\exhyphenpenalty} \NC \NR +\NC \type{4} \NC \type {\automatichyphenpenalty} \NC \type {\explicithyphenpenalty} \NC \NR +\NC \type{5} \NC \type {\exhyphenpenalty} \NC \type {\explicithyphenpenalty} \NC \NR +\NC \type{6} \NC \type {\hyphenpenalty} \NC \type {\explicithyphenpenalty} \NC \NR +\NC \type{7} \NC \type {\automatichyphenpenalty} \NC \type {\exhyphenpenalty} \NC \NR +\NC \type{8} \NC \type {\automatichyphenpenalty} \NC \type {\hyphenpenalty} \NC \NR \stoptabulate other values do what we always did in \LUATEX: insert \type {\exhyphenpenalty}. @@ -488,9 +547,9 @@ listed items. It is important to note that the keys in an exception dictionary can always be generated from the values. Here are a few examples: \starttabulate[|l|l|l|] -\NC \bf value \NC \bf implied key (input) \NC \bf effect \NC\NR -\NC \type {ta-ble} \NC table \NC \type {ta\-ble} ($=$ \type {ta\discretionary{-}{}{}ble}) \NC\NR -\NC \type {ba{k-}{}{c}ken} \NC backen \NC \type {ba\discretionary{k-}{}{c}ken} \NC\NR +\BC value \BC implied key (input) \NC effect \NC\NR +\NC \type {ta-ble} \NC table \NC \type {ta\-ble} ($=$ \type {ta\discretionary{-}{}{}ble}) \NC\NR +\NC \type {ba{k-}{}{c}ken} \NC backen \NC \type {ba\discretionary{k-}{}{c}ken} \NC\NR \stoptabulate The resultant patterns and exception dictionary will be stored under the language @@ -650,10 +709,10 @@ For example, take the word \type {office}, hyphenated \type {of-fice}, using a type ligatures: \starttabulate[|l|l|] -\NC Initial: \NC \type {{o}{f}{f}{i}{c}{e}} \NC\NR -\NC After hyphenation: \NC \type {{o}{f}{{-},{},{}}{f}{i}{c}{e}} \NC\NR -\NC First ligature stage: \NC \type {{o}{{f-},{f},{<ff>}}{i}{c}{e}} \NC\NR -\NC Final result: \NC \type {{o}{{f-},{<fi>},{<ffi>}}{c}{e}} \NC\NR +\NC initial \NC \type {{o}{f}{f}{i}{c}{e}} \NC\NR +\NC after hyphenation \NC \type {{o}{f}{{-},{},{}}{f}{i}{c}{e}} \NC\NR +\NC first ligature stage \NC \type {{o}{{f-},{f},{<ff>}}{i}{c}{e}} \NC\NR +\NC final result \NC \type {{o}{{f-},{<fi>},{<ffi>}}{c}{e}} \NC\NR \stoptabulate That's bad enough, but let us assume that there is also a hyphenation point @@ -675,25 +734,25 @@ the top-level discretionary that resulted from the first hyphenation point. Here is that nested solution again, in a different representation: -\starttabulate[|l|l|l|l|] -\NC \NC pre \NC post \NC replace \NC \NR -\NC topdisc \NC \type {f-}$^1$ \NC sub1 \NC sub2 \NC \NR -\NC sub1 \NC \type {f-}$^2$ \NC \type {i}$^3$ \NC \type {<fi>}$^4$ \NC \NR -\NC sub2 \NC \type {<ff>-}$^5$\NC \type {i}$^6$ \NC \type {<ffi>}$^7$ \NC \NR +\starttabulate[|l|c|c|c|c|c|c|] +\NC \BC pre \BC \BC post \BC \BC replace \BC \NC \NR +\NC topdisc \NC \type {f-} \NC (1) \NC \NC sub 1 \NC \NC sub 2 \NC \NR +\NC sub 1 \NC \type {f-} \NC (2) \NC \type {i} \NC (3) \NC \type {<fi>} \NC (4) \NC \NR +\NC sub 2 \NC \type {<ff>-} \NC (5) \NC \type {i} \NC (6) \NC \type {<ffi>} \NC (7) \NC \NR \stoptabulate When line breaking is choosing its breakpoints, the following fields will eventually be selected: -\starttabulate[|l|l|l|] -\NC \type {of-f-ice} \NC \type {f-}$^1$ \NC \NR -\NC \NC \type {f-}$^2$ \NC \NR -\NC \NC \type {i}$^3$ \NC \NR -\NC \type {of-fice} \NC \type {f-}$^1$ \NC \NR -\NC \NC \type {<fi>}$^4$ \NC \NR -\NC \type {off-ice} \NC \type {<ff>-}$^5$ \NC \NR -\NC \NC \type {i}$^6$ \NC \NR -\NC \type {office} \NC \type {<ffi>}$^7$ \NC \NR +\starttabulate[|l|c|c|] +\NC \type {of-f-ice} \NC \type {f-} \NC (1) \NC \NR +\NC \NC \type {f-} \NC (2) \NC \NR +\NC \NC \type {i} \NC (3) \NC \NR +\NC \type {of-fice} \NC \type {f-} \NC (1) \NC \NR +\NC \NC \type {<fi>} \NC (4) \NC \NR +\NC \type {off-ice} \NC \type {<ff>-} \NC (5) \NC \NR +\NC \NC \type {i} \NC (6) \NC \NR +\NC \type {office} \NC \type {<ffi>} \NC (7) \NC \NR \stoptabulate The current solution in \LUATEX\ is not able to handle nested discretionaries, @@ -711,14 +770,14 @@ make the whole stuff fit into just two discretionary nodes. The mapping of the seven list fields to the six fields in this discretionary node pair is as follows: -\starttabulate[|l|p|] -\NC \bf field \NC \bf description \NC \NR -\NC \type {disc1.pre} \NC \type {f-}$^1$ \NC \NR -\NC \type {disc1.post} \NC \type {<fi>}$^4$ \NC \NR -\NC \type {disc1.replace} \NC \type {<ffi>}$^7$ \NC \NR -\NC \type {disc2.pre} \NC \type {f-}$^2$ \NC \NR -\NC \type {disc2.post} \NC \type {i}$^{3{,}6}$\NC \NR -\NC \type {disc2.replace} \NC \type {<ff>-}$^5$\NC \NR +\starttabulate[|l|c|c|] +\BC field \BC description \NC \NC \NR +\NC \type {disc1.pre} \NC \type {f-} \NC (1) \NC \NR +\NC \type {disc1.post} \NC \type {<fi>} \NC (4) \NC \NR +\NC \type {disc1.replace} \NC \type {<ffi>} \NC (7) \NC \NR +\NC \type {disc2.pre} \NC \type {f-} \NC (2) \NC \NR +\NC \type {disc2.post} \NC \type {i} \NC (3,6) \NC \NR +\NC \type {disc2.replace} \NC \type {<ff>-} \NC (5) \NC \NR \stoptabulate What is actually generated after ligaturing has been applied is therefore: diff --git a/doc/context/sources/general/manuals/luatex/luatex-lua.tex b/doc/context/sources/general/manuals/luatex/luatex-lua.tex index 0960f8032..82b060440 100644 --- a/doc/context/sources/general/manuals/luatex/luatex-lua.tex +++ b/doc/context/sources/general/manuals/luatex/luatex-lua.tex @@ -55,33 +55,33 @@ option. If there is no \type {--lua} option, the command line is interpreted in similar fashion as the other \TEX\ engines. Some options are accepted but have no consequence. The following command|-|line options are understood: -\starttabulate[|lT|p|] -\NC --credits \NC display credits and exit \NC \NR -\NC --debug-format \NC enable format debugging \NC \NR -\NC --draftmode \NC switch on draft mode i.e.\ generate no output in \PDF\ mode \NC \NR -\NC --[no-]file-line-error \NC disable/enable \type {file:line:error} style messages \NC \NR -\NC --[no-]file-line-error-style \NC aliases of \type {--[no-]file-line-error} \NC \NR -\NC --fmt=FORMAT \NC load the format file \type {FORMAT} \NC\NR -\NC --halt-on-error \NC stop processing at the first error\NC \NR -\NC --help \NC display help and exit \NC\NR -\NC --ini \NC be \type {iniluatex}, for dumping formats \NC\NR -\NC --interaction=STRING \NC set interaction mode: \type {batchmode}, \type {nonstopmode}, \type {scrollmode} or \type {errorstopmode} \NC \NR -\NC --jobname=STRING \NC set the job name to \type {STRING} \NC \NR -\NC --kpathsea-debug=NUMBER \NC set path searching debugging flags according to the bits of \type {NUMBER} \NC \NR -\NC --lua=FILE \NC load and execute a \LUA\ initialization script \NC\NR -\NC --[no-]mktex=FMT \NC disable/enable \type {mktexFMT} generation with \type {FMT} is \type {tex} or \type {tfm} \NC \NR -\NC --nosocket \NC disable the \LUA\ socket library \NC\NR -\NC --output-comment=STRING \NC use \type {STRING} for \DVI\ file comment instead of date (no effect for \PDF) \NC \NR -\NC --output-directory=DIR \NC use \type {DIR} as the directory to write files to \NC \NR -\NC --output-format=FORMAT \NC use \type {FORMAT} for job output; \type {FORMAT} is \type {dvi} or \type {pdf} \NC \NR -\NC --progname=STRING \NC set the program name to \type {STRING} \NC \NR -\NC --recorder \NC enable filename recorder \NC \NR -\NC --safer \NC disable easily exploitable \LUA\ commands \NC\NR -\NC --[no-]shell-escape \NC disable/enable system calls \NC \NR -\NC --shell-restricted \NC restrict system calls to a list of commands given in \type {texmf.cnf} \NC \NR -\NC --synctex=NUMBER \NC enable \type {synctex} \NC \NR -\NC --utc \NC use utc times when applicable \NC \NR -\NC --version \NC display version and exit \NC \NR +\starttabulate[|l|p|] +\NC \type{--credits} \NC display credits and exit \NC \NR +\NC \type{--debug-format} \NC enable format debugging \NC \NR +\NC \type{--draftmode} \NC switch on draft mode i.e.\ generate no output in \PDF\ mode \NC \NR +\NC \type{--[no-]file-line-error} \NC disable/enable \type {file:line:error} style messages \NC \NR +\NC \type{--[no-]file-line-error-style} \NC aliases of \type {--[no-]file-line-error} \NC \NR +\NC \type{--fmt=FORMAT} \NC load the format file \type {FORMAT} \NC\NR +\NC \type{--halt-on-error} \NC stop processing at the first error\NC \NR +\NC \type{--help} \NC display help and exit \NC\NR +\NC \type{--ini} \NC be \type {iniluatex}, for dumping formats \NC\NR +\NC \type{--interaction=STRING} \NC set interaction mode: \type {batchmode}, \type {nonstopmode}, \type {scrollmode} or \type {errorstopmode} \NC \NR +\NC \type{--jobname=STRING} \NC set the job name to \type {STRING} \NC \NR +\NC \type{--kpathsea-debug=NUMBER} \NC set path searching debugging flags according to the bits of \type {NUMBER} \NC \NR +\NC \type{--lua=FILE} \NC load and execute a \LUA\ initialization script \NC\NR +\NC \type{--[no-]mktex=FMT} \NC disable/enable \type {mktexFMT} generation with \type {FMT} is \type {tex} or \type {tfm} \NC \NR +\NC \type{--nosocket} \NC disable the \LUA\ socket library \NC\NR +\NC \type{--output-comment=STRING} \NC use \type {STRING} for \DVI\ file comment instead of date (no effect for \PDF) \NC \NR +\NC \type{--output-directory=DIR} \NC use \type {DIR} as the directory to write files to \NC \NR +\NC \type{--output-format=FORMAT} \NC use \type {FORMAT} for job output; \type {FORMAT} is \type {dvi} or \type {pdf} \NC \NR +\NC \type{--progname=STRING} \NC set the program name to \type {STRING} \NC \NR +\NC \type{--recorder} \NC enable filename recorder \NC \NR +\NC \type{--safer} \NC disable easily exploitable \LUA\ commands \NC\NR +\NC \type{--[no-]shell-escape} \NC disable/enable system calls \NC \NR +\NC \type{--shell-restricted} \NC restrict system calls to a list of commands given in \type {texmf.cnf} \NC \NR +\NC \type{--synctex=NUMBER} \NC enable \type {synctex} \NC \NR +\NC \type{--utc} \NC use utc times when applicable \NC \NR +\NC \type{--version} \NC display version and exit \NC \NR \stoptabulate Some of the traditional flags are just ignored: \type {--etex}, \type @@ -141,7 +141,7 @@ Then it checks the various safety switches. You can use those to disable some \type {--safer} \type {nil}s the following functions: \starttabulate[|l|l|] -\NC \bf library \NC \bf functions \NC \NR +\BC library \BC functions \NC \NR \NC \type {os} \NC \type {execute} \type {exec} \type {spawn} \type {setenv} \type {rename} \type {remove} \type {tmpdir} \NC \NR \NC \type {io} \NC \type {popen} \type {output} \type {tmpfile} \NC \NR \NC \type {lfs} \NC \type {rmdir} \type {mkdir} \type {chdir} \type {lock} \type {touch} \NC \NR @@ -179,8 +179,7 @@ deal with typesetting, like \type {tex}, \type {token}, \type {node} and are \type {nil}'d). Special care is taken that \type {texio.write} and \type {texio.write_nl} function properly, so that you can at least report your actions to the log file when (and if) it eventually becomes opened (note that \TEX\ does -not even know its \type {\jobname} yet at this point). See \in {chapter} [libraries] -for more information about the \LUATEX-specific \LUA\ extension tables. +not even know its \type {\jobname} yet at this point). Everything you do in the \LUA\ initialization script will remain visible during the rest of the run, with the exception of the \TEX\ specific libraries like @@ -214,7 +213,7 @@ the right|-|hand side of an assignment to a \type {\dimen} or \type {\count}. Loading dynamic \LUA\ libraries will fail if there are two \LUA\ libraries loaded at the same time (which will typically happen on \type {win32}, because there is -one \LUA\ 5.2 inside \LUATEX, and another will likely be linked to the \DLL\ file +one \LUA\ 5.3 inside \LUATEX, and another will likely be linked to the \DLL\ file of the module itself). \LUATEX\ is able to use the kpathsea library to find \type {require()}d modules. @@ -304,17 +303,17 @@ piecemeal: \type {string.utfcharacters(s)}: a string with a single \UTF-8 token in it \stopitem \startitem - \type {string.characters(s)} \NC a string containing one byte + \type {string.characters(s)}: a string containing one byte \stopitem \startitem - \type {string.characterpairs(s)} two strings each containing one byte or an + \type {string.characterpairs(s)}: two strings each containing one byte or an empty second string if the string length was odd \stopitem \startitem - \type {string.bytes(s)} a single byte value + \type {string.bytes(s)}: a single byte value \stopitem \startitem - \type {string.bytepairs(s)} two byte values or nil instead of a number as + \type {string.bytepairs(s)}: two byte values or nil instead of a number as its second return value if the string length was odd \stopitem \stopitemize @@ -336,8 +335,28 @@ always returns byte positions in a string, and \type {unicode.utf8.match} and are} \UNICODE|-|aware, they fall|-|back to non|-|\UNICODE|-|aware behavior when using the empty capture \type {()} but other captures work as expected. For the interpretation of character classes in \type {unicode.utf8} functions refer to -the library sources at \hyphenatedurl {http://luaforge.net/projects/sln}. Version -5.3 of \LUA\ will provide some native \UTF8 support. +the library sources at \hyphenatedurl {http://luaforge.net/projects/sln}. + +Version 5.3 of \LUA\ provides some native \UTF8 support but we have added a few +similar helpers too: + +\startitemize +\startitem + \type {string.utfvalue(s)}: returns the codepoints of the characters in the + given string +\stopitem +\startitem + \type {string.utfcharacter(c,...)}: returns a string with the characters of + the given code points +\stopitem +\startitem + \type {string.utflength(s)}: returns the length oif the given string +\stopitem +\stopitemize + +These three functions are relative fast and don't do much checking. They can be used +as building blocks for other helpers. + \blank @@ -405,7 +424,7 @@ The \type {os} library has a few extra functions and variables: \startitem \type {os.env} is a hash table containing a dump of the variables and values in the process environment at the start of the run. It is writeable, - but the actual environment is {\em not\/} updated automatically. + but the actual environment is \notabene {not} updated automatically. \stopitem \startitem @@ -560,12 +579,17 @@ When Universal Time is needed, you can pass the flag \type {utc} to the engine. property also works when the date and time are set by \LUATEX\ itself. It has a complementary entry \type {use_utc_time} in the \type {texconfig} table. -{\em To some extend a cleaner solution would be to have a flag that disables all -variable data in one go (like filenames and so) but we just follow the method -implemented in \PDFTEX\ where primitives are used to influence other properties.} - -{\em In \CONTEXT\ we provide the command line argument \type {--nodates} that -does bit more disabling of dates.} +\startnotabene + To some extend a cleaner solution would be to have a flag that disables all + variable data in one go (like filenames and so) but we just follow the method + implemented in \PDFTEX\ where primitives are used to influence other + properties. +\stopnotabene + +\startnotabene + In \CONTEXT\ we provide the command line argument \type {--nodates} that does + bit more disabling of dates. +\stopnotabene \stopchapter diff --git a/doc/context/sources/general/manuals/luatex/luatex-math.tex b/doc/context/sources/general/manuals/luatex/luatex-math.tex index 3c29d9609..8ccae83f3 100644 --- a/doc/context/sources/general/manuals/luatex/luatex-math.tex +++ b/doc/context/sources/general/manuals/luatex/luatex-math.tex @@ -168,20 +168,20 @@ The input for such primitives would look like this: The altered \TEX82 primitives are: \starttabulate[|l|l|r|c|l|r|] -\NC \bf primitive \NC \bf min \NC \bf max \NC \kern 2em \NC \bf min \NC \bf max \NC \NR -\NC \type {\mathcode} \NC 0 \NC 10FFFF \NC = \NC 0 \NC 8000 \NC \NR -\NC \type {\delcode} \NC 0 \NC 10FFFF \NC = \NC 0 \NC FFFFFF \NC \NR +\BC primitive \BC min \BC max \BC \kern 2em \BC min \BC max \NC \NR +\NC \type {\mathcode} \NC 0 \NC 10FFFF \NC = \NC 0 \NC 8000 \NC \NR +\NC \type {\delcode} \NC 0 \NC 10FFFF \NC = \NC 0 \NC FFFFFF \NC \NR \stoptabulate The unaltered ones are: \starttabulate[|l|l|r|] -\NC \bf primitive \NC \bf min \NC \bf max \NC \NR -\NC \type {\mathchardef} \NC 0 \NC 8000 \NC \NR -\NC \type {\mathchar} \NC 0 \NC 7FFF \NC \NR -\NC \type {\mathaccent} \NC 0 \NC 7FFF \NC \NR -\NC \type {\delimiter} \NC 0 \NC 7FFFFFF \NC \NR -\NC \type {\radical} \NC 0 \NC 7FFFFFF \NC \NR +\BC primitive \BC min \BC max \NC \NR +\NC \type {\mathchardef} \NC 0 \NC 8000 \NC \NR +\NC \type {\mathchar} \NC 0 \NC 7FFF \NC \NR +\NC \type {\mathaccent} \NC 0 \NC 7FFF \NC \NR +\NC \type {\delimiter} \NC 0 \NC 7FFFFFF \NC \NR +\NC \type {\radical} \NC 0 \NC 7FFFFFF \NC \NR \stoptabulate For practical reasons \type {\mathchardef} will silently accept values larger @@ -193,18 +193,18 @@ The following new primitives are compatible with \XETEX: % somewhat fuzzy: \starttabulate[|l|l|r|c|l|r|] -\NC \bf primitive \NC \bf min \NC \bf max \NC \kern 2em \NC \bf min \NC \bf max \NC \NR -\NC \type {\Umathchardef} \NC 0+0+0 \NC 7+FF+10FFFF\rlap{\high{1}} \NC \NC \NC \NC \NR -\NC \type {\Umathcharnumdef}\rlap{\high{5}} \NC -80000000 \NC 7FFFFFFF\rlap{\high{3}} \NC \NC \NC \NC \NR -\NC \type {\Umathcode} \NC 0 \NC 10FFFF \NC = \NC 0+0+0 \NC 7+FF+10FFFF\rlap{\high{1}} \NC \NR -\NC \type {\Udelcode} \NC 0 \NC 10FFFF \NC = \NC 0+0 \NC FF+10FFFF\rlap{\high{2}} \NC \NR -\NC \type {\Umathchar} \NC 0+0+0 \NC 7+FF+10FFFF \NC \NC \NC \NC \NR -\NC \type {\Umathaccent} \NC 0+0+0 \NC 7+FF+10FFFF\rlap{\high{2,4}} \NC \NC \NC \NC \NR -\NC \type {\Udelimiter} \NC 0+0+0 \NC 7+FF+10FFFF\rlap{\high{2}} \NC \NC \NC \NC \NR -\NC \type {\Uradical} \NC 0+0 \NC FF+10FFFF\rlap{\high{2}} \NC \NC \NC \NC \NR -\NC \type {\Umathcharnum} \NC -80000000 \NC 7FFFFFFF\rlap{\high{3}} \NC \NC \NC \NC \NR -\NC \type {\Umathcodenum} \NC 0 \NC 10FFFF \NC = \NC -80000000 \NC 7FFFFFFF\rlap{\high{3}} \NC \NR -\NC \type {\Udelcodenum} \NC 0 \NC 10FFFF \NC = \NC -80000000 \NC 7FFFFFFF\rlap{\high{3}} \NC \NR +\BC primitive \BC min \BC max \BC \kern 2em \BC min \BC max \NC \NR +\NC \type {\Umathchardef} \NC 0+0+0 \NC 7+FF+10FFFF\rlap{\high{1}} \NC \NC \NC \NC \NR +\NC \type {\Umathcharnumdef}\rlap{\high{5}} \NC -80000000 \NC 7FFFFFFF\rlap{\high{3}} \NC \NC \NC \NC \NR +\NC \type {\Umathcode} \NC 0 \NC 10FFFF \NC = \NC 0+0+0 \NC 7+FF+10FFFF\rlap{\high{1}} \NC \NR +\NC \type {\Udelcode} \NC 0 \NC 10FFFF \NC = \NC 0+0 \NC FF+10FFFF\rlap{\high{2}} \NC \NR +\NC \type {\Umathchar} \NC 0+0+0 \NC 7+FF+10FFFF \NC \NC \NC \NC \NR +\NC \type {\Umathaccent} \NC 0+0+0 \NC 7+FF+10FFFF\rlap{\high{2,4}} \NC \NC \NC \NC \NR +\NC \type {\Udelimiter} \NC 0+0+0 \NC 7+FF+10FFFF\rlap{\high{2}} \NC \NC \NC \NC \NR +\NC \type {\Uradical} \NC 0+0 \NC FF+10FFFF\rlap{\high{2}} \NC \NC \NC \NC \NR +\NC \type {\Umathcharnum} \NC -80000000 \NC 7FFFFFFF\rlap{\high{3}} \NC \NC \NC \NC \NR +\NC \type {\Umathcodenum} \NC 0 \NC 10FFFF \NC = \NC -80000000 \NC 7FFFFFFF\rlap{\high{3}} \NC \NR +\NC \type {\Udelcodenum} \NC 0 \NC 10FFFF \NC = \NC -80000000 \NC 7FFFFFFF\rlap{\high{3}} \NC \NR \stoptabulate Specifications typically look like: @@ -238,13 +238,13 @@ details. New primitives that exist in \LUATEX\ only (all of these will be explained in following sections): -\starttabulate[|l|l|l|l|] -\NC \bf primitive \NC \bf value range (in hex) \NC \NR -\NC \type {\Uroot} \NC 0+0--FF+10FFFF$^2$ \NC \NR -\NC \type {\Uoverdelimiter} \NC 0+0--FF+10FFFF$^2$ \NC \NR -\NC \type {\Uunderdelimiter} \NC 0+0--FF+10FFFF$^2$ \NC \NR -\NC \type {\Udelimiterover} \NC 0+0--FF+10FFFF$^2$ \NC \NR -\NC \type {\Udelimiterunder} \NC 0+0--FF+10FFFF$^2$ \NC \NR +\starttabulate[|l|l|] +\BC primitive \BC value range (in hex) \NC \NR +\NC \type {\Uroot} \NC 0+0--FF+10FFFF$^2$ \NC \NR +\NC \type {\Uoverdelimiter} \NC 0+0--FF+10FFFF$^2$ \NC \NR +\NC \type {\Uunderdelimiter} \NC 0+0--FF+10FFFF$^2$ \NC \NR +\NC \type {\Udelimiterover} \NC 0+0--FF+10FFFF$^2$ \NC \NR +\NC \type {\Udelimiterunder} \NC 0+0--FF+10FFFF$^2$ \NC \NR \stoptabulate \section{Cramped math styles} @@ -336,7 +336,7 @@ now accessible via primitive commands. In fact, refactoring of the math engine has resulted in many more parameters than were accessible before. \starttabulate -\NC \bf primitive name \NC \bf description \NC \NR +\BC primitive name \BC description \NC \NR \NC \type {\Umathquad} \NC the width of 18 mu's \NC \NR \NC \type {\Umathaxis} \NC height of the vertical center axis of the math formula above the baseline \NC \NR @@ -412,8 +412,8 @@ to fully control spacing. Therefore \LUATEX\ comes with a new directive: \type {\mathdisplayskipmode}. The following values apply: \starttabulate -\NC 0 \NC normal \TEX\ behaviour: always above, only below when larger than zero \NC \NR -\NC 1 \NC always \NC \NR +\NC 0 \NC normal \TEX\ behaviour \NC \NR +\NC 1 \NC always (same as 0) \NC \NR \NC 2 \NC only when not zero \NC \NR \NC 3 \NC never, not even when not zero \NC \NR \stoptabulate @@ -447,7 +447,7 @@ dimension parameter. For math fonts, this should be set to zero. \switchtobodyfont[8pt] \starttabulate[|l|l|l|p|] -\NC \bf variable \NC \bf style \NC \bf default value opentype \NC \bf default value tfm \NC \NR +\BC variable \BC style \BC default value opentype \BC default value tfm \NC \NR \NC \type {\Umathaxis} \NC -- \NC AxisHeight \NC axis_height \NC \NR \NC \type {\Umathoperatorsize} \NC D, D' \NC DisplayOperatorMinHeight \NC $^6$ \NC \NR \NC \type {\Umathfractiondelsize} \NC D, D' \NC FractionDelimiterDisplayStyleSize$^9$ \NC delim1 \NC \NR @@ -579,7 +579,7 @@ kerns assume correction too. Anyway, with this parameter one can control it. \NC \mathnolimitsmode8000 $\displaystyle\int\nolimits^0_1$ \NC \NR \TB - \NC \bf mode + \BC mode \NC \tttf 0 \NC \tttf 1 \NC \tttf 2 @@ -587,7 +587,7 @@ kerns assume correction too. Anyway, with this parameter one can control it. \NC \tttf 4 \NC \tttf 8000 \NC \NR - \NC \bf superscript + \BC superscript \NC 0 \NC font \NC 0 @@ -595,7 +595,7 @@ kerns assume correction too. Anyway, with this parameter one can control it. \NC +ic/2 \NC 0 \NC \NR - \NC \bf subscript + \BC subscript \NC -ic \NC font \NC 0 @@ -617,26 +617,121 @@ experimenting. The \type {\mathitalicsmode} parameter can be set to~1 to force italic correction before noads that represent some more complex structure (read: everything -that is not an ord, bin, rel, open, close, punct or inner). +that is not an ord, bin, rel, open, close, punct or inner). We show a Cambria +example. \starttexdefinition Whatever #1 - \NC \type{\mathitalicsmode=#1} + \NC \type{\mathitalicsmode = #1} \NC \mathitalicsmode#1\ruledhbox{$\left|T^1\right|$} \NC \mathitalicsmode#1\ruledhbox{$\left|T\right|$} \NC \mathitalicsmode#1\ruledhbox{$T+1$} \NC \mathitalicsmode#1\ruledhbox{$T{1\over2}$} \NC \mathitalicsmode#1\ruledhbox{$T\sqrt{1}$} - \NR \NR + \NC \NR \stoptexdefinition -\starttabulate[|c|c|c|c|c|c|] - \Whatever0 - \Whatever1 -\stoptabulate +\start + \switchtobodyfont[cambria] + \starttabulate[|c|c|c|c|c|c|] + \Whatever{0}% + \Whatever{1}% + \stoptabulate +\stop This kind of parameters relate to the fact that italic correction in \OPENTYPE\ math is bound to fuzzy rules. So, control is the solution. +\section{Script boxes} + +If you want typeset text in math macro packages often provide something \type +{\text} which obeys the script sizes. As the definition can be anything there is +a good change that the kerning doesn't come out well when used in a script. Given +that the first glyph ends up in an \type {\hbox} we have some control over this. +And, as a bonus we also added control over the normal sublist kerning. The \type +{\mathscriptboxmode} parameter defaults to~1. + +\starttabulate[|l|l|] +\NC \type {0} \NC forget about kerning \NC \NR +\NC \type {1} \NC kern math sub lists with a valid glyph \NC \NR +\NC \type {2} \NC also kern math sub boxes that have a valid glyph \NC \NR +\NC \type {2} \NC only kern math sub boxes with a boundary node present\NC \NR +\stoptabulate + +Here we show some examples. Of course this doesn't solve all our problems, if +only because some fonts have characters with bounding boxes that compensate for +italics, while other fonts can lack kerns. + +\startbuffer[1] + $T_{\tf fluff}$ +\stopbuffer + +\startbuffer[2] + $T_{\text{fluff}}$ +\stopbuffer + +\startbuffer[3] + $T_{\text{\boundary1 fluff}}$ +\stopbuffer + +\unexpanded\def\Show#1#2#3% + {\doifelsenothing{#3} + {\small\typeinlinebuffer[#1]} + {\doifelse{#3}{-} + {\small\type{mode #2}} + {\switchtobodyfont[#3]\showfontkerns\showglyphs\mathscriptboxmode#2\relax\inlinebuffer[#1]}}} + +\starttabulate[|lT|c|c|c|c|c|] + \NC \NC \Show{1}{0}{} \NC\Show{1}{1}{} \NC \Show{2}{1}{} \NC \Show{2}{2}{} \NC \Show{3}{3}{} \NC \NR + \NC \NC \Show{1}{0}{-} \NC\Show{1}{1}{-} \NC \Show{2}{1}{-} \NC \Show{2}{2}{-} \NC \Show{3}{3}{-} \NC \NR + \NC modern \NC \Show{1}{0}{modern} \NC\Show{1}{1}{modern} \NC \Show{2}{1}{modern} \NC \Show{2}{2}{modern} \NC \Show{3}{3}{modern} \NC \NR + \NC lucidaot \NC \Show{1}{0}{lucidaot} \NC\Show{1}{1}{lucidaot} \NC \Show{2}{1}{lucidaot} \NC \Show{2}{2}{lucidaot} \NC \Show{3}{3}{lucidaot} \NC \NR + \NC pagella \NC \Show{1}{0}{pagella} \NC\Show{1}{1}{pagella} \NC \Show{2}{1}{pagella} \NC \Show{2}{2}{pagella} \NC \Show{3}{3}{pagella} \NC \NR + \NC cambria \NC \Show{1}{0}{cambria} \NC\Show{1}{1}{cambria} \NC \Show{2}{1}{cambria} \NC \Show{2}{2}{cambria} \NC \Show{3}{3}{cambria} \NC \NR + \NC dejavu \NC \Show{1}{0}{dejavu} \NC\Show{1}{1}{dejavu} \NC \Show{2}{1}{dejavu} \NC \Show{2}{2}{dejavu} \NC \Show{3}{3}{dejavu} \NC \NR +\stoptabulate + +\section{Unscaled fences} + +The \type {\mathdelimitersmode} primitive is experimental and deals with the +following (potential) problems. Three bits can be set. The first bit prevents +an unwanted shift when the fence symbol is not scaled (a cambria side effect). The +second bit forces italic correction between a preceding character ordinal and +the fenced subformula, while the third bit turns that subformula into a ordinary +so that the same spacing applies as with unfenced variants. Here we show Cambria +(with \type {\mathitalicsmode} enabled). + +\starttexdefinition Whatever #1 + \NC \type{\mathdelimitersmode = #1} + \NC \mathitalicsmode1\mathdelimitersmode#1\ruledhbox{\showglyphs\showfontkerns\showfontitalics$f(x)$} + \NC \mathitalicsmode1\mathdelimitersmode#1\ruledhbox{\showglyphs\showfontkerns\showfontitalics$f\left(x\right)$} + \NC \NR +\stoptexdefinition + +\start + \switchtobodyfont[cambria] + \starttabulate[|l|l|l|] + \Whatever{0}\Whatever{1}\Whatever{2}\Whatever{3}% + \Whatever{4}\Whatever{5}\Whatever{6}\Whatever{7}% + \stoptabulate +\stop + +So, when set to 7 fenced subformulas with unscaled delimiters come out the same +as unfenced ones. This can be handy for cases where one is forced to use \type +{\left} and \type {\right} always because of unpredictable content. As said, it's +an experimental features (which somehow fits in the exceptional way fences are +dealt with in the engine). The full list of flags is given in the next table: + +\starttabulate[|T|l|] +\NC "01 \NC don't apply the usual shift \NC \NR +\NC "02 \NC apply italic correction when possible \NC \NR +\NC "04 \NC force a ordinary subformula \NC \NR +\NC "08 \NC no shift when a base character \NC \NR +\NC "10 \NC only shift when an extensible \NC \NR +\stoptabulate + +The effect can depend on the font (and for Cambria one can use for instance \type +{"16}). + \section{Math spacing setting} Besides the parameters mentioned in the previous sections, there are also 64 new @@ -1033,8 +1128,8 @@ get the length of the last line, the following will often work too: \LUATEX\ defines six new primitives that have the same function as \type {^}, \type {_}, \type {$}, and \type {$$}: -\starttabulate[|l|l|l|l|] -\NC \bf primitive \NC \bf explanation \NC \NR +\starttabulate[|l|l|] +\BC primitive \BC explanation \NC \NR \NC \type {\Usuperscript} \NC Duplicates the functionality of \type {^} \NC \NR \NC \type {\Usubscript} \NC Duplicates the functionality of \type {_} \NC \NR \NC \type {\Ustartmath} \NC Duplicates the functionality of \type {$}, % $ @@ -1051,6 +1146,25 @@ The \type {\Ustopmath} and \type {\Ustopdisplaymath} primitives check if the cur math mode is the correct one (inline vs.\ displayed), but you can freely intermix the four mathon|/|mathoff commands with explicit dollar sign(s). +\subsection{Script commands \type {\Unosuperscript} and \type {\Unosubscript}} + +These two commands result in super- and subscripts but with the current style (at the +time of rendering). So, + +\startbuffer[script] +$ + x\Usuperscript {1}\Usubscript {2} = + x\Unosuperscript{1}\Unosubscript{2} = + x\Usuperscript {1}\Unosubscript{2} = + x\Unosuperscript{1}\Usubscript {2} +$ +\stopbuffer + +\typebuffer + +results in \inlinebuffer[script]. + + \subsection{Allowed math commands in non-math modes} The commands \type {\mathchar}, and \type {\Umathchar} and control sequences that @@ -1071,9 +1185,7 @@ with zero being the default behaviour. \start \def\OneLiner#1#2% - {\NC #1 -% \NC \ruledhbox{\mathsurroundmode#1\relax\hsize 100pt x$x$x} -% \NC \ruledhbox{\mathsurroundmode#1\relax\hsize 100pt x $x$ x} + {\NC \type{#1} \NC \dontleavehmode\inframed[align=normal,offset=0pt,frame=off]{\mathsurroundmode#1\relax\hsize 100pt x$x$x} \NC \dontleavehmode\inframed[align=normal,offset=0pt,frame=off]{\mathsurroundmode#1\relax\hsize 100pt x $x$ x} \NC #2 @@ -1086,7 +1198,7 @@ with zero being the default behaviour. \typebuffer \getbuffer -\starttabulate[|Tc|c|c|pl|] +\starttabulate[|c|c|c|pl|] \HL \BC mode \BC \type {x$x$x} \BC \type {x $x$ x} \BC effect \NC \NR \HL @@ -1105,7 +1217,7 @@ with zero being the default behaviour. Method six omits the surround glue when there is (x)spacing glue present while method seven does the opposite, the glue is only applied when there is (x)space -glue present too. Anything more fance, like checking the begining or end of a +glue present too. Anything more fancy, like checking the begining or end of a paragraph (or edges of a box) would not be robust anyway. If you want that you can write a callback that runs over a list and analyzes a paragraph. Actually, in that case you could also inject glue (or set the properties of a math node) @@ -1175,7 +1287,7 @@ still stepping through the successively larger variants. When no dimensions are given the \type {noaxis} command can be used to prevent shifting over the axis. You can influence the final class with the keyword \type {class} which will -influence the spacing. +influence the spacing. The numbers are the same as for character classes. \subsection{Fixed scripts} @@ -1196,13 +1308,13 @@ effects. {$\mathscriptsmode#1\mathupright CH_2 + CH^+_2 + CH^2_2$} \starttabulate[|c|c|c|l|] -\NC \bf mode \NC \bf down \NC \bf up \NC \NC \NR -\NC 0 \NC dynamic \NC dynamic \NC \SampleMath{0} \NC \NR -\NC 1 \NC $d$ \NC $u$ \NC \SampleMath{1} \NC \NR -\NC 2 \NC $s$ \NC $u$ \NC \SampleMath{2} \NC \NR -\NC 3 \NC $s$ \NC $u + s - d$ \NC \SampleMath{3} \NC \NR -\NC 4 \NC $d + (s-d)/2$ \NC $u + (s-d)/2$ \NC \SampleMath{4} \NC \NR -\NC 5 \NC $d$ \NC $u + s - d$ \NC \SampleMath{5} \NC \NR +\BC mode \BC down \BC up \BC \NC \NR +\NC 0 \NC dynamic \NC dynamic \NC \SampleMath{0} \NC \NR +\NC 1 \NC $d$ \NC $u$ \NC \SampleMath{1} \NC \NR +\NC 2 \NC $s$ \NC $u$ \NC \SampleMath{2} \NC \NR +\NC 3 \NC $s$ \NC $u + s - d$ \NC \SampleMath{3} \NC \NR +\NC 4 \NC $d + (s-d)/2$ \NC $u + (s-d)/2$ \NC \SampleMath{4} \NC \NR +\NC 5 \NC $d$ \NC $u + s - d$ \NC \SampleMath{5} \NC \NR \stoptabulate The value of this parameter obeys grouping but applies to the whole current @@ -1210,6 +1322,28 @@ formula. % if needed we can put the value in stylenodes but maybe more should go there +\subsection{Penalties: \type {\mathpenaltiesmode}} + +Only in inline math penalties will be added in a math list. You can force +penalties (also in display math) by setting: + +\starttyping +\mathpenaltiesmode = 1 +\stoptyping + +This primnitive is not really needed in \LUATEX\ because you can use the callback +\type {mlist_to_hlist} to force penalties by just calling the regular routine +with forced penalties. However, as part of opening up and control this primitive +makes sense. As a bonus we also provide two extra penalties: + +\starttyping +\prebinoppenalty = -100 % example value +\prerelpenalty = 900 % example value +\stoptyping + +They default to inifinite which signals that they don't need to be inserted. When +set they are injected before a binop or rel noad. This is an experimental feature. + \subsection {Tracing} Because there are quite some math related parameters and values, it is possible diff --git a/doc/context/sources/general/manuals/luatex/luatex-modifications.tex b/doc/context/sources/general/manuals/luatex/luatex-modifications.tex index 2857603ea..b5d8f2750 100644 --- a/doc/context/sources/general/manuals/luatex/luatex-modifications.tex +++ b/doc/context/sources/general/manuals/luatex/luatex-modifications.tex @@ -326,7 +326,7 @@ provide the ability to use content that has been rendered in several places, and images are also common. For that reason we also changed the names: \starttabulate[|l|l|] -\NC \bf new name \NC \bf old name \NC \NR +\BC new name \BC old name \NC \NR \NC \type {\saveboxresource} \NC \type {\pdfxform} \NC \NR \NC \type {\saveimageresource} \NC \type {\pdfximage} \NC \NR \NC \type {\useboxresource} \NC \type {\pdfrefxform} \NC \NR @@ -1063,20 +1063,58 @@ kerns, should be handled in the input or macro package because there is no way w can predict the expected behaviour. In fact, the \type {\linedir} is just a convenience extra which could also have been implemented using node list parsing. +Glue after a dir node is ignored in the linebreak decision but you can bypass that +by setting \type {\breakafterdirmode} to~\type {1}. The following table shows the +difference. Watch your spaces. + +\def\ShowSome#1{% + \BC + \type{#1} + \NC + \breakafterdirmode = 0 + \hsize 0pt + #1 + \NC + \NC + \breakafterdirmode = 1 + \hsize 0pt + #1 + \NC + \NC \NR \HL +} + +\starttabulate[|l|Tp(0pt)|w(5em)|Tp(0pt)|p|] + \HL + \BC \type{\breakafterdirmode} + \BC \type{0} + \NC + \BC \type{1} + \NC + \NC \NR + \HL + \ShowSome{pre {\textdir TLT xxx} post} + \ShowSome{pre {\textdir TLT xxx }post} + \ShowSome{pre{ \textdir TLT xxx} post} + \ShowSome{pre{ \textdir TLT xxx }post} + \ShowSome{pre { \textdir TLT xxx } post} + \ShowSome{pre {\textdir TLT\relax\space xxx} post} +\stoptabulate + + Another adaptation to the \ALEPH\ directional model is control over shapes driven by \type {\hangindent} and \type {\parshape}. This is controlled by a new parameter \type {\shapemode}: -\starttabulate[|cTB|c|] -\NC \NC \bf \type {\hangindent} \NC \bf \type {\parshape} \NC \NR -\NC 0 \NC normal \NC normal \NC \NR -\NC 1 \NC mirrored \NC normal \NC \NR -\NC 2 \NC normal \NC mirrored \NC \NR -\NC 3 \NC mirrored \NC mirrored \NC \NR +\starttabulate[|c|c|c|] +\BC \BC \type {\hangindent} \BC \type {\parshape} \NC \NR +\BC \type{0} \NC normal \NC normal \NC \NR +\BC \type{1} \NC mirrored \NC normal \NC \NR +\BC \type{2} \NC normal \NC mirrored \NC \NR +\BC \type{3} \NC mirrored \NC mirrored \NC \NR \stoptabulate The value is reset to zero (like \type {\hangindent} and \type {\parshape}) -after the paragraph is done with. You can use negative values to preven t +after the paragraph is done with. You can use negative values to prevent this. In \in {figure} [fig:shapemode] a few examples are given. @@ -1217,6 +1255,28 @@ previous code (that mostly used \type {getc} calls), it can be quite a bit faste \stopsubsection +\startsubsection[title=Tabs and spaces] + +We conform to the way other \TEX\ engines handle trailing tabs and spaces. For +decades trailing tabs and spaces (before a newline) were removed from the input +but this behaviour was changed in September 2017 to only handle spaces. We are +aware that this can introduce compatibility issues in existing workflows but +because we don't want too many differences with upstream \TEXLIVE\ we just follow +up on that patch (which is a functional one and not really a fix). It is up to +macro packages maintainers to deal with possible compatibility issues and in +\LUATEX\ they can do so via the callbacks that deal with reading from files. + +The previous behaviour was a known side effect and (as that kind of input +normally comes from generated sources) it was normally dealt with by adding a +comment token to the line in case the spaces and|/|or tabs were intentional and +to be kept. We are aware of the fact that this contradicts some of our other +choices but consistency with other engines and the fact that in \KPSE\ mode a +common file \IO\ layer is used can have a side effect of breaking compatibility. +We still stick to our view that at the log level we can (and might be) more +incompatible. + +\stopsubsection + \stopsection \stopchapter diff --git a/doc/context/sources/general/manuals/luatex/luatex-nodes.tex b/doc/context/sources/general/manuals/luatex/luatex-nodes.tex index d3c2c06da..517d9b6c8 100644 --- a/doc/context/sources/general/manuals/luatex/luatex-nodes.tex +++ b/doc/context/sources/general/manuals/luatex/luatex-nodes.tex @@ -35,6 +35,13 @@ You can ask for a list of fields with the \type {node.fields} (which takes an id and for valid subtypes with \type {node.subtypes} (which takes a string because eventually we might support more used enumerations). +The \type {node.values} function reports some used values. Valid arguments are +\type {dir}, \type {direction}, \type {glue}, \type {pdf_literal}, \type +{pdf_action}, \type {pdf_window} and \type {color_stack}. Keep in mind that the +setters normally expect a number, but this helper gives you a list of what +numbers matter. For practical reason the \type {pagestate} values are also +reported with this helper. + \subsection{Attributes} The newly introduced attribute registers are non|-|trivial, because the value @@ -48,9 +55,9 @@ the low|-|level interface. An \type {attribute_list} item is used as a head pointer for a list of attribute items. It has only one user-visible field: -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC next \NC node \NC pointer to the first attribute \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{next} \NC node \NC pointer to the first attribute \NC \NR \stoptabulate \subsubsection{attribute nodes} @@ -60,11 +67,11 @@ A normal node's attribute field will point to an item of type \type defined \quote {attribute} item, whose \type {next} will point to the second \quote {attribute} item, etc. -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC next \NC node \NC pointer to the next attribute \NC \NR -\NC number \NC number \NC the attribute type id \NC \NR -\NC value \NC number \NC the attribute value \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{next} \NC node \NC pointer to the next attribute \NC \NR +\NC \type{number} \NC number \NC the attribute type id \NC \NR +\NC \type{value} \NC number \NC the attribute value \NC \NR \stoptabulate As mentioned it's better to use the official helpers rather than edit these @@ -76,11 +83,11 @@ and there is no double linked list. These are the nodes that comprise actual typesetting commands. A few fields are present in all nodes regardless of their type, these are: -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC next \NC node \NC the next node in a list, or nil \NC \NR -\NC id \NC number \NC the node's type (\type {id}) number \NC \NR -\NC subtype \NC number \NC the node \type {subtype} identifier \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{next} \NC node \NC the next node in a list, or nil \NC \NR +\NC \type{id} \NC number \NC the node's type (\type {id}) number \NC \NR +\NC \type{subtype} \NC number \NC the node \type {subtype} identifier \NC \NR \stoptabulate The \type {subtype} is sometimes just a stub entry. Not all nodes actually use @@ -98,19 +105,19 @@ internal magic uses a leading \type {temp} nodes to temporarily store a state. \subsubsection{hlist nodes} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC \showsubtypes{list} \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC width \NC number \NC the width of the box \NC \NR -\NC height \NC number \NC the height of the box \NC \NR -\NC depth \NC number \NC the depth of the box \NC \NR -\NC shift \NC number \NC a displacement perpendicular to the character progression direction \NC \NR -\NC glue_order \NC number \NC a number in the range $[0,4]$, indicating the glue order \NC \NR -\NC glue_set \NC number \NC the calculated glue ratio \NC \NR -\NC glue_sign \NC number \NC 0 = \type {normal}, 1 = \type {stretching}, 2 = \type {shrinking} \NC \NR -\NC head/list \NC node \NC the first node of the body of this list \NC \NR -\NC dir \NC string \NC the direction of this box, see~\in[dirnodes] \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{subtype} \NC number \NC \showsubtypes{list} \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{width} \NC number \NC the width of the box \NC \NR +\NC \type{height} \NC number \NC the height of the box \NC \NR +\NC \type{depth} \NC number \NC the depth of the box \NC \NR +\NC \type{shift} \NC number \NC a displacement perpendicular to the character progression direction \NC \NR +\NC \type{glue_order} \NC number \NC a number in the range $[0,4]$, indicating the glue order \NC \NR +\NC \type{glue_set} \NC number \NC the calculated glue ratio \NC \NR +\NC \type{glue_sign} \NC number \NC 0 = \type {normal}, 1 = \type {stretching}, 2 = \type {shrinking} \NC \NR +\NC \type{head/list} \NC node \NC the first node of the body of this list \NC \NR +\NC \type{dir} \NC string \NC the direction of this box, see~\in[dirnodes] \NC \NR \stoptabulate A warning: never assign a node list to the \type {head} field unless you are sure @@ -132,27 +139,27 @@ Contrary to traditional \TEX, \LUATEX\ has more subtypes because we also use rules to store reuseable objects and images. User nodes are invisible and can be intercepted by a callback. -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC \showsubtypes{rule} \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC width \NC number \NC the width of the rule where the special value $-1073741824$ is used for \quote {running} glue dimensions \NC \NR -\NC height \NC number \NC the height of the rule (can be negative) \NC \NR -\NC depth \NC number \NC the depth of the rule (can be negative) \NC \NR -\NC dir \NC string \NC the direction of this rule, see~\in[dirnodes] \NC \NR -\NC index \NC number \NC an optional index that can be referred to \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{subtype} \NC number \NC \showsubtypes{rule} \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{width} \NC number \NC the width of the rule where the special value $-1073741824$ is used for \quote {running} glue dimensions \NC \NR +\NC \type{height} \NC number \NC the height of the rule (can be negative) \NC \NR +\NC \type{depth} \NC number \NC the depth of the rule (can be negative) \NC \NR +\NC \type{dir} \NC string \NC the direction of this rule, see~\in[dirnodes] \NC \NR +\NC \type{index} \NC number \NC an optional index that can be referred to \NC \NR \stoptabulate \subsubsection{ins nodes} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC the insertion class \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC cost \NC number \NC the penalty associated with this insert \NC \NR -\NC height \NC number \NC height of the insert \NC \NR -\NC depth \NC number \NC depth of the insert \NC \NR -\NC head/list \NC node \NC the first node of the body of this insert \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{subtype} \NC number \NC the insertion class \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{cost} \NC number \NC the penalty associated with this insert \NC \NR +\NC \type{height} \NC number \NC height of the insert \NC \NR +\NC \type{depth} \NC number \NC depth of the insert \NC \NR +\NC \type{head/list} \NC node \NC the first node of the body of this insert \NC \NR \stoptabulate There is a set of extra fields that concern the associated glue: \type {width}, @@ -166,21 +173,21 @@ names and both names are equally sensible). \subsubsection{mark nodes} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC unused \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC class \NC number \NC the mark class \NC \NR -\NC mark \NC table \NC a table representing a token list \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{subtype} \NC number \NC unused \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{class} \NC number \NC the mark class \NC \NR +\NC \type{mark} \NC table \NC a table representing a token list \NC \NR \stoptabulate \subsubsection{adjust nodes} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC \showsubtypes{adjust} \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC head/list \NC node \NC adjusted material \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{subtype} \NC number \NC \showsubtypes{adjust} \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{head/list} \NC node \NC adjusted material \NC \NR \stoptabulate A warning: never assign a node list to the \type {head} field unless you are sure @@ -188,14 +195,14 @@ its internal link structure is correct, otherwise an error may be result. \subsubsection{disc nodes} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC \showsubtypes{disc} \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC pre \NC node \NC pointer to the pre|-|break text \NC \NR -\NC post \NC node \NC pointer to the post|-|break text \NC \NR -\NC replace \NC node \NC pointer to the no|-|break text \NC \NR -\NC penalty \NC number \NC the penalty associated with the break, normally \type {\hyphenpenalty} or \type {\exhyphenpenalty} \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{subtype} \NC number \NC \showsubtypes{disc} \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{pre} \NC node \NC pointer to the pre|-|break text \NC \NR +\NC \type{post} \NC node \NC pointer to the post|-|break text \NC \NR +\NC \type{replace} \NC node \NC pointer to the no|-|break text \NC \NR +\NC \type{penalty} \NC number \NC the penalty associated with the break, normally \type {\hyphenpenalty} or \type {\exhyphenpenalty} \NC \NR \stoptabulate The subtype numbers~4 and~5 belong to the \quote {of-f-ice} explanation given @@ -223,11 +230,11 @@ freeing it again might crash \LUATEX). \subsubsection{math nodes} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC \showsubtypes{math} \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC surround \NC number \NC width of the \type {\mathsurround} kern \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{subtype} \NC number \NC \showsubtypes{math} \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{surround} \NC number \NC width of the \type {\mathsurround} kern \NC \NR \stoptabulate There is a set of extra fields that concern the associated glue: \type {width}, @@ -240,13 +247,13 @@ Skips are about the only type of data objects in traditional \TEX\ that are not simple value. The structure that represents the glue components of a skip is called a \type {glue_spec}, and it has the following accessible fields: -\starttabulate[|lT|l|p|] -\NC \rmbf key \NC \bf type \NC \bf explanation \NC \NR -\NC width \NC number \NC the horizontal or vertical displacement \NC \NR -\NC stretch \NC number \NC extra (positive) displacement or stretch amount \NC \NR -\NC stretch_order \NC number \NC factor applied to stretch amount \NC \NR -\NC shrink \NC number \NC extra (negative) displacement or shrink amount\NC \NR -\NC shrink_order \NC number \NC factor applied to shrink amount \NC \NR +\starttabulate[|l|l|p|] +\BC key \BC type \BC explanation \NC \NR +\NC \type{width} \NC number \NC the horizontal or vertical displacement \NC \NR +\NC \type{stretch} \NC number \NC extra (positive) displacement or stretch amount \NC \NR +\NC \type{stretch_order} \NC number \NC factor applied to stretch amount \NC \NR +\NC \type{shrink} \NC number \NC extra (negative) displacement or shrink amount\NC \NR +\NC \type{shrink_order} \NC number \NC factor applied to shrink amount \NC \NR \stoptabulate The effective width of some glue subtypes depends on the stretch or shrink needed @@ -273,11 +280,11 @@ a field can result in a new copy). So in the end the advantages of sharing are not that high (and nowadays memory is less an issue, also given that a glue node is only a few memory words larger than a spec). -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC \showsubtypes{glue} \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC leader \NC node \NC pointer to a box or rule for leaders \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{subtype} \NC number \NC \showsubtypes{glue} \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{leader} \NC node \NC pointer to a box or rule for leaders \NC \NR \stoptabulate In addition there are the \type {width}, \type {stretch} \type {stretch_order}, @@ -290,20 +297,20 @@ a \type {userskip} with subtype zero). \subsubsection{kern nodes} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC \showsubtypes{kern} \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC kern \NC number \NC fixed horizontal or vertical advance \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{subtype} \NC number \NC \showsubtypes{kern} \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{kern} \NC number \NC fixed horizontal or vertical advance \NC \NR \stoptabulate \subsubsection{penalty nodes} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC \showsubtypes{penalty} \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC penalty \NC number \NC the penalty value \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{subtype} \NC number \NC \showsubtypes{penalty} \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{penalty} \NC number \NC the penalty value \NC \NR \stoptabulate The subtypes are just informative and \TEX\ itself doesn't use them. When you @@ -312,24 +319,24 @@ accumulation of \type {club}, \type{widow} and other relevant penalties. \subsubsection[glyphnodes]{glyph nodes} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \rmbf type \NC \rmbf explanation \NC \NR -\NC subtype \NC number \NC bitfield \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC char \NC number \NC the chatacter index in the font \NC \NR -\NC font \NC number \NC the font identifier \NC \NR -\NC lang \NC number \NC the language identifier \NC \NR -\NC left \NC number \NC the frozen \type {\lefthyphenmnin} value \NC \NR -\NC right \NC number \NC the frozen \type {\righthyphenmnin} value \NC \NR -\NC uchyph \NC boolean \NC the frozen \type {\uchyph} value \NC \NR -\NC components \NC node \NC pointer to ligature components \NC \NR -\NC xoffset \NC number \NC a virtual displacement in horizontal direction \NC \NR -\NC yoffset \NC number \NC a virtual displacement in vertical direction \NC \NR -\NC xadvance \NC number \NC an additional advance after the glyph (experimental) \NC \NR -\NC width \NC number \NC the (original) width of the character \NC \NR -\NC height \NC number \NC the (original) height of the character\NC \NR -\NC depth \NC number \NC the (original) depth of the character\NC \NR -\NC expansion_factor \NC number \NC the to be applied expansion_factor \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{subtype} \NC number \NC bitfield \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{char} \NC number \NC the chatacter index in the font \NC \NR +\NC \type{font} \NC number \NC the font identifier \NC \NR +\NC \type{lang} \NC number \NC the language identifier \NC \NR +\NC \type{left} \NC number \NC the frozen \type {\lefthyphenmnin} value \NC \NR +\NC \type{right} \NC number \NC the frozen \type {\righthyphenmnin} value \NC \NR +\NC \type{uchyph} \NC boolean \NC the frozen \type {\uchyph} value \NC \NR +\NC \type{components} \NC node \NC pointer to ligature components \NC \NR +\NC \type{xoffset} \NC number \NC a virtual displacement in horizontal direction \NC \NR +\NC \type{yoffset} \NC number \NC a virtual displacement in vertical direction \NC \NR +%NC \type{xadvance} \NC number \NC an additional advance after the glyph (experimental) \NC \NR +\NC \type{width} \NC number \NC the (original) width of the character \NC \NR +\NC \type{height} \NC number \NC the (original) height of the character\NC \NR +\NC \type{depth} \NC number \NC the (original) depth of the character\NC \NR +\NC \type{expansion_factor} \NC number \NC the to be applied expansion_factor \NC \NR \stoptabulate The \type {width}, \type {height} and \type {depth} values are read|-|only. The @@ -340,12 +347,12 @@ its internal link structure is correct, otherwise an error may be result. Valid bits for the \type {subtype} field are: \starttabulate[|c|l|] -\NC \rmbf bit \NC \bf meaning \NC \NR -\NC 0 \NC character \NC \NR -\NC 1 \NC ligature \NC \NR -\NC 2 \NC ghost \NC \NR -\NC 3 \NC left \NC \NR -\NC 4 \NC right \NC \NR +\BC bit \BC meaning \NC \NR +\NC 0 \NC character \NC \NR +\NC 1 \NC ligature \NC \NR +\NC 2 \NC ghost \NC \NR +\NC 3 \NC left \NC \NR +\NC 4 \NC right \NC \NR \stoptabulate See \in {section} [charsandglyphs] for a detailed description of the \type @@ -368,15 +375,16 @@ and \type {false} gets returned otherwise. When nil is returned, the id is also returned. The \type {is_glyph} variant doesn't check for a subtype being less than 256, so it returns either the character value or nil plus the id. These helpers are not always faster than separate calls but they sometimes permit -making more readable tests. +making more readable tests. The \type {uses_font} helpers takes a node +and font id and returns true when a glyph or disc node references that font. \subsubsection{boundary nodes} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC \showsubtypes{boundary} \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC value \NC number \NC values 0--255 are reserved \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{subtype} \NC number \NC \showsubtypes{boundary} \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{value} \NC number \NC values 0--255 are reserved \NC \NR \stoptabulate This node relates to the \type {\noboundary}, \type {\boundary}, \type @@ -384,16 +392,16 @@ This node relates to the \type {\noboundary}, \type {\boundary}, \type \subsubsection{local_par nodes} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC pen_inter \NC number \NC local interline penalty (from \type {\localinterlinepenalty}) \NC \NR -\NC pen_broken \NC number \NC local broken penalty (from \type {\localbrokenpenalty}) \NC \NR -\NC dir \NC string \NC the direction of this par. see~\in [dirnodes] \NC \NR -\NC box_left \NC node \NC the \type {\localleftbox} \NC \NR -\NC box_left_width \NC number \NC width of the \type {\localleftbox} \NC \NR -\NC box_right \NC node \NC the \type {\localrightbox} \NC \NR -\NC box_right_width \NC number \NC width of the \type {\localrightbox} \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{pen_inter} \NC number \NC local interline penalty (from \type {\localinterlinepenalty}) \NC \NR +\NC \type{pen_broken} \NC number \NC local broken penalty (from \type {\localbrokenpenalty}) \NC \NR +\NC \type{dir} \NC string \NC the direction of this par. see~\in [dirnodes] \NC \NR +\NC \type{box_left} \NC node \NC the \type {\localleftbox} \NC \NR +\NC \type{box_left_width} \NC number \NC width of the \type {\localleftbox} \NC \NR +\NC \type{box_right} \NC node \NC the \type {\localrightbox} \NC \NR +\NC \type{box_right_width} \NC number \NC width of the \type {\localrightbox} \NC \NR \stoptabulate A warning: never assign a node list to the \type {box_left} or \type {box_right} @@ -402,11 +410,11 @@ error may be result. \subsubsection[dirnodes]{dir nodes} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC dir \NC string \NC the direction (but see below) \NC \NR -\NC level \NC number \NC nesting level of this direction whatsit \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{dir} \NC string \NC the direction (but see below) \NC \NR +\NC \type{level} \NC number \NC nesting level of this direction whatsit \NC \NR \stoptabulate A note on \type {dir} strings. Direction specifiers are three|-|letter @@ -436,12 +444,12 @@ or popped from the direction stack. \subsubsection{margin_kern nodes} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC \showsubtypes{margin_kern} \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC width \NC number \NC the advance of the kern \NC \NR -\NC glyph \NC node \NC the glyph to be used \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{subtype} \NC number \NC \showsubtypes{margin_kern} \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{width} \NC number \NC the advance of the kern \NC \NR +\NC \type{glyph} \NC node \NC the glyph to be used \NC \NR \stoptabulate \subsection{Math nodes} @@ -461,11 +469,11 @@ The \type {next} and \type {prev} fields for these subnodes are unused. \subsubsubsection{math_char and math_text_char subnodes} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC char \NC number \NC the character index \NC \NR -\NC fam \NC number \NC the family number \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{char} \NC number \NC the character index \NC \NR +\NC \type{fam} \NC number \NC the family number \NC \NR \stoptabulate The \type {math_char} is the simplest subnode field, it contains the character @@ -475,10 +483,10 @@ conversion (its sole function is to suppress a following italic correction). \subsubsubsection{sub_box and sub_mlist subnodes} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC head/list \NC node \NC list of nodes \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{head/list} \NC node \NC list of nodes \NC \NR \stoptabulate These two subnode types are used for subsidiary list items. For \type {sub_box}, @@ -495,13 +503,13 @@ before, the \type {next} and \type {prev} fields are unused. \subsubsubsection{delim subnodes} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC small_char \NC number \NC character index of base character \NC \NR -\NC small_fam \NC number \NC family number of base character \NC \NR -\NC large_char \NC number \NC character index of next larger character \NC \NR -\NC large_fam \NC number \NC family number of next larger character \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{small_char} \NC number \NC character index of base character \NC \NR +\NC \type{small_fam} \NC number \NC family number of base character \NC \NR +\NC \type{large_char} \NC number \NC character index of next larger character \NC \NR +\NC \type{large_fam} \NC number \NC family number of next larger character \NC \NR \stoptabulate The fields \type {large_char} and \type {large_fam} can be zero, in that case the @@ -515,50 +523,68 @@ associated with the simple math objects: ord, op, bin, rel, open, close, punct, inner, over, under, vcent. These all have the same fields, and they are combined into a single node type with separate subtypes for differentiation. +Some noads have an option field. The values in this bitset are common: + +\starttabulate[|l|r|] +\NC set \NC \type{0x08} \NC \NR +\NC internal \NC \type{0x00} + \type{0x08} \NC \NR +\NC internal \NC \type{0x01} + \type{0x08} \NC \NR +\NC axis \NC \type{0x02} + \type{0x08} \NC \NR +\NC no axis \NC \type{0x04} + \type{0x08} \NC \NR +\NC exact \NC \type{0x10} + \type{0x08} \NC \NR +\NC left \NC \type{0x11} + \type{0x08} \NC \NR +\NC middle \NC \type{0x12} + \type{0x08} \NC \NR +\NC right \NC \type{0x14} + \type{0x08} \NC \NR +\NC no sub script \NC \type{0x21} + \type{0x08} \NC \NR +\NC no super script \NC \type{0x22} + \type{0x08} \NC \NR +\NC no script \NC \type{0x23} + \type{0x08} \NC \NR +\stoptabulate + \subsubsubsection{simple nodes} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC \showsubtypes{noad} \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC nucleus \NC kernel node \NC base \NC \NR -\NC sub \NC kernel node \NC subscript \NC \NR -\NC sup \NC kernel node \NC superscript \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{subtype} \NC number \NC \showsubtypes{noad} \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{nucleus} \NC kernel node \NC base \NC \NR +\NC \type{sub} \NC kernel node \NC subscript \NC \NR +\NC \type{sup} \NC kernel node \NC superscript \NC \NR +\NC \type{options} \NC number \NC bitset of rendering options \NC \NR \stoptabulate \subsubsubsection{accent nodes} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC \showsubtypes{accent} \NC \NR -\NC nucleus \NC kernel node \NC base \NC \NR -\NC sub \NC kernel node \NC subscript \NC \NR -\NC sup \NC kernel node \NC superscript \NC \NR -\NC accent \NC kernel node \NC top accent \NC \NR -\NC bot_accent \NC kernel node \NC bottom accent \NC \NR -\NC fraction \NC number \NC larger step criterium (divided by 1000) \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{subtype} \NC number \NC \showsubtypes{accent} \NC \NR +\NC \type{nucleus} \NC kernel node \NC base \NC \NR +\NC \type{sub} \NC kernel node \NC subscript \NC \NR +\NC \type{sup} \NC kernel node \NC superscript \NC \NR +\NC \type{accent} \NC kernel node \NC top accent \NC \NR +\NC \type{bot_accent} \NC kernel node \NC bottom accent \NC \NR +\NC \type{fraction} \NC number \NC larger step criterium (divided by 1000) \NC \NR \stoptabulate \subsubsubsection{style nodes} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC style \NC string \NC contains the style \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{style} \NC string \NC contains the style \NC \NR \stoptabulate -There are eight possibilities for the string value: one of \quote {display}, -\quote {text}, \quote {script}, or \quote {scriptscript}. Each of these can have -a trailing \type {'} to signify \quote {cramped} styles. +There are eight possibilities for the string value: one of \type {display}, +\type {text}, \type {script}, or \type {scriptscript}. Each of these can have +be prefixed by \type {cramped}. \subsubsubsection{choice nodes} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC display \NC node \NC list of display size alternatives \NC \NR -\NC text \NC node \NC list of text size alternatives \NC \NR -\NC script \NC node \NC list of scriptsize alternatives \NC \NR -\NC scriptscript \NC node \NC list of scriptscriptsize alternatives \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{display} \NC node \NC list of display size alternatives \NC \NR +\NC \type{text} \NC node \NC list of text size alternatives \NC \NR +\NC \type{script} \NC node \NC list of scriptsize alternatives \NC \NR +\NC \type{scriptscript} \NC node \NC list of scriptscriptsize alternatives \NC \NR \stoptabulate Warning: never assign a node list to the \type {display}, \type {text}, \type @@ -567,17 +593,17 @@ structure is correct, otherwise an error may be result. \subsubsubsection{radical nodes} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC \showsubtypes{radical} \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC nucleus \NC kernel node \NC base \NC \NR -\NC sub \NC kernel node \NC subscript \NC \NR -\NC sup \NC kernel node \NC superscript \NC \NR -\NC left \NC delimiter node \NC \NC \NR -\NC degree \NC kernel node \NC only set by \type {\Uroot} \NC \NR -\NC width \NC number \NC required width \NC \NR -\NC options \NC number \NC bitset of rendering options \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{subtype} \NC number \NC \showsubtypes{radical} \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{nucleus} \NC kernel node \NC base \NC \NR +\NC \type{sub} \NC kernel node \NC subscript \NC \NR +\NC \type{sup} \NC kernel node \NC superscript \NC \NR +\NC \type{left} \NC delimiter node \NC \NC \NR +\NC \type{degree} \NC kernel node \NC only set by \type {\Uroot} \NC \NR +\NC \type{width} \NC number \NC required width \NC \NR +\NC \type{options} \NC number \NC bitset of rendering options \NC \NR \stoptabulate Warning: never assign a node list to the \type {nucleus}, \type {sub}, \type @@ -586,16 +612,16 @@ link structure is correct, otherwise an error may be result. \subsubsubsection{fraction nodes} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC width \NC number \NC (optional) width of the fraction \NC \NR -\NC num \NC kernel node \NC numerator \NC \NR -\NC denom \NC kernel node \NC denominator \NC \NR -\NC left \NC delimiter node \NC left side symbol \NC \NR -\NC right \NC delimiter node \NC right side symbol \NC \NR -\NC middle \NC delimiter node \NC middle symbol \NC \NR -\NC options \NC number \NC bitset of rendering options \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{width} \NC number \NC (optional) width of the fraction \NC \NR +\NC \type{num} \NC kernel node \NC numerator \NC \NR +\NC \type{denom} \NC kernel node \NC denominator \NC \NR +\NC \type{left} \NC delimiter node \NC left side symbol \NC \NR +\NC \type{right} \NC delimiter node \NC right side symbol \NC \NR +\NC \type{middle} \NC delimiter node \NC middle symbol \NC \NR +\NC \type{options} \NC number \NC bitset of rendering options \NC \NR \stoptabulate Warning: never assign a node list to the \type {num}, or \type {denom} field @@ -604,16 +630,16 @@ may be result. \subsubsubsection{fence nodes} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC subtype \NC number \NC \showsubtypes{fence} \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC delim \NC delimiter node \NC delimiter specification \NC \NR -\NC italic \NC number \NC italic correction \NC \NR -\NC height \NC number \NC required height \NC \NR -\NC depth \NC number \NC required depth \NC \NR -\NC options \NC number \NC bitset of rendering options \NC \NR -\NC class \NC number \NC spacing related class \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{subtype} \NC number \NC \showsubtypes{fence} \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{delim} \NC delimiter node \NC delimiter specification \NC \NR +\NC \type{italic} \NC number \NC italic correction \NC \NR +\NC \type{height} \NC number \NC required height \NC \NR +\NC \type{depth} \NC number \NC required depth \NC \NR +\NC \type{options} \NC number \NC bitset of rendering options \NC \NR +\NC \type{class} \NC number \NC spacing related class \NC \NR \stoptabulate Warning: some of these fields are used by the renderer and might get adapted in @@ -637,30 +663,30 @@ Whatsit nodes come in many subtypes that you can ask for by running \subsubsubsection{open whatsits} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC stream \NC number \NC \TEX's stream id number \NC \NR -\NC name \NC string \NC file name \NC \NR -\NC ext \NC string \NC file extension \NC \NR -\NC area \NC string \NC file area (this may become obsolete) \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{stream} \NC number \NC \TEX's stream id number \NC \NR +\NC \type{name} \NC string \NC file name \NC \NR +\NC \type{ext} \NC string \NC file extension \NC \NR +\NC \type{area} \NC string \NC file area (this may become obsolete) \NC \NR \stoptabulate \subsubsubsection{write whatsits} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC stream \NC number \NC \TEX's stream id number \NC \NR -\NC data \NC table \NC a table representing the token list to be written \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{stream} \NC number \NC \TEX's stream id number \NC \NR +\NC \type{data} \NC table \NC a table representing the token list to be written \NC \NR \stoptabulate \subsubsubsection{close whatsits} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC stream \NC number \NC \TEX's stream id number \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{stream} \NC number \NC \TEX's stream id number \NC \NR \stoptabulate \subsubsubsection{user_defined whatsits} @@ -669,46 +695,46 @@ User|-|defined whatsit nodes can only be created and handled from \LUA\ code. In effect, they are an extension to the extension mechanism. The \LUATEX\ engine will simply step over such whatsits without ever looking at the contents. -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC user_id \NC number \NC id number \NC \NR -\NC type \NC number \NC type of the value \NC \NR -\NC value \NC number \NC a \LUA\ number \NC \NR -\NC \NC node \NC a node list \NC \NR -\NC \NC string \NC a \LUA\ string \NC \NR -\NC \NC table \NC a \LUA\ table \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{user_id} \NC number \NC id number \NC \NR +\NC \type{type} \NC number \NC type of the value \NC \NR +\NC \type{value} \NC number \NC a \LUA\ number \NC \NR +\NC \NC node \NC a node list \NC \NR +\NC \NC string \NC a \LUA\ string \NC \NR +\NC \NC table \NC a \LUA\ table \NC \NR \stoptabulate The \type {type} can have one of six distinct values. The number is the \ASCII\ value if the first character if the type name (so you can use string.byte("l") instead of \type {108}). -\starttabulate[|lT|lT|p|] -\NC \rmbf value \NC \bf meaning \NC \bf explanation \NC \NR -\NC 97 \NC a \NC list of attributes (a node list) \NC \NR -\NC 100 \NC d \NC a \LUA\ number \NC \NR -\NC 108 \NC l \NC a \LUA\ value (table, number, boolean, etc) \NC \NR -\NC 110 \NC n \NC a node list \NC \NR -\NC 115 \NC s \NC a \LUA\ string \NC \NR -\NC 116 \NC t \NC a \LUA\ token list in \LUA\ table form (a list of triplets) \NC \NR +\starttabulate[|r|c|p|] +\BC value \BC meaning \BC explanation \NC \NR +\NC 97 \NC a \NC list of attributes (a node list) \NC \NR +\NC 100 \NC d \NC a \LUA\ number \NC \NR +\NC 108 \NC l \NC a \LUA\ value (table, number, boolean, etc) \NC \NR +\NC 110 \NC n \NC a node list \NC \NR +\NC 115 \NC s \NC a \LUA\ string \NC \NR +\NC 116 \NC t \NC a \LUA\ token list in \LUA\ table form (a list of triplets) \NC \NR \stoptabulate \subsubsubsection{save_pos whatsits} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR \stoptabulate \subsubsubsection{late_lua whatsits} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC data \NC string \NC data to execute \NC \NR -\NC string \NC string \NC data to execute \NC \NR -\NC name \NC string \NC the name to use for \LUA\ error reporting \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{data} \NC string \NC data to execute \NC \NR +\NC \type{string} \NC string \NC data to execute \NC \NR +\NC \type{name} \NC string \NC the name to use for \LUA\ error reporting \NC \NR \stoptabulate The difference between \type {data} and \type {string} is that on assignment, the @@ -719,31 +745,32 @@ The difference between \type {data} and \type {string} is that on assignment, th \subsubsection{special whatsits} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC data \NC string \NC the \type {\special} information \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{data} \NC string \NC the \type {\special} information \NC \NR \stoptabulate \subsubsection{\PDF\ backend whatsits} \subsubsubsection{pdf_literal whatsits} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC mode \NC number \NC the \quote {mode} setting of this literal \NC \NR -\NC data \NC string \NC the \type {\pdfliteral} information \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{mode} \NC number \NC the \quote {mode} setting of this literal \NC \NR +\NC \type{data} \NC string \NC the \type {\pdfliteral} information \NC \NR \stoptabulate Possible mode values are: -\starttabulate[|lT|p|] -\NC \rmbf value \NC \rmbf \PDFTEX\ keyword \NC \NR -\NC 0 \NC setorigin \NC \NR -\NC 1 \NC page \NC \NR -\NC 2 \NC direct \NC \NR -\NC 3 \NC raw \NC \NR +\starttabulate[|l|p|] +\BC value \BC keyword \NC \NR +\NC 0 \NC \type{origin} \NC \NR +\NC 1 \NC \type{page} \NC \NR +\NC 2 \NC \type{direct} \NC \NR +\NC 3 \NC \type{raw} \NC \NR +\NC 4 \NC \type{text} \NC \NR \stoptabulate The higher the number, the less checking and the more you can run into troubles. @@ -752,58 +779,58 @@ what you generate. \subsubsubsection{pdf_refobj whatsits} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC objnum \NC number \NC the referenced \PDF\ object number \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{objnum} \NC number \NC the referenced \PDF\ object number \NC \NR \stoptabulate \subsubsubsection{pdf_annot whatsits} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC width \NC number \NC the width (not used in calculations) \NC \NR -\NC height \NC number \NC the height (not used in calculations) \NC \NR -\NC depth \NC number \NC the depth (not used in calculations) \NC \NR -\NC objnum \NC number \NC the referenced \PDF\ object number \NC \NR -\NC data \NC string \NC the annotation data \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{width} \NC number \NC the width (not used in calculations) \NC \NR +\NC \type{height} \NC number \NC the height (not used in calculations) \NC \NR +\NC \type{depth} \NC number \NC the depth (not used in calculations) \NC \NR +\NC \type{objnum} \NC number \NC the referenced \PDF\ object number \NC \NR +\NC \type{data} \NC string \NC the annotation data \NC \NR \stoptabulate \subsubsubsection{pdf_start_link whatsits} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC width \NC number \NC the width (not used in calculations) \NC \NR -\NC height \NC number \NC the height (not used in calculations) \NC \NR -\NC depth \NC number \NC the depth (not used in calculations) \NC \NR -\NC objnum \NC number \NC the referenced \PDF\ object number \NC \NR -\NC link_attr \NC table \NC the link attribute token list \NC \NR -\NC action \NC node \NC the action to perform \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{width} \NC number \NC the width (not used in calculations) \NC \NR +\NC \type{height} \NC number \NC the height (not used in calculations) \NC \NR +\NC \type{depth} \NC number \NC the depth (not used in calculations) \NC \NR +\NC \type{objnum} \NC number \NC the referenced \PDF\ object number \NC \NR +\NC \type{link_attr} \NC table \NC the link attribute token list \NC \NR +\NC \type{action} \NC node \NC the action to perform \NC \NR \stoptabulate \subsubsubsection{pdf_end_link whatsits} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{attr} \NC node \NC \NC \NR \stoptabulate \subsubsubsection{pdf_dest whatsits} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC width \NC number \NC the width (not used in calculations) \NC \NR -\NC height \NC number \NC the height (not used in calculations) \NC \NR -\NC depth \NC number \NC the depth (not used in calculations) \NC \NR -\NC named_id \NC number \NC is the \type {dest_id} a string value? \NC \NR -\NC dest_id \NC number \NC the destination id \NC \NR -\NC \NC string \NC the destination name \NC \NR -\NC dest_type \NC number \NC type of destination \NC \NR -\NC xyz_zoom \NC number \NC the zoom factor (times 1000) \NC \NR -\NC objnum \NC number \NC the \PDF\ object number \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{width} \NC number \NC the width (not used in calculations) \NC \NR +\NC \type{height} \NC number \NC the height (not used in calculations) \NC \NR +\NC \type{depth} \NC number \NC the depth (not used in calculations) \NC \NR +\NC \type{named_id} \NC number \NC is the \type {dest_id} a string value? \NC \NR +\NC \type{dest_id} \NC number \NC the destination id \NC \NR +\NC \NC string \NC the destination name \NC \NR +\NC \type{dest_type} \NC number \NC type of destination \NC \NR +\NC \type{xyz_zoom} \NC number \NC the zoom factor (times 1000) \NC \NR +\NC \type{objnum} \NC number \NC the \PDF\ object number \NC \NR \stoptabulate \subsubsubsection{pdf_action whatsits} @@ -811,98 +838,99 @@ what you generate. These are a special kind of item that only appears inside \PDF\ start link objects. -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC action_type \NC number \NC the kind of action involved \NC \NR -\NC action_id \NC number or string \NC token list reference or string \NC \NR -\NC named_id \NC number \NC the index of the destination \NC \NR -\NC file \NC string \NC the target filename \NC \NR -\NC new_window \NC number \NC the window state of the target \NC \NR -\NC data \NC string \NC the name of the destination \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\BC field \BC type \BC explanation \NC \NR +\NC \type{action_type} \NC number \NC the kind of action involved \NC \NR +\NC \type{action_id} \NC number or string \NC token list reference or string \NC \NR +\NC \type{named_id} \NC number \NC the index of the destination \NC \NR +\NC \type{file} \NC string \NC the target filename \NC \NR +\NC \type{new_window} \NC number \NC the window state of the target \NC \NR +\NC \type{data} \NC string \NC the name of the destination \NC \NR \stoptabulate Valid action types are: -\starttabulate[|lT|lT|] -\NC 0 \NC page \NC \NR -\NC 1 \NC goto \NC \NR -\NC 2 \NC thread \NC \NR -\NC 3 \NC user \NC \NR +\starttabulate[|l|l|] +\NC 0 \NC \type{page} \NC \NR +\NC 1 \NC \type{goto} \NC \NR +\NC 2 \NC \type{thread} \NC \NR +\NC 3 \NC \type{user} \NC \NR \stoptabulate Valid window types are: -\starttabulate[|lT|lT|] -\NC 0 \NC notset \NC \NR -\NC 1 \NC new \NC \NR -\NC 2 \NC nonew \NC \NR +\starttabulate[|l|l|] +\NC 0 \NC \type{notset} \NC \NR +\NC 1 \NC \type{new} \NC \NR +\NC 2 \NC \type{nonew} \NC \NR \stoptabulate \subsubsubsection{pdf_thread whatsits} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC width \NC number \NC the width (not used in calculations) \NC \NR -\NC height \NC number \NC the height (not used in calculations) \NC \NR -\NC depth \NC number \NC the depth (not used in calculations) \NC \NR -\NC named_id \NC number \NC is \type {tread_id} a string value? \NC \NR -\NC tread_id \NC number \NC the thread id \NC \NR -\NC \NC string \NC the thread name \NC \NR -\NC thread_attr \NC number \NC extra thread information \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{width} \NC number \NC the width (not used in calculations) \NC \NR +\NC \type{height} \NC number \NC the height (not used in calculations) \NC \NR +\NC \type{depth} \NC number \NC the depth (not used in calculations) \NC \NR +\NC \type{named_id} \NC number \NC is \type {tread_id} a string value? \NC \NR +\NC \type{tread_id} \NC number \NC the thread id \NC \NR +\NC \NC string \NC the thread name \NC \NR +\NC \type{thread_attr} \NC number \NC extra thread information \NC \NR \stoptabulate \subsubsubsection{pdf_start_thread whatsits} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC width \NC number \NC the width (not used in calculations) \NC \NR -\NC height \NC number \NC the height (not used in calculations) \NC \NR -\NC depth \NC number \NC the depth (not used in calculations) \NC \NR -\NC named_id \NC number \NC is \type {tread_id} a string value? \NC \NR -\NC tread_id \NC number \NC the thread id \NC \NR -\NC \NC string \NC the thread name \NC \NR -\NC thread_attr \NC number \NC extra thread information \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{width} \NC number \NC the width (not used in calculations) \NC \NR +\NC \type{height} \NC number \NC the height (not used in calculations) \NC \NR +\NC \type{depth} \NC number \NC the depth (not used in calculations) \NC \NR +\NC \type{named_id} \NC number \NC is \type {tread_id} a string value? \NC \NR +\NC \type{tread_id} \NC number \NC the thread id \NC \NR +\NC \NC string \NC the thread name \NC \NR +\NC \type{thread_attr} \NC number \NC extra thread information \NC \NR \stoptabulate \subsubsubsection{pdf_end_thread whatsits} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{attr} \NC node \NC \NC \NR \stoptabulate \subsubsubsection{pdf_colorstack whatsits} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC stack \NC number \NC colorstack id number \NC \NR -\NC command \NC number \NC command to execute \NC \NR -\NC data \NC string \NC data \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{stack} \NC number \NC colorstack id number \NC \NR +\NC \type{command} \NC number \NC command to execute \NC \NR +\NC \type{data} \NC string \NC data \NC \NR \stoptabulate \subsubsubsection{pdf_setmatrix whatsits} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR -\NC data \NC string \NC data \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR +\NC \type{data} \NC string \NC data \NC \NR \stoptabulate \subsubsubsection{pdf_save whatsits} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR \stoptabulate \subsubsubsection{pdf_restore whatsits} -\starttabulate[|lT|l|p|] -\NC \rmbf field \NC \bf type \NC \bf explanation \NC \NR -\NC attr \NC node \NC list of attributes \NC \NR +\starttabulate[|l|l|p|] +\BC field \BC type \BC explanation \NC \NR +\NC \type{attr} \NC node \NC list of attributes \NC \NR \stoptabulate \section{The \type {node} library} @@ -1541,26 +1569,29 @@ optional. The two returned nodes \type {h} and \type {t} are the head and tail (either one of these can be an inserted kern node, because special kernings with word boundaries are possible). -\subsubsection{\type {node.unprotect_glyphs}} +\subsubsection{\type {node.unprotect_glyphs} and \type {node.unprotect_glyph}} \startfunctioncall -node.unprotect_glyphs(<node> n) +node.unprotect_glyph(<node> n) +node.unprotect_glyphs(<node> n,[<node> n]) \stopfunctioncall Subtracts 256 from all glyph node subtypes. This and the next function are helpers to convert from \type {characters} to \type {glyphs} during node -processing. +processing. The second argument is option and indicates the end of a range. \subsubsection{\type {node.protect_glyphs} and \type {node.protect_glyph}} \startfunctioncall -node.protect_glyphs(<node> n) +node.protect_glyph(<node> n) +node.protect_glyphs(<node> n,[<node> n]) \stopfunctioncall Adds 256 to all glyph node subtypes in the node list starting at \type {n}, except that if the value is 1, it adds only 255. The special handling of 1 means that \type {characters} will become \type {glyphs} after subtraction of 256. A -single character can be marked by the singular call. +single character can be marked by the singular call. The second argument is +option and indicates the end of a range. \subsubsection{\type {node.last_node}} @@ -1604,8 +1635,7 @@ node.setglue(<node> n) node.setglue(<node> n,width,stretch,shrink,stretch_order,shrink_order) \stopfunctioncall -When you pass values, only arguments that are numbers -are assigned so +When you pass values, only arguments that are numbers are assigned so \starttyping node.setglue(n,655360,false,65536) @@ -1613,6 +1643,8 @@ node.setglue(n,655360,false,65536) will only adapt the width and shrink. +When a list node is passed, you set the glue, order and sign instead. + \subsubsection{\type {node.getglue}} The next call will return 5 values (or northing when no glue is passed). @@ -1625,6 +1657,9 @@ The next call will return 5 values (or northing when no glue is passed). When the second argument is false, only the width is returned (this is consistent with \type {tex.get}). +When a list node is passed, you get back the glue that is set, the order of that +glue and the sign. + \subsubsection{\type {node.is_zero_glue}} This function returns \type {true} when the width, stretch and shrink properties @@ -1681,7 +1716,7 @@ node.set_attribute(<node> n, <number> id, <number> val) \stopfunctioncall Sets the attribute with number \type {id} to the value \type {val}. Duplicate -assignments are ignored. {\em [needs explanation]} +assignments are ignored. \subsubsection{\type {node.unset_attribute}} @@ -1733,6 +1768,15 @@ node.check_discretionaries(<node> head) The plural variant runs over all disc nodes in a list, the singular variant checks one node only (it also checks if the node is a disc node). +\subsubsection{\type {node.flatten_discretionaries}} + +This function will remove the discretionaries in the list and inject the replace +field when set. + +\startfunctioncall +<node> head, count = node.flatten_discretionaries(<node> n) +\stopfunctioncall + \subsubsection{\type {node.family_font}} When you pass it a proper family identifier the next helper will return the font @@ -1744,6 +1788,22 @@ font field or getter because it will resolve the family automatically for noads. node.family_font(<integer> fam) \stopfunctioncall +\subsubsection{\type {node.set_synctex_fields} and \type {node.get_synctex_fields}} + +You can set and query the synctex fields, a file number aka tag and a line +number, for a glue, kern, hlist, vlist, rule and math nodes as well as glyph +nodes (although this last one are not used in native synctex). + +\startfunctioncall +node.set_synctex_fields(<integer> f, <integer> l) +<integer> f, <integer> l = + node.get_synctex_fields(<node> n) +\stopfunctioncall + +Of course you need to know what you're doing as no checking on sane values takes +place. Also, the synctex interpreter used in editors is rather peculiar and has +some assumptions (heuristics). + \section{Two access models} Deep down in \TEX\ a node has a number which is an numeric entry in a memory @@ -1812,24 +1872,24 @@ end Some accessors are used frequently and for these we provide more efficient helpers: -\starttabulate[|T|p|] -\NC getnext \NC parsing nodelist always involves this one \NC \NR -\NC getprev \NC used less but is logical companion to \type {getnext} \NC \NR -\NC getboth \NC returns the next and prev pointer of a node \NC \NR -\NC getid \NC consulted a lot \NC \NR -\NC getsubtype \NC consulted less but also a topper \NC \NR -\NC getfont \NC used a lot in \OPENTYPE\ handling (glyph nodes are consulted a lot) \NC \NR -\NC getchar \NC idem and also in other places \NC \NR -\NC getwhd \NC returns the \type {width}, \type {height} and \type {depth} of a list, rule or - (unexpanded) glyph as well as glue (its spec is looked at) and unset nodes\NC \NR -\NC getdisc \NC returns the \type {pre}, \type {post} and \type {replace} fields and - optionally when true is passed also the tail fields. \NC \NR -\NC getlist \NC we often parse nested lists so this is a convenient one too \NC \NR -\NC getleader \NC comparable to list, seldom used in \TEX\ (but needs frequent consulting - like lists; leaders could have been made a dedicated node type) \NC \NR -\NC getfield \NC generic getter, sufficient for the rest (other field names are - often shared so a specific getter makes no sense then) \NC \NR -\NC getbox \NC gets the given box (a list node) \NC \NR +\starttabulate[|l|p|] +\NC \type{getnext} \NC parsing nodelist always involves this one \NC \NR +\NC \type{getprev} \NC used less but is logical companion to \type {getnext} \NC \NR +\NC \type{getboth} \NC returns the next and prev pointer of a node \NC \NR +\NC \type{getid} \NC consulted a lot \NC \NR +\NC \type{getsubtype} \NC consulted less but also a topper \NC \NR +\NC \type{getfont} \NC used a lot in \OPENTYPE\ handling (glyph nodes are consulted a lot) \NC \NR +\NC \type{getchar} \NC idem and also in other places \NC \NR +\NC \type{getwhd} \NC returns the \type {width}, \type {height} and \type {depth} of a list, rule or + (unexpanded) glyph as well as glue (its spec is looked at) and unset nodes\NC \NR +\NC \type{getdisc} \NC returns the \type {pre}, \type {post} and \type {replace} fields and + optionally when true is passed also the tail fields. \NC \NR +\NC \type{getlist} \NC we often parse nested lists so this is a convenient one too \NC \NR +\NC \type{getleader} \NC comparable to list, seldom used in \TEX\ (but needs frequent consulting + like lists; leaders could have been made a dedicated node type) \NC \NR +\NC \type{getfield} \NC generic getter, sufficient for the rest (other field names are + often shared so a specific getter makes no sense then) \NC \NR +\NC \type{getbox} \NC gets the given box (a list node) \NC \NR \stoptabulate In the direct namespace there are more such helpers and most of them are @@ -1857,9 +1917,9 @@ consistency. You can of course always define additional accessor using \type \def\yes{$+$} \def\nop{$-$} -\starttabulate[|T|c|c|] +\starttabulate[|l|c|c|] \HL -\NC \bf function \NC \bf node \NC \bf direct \NC \NR +\BC function \BC node \BC direct \NC \NR \HL %NC \type {do_ligature_n} \NC \yes \NC \yes \NC \NR % was never documented and experimental \NC \type {check_discretionaries}\NC \yes \NC \yes \NC \NR @@ -1886,6 +1946,7 @@ consistency. You can of course always define additional accessor using \type \NC \type {getdepth} \NC \nop \NC \yes \NC \NR \NC \type {getdir} \NC \nop \NC \yes \NC \NR \NC \type {getdisc} \NC \yes \NC \yes \NC \NR +\NC \type {getfam} \NC \nop \NC \yes \NC \NR \NC \type {getfield} \NC \yes \NC \yes \NC \NR \NC \type {getfont} \NC \yes \NC \yes \NC \NR \NC \type {getglue} \NC \yes \NC \yes \NC \NR @@ -1977,10 +2038,13 @@ consistency. You can of course always define additional accessor using \type \NC \type {unprotect_glyphs} \NC \yes \NC \yes \NC \NR \NC \type {unset_attribute} \NC \yes \NC \yes \NC \NR \NC \type {usedlist} \NC \yes \NC \yes \NC \NR +\NC \type {uses_font} \NC \yes \NC \yes \NC \NR \NC \type {vpack} \NC \yes \NC \yes \NC \NR \NC \type {whatsitsubtypes} \NC \yes \NC \nop \NC \NR \NC \type {whatsits} \NC \yes \NC \nop \NC \NR \NC \type {write} \NC \yes \NC \yes \NC \NR +\NC \type {set_synctex_fields} \NC \yes \NC \yes \NC \NR +\NC \type {get_synctex_fields} \NC \yes \NC \yes \NC \NR \stoptabulate % \stopcolumns diff --git a/doc/context/sources/general/manuals/luatex/luatex-style.tex b/doc/context/sources/general/manuals/luatex/luatex-style.tex index c07dc3b76..a277a1178 100644 --- a/doc/context/sources/general/manuals/luatex/luatex-style.tex +++ b/doc/context/sources/general/manuals/luatex/luatex-style.tex @@ -89,7 +89,11 @@ \definecolor[keptcolor] [b=.5] \definecolor[othercolor][r=.5,g=.5] -\setupbodyfont[modern] % we need this in examples so we predefine +\usebodyfont[lucidaot] +\usebodyfont[pagella] +\usebodyfont[cambria] +%usebodyfont[dejavu] +\usebodyfont[modern] % we need this in examples so we predefine % \doifmodeelse {atpragma} { % @@ -214,7 +218,7 @@ luaorbitfactor := 1 ; picture p ; p := lualogo xsized (3PaperWidth/5) ; - draw p shifted center Page shifted (0,-.5ypart center ulcorner p) ; + draw p shifted center Page shifted (0,-.85ypart center ulcorner p) ; StopPage ; \stopuseMPgraphic @@ -354,6 +358,16 @@ [margin=3em, width=5em] +\definestartstop + [notabene] + [style=slanted] + +\definestartstop + [preamble] + [style=normal, + before=\blank, + after=\blank] + % Hans doesn't like the bookmarks opening by default so we comment this: % % \setupinteractionscreen diff --git a/doc/context/sources/general/manuals/luatex/luatex-titlepage.tex b/doc/context/sources/general/manuals/luatex/luatex-titlepage.tex index 8ab56f85d..307741ee1 100644 --- a/doc/context/sources/general/manuals/luatex/luatex-titlepage.tex +++ b/doc/context/sources/general/manuals/luatex/luatex-titlepage.tex @@ -21,7 +21,7 @@ [align=middle, foregroundcolor=blue, frame=off] - {Lua\TeX\\Reference} + {Lua\TeX\\Reference Manual} \definedfont[Bold*default at 18pt] \setupinterlinespace diff --git a/doc/context/sources/general/manuals/luatex/luatex.tex b/doc/context/sources/general/manuals/luatex/luatex.tex index 1613b920b..1d6f16f6a 100644 --- a/doc/context/sources/general/manuals/luatex/luatex.tex +++ b/doc/context/sources/general/manuals/luatex/luatex.tex @@ -1,6 +1,8 @@ % macros=mkvi -% author : Hans Hagen +% \disabledirectives[vspacing.synchronizepage] + +% author : Hans Hagen with Taco Hoekwater, Luigi Scarso & Hartmut Henkel % copyright : PRAGMA ADE & ConTeXt Development Team % license : Creative Commons Attribution ShareAlike 4.0 International % reference : pragma-ade.nl | contextgarden.net | texlive (related) distributions @@ -13,9 +15,13 @@ % 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. +% comment : Some (parts of) 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. +% +% 238 pages : 2017-07-06 +% luatex 9.5 sec / luajittex 7.0 sec +% Dell 7600 / i7 3840QM / passmark 1.922 / Windows 10 64 bit % \tex vs \type vs \syntax vs. \luatex % \em \it \/ @@ -23,16 +29,33 @@ % "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 +\startmode[export] + + \setupbackend + [export=luatex] + +\stopmode + \dontcomplain \startdocument - [status=release, - version=1.0.5] + [status=experimental, + version=1.08.0] + +\startnotmode[*export] + \component luatex-titlepage +\stopnotmode -\component luatex-titlepage +\startmode[*export] + \component luatex-export-titlepage +\stopmode \startfrontmatter \component luatex-contents diff --git a/doc/context/sources/general/manuals/math/math-alignments.tex b/doc/context/sources/general/manuals/math/math-alignments.tex new file mode 100644 index 000000000..bb2801b8a --- /dev/null +++ b/doc/context/sources/general/manuals/math/math-alignments.tex @@ -0,0 +1,297 @@ +\environment math-layout + +\startcomponent math-alignments + +\startchapter[title=Alignments and such] + +\startsection[title=Using ampersands] + +When you come from plain \TEX, using ampersands probably comes as a custom, like in: + +\startbuffer +\startformula +\bordermatrix { + a & b & c & d \cr + e & f & G & h \cr + i & j & k & l \cr +} +\stopformula +\stopbuffer + +\typebuffer \getbuffer + +or: + +\startbuffer +\startformula +\bbordermatrix { + a & b & c & d \cr + e & f & G & h \cr + i & j & k & l \cr +} +\stopformula +\stopbuffer + +\typebuffer \getbuffer + +A more \CONTEXT\ way is this: + +\startbuffer +\startformula +\startbordermatrix + \NC a \NC b \NC c \NC d \NR + \NC e \NC f \NC G \NC h \NR + \NC i \NC j \NC k \NC l \NR +\stopbordermatrix +\stopformula +\stopbuffer + +\typebuffer \getbuffer + +and: + +\startbuffer +\startformula +\startbbordermatrix + \NC a \NC b \NC c \NC d \NR + \NC e \NC f \NC G \NC h \NR + \NC i \NC j \NC k \NC l \NR +\stopbbordermatrix +\stopformula +\stopbuffer + +\typebuffer \getbuffer + +Just that you know. In general ampersands in \CONTEXT\ text mode are just that: +ampersands, not something alignment related. + +\stopsection + +\startsection[title=Locations] + +The \type {location} feature gives some control over the alignment of alignments. +The following examples are taken from an email exchange with Henri Menke. + +\startbuffer +\startplaceformula + \startformula + \startmathalignment[location=top] + \NC a + b \NC= c + d \NR + \NC a + b \NC= c + d \NR + \NC a + b \NC= c + d \NR + \stopmathalignment + \quad\text{or}\quad + \startmathalignment[location=center] + \NC a + b \NC= c + d \NR + \NC a + b \NC= c + d \NR + \NC a + b \NC= c + d \NR + \stopmathalignment + \quad\text{or}\quad + \startmathalignment[location=bottom] + \NC a + b \NC= c + d \NR + \NC a + b \NC= c + d \NR + \NC a + b \NC= c + d \NR + \stopmathalignment + \stopformula +\stopplaceformula +\stopbuffer + +\typebuffer \getbuffer + +Numbering works ok for a single mathalignment + +\startbuffer +\startplaceformula + \startformula + \startmathalignment[number=auto] + \NC a + b \NC= c + d \NR + \NC a + b \NC= c + d \NR + \NC a + b \NC= c + d \NR + \stopmathalignment + \stopformula +\stopplaceformula +\stopbuffer + +\typebuffer \getbuffer + +But for one with a location the results are suboptimal: + +\startbuffer +\startplaceformula + \startformula + \startmathalignment[location=center,number=auto] + \NC a + b \NC= c + d \NR + \NC a + b \NC= c + d \NR + \NC a + b \NC= c + d \NR + \stopmathalignment + \stopformula +\stopplaceformula +\stopbuffer + +\typebuffer \getbuffer + +Here is a real example: + +\startbuffer +\startplaceformula + \startformula + U_2 = \frac{1}{2!} + \int_0^\beta \diff\tau_1 \int_0^\beta \diff\tau_2\; + \sum_{\startsubstack k_1,q_1 \NR k_2,q_2 \stopsubstack} + \Bigl\langle + \startmathalignment[location=top,align=left] + \NC + \mathcal T \Bigl[ + c_{k_1}^\dagger (\tau_1) + \Delta_{k_1,q_1}^r c_{-k_1}^* (\tau_1) + c_{-q_1}^T (\tau_1) + \Delta_{k_1,q_1}^{r\dagger} c_{q_1} (\tau_1) + \Bigr] + \NR + \NC + \times \Bigl[ + c_{k_2}^\dagger(\tau_2) \Delta_{k_2,q_2}^r c_{-k_2}^* + (\tau_2) + c_{-q_2}^T (\tau_2) \Delta_{k_2,q_2}^{r\dagger} + c_{q_2} (\tau_2) + \Bigr] \Bigr\rangle . + \NR + \stopmathalignment + \stopformula +\stopplaceformula +\stopbuffer + +\typebuffer \getbuffer + +\stopsection + +\startsection[title=Tuning alignments] + +Again a few examples of manipulating alignments. It really helps to play +with examples if you want to get an idea what is possible. + +\startbuffer +\startformula + \startalign[m=2,align={middle}] + \NC \text to 6cm{} \NC x = 0 \NR + \stopalign +\stopformula + +\startformula + \startalign[m=2,align={middle}] + \NC \text to 6cm{One\hfill} \NC a = 1 \NR + \NC \text to 6cm{One Two\hfill} \NC b = 2 \NR + \NC \text to 6cm{One Two Three\hfill} \NC c = 3 \NR + \stopalign +\stopformula + +\startformula + \startalign[m=2,align={left}] + \NC \text to 6cm{One\hfill} \NC a = 1 \NR + \NC \text to 6cm{One Two\hfill} \NC b = 2 \NR + \NC \text to 6cm{One Two Three\hfill} \NC c = 3 \NR + \stopalign +\stopformula +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\startformula + \startalign[m=2,align={middle}] + \NC \text to 6cm{} \NC x = 0 \NR + \stopalign +\stopformula + +\startformula + \startalign[m=2,align={middle}] + \NC \text to 6cm{One} \NC a = 1 \NR + \NC \text to 6cm{One Two} \NC b = 2 \NR + \NC \text to 6cm{One Two Three} \NC c = 3 \NR + \stopalign +\stopformula + +\startformula + \startalign[m=2,align={left}] + \NC \text to 6cm{One} \NC a = 1 \NR + \NC \text to 6cm{One Two} \NC b = 2 \NR + \NC \text to 6cm{One Two Three} \NC c = 3 \NR + \stopalign +\stopformula +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\startformula + \startalign[m=2,align={middle}] + \NC \text{} \NC x = 0 \NR + \stopalign +\stopformula + +\startformula + \startalign[m=2,align={middle}] + \NC \text{One} \NC a = 1 \NR + \NC \text{One Two} \NC b = 2 \NR + \NC \text{One Two Three} \NC c = 3 \NR + \stopalign +\stopformula + +\startformula + \startalign[m=2,align={left}] + \NC \text{One} \NC a = 1 \NR + \NC \text{One Two} \NC b = 2 \NR + \NC \text{One Two Three} \NC c = 3 \NR + \stopalign +\stopformula +\stopbuffer + +\typebuffer \getbuffer + +\stopsection + +\startsection[title={Splitting over pages}] + +Because formula placement has positioning options a formula gets +wrapped in a box. As a consequence formulas will not break across +pages. This can be an issue with alignments. There is an experimental +option for this (the result is shown in \in {figure} [fig:splitalign]): + +\startbuffer[demo] +\usemodule[art-01] +\setupbodyfont[13pt] +\starttext + \input tufte + \startplaceformula + \startsplitformula + \startalign + \NC a \EQ b \NR[+] + \NC \EQ d \NR + \NC c \EQ f \NR[+] + \NC \EQ g \NR + \NC \EQ h \NR[+] + \dorecurse{100}{\NC \EQ i + #1 - #1\NR[+]}% + \NC \EQ x \NR + \stopalign + \stopsplitformula + \stopplaceformula + \input tufte +\stoptext +\stopbuffer + +\typebuffer[demo] + +\startplacefigure[title={Splitting an alignment.},reference=fig:splitalign] + \startcombination[nx=4,ny=1] + {\typesetbuffer[demo][page=1,width=\measure{combination}]} {} + {\typesetbuffer[demo][page=2,width=\measure{combination}]} {} + {\typesetbuffer[demo][page=3,width=\measure{combination}]} {} + {\typesetbuffer[demo][page=4,width=\measure{combination}]} {} + \stopcombination +\stopplacefigure + +\stoptext + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/math/math-definitions.tex b/doc/context/sources/general/manuals/math/math-definitions.tex new file mode 100644 index 000000000..d8903121a --- /dev/null +++ b/doc/context/sources/general/manuals/math/math-definitions.tex @@ -0,0 +1,101 @@ +\environment math-layout + +\startcomponent math-definitions + +\startchapter[title=Definitions] + +\startsection[title=Special stackers] + +There are many math symbols but never enough. Here is an example of how you can +roll out your own. We start out with nothing: + +\startbuffer +\definemathstackers + [nosymbol] + [voffset=\zeropoint, + hoffset=\zeropoint, + mathclass=ord, + topoffset=\zeropoint, + middlecommand=, + color=maincolor] +\stopbuffer + +\typebuffer \getbuffer + +You can now use this class of stackers: + +\startbuffer +\startformula + \mathover [nosymbol] {"2217} {A} + \mathover [nosymbol] {"2218} {A} + \mathover [nosymbol] {"2219} {A} +\stopformula +\stopbuffer + +\typebuffer + +This looks like this: + +\getbuffer + +But we want proper math, which means an an italic nucleus, a properly placed +accent, a shift of that accent matching the slope or the nucleus, so we actually +need: + +\startbuffer +\definemathstackers + [mysymbol] + [voffset=-.30\mathexheight, + hoffset=\zeropoint, + mathclass=ord, + topoffset=.4\mathemwidth, + middlecommand=\mathematics, + color=maincolor] +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\startformula + \mathover [mysymbol]{"2217} {A} + \mathover [mysymbol]{"2218} {A} + \mathover [mysymbol]{"2219} {A} + \mathunder [mysymbol] {"2217}{A} + \mathunder [mysymbol] {"2218}{A} + \mathunder [mysymbol] {"2219}{A} + \mathdouble[mysymbol]{"2217}{"2217}{A} + \mathdouble[mysymbol]{"2218}{"2218}{A} + \mathdouble[mysymbol]{"2219}{"2219}{A} +\stopformula +\stopbuffer + +We show both over and under variants: + +\typebuffer + +So this time we get: + +\getbuffer + +We can now redefine the \quote {interiorset} symbol to use +\type {0x2217} instead of \type {0x2218}: + +\startbuffer +\definemathover[mysymbol][interiorset]["2217] + +\startformula + \interiorset{A}^{\interiorset{A}^{\interiorset{A}}} +\stopformula +\stopbuffer + +\typebuffer + +Of course normally you will not use color: + +\getbuffer + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/math/math-features.tex b/doc/context/sources/general/manuals/math/math-features.tex index 3869c575e..863493804 100644 --- a/doc/context/sources/general/manuals/math/math-features.tex +++ b/doc/context/sources/general/manuals/math/math-features.tex @@ -122,6 +122,84 @@ show the plus sign. \stopsection +\startsection[title=Script kerning] + +Text in math is somewhat special. First of all, a math font is not a text fonts +because the characters and glyphs have a different purpose. Text features are +normally not present (and often not even wanted). Anyway, you can force a text +font, but that doesn't mean you will get for instance kerning. You can force a +box which in turn will trigger font processing, but then you normally loose the +script related size properties. So we end up with some juggling possibly combined +with user intervention, and that is what the \type {\text} macro does. + +But still there is the kern between a variable and its subscript to consider, +something that normally is dealt with with staircase kerns, an \OPENTYPE\ math +speciality. But, as we progress over the math list, and we bind a subscript to a +variable, that subscript can be anything: a simple character, or more characters +(a list) or something wrapped in a box. There is simply no universal solution +that we can hard code because sometimes you don't want that special kerning. This +is why in \LUATEX\ the integer variable \type {\mathscriptboxmode} controls the +way this is dealt with. + +\starttabulate[|l|p|] +\NC \type {0} \NC forget about kerning \NC \NR +\NC \type {1} \NC kern math sub lists with a valid glyph (default in the engine) \NC \NR +\NC \type {2} \NC also kern math sub boxes that have a valid glyph (default in \CONTEXT) \NC \NR +\NC \type {3} \NC only kern math sub boxes with a boundary node present \NC \NR +\stoptabulate + +Here we show some examples of how this parameter controls kerning. Watch the +difference between a simple font switch and a text wrapped in a box. There are +differences between fonts: some fonts have kerns, some don't. When present kerns +are passed to the engine without further user intervention. + +\startbuffer[1] + $T_{\tf fluff}$ +\stopbuffer + +\startbuffer[2] + $T_{\text{fluff}}$ +\stopbuffer + +\startbuffer[3] + $T_{\text{\boundary1 fluff}}$ +\stopbuffer + +\unexpanded\def\Show#1#2#3% + {\doifelsenothing{#3} + {\typeinlinebuffer[#1]} + {\doifelse{#3}{-} + {\type{mode #2}} + {\switchtobodyfont[#3,big]\setstrut\strut\showfontkerns\showglyphs\mathscriptboxmode#2\relax\inlinebuffer[#1]}}} + +% \starttabulate[|lT|c|c|c|c|c|] +% \NC \NC \Show{1}{0}{} \NC\Show{1}{1}{} \NC \Show{2}{1}{} \NC \Show{2}{2}{} \NC \Show{3}{3}{} \NC \NR +% \NC \NC \Show{1}{0}{-} \NC\Show{1}{1}{-} \NC \Show{2}{1}{-} \NC \Show{2}{2}{-} \NC \Show{3}{3}{-} \NC \NR +% \NC modern \NC \Show{1}{0}{modern} \NC\Show{1}{1}{modern} \NC \Show{2}{1}{modern} \NC \Show{2}{2}{modern} \NC \Show{3}{3}{modern} \NC \NR +% \NC lucidaot \NC \Show{1}{0}{lucidaot} \NC\Show{1}{1}{lucidaot} \NC \Show{2}{1}{lucidaot} \NC \Show{2}{2}{lucidaot} \NC \Show{3}{3}{lucidaot} \NC \NR +% \NC pagella \NC \Show{1}{0}{pagella} \NC\Show{1}{1}{pagella} \NC \Show{2}{1}{pagella} \NC \Show{2}{2}{pagella} \NC \Show{3}{3}{pagella} \NC \NR +% \NC cambria \NC \Show{1}{0}{cambria} \NC\Show{1}{1}{cambria} \NC \Show{2}{1}{cambria} \NC \Show{2}{2}{cambria} \NC \Show{3}{3}{cambria} \NC \NR +% \NC dejavu \NC \Show{1}{0}{dejavu} \NC\Show{1}{1}{dejavu} \NC \Show{2}{1}{dejavu} \NC \Show{2}{2}{dejavu} \NC \Show{3}{3}{dejavu} \NC \NR +% \stoptabulate + +\def\ShowMore#1#2% + {\subsubject{\Show{#1}{#2}{} (\Show{#1}{#2}{-})} + \starttabulate[|lT|c|c|c|c|c|] + \NC modern \NC \Show{#1}{#2}{modern} \NC \NR + \NC lucidaot \NC \Show{#1}{#2}{lucidaot} \NC \NR + \NC pagella \NC \Show{#1}{#2}{pagella} \NC \NR + \NC cambria \NC \Show{#1}{#2}{cambria} \NC \NR + \NC dejavu \NC \Show{#1}{#2}{dejavu} \NC \NR + \stoptabulate} + +\ShowMore{1}{0} +\ShowMore{1}{1} +\ShowMore{2}{1} +\ShowMore{2}{2} +\ShowMore{3}{3} + +\stopsection + \stopchapter \stopcomponent diff --git a/doc/context/sources/general/manuals/math/math-input.tex b/doc/context/sources/general/manuals/math/math-input.tex new file mode 100644 index 000000000..d395e1865 --- /dev/null +++ b/doc/context/sources/general/manuals/math/math-input.tex @@ -0,0 +1,100 @@ +% language=uk + +\environment math-layout + +\startcomponent math-input + +\startchapter[title=Inputting math] + +\startsection[title=Collapsing] + +When in text mode you enter a combination of combining accent and character, a +composed character is assumed and often you then get one shape in your document. +A similar feature is available in math mode. After some discussion and analysis +of the potential clashes and confusion (thanks to Aditya Mahajan) we settled on a +combination of methods: so called math lists entries that we entered in the +character database and|/|or so called special sequences that are part of +\UNICODE. In the next tables we use \type {ml} for math list and \type {sp} for +specials. Collapsing mode \type {1} only uses the specials, while \type {2} first +checks the specials and then the math lists, and \type {3} does the reverse. + +In the database you can find this (a few fields have been omitted): + +\starttyping +[0x2260] = { + adobename = "notequal", + category = "sm", + description = "NOT EQUAL TO", + mathlist = { 0x2F, 0x3D }, + mathspec = { + { + class = "relation", + name = "neq", + }, + { + class = "relation", + name = "ne", + }, + }, + specials = { "char", 0x3D, 0x338 }, + unicodeslot = 0x2260, +} +\stoptyping + +and + +\starttyping +[0x2261] = { + adobename = "equivalence", + category = "sm", + description = "IDENTICAL TO", + mathclass = "relation", + mathextensible = "h", + mathname = "equiv", + mathlist = { 0x3D, 0x3D }, + unicodeslot = 0x2261, +} +\stoptyping + +Here are a few examples: + +\def\Test#1% + {\NC \bf \type{$#1$} + \NC \setupmathematics[collapsing=0] $#1$ + \NC \setupmathematics[collapsing=1] $#1$ + \NC \setupmathematics[collapsing=2] $#1$ + \NC \setupmathematics[collapsing=3] $#1$ \NC \NR} + +\starttabulate[|c|cp|cp|cp|cp|] + \NC \BC \ttbf 0 \BC \ttbf 1 (sp) \BC \ttbf 2 (sp ml) \BC \ttbf 3 (ml sp) \BC \NR + \Test{==} + \Test{/=} + \Test{>=} +\stoptabulate + +A complete list of collapses can be generated after loading one of the tracing +modules: + +\startbuffer +\usemodule[math-ligatures] +\stopbuffer + +\typebuffer \getbuffer + +This provides the command: + +\startbuffer +\showmathligatures +\stopbuffer + +\typebuffer + +which gives: + +\start \switchtobodyfont[8pt] \getbuffer \stop + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/math/math-introduction.tex b/doc/context/sources/general/manuals/math/math-introduction.tex index f5d241004..de7c0a960 100644 --- a/doc/context/sources/general/manuals/math/math-introduction.tex +++ b/doc/context/sources/general/manuals/math/math-introduction.tex @@ -7,7 +7,18 @@ This manual is not a systematic discussion about math in \CONTEXT\ but more a collection of wrap|-|ups. The file also serves as testcase. The content can change over time and can also serve as a trigger for discussions on the mailing -list. Suggestions are welcome. +list. Content gets added sort of random. Suggestions are welcome. + +We discuss high level as well as low level commands. Some of the low level +commands (primitives) are wrapped in high level commands but you can of course +always revert to bare \TEX. + +I won't go into much detail about typesetting beautiful math, for that I refer to +the \TEX book. \footnote {The most beautiful math is not typeset by \TEX\ anyway: +just search on YouTube for \quotation {Mathematics} by Hollie McNish, the +Metropole Orkest (conducted by Jules Buckley) and Martin Pyper.} + +% https://www.youtube.com/watch?v=SB8_2Yuj8Og \startlines Hans Hagen diff --git a/doc/context/sources/general/manuals/math/math-layout.tex b/doc/context/sources/general/manuals/math/math-layout.tex index 92ced8f22..83137444d 100644 --- a/doc/context/sources/general/manuals/math/math-layout.tex +++ b/doc/context/sources/general/manuals/math/math-layout.tex @@ -1,10 +1,17 @@ \startenvironment math-layout -\switchtobodyfont [modern] -\switchtobodyfont [dejavu] -\switchtobodyfont [cambria] -\switchtobodyfont[lucidaot] -\switchtobodyfont [xits] +\enabledirectives[fontgoodies.mathkerning] + +\usebodyfont [modern] +\usebodyfont [cambria] +\usebodyfont [lucidaot] +\usebodyfont [xits] +\usebodyfont [stixtwo] +\usebodyfont [dejavu] +\usebodyfont [pagella] +\usebodyfont [termes] +\usebodyfont [bonum] +\usebodyfont [schola] \setupbodyfont [pagella] @@ -32,21 +39,24 @@ height=middle, width=middle] +\definecolor[maincolor] [darkmagenta] +\definecolor[extracolor][darkyellow] + \setuphead [chapter] [header=high, style=\bfc, - color=darkmagenta] + color=maincolor] \setuphead [section] [style=\bfb, - color=darkmagenta] + color=maincolor] \setuphead [subsection] [style=\bfa, - color=darkmagenta] + color=maincolor] \usemodule[abr-02] diff --git a/doc/context/sources/general/manuals/math/math-mkiv.tex b/doc/context/sources/general/manuals/math/math-mkiv.tex index f36b1032d..11fb4ca1c 100644 --- a/doc/context/sources/general/manuals/math/math-mkiv.tex +++ b/doc/context/sources/general/manuals/math/math-mkiv.tex @@ -31,12 +31,17 @@ \stopfrontmatter \startbodymatter + \component math-input + \component math-definitions \component math-spacing \component math-framing \component math-numbering \component math-combining \component math-features + \component math-alignments + \component math-suboptimal \component math-tricks + \component math-oddities \stopbodymatter \stopdocument diff --git a/doc/context/sources/general/manuals/math/math-numbering.tex b/doc/context/sources/general/manuals/math/math-numbering.tex index 64f766628..1576e17bb 100644 --- a/doc/context/sources/general/manuals/math/math-numbering.tex +++ b/doc/context/sources/general/manuals/math/math-numbering.tex @@ -69,6 +69,61 @@ are some examples: \typebuffer \getbuffer +In the next examples we demonstrate how we can avoid numbering, pass a reference as key, +use assignments instead and add a title or suffix. + +\startbuffer +\startplaceformula + \startformula e=mc^2 \stopformula +\stopplaceformula +\startplaceformula[-] + \startformula e=mc^2 \stopformula +\stopplaceformula +\startplaceformula[p] + \startformula e=mc^2 \stopformula +\stopplaceformula +\startplaceformula[reference=foo] + \startformula e=mc^2 \stopformula +\stopplaceformula +\startplaceformula[title=whatever] + \startformula e=mc^2 \stopformula +\stopplaceformula +\startplaceformula[suffix=q] + \startformula e=mc^2 \stopformula +\stopplaceformula +\startplaceformula[r] + \startformula e=mc^2 \stopformula +\stopplaceformula +\stopbuffer + +\typebuffer \getbuffer + +If you want consistent spacing you can enforce this: + +\startbuffer +\startplaceformula[s] + \startformula e=mc^2 \stopformula +\stopplaceformula +\startplaceformula[-] + \startformula e=mc^2 \stopformula +\stopplaceformula +\startplaceformula[-] + \startformula e=mc^2 \stopformula +\stopplaceformula +\setupformulas[numberstrut=always] +\startplaceformula[-] + \startformula e=mc^2 \stopformula +\stopplaceformula +\startplaceformula[-] + \startformula e=mc^2 \stopformula +\stopplaceformula +\stopbuffer + +\typebuffer \start \showstruts \getbuffer \stop + +Possible values for \type {numberstrut} are \type {yes} (the default), \type +{always} and \type {no}. + \stopchapter \stopcomponent diff --git a/doc/context/sources/general/manuals/math/math-oddities.tex b/doc/context/sources/general/manuals/math/math-oddities.tex new file mode 100644 index 000000000..015a30126 --- /dev/null +++ b/doc/context/sources/general/manuals/math/math-oddities.tex @@ -0,0 +1,176 @@ +% language=uk + +\environment math-layout + +\startcomponent math-oddities + +\startchapter[title=Things you might forget] + +\startsection[title=Ampersands] + +You can skip this, but if you continue reading, here is some low level plain code +(don't use this in \CONTEXT): + +\starttyping +\def\matrix#1% + {\null + \, + \vcenter + {\normalbaselines + \ialign{\hfil$##$\hfil && \quad\hfil$##$\hfil\crcr + \mathstrut\crcr + \noalign{\kern-\baselineskip} + #1\crcr + \mathstrut\crcr + \noalign{\kern-\baselineskip}}}% + \,} +\stoptyping + +You see the \type {&} here and it's the alignment cell separator. The special +meaning of these characters is determined by the so called catcode. Here we have: + +\starttyping +\catcode"26=4 +\stoptyping + +Character \type {0x26} is the ampersand. In \CONTEXT\ this character can be used +in text mode because we never use it as alignment character, which is something +typical \TEX. The same is true for \type {^} and \type {_}. So, effectively we +have (for instance): + +\starttyping +\catcode"26=12 +\stoptyping + +In order to still get this \type {&} supported as alignment character in math +mode, we have to jump through some hoops. Think of this (again, don't do this in +\CONTEXT): + +\starttyping +\bgroup + \global\mathcode"26="8000 + + \catcode"26=4 + + \xdef\normalmathaligntab{&} + + \catcode"26=13 + + \global\everymath{\def&{\normalmathaligntab}} +\egroup +\stoptyping + +Before we go on you should realize that we never use the \type {&} in \CONTEXT\ +as separator. The sole reason for dealing with this issue is that users can have +their own code that uses the ampersand that way. In \CONTEXT\ we do things like: + +\starttyping +\startformula + \startmatrix + \NC 1 \NC 2 \NR + \NC 3 \NC 4 \NR + \stopmatrix +\stopformula +\stoptyping + +Where \type {\NC} can be more powerful than a \type {&}. Anyhow, the reason for +discussing this here is that there can be surprises. In a running text you can do +this: + +\starttyping +A & B +\stoptyping + +Which procces okay and gives the ampersand as glyph. The following is also okay: + +\starttyping +$A \Umathchar"2"0"26 B$ +\stoptyping + +However, the next one: + +\starttyping +$A \char"26 B$ +\stoptyping + +fails with a \type {Misplaced alignment tab character &}. The reason is that +where in text mode \TEX's parser will turn the \type {\char} into a character +node and carry on afterwards, in math mode it will treat this inpout as were it a +directly input character, so the above is like, where the \type {&} has active +properties and becomes the sparator ampersand which then triggers the error: + +\starttyping +$A & B$ +\stoptyping + +This means that we cannot have a definition like: + +\starttyping +\def\AND{\char"26\relax} +\stoptyping + +that can be used in math mode, which is why the \CWEB\ macros do: + +\starttyping +\def\AND{\def\AND{\mathchar"2026\relax}\AND} +\stoptyping + +Back to the plain example. The \type {\matrix} command has to be wrapped in +math mode and therefore the \type {&} will adapt, while in most \CONTEXT\ +constructs that use alignment, we're not in math mode at all when we start +with the alignment. Therefore the \type {&} will be just an ampersand in most +\CONTEXT\ cases. + +So to summarize: don't expect \type {\char"26} to work out well in math mode +because all kind of magic kicks in. These are the more obscure features and side +effects of \TEX\ dealing with input and it's really hard to predict how \TEX\ +will see the ampersand you entered. You need to know the internals and even then +it's non trivial. Take + +\starttyping +\startformula +\startalign + \NC x \NR + \NC x \NR +\stopalign +\stopformula +\stoptyping + +versus: + +\starttyping +\startformula +\startalign + & x \NR + & x \NR +\stopalign +\stopformula +\stoptyping + +versus: + +\starttyping +\startformula +\startalign + \NC x & y \NR + \NC x & y \NR +\stopalign +\stopformula +\stoptyping + +The first case works as expected, the second one treats the \type {&} as text and +the third one, as we enter math mode with \type {\NC}, depends on circumstances. +If you use just \CONTEXT\ math coding, you can say: + +\starttyping +\setupmathematics + [ampersand=normal] +\stoptyping + +And always render an ampersand (although a math one in math mode). + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/math/math-spacing.tex b/doc/context/sources/general/manuals/math/math-spacing.tex index 3412a3abc..913a90d9e 100644 --- a/doc/context/sources/general/manuals/math/math-spacing.tex +++ b/doc/context/sources/general/manuals/math/math-spacing.tex @@ -1,3 +1,5 @@ +% language=uk + \environment math-layout \startcomponent math-spacing @@ -392,6 +394,352 @@ Of course better is to fix the font. \stopsection +\startsection[title=Multiline] + +Inline formulas can span lines but display math normally sits on one line unless +one uses alignment mechanisms. Take this: + +\startbuffer[demo] +\startformula + x\dorecurse{30}{ + #1x^{#1x}} = 10 +\stopformula +\stopbuffer + +\typebuffer[demo] + +\par \start \setupformula[split=no] \getbuffer[demo] \stop \par + +You can set \type {split} to \type {yes} using \type {\setupformula} and get the +following: + +\par \start \setupformula[split=yes] \getbuffer[demo] \stop \par + +Maybe nicer is to also set \type {align} to \type {flushleft}: + +\par \start \setupformula[split=yes,align=flushleft] \getbuffer[demo] \stop \par + +If you want the binary operators to start the lines you can set this: + +\startbuffer[setup] +\setupmathematics[setups=math:spacing:split] +\setupformulas[split=yes,align=flushleft] +\stopbuffer + +\typebuffer[setup] + +\par \start \getbuffer[setup,demo] \stop \par + +You can prevent a split with a large penalty. Here is a test that yuou can run +to play with this feature: + +\starttyping +\dostepwiserecurse {30} {100} {1} { + \hsize \dimexpr 40pt + #1pt \relax + \startformula + y = a \dorecurse {50} { + \penalty 10000 {\bf + ##1b} + + ##1c^2 + } + \stopformula + \page +} +\stoptyping + +There is an experimental alignment mechanism available. Watch the following +examples: + +\startbuffer[demo] +before + \startformula + z + 3y = \alignhere x + \dorecurse{20}{ + #1x^{#1x}} + \stopformula +inbetween + \startformula + z + 3y \alignhere = 1 + \dorecurse{4}{ + \dorecurse{#1}{+ #1x^{##1x}} + \ifnum#1<4\breakhere\fi + } + \stopformula +after +\stopbuffer + +\typebuffer[demo] + +\startbuffer[setup] +\setupformula + [split=no] +\stopbuffer + +\typebuffer[setup] \start \getbuffer[setup,demo] \stop + +\startbuffer[setup] +\setupformula + [split=yes, + align=flushleft] +\stopbuffer + +\typebuffer[setup] \start \getbuffer[setup,demo] \stop + +\startbuffer[setup] +\setupformula + [split=yes, + align=flushleft, + hang=auto] +\stopbuffer + +\typebuffer[setup] \start \getbuffer[setup,demo] \stop + +\startbuffer[setup] +\setupformula + [split=yes, + align=flushleft, + hang=auto, + distance=1em] +\stopbuffer + +\typebuffer[setup] \start \getbuffer[setup,demo] \stop + +\startbuffer[setup] +\setupformula + [split=yes, + align=flushleft, + hang=yes, + distance=2em] +\stopbuffer + +\typebuffer[setup] \start \getbuffer[setup,demo] \stop + +\startbuffer[setup] +\setupformula + [split=yes, + align=flushleft, + hang=yes, + distance=2em, + interlinespace=1.5\lineheight] +\stopbuffer + +\typebuffer[setup] \start \getbuffer[setup,demo] \stop + +If you want to split over pages, you can say: + +\starttyping +\setupformula + [split=page, + align=middle] +\stoptyping + +but that is rather experimental (especially in combination with other +number placement related options). + +\stopsection + +\startsection[title=Scripts] + +Superscripts and subscripts are typeset in a smaller size than their nucleus. You +can influence that as follows: + +\startbuffer +\startformula +x^{2} = x^{\textstyle 2} + = x^{\scriptstyle 2} + = x^{\scriptscriptstyle 2} +\stopformula +\stopbuffer + +\typebuffer \getbuffer + +You can also use macros instead of a \type {^} and \type {_}, as in: + +\startbuffer +\startformula +x \superscript {2} = +x \superscript {\textstyle 2} = +x \superscript {\scriptstyle 2} = +x \superscript {\scriptscriptstyle 2} = +x \nosuperscript {2} +\stopformula +\stopbuffer + +\typebuffer \getbuffer + +The \type {\nosuperscript} primitive makes sure that we get the same size as the +nucleus. + +\startbuffer +\startformula +x \superscript {2} \subscript {i} = +x \nosuperscript {2} \subscript {i} = +x \superscript {2} \nosubscript {i} = +x \nosuperscript {2} \nosubscript {i} +\stopformula +\stopbuffer + +\typebuffer \getbuffer + +\stopsection + +\startsection[title=Text accents] + +You can put an accent over a character: + +\startbuffer +$\grave{x} \neq \grave{i}$\quad +$\ddot {x} \neq \ddot {i}$\quad +$\bar {x} \neq \bar {i}$\quad +$\acute{x} \neq \acute{i}$\quad +$\hat {x} \neq \hat {i}$\quad +$\check{x} \neq \check{i}$\quad +$\breve{x} \neq \breve{i}$\quad +$\dot {x} \neq \dot {i}$\quad +$\ring {x} \neq \ring {i}$\quad +$\tilde{x} \neq \tilde{i}$\quad +$\dddot{x} \neq \dddot{i}$\quad +\stopbuffer + +\typebuffer + +This comes out as: \inlinebuffer. For regular text you can better use proper composed +\UTF\ encoded characters. + +\stopsection + +\startsection[title=Directions] + +Math has its own direction control: + +\starttexdefinition unexpanded MathTest #1#2#3 + \ruledvbox \bgroup + \mathdir#1\relax + \textdir#2\relax + \pardir #3\relax + \hsize=30mm + \startformula + a^2+b^2=c^2 + \stopformula + \egroup +\stoptexdefinition + +\starttexdefinition unexpanded MathShow #1#2#3#4 + \hbox \bgroup + \infofont #1 : m=#2 t=#3 p=#4 + \egroup +\stoptexdefinition + +\startbuffer +\startcombination[nx=4,ny=2,distance=1cm] + {\MathTest{TLT}{TLT}{TLT}} {\MathShow1{TLT}{TLT}{TLT}} + {\MathTest{TLT}{TLT}{TRT}} {\MathShow2{TLT}{TLT}{TRT}} + {\MathTest{TLT}{TRT}{TLT}} {\MathShow3{TLT}{TRT}{TLT}} + {\MathTest{TLT}{TRT}{TRT}} {\MathShow4{TLT}{TRT}{TRT}} + {\MathTest{TRT}{TLT}{TLT}} {\MathShow5{TRT}{TLT}{TLT}} + {\MathTest{TRT}{TLT}{TRT}} {\MathShow6{TRT}{TLT}{TRT}} + {\MathTest{TRT}{TRT}{TLT}} {\MathShow7{TRT}{TRT}{TLT}} + {\MathTest{TRT}{TRT}{TRT}} {\MathShow8{TRT}{TRT}{TRT}} +\stopcombination +\stopbuffer + +\typebuffer + +Normally you will not control directions this way but use the proper parameters +in layout related setup commands. + +\startlinecorrection +\getbuffer +\stoplinecorrection + +\stopsection + +\startsection[title=Surround] + +The spacing around inline formulas is consistent with other +spacing but it can be enlarged. We just show a few examples: + +\startbuffer[demo] +\hsize 20em +We have +\dorecurse {8} {% + \ifcase#1\or\else and \fi + $x+#1$ and $x-#1$ and $x \times #1$ +} +\removeunwantedspaces . +\par +\stopbuffer + +\typebuffer[demo] + +\blank \start \getbuffer[demo] \stop + +\startbuffer[setup] +\setupmathematics + [textdistance=2pt plus 1pt minus 1pt] +\stopbuffer + +\typebuffer[setup] + +\blank \start \getbuffer[setup,demo] \stop + +\startbuffer[setup] +\setupmathematics + [textdistance=4pt plus 2pt minus 2pt] +\stopbuffer + +\typebuffer[setup] + +\blank \start \getbuffer[setup,demo] \stop + +\stopsection + +\startsection[title=Choices] + +The next examples are generated using this macro: + +\startbuffer +\starttexdefinition unexpanded Test#1#2 + + \begingroup + + \showmakeup[depth] + + \def\TestA{\dontleavehmode\ruledhbox{\dorecurse{8}{before }}} + \def\TestB{\dontleavehmode\ruledhbox{\dorecurse{8}{after }}} + \def\TestC{\dorecurse{18}{x+}x} + + \setdisplaymathspacemodel[3] + \setupalign[flushleft] 1\space:\space\TestA \par + \startformula #2 \TestC \stopformula \par + \setupalign[flushleft] 2\space:\space\TestB \par + + \setdisplaymathspacemodel[4] + + \vskip#1\lineheight + + \setupalign[flushright] \TestA\space:\space2 \par + \startformula #2 \TestC \stopformula \par + \setupalign[flushright] \TestB\space:\space2 \par + + \endgroup + +\stoptexdefinition +\stopbuffer + +\typebuffer \getbuffer + +It demonstrates the often hard decisions that we have to make with regards to +spacing. On the one hand we want to be adaptive, on the other hand we want to be +consistent, for instance in the depth of lines. These examples overlay the two +variants (which is of course font and style dependent). + +\Test{-4.70}{} \blank[2*line] +\Test{-6.00}{\frac{1}{2}} \blank[2*line] +\Test{-6.55}{\frac{1}{\frac{1}{2}}} + +One side effect of these options is that at some point we need to choose a +default and then easily forget about the other variants. + +\stopsection + \stopchapter \stopcomponent diff --git a/doc/context/sources/general/manuals/math/math-suboptimal.tex b/doc/context/sources/general/manuals/math/math-suboptimal.tex new file mode 100644 index 000000000..9f4e94730 --- /dev/null +++ b/doc/context/sources/general/manuals/math/math-suboptimal.tex @@ -0,0 +1,40 @@ +\environment math-layout + +\startcomponent math-subtoptimal + +\startchapter[title=Suboptimal] + +\startsection[title=Extensibles] + +Extensibles are implemented as follows: we start with the default shape, and when +that doesn't cover the body of text, a next size is chosen. When we run out of +sizes, a glyph is made from snippets (often a start glyph, overlapping middle +pieces and an end piece. Of course a font needs to provide these variants and +snippets. + +However, the quality of the coverage can differ per font. Here we show how Latin +Modern, Pagella, Cambria, Lucida and Dejavu look like: + +\starttexdefinition ShowSample #1#2 + \start + \showglyphs + \switchtobodyfont [#1] + \dontleavehmode#2: \dorecurse{50}{$\vec{\blackrule[width=##1pt]}$\space}\unskip + \par + \stop +\stoptexdefinition + +\ShowSample{modern} {Latin Modern} \blank +\ShowSample{pagella} {Pagella} \blank +\ShowSample{cambria} {Cambria} \blank +\ShowSample{lucidaot}{Lucida} \blank +\ShowSample{dejavu} {Dejavu} + +Of course fonts can be improved (or patched) and these samples might come out +better compared to previous renderings. + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/math/math-tricks.tex b/doc/context/sources/general/manuals/math/math-tricks.tex new file mode 100644 index 000000000..7efcec50b --- /dev/null +++ b/doc/context/sources/general/manuals/math/math-tricks.tex @@ -0,0 +1,819 @@ +\environment math-layout + +\startcomponent math-tricks + +\startchapter[title=Tricks] + +\startsection[title=Introduction] + +Math support in \CONTEXT\ is wrapped around basic \TEX\ primitives and +unfortunately not all we want is easy to configure. This is not surprising +because the original ideas behind \TEX\ are that one makes a style per book and a +one macro package \quote {we-can-do-it-all} approach is not what Don Knuth had in +mind at that time. + +So, for instance support for configurable spacing per math element, coloring of +specific (sub) elements, simple switching of whatever combination of alignments +and number placement, these all take quite a bit of code and hackery. + +Even configuring something seemingly trivial as fractions or top, bottom, left, +middle and right fences take some effort. This is because the engine uses +information from fonts to combine shapes and paste the content and ornaments to +together. + +For that reason already in \MKII\ but more extensively in \MKIV\ we did a lot of +these things in wrapper macros. When the math renderer was finalized for +\OPENTYPE\ math some extra control was added that can make these things easier. +However, because we go a bit beyond what is possible using this new functionality +these new mechanisms are not yet used in \MKIV, but they might be eventually. +Here we just show some of the (newer) low level trickery. For details about what +was already possible in pure \TEX, we refer to the ultimate references: the \TeX +book (by Donald Knuth) and \TeX\ by Topic (by Victor Eijkhout). + +\stopsection + +\startsection[title=Kerning] + +Kerning in \OPENTYPE\ math is not the same as in traditional \TEX: instead of a +single value, we have staircase kerns, that is, depending on the location (left +or right) and the vertical position, at discrete distances between depth and +height. In addition there is italic correction but that is only applied in +certain cases, one of which is the script location. + +Unfortunately not all fonts follow the same route. Some fonts have a true width +and a moderate italic correction is added to it (of at all), while other fonts +lie about the width and depend on an excessive italic correction to compensate +for that. + +\definemeasure[quarter][\dimexpr(\textwidth-3em)/4\relax] + +\def\TestKern#1% + {\scale + [width=\measure{quarter}] + {\hbox to 50pt{\hss\showboxes\switchtobodyfont[#1]$V_i^i = W_i^i$\hss}}} + +\startlinecorrection +\startcombination[nx=4,ny=2,distance=1em] + {\TestKern {modern}} {\infofont modern} + {\TestKern {cambria}} {\infofont cambria} + {\TestKern{lucidaot}} {\infofont lucida} + {\TestKern {dejavu}} {\infofont dejavu} + {\TestKern {pagella}} {\infofont pagella} + {\TestKern {termes}} {\infofont termes} + {\TestKern {bonum}} {\infofont bonum} + {\TestKern {schola}} {\infofont schola} +\stopcombination +\stoplinecorrection + +I will not discuss the details because when a font gets updated, it might look +better or worse. These fonts were loaded with the following directive set: + +\starttyping +\enabledirectives[fontgoodies.mathkerning] +\stoptyping + +An example of a fontgoodie that fixed the kerning is \type {pagella-math.lfg}. Here +is the relevant bit: + +\starttyping +local kern_200 = { bottomright = { { kern = -200 } } } +local kern_100 = { bottomright = { { kern = -100 } } } + +return { + ..... + mathematics = { + ..... + kerns = { + [0x1D449] = kern_200, -- 𝑉 + [0x1D44A] = kern_100, -- 𝑊 + }, + ..... + } +} +\stoptyping + +This fixes the real bad kerning of Pagella Math which at least in 2017 was not +(yet) fixed. When the fonts are frozen we can start makling permanent runtime +fixes like this. + +\stopsection + +\startsection[title=Primes] + +Primes are a pain in the butt. The reason for this is that they are independent +characters on the one hand but can be seen as a superscript on the other. Let's +first look at the symbols at the three sizes that are used in math. + +\startbuffer[prime] +$ + {\textstyle \char"2032} + {\scriptstyle \char"2032} + {\scriptscriptstyle\char"2032} +\quad + {\textstyle \char"FE931} + {\scriptstyle \char"FE931} + {\scriptscriptstyle\char"FE931} +\quad + {\textstyle \char"FE932} + {\scriptstyle \char"FE932} + {\scriptscriptstyle\char"FE932} +$ +\stopbuffer + +\typebuffer[prime] + +We blow up the characters a bit and get this: + +\startlinecorrection +\scale[scale=5000]{\showglyphs\inlinebuffer[prime]} +\stoplinecorrection + +\def\TestPrime#1% + {\scale + [width=\measure{quarter}] + {\ruledhbox to 65pt{% + \hss + \showglyphs + \switchtobodyfont[#1]% + \inlinebuffer[prime]% + \hss}}} + +The first set is the normal prime character scaled to the text, script and +scriptscriptsize. The second set shows the characters (at three sizes) as they +are in the font. The largest character is raised while the other two are closer +to the baseline. In some fonts the smaller sizes arenot smaller at all. The last +set is a variant of the the first set but we made them into virtual characters +with a displacement and different dimensions. Those are the ones we use as +primes. + +\startlinecorrection +\startcombination[nx=4,ny=2,distance=1em] + {\TestPrime {modern}} {\infofont modern} + {\TestPrime {cambria}} {\infofont cambria} + {\TestPrime{lucidaot}} {\infofont lucida} + {\TestPrime {dejavu}} {\infofont dejavu} + {\TestPrime {pagella}} {\infofont pagella} + {\TestPrime {termes}} {\infofont termes} + {\TestPrime {bonum}} {\infofont bonum} + {\TestPrime {schola}} {\infofont schola} +\stopcombination +\stoplinecorrection + +Next we show how primes show up in real math. The examples +explain themselves. + +\startbuffer +{\textstyle f = g} \quad +{\scriptstyle f = g} \quad +{\scriptscriptstyle f = g} +\stopbuffer + +\typebuffer + +\startlinecorrection +\scale[scale=2000]{\showglyphs$\inlinebuffer$} +\stoplinecorrection + +\startbuffer +{\textstyle f_i' = g_i'} \quad +{\scriptstyle f_i' = g_i'} \quad +{\scriptscriptstyle f_i' = g_i'} +\stopbuffer + +\typebuffer + +\startlinecorrection +\scale[scale=2000]{\showglyphs$\inlinebuffer$} +\stoplinecorrection + +\startbuffer +{\textstyle f^{\char"2032}(0) = g^{\char"2032}(0)} \quad +{\scriptstyle f^{\char"2032}(0) = g^{\char"2032}(0)} \quad +{\scriptscriptstyle f^{\char"2032}(0) = g^{\char"2032}(0)} +\stopbuffer + +\typebuffer + +\startlinecorrection +\scale[scale=2000]{\showglyphs$\inlinebuffer$} +\stoplinecorrection + +\startbuffer +{\textstyle f'(0) = g'(0)} \quad +{\scriptstyle f'(0) = g'(0)} \quad +{\scriptscriptstyle f'(0) = g'(0)} +\stopbuffer + +\typebuffer + +\startlinecorrection +\scale[scale=2000]{\showglyphs$\inlinebuffer$} +\stoplinecorrection + +\startbuffer +{\textstyle f^{\char"2032}(0) = g^{\char"2032}(0)} \quad +{\scriptstyle f^{\char"2032}(0) = g^{\char"2032}(0)} \quad +{\scriptscriptstyle f^{\char"2032}(0) = g^{\char"2032}(0)} +\stopbuffer + +\typebuffer + +\startlinecorrection +\scale[scale=2000]{\showglyphs$\inlinebuffer$} +\stoplinecorrection + +\startbuffer +{\textstyle f^{\char"2032}(0) = g^{\char"2032}(0)} \quad +{\scriptstyle f^{\char"2032}(0) = g^{\char"2032}(0)} \quad +{\scriptscriptstyle f^{\char"2032}(0) = g^{\char"2032}(0)} +\stopbuffer + +\typebuffer + +\startlinecorrection +\scale[scale=2000]{\showglyphs$\inlinebuffer$} +\stoplinecorrection + +The prime analyzer can deal with sizes, subscripts but also converts a sequence +of upright quotes into one unicode symbol. So, + +\startbuffer +f'_i \neq f''_i \neq f'''_i \neq f''''_i +\stopbuffer + +\typebuffer + +becomes: + +\startlinecorrection +\scale[scale=4000]{\showglyphs$\inlinebuffer$} +\stoplinecorrection + +\stopsection + +\startsection[title=Radicals] + +Sometimes users complain about the look of a radical symbol. This is however a matter +of design. Some fonts let the shape start more below the baseline than others. Soem go +more straight up than relatives in another font. When largers sizes are needed, some +fonts offer smaller than others. Just look at the different desings: + +\def\TestRadical#1% + {\NC + \type{#1}\blackrule[width=0pt,height=2.5ex,depth=2ex]\NC + \switchtobodyfont[#1]\scale[scale=2000]{\showglyphs$\surd $}\NC + \switchtobodyfont[#1]\scale[scale=2000]{\showglyphs$\sqrt{} $}\NC + \switchtobodyfont[#1]\scale[scale=2000]{\showglyphs$\sqrt{.}$}\NC + \switchtobodyfont[#1]\scale[scale=2000]{\showglyphs$\sqrt{x}$}\NC + \switchtobodyfont[#1]\scale[scale=2000]{\showglyphs$\surd \sqrt{} \sqrt{.} \sqrt{x}$}\NC + \NR} + +\starttabulate[|l|c|c|c|c|c|] + \NC \NC \type{\surd} \NC \type{\sqrt{}} \NC \type{\sqrt{.}} \NC \type{\sqrt{x}} \NC \NR + \TestRadical{modern} + \TestRadical{cambria} + \TestRadical{lucidaot} + \TestRadical{dejavu} + \TestRadical{pagella} + \TestRadical{termes} + \TestRadical{bonum} + \TestRadical{schola} +\stoptabulate + +The automatic scaling doesn't always work out as expected but on the average is +okay. Keep in mind that often the content is not that extreme. + +\def\TestRadical#1% + {\NC + \type{#1}\NC + \switchtobodyfont[#1]\showglyphs$\sqrt{\blackrule[width=1em,height=1.0ex,color=darkgray]}$\NC + \switchtobodyfont[#1]\showglyphs$\sqrt{\blackrule[width=1em,height=1.5ex,color=darkgray]}$\NC + \switchtobodyfont[#1]\showglyphs$\sqrt{\blackrule[width=1em,height=2.0ex,color=darkgray]}$\NC + \switchtobodyfont[#1]\showglyphs$\sqrt{\blackrule[width=1em,height=2.5ex,color=darkgray]}$\NC + \switchtobodyfont[#1]\showglyphs$\sqrt{\blackrule[width=1em,height=3.0ex,color=darkgray]}$\NC + \switchtobodyfont[#1]\showglyphs$\sqrt{\blackrule[width=1em,height=3.5ex,color=darkgray]}$\NC + \switchtobodyfont[#1]\showglyphs$\sqrt{\blackrule[width=1em,height=4.0ex,color=darkgray]}$\NC + \switchtobodyfont[#1]\showglyphs$\sqrt{\blackrule[width=1em,height=4.5ex,color=darkgray]}$\NC + \NR} + +\starttabulate[|l|c|c|c|c|c|c|c|c|] + \NC \NC 1.0ex \NC 1.5ex \NC 2.0ex \NC 2.5ex \NC 3.0ex \NC 3.5ex \NC 4.0ex \NC 4.5ex \NC \NR + \TestRadical{modern} + \TestRadical{cambria} + \TestRadical{lucidaot} + \TestRadical{dejavu} + \TestRadical{pagella} + \TestRadical{termes} + \TestRadical{bonum} + \TestRadical{schola} +\stoptabulate + +In Lucida (the version at the time of writing this) we have to correct the threshold +a bit in the goodie file: + +\starttyping +local function FixRadicalDisplayStyleVerticalGap(value,target,original) + local o = original.mathparameters.RadicalVerticalGap -- 50 + return 2 * o * target.parameters.factor +end + +return { + ..... + mathematics = { + ..... + parameters = { + RadicalDisplayStyleVerticalGap = + FixRadicalDisplayStyleVerticalGap, + }, + ..... + }, +} +\stoptyping + +\stopsection + +\startsection[title=Integrals] + +A curious exception in the math system is the integral sign. Its companions are +the summation and product signs, but integral has as extra property that it has a +slant. In \LUATEX\ there is rather advanced control over how the (optional) +scripts are positioned (which relates to italic correction) but in \CONTEXT\ we +only make limited use of that. The main reason is that we also need to support +additional features like color. Therefore integrals are handled by the extensible +mechanism. + +The size of an integral is more of less fixed but you can enlarge to your +liking. One reason for this is that you might want a consistent size across +formulas. Let's use the following setup: + +\startbuffer[setup] +\setupmathextensible + [integral] + [rightoffset=-1mu, + exact=yes, + factor=2] + +\let\int\integral +\stopbuffer + +\typebuffer[setup] + +We use the following exmaple: + +\startbuffer[demo] +\ruledhbox{$\integral f\frac{1}{2} $}\quad +\ruledhbox{$\integral[rightoffset=3mu] f\frac{1}{2} $}\quad +\ruledhbox{$\integral[exact=no] f\frac{1}{2} $}\quad +\ruledhbox{$\integral f\frac{\frac{1}{2}}{x} $}\quad +\ruledhbox{$\integral[exact=no] f\frac{\frac{1}{2}}{x} $}\quad +\ruledhbox{$\integral[factor=1] f\frac{1}{2} $}\quad +\ruledhbox{$\integral[factor=3] f\frac{\frac{1}{2}}{x} $}\quad +\ruledhbox{$\integral[factor=3] f\frac{1}{2} $}\quad +\ruledhbox{$\int f\frac{1}{2} $}% bonus +\stopbuffer + +\typebuffer[demo] + +This renders as: + +\dontleavehmode\hbox{\getbuffer[setup,demo]} + +\stopsection + +\startsection[title=Fancy fences] + +Here I only show an example of fences drawn by \METAPOST. For the implementation +you can consult the library file \type {meta-imp-mat.mkiv} in the \CONTEXT\ +distribution. + +\startbuffer[setup] +\useMPlibrary[mat] + +\setupmathstackers + [both] % vfenced] + [color=darkred, + alternative=mp] + +\setupmathstackers + [top] + [color=darkred, + alternative=mp] + +\setupmathstackers + [bottom] + [color=darkred, + alternative=mp] +\stopbuffer + +\typebuffer[setup] + +We keep the demo simple: + +\startbuffer[demo] +$ \overbracket {a+b+c+d} \quad + \underbracket {a+b+c+d} \quad + \doublebracket {a+b+c+d} \quad + \overparent {a+b+c+d} \quad + \underparent {a+b+c+d} \quad + \doubleparent {a+b+c+d} $ \blank +$ \overbrace {a+b+c+d} \quad + \underbrace {a+b+c+d} \quad + \doublebrace {a+b+c+d} \quad + \overbar {a+b+c+d} \quad + \underbar {a+b+c+d} \quad + \doublebar {a+b+c+d} $ \blank +$ \overleftarrow {a+b+c+d} \quad + \overrightarrow {a+b+c+d} \quad + \underleftarrow {a+b+c+d} \quad + \underrightarrow {a+b+c+d} $ \blank +\stopbuffer + +\typebuffer[demo] + +Or visualized: + +\start +\getbuffer[setup,demo] +\stop + +\stopsection + +\startsection[title=Combined characters] + +We have some magic built with respect to sequences of characters. They are derived +from information in the character database that ships with \CONTEXT\ and are +implemented as a sort of ligatures. Some are defined in \UNICODE, others are +defined explicitly. + +\usemodule[math-ligatures] + +\start + \switchtobodyfont[small] + \showmathligatures +\stop + +\stopsection + +\startsection[title=Middle class fences] + +The next examples are somewhat obscure. They are a side effect of some extensions +to the engine that were introduced to control spacing around the \type {\middle} +class fences. Actually there is no real middle class and spacing was somewhat +hard codes when \type {\middle} was added to \ETEX. In \LUATEX\ we have +introduced keywords to some primitives that control spacing and other properties. +This permits better control over spacing than messing around with (for instance) +injected \type {\mathrel} commands that can have their own side effects. + +\startbuffer +\def\Middle{\middle|} +\def\Riddle{\Umiddle class 5 |} +\def\Left {\left (} +\def\Right {\right )} +\def\Rel {\mathrel{}} +\def\Per {\mathrel{.}} +\stopbuffer + +\startbuffer[1a] +$ a b $ +\stopbuffer +\startbuffer[1b] +$ \Rel a\Rel b\Rel $ +\stopbuffer + +\startbuffer[2a] +$ a b $ +\stopbuffer +\startbuffer[2b] +$ \Per a\Per b\Per $ +\stopbuffer + +\startbuffer[3a] +$\Left a \Middle b \Right$ +\stopbuffer +\startbuffer[3b] +$\Left\Rel a \Middle\Rel b\Rel\Right$ +\stopbuffer + +\startbuffer[4a] +$\Left a \Middle b \Right$ +\stopbuffer +\startbuffer[4b] +$\Left\Rel a \Middle\Per b\Per\Right$ +\stopbuffer + +\startbuffer[5a] +$\Left a \Middle b \Right$ +\stopbuffer +\startbuffer[5b] +$\Left\Rel a\Rel\Middle\Rel b\Rel\Right$ +\stopbuffer + +\startbuffer[6a] +$\Left a \Middle b \Right$ +\stopbuffer +\startbuffer[6b] +$\Left\Per a\Per\Middle\Per b\Per\Right$ +\stopbuffer + +\startbuffer[7a] +$\Left a \Riddle b \Right$ +\stopbuffer +\startbuffer[7b] +$\Left\Rel a \Riddle\Rel b\Rel\Right$ +\stopbuffer + +\startbuffer[8a] +$\Left a \Riddle b \Right$ +\stopbuffer +\startbuffer[8b] +$\Left\Rel a \Riddle\Per b\Per\Right$ +\stopbuffer + +\startbuffer[9a] +$\Left a \Riddle b \Right$ +\stopbuffer +\startbuffer[9b] +$\Left\Rel a\Rel\Riddle\Rel b\Rel\Right$ +\stopbuffer + +\startbuffer[10a] +$\Left a \Riddle b \Right$ +\stopbuffer +\startbuffer[10b] +$\Left\Per a\Per\Riddle\Per b\Per\Right$ +\stopbuffer + +We use the following definitions: + +\typebuffer + +Applied to samples these give the following outcome and spacing: + +\start + \getbuffer + + \starttabulate + \NC \ruledhbox{\typeinlinebuffer[1a]} \NC \showglyphs \inlinebuffer[1a] \NC \NR + \NC \ruledhbox{\typeinlinebuffer[1b]} \NC \showglyphs \inlinebuffer[1b] \NC \NR + \NC \ruledhbox{\typeinlinebuffer[2a]} \NC \showglyphs \inlinebuffer[2a] \NC \NR + \NC \ruledhbox{\typeinlinebuffer[2b]} \NC \showglyphs \inlinebuffer[2b] \NC \NR + \NC \ruledhbox{\typeinlinebuffer[3a]} \NC \showglyphs \inlinebuffer[3a] \NC \NR + \NC \ruledhbox{\typeinlinebuffer[3b]} \NC \showglyphs \inlinebuffer[3b] \NC \NR + \NC \ruledhbox{\typeinlinebuffer[4a]} \NC \showglyphs \inlinebuffer[4a] \NC \NR + \NC \ruledhbox{\typeinlinebuffer[4b]} \NC \showglyphs \inlinebuffer[4b] \NC \NR + \NC \ruledhbox{\typeinlinebuffer[5a]} \NC \showglyphs \inlinebuffer[5a] \NC \NR + \NC \ruledhbox{\typeinlinebuffer[5b]} \NC \showglyphs \inlinebuffer[5b] \NC \NR + \NC \ruledhbox{\typeinlinebuffer[6a]} \NC \showglyphs \inlinebuffer[6a] \NC \NR + \NC \ruledhbox{\typeinlinebuffer[6b]} \NC \showglyphs \inlinebuffer[6b] \NC \NR + \NC \ruledhbox{\typeinlinebuffer[7a]} \NC \showglyphs \inlinebuffer[7a] \NC \NR + \NC \ruledhbox{\typeinlinebuffer[7b]} \NC \showglyphs \inlinebuffer[7b] \NC \NR + \NC \ruledhbox{\typeinlinebuffer[8a]} \NC \showglyphs \inlinebuffer[8a] \NC \NR + \NC \ruledhbox{\typeinlinebuffer[8b]} \NC \showglyphs \inlinebuffer[8b] \NC \NR + \NC \ruledhbox{\typeinlinebuffer[9a]} \NC \showglyphs \inlinebuffer[9a] \NC \NR + \NC \ruledhbox{\typeinlinebuffer[9b]} \NC \showglyphs \inlinebuffer[9b] \NC \NR + \NC \ruledhbox{\typeinlinebuffer[10a]} \NC \showglyphs \inlinebuffer[10a] \NC \NR + \NC \ruledhbox{\typeinlinebuffer[10b]} \NC \showglyphs \inlinebuffer[10b] \NC \NR + \stoptabulate +\stop + +\stopsection + +\startsection[title=Auto|-|punctuation] + +\def\TestA#1#2#3% + {\ifnum#1=0 \type{#2}\else\setupmathematics[autopunctuation={#2}]$#3$\fi} + +\def\TestB#1#2% + {\NC \TestA{#1}{no} {#2} + \NC \TestA{#1}{yes} {#2} + \NC \TestA{#1}{yes,semicolon}{#2} + \NC \TestA{#1}{all} {#2} + \NC \TestA{#1}{all,semicolon}{#2} + \NC \NR} + +The \type {\setupmathematics} command has an option \type {autopunctuation} that +influences the way spacing after punctuatuon is handled, especially in cases like +the following (coordinates and such): + +\starttabulate[|c|c|c|c|c|] + \TestB{0}{} + \TestB{1}{(1,2)=(1, 2)} + \TestB{1}{(1.2)=(1. 2)} + \TestB{1}{(1;2)=(1; 2)} +\stoptabulate + +\stopsection + +\stopcomponent + +% \enabletrackers[math.makeup=boxes] + +% \startTEXpage[offset=10pt] +% $\displaystyle {{1}\normalover{2}}+x$\quad $\crampeddisplaystyle {{1}\normalover{2}}+x$\blank +% $\textstyle {{1}\normalover{2}}+x$\quad $\crampedtextstyle {{1}\normalover{2}}+x$\blank +% $\scriptstyle {{1}\normalover{2}}+x$\quad $\crampedscriptstyle {{1}\normalover{2}}+x$\blank +% $\scriptscriptstyle {{1}\normalover{2}}+x$\quad $\crampedscriptscriptstyle{{1}\normalover{2}}+x$\blank +% \stopTEXpage + +% \startTEXpage[offset=10pt] +% $e=mc^2$ +% \stopTEXpage + +% \startTEXpage[offset=10pt] +% $\sqrt{\frac{1}{2}+x}$ +% \stopTEXpage + +% \startTEXpage[offset=10pt] +% $\int^0_1{\frac{1}{2}+x}$ +% \stopTEXpage + +% \startTEXpage[offset=10pt] +% $\displaystyle\the\everydisplay\int^0_1{\frac{1}{2}+x}$ +% \stopTEXpage + +% \startbuffer +% ${}^2_2x^3_4 {}^2x_4$ +% \stopbuffer + +% % d : \Umathsubshiftdown +% % u : \Umathsupshiftup +% % s : \Umathsubsupshiftdown + +% \startTEXpage[offset=10pt] +% \starttabulate[|T||cT|cT|] +% \NC 0 \NC \mathscriptsmode 0 \inlinebuffer \NC dynamic \NC dynamic \NC \NR \TB +% \NC 1 \NC \mathscriptsmode 1 \inlinebuffer \NC d \NC u \NC \NR \TB +% \NC 2 \NC \mathscriptsmode 2 \inlinebuffer \NC s \NC u \NC \NR \TB +% \NC 3 \NC \mathscriptsmode 3 \inlinebuffer \NC s \NC u + s − d \NC \NR \TB +% \NC 4 \NC \mathscriptsmode 4 \inlinebuffer \NC d + (s − d)/2 \NC u + (s − d)/2 \NC \NR \TB +% \NC 5 \NC \mathscriptsmode 5 \inlinebuffer \NC d \NC u + s − d \NC \NR +% \stoptabulate +% \stopTEXpage + +% \startTEXpage[offset=10pt] \tt +% \starttabulate[|l|ck1|ck1|ck1|ck1|ck1|ck1|] +% \NC +% \NC \mathnolimitsmode0 $\displaystyle\int\nolimits^0_1$ +% \NC \mathnolimitsmode1 $\displaystyle\int\nolimits^0_1$ +% \NC \mathnolimitsmode2 $\displaystyle\int\nolimits^0_1$ +% \NC \mathnolimitsmode3 $\displaystyle\int\nolimits^0_1$ +% \NC \mathnolimitsmode4 $\displaystyle\int\nolimits^0_1$ +% \NC \mathnolimitsmode8000 $\displaystyle\int\nolimits^0_1$ +% \NC \NR +% \TB +% \NC \bf mode +% \NC 0 +% \NC 1 +% \NC 2 +% \NC 3 +% \NC 4 +% \NC 8000 +% \NC \NR +% \NC \bf superscript +% \NC 0 +% \NC font +% \NC 0 +% \NC 0 +% \NC +ic/2 +% \NC 0 +% \NC \NR +% \NC \bf subscript +% \NC -ic +% \NC font +% \NC 0 +% \NC -ic/2 +% \NC -ic/2 +% \NC 8000ic/1000 +% \NC \NR +% \stoptabulate +% \stopTEXpage + +{ } \bgroup \egroup \begingroup \endgroup + +\startbuffer[1] + [a:\mathstyle]\quad + \bgroup + \mathchoice + {\bf \scriptstyle (x:d :\mathstyle)} + {\bf \scriptscriptstyle (x:t :\mathstyle)} + {\bf \scriptscriptstyle (x:s :\mathstyle)} + {\bf \scriptscriptstyle (x:ss:\mathstyle)} + \egroup + \quad[b:\mathstyle]\quad + \mathchoice + {\bf \scriptstyle (y:d :\mathstyle)} + {\bf \scriptscriptstyle (y:t :\mathstyle)} + {\bf \scriptscriptstyle (y:s :\mathstyle)} + {\bf \scriptscriptstyle (y:ss:\mathstyle)} + \quad[c:\mathstyle]\quad + \bgroup + \mathchoice + {\bf \scriptstyle (z:d :\mathstyle)} + {\bf \scriptscriptstyle (z:t :\mathstyle)} + {\bf \scriptscriptstyle (z:s :\mathstyle)} + {\bf \scriptscriptstyle (z:ss:\mathstyle)} + \egroup + \quad[d:\mathstyle] +\stopbuffer + +\startbuffer[2] + [a:\mathstyle]\quad + \begingroup + \mathchoice + {\bf \scriptstyle (x:d :\mathstyle)} + {\bf \scriptscriptstyle (x:t :\mathstyle)} + {\bf \scriptscriptstyle (x:s :\mathstyle)} + {\bf \scriptscriptstyle (x:ss:\mathstyle)} + \endgroup + \quad[b:\mathstyle]\quad + \mathchoice + {\bf \scriptstyle (y:d :\mathstyle)} + {\bf \scriptscriptstyle (y:t :\mathstyle)} + {\bf \scriptscriptstyle (y:s :\mathstyle)} + {\bf \scriptscriptstyle (y:ss:\mathstyle)} + \quad[c:\mathstyle]\quad + \begingroup + \mathchoice + {\bf \scriptstyle (z:d :\mathstyle)} + {\bf \scriptscriptstyle (z:t :\mathstyle)} + {\bf \scriptscriptstyle (z:s :\mathstyle)} + {\bf \scriptscriptstyle (z:ss:\mathstyle)} + \endgroup + \quad[d:\mathstyle] +\stopbuffer + +% % \bgroup .. \egroup + +% \startTEXpage[offset=10pt] +% $\displaystyle \getbuffer[1]$ \blank +% $\textstyle \getbuffer[1]$ +% \stopTEXpage + +% % \begingroup .. \endgroup + +% \startTEXpage[offset=10pt] +% $\displaystyle \getbuffer[2]$ \blank +% $\textstyle \getbuffer[2]$ +% \stopTEXpage + + +% \startTEXpage[offset=10pt] +% $\Uleft ( x \Umiddle\| \Uright )$ +% $\Uleft height 3ex ( x \Umiddle\| \Uright height 3ex )$ +% $\Uleft axis height 3ex ( x \Umiddle\| \Uright axis height 3ex )$ +% $\Uleft axis height 3ex depth 1ex ( x \Umiddle\| \Uright axis height 3ex depth 1ex )$ +% \stopTEXpage + +% \startTEXpage[offset=10pt] +% $\Uvextensible ( \frac{1}{x}$ +% $\Uvextensible height 3ex ( \frac{1}{x}$ +% $\Uvextensible axis height 3ex ( \frac{1}{x}$ +% $\Uvextensible axis height 3ex depth 1ex ( \frac{1}{x}$ +% $\Uvextensible exact axis height 3ex depth 1ex ( \frac{1}{x}$ +% \stopTEXpage + +% \startTEXpage[offset=10pt] +% \ruledhbox{$\Uhextensible "0 "23DE$} +% \ruledhbox{$\Uhextensible width 3ex "0 "23DE$} +% \ruledhbox{$\Uhextensible middle width 3ex "0 "23DE$} +% \ruledhbox{$\Uhextensible left width 3ex "0 "23DE$} +% \ruledhbox{$\Uhextensible right width 3ex "0 "23DE$} +% \stopTEXpage + +% \startTEXpage[offset=10pt] +% \ruledhbox{$\Umathaccent "0 "0 "23DE {1+x}$} +% \ruledhbox{$\Umathaccent fixed "0 "0 "23DE {1+x}$} +% \ruledhbox{$\Umathaccent top "0 "0 "23DE {1+x}$} +% \ruledhbox{$\Umathaccent bottom "0 "0 "23DF {1+x}$} +% \ruledhbox{$\Umathaccent both "0 "0 "23DE "0 "0 "23DF {1+x}$} +% \ruledhbox{$\Umathaccent overlay "0 "0 "23DE {1+x}$} +% \ruledhbox{$\Umathaccent top "0 "0 "23DE fraction 800 {1+x}$} +% \stopTEXpage + +% \startTEXpage[offset=10pt] +% ${ {1} \Uskewed / {2} }$ +% ${ {1} \Uskewed / exact {2} }$ +% ${ {1} \Uskewed / noaxis {2} }$ +% ${ {1} \Uskewed / exact noaxis {2} }$ +% ${ {1} \Uskewedwithdelims / () {2} }$ +% ${ {1} \Uskewedwithdelims / () exact {2} }$ +% ${ {1} \Uskewedwithdelims / () noaxis {2} }$ +% ${ {1} \Uskewedwithdelims / () exact noaxis {2} }$ +% \stopTEXpage + +% \disabletrackers[math.makeup] + +% \stopchapter +% +% \stopcomponent + +% A \type {\matheqnogapstep} factor that determines the gap between formula and +% equation number. +% +% A \type {\mathdisplayskipmode} directive that controls display skips: 1 = always, +% 2 = only when not zero, 3 = never. +% +% \mathstyle +% +% \suppressmathparerror + diff --git a/doc/context/sources/general/manuals/metafun/cow-fun.mps b/doc/context/sources/general/manuals/metafun/cow-fun.mps new file mode 100644 index 000000000..4235985ba --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/cow-fun.mps @@ -0,0 +1,154 @@ +%!PS-Adobe-2.0 EPSF-2.0 +%%BoundingBox: 52 425 327 625 +%%Comment: originally a CorelDraw cow +%%Creator: MetaPost +%%Pages: 1 +%%EndProlog +%%Page: 1 1 +0 2 dtransform truncate idtransform setlinewidth pop +.625 0 0 setrgbcolor +newpath 245.45 600.34 moveto +242.78 599.40 239.62 596.02 237.67 594.07 curveto +236.74 584.42 244.58 583.63 250.20 577.44 curveto +258.77 573.70 251.21 567.72 256.18 557.42 curveto +257.04 550.94 257.90 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.70 217.80 543.17 curveto +213.77 538.06 215.78 531.22 217.80 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.50 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.60 543.53 162.14 555.91 curveto +159.41 561.24 156.74 559.08 156.89 553.90 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.00 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.70 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.90 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.82 565.13 curveto +92.02 565.63 84.24 566.71 79.34 568.15 curveto +73.51 560.88 58.32 565.63 56.23 570.31 curveto +54.79 572.69 54.65 575.21 54.79 576.50 curveto +52.34 580.10 55.87 582.70 59.62 583.06 curveto +62.86 587.16 68.54 594.94 71.28 601.56 curveto +72.29 603.07 74.95 609.34 78.19 609.55 curveto +74.95 612.94 74.30 622.51 82.66 617.33 curveto +87.12 624.02 92.09 624.31 95.76 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.80 curveto +140.76 564.70 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.50 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.40 550.44 303.98 536.47 304.20 525.31 curveto +303.70 521.35 299.81 517.46 299.38 525.67 curveto +295.85 530.86 296.42 540.07 293.40 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.50 524.02 264.31 526.68 266.69 534.46 curveto +270.29 543.02 268.34 554.76 266.54 561.60 curveto +262.37 578.59 264.02 587.09 271.58 596.09 curveto +267.48 604.51 lineto +275.40 608.26 285.62 604.58 290.02 602.21 curveto +294.62 600.26 300.24 595.94 301.10 587.38 curveto +303.34 578.88 304.42 569.74 305.28 560.95 curveto +closepath fill +.625 .625 0 setrgbcolor +newpath 84.38 618.55 moveto +88.34 624.38 92.59 622.94 96.34 615.67 curveto +101.23 615.60 102.46 612.43 104.98 610.78 curveto +122.62 598.39 147.46 607.18 167.90 601.92 curveto +180.94 598.54 190.87 599.76 200.09 602.06 curveto +220.32 607.25 246.10 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.10 312.48 522.07 curveto +315.79 511.34 316.08 510.12 317.16 502.20 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.30 320.90 473.90 322.56 471.74 curveto +320.83 470.81 318.46 473.47 317.52 475.20 curveto +318.17 473.04 317.81 470.81 316.73 469.30 curveto +315.86 472.25 316.58 473.18 315.36 473.90 curveto +313.99 472.90 314.21 469.30 314.28 466.20 curveto +313.49 468.07 311.47 472.46 312.55 476.42 curveto +312.48 484.20 308.81 489.10 310.32 499.10 curveto +310.10 504.43 307.30 521.06 304.56 524.30 curveto +303.12 526.25 306.36 510.77 306.36 506.16 curveto +306.65 500.90 307.08 468.72 306.43 463.10 curveto +306.43 459.22 306.22 453.96 307.08 452.16 curveto +308.74 450.79 309.38 450.50 309.60 447.98 curveto +309.24 446.62 308.74 446.04 307.73 445.54 curveto +306.07 444.60 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.00 303.05 437.98 302.47 436.18 curveto +299.66 433.80 292.18 432.50 289.15 434.66 curveto +289.73 440.64 291.74 441.58 295.63 446.62 curveto +298.66 452.59 297.00 460.94 296.93 468.14 curveto +295.49 480.38 289.22 487.30 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.00 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.10 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.30 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.70 487.66 257.33 485.50 253.22 486.29 curveto +252.58 484.34 253.30 482.33 252.22 480.10 curveto +251.86 479.52 249.34 478.58 249.19 481.39 curveto +248.98 483.05 248.90 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.20 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.40 169.85 454.46 168.48 454.46 curveto +168.48 453.10 169.34 450.86 168.62 449.42 curveto +167.18 447.62 165.89 451.80 165.02 444.60 curveto +163.15 443.74 157.75 442.22 155.59 445.18 curveto +155.88 448.99 158.33 451.30 160.13 453.38 curveto +161.42 456.91 160.99 458.28 160.70 461.81 curveto +160.99 464.98 161.71 468.58 161.86 470.09 curveto +161.86 473.04 162.50 479.30 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.50 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.70 149.76 444.74 curveto +150.05 442.80 147.89 443.59 146.09 444.60 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.60 137.88 448.06 140.62 451.01 curveto +143.14 455.83 140.90 465.70 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.38 567.65 79.06 567.65 curveto +73.44 563.04 66.24 563.62 58.54 567.65 curveto +55.66 569.23 54.43 573.19 54.50 576.50 curveto +52.63 580.75 55.22 582.19 59.62 583.49 curveto +62.71 587.81 68.62 594.65 69.19 597.74 curveto +70.34 601.92 75.53 608.11 77.76 609.77 curveto +75.82 613.01 74.81 615.17 77.11 618.55 curveto +79.56 620.14 81.79 616.61 84.38 618.55 curveto +closepath stroke +showpage +%%EOF diff --git a/doc/context/sources/general/manuals/metafun/hacker.png b/doc/context/sources/general/manuals/metafun/hacker.png Binary files differnew file mode 100644 index 000000000..3a54696ee --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/hacker.png diff --git a/doc/context/sources/general/manuals/metafun/m-1.png b/doc/context/sources/general/manuals/metafun/m-1.png Binary files differnew file mode 100644 index 000000000..ab020de9f --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/m-1.png diff --git a/doc/context/sources/general/manuals/metafun/m-2.png b/doc/context/sources/general/manuals/metafun/m-2.png Binary files differnew file mode 100644 index 000000000..512d3eda0 --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/m-2.png diff --git a/doc/context/sources/general/manuals/metafun/metafun-backgrounds.tex b/doc/context/sources/general/manuals/metafun/metafun-backgrounds.tex new file mode 100644 index 000000000..200620cae --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/metafun-backgrounds.tex @@ -0,0 +1,878 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\startcomponent metafun-backgrounds + +\environment metafun-environment + +\startchapter[reference=sec:page,title={Page backgrounds}] + +\startintro + +Especially in interactive documents, adding backgrounds to the page and text +areas not only enhances readability, but also makes it more convenient to +identify header, footers and navigational areas. In this chapter we will +demonstrate that with \METAPOST\ we can go beyond the \TEX\ based features +present in \CONTEXT. One section is dedicated to graphics and printing, +especially bleeding. + +\stopintro + +\startsection[title={The basic layout}] + +\index {layout} + +In the \CONTEXT\ manual you can find many details on the composition of the page. +When \TEX\ typesets text, crossing the page boundary triggers \TEX's output +routine. This routine is responsible for pasting the body text that goes onto a +page in the correct area. A simple representation of such a page is: + +\startbuffer[a] +\startuseMPgraphic{layout 1} + pickup pencircle scaled 1mm ; + fill unitsquare xyscaled (7cm,8cm) + withcolor .85white ; + fill unitsquare xyscaled (5cm,5cm) shifted (1cm,1.5cm) + withcolor .625yellow ; + fill unitsquare xyscaled (5cm,1cm) shifted (1cm,.5cm) + withcolor .625red ; + fill unitsquare xyscaled (5cm,1cm) shifted (1cm,6.5cm) + withcolor .625red ; + draw unitsquare xyscaled (5cm,7cm) shifted (1cm,.5cm) + withcolor .25white ; + drawarrow (2cm,8cm) -- top (2cm,7.5cm) ; + drawarrow (0cm,7cm) -- lft (1cm,7cm) ; + clip currentpicture to unitsquare xyscaled (7cm,8cm) ; +\stopuseMPgraphic +\stopbuffer + +\startbuffer[b] +\startuseMPgraphic{layout 2} + \includeMPgraphic{layout 1} + clip currentpicture to unitsquare scaled 3cm shifted (0,5cm) ; + currentpicture := currentpicture scaled 2 shifted (0,-8cm) ; + setbounds currentpicture to unitsquare xyscaled (6cm,8cm) ; +\stopuseMPgraphic +\stopbuffer + +\getbuffer[a,b] + +\startbuffer[c] +\startlinecorrection[blank] +\hbox + {\useMPgraphic{layout 1}\hskip1cm + \useMPgraphic{layout 2}} +\stoplinecorrection +\stopbuffer + +\getbuffer[c] + +The red areas are the header and footer, while the yellow areas contains the text +flow. We can turn headers on and off and|/|or hide them. For this reason, the +header, text and footer areas together make up the height of the text. + +A close look at the left picture will reveal that the two arrows point to the +center of the lines. This is achieved by the \type {top} and \type {lft} +directives. If we would not have clipped the picture, the arrow would have stuck +half a line width outside the gray area that represents the page. When +constructing such pictures, one should really pay attention to such details, +since it pays off in the overall look and feel of the document. + +The vertical arrow represents the top space, while the horizontal arrow denotes +the distance to the back of the cover (back space). By changing their values, you +can shift the main body text on the page. In a double sided layout scheme, the +back space is automatically mirrored on even pages. + +An advanced \METAPOST\ user may wonder why we hard code the dimensions, and avoid +\METAPOST's powerful mechanisms for defining relations. Our experience has taught +us that in pictures like this, providing a general solution seldom pays large +dividents or savings in time. + +\typebuffer[a] + +As you can see, the left graphic is defined as a series of rectangles. The \type +{xyscaled} macro is part of the \CONTEXT\ files, and saves some typing and space. +It is defined as a primary, requiring both left and right operands. + +\starttyping +primarydef p xyscaled q = + p xscaled (xpart q) yscaled (ypart q) +enddef ; +\stoptyping + +Zooming in on the top left corner only takes a few lines. First we clip the +correct part, next we scale it up, and finally we let the bounding box suit the +left picture. + +\typebuffer[b] + +This code demonstrates how you can reuse a graphic inside another one. This +strategy can easily be used to stepwise build (or extend) graphics. The two +graphics were put side by side with the following command. Watch the use of line +correction commands. They optimize the white space around the graphic. + +\typebuffer[c] + +As soon as you want to make an electronic document, you will want to use +different areas of the screen for different purposes: text, menus, buttons, etc. +For this reason, \CONTEXT\ provides not only left and right margins, but also +additional left and right edge areas and top and bottom margins. These areas are +shown in the figure on the next page. + +\startbuffer[aa] +pickup pencircle scaled 2pt ; + +numeric w[], h[], x[], y[], u ; u := .5cm ; + +numeric width ; width := \the\textwidth ; +numeric height ; height := \the\textheight ; +\stopbuffer + +\startbuffer[bb] +w[1] = 2u ; w[2] = 3u ; w[4] = 3u ; w[5] = 2u ; +h[1] = 1u ; h[2] = 1u ; h[4] = 1u ; h[5] = 1u ; + +w[1]+w[2]+w[3]+w[4]+w[5]+4u = width ; +h[1]+h[2]+h[3]+h[4]+h[5]+4u = height ; + +x[1] = 1u ; y[1] = 1u ; +x[2] = x[1] + w[1] + .5u ; y[2] = y[1] + h[1] + .5u ; +x[3] = x[2] + w[2] + .5u ; y[3] = y[2] + h[2] + .5u ; +x[4] = x[3] + w[3] + .5u ; y[4] = y[3] + h[3] + .5u ; +x[5] = x[4] + w[4] + .5u ; y[5] = y[4] + h[4] + .5u ; +\stopbuffer + +\startbuffer[cc] +def do_it (expr xx, yy, cc) = + draw unitsquare + xyscaled (w[xx],h[yy]) shifted (x[xx],y[yy]) + withcolor if cc : .625red else : .625yellow fi ; +enddef ; + +fill unitsquare xyscaled (width,height) withcolor .85white; + +do_it (1,1,false) ; do_it (5,1,false) ; +do_it (2,1,false) ; do_it (3,1,false) ; do_it (4,1,false) ; + +do_it (1,2,false) ; do_it (5,2,false) ; +do_it (2,2,true ) ; do_it (3,2,true ) ; do_it (4,2,true ) ; + +do_it (1,3,false) ; do_it (5,3,false) ; +do_it (2,3,true ) ; do_it (3,3,true ) ; do_it (4,3,true ) ; + +do_it (1,4,false) ; do_it (5,4,false) ; +do_it (2,4,true ) ; do_it (3,4,true ) ; do_it (4,4,true ) ; + +do_it (1,5,false) ; do_it (5,5,false) ; +do_it (2,5,false) ; do_it (3,5,false) ; do_it (4,5,false) ; +\stopbuffer + +\startbuffer[dd] +def do_it (expr yy, tt) = + path p ; + p := unitsquare xyscaled (w[1],h[yy]) shifted (x[1],y[yy]) ; + label.lft(tt, center p shifted (-w[1]/2-u-.25cm,0)) ; +enddef ; + +do_it (1,btex bottom etex) ; +do_it (2,btex footer etex) ; +do_it (3,btex text etex) ; +do_it (4,btex header etex) ; +do_it (5,btex top etex) ; +\stopbuffer + +\startbuffer[ee] +def do_it (expr xx, tt) = + path p ; + p := unitsquare xyscaled (w[xx],h[1]) shifted (x[xx],y[1]) ; + label(tt, center p shifted (0,height-h[1]/2)) ; +enddef ; + +do_it (1,btex edge etex) ; +do_it (2,btex margin etex) ; +do_it (3,btex text etex) ; +do_it (4,btex margin etex) ; +do_it (5,btex edge etex) ; +\stopbuffer + +\startbuffer[ff] +setbounds currentpicture to + unitsquare xyscaled (width,height) ; +\stopbuffer + +% We use two chars for buffer names, otherwise we can get +% get in conflict with the next buffers with similar names. + +\startpostponing +\centerbox{\processMPbuffer[aa,bb,cc,dd,ee,ff]} +\stoppostponing + +When defining this graphic, all areas have related dimensions. Here it makes +sense to let \METAPOST\ calculate these dimensions as much as possible. First we +define the five by five matrix of areas. We pass the width and height of the main +text area. Because they are stored in \TEX\ dimension registers, we have to +prefix them by \type {\the}. + +\typebuffer[aa] + +We now specify the lower left corners using \type {=} instead of the \type {:=}, +which means that \METAPOST\ will calculate \type {w[3]} and \type {h[3]} for us. + +\typebuffer[bb] + +Because we are going to repeat ourselves, we draw the areas using a macro. +Depending on its importance, we color it red or yellow. + +\typebuffer[cc] + +This picture in itself is not yet explanatory, so we add some labels. Again, we +use a macro, which we feed with a picture generated by \TEX. Since these pictures +are filtered from the source and pre||processed, we cannot embed the \type +{btex}||\type {etex} in the macro \type {do_it} and pass a string. It has to be +done this way. \footnote {This is true only in a regular \METAPOST\ run. In +\CONTEXT\ \MKIV\ we follow a different route.} + +\typebuffer[dd] + +In the horizontal direction we have edges, margins and text. There are left and +right edges and margins, which are swapped on even pages when you typeset a +double sided document. + +\typebuffer[ee] + +Since we want the graphic to match the dimensions of the text area of the current +page, we have to make sure that the bounding box is adapted accordingly. By this +action, the labels will fall outside the bounding box. When we directly embed a +graphic, this works ok, but when we start scaling and reusing, due to the object +reuse mechanism the graphic will be clipped to the bounding box. + +\typebuffer[ff] + +In the following sections we will demonstrate how you can put graphics behind +these 25~areas, as well as behind the (left and right) page. + +\stopsection + +\startsection[title={Setting up backgrounds}] + +\index {overlays} +\index {backgrounds} + +One way of protecting a document for unwanted usage is to put an annoying word in +the background. If you like this, you may try the following. The macro \type +{ysized} is part of the macros that come with \CONTEXT\ and scales a picture to a +specific size. + +\startbuffer[a] +\startuniqueMPgraphic{concept} + draw btex \colored[s=.8]{\bf CONCEPT} etex rotated 60 ; + currentpicture := currentpicture + ysized (\overlayheight-.5cm) ; +\stopuniqueMPgraphic + +\defineoverlay[concept][\uniqueMPgraphic{concept}] +\stopbuffer + +\typebuffer[a] + +You can now put this graphic in the page background by +saying: + +\starttyping +\setupbackgrounds[page][background=concept] +\stoptyping + +You may consider the next alternative a bit better, but still it renders the text +unreadable. Like \type {xysized}, the macro \type {enlarged} is not part of +standard \METAPOST, but comes with \CONTEXT. + +\startbuffer[b] +\startuniqueMPgraphic{copyright} + picture p ; p := btex \colored[s=.8]{COPYRIGHT} etex + rotated 90 ; + setbounds p to boundingbox p enlarged 1pt ; + draw p ; + currentpicture := currentpicture + xysized (\overlaywidth,\overlayheight) ; +\stopuniqueMPgraphic + +\defineoverlay[copyright][\uniqueMPgraphic{copyright}] +\stopbuffer + +\typebuffer[b] + +Again, we put this graphic in the background. By using a unique graphic, we make +sure that it's rendered only once and reused when possible. + +\startbuffer[c] +\setupbackgrounds[text][rightmargin][background=copyright] +\stopbuffer + +\typebuffer[c] + +\doifnotmode{screen}{\getbuffer[b,c]} + +In both cases, we slightly scale down the graphic. We do so because otherwise a +small portion of the text is clipped off. This is unrelated to \TEX\ or +\METAPOST, but a characteristic of the font. Compare the following Pagella, Latin +Modern and Termes gi's (the Pagella is the body font of this text). + +\startbuffer +\hbox \bgroup + \hbox{\definedfont[file:texgyrepagella-regular at 6cm]gi}% + \hbox{\definedfont[file:lmroman10-regular at 6cm]gi}% + \hbox{\definedfont[file:texgyretermes-regular at 6cm]gi}% +\egroup +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +{\showboxes \getbuffer} +\stoplinecorrection + +Watch how the bounding boxes differ and sometimes cross the shape. So, in order +not to loose part of a glyph when clipping, you need to add a bit of space. \in +{Figure} [fig:annoying] shows the two backgrounds in action. + +\startbuffer +\getbuffer[a,b] +\def\ShowPage#1% % (yet) no image as background to image + {\framed % possible due to nested file problems + [background=#1,offset=overlay] + {\typesetfile[mfun-900.tex][page=1,width=.4\textwidth]}} +\startcombination + {\ShowPage{concept}} {concept} + {\ShowPage{copyright}} {copyright} +\stopcombination +\stopbuffer + +\placefigure + [here][fig:annoying] + {Two examples of annoying backgrounds.} + {\getbuffer} + +If you really want to add such texts to a document, in \CONTEXT\ we don't have to +use the page background, but can use one of the layout areas instead (like \type +{[text][text]} or \type {[text][leftmargin]}) + +\typebuffer[d] + +There is one drawback: when your left and right margin have different dimensions, +the text will be scaled differently on odd and even pages. Normally this is no +problem for a draft. + +As an alternative you can use the \type {\setuptexts} command and wrap the +graphic in a box with the right dimensions, using code like: + +\starttyping +\startuniqueMPgraphic{copyright} + picture p ; p := btex COPYRIGHT etex rotated 90 ; + setbounds p to boundingbox p enlarged 1pt ; + draw p withcolor .8white ; + xyscale_currentpicture(\the\leftmarginwidth,\the\textheight) ; +\stopuniqueMPgraphic + +\setuptexttexts [margin] [] [\uniqueMPgraphic{copyright}] +\stoptyping + +The graphic goes into the outer margin. The second argument can be used to put +something in the inner margin. + +\stopsection + +\startsection[title={Multiple overlays}] + +\index{overlays+stack} + +\setupbackgrounds[text][rightmargin][background=] + +You can stack overlays. Consider the next case, where we assume that you have +enabled interaction support using \type {\setupinteraction[state=start]}: + +\starttyping +\setupbackgrounds + [page] + [background={color,nextpage}, + backgroundcolor=darkyellow] +\stoptyping + +Here, the page gets a colored background and a hyperlink to the next page, +previously defined by: + +\starttyping +\defineoverlay[nextpage][\overlaybutton{nextpage}] +\stoptyping + +An \type {\overlaybutton} is just a button, with all attributes (color, frame, +etc) set to nothing, having the dimensions of the overlay. The argument is one of +the permitted destinations, like \type {nextpage}, \type {firstpage}, \type +{SearchDocument} and alike. + +For efficiency reasons, the background areas (like \type {[text][text]}) are +calculated only when their definition has changed. When a background changes per +page, we have to recalculate it on each page. In the next example, the macro +\type {\overlaybutton} generates a different button on each page. But, since we +don't explicitly set the background at each page, there is no way the background +drawing mechanism can know that this button has changed. Therefore, we must force +recalculation with: + +\starttyping +\setupbackgrounds[state=repeat] +\stoptyping + +You can test this concept yourself with the following code. Here we assume that +you have a file called \type {tufte.tex} on your system, which is the case if you +have \CONTEXT\ installed. However, you can just as easily use any file having a +paragraph of two of text. + +\starttyping +\starttext +\setupinteraction[state=start] +\setupbackgrounds[state=repeat] +\defineoverlay[nextpage][\overlaybutton{nextpage}] +\setupbackgrounds[text][text][background=nextpage] +\dorecurse{20}{\input tufte \par} +\stoptext +\stoptyping + +Note that you can move forward from page to page in the resulting \PDF\ file by +clicking on each page with the mouse. Now compile this file without setting the +background state to \type {repeat} and note the difference as you click pages +with the mouse. + +Setting the state was not needed when we used the page background: + +\starttyping +\setupbackgrounds[page][background=nextpage] +\stoptyping + +The \type {\dorecurse} macro is handy for testing since it saves us typing. One +can nest this macro as in: + +\starttyping +\dorecurse{20}{\dorecurse{10}{Hello World! }\par} +\stoptyping + +The current step is available in \type {\recurselevel} and the depth (nesting +level) in \type {\recursedepth}. + +\stopsection + +\startsection[title={Crossing borders}] + +\index{backgrounds} + +In many cases, the previously mentioned background areas will suffice, but in the +case of more complicated backgrounds, you may wish to use \METAPOST\ to draw +graphics that combine or span these areas. + +At runtime \CONTEXT\ saves information on the layout that can be picked up by +\METAPOST. The framework for a page graphic is: + +\starttyping +StartPage; + % all kind of commands +StopPage ; +\stoptyping + +Between the \type {StartPage} and \type {StopPage} command you have access to a +wide range of variables: + +\starttabulate[|l|Tp|] +\HL +\NC page \NC PaperHeight PaperWidth \NC \NR +\NC \NC PrintPaperHeight PrintPaperWidth \NC \NR +\NC \NC PageOffset PageDepth \NC \NR +\NC margins \NC TopSpace BackSpace \NC \NR +\NC text \NC MakeupHeight MakeupWidth \NC \NR +\NC vertical \NC TopHeight TopDistance \NC \NR +\NC \NC HeaderHeight HeaderDistance \NC \NR +\NC \NC TextHeight \NC \NR +\NC \NC FooterDistance FooterHeight \NC \NR +\NC \NC BottomDistance BottomHeight \NC \NR +\NC horizontal \NC LeftEdgeWidth LeftEdgeDistance \NC \NR +\NC \NC LeftMarginWidth LeftMarginDistance \NC \NR +\NC \NC TextWidth \NC \NR +\NC \NC RightMarginDistance RightMarginWidth \NC \NR +\NC \NC RightEdgeDistance RightEdgeWidth \NC \NR +\HL +\stoptabulate + +Since using these variables to construct paths is not that handy because the +areas are available as predefined paths, which we will demonstrate here. + +\placefigure + [here][fig:back 1] + {A background with combined areas.} + {\startcombination + {\typesetfile[mfun-900.tex][page=2,width=.4\textwidth]}{even} + {\typesetfile[mfun-900.tex][page=3,width=.4\textwidth]}{odd} + \stopcombination} + +In \in {figure} [fig:back 1] you see two pages (odd and even) with a background +spanning the outer margin and the text area. You can access an area in two ways. +The area itself is available as \type {Area}. + +\starttyping +StartPage ; + fill Area[Text][Text] withcolor .85white ; +StopPage ; +\stoptyping + +If you use an area this way, you will notice that it is not positioned at the +right place. An \type {Area} is just a rectangle. If you want a positioned area, +you should use the \type {Field} array: + +\starttyping +StartPage ; + fill Field[Text][Text] withcolor .85white ; +StopPage ; +\stoptyping + +The location of an area is available in \type {Location}, so the previous +definition is the same as: + +\starttyping +StartPage ; + fill Area[Text][Text] shifted Location[Text][Text] + withcolor .85white ; +StopPage ; +\stoptyping + +The following definition fills and draws the margin and text areas. + +\typebuffer[back-2] + +This background is assigned to the page layer by saying: + +\typebuffer[back-0] + +As you can see in \in {figure} [fig:back 2], the text is typeset rather tightly +between the left and right margins. + +\placefigure + [here][fig:back 2] + {A background with split areas.} + {\startcombination + {\typesetfile[mfun-900.tex][page=4,width=.4\textwidth]}{even} + {\typesetfile[mfun-900.tex][page=5,width=.4\textwidth]}{odd} + \stopcombination} + +This can easily be solved by enlarging the areas a bit. The next example +demonstrates this on the text area, which is shown in \in {figure} [fig:back 3]. + +\typebuffer[back-3] + +\placefigure + [here][fig:back 3] + {A background with enlarged text area.} + {\startcombination + {\typesetfile[mfun-900.tex][page=6,width=.4\textwidth]}{even} + {\typesetfile[mfun-900.tex][page=7,width=.4\textwidth]}{odd} + \stopcombination} + +The \type {enlarged} macro can be used like \type {shifted} and accepts either a +numeric or a pair. + +How do we define a background as in \in {figure} [fig:back 1]? Because \type +{Field} provides us the positioned areas, we can use the corners of those. + +\typebuffer[back-1] + +In this definition we calculate a different path for odd and even pages. When +done, we enlarge the path a bit. If you want to use different offsets in all +directions, you can use moved corner points. + +\typebuffer[back-4] + +Here we displace the corners randomly which leads to backgrounds like \in +{figure} [fig:back 4]. The following definition would have worked as well: + +\typebuffer[back-4x] + +\placefigure + [here][fig:back 4] + {A random text area.} + {\startcombination + {\typesetfile[mfun-900.tex][page=8,width=.4\textwidth]}{even} + {\typesetfile[mfun-900.tex][page=9,width=.4\textwidth]}{odd} + \stopcombination} + +The previous graphics are defined as usable ones, which means that they will be +recalculated each page. This is rather inefficient when the shapes don't change. +But, using a reusable graphic instead, would result in only one graphic for both +pages. Since the layout for the left and right page differs, another method is +needed. + +Instead of putting the same graphic on the page layer, we put two different ones +on the left and right page layer. + +\starttyping +\defineoverlay[left page] [\useMPgraphic{left page}] +\defineoverlay[right page][\useMPgraphic{right page}] + +\setupbackgrounds[leftpage] [background=left page] +\setupbackgrounds[rightpage][background=right page] +\stoptyping + +Now we only have to split the previously defined graphic into two parts. In order +to force consistency, we isolate the code that fills and draws. The left page +code looks like: + +\starttyping +\startreusableMPgraphic{left page} + StartPage ; + path Main ; Main := + llcorner Field[OuterMargin][Text] -- + lrcorner Field[Text] [Text] -- + urcorner Field[Text] [Text] -- + ulcorner Field[OuterMargin][Text] -- cycle ; + \includeMPgraphic{draw page} + StopPage ; +\stopreusableMPgraphic +\stoptyping + +The right page text looks similar: + +\starttyping +\startreusableMPgraphic{right page} + StartPage ; + path Main ; Main := + lrcorner Field[OuterMargin][Text] -- + llcorner Field[Text] [Text] -- + ulcorner Field[Text] [Text] -- + urcorner Field[OuterMargin][Text] -- cycle ; + \includeMPgraphic{draw page} + StopPage ; +\stopreusableMPgraphic +\stoptyping + +Watch how we used a reusable graphic first and a simple usable one next. +Actually, the next graphic is not a stand alone graphic. + +\starttyping +\startuseMPgraphic{draw page} + Main := Main enlarged 6pt ; + pickup pencircle scaled 2pt ; + fill Page withcolor .625white ; + fill Main withcolor .850white ; + draw Main withcolor .625red ; +\stopuseMPgraphic +\stoptyping + +We have seen some predefined paths and locations. Apart from the \type {Page} +path, they take two arguments that specify their position on the layout grid. + +\starttabulate[|lT|l|] +\HL +\NC path Area [][] \NC an area similar to a \CONTEXT\ one \NC \NR +\NC pair Location [][] \NC the position of this area \NC \NR +\NC path Field [][] \NC the area positioned at the right place \NC \NR +\NC path Page \NC the page itself \NC \NR +\HL +\stoptabulate + +Some less used and more obscure variables are the following. + +\starttabulate[|lT|l|] +\HL +\NC numeric Hstep [] \NC the horizontal distance to the previous area \NC \NR +\NC numeric Vstep [] \NC the vertical distance to the previous area \NC \NR +\NC numeric Hsize [] \NC the width of an area \NC \NR +\NC numeric Vsize [] \NC the height of an area \NC \NR +\HL +\stoptabulate + +The array variables are accessed by using constants: + +\starttabulate[|l|l|] +\HL +\NC horizontal \NC vertical \NC \NR +\HL +\NC LeftEdge \NC Top \NC \NR +\NC LeftEdgeSeparator \NC TopSeparator \NC \NR +\NC LeftMargin \NC Header \NC \NR +\NC LeftMarginSeparator \NC HeaderSeparator \NC \NR +\NC Text \NC Text \NC \NR +\NC RightMarginSeparator \NC FooterSeparator \NC \NR +\NC RightMargin \NC Footer \NC \NR +\NC RightEdgeSeparator \NC BottomSeparator \NC \NR +\NC RightEdge \NC Bottom \NC \NR +\HL +\stoptabulate + +In addition to these, there are \type {Margin}, \type {InnerMargin} and \type +{OuterMargin} which adapt themselves to the current odd or even page. The same is +true for \type {Edge}, \type {InnerEdge} and \type {OuterEdge}, although these +will seldom be used, since interactive documents are always single sided. + +We started this chapter with spending a lot of code to simulate the page areas. +It will be clear now that in practice this is much easier using the mechanism +described here. + +\placefigure + [here][fig:back 5] + {A quick way to draw all used areas.} + {\setupexternalfigures[background=color,backgroundcolor=white]% + \startcombination + {\typesetfile[mfun-900.tex][page=10,width=.4\textwidth]}{even} + {\typesetfile[mfun-900.tex][page=11,width=.4\textwidth]}{odd} + \stopcombination} + +In \in {figure} [fig:back 5] we see all used areas. Areas that are not used are +not drawn (which saves some testing). This background was defined as: + +\typebuffer[back-5] + +We use two nested \type {for} loops to step over the areas. A \type {for} loop +with a step of~1 will fail, because the indices are defined in a rather special +way. On the other hand, the mechanism is rather tolerant, in the sense that \type +{[i][j]} and \type {[j][i]} are both accepted. + +\stopsection + +\startsection[title={Bleeding}] + +\index {bleeding} + +If you want to share your document all over the world, it makes sense to use a +paper format like {\em letter} or {\em A4}. In that case, the layout often +matches the paper size. + +\startlinecorrection[blank] +\startMPcode + path p ; p := fullcircle xyscaled (21mm,29.7mm) ; + path q ; q := boundingbox p ; + fill q withcolor .625white ; + fill p withcolor .625yellow ; + currentpicture := currentpicture shifted (-31mm,0) ; + fill q withcolor .625white ; + fill p xsized (bbwidth(p)-2mm) withcolor .625yellow ; + currentpicture := currentpicture shifted (-31mm,0) ; + fill q withcolor .625white ; + fill p withcolor .625yellow ; + draw q enlarged -1mm withpen pencircle scaled 2mm withcolor .625white ; +\stopMPcode +\stoplinecorrection + +The left picture demonstrates what happens when you have a printer that is +capable of printing from edge to edge. If you have such a printer, you're lucky. +The middle picture demonstrates what happens if you have a properly set up +printing program and|/|or printer: the page is scaled down so that the content +fits into the non printable area of the printer. One reason why printers don't +print from edge to edge is that the engine is not that happy when toner or ink +ends up next to the page. The third picture shows what happens when a printer +simply ignores content that runs over the non printable area. In many cases it's +best to make sure that the content leaves a margin of 5mm from the edges. + +Books and magazines seldom use the popular desk||top paper sizes. Here the +designer determined the paper size and layout more or less independent from the +size of the sheet on which the result is printed. Instead of one page per sheet, +arrangements of 2 upto 32 or more pages per sheet are made. The process of +arranging pages in such a way that these sheets can be folded and combined into +books is called page imposition. \CONTEXT\ supports a wide range of page +imposition schemes. More information on this can be found in the \CONTEXT\ +manuals. + +The fact that the sheet on which a page is printed is larger than the page itself +opens the possibility to use the full page for content. In that case, especially +when you use background graphics, you need to make sure that indeed the page is +covered completely. Where in desk top printing you can get away with imperfection +simply because the printing engines have their limitations, in professional +output you need to be more considerate. + +\startlinecorrection[blank] +\startMPcode + path p ; p := fullsquare xyscaled (4cm,5cm) ; + path q ; q := fullsquare xyscaled (3cm,4cm) ; + path r ; r := fullsquare xyscaled (2cm,3cm) shifted (-.5cm,.5cm) ; + fill p withcolor .625white ; + fill q withcolor .850white ; + currentpicture := currentpicture shifted (-45mm,0) ; + fill p withcolor .625white ; + fill q withcolor .850white ; + fill r withcolor transparent(1,.5,.625yellow) ; + currentpicture := currentpicture shifted (-45mm,0) ; + fill p withcolor .625white ; + fill q withcolor .850white ; + r := r topenlarged 2mm leftenlarged 2mm ; + fill r withcolor transparent(1,.5,.625yellow) ; +\stopMPcode +\stoplinecorrection + +Slightly enlarging a graphic so that it exceeds the natural page limits is called +bleeding. Because quite often layout elements have a rectangular nature, +\METAFUN\ provides a couple of operations that can save you some work in defining +bleeding boxes. + +\startbuffer +path p, q ; +def ShowPath = + fill p withcolor transparent(1,.5,.625yellow) ; + fill q withcolor transparent(1,.5,.625yellow) ; + currentpicture := currentpicture shifted (-25mm,0) ; +enddef ; +p := q := fullsquare xyscaled (2cm,3cm) ; ShowPath ; +p := p leftenlarged 2mm ; ShowPath ; +p := p topenlarged 2mm ; ShowPath ; +p := p rightenlarged 2mm ; ShowPath ; +p := p bottomenlarged 2mm ; ShowPath ; +\stopbuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +This graphic is generated as follows: + +\typebuffer + +The trick is in the last couple of lines. In addition to the general \type +{enlarged} operator, we have 4~operators that enlarge a rectangle in a certain +direction. This means that we can define the original path using dimensions +related to the layout, and add bleed strips independently. + +\startbuffer +path p ; p := fullsquare xyscaled (4cm,1cm) ; +path q ; q := p leftenlarged 2mm topenlarged 2mm ; +fill p withcolor transparent(1,.5,.625yellow) ; +fill q withcolor transparent(1,.5,.625yellow) ; +draw boundingbox currentpicture withcolor .625red ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +This example demonstrates that when we enlarge a graphic, the bounding box also +gets larger. Because this can interfere with the placement of such a graphic, we +need to make sure that the bleeding is there but not seen. + +\startbuffer +path p ; p := fullsquare xyscaled (4cm,1cm) ; +path q ; q := p leftenlarged 2mm topenlarged 2mm ; +fill p withcolor transparent(1,.5,.625yellow) ; +fill q withcolor transparent(1,.5,.625yellow) ; +setbounds currentpicture to p ; +draw boundingbox currentpicture withcolor .625red ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +There are two more operators: \type {innerenlarged} and \type {outerenlarged}. +These expand to either \type {leftenlarged} or \type {rightenlarged}, depending +on the page being left or right hand. + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/metafun/metafun-backpage.tex b/doc/context/sources/general/manuals/metafun/metafun-backpage.tex new file mode 100644 index 000000000..82931d756 --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/metafun-backpage.tex @@ -0,0 +1,53 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\doifmode{book}{\endinput} + +\startcomponent metafun-backpage + +\environment metafun-environment + +\startstandardmakeup[doublesided=no,page=right] + % back page +\stopstandardmakeup + +\setupbackgrounds + [leftpage] + [background=back page] + +\definecolor[twhite][s=1,t=.80,a=1] + +\setupbackgrounds + [text][text] + [background=color, + backgroundcolor=twhite, + backgroundoffset=.5cm] + +\setuplayout + [cutspace=2cm, + backspace=8cm, + header=0pt, + footer=0pt, + topspace=17cm, + bottomspace=2cm] + +\startstandardmakeup[doublesided=no,page=left,top=,bottom=] + + \switchtobodyfont[big] + + \setupinterlinespace[stretch=.5] + + \getbuffer[backtext] + + \blank + + \getbuffer[backbanner] + +\stopstandardmakeup + +\setupbackgrounds + [rightpage] + [background=] + +\stopcomponent diff --git a/doc/context/sources/general/manuals/metafun/metafun-basics.tex b/doc/context/sources/general/manuals/metafun/metafun-basics.tex new file mode 100644 index 000000000..df556e239 --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/metafun-basics.tex @@ -0,0 +1,3587 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\startcomponent metafun-basics + +\environment metafun-environment + +\startchapter[title={A few more details}] + +\startintro + +In this chapter we will see how to define a \METAPOST\ graphic, and how to +include it in a document. Since the exact dimensions of graphics play an +important role in the placement of a graphic, we will explore the way a bounding +box is constructed. + +We will also pay attention to the usage of units and the side effects of scaling +and shifting, since they can contradict our expectations in unexpected ways. +Furthermore we will explore a few obscure areas. + +\stopintro + +\startsection[title={Making graphics}] + +\index{graphics} + +In this manual we will use \METAPOST\ in a rather straightforward way, and we +will try to avoid complicated math as much as possible. We will do a bit of +drawing, clipping, and moving around. Occasionally we will see some more +complicated manipulations. + +When defined as stand||alone graphic, a \METAPOST\ file looks like this: + +\starttyping +% Let's draw a circle. + +beginfig (7) ; + draw fullcircle scaled 3cm withpen pencircle scaled 1cm ; +endfig ; + +end . +\stoptyping + +The main structuring components in such a file are the \type {beginfig} and \type +{endfig} macros. Like in a big story, the file has many sub||sentences, where +each sub||sentence ends with a semi||colon. Although the \type {end} command at +the end of the file concludes the story, putting a period there is a finishing +touch. Actually, after the \type {end} command you can put whatever text you +wish, your comments, your grocery list, whatever. Comments in \METAPOST, prefixed +by a percent sign, as in \typ {% Let's draw a circle}, are ignored by the +interpreter, but useful reminders for the programmer. + +If the file is saved as \type {yourfile.mp}, then the file is processed by +\METAPOST\ by issuing the following command: + +\starttyping +mpost yourfile +\stoptyping + +after which you will have a graphic called \type {yourfile.7}, which contains a +series of \POSTSCRIPT\ commands. Because \METAPOST\ does all the work, this file +is efficient and compact. The number of distinct \POSTSCRIPT\ operators used is +limited, which has the advantage that we can postprocess this file rather easily. +Alternatively \METAPOST\ can generate \SVG\ output. It does when you say + +\starttyping +outputformat := "svg" ; +\stoptyping + +Here we will not go into details about this format. Even \POSTSCRIPT\ is not +covered in detail as we use \METAPOST\ mostly in embedded form. + +We can view this file in a \POSTSCRIPT\ viewer like \GHOSTVIEW\ or convert the +graphic to \PDF\ (using \type {mptopdf}) and view the result in a suitable \PDF\ +viewer like \ACROBAT. Of course, you can embed such a file in a \CONTEXT\ +document, using a command like: + +\starttyping +\externalfigure[yourfile.7] +\stoptyping + +We will go in more detail about embedding graphics in \in {chapter} +[sec:embedding]. + +If you have installed \CONTEXT, somewhere on your system there resides a file +\type {mp-tool.mp}. If you make a stand||alone graphic, it's best to put the +following line at the top of your file: + +\starttyping +input mp-tool ; % or input metafun ; +\stoptyping + +By loading this file, the resulting graphic will provide a high resolution +bounding box, which enables more accurate placement. The file also sets the \typ +{prologues := 1} so that viewers like \GHOSTVIEW\ can refresh the file when it is +changed. + +Next we will introduce some more \METAPOST\ commands. From now on, we will omit +the encapsulating \type {beginfig} and \type {endfig} macros. If you want to +process these examples yourself, you should add those commands yourself, or if +you use \CONTEXT\ you don't need them at all. + +\startbuffer +pickup pencircle scaled .5cm ; +draw unitsquare xscaled 8cm yscaled 1cm withcolor .625white ; +draw origin withcolor .625yellow ; +pickup pencircle scaled 1pt ; +draw bbox currentpicture withcolor .625red ; +\stopbuffer + +\typebuffer + +In this example we see a mixture of so called primitives as well as macros. A +primitive is something hard coded, a built||in command, while a macro is a +collection of such primitives, packaged in a way that they can be recalled +easily. Where \type {scaled} is a primitive and \type {draw} a macro, \type +{unitsquare} is a path variable, an abbreviation for: + +\starttyping +unitsquare = (0,0) -- (1,0) -- (1,1) -- (0,1) -- cycle ; +\stoptyping + +The double dash (\type {--}) is also a macro, used to connect two points with a +straight line segment. However, \type {cycle} is a primitive, which connects the +last point of the unitsquare to the first on unitsquare's path. Path variables +must first be declared, as in: + +\starttyping +path unitsquare ; +\stoptyping + +A large collection of such macros is available when you launch \METAPOST. Consult +the \METAPOST\ manual for details. + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +In the first line of our example, we set the drawing pen to \type {.5cm}. You can +also specify such a dimension in other units, like points (\type {pt}). When no +unit is provided, \METAPOST\ will use a big point (\type {bp}) , the \POSTSCRIPT\ +approximation of a point. + +The second line does just as it says: it draws a rectangle of certain dimensions +in a certain color. In the third line we draw a colored dot at the origin of the +coordinate system in which we are drawing. Finally, we set up a smaller pen and +draw the bounding box of the current picture, using the variable \type +{currentpicture}. Normally, all drawn shapes end up in this picture variable. + +\stopsection + +\startsection[title={Bounding boxes}] + +\index{boundingbox} + +If you take a close look at the last picture in the previous section, you will +notice that the bounding box is larger than the picture. This is one of the nasty +side effects of \METAPOST's \type {bbox} macro. This macro draws a box, but with +a certain offset. The next example shows how we can manipulate this offset. +Personally I never use the \type {bbox} macro because this offset is rather +annoying. Also, the \type {boundingbox} operator combined with \type {enlarged} +can provide any offset you want. + +\startbuffer +pickup pencircle scaled .5cm ; +draw unitsquare xscaled 8cm yscaled 1cm withcolor .625white ; +path bb ; bboxmargin := 0pt ; bb := bbox currentpicture ; +draw bb withpen pencircle scaled 1pt withcolor .625red ; +draw origin withpen pencircle scaled 5pt withcolor .625yellow ; +\stopbuffer + +\typebuffer + +In the third line we define a path variable. We assign the current bounding box +to this variable, but first we set the offset to zero. The last line demonstrates +how to draw such a path. Instead of setting the pen as we did in the first line, +we pass the dimensions directly. + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +Where \type {draw} draws a path, the \type {fill} macro fills one. In order to be +filled, a path should be closed, which is accomplished by the \type {cycle} +primitive, as we saw in constructing the \type {unitsquare} path. + +\startbuffer +pickup pencircle scaled .5cm ; +fill unitsquare xscaled 8cm yscaled 1cm withcolor .625white ; +path bb ; bboxmargin := 0pt ; bb := bbox currentpicture ; +draw bb withpen pencircle scaled 1pt withcolor .625red ; +draw origin withpen pencircle scaled 5pt withcolor .625yellow ; +\stopbuffer + +\typebuffer + +This example demonstrates that when we fill the path, the resulting graphic is +smaller. Where \type {draw} follows the center of a path, \type {fill} stays +inside the path. + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +A third alternative is the \type {filldraw} macro. From the previous examples, we +would expect a bounding box that matches the one of the drawn path. + +\startbuffer +pickup pencircle scaled .5cm ; +filldraw unitsquare xscaled 8cm yscaled 1cm withcolor .625white ; +path bb ; bboxmargin := 0pt ; bb := bbox currentpicture ; +draw bb withpen pencircle scaled 1pt withcolor .625red ; +draw origin withpen pencircle scaled 5pt withcolor .625yellow ; +\stopbuffer + +\typebuffer + +% The resulting graphic has the bounding box of the fill. Note +% how the path, because it is stroked with a .5cm pen, extends +% beyond the border of the bounding box. The way this image +% shows up depends on the viewer (settings) you use to render +% the graphic. For example, in \GHOSTVIEW, if you disable +% clipping to the bounding box, only the positive quadrant of +% the graphic is shown. Further, if you enable clipping to the +% bounding box, this image will look exactly like the previous +% image created with the fill command. In many cases, it may +% be best to avoid the \type {filldraw} command. + +The resulting graphic has the bounding box of the fill. Note how the path, +because it is stroked with a .5cm pen, extends beyond the border of the previous +bounding box. The way this image shows up depends on the viewer (settings) you +use to render the graphic. For example, in \GHOSTVIEW, if you disable clipping to +the bounding box, only the positive quadrant of the graphic is shown. \footnote +{Old versions of \METAPOST\ calculated the boundingbox differently for a \type +{filldraw}: through the middle of the penpath.} + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +From the previous examples, you can conclude that the following alternative +results in a proper bounding box: + +\startbuffer +pickup pencircle scaled .5cm ; +path p ; p := unitsquare xscaled 8cm yscaled 1cm ; +fill p withcolor .625white ; +draw p withcolor .625white ; +path bb ; bboxmargin := 0pt ; bb := bbox currentpicture ; +draw bb withpen pencircle scaled 1pt withcolor .625red ; +draw origin withpen pencircle scaled 5pt withcolor .625yellow ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +The \CONTEXT\ distribution comes with a set of \METAPOST\ modules, one of which +contains the \type {drawfill} macro, which provides the outer bounding box. +\footnote {Starting from version 1.0 \METAPOST\ calculates the boundingbox +differently and the distinction between \type {drawfill} and \type {filldraw} is +gone. We keep them around both for compatibility.} Next we demonstrate its use in +another, more complicated example. + +\startbuffer +picture finalpicture ; finalpicture := nullpicture ; +numeric n ; n := 0 ; bboxmargin := 0pt ; +pickup pencircle scaled .5cm ; + +def shape = + unitsquare scaled 2cm withcolor .625white ; + draw bbox currentpicture + withpen pencircle scaled .5mm withcolor .625red ; + addto finalpicture also currentpicture shifted(n*3cm,0) ; + currentpicture := nullpicture ; n := n+1 ; +enddef ; + +fill shape ; draw shape ; filldraw shape ; drawfill shape ; + +currentpicture := finalpicture ; +\stopbuffer + +\typebuffer + +Here we introduce a macro definition, \type {shape}. In \METAPOST, the start of a +macro definition is indicated with the keyword \type {def}. Thereafter, you can +insert other variables and commands, even other macro definitions. The keyword +\type {enddef} signals the end of the macro definition. The result is shown in +\in {figure} [fig:draws and fills]; watch the bounding boxes. Close reading of +the macro will reveal that the \type {fill}, \type {draw}, \type {filldraw} and +\type {drawfill} macros are applied to the first \type {unitsquare} path in the +macro. + +\placefigure + [here] + [fig:draws and fills] + {A \type {fill}, \type {draw}, \type {filldraw} and \type + {drawfill} applied to the same square.} + {\processMPbuffer} + +In this macro, \type {bbox} calls a macro that returns the enlarged bounding box +of a path. By setting \type {bboxmargin} we can influence how much the bounding +box is enlarged. Since this is an existing variable, we don't have to allocate +it, like we do with~\type{numeric n}. Unless you take special precautions, +variables are global by nature and persistent outside macros. + +\starttyping +picture finalpicture ; finalpicture := nullpicture ; +\stoptyping + +Just as \type {numeric} allocates an integer variable, the \type {picture} +primitive allocates a picture data structure. We explicitly have to set this +picture to nothing using the built||in primitive \type {nullpicture}. + +Later on, we will add the drawn paths as accumulated in \type {currentpicture} to +this \type {finalpicture} in the following manner. + +\starttyping +addto finalpicture also currentpicture shifted(n*3cm,0) ; +\stoptyping + +Since we want to add a few more and don't want them to overlap, we shift them. +Therefore we have to erase the current picture as well as increment the shift +counter. + +\starttyping +currentpicture := nullpicture ; n := n+1 ; +\stoptyping + +The \type {drawfill} macro is one of the \METAFUN\ macros. Another handy macro is +\type {boundingbox}. When used instead of \type {bbox}, you don't have to set the +margin to zero. + +\startbuffer +drawoptions (withcolor .625white) ; +path p ; p := unitsquare scaled 2cm ; +fill p shifted (3cm,0) ; +pickup pencircle scaled .5cm ; fill p shifted (6cm,0) ; +fill p shifted (9cm,0) withpen pencircle scaled .5cm ; +\stopbuffer + +\placefigure + [here] + [fig:more draws and fills] + {The influence of pens on \type {fill}.} + {\processMPbuffer} + +There is a subtle point in filling a shape. In \in {figure} [fig:more draws and +fills] you see the influence of the pen on a \type {fill} operation. An indirect +specification has no influence, and results in a filled rectangle with sharp +corners. The third rectangle is drawn with a direct pen specification which +results in a larger shape with rounds corners. However, the bounding box is the +same in all three cases. The graphic is defined as follows. This time we don't +use a (complicated) macro. + +\typebuffer + +When a graphic is constructed, its components end up in an internal data +structure in a more or less layered way. This means that as long as a graphic is +not flushed, you may consider it to be a stack of paths and texts with the paths +being drawn or filled shapes or acting as clipping paths or bounding boxes. + +When you ask for the dimensions of a graphic the lower left and upper right +corner are calculated using this stack. Because you can explicitly set bounding +boxes, you can lie about the dimensions of a graphic. This is a very useful +feature. In the rare case that you want to know the truth and nothing but the +truth, you can tweak the \type {truecorners} numeric variable. We will +demonstrate this with a few examples. + +\startbuffer +fill fullcircle scaled 1cm withcolor .625yellow ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank]\ruledhbox{\processMPbuffer}\stoplinecorrection + +\startbuffer +fill fullcircle scaled 1cm withcolor .625yellow ; +setbounds currentpicture to boundingbox currentpicture enlarged 2mm ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank]\ruledhbox{\processMPbuffer}\stoplinecorrection + +\startbuffer +fill fullcircle scaled 1cm withcolor .625yellow ; +setbounds currentpicture to boundingbox currentpicture enlarged 2mm ; +interim truecorners := 1 ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank]\ruledhbox{\processMPbuffer}\stoplinecorrection + +\startbuffer +fill fullcircle scaled 1cm withcolor .625yellow ; +interim truecorners := 1 ; +setbounds currentpicture to boundingbox currentpicture enlarged 2mm ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank]\ruledhbox{\processMPbuffer}\stoplinecorrection + +As you can see here, as soon as we set \type {truecorners} to~1, the bounding box +settings are ignored. \footnote {Normally you will use grouping to keep the +interim local. In \METAFUN\ each figure restores this variable at the beginning.} + +There are two related macros: \type {bbwidth} and \type {bbheight} that you can +apply to a path. + +\startbuffer +fill unitcircle xscaled 4cm yscaled 2cm + withpen pencircle scaled 1mm withcolor .625red ; +draw origin -- (bbwidth(currentpicture),0) + withpen pencircle scaled 1mm withcolor .625yellow ; +draw origin -- (0,bbheight(currentpicture)) + withpen pencircle scaled 1mm withcolor .625white ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank]\processMPbuffer\stoplinecorrection + +\stopsection + +Yet another helper is \type {boundingcircle}. Its effect can best be demonstrated with +a few examples: + +\startbuffer[a] +path p ; p := fullsquare scaled 2cm ; + +draw p withpen pencircle scaled 3mm withcolor .625white ; +draw center p withpen pencircle scaled 3mm withcolor .625white ; +draw boundingbox p withpen pencircle scaled 1mm withcolor .625red ; +draw boundingcircle p withpen pencircle scaled 1mm withcolor .625yellow ; +\stopbuffer + +\startbuffer[b] +path p ; p := fullcircle scaled 2cm ; + +draw p withpen pencircle scaled 3mm withcolor .625white ; +draw center p withpen pencircle scaled 3mm withcolor .625white ; +draw boundingbox p withpen pencircle scaled 1mm withcolor .625red ; +draw boundingcircle p withpen pencircle scaled 1mm withcolor .625yellow ; +\stopbuffer + +\startbuffer[c] +path p ; p := fulltriangle scaled 2cm ; + +draw p withpen pencircle scaled 3mm withcolor .625white ; +draw center p withpen pencircle scaled 3mm withcolor .625white ; +draw boundingbox p withpen pencircle scaled 1mm withcolor .625red ; +draw boundingcircle p withpen pencircle scaled 1mm withcolor .625yellow ; +\stopbuffer + +\typebuffer[a,b,c] + +You can consider the \type {boundingcircle} to be a round boundingbox. + +\startlinecorrection +\startcombination[nx=3,ny=1,location=middle] + {\processMPbuffer[a]} {square} + {\processMPbuffer[b]} {circle} + {\processMPbuffer[c]} {triangle} +\stopcombination +\stoplinecorrection + +\startsection[title={Units}] + +\index{units} + +Like \TEX, \METAPOST\ supports multiple units of length. In \TEX, these units are +hard coded and handled by the parser, where the internal unit of length is the +scaled point (\type {sp}), something on the nanometer range. Because \METAPOST\ +is focused on \POSTSCRIPT\ output, its internal unit is the big point (\type +{bp}). All other units are derived from this unit and available as numeric +instead of hard coded. + +\starttyping +mm = 2.83464 ; pt = 0.99626 ; dd = 1.06601 ; bp := 1 ; +cm = 28.34645 ; pc = 11.95517 ; cc = 12.79213 ; in := 72 ; +\stoptyping + +Careful reading reveals that only the \type {bp} and \type {in} are fixed, while +the rest of the dimensions are scalar multiples of \type {bp}. + +Since we are dealing with graphics, the most commonly used dimensions are \type +{pt}, \type {bp}, \type {mm}, \type {cm} and~\type {in}. + +\startuseMPgraphic{pt} + fill fullsquare scaled 72.27pt withcolor .625yellow ; + fill fullcircle scaled 72.27pt withcolor white ; + label("72.27pt", center currentpicture) ; +\stopuseMPgraphic +\startuseMPgraphic{bp} + fill fullsquare scaled 72bp withcolor .625yellow ; + fill fullcircle scaled 72bp withcolor white ; + label("72bp", center currentpicture) ; +\stopuseMPgraphic +\startuseMPgraphic{mm} + fill fullsquare scaled 25.4mm withcolor .625yellow ; + fill fullcircle scaled 25.4mm withcolor white ; + label("25.4mm", center currentpicture) ; +\stopuseMPgraphic +\startuseMPgraphic{cm} + fill fullsquare scaled 2.54cm withcolor .625yellow ; + fill fullcircle scaled 2.54cm withcolor white ; + label("2.54cm", center currentpicture) ; +\stopuseMPgraphic +\startuseMPgraphic{in} + fill fullsquare scaled 1in withcolor .625yellow ; + fill fullcircle scaled 1in withcolor white ; + label("1in", center currentpicture) ; +\stopuseMPgraphic + +\startlinecorrection[blank] +\hbox to \hsize + {\useMPgraphic{pt}\hss + \useMPgraphic{bp}\hss + \useMPgraphic{mm}\hss + \useMPgraphic{cm}\hss + \useMPgraphic{in}} +\stoplinecorrection + +The text in the center of the leftmost graphic is typeset by \METAPOST\ as a +label. + +\starttyping +fill fullsquare scaled 72.27pt withcolor .625yellow ; +fill fullcircle scaled 72.27pt withcolor white ; +label("72.27pt", center currentpicture) ; +\stoptyping + +In \METAPOST\ the following lines are identical: + +\starttyping +draw fullcircle scaled 100 ; +draw fullcircle scaled 100bp ; +\stoptyping + +You might be tempted to omit the unit, but this can be confusing, particularly if +you also program in a language like \METAFONT, where the \type {pt} is the base +unit. This means that a circle scaled to 100 in \METAPOST\ is not the same as a +circle scaled to 100 in \METAFONT. Consider the next definition: + +\startbuffer +pickup pencircle scaled 0 ; +fill unitsquare + xscaled 400pt yscaled -.5cm withcolor .625red ; +fill unitsquare + xscaled 400bp yscaled +.5cm withcolor .625yellow ; +drawoptions(withcolor white) ; +label.rt("400 pt", origin shifted (0, -.25cm)) ; +label.rt("400 bp", origin shifted (0, +.25cm)) ; +\stopbuffer + +\typebuffer + +When processed, the difference between a \type {pt} and \type {bp} shows rather +well. Watch how we use \type {.rt} to move the label to the right; you can +compare this with \TEX's macro \type {\rlap}. You might want to experiment with +\type {.lft}, \type {.top}, \type {.bot}, \type {.ulft}, \type {.urt}, \type +{.llft} and \type {.lrt}. + +The difference between both bars is exactly \scratchdimen = 400 bp +\advance\scratchdimen by -400 pt \the \scratchdimen \space (as calculated by +\TEX). + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +Where \TEX\ is anchored in tradition, and therefore more or less uses the \type +{pt} as the default unit, \METAPOST, much like \POSTSCRIPT, has its roots in the +computer sciences. There, to simplify calculations, an inch is divided in 72 big +points, and .72pt is sacrificed. + +When you consider that \POSTSCRIPT\ is a high end graphic programming language, +you may wonder why this sacrifice was made. Although the difference between \type +{1bp} and \type {1pt} is miniscule, this difference is the source of much +(unknown) confusion. When \TEX\ users talk about a \type {10pt} font, a desktop +publisher hears \type {10bp}. In a similar vein, when we define a papersize +having a width of \type {600pt} and a height of \type {450pt}, which is papersize +\type {S6} in \CONTEXT, a \POSTSCRIPT\ or \PDF\ viewer will report slightly +smaller values as page dimensions. This is because those programs claim the \type +{pt} to be a \type {bp}. [This confusion can lead to interesting discussions with +desktop publishers when they have to use \TEX. They often think that their demand +of a baseline distance of \type {13.4} is met when we set it to \type {13.4pt}, +while actually they were thinking of \type {13.4bp}, which of course in other +programs is specified using a \type {pt} suffix.] + +Therefore, when embedding graphics in \CONTEXT, we strongly recommend that you +use \type {pt} as the base unit instead. The main reason why we spend so many +words on this issue is that, when neglected, large graphics may look inaccurate. +Actually, when taken care of, it is one of the (many) reasons why \TEX\ documents +always look so accurate. Given that the eye is sensitive to distortions of far +less than \type {1pt}, you can be puzzled by the fact that many drawing programs +only provide a bounding box in rounded units. Thereby, they round to the next +position, to prevent unwanted cropping. For some reason this low resolution has +made it into the high end \POSTSCRIPT\ standard. + +In \CONTEXT\ we try to deal with these issues as well as possible. + +\stopsection + +\startsection[title={Scaling and shifting}] + +\index{scaling} +\index{shifting} + +When we draw a shape, \METAPOST\ will adapt the bounding box accordingly. This +means that a graphic has its natural dimensions, unless of course we adapt the +bounding box manually. When you limit your graphic to a simple shape, say a +rectangle, shifting it to some place can get obscured by this fact. Therefore, +the following series of shapes appear to be the same. + +\startbuffer +draw + unitsquare xscaled 6cm yscaled 1.5cm + withpen pencircle scaled 2mm withcolor .625red ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank]\processMPbuffer\stoplinecorrection + +\startbuffer +draw + unitsquare shifted (.5,.5) xscaled 6cm yscaled 1.5cm + withpen pencircle scaled 2mm withcolor .625red ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank]\processMPbuffer\stoplinecorrection + +\startbuffer +draw + unitsquare shifted (-.5,-.5) xscaled 6cm yscaled 1.5cm + withpen pencircle scaled 2mm withcolor .625red ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank]\processMPbuffer\stoplinecorrection + +\startbuffer +draw + unitsquare xscaled 6cm yscaled 1.5cm shifted (1cm,1cm) + withpen pencircle scaled 2mm withcolor .625red ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank]\processMPbuffer\stoplinecorrection + +\startbuffer +draw + unitsquare xscaled 6cm yscaled 1.5cm shifted (1.5cm,1cm) + withpen pencircle scaled 2mm withcolor .625red ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank]\processMPbuffer\stoplinecorrection + +However, when we combine such graphics into one, we will see in what respect the +scaling and shifting actually takes place. + +\startbuffer +draw + unitsquare xscaled 6cm yscaled 2cm + withpen pencircle scaled 3.0mm withcolor .625yellow ; +draw + unitsquare shifted (.5,.5) xscaled 6cm yscaled 2cm + withpen pencircle scaled 3.0mm withcolor .625red ; +draw + unitsquare xscaled 6cm yscaled 2cm shifted (1cm,1cm) + withpen pencircle scaled 3.0mm withcolor .625white ; +draw + unitsquare xscaled 6cm yscaled 2cm shifted (1.5cm,1cm) + withpen pencircle scaled 1.5mm withcolor white ; +draw + unitsquare shifted (-.5,-.5) xscaled 6cm yscaled 2cm + withpen pencircle scaled 1mm withcolor black ; +draw origin withpen pencircle scaled 1mm ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank]\processMPbuffer\stoplinecorrection + +As you can see, the transformations are applied in series. Sometimes this is not +what we want, in which case we can use parentheses to force the desired +behaviour. The lesson learned is that {\em scaling and shifting} is not always +the same as {\em shifting and scaling}. + +\startbuffer +draw + origin -- origin shifted ((4cm,0cm) shifted (4cm,0cm)) + withpen pencircle scaled 1cm withcolor .625white ; +draw + origin -- origin shifted (4cm,0cm) shifted (4cm,0cm) + withpen pencircle scaled 8mm withcolor .625yellow ; +draw + (origin -- origin shifted (4cm,0cm)) shifted (4cm,0cm) + withpen pencircle scaled 6mm withcolor .625red ; +draw + origin -- (origin shifted (4cm,0cm) shifted (4cm,0cm)) + withpen pencircle scaled 4mm withcolor white ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank]\processMPbuffer\stoplinecorrection + +Especially when a path results from a call to a macro, using parentheses around a +path may help, as in the following example. + +\startbuffer +def unitslant = origin -- origin shifted (1,1) enddef ; +draw + unitslant xscaled 5cm yscaled 1cm + withpen pencircle scaled 1cm withcolor .625red ; +draw + (unitslant) xscaled 5cm yscaled 1cm + withpen pencircle scaled 5mm withcolor .625yellow ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank]\processMPbuffer\stoplinecorrection + +The next definition of \type {unitslant} is therefore better. + +\startbuffer +def unitslant = (origin -- origin shifted (1,1)) enddef ; +draw + unitslant xscaled 5cm yscaled 1cm + withpen pencircle scaled 5mm withcolor .625red ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank]\processMPbuffer\stoplinecorrection + +An even better alternative is: + +\startbuffer +path unitslant ; unitslant = origin -- origin shifted (1,1) ; +draw + unitslant xscaled 5cm yscaled 1cm + withpen pencircle scaled 5mm withcolor .625yellow ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +\stopsection + +\startsection[title={Curve construction}] + +\index{curves} + +\doifmodeelse{screen} + {\def\Xcom{3}\def\Ycom{2}\def\Zcom{\the\textheight}} + {\def\Xcom{2}\def\Ycom{3}\def\Zcom{\the\textwidth }} + +Chapter 3 of the \METAFONT\ book explains the mathematics behind the construction +of curves. Both \METAFONT\ and \METAPOST\ implement B\'ezier curves. The fact +that these curves are named after Pierre B\'ezier obscures the fact that the math +behind them originates with Serge\u{\i} Bernshte\u{\i}n. + +The points on the curve are determined by the following formula: + +\placeformula[-] +\startformula +z(t) = (1-t)^3 z_1 + 3 (1-t)^2 t z_2 + 3 (1-t) t^2 z_3 + t^3 z_4 +\stopformula + +Here, the parameter $t$ runs from $[0,1]$. As you can see, we are dealing with +four points. In practice this means that when we construct a curve from multiple +points, we act on two points and the two control points in between. So, the +segment that goes from $z_1$ to $z_4$ is calculated using these two points and +the points that \METAFONT|/|\METAPOST\ calls post control point and pre control +point. + +\startbuffer[a] +vardef dodrawmidpoints (expr a, b, c, d, n, col, m) = + save e, f, g, h, i, j ; pair e, f, g, h, i, j ; + e := .5[a,b] ; f := .5[b,c] ; g := .5[c,d] ; + h := .5[e,f] ; i := .5[f,g] ; j := .5[h,i] ; + if m= 0 : drawpoints j elseif + m= 1 : draw a--b--c--d elseif + m= 2 : draw e--f--g elseif + m= 3 : draw h--i elseif + m= 4 : draw a--e--h--j elseif + m= 5 : draw j--i--g--d elseif + m=11 : drawpoints a--b--c--d elseif + m=12 : drawpoints e--f--g elseif + m=13 : drawpoints h--i elseif + m=14 : drawpoints a--e--h--j elseif + m=15 : drawpoints j--i--g--d fi withcolor col ; + if n>1 : + dodrawmidpoints(a, e, h, j, n-1, col, m) ; + dodrawmidpoints(j, i, g, d, n-1, col, m) ; + fi ; +enddef ; + +vardef drawmidpoints (expr p, n, col, m) = + save a, b, c, d ; pair a, b, c, d ; + for x=0 upto length(p)-1 : + a := point x of p ; b := postcontrol x of p ; + d := point x+1 of p ; c := precontrol x+1 of p ; + dodrawmidpoints(a,b,c,d,n,col,m) ; + endfor ; +enddef ; +\stopbuffer + +\startbuffer[b] +path p ; p := (4cm,4cm)..(6cm,0cm)..(1cm,2cm) ; +\stopbuffer + +\startbuffer[c] +drawpath p ; +drawcontrollines p withcolor .625yellow ; +drawcontrolpoints p withcolor .625red ; +drawpoints p withcolor .625red ; +freelabel(btex $z_1$ etex, point 0 of p, center p) ; +freelabel(btex $z_2$ etex, postcontrol 0 of p, center p) ; +freelabel(btex $z_3$ etex, precontrol 1 of p, center p) ; +freelabel(btex $z_4$ etex, point 1 of p, center p) ; +freelabel(btex $z_5$ etex, postcontrol 1 of p, center p) ; +freelabel(btex $z_6$ etex, precontrol 2 of p, center p) ; +freelabel(btex $z_7$ etex, point 2 of p, center p) ; +\stopbuffer + +\startbuffer[x] +draw boundingbox p enlarged 1cm ; +setbounds currentpicture to boundingbox p enlarged 1cm ; +currentpicture := currentpicture xsized (.45*\Zcom) ; +\stopbuffer + +\startlinecorrection[blank] +\processMPbuffer[a,b,c,x] +\stoplinecorrection + +The previous curve is constructed from the three points $z_1$, $z_4$ and $z_7$. +The curve is drawn in \METAPOST\ by \type {z1..z4..z7} and is made up out of two +segments. The first segment is determined by the following points: + +\startitemize[packed,n] +\item point $z_1$ of the curve +\item the postcontrol point $z_2$ of $z_1$ +\item the precontrol point $z_3$ of $z_4$ +\item point $z_4$ of the curve +\stopitemize + +On the next pages we will see how the whole curve is constructed from these +quadruples of points. The process comes down to connecting the mid points of the +straight lines to the points mentioned. We do this three times, which is why +these curves are classified as third order approximations. + +The first series of graphics demonstrates the process of determining the mid +points. The third order midpoint is positioned on the final curve. The second +series focuses on the results: new sets of four points that will be used in a +next stage. The last series only shows the third order midpoints. As you can see, +after some six iterations we have already reached a rather good fit of the final +curve. The exact number of iterations depends on the resolution needed. You will +notice that the construction speed (density) differs per segment. + +\startpostponing + +% cc .. hh in order to avoid conflicts with c-... + +\startbuffer[cc] +drawpath p ; drawpoints p ; drawcontrolpoints p ; +\stopbuffer + +\startbuffer[dd] +drawmidpoints(p,1,.625red, 11) ; drawmidpoints(p,1,.625yellow, 1) ; +\stopbuffer + +\startbuffer[ee] +drawmidpoints(p,1,.625red, 12) ; drawmidpoints(p,1,.625yellow, 2) ; +\stopbuffer + +\startbuffer[ff] +drawmidpoints(p,1,.625red, 13) ; drawmidpoints(p,1,.625yellow, 3) ; +\stopbuffer + +\startbuffer[gg] +drawmidpoints(p,1,.625red, 14) ; drawmidpoints(p,1,.625yellow, 4) ; +\stopbuffer + +\startbuffer[hh] +drawmidpoints(p,1,.625red, 15) ; drawmidpoints(p,1,.625yellow, 5) ; +\stopbuffer + +\startbuffer +\startcombination[\Xcom*\Ycom] + {\processMPbuffer[a,b,cc,x]} {points} + {\processMPbuffer[a,b,cc,dd,x]} {first order curve} + {\processMPbuffer[a,b,cc,dd,ee,x]} {second order curve} + {\processMPbuffer[a,b,cc,dd,ee,ff,x]} {third order curve} + {\processMPbuffer[a,b,cc,dd,ee,gg,x]} {left side curves} + {\processMPbuffer[a,b,cc,dd,ee,hh,x]} {right side curves} +\stopcombination +\stopbuffer + +\getbuffer \page + +\startbuffer[dd] +drawmidpoints(p,1,.625red, 11) ; +drawmidpoints(p,1,.625yellow, 1) ; +\stopbuffer + +\startbuffer[ee] +for i=11, 12 : drawmidpoints(p,1,.625red, i) ; endfor ; +drawmidpoints(p,1,.625yellow, 2) ; +\stopbuffer + +\startbuffer[ff] +for i=11, 12, 13 : drawmidpoints(p,1,.625red, i) ; endfor ; +drawmidpoints(p,1,.625yellow, 3) ; +\stopbuffer + +\startbuffer[gg] +for i=11,12,13,14 : drawmidpoints(p,1,.625red, i) ; endfor ; +drawmidpoints(p,1,.625yellow, 4) ; +\stopbuffer + +\startbuffer[hh] +for i=11, 12, 13, 14, 15 : drawmidpoints(p,1,.625red, i) ; endfor ; +drawmidpoints(p,1,.625yellow, 5) ; +\stopbuffer + +\startbuffer +\startcombination[\Xcom*\Ycom] + {\processMPbuffer[a,b,cc,x]} {points} + {\processMPbuffer[a,b,cc,dd,x]} {first order points} + {\processMPbuffer[a,b,cc,ee,x]} {second order points} + {\processMPbuffer[a,b,cc,ff,x]} {third order points} + {\processMPbuffer[a,b,cc,gg,x]} {left side points} + {\processMPbuffer[a,b,cc,hh,x]} {right side points} +\stopcombination +\stopbuffer + +\getbuffer \page + +\startbuffer[cc] +drawpath p ; drawmidpoints (p,1,.625yellow, 0) ; +\stopbuffer + +\startbuffer[dd] +drawpath p ; drawmidpoints (p,2,.625yellow, 0) ; +\stopbuffer + +\startbuffer[ee] +drawpath p ; drawmidpoints (p,3,.625yellow, 0) ; +\stopbuffer + +\startbuffer[ff] +drawpath p ; drawmidpoints (p,4,.625yellow, 0) ; +\stopbuffer + +\startbuffer[gg] +drawpath p ; drawmidpoints (p,5,.625yellow, 0) ; +\stopbuffer + +\startbuffer[hh] +drawpath p ; drawmidpoints (p,6,.625yellow, 0) ; +\stopbuffer + +\startbuffer +\startcombination[\Xcom*\Ycom] + {\processMPbuffer[a,b,cc,x]} {first iteration} + {\processMPbuffer[a,b,cc,dd,x]} {second iteration} + {\processMPbuffer[a,b,cc,dd,ee,x]} {third iteration} + {\processMPbuffer[a,b,cc,dd,ee,ff,x]} {fourth iteration} + {\processMPbuffer[a,b,cc,dd,ee,ff,gg,x]} {fifth iteration} + {\processMPbuffer[a,b,cc,dd,ee,ff,gg,hh,x]} {sixths iteration} +\stopcombination +\stopbuffer + +\getbuffer \page + +\stoppostponing + +% here we pick up the thread, if we would not flush the +% pages before the next text, the reader could become +% confused + +The path in these examples is defined as follows: + +\typebuffer[b] + +If you are playing with graphics like this, the \METAFUN\ macro \type {randomize} +may come in handy: + +\startbuffer[bb] +p := p randomized (1cm,.5cm) ; +\stopbuffer + +\typebuffer[bb] + +If we apply this operation a couple of times we can see how the (control) points +vary. (Using the randomizer saves us the troubles of finding nice example +values.) The angle between the tangent as well as the distance from the parent +point determine the curve. + +\startbuffer[xx] +currentpicture := currentpicture scaled .5 ; +\stopbuffer + +\startlinecorrection[blank] +\hbox to \hsize + {\processMPbuffer[a,b,bb,c,x,xx]\hss + \processMPbuffer[a,b,bb,c,x,xx]\hss + \processMPbuffer[a,b,bb,c,x,xx]\hss + \processMPbuffer[a,b,bb,c,x,xx]} +\stoplinecorrection + +% new thread + +Just in case you are interested in how such graphical simulations can be +organized, we show simplified versions of the macros used here. (In the previous +examples we minimized the complexity of the code by using buffers, but describing +this mechanism is out of the scope of this section.) + +\startbuffer[demo] +vardef dodrawmidpoints (expr a, b, c, d, n) = + save e, f, g, h, i, j ; pair e, f, g, h, i, j ; + e := .5[a,b] ; f := .5[b,c] ; g := .5[c,d] ; + h := .5[e,f] ; i := .5[f,g] ; j := .5[h,i] ; + draw j ; + if n>1 : + dodrawmidpoints(a, e, h, j, n-1) ; + dodrawmidpoints(j, i, g, d, n-1) ; + fi ; +enddef ; + +vardef drawmidpoints (expr p, n) = + save a, b, c, d ; pair a, b, c, d ; + for x=0 upto length(p)-1 : + a := point x of p ; b := postcontrol x of p ; + d := point x+1 of p ; c := precontrol x+1 of p ; + dodrawmidpoints(a, b, c, d, n) ; + endfor ; +enddef ; +\stopbuffer + +We need to loop over all segments of a curve, where for each segment the left and +right side sub curves are handled recursively, upto the requested depth (denoted +as \type {n}). For this we define the following macros. + +\typebuffer[demo] + +\startbuffer[zero] +drawoptions (withpen pencircle scaled 5pt withcolor .625red); +\stopbuffer + +\startbuffer[extra] +drawoptions (withpen pencircle scaled 5pt withcolor .625yellow); +\stopbuffer + +We apply this macro to a simple shape: + +\startbuffer[one] +drawmidpoints (fullcircle xscaled 300pt yscaled 50pt, 1) ; +\stopbuffer + +\typebuffer[one] + +When drawn, this results in the points that makes up the +curve: + +\startlinecorrection[blank] +\processMPbuffer[demo,zero,one] +\stoplinecorrection + +We now add an extra iteration (resulting in the yellow points): + +\startbuffer[two] +drawmidpoints (fullcircle xscaled 300pt yscaled 50pt, 2) ; +\stopbuffer + +\typebuffer[two] + +and get: + +\startlinecorrection[blank] +\processMPbuffer[demo,zero,two,extra,one] +\stoplinecorrection + +We don't even need that much iterations to get a good result. The depth needed to +get a good result depends on the size of the pen and the resolution of the device +on which the curve is visualized. + +\startbuffer[zero] +drawoptions (withpen pencircle scaled 2pt withcolor .625red) ; +\stopbuffer + +\startbuffer[three] +for i=1 upto 7 : + drawmidpoints (fullcircle + xscaled (300pt+i*10pt) yscaled (50pt+i*10pt), i) ; +endfor ; +\stopbuffer + +\typebuffer[three] + +Here we show 7 iterations in one graphic. + +\startlinecorrection[blank] +\processMPbuffer[demo,zero,three] +\stoplinecorrection + +In practice it is not that trivial to determine the depth needed. The next +example demonstrates how the resolution of the result depends on the length and +nature of the segment. + +\startbuffer[four] +drawmidpoints (fullsquare + xscaled 300pt yscaled 50pt randomized (20pt,10pt), 5) ; +\stopbuffer + +\typebuffer[four] + +\startlinecorrection[blank] +\processMPbuffer[demo,zero,four] +\stoplinecorrection + +\stopsection + +\startsection[title={Inflection, tension and curl}] + +\index{inflection} +\index{tension} +\index{curl} + +The \METAPOST\ manual describes the meaning of \type {...} as \quotation {choose +an inflection||free path between these points unless the endpoint directions make +this impossible}. To use the words of David Arnold: a point of inflection is +where a path switches concavity, from concave up to concave down, for example. + +It is surprisingly difficult to find nice examples that demonstrate the +difference between \type {..} and \type {...}, as it is often \quote {impossible} +to honour the request for less inflection. We will demonstrate this with a few +graphics. + +In the four figures on the next pages, you will see that \type {...} is not +really suited for taming wild curves. If you really want to make sure that a +curve stays within certain bounds, you have to specify it as such using control +or intermediate points. In the figures that follow, the gray curves draw the +random path using \type {..} on top of yellow curves that use the \type {...} +connection. As you can see, in only a few occasions do the yellow \quote +{inflection} free curves show up. + +For those who asked for the code that produces these pictures, we now include it +here. We use a macro \type {sample} which we define as a usable graphic (nearly +all examples in this manual are coded in the document source). + +\startbuffer +\startuseMPgraphic{sample} +def sample (expr rx, ry) = + path p, q ; numeric n, m, r, a, b ; + color c ; c := \MPcolor{lightgray} ; + a := 3mm ; b := 2mm ; r := 2cm ; n := 7 ; m := 5 ; + q := unitsquare scaled r xyscaled (n,m) shifted (.5r,.5r) ; + draw q withpen pencircle scaled (b/4) withcolor .625yellow; + for i=1 upto n : for j=1 upto m : + p := (fullcircle scaled r randomized (r/rx,r/ry)) + shifted ((i,j) scaled r) ; + pickup pencircle scaled a ; + draw for k=0 upto length(p) : + point k of p .. endfor cycle withcolor c ; + draw for k=0 upto length(p) : + point k of p ... endfor cycle withcolor c ; + pickup pencircle scaled b ; + draw for k=0 upto length(p) : + point k of p .. endfor cycle withcolor .625yellow ; + draw for k=0 upto length(p) : + point k of p ... endfor cycle withcolor .625white ; + for k=0 upto length(p) : + draw point k of p withcolor .625red ; + endfor ; + endfor ; endfor ; + setbounds currentpicture to q ; +enddef ; +\stopuseMPgraphic +\stopbuffer + +\typebuffer \getbuffer + +As you see, not so much code is needed. The graphics themselves were produced +with a couple of commands like: + +\startbuffer +\placefigure + {Circles with minimized inflection and 25\% randomized points.} + {\startMPcode + \includeMPgraphic{sample} ; sample(4,4) ; + \stopMPcode} +\stopbuffer + +\typebuffer + +\startpostponing + +\placefigure + {Circles with minimized inflection and 25\% randomized points.} + {\startMPcode\includeMPgraphic{sample} ; sample(4,4) ; \stopMPcode} + +\placefigure + {Circles with minimized inflection and 33\% randomized points.} + {\startMPcode\includeMPgraphic{sample} ; sample(3,3) ; \stopMPcode} + +\page + +\placefigure + {Circles with minimized inflection and 50\% randomized points.} + {\startMPcode\includeMPgraphic{sample} ; sample(2,2) ; \stopMPcode} + +\placefigure + {Circles with minimized inflection and 100\% randomized points.} + {\startMPcode\includeMPgraphic{sample} ; sample(1,1) ; \stopMPcode} + +\page + +\stoppostponing + +The tension specifier can be used to influence the curvature. To quote the +\METAPOST\ manual once more: \quotation {The tension parameter can be less than +one, but it must be at least $3/4$}. The following paths are the same: + +\starttyping +z1 .. z2 +z1 .. tension 1 .. z2 +z1 .. tension 1 and 1 .. z2 +\stoptyping + +The triple dot command \type {...} is actually a macro that makes the following +commands equivalent. Both commands will draw identical paths. + +\starttyping +z1 ... z2 +z1 .. tension atleast 1 .. z2 +\stoptyping + +The \type {atleast} directive tells \METAPOST\ to do some magic behind the +screens. Both the $3/4$ and the \type {atleast} lead directly to the question: +\quotation {What, exactly, is the influence of the tension directive?} We will +try to demystify the \type {tension} specifier through a sequence of graphics. + +\startbuffer +u := 1cm ; z1 = (0,0) ; z2 = (2u,4u) ; z3 = (4u,0) ; +def sample (expr p, c) = + draw p withpen pencircle scaled 2.5mm withcolor white ; + draw p withpen pencircle scaled 2.0mm withcolor c ; +enddef ; +for i=.75 step .05 until 1 : + sample (z1 .. tension i .. z2 .. z3, .625red) ; +endfor ; +for i=1 step .05 until 2 : + sample (z1 .. tension i .. z2 .. z3, .625yellow) ; +endfor ; +sample (z1 .. z2 .. z3, .625white) ; +sample (z1 ... z2 ... z3, .625white) ; +\stopbuffer + +\typebuffer + +Indeed values less than .75 give an error message, but large values are okay. As +you can see, the two gray curves are the same. Here, \type {atleast 1} means~1, +even if larger values are useful. + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +\startbuffer +u := 1cm ; z1 = (0,0) ; z2 = (2u,4u) ; z3 = (4u,0) ; +def sample (expr p, c) = + draw p withpen pencircle scaled 2.5mm withcolor white ; + draw p withpen pencircle scaled 2.0mm withcolor c ; +enddef ; +for i=.75 step .05 until 1 : + sample (z1 .. tension i and 2i .. z2 .. z3, .625red) ; +endfor ; +for i=1 step .05 until 2 : + sample (z1 .. tension i and 2i .. z2 .. z3, .625yellow) ; +endfor ; +sample (z1 .. z2 .. z3, .625white) ; +sample (z1 ... z2 ... z3, .625white) ; +\stopbuffer + +Curves finally are made up out of points, and each point has two control points. +Since the \type {tension} specifier finally becomes a control point, it is not +surprising that you may specify two tension values. If we replace the tension in +the previous example by + +\starttyping +.. tension i and 2i .. +\stoptyping + +we get the following graphic: + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +\startbuffer +u := 1cm ; z1 = (0,0) ; z2 = (2u,4u) ; z3 = (4u,0) ; +def sample (expr p, c) = + draw p withpen pencircle scaled 2.5mm withcolor white ; + draw p withpen pencircle scaled 2.0mm withcolor c ; +enddef ; +for i=.75 step .05 until 1 : + sample (z1 .. tension 2i and i .. z2 .. z3, .625red) ; +endfor ; +for i=1 step .05 until 2 : + sample (z1 .. tension 2i and i .. z2 .. z3, .625yellow) ; +endfor ; +sample (z1 .. z2 .. z3, .625white) ; +sample (z1 ... z2 ... z3, .625white) ; +\stopbuffer + +If we swap both values (\type {.. tension 2i and i ..}) we get: + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +\startbuffer[a] +u := 1cm ; z1 = (0,0) ; z2 = (2u,4u) ; z3 = (4u,0) ; +def sample (expr p, c) = + drawpath p withpen pencircle scaled 2.5mm withcolor c ; + drawcontrollines p withcolor c ; + drawpoints p ; + drawcontrolpoints p ; +enddef ; +\stopbuffer + +We mentioned control points. We will now draw a few extreme tensions and show the +control points as \METAPOST\ calculates them. + +\startbuffer[b] +sample (z1 .. tension 0.75 .. z2 .. z3, .625red) ; +sample (z1 .. tension 2.00 .. z2 .. z3, .625yellow) ; +sample (z1 .. z2 .. z3, .625white) ; +\stopbuffer + +\typebuffer[b] + +First we will show the symmetrical tensions. + +\startlinecorrection[blank] +\processMPbuffer[a,b] +\stoplinecorrection + +The asymetrical tensions are less prominent. We use the following values: + +\startbuffer[b] +sample (z1 .. tension .75 and 10 .. z2 .. z3, .625red) ; +sample (z1 .. tension 10 and .75 .. z2 .. z3, .625yellow) ; +sample (z1 .. z2 .. z3, .625white) ; +\stopbuffer + +\typebuffer[b] + +\startlinecorrection[blank] +\processMPbuffer[a,b] +\stoplinecorrection + +What happens when you use the \METAPOST\ maximum value of \type {infinity} +instead of 10? Playing with this kind of graphic can be fun, especially when we +apply a few tricks. + +\startbuffer +def sample (expr p, c) = + draw p withpen pencircle scaled 2.5mm withcolor white ; + draw p withpen pencircle scaled 2.0mm withcolor c ; +enddef; + +u := 1cm ; z1 = (0,0) ; z2 = (2u,4u) ; z3 = (4u,0) ; + +for i=0 step .05 until 1 : + sample(z1 .. tension (.75+i) .. z2 .. z3, i[.625red,.625yellow]) ; +endfor; +\stopbuffer + +\typebuffer + +Here we change the color along with the tension. This clearly demonstrates that +we're dealing with a non linear phenomena. + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +We can (misuse) transparant colors to illustrate how the effect becomes less with +growing tension. + +\startbuffer +def sample (expr p) (text c)= + draw p withpen pencircle scaled 2.0mm withcolor c ; +enddef; + +u := 1cm ; z1 = (0,0) ; z2 = (2u,4u) ; z3 = (4u,0) ; + +for i=0 step .05 until 1 : + sample(z1 .. tension (.75+i) .. z2 .. z3, transparent(1,1-i,.625red)) ; +endfor; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +A third magic directive is \type {curl}. The curl is attached to a point between +\type {{ }}, like \type {{curl 2}}. Anything between curly braces is a direction +specifier, so instead of a \type {curl} you may specify a vector, like \type +{{(2,3)}}, a pair of numbers, as in \type {{2,3}}, or a direction, like \type +{{dir 30}}. Because vectors and angles are straightforward, we will focus a bit +on \type {curl}. + +\starttyping +z0 .. z1 .. z2 +z0 {curl 1} .. z1 .. {curl 1} z2 +\stoptyping + +So, a \type {curl} of~1 is the default. When set to~1, the begin and|/|or end +points are approached. Given the following definitions: + +\startbuffer[a] +u := 1cm ; z1 = (0,0) ; z2 = (2u,4u) ; z3 = (4u,0) ; +def sample (expr p, c) = + draw p withpen pencircle scaled 2.5mm withcolor white ; + draw p withpen pencircle scaled 2.0mm withcolor c ; +enddef ; +\stopbuffer + +\typebuffer[a] + +We can draw three curved paths. + +\startbuffer[b] +sample (z1 {curl 0} .. z2 .. {curl 0} z3, .625red) ; +sample (z1 {curl 2} .. z2 .. {curl 2} z3, .625yellow) ; +sample (z1 {curl 1} .. z2 .. {curl 1} z3, .625white) ; +\stopbuffer + +\typebuffer[b] + +The third (gray) curve is the default situation, so we could have left the \type +{curl} specifier out of the expression. + +\startlinecorrection[blank] +\processMPbuffer[a,b] +\stoplinecorrection + +\startbuffer[b] +sample (z1 {curl 0} .. z2 .. {curl 0} z3, .625red) ; +sample (z1 {curl infinity} .. z2 .. {curl infinity} z3, .625yellow) ; +sample (z1 {curl 1} .. z2 .. {curl 1} z3, .625white) ; +\stopbuffer + +The curly specs have a lower bound of zero and no upper bound. When we use +\METAPOST\ maximum value of \type {infinity} instead of~2, we get: + +\startlinecorrection[blank] +\processMPbuffer[a,b] +\stoplinecorrection + +These curves were defined as: + +\typebuffer[b] + +It may sound strange, but internally \METAPOST\ can handle +larger values than \type {infinity}. + +\startbuffer[b] +sample (z1 {curl infinity} .. z2 .. {curl infinity} z3, .625red) ; +sample (z1 {curl 4infinity} .. z2 .. {curl 4infinity} z3, .625yellow) ; +sample (z1 {curl 8infinity} .. z2 .. {curl 8infinity} z3, .625white) ; +\stopbuffer + +\typebuffer[b] + +Although this is quite certainly undefined behaviour, interesting effects can be +achieved. When you turn off \METAPOST's first stage overflow catcher by setting +\type {warningcheck} to zero, you can go upto 8 times \type {infinity}, which, +being some $2^{15}$, is still far from what today's infinity is supposed to be. + +\startlinecorrection[blank] +\processMPbuffer[a,b] +\stoplinecorrection + +As the built||in \METAPOST\ command \type {..} accepts the \type {curl} and \type +{tension} directives as described in this section, you will now probably +understand the following plain \METAPOST\ definitions: + +\starttyping +def -- = {curl 1} .. {curl 1} enddef ; +def --- = .. tension infinity .. enddef ; +def ... = .. tension atleast 1 .. enddef ; +\stoptyping + +These definitions also point out why you cannot add directives to the left or +right side of \type {--}, \type {---} and \type {...}: they are directives +themselves! + +\stopsection + +\startsection[title={Transformations}] + +\index{transformations} + +A \type {transform} is a vector that is used in what is called an affine +transformation. To quote the \METAPOST\ manual: + +\startquotation +If $p=(p_x,p_y)$ is a pair and $T$ is a transform, then +\type {p transform T} is a pair of the form: + +\startformula +(t_x + t_{xx} p_x + t_{xy} p_y, t_y + t_{yx} p_x + t_{yy} p_y) +\stopformula + +where the six numeric quantities $(t_x, t_y, t_{xx}, t_{xy}, +t_{yx}, t_{yy})$ determine T. +\stopquotation + +In literature concerning \POSTSCRIPT\ and \PDF\ you will find many references to +such transformation matrices. A matrix of $(s_x,0,0,s_y,0,0)$ is scaling by $s_x$ +in the horizontal direction and $s_y$ in the vertical direction, while +$(1,0,t_x,1,0,t_y)$ is a shift over $t_x,t_y$. Of course combinations are also +possible. + +Although these descriptions seem in conflict with each other in the nature and +order of the transform components in the vectors, the concepts are the same. You +normally populate transformation matrices using \type {scaled}, \type {shifted}, +\type {rotated}. + +\starttyping +transform t ; t := identity shifted (a,b) rotated c scaled d ; +path p ; p := fullcircle transformed t ; +\stoptyping + +The previous lines of code are equivalent to: + +\starttyping +path p ; p := fullcircle shifted (a,b) rotated c scaled d ; +\stoptyping + +You always need a starting point, in this case the identity matrix \type +{identity}: $(0,0,1,0,0,1)$. By the way, in \POSTSCRIPT\ the zero vector is +$(1,0,0,1,0,0)$. So, unless you want to extract the components using \type +{xpart}, \type {xypart}, \type {xxpart}, \type {ypart}, \type {yxpart} and|/|or \ +\type {yypart}, you may as well forget about the internal representation. + +You can invert a transformation using the \type {inverse} macro, which is defined +as follows, using an equation: + +\starttyping +vardef inverse primary T = + transform T_ ; T_ transformed T = identity ; T_ +enddef ; +\stoptyping + +Using transform matrices makes sense when similar transformations need to be +applied on many paths, pictures, pens, or other transforms. However, in most +cases you will use the predefined commands \type {scaled}, \type {shifted}, \type +{rotated} and alike. We will now demonstrate the most common transformations in a +text example. + +\startbuffer[a] +draw btex \bfd MetaFun etex ; +draw boundingbox currentpicture withcolor .625yellow ; +\stopbuffer + +\typebuffer[a] + +Before an independent \METAPOST\ run, the \typ {btex ... etex}'s are filtered +from the file and passed on to \TEX. After that, the \DVI\ file is converted to a +list of pictures, which is consulted by \METAPOST. This is no longer the case in +\LUATEX\ where we use \MPLIB, so users don't have to worry about these issues: +just ignore what is mentioned in the official \METAPOST\ manual. + +We can manipulate the pictures representing text like any graphic as well as draw +it with \type {draw}. + +\startlinecorrection[blank] +\processMPbuffer[a] +\stoplinecorrection + +We show the transformations in relation to the origin and make the origin stand +out a bit more by painting it a bit larger in white first. + +\startbuffer[c] +draw origin withpen pencircle scaled 1.5mm withcolor white ; +draw origin withpen pencircle scaled 1mm withcolor .625red +\stopbuffer + +\typebuffer[c] + +The origin is in the lower left corner of the picture. + +\startlinecorrection[blank] +\processMPbuffer[a,c] +\stoplinecorrection + +Because the transformation keywords are proper english, we let the pictures speak +for themselves. + +% shifted + +\startbuffer[b] +currentpicture := currentpicture shifted (0,-1cm) ; +\stopbuffer + +\page[preference] \typebuffer[b] \page[no] + +\startlinecorrection[blank] +\processMPbuffer[a,b,c] +\stoplinecorrection + +% rotated + +\startbuffer[b] +currentpicture := currentpicture rotated 180 ; +\stopbuffer + +\page[preference] \typebuffer[b] \page[no] + +\startlinecorrection[blank] +\processMPbuffer[a,b,c] +\stoplinecorrection + +% rotatedaround + +\startbuffer[b] +currentpicture := currentpicture rotatedaround(origin,30) ; +\stopbuffer + +\page[preference] \typebuffer[b] \page[no] + +\startlinecorrection[blank] +\processMPbuffer[a,b,c] +\stoplinecorrection + +% scaled + +\startbuffer[b] +currentpicture := currentpicture scaled 1.75 ; +\stopbuffer + +\page[preference] \typebuffer[b] \page[no] + +\startlinecorrection[blank] +\processMPbuffer[a,b,c] +\stoplinecorrection + +% scaled + +\startbuffer[b] +currentpicture := currentpicture scaled -1 ; +\stopbuffer + +\page[preference] \typebuffer[b] \page[no] + +\startlinecorrection[blank] +\processMPbuffer[a,b,c] +\stoplinecorrection + +% xscaled + +\startbuffer[b] +currentpicture := currentpicture xscaled 3.50 ; +\stopbuffer + +\page[preference] \typebuffer[b] \page[no] + +\startlinecorrection[blank] +\processMPbuffer[a,b,c] +\stoplinecorrection + +% xscaled + +\startbuffer[b] +currentpicture := currentpicture xscaled -1 ; +\stopbuffer + +\page[preference] \typebuffer[b] \page[no] + +\startlinecorrection[blank] +\processMPbuffer[a,b,c] +\stoplinecorrection + +% yscaled + +\startbuffer[b] +currentpicture := currentpicture yscaled .5 ; +\stopbuffer + +\page[preference] \typebuffer[b] \page[no] + +\startlinecorrection[blank] +\processMPbuffer[a,b,c] +\stoplinecorrection + +% yscaled + +\startbuffer[b] +currentpicture := currentpicture yscaled -1 ; +\stopbuffer + +\page[preference] \typebuffer[b] \page[no] + +\startlinecorrection[blank] +\processMPbuffer[a,b,c] +\stoplinecorrection + +% slanted + +\startbuffer[b] +currentpicture := currentpicture slanted .5 ; +\stopbuffer + +\page[preference] \typebuffer[b] \page[no] + +\startlinecorrection[blank] +\processMPbuffer[a,b,c] +\stoplinecorrection + +% slanted + +\startbuffer[b] +currentpicture := currentpicture slanted -.5 ; +\stopbuffer + +\page[preference] \typebuffer[b] \page[no] + +\startlinecorrection[blank] +\processMPbuffer[a,b,c] +\stoplinecorrection + +% zscaled + +\startbuffer[b] +currentpicture := currentpicture zscaled (.75,.25) ; +\stopbuffer + +\page[preference] \typebuffer[b] \page[no] + +\startlinecorrection[blank] +\processMPbuffer[a,b,c] +\stoplinecorrection + +% reflectedabout + +\startbuffer[b] +currentpicture := currentpicture + reflectedabout(llcorner currentpicture,urcorner currentpicture) ; +\stopbuffer + +\page[preference] \typebuffer[b] \page[no] + +\startlinecorrection[blank] +\processMPbuffer[a,b,c] +\stoplinecorrection + +% reverse counterclockwise turningnumber + +A path has a certain direction. When the \type {turningnumber} of a path is +larger than zero, it runs in clockwise direction. The \METAPOST\ primitive \type +{reverse} changes the direction, while the macro \type {counterclockwise} can be +used to get a path running in a well defined direction. + +\startbuffer +drawoptions(withpen pencircle scaled 2pt withcolor .625red) ; +path p ; p := fullcircle scaled 1cm ; +drawarrow p ; +drawarrow reverse p shifted (2cm,0) ; +drawarrow counterclockwise p shifted (4cm,0) ; +drawarrow counterclockwise reverse p shifted (6cm,0) ; +drawarrow reverse counterclockwise p shifted (8cm,0) ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +\stopsection + +\startsection[title={Only this far}] + +When you take a close look at the definitions of the Computer Modern Roman fonts, +defined in the \METAFONT\ book, you will notice a high level of abstraction. +Instead of hard coded points you will find points defined in terms of \quote +{being the same as this point} or \quote {touching that point}. In this section +we will spend some time on this touchy aspect. + +\startbuffer[a] +pickup pencircle scaled 2mm ; +path p ; p := fullsquare scaled 2cm ; +draw p withcolor .625white ; +\stopbuffer + +\startlinecorrection[blank] +\processMPbuffer[a] +\stoplinecorrection + +This rectangle is a scaled instance of the predefined \METAFUN\ path \type +{fullsquare} which is centered around the origin. + +\typebuffer[a] + +On this path, halfway between two of its corners, we define a point \type {q}: + +\startbuffer[b] +pair q ; q := .5[llcorner p, lrcorner p] ; +\stopbuffer + +\typebuffer[b] + +We draw this point in red, using: + +\startbuffer[c] +draw q withcolor .625red ; +\stopbuffer + +\typebuffer[c] + +As you can see, this point is drawn on top of the path. + +\startlinecorrection[blank] +\processMPbuffer[a,b,c] +\stoplinecorrection + +There are four of those midpoints, and when we connect them, we get: + +\startbuffer[c] +draw q -- q rotated 90 -- q rotated 180 -- + q rotated 270 -- cycle withcolor .625red ; +\stopbuffer + +\startlinecorrection[blank] +\processMPbuffer[a,b,c] +\stoplinecorrection + +Because path \type {p} is centered around the origin, we can simply rotate point +\type {q} a few times. + +\typebuffer[c] + +There are situations, where you don't want the red path to be drawn inside +another path, or more general: where you want points to touch instead of being +overlayed. + +\startlinecorrection[blank] +\processMPbuffer[a,b,c] +\stoplinecorrection + +We can achieve this by defining point \type {q} to be located on top of the +midpoint. + +\startbuffer[b] +pair q ; q := top .5[llcorner p, lrcorner p] ; +\stopbuffer + +\typebuffer[b] + +The predefined macro \type {top} moves the point over the distance similar to the +current pen width. + +\startlinecorrection[blank] +\processMPbuffer[a,b,c] +\stoplinecorrection + +Because we are dealing with two drawing operations, and since the path inside is +drawn through the center of points, we need to repeat this move in order to draw +the red path really inside the other one. + +\startbuffer[b] +pair q ; q := top top .5[llcorner p, lrcorner p] ; +\stopbuffer + +\typebuffer[b] + +Operations like \type {top} and its relatives \type {bot}, \type {lft} and \type +{rt} can be applied sequentally. + +\startlinecorrection[blank] +\processMPbuffer[a,b,c] +\stoplinecorrection + +We already showed that \type {q} was defined as a series of rotations. + +\typebuffer[c] + +As an intermezzo we will show an alternative definition of \type {q}. Because +each point is rotated 90 degrees more, we can define a macro that expands into +the point and rotates afterwards. Because each consecutive point on the path is +rotated an additional 90 degrees, we use the \METAPOST\ macro \type {hide} to +isolate the assignment. The \type {hide} command executes the hidden command and +afterwards continues as if it were never there. You must not confuse this with +grouping, since the hidden commands are visible to its surroundings. + +\startbuffer[c] +def qq = q hide(q := q rotated 90) enddef ; +draw qq -- qq -- qq -- qq -- cycle withcolor .625red ; +\stopbuffer + +\typebuffer[c] + +The macro \type {top} uses the characteristics of the current pen to determine +the displacement. However, for the more complicated pen shapes we need a +different trick to get an inside path. Let's start by defining an elliptical +path. + +\startbuffer[a] +pickup pencircle xscaled 3mm yscaled 5mm rotated 30 ; +path p ; p := fullcircle xscaled 6cm yscaled 3cm ; +draw p withcolor .625white ; +\stopbuffer + +\typebuffer[a] + +We draw this path using a non standard pen. In the \METAFONT\ manual you will +find methods to draw shapes with similar pens, where the pen is also turning, as +it does in real calligraphy. Here we stick to a more simple one. + +\startlinecorrection[blank] +\processMPbuffer[a] +\stoplinecorrection + +We construct the inner path from the points that make up the curve. Watch how we +use a for loop to compose the new path. When used this way, no semi colon may be +used to end the loop, since it would isolate the color directive. + +\startbuffer[b] +draw point 0 of p + for i=1 upto length(p) : -- point (i) of p endfor + withcolor .625red ; +\stopbuffer + +\typebuffer[b] + +The points are still located on the original path. + +\startlinecorrection[blank] +\processMPbuffer[a,b] +\stoplinecorrection + +We can move the points to the inside by shifting them over the penwidth in the +direction perpendicular to the point. Because we use this transformation more +than once, we wrap it into a macro. This also keeps the code readable. + +\startbuffer[b] +vardef inside expr pnt of p = + (point pnt of p shifted + -(penoffset direction pnt of p of currentpen)) +enddef ; +draw inside 0 of p + for i=1 upto length(p) : -- inside i of p endfor + withcolor .625red ; +\stopbuffer + +\typebuffer[b] + +Whenever you define a pen, \METAPOST\ stores its characteristics in some private +variables which are used in the \type {top} and alike directives. The \type +{penoffset} is a built in primitive and is defined as the \quotation {point on +the pen furthest to the right of the given direction}. Deep down in \METAPOST\ +pens are actually simple paths and therefore \METAPOST\ has a notion of a point +on the penpath. In the \METAFONT\ book and \METAPOST\ manual you can find in +depth discussions on pens. + +\startlinecorrection[blank] +\processMPbuffer[a,b] +\stoplinecorrection + +We're still not there. Like in a previous example, we need to shift over twice +the pen width. To get good results, we should determine the width of the pen at +that particular point, which is not trivial. The more general solution, which +permits us to specify the amount of shifting, is as follows. + +\startbuffer[b] +vardef penpoint expr pnt of p = + save n, d ; numeric n, d ; + (n,d) = if pair pnt : pnt else : (pnt,1) fi ; + (point n of p shifted + ((penoffset direction n of p of currentpen) scaled d)) +enddef ; +\stopbuffer + +\typebuffer[b] + +When the point specification is extended with a distance, in which case we have a +pair expression, the point and distance are derived from this specification. +First we demonstrate the simple case: + +\startbuffer[c] +draw penpoint 0 of p + for i=1 upto length(p)-1 : .. penpoint i of p endfor .. cycle + withcolor .625red ; +\stopbuffer + +\typebuffer[c] + +\startlinecorrection[blank] +\processMPbuffer[a,b,c] +\stoplinecorrection + +In the next graphic, we draw both an inner and and outer path. + +\startbuffer[c] +draw penpoint (0,-2) of p + for i=1 upto length(p)-1 : .. penpoint (i,-2) of p endfor .. cycle + withcolor .625red ; +draw penpoint (0,+2) of p + for i=1 upto length(p)-1 : .. penpoint (i,+2) of p endfor .. cycle + withcolor .625yellow ; +\stopbuffer + +\typebuffer[c] + +\startlinecorrection[blank] +\processMPbuffer[a,b,c] +\stoplinecorrection + +\startbuffer[a] +path p, q, r ; + +p := fullcircle scaled 3cm ; +q := p shifted (7cm,0cm) ; +r := center p -- center q ; +\stopbuffer + +\startbuffer[b] +pair pr, qr ; + +pr := p intersectionpoint r ; +qr := q intersectionpoint r ; + +r := r cutbefore pr cutafter qr ; +\stopbuffer + +\startbuffer[c] +r := r cutbefore (point 5pt on r) ; +r := r cutafter (point -5pt on r) ; +\stopbuffer + +\startbuffer[cc] +r := r cutends 5pt ; +\stopbuffer + +\startbuffer[d] +draw p withpen pencircle scaled 10pt withcolor .625red ; +draw q withpen pencircle scaled 10pt withcolor .625yellow ; +draw r withpen pencircle scaled 20pt withcolor .625white ; +\stopbuffer + +\startbuffer[dd] +draw r withpen pencircle scaled 20pt withcolor .625white ; +draw p withpen pencircle scaled 10pt withcolor .625red ; +draw q withpen pencircle scaled 10pt withcolor .625yellow ; +\stopbuffer + +Another case when \type {top} and friends cannot be applied in a general way is +the following. Consider the three paths: + +\typebuffer[a] + +We draw these paths with: + +\typebuffer[d] + +The line is drawn from center to center and since the line has a non zero width +and a round line cap, it extends beyond this point. + +\startlinecorrection[blank] +\processMPbuffer[a,d] +\stoplinecorrection + +If we want the line to stop at the circular paths, we can cut off the pieces that +extend beyond those paths. + +\typebuffer[b] + +This time we get: + +\startlinecorrection[blank] +\processMPbuffer[a,b,d] +\stoplinecorrection + +Due to the thicker line width used when drawing the straight line, part of that +line is still visible inside the circles. So, we need to clip off a bit more. + +\typebuffer[c] + +The \type {point ... on} operation is a \METAFUN\ macro that takes a dimension. + +\startlinecorrection[blank] +\processMPbuffer[a,b,c,d] +\stoplinecorrection + +In order to save you some typing, \METAFUN\ provides a macro \type {cutends} that +does the same job: + +\typebuffer[cc] + +This time we draw the path in a different order: + +\typebuffer[dd] + +That way we hide the still remaining overlapping part of the line. + +\startlinecorrection[blank] +\processMPbuffer[a,b,cc,dd] +\stoplinecorrection + +\stopsection + +\startsection[title={Directions}] + +\index{directions} + +Quite often you have to tell \METAPOST\ in what direction a line should be drawn. +A direction is specified as a vector. There are four predefined vectors: \type +{up}, \type {down}, \type {left}, \type {right}. These are defined as follows: + +\starttyping +pair up, down, left, right ; +up = -down = (0,1) ; right = -left = (1,0) ; +\stoptyping + +We can use these predefined pairs as specifications and in calculations. + +\startbuffer +dotlabel.top("up" , up * 1cm) ; +dotlabel.bot("down" , down * 1cm) ; +dotlabel.lft("left" , left * 1cm) ; +dotlabel.rt ("right", right * 1cm) ; + +drawoptions (withpen pencircle scaled .25mm withcolor .625 red) ; + +drawarrow origin -- up * 1cm ; +drawarrow origin -- down * 1cm ; +drawarrow origin -- left * 1cm ; +drawarrow origin -- right * 1cm ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +This graphic can also be defined in a more efficient (but probably more cryptic) +way. The next definition demonstrates a few nice tricks. Instead of looping over +the four directions, we loop over their names. Inside the loop we convert these +names, or strings, into a pair by scanning the string using \type {scantokens}. +The \type {freedotlabel} macro is part of \METAFUN\ and takes three arguments: a +label string (or alternatively a picture), a point (location), and the \quote +{center of gravity}. The label is positioned in the direction opposite to this +center of gravity. + +\startbuffer +pair destination ; +for whereto = "up", "down", "left", "right" : + destination := scantokens(whereto) * 1cm ; + freedotlabel(whereto, destination, origin) ; + drawarrow origin -- destination + withpen pencircle scaled .25mm withcolor .625 red ; +endfor ; +\stopbuffer + +\typebuffer + +So, in this code fragment, we use the string as string and (by means of \type +{scantokens}) as a point or vector. + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +The previous definition is a stepping stone to the next one. This time we don't +use points, but the \type {dir} command. This command converts an angle into an +unitvector. + +\startbuffer +pair destination ; +for whereto = 0 step 30 until 330 : + destination := dir(whereto) * 1.5cm ; + freedotlabel(decimal whereto, destination, origin) ; + drawarrow origin -- destination + withpen pencircle scaled .25mm withcolor .625 red ; +endfor ; +\stopbuffer + +\typebuffer + +In \METAPOST\ the angles go counter clockwise, which is not that illogical if you +look at it from the point of view of vector algebra. + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +\stopsection + +\startsection[title={Analyzing pictures}] + +\index{pictures+analyzing} + +{\em Unless you really want to know all details, you can safely skip this +section. The \METAPOST\ features discussed here are mainly of importance when you +write (advanced) macros.} + +% Later we will discuss in detail how you can use either \METAPOST\ or \TEX\ to +% typeset text (\in {section} [sec:text] and \in {chapter} [sec:typesetting]), so +% here we limit our exploration to a quick introduction. The most direct way of +% processing text in \METAPOST\ is using the \type {infont} operator. +% +% \startbuffer[mp] +% draw "this string will become a sequence of glyphs (MP)" +% infont defaultfont scaled defaultscale ; +% \stopbuffer +% +% \typebuffer[mp] +% +% The text between \type {"} is passed to \TEX, and the resulting \DVI\ will be +% converted into a picture with textual components. So, we get: +% +% \startlinecorrection[blank] +% \midaligned{\processMPbuffer[mp]} +% \stoplinecorrection +% +% The same string typeset by \TEX\ shows up as: +% +% \blank +% \midaligned{this string will become a sequence of glyphs (\TeX)} +% \blank +% +% The following \METAPOST\ features are not covered by the \METAPOST\ manual, but +% most of them are discussed in the appendix of the \type {graph} package written +% by John Hobby. +% +%It is possible to disassemble a picture by means of a special for loop using the +%\type {within} specifier. The following code walks over a picture and draws the +%components with their bounding boxes. +% +% \startbuffer[show] +% for i within currentpicture : +% draw boundingbox i withcolor .625yellow ; +% endfor ; +% \stopbuffer +% +% \typebuffer[show] +% +% We can use the disassemble loop feature to look into the previously shown +% example text. +% +% \startlinecorrection[blank] +% \processMPbuffer[mp,show] +% \stoplinecorrection +% +% The second line is typeset by \TEX. The resulting \DVI\ code is converted into a +% series of pictures, which \METAPOST\ pastes into one picture. You may also notice +% that in the set of pictures that originate in \TEX, the space is replaced by a +% shift (this is because \TEX\ knows no space). +% +% An interesting aspect of this \quote {loop over a picture} feature, is that it +% can provide insight in how \TEX\ is composing a paragraph. +% +% \startbuffer +% draw btex \framed[width=fit,align=middle]{\input tufte \relax} etex ; +% for i within currentpicture : +% draw boundingbox i withpen pencircle scaled .2pt withcolor .625yellow ; +% endfor ; +% \stopbuffer +% +% \startlinecorrection[blank] +% \processMPbuffer +% \stoplinecorrection +% +% You may also notice, that rules produced by \TEX\ are converted to straight line +% segments. Because the line extends 50\% of its linewidth beyond a point, there is +% a slight overshoot. This picture was defined in a few lines: +% +% \typebuffer +% +% If we use a Times Roman instead of a Palatino, we get quite +% different results. +% +% \startlinecorrection[blank] +% \startMPenvironment +% %\let\fontclass\empty +% \usetypescript[times][texnansi] +% \switchtobodyfont[times,10pt] +% \stopMPenvironment +% \processMPbuffer +% \stoplinecorrection +% +% In \CONTEXT, you can easily change the body font for +% \METAPOST\ graphics with directives like: +% +% \starttyping +% \startMPenvironment +% \usetypescript[times][texnansi] +% \switchtobodyfont[times,10pt] +% \stopMPenvironment +% \stoptyping +% +% This font has far less kerning. Even more interesting is the Lucida Bright +% Handwriting font, which is defined in such a way that no kerning is needed at +% all. +% +% \startlinecorrection[blank] +% \resetMPenvironment +% \startMPenvironment +% %\let\fontclass\empty +% \usetypescript[lucida][texnansi] +% \switchtobodyfont[lucida,hw,10pt] +% \stopMPenvironment +% \processMPbuffer +% \stoplinecorrection +% +% You can ask for the number of components with \type {length}. A component can be +% a stroked or filled path, or a text resulting from an \type {infont} operation. +% If the (last) path is a clip path, or when the whole picture has a forced +% boundingbox, the picture is treated as a whole. We will demonstrate this later. + +We can decompose \METAPOST\ pictures using a \type {within} loop. You may wonder +if such a \type {within} loop construct has any real application, and as you can +expect, it has. In \in {section} [sec:color circles] a macro is defined that +draws a colored circle. If you want the inverted alternative, you can pass the +inverted color specification, but wouldn't it be more convenient if there was an +operator that did this for you automatically? Unfortunately there isn't one so we +have to define one ourselves in a macro. + +\startbuffer +colorcircle(4cm,(.4,.6,.8),(.4,.8,.6),(.6,.4,.8)) ; +addto currentpicture also inverted currentpicture shifted (5cm,0) ; +\stopbuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +These circles were drawn using: + +\typebuffer + +When we \type {draw} a path, or stroke a path, as it is called officially, we +actually perform an addition: + +\starttyping +addto currentpicture doublepath somepath +\stoptyping + +The \type {fill} command is actually: + +\starttyping +addto currentpicture contour somepath +\stoptyping + +We will need both \type {doublepath} and \type {contour} operations in the +definition of \type {inverted}. + +When \METAPOST\ has digested a path into a picture, it keeps track of some +characteristics. We can ask for them using \type {part...} operators. The +following operators can be applied to a transform vector (one of \METAPOST's data +types), but also to a picture. Say that we have drawn a circle: + +\startbuffer[a] +draw fullcircle + xscaled 3cm yscaled 2cm + dashed dashpattern(on 3mm off 3mm) + withpen pencircle scaled 1mm + withcolor .625red ; +picture p ; p := currentpicture ; +\stopbuffer + +\typebuffer[a] + +This circle looks like: + +\startlinecorrection[blank] +\processMPbuffer[a] +\stoplinecorrection + +We can now ask for some of the characteristics of \type {currentpicture}, like +its color. We could write the values to the log file, but it is more convenient +to put them on paper. + +\startbuffer[b] +label.rt("redpart: " & decimal redpart p, (4cm,+.5cm)) ; +label.rt("greenpart: " & decimal greenpart p, (4cm, 0cm)) ; +label.rt("bluepart: " & decimal bluepart p, (4cm,-.5cm)) ; +\stopbuffer + +\typebuffer[b] + +Here the \type {&} glues strings together, while the decimal operator converts a +number into a string. + +The result has no typographic beauty |<|keep in mind that here we use \METAPOST\ +to typeset the text|>|but the result serves its purpose. + +\startlinecorrection[blank] +\processMPbuffer[a,b] +\stoplinecorrection + +We can also ask for the path itself (\type {pathpart}), the pen (\type {penpart}) +and the dashpattern (\type {dashpart}), but these can only be assigned to +variables of the corresponding type. + +A path can be stroked or filled, in which case it is a cyclic path. It can have a +non natural bounding box, be a clip path, consist of line segments or contain +text. All these characteristics can be tested. + +\startbuffer[b] +label.rt("filled: " & condition filled p, (4cm,+1.25cm)) ; +label.rt("stroked: " & condition stroked p, (4cm,+0.75cm)) ; +label.rt("textual: " & condition textual p, (4cm,+0.25cm)) ; +label.rt("clipped: " & condition clipped p, (4cm,-0.25cm)) ; +label.rt("bounded: " & condition bounded p, (4cm,-0.75cm)) ; +label.rt("cycle: " & condition cycle pathpart p, (4cm,-1.25cm)) ; +\stopbuffer + +\typebuffer[b] + +\startlinecorrection[blank] +\processMPbuffer[a,b] +\stoplinecorrection + +In this code snippet, \type {condition} is a macro that takes care of translating +a boolean value into a string (like \type {decimal} does with a numeric value). + +\starttyping +def condition primary b = + if b : "true" else : "false" fi +enddef ; +\stoptyping + +Clip paths and bounding boxes are kind of special in the sense that they can +obscure components. The following examples demonstrate this. In case of a clip +path or bounding box, the \type {pathpart} operator returns this path. In any +case that asking for a value does not make sense |<|a clipping path for instance +has no color|>| a zero (null) value is returned. + +\startbuffer[b] +n := 1 ; +for i within currentpicture : n := n + 1 ; + label("n: " & decimal n & " / " & + "length: " & decimal length i & " / " & + "stroked: " & condition stroked i & " / " & + "clipped: " & condition clipped i & " / " & + "bounded: " & condition bounded i , (0,-n*.5cm)) ; +endfor ; +\stopbuffer + +\startbuffer[c] +\startlinecorrection[blank] +\framed[offset=overlay,frame=off,background=color,backgroundcolor=gray]{\processMPbuffer[a,b]} +\stoplinecorrection +\stopbuffer + +\startbuffer[a] +draw fullcircle withpen pencircle scaled 6mm ; +clip currentpicture to fullcircle ; +setbounds currentpicture to fullcircle ; +\stopbuffer + +\typebuffer[a] \getbuffer[c] + +\startbuffer[a] +draw fullcircle withpen pencircle scaled 6mm ; +setbounds currentpicture to fullcircle ; +clip currentpicture to fullcircle ; +\stopbuffer + +\typebuffer[a] \getbuffer[c] + +\startbuffer[a] +clip currentpicture to fullcircle ; +draw fullcircle withpen pencircle scaled 6mm ; +setbounds currentpicture to fullcircle ; +\stopbuffer + +\typebuffer[a] \getbuffer[c] + +\startbuffer[a] +clip currentpicture to fullcircle ; +setbounds currentpicture to fullcircle ; +draw fullcircle withpen pencircle scaled 6mm ; +\stopbuffer + +\typebuffer[a] \getbuffer[c] + +\startbuffer[a] +setbounds currentpicture to fullcircle ; +clip currentpicture to fullcircle ; +draw fullcircle withpen pencircle scaled 6mm ; +\stopbuffer + +\typebuffer[a] \getbuffer[c] + +\startbuffer[a] +setbounds currentpicture to fullcircle ; +draw fullcircle withpen pencircle scaled 6mm ; +clip currentpicture to fullcircle ; +\stopbuffer + +\typebuffer[a] \getbuffer[c] + +The description lines were generated by the following loop: + +\typebuffer[b] + +% % The following is no longer valid in MetaFun: +% +% If we have a textual picture, we can also ask for the text and font. Take the +% following picture: +% +% \startbuffer[a] +% picture p ; +% p := "MetaFun" normalinfont "rm-lmr10" scaled 2 rotated 30 slanted .5 ; +% p := p shifted (0,-ypart center p) ; +% currentpicture := p ; +% \stopbuffer +% +% \typebuffer[a] +% +% Here we can ask for: +% +% \startbuffer[b] +% label.rt("textpart: " & textpart p, (4cm,+0.25cm)) ; +% label.rt("fontpart: " & fontpart p, (4cm,-0.25cm)) ; +% \stopbuffer +% +% \typebuffer[b] +% +% and get: +% +% \startlinecorrection[blank] +% \processMPbuffer[a,b] +% \stoplinecorrection +% +% We use \type {normalinfont} instead of \type {infont} because in \METAFUN\ this +% operator is overloaded and follows another route for including text. +% +% If we're dealing with a path, the transformations have ended up in the path +% specification. If we have a text picture, we can explicitly ask for the transform +% components. +% +% \startbuffer[b] +% label.rt("xpart: " & decimal xpart p, (4cm,+1.25cm)) ; +% label.rt("ypart: " & decimal ypart p, (4cm,+0.75cm)) ; +% label.rt("xxpart: " & decimal xxpart p, (4cm,+0.25cm)) ; +% label.rt("xypart: " & decimal xypart p, (4cm,-0.25cm)) ; +% label.rt("yxpart: " & decimal yxpart p, (4cm,-0.75cm)) ; +% label.rt("yypart: " & decimal yypart p, (4cm,-1.25cm)) ; +% \stopbuffer +% +% \typebuffer[b] +% +% \startlinecorrection[blank] +% \processMPbuffer[a,b] +% \stoplinecorrection +% +% We will now define the \type {inverted} macro using these primitives. Because we +% have to return a picture, we cannot use \type {draw} and \type {fill} but need to +% use the low level operators. Because a picture can consist of more than one path, +% we need a temporary picture \type {pp}. +% +% \starttyping +% vardef inverted expr p = +% save pp ; picture pp ; pp := nullpicture ; +% for i within p : +% addto pp +% if stroked i or filled i : +% if filled i : contour else : doublepath fi pathpart i +% dashed dashpart i withpen penpart i +% else : +% also i +% fi +% withcolor white-(redpart i, greenpart i, bluepart i) ; +% endfor ; +% pp +% enddef ; +% \stoptyping +% +% We probably need to handle a few more border cases, but for general purposes, +% this macro works as expected. + +The textual capabilities built in \METAPOST\ are rather limited but in \CONTEXT\ +we have overloaded the relevant operators. There we hook into the normal font +handler. The native text related operators are: + +\starttyping +draw "MetaFun" infont "somefont" scaled 2 rotated 30 slanted .5 ; +draw btex MetaFun etex scaled 2 rotated 30 slanted .5 ; +\stoptyping + +The \type {infont} operator directly calls for a font and in stock \METAPOST\ is +limited to (eight bit) \TYPEONE\ fonts. In \CONTEXT\ you can do this: + +\startbuffer[a] +draw "MetaFun" infont "SerifBold*default" xscaled 5 rotated 5 slanted .5 ; +\stopbuffer + +\typebuffer[a] + +The specification is a regular \CONTEXT\ font specification. + +\startlinecorrection[blank] +\processMPbuffer[a] +\stoplinecorrection + +The \type {btex ... etex} variant in normal \METAPOST\ delegates to \TEX\ and in \MKII\ +indeed we filter them and process them between runs (or at runtime). In \MKIV\ they are +also handled by \TEX\ but in an even more integrated and immediate way. + +The two primitives \type {textpart} and \type {fontpart} that can be used to disassemble +a picture don't apply to \METAFUN\ as contrary to \METAPOST\ we don't convert the result +to a picture. In later chapters we will discuss text in more detail. + +From the previous examples it may be clear that each picture has some associated +data stored with it. From the \type {bounded} boolean test we can conclude that +the bounding box is part of this data. Internally \METAPOST\ keeps track of two +bounding boxes: the natural one, and the forced one. The forced one is actually a +component of the picture which applies to all previously added graphics. You can +calculate the bounding box from the \type {llcorner} and \type {urcorner} or if +you like \type {ulcorner} and \type {lrcorner} and the \METAFUN\ command \type +{boundingbox} does so. + +The four corners that make up the bounding box are either the natural ones, or +the ones forced by \type {setbounds}. You can force \METAPOST\ to report the +natural ones by setting \type {truecorners} to~1. The next example demonstrates +this feature. + +\startbuffer +pickup pencircle scaled 2mm ; path p, q ; +draw fullcircle + scaled 4cm slanted .5 withcolor .625white ; +setbounds currentpicture to + boundingbox currentpicture enlarged -5mm ; +interim truecorners := 0 ; p := boundingbox currentpicture ; +interim truecorners := 1 ; q := boundingbox currentpicture ; +pickup pencircle scaled 1mm ; +draw p withcolor .625red ; +draw q withcolor .625yellow ; +\stopbuffer + +\typebuffer + +We use \type {interim} because \type {truecorners} is an internal \METAPOST\ +variable. + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +% % we already redefined infont so it's kind of dangerous to provide this example +% +% Since \METAPOST\ can handle fonts (it can even generate font metric files) it is +% no surprise that we can also ask for the natural size of a font. For this we use +% \type {fontsize}. However, you should beware of the fact that the size reported +% is in base points. Since this is \METAPOST's native unit, this is no problem in +% calculations, but it may look confusing when you \type {show} this size on your +% terminal and get less that 10 reported for a \type {cmr10} font. +% +% \starttyping +% show fontsize "cmr10" ; +% \stoptyping +% +% In order to demonstrate that \type {fontsize} is useful, we extend the \type +% {infont} command. In the process we show a few macro definition tricks. What we +% want is a \TEX\ like specification of a font size: +% +% \startbuffer[txt] +% draw "MetaFun" infont defaultfont at 20pt ; +% \stopbuffer +% +% \typebuffer[txt] +% +% We can store the current meaning of a primitive or macro in a new macro. We do so +% with \type {infont}: +% +% \startbuffer[a] +% let normalinfont = infont ; +% \stopbuffer +% +% \typebuffer[a] +% +% We can only know the size if we know the name of the font, so we have to redefine +% \type {infont} to pick up this name. +% +% \startbuffer[b] +% numeric lastfontsize ; lastfontsize = fontsize defaultfont ; +% \stopbuffer +% +% \startbuffer[c] +% primarydef infont primary name = % patched: def should work too +% hide(lastfontsize := fontsize name) +% normalinfont name +% enddef ; +% \stopbuffer +% +% \typebuffer[c] +% +% Because we are replacing an operator, and since \METAPOST\ expects one, we have +% to use \type {def} instead of \type {vardef} (which is actually a kind of +% variable). For the same reason, we have to pick up a \type {primary}. If we would +% use a \typ {expr name}, we would end up in an unwanted look ahead. The \type +% {hide} macro hides the assignment and makes this macro behave like a \type +% {vardef} with respect to hiding expressions. We may not put a semi colon after +% the \type {)} because it would stop \METAPOST\ from reading on, and thereby +% invoke an error message. +% +% We can now define \type {at}. This macro picks up an expression (which can be +% more than just a number) and return a scale transform that normalizes the given +% size to the design size. +% +% \startbuffer[d] +% def at expr size = +% scaled (size/lastfontsize) +% enddef ; +% \stopbuffer +% +% \typebuffer[d] +% +% Because this macro is defined global, and therefore can be used apart from \type +% {infont}, we predefine the size: +% +% \typebuffer[b] +% +% When defined this way \type {at} a comfortable 20 points, the string \type +% {MetaFun} comes out as follows: +% +% \startlinecorrection[blank] +% \processMPbuffer[a,b,c,d,txt] +% \stoplinecorrection + +\stopsection + +\startsection[title={Filling}] + +\index{filling} +\index{reversing} + +In most cases a path ends up being drawn or filled. When filling a path, it +doesn't matter in what direction the path runs, as long as it's closed you're +fine. You can however change the direction any time along the path. Here is an +example of what happens when you fill a path that is partially reversed. + +\startbuffer +fill fullsquare rotated 45 scaled 2cm + withcolor .625 red ; +fill fullcircle scaled 2cm -- reverse fullcircle scaled 1cm -- cycle + withcolor .625 yellow ; +\stopbuffer + +\typebuffer + +You'll notice that the inner circle is not filled: + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +Now watch the following: + +\startbuffer +fill + fullsquare rotated 45 scaled 2cm + -- fullcircle scaled 2cm + -- cycle + withcolor .625 red ; +\stopbuffer + +\typebuffer + +This results in: + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +Compare this with: + +\startbuffer +fill + fullsquare rotated 45 scaled 2cm + -- reverse fullcircle scaled 2cm -- cycle + -- cycle + withcolor .625 red ; +\stopbuffer + +\typebuffer + +giving: + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +The normal filling happens according to the non||zero winding rule. An alternative is the +odd||even rule. There we don't need the reverse trick: + +\startbuffer +eofill fullsquare rotated 45 scaled 2cm + -- fullcircle scaled 2cm -- cycle + withcolor .625 red ; +\stopbuffer + +\typebuffer + +The \type {eofill} is a \METAFUN\ extension. Hopefully the next explains a bit +how this works (you can find explanations zon the internet). + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +\startuseMPgraphic{demo} + def DrawIt(text how) = + path p ; p := ((0,0) .. (1,0) .. (1,1) .. (0,1) .. (1,0) .. (2,1) .. cycle) scaled 2cm ; + how p withcolor .625 yellow ; + draw p withcolor .625 red ; + for i=0 step 0.05 until 1 : + fill arrowheadonpath (p,i) + withcolor .625 red ; + endfor ; + draw (0.5,0.5) scaled 2cm withpen pencircle scaled .5mm withcolor .375 white ; + draw ((0.5,0.5) scaled 2cm -- llcorner p) withpen pencircle scaled .5mm withcolor .375 white ; + draw (1.5,1.5) scaled 2cm withpen pencircle scaled .5mm withcolor .375 white ; + draw ((1.5,1.5) scaled 2cm -- urcorner p) withpen pencircle scaled .5mm withcolor .375 white ; + enddef ; +\stopuseMPgraphic + +\startlinecorrection[blank] + \startcombination[distance=4em] + {\startMPcode \includeMPgraphic{demo} DrawIt(eofill) \stopMPcode} {\type{eofill}} + {\startMPcode \includeMPgraphic{demo} DrawIt(fill) \stopMPcode} {\type{fill}} + \stopcombination +\stoplinecorrection + +In the case of a normal fill, the non||zero winding rule is applied: a winding +number is calculated by subtracting 1 each time the line (from inside an area to +someplace outside) is crossed clockwise while 1 is added each time we cross +anti||clockwise. When the total is non zero the area is filled. Here we run in one +direction and therefore we always get a fill. In the previous example where we +used a reverse, an anti||clockwise crossing was nilled by a clockwise one. + +The leftmost shape uses \type {eofill} and therefore the odd||even rule gets +applied. This time we follow the line and when it gets crossed en even number of +times the area will not be filled. + +A glyph is often constructed from more than one path and eventually the shape is +filled with an odd||even fill (\type {eofill}) operation. Take the following +sequence: + +\startbuffer +pickup pencircle scaled 1mm ; +draw fullsquare scaled 2cm ; +draw fullsquare scaled 2cm shifted (1cm,0) ; +draw fullsquare scaled 2cm shifted (0,1cm) ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +We can use a sequence of \type {nofill} ending with a \type {eofill} to create +a combined shape. This is not done in \METAPOST\ but in the backend. + +\startbuffer +nofill fullsquare scaled 2cm ; +nofill fullsquare scaled 2cm shifted (1cm,0) ; +eofill fullsquare scaled 2cm shifted (0,1cm) ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +As this is used for glyphs, we demonstrate this mechanism with a simple \type {O} +shape: + +\startbuffer +nofill fullcircle xyscaled (2cm,3cm) ; +eofill fullcircle xyscaled (1cm,2cm) ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +Another backend related feature is \type {fillup}. This is just a combination +of a fill and a draw in one go. It can save some bytes in the output file. + +\startbuffer +draw image ( + pickup pencircle scaled 5mm ; + fill fullsquare scaled 2cm ; + draw fullsquare scaled 2cm ; + fillup fullsquare scaled 2cm shifted (4cm,0) ; +) withcolor .625red ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +\stopsection + +\startsection[title={Pitfalls}] + +When writing macros, you need to be careful in what +operations apply to what object. There is for instance a +difference between the following code: + +\startbuffer +pickup pencircle scaled 2pt ; +draw (0,0)--(0,1)--(1,1) scaled 1cm withcolor .625 red ; +draw ((0,0)--(0,1)--(1,1)) scaled 2cm withcolor .625 yellow ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +The \type {scaled} operates on the previous expression which in the first case is +the point \type {(1,1)} and in the second case the whole path. + +\startbuffer +pickup pencircle scaled 2pt ; +draw (0,0)--(0,1)--(1,1)--cycle scaled 1cm withcolor .625 red ; +draw ((0,0)--(0,1)--(1,1)--cycle) scaled 2cm withcolor .625 yellow ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +Here the last element in the first case is not the cycle, and the next +alternative does not help us much in discovering what is going on. (Well, at +least something {\em is} going on, because the result seems to have some +dimensions.) + +\startbuffer +pickup pencircle scaled 2pt ; +draw (1,1)--cycle scaled 1cm withcolor .625 red ; +draw ((1,1)--cycle) scaled 1cm withcolor .625 yellow ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +The next lines demonstrate that we're dealing with the dark sides of \METAPOST, +and from that we may conclude that in case of doubt it's best to add parenthesis +when such fuzzy situations threaten to occur. + +\startbuffer +pickup pencircle scaled 2pt ; +draw (0,1)--(1,1)--cycle scaled 1cm withcolor .625 red ; +draw ((0,1)--(1,1)--cycle) scaled 1cm withcolor .625 yellow ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +There are more cases where the result may surprise you. Take the following code: + +\startbuffer +drawarrow ((0,0)--(10,0)) + withpen pencircle scaled 2pt + withcolor red randomized (.4,.9) ; +currentpicture := currentpicture scaled 8 ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +The arrow is made up out of two pieces and each piece gets a different shade of +red. This is because the attributes are collected and applied to each of the +components that make up the arrow. Because for each component the attribute code +is expanded again, we get two random colors. One way around this is to apply the +color afterwards. + +\startbuffer +draw + image (drawarrow ((0,0)--(10,0)) withpen pencircle scaled 2pt) + scaled 8 withcolor red randomized (.4,.9) ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +Here the \type {image} macro creates a picture and as you can see, this provides +a way to draw within a draw operation. + +Once you see the benefits of \type {image}, you will use it frequently. Another +handy (at first sight strange) macro is \type {hide}. You can use this in +situations where you don't want code to interfere. + +\starttyping +def mydraw text t = + boolean error ; error := false ; + def withpencil expr p = hide (error := true) enddef ; + draw t ; + if error : message "pencils are not supported here" fi ; +enddef ; +mydraw fullcircle scaled 10cm withpencil sharp ; +\stoptyping + +Here, setting the boolean normally interferes with the draw operation, but by +hiding the assignment, this code becomes valid. This code will bring the message +to your terminal and log file. + +Once you start using expressions you have a good chance of encountering messages +with regard to redundant expressions. The following code is for instance a +recipe for problems: + +\starttyping +z1 = (1,0) ; z1 = (2,0) ; +\stoptyping + +Changing the \type {=} into \type {:=} helps, but this may not be what you want. + +Because the \type {z}||variables are used frequently, they are reset each figure. +You can also reset them yourself, using the \type {clearxy} macro. The \METAFUN\ +version clears all \type {z}||variables, unless you explictly specify what +variables to reset. \footnote {This version resulted from a discussion on the +\METAFONT\ discussion list and is due to Bogus\l{}aw Jackowski.} If you want to +play with this macro, see what happens when you run the following code: + +\starttyping +show x0 ; z0 = (10,10) ; +show x0 ; x0 := whatever ; y0 := whatever ; +show x0 ; z0 = (20,20) ; +show x0 ; clearxy 0 ; +show x0 ; z0 = (30,30) ; +\stoptyping + +So, the following calls are all legal: + +\starttyping +clearxy ; clearxy 1 ; clearxy 1, 8, 10 ; +\stoptyping + +Keep in mind that for each figure a full clear is done anyway. You should not +confuse this command with \type {clearit}, which clears \type {currentpicture}. + +\stopsection + +\startsection[title={\TeX\ versus \MetaPost}] + +If you are defining your own \TEX\ and \METAPOST\ macros, you will notice that +there are a couple of essential differences between the two macro languages. In +\TEX\ the following code is invalid. \footnote {In \ETEX\ the calculation can be +done in less lines using a \type {\numexpr}.} + +\starttyping +\def\fancyplied#1% + {\ifnum#1=0 + \message{zero argument}% + \fi + \count0=#1 \multiply \count0 by \count0 + \count2=#1 \multiply \count2 by 2 + \count4=#1 \divide \count4 by 2 + \advance \count0 by \count2 + \advance \count0 by \count4 + \count4 } +\hskip \fancyplied{3} pt +\stoptyping + +This is because \TEX\ is very strict in what tokens it expects next. In +\METAPOST\ however, you can use \type {vardef}'d macros to hide nasty +intermediate calculations. + +\starttyping +vardef fancyplied expr x = + if x=0 : message "x is zero" ; (x*x+2x+x/2) +enddef ; +a := a shifted (fancyplied 3pt,0) ; +\stoptyping + +Hiding intermediate calculations and manipulations is a very strong point of +\METAPOST. + +Another important difference between both languages is the way grouping is +implemented. Because \TEX\ is dealing with a flow of information, strong grouping +is a must and therefore part of the language. Occasionally you run into +situations where you wished that you could reach over a group (for instance in +order to pass a value). + +In \METAPOST\ grouping behaves quite different. First of all, it provides the +mechanism that hides processing from the current flow. The previously mentioned +\type {vardef} is implicitly grouped. Contrary to \TEX, in \METAPOST\ all +assignments are global by default, even in a group. If you assign a variable +inside a group it is persistent unless you first save the variable (or macro) +using the \type {save} operator. + +So, in the next code snippet, the value of \type {\value} inside the box is {\em +no} but after the box is typeset, it will be {\em yes} again. + +\starttyping +\def\value{yes} \hbox{\def\value{no}\value} \value +\stoptyping + +To make a value local in \METAPOST, the following code is needed. + +\starttyping +string value ; value := "yes" ; +def intermezzo + begingroup ; + save value ; string value ; value := "no" ; + endgroup ; +enddef ; +\stoptyping + +Once you start writing your own \METAPOST\ macros, you will appreciate this +\quote {always global} behaviour. As with other differences between the two +languages, they make sense if you look at what the programs are supposed to do. + +\stopsection + +\startsection[title={Internals and Interims}] + +\index{internals} +\index{interims} + +Related to grouping is the internal numeric datatype. When numeric variables are +defined as interim, you can quickly overload them inside a group. + +\starttyping +newinternal mynumber ; mynumber := 1 ; + +begingroup ; ... interim mynumber := 0 ; ... ; endgroup ; +\stoptyping + +You can only \type {interim} a variable if it is already defined using \type +{newinternal}. + +Among the \METAPOST\ macros is one called \type {drawdot}. This macro is kind of +redundant because, at least at first sight, you can use draw to achieve the same +result. There is however a very subtle difference: a dot is slightly larger than +a drawn point. We guess that it's about the device pixel, so you may not even +notice it. It may even be due to differences in accuracy of the methods to render +them. + +\startbuffer +pickup pencircle scaled 50pt ; +drawdot origin shifted (-120pt,0) ; draw origin shifted (-60pt,0) ; +drawdot origin ; draw origin withcolor white ; +setbounds currentpicture to boundingbox currentpicture enlarged 1pt ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +\stopsection + +\startsection[title=Named colors] + +The \type {withcolor} operator accepts a color expression but in \METAFUN\ it +also accepts a string indicating a color defined at the \TEX\ end. Most helpers +that deal with colors are able to deal with named colors as well. Here are some +examples. First we define a few colors: + +\startbuffer +\definecolor[MyColor1][r=.5] +\definecolor[MyColor2][g=.5] +\definecolor[MyColor3][b=.5] +\definecolor[MyColor4][s=.8] +\stopbuffer + +\typebuffer \getbuffer + +Here we access them: + +\startbuffer +fill fullcircle scaled 12 withcolor "MyColor1" ; +fill fullcircle scaled 10 withcolor "MyColor2" ; +fill fullcircle scaled 8 withcolor complementary "MyColor3" ; +fill fullcircle scaled 6 withcolor complemented "MyColor3" ; +fill fullcircle scaled 4 withcolor "MyColor4" randomized 2 ; +fill fullcircle scaled 2 withcolor "MyColor4" randomized 2 ; +addbackground + withcolor .5[resolvedcolor("MyColor4"),resolvedcolor("MyColor2")] ; +currentpicture := currentpicture ysized 4cm ; +\stopbuffer + +\typebuffer + +And get: + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +\stopsection + +\startsection[title=Formatted text] + +Text support in \METAFUN\ has evolved quite a bit over years. For compatibility +reasons we keep old methods around but in practice one can probably do all with +the following: + +\starttabulate[|T|p|] +\NC textext[.anchor](str) \NC position a text relative to the origin \NC \NR +\NC thetextext[.anchor](str,pos) \NC position a text relative to the given position \NC \NR +\NC rawtextext[.anchor](str,pos) \NC idem but with less checking \NC \NR +\stoptabulate + +If needed all functionality could be combined in one call (textext) but we keep +it this way. + +You need to keep in mind that text in \METAPOST\ is not a first class object but +something virtual that is known to \METAFUN\ as something with path like properties +but is actually dealt with in the backend. This means that timing is important. + +\starttyping +\startMPinitializations +picture p ; p := image(draw textext("Foo");); +\stopMPinitializations + +\startMPcode + picture q ; q := image(draw textext("Bar");); + picture r ; r := image(draw textext("Gnu");); + draw p ; + draw q shifted (2cm,0) ; + draw r shifted (4cm,0) ; +\stopMPcode +\stoptyping + +This will work out well because an initialization is part of a figure, but +this will fail: + +\starttyping +\startMPinclusions +picture p ; p := image(draw textext("Foo");); +\stopMPinclusions +\stoptyping + +because inclusions happen before the local textexts get initialized and +due to the multipass implementation are not seeN a second time. The order of +processing is: + +\starttabulate[|l|c|c|] +\BC action \BC first pass \BC second pass \NC \NR +\NC definitions \NC yes \NC \NC \NR +\NC extensions \NC yes \NC \NC \NR +\NC inclusions \NC yes \NC \NC \NR +\NC begin figure \NC yes \NC yes \NC \NR +\NC initializations \NC yes \NC yes \NC \NR +\NC metapost code \NC yes \NC yes \NC \NR +\NC end figure \NC yes \NC yes \NC \NR +\stoptabulate + +The graph package (that comes with \METAPOST) has some pseudo typesetting on +board needed to format numbers. Because we don't want to interfere with the +definitions of macros used in that package we provide another set of macros for +formatting: \type {fmttext}, \type {thefmttext} and \type {rawfmttext}. + +\startbuffer +\startMPcode +draw thefmttext("\bf@3.2f done",123.45678) withcolor darkred ; +\stopMPcode +\stopbuffer + +\typebuffer + +Here we pass one variable to the format but there can be more: \inlinebuffer. In +\LUA\ the \type {%} is used as format directive but that does not work well in +\TEX\ and \LUA\ which is why we use \type {@} instead. The formatting is done +with the formatters subsystem which is an extension to the regular \LUA\ \type +{format} function. More information can be found in \type {clf-mkiv.pdf} but one +extension is not mentioned there: \type {%!texexp!}. This directive takes one +argument by default but optionally can take one or two extra arguments: the +format of the base number and one for the exponent. The following code +demonstrates this: + +\startbuffer +\startMPcode{doublefun} +draw image ( + draw thefmttext.rt("@!texexp!", 10.4698E30, (0,-1LineHeight)) ; + draw thefmttext.rt("@1!texexp!",10.4698E30, (0,-2LineHeight)) ; + draw thefmttext.rt("@2!texexp!",10.4698E30,"@2.3f", (0,-3LineHeight)) ; + draw thefmttext.rt("@3!texexp!",10.4698E30,false,"@2i", (0,-4LineHeight)) ; + draw thefmttext.rt("@3!texexp!",10.4698E30,"@2.3f","@2i",(0,-5LineHeight)) ; +) withcolor darkblue ; +\stopMPcode +\stopbuffer + +\typebuffer + +We switch to double mode because we use large numbers. + +\startlinecorrection[blank] + \getbuffer +\stoplinecorrection + +Of course this extra formatter is also supported in the \type {context} +command: + +\startbuffer +\startluacode +context("%!texexp!, ", 10.4698E30) +context("%1!texexp!, ", 10.4698E30) +context("%2!texexp!, ", 10.4698E30,"@2.3f") +context("%3!texexp! and ",10.4698E30,false,"@2i") +context("%3!texexp!", 10.4698E30,"@2.3f","@2i") +\stopluacode +\stopbuffer + +\typebuffer + +This gives: \inlinebuffer . + +\stopsection + +\startsection[title=Lists (aka suffixed variables)] + +Sometimes graphics are constructed using lists. There are a few helpers (and +maybe there will be some more) that can make things a bit easier. Say that we +do this: + +\startbuffer +pair a[] ; +a[1] := (0,0) ; a[2] := (1,0) ; +a[3] := (1,1) ; a[4] := (0,1) ; +a[5] := (1,1) ; a[6] := (2,0) ; + +draw topath(a,--) ysized 2cm + withpen pencircle scaled 1mm + withcolor .625red ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +The \type {topath} macro converts the list into a path, in this case an ugly one. + +Say that we want to get rid of the sixth entry. For that we can use the \type +{dispose} macro. You can use the dispose for any type (except a macro). + +\startbuffer +dispose(a[6]) ; +draw topath(a,--) ysized 2cm + withpen pencircle scaled 1mm + withcolor .625yellow ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +We still have some duplicate entries here: + +\startbuffer +dispose(a[6]) ; +drawpoints topath(a,--) ysized 2cm + withpen pencircle scaled 1mm + withcolor .625red ; +drawpointlabels topath(a,--) ysized 2cm ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +These can be removed with: + +\startbuffer +uniquelist(a) ; +draw topath(a,--) ysized 2cm + withpen pencircle scaled 1mm + withcolor .625yellow ; +drawpoints topath(a,--) ysized 2cm + withpen pencircle scaled 1mm + withcolor .625red ; +drawpointlabels topath(a,--) ysized 2cm ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +Sometimes a list needs to be sorted and here is the solution: + +\startbuffer +sortlist(a,nothing) ; +draw topath(a,--) ysized 2cm + withpen pencircle scaled 1mm + withcolor .625red ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +The second argument can be an operator that takes a pair variable: + +\startbuffer +sortlist(a,xpart) ; +draw topath(a,--) ysized 2cm + withpen pencircle scaled 3mm + withcolor .625red ; +sortlist(a,ypart) ; +draw topath(a,--) ysized 2cm + withpen pencircle scaled 2mm + withcolor .625yellow ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +Constructing a list can be sped up with the \type {tolist} macro. + +\startbuffer +pair a[], b[], c[], d[] ; +tolist(a,1,(0,0),(1,0),(1,1),(0,1)--(1,1)--(2,2)) ; +tolist(b,0,(0,0),(1,0),(1,1),(0,1)--(1,1)--(2,2)) ; +tolist(c,(0,0),(1,0),(1,1),(0,1)--(1,1)--(2,2)) ; +tolist(d,(0,0),(1,0),(1,1)) ; + +draw image ( + draw topath(a,--) shifted (0,0) ; + draw topath(b,--) shifted (3,0) ; + draw topath(c,--) shifted (6,0) ; + draw topath(d,--) shifted (9,0) ; +) ysized 2cm withpen pencircle scaled 1mm withcolor .625red ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +\stopsection + +\startsection[title=Segmented paths] + +\index {segmented paths}There are all kind of helpers in \METAFUN\ and some are +discussed here. In \in {figure} [fig:segmentedpaths] we see a few macros that +return a (smooth) path made from segments. You can for instance use these to do +things that use the points on a path, like anchoring text. + +\startbuffer +def DrawSomePath(text t) = + drawpath t withcolor .625red ; + drawpoints t withcolor white ; + drawpointlabels t ; +enddef ; + +DrawSomePath(circularpath(5) scaled 12cm) ; +DrawSomePath(squarepath (5) scaled 8cm) ; +DrawSomePath(linearpath (5) scaled 4cm) ; +\stopbuffer + +\typebuffer + +\startplacefigure[title={A few segmented paths.},reference=fig:segmentedpaths] + \processMPbuffer +\stopplacefigure + +\index {crossing paths}The following examples demonstrates two mechanisms. In the +image two paths are drawn on top of each other but one of them has holes where +the other one crosses. The \type {crossingunder} macro was written by Alan +Braslau as part of the node based diagram builder. In the process the arrow +drawing code was adapted to accept a picture. + +\startbuffer[a] +drawarrow image ( + draw ((fullcircle scaled 2.25cm) crossingunder (fullsquare scaled 2cm)) + withpen pencircle scaled 1mm withcolor .625green ; + draw (fullsquare scaled 2cm) + withpen pencircle scaled 1mm withcolor .625blue ; +) ; +drawarrow image ( + draw (fullsquare scaled 4cm) + withpen pencircle scaled 1mm withcolor .625red ; + draw ((fullcircle scaled 5cm) crossingunder (fullsquare scaled 4cm)) + withpen pencircle scaled 1mm withcolor .625yellow ; +) ; +\stopbuffer + +\startbuffer[b] +drawarrow image ( + draw ((fullsquare scaled 2cm) crossingunder (fullcircle scaled 2.25cm)) + withpen pencircle scaled 1mm withcolor .625blue ; + draw (fullcircle scaled 2.25cm) + withpen pencircle scaled 1mm withcolor .625green ; +) ; +drawarrow image ( + draw (fullcircle scaled 5cm) + withpen pencircle scaled 1mm withcolor .625yellow ; + draw ((fullsquare scaled 4cm) crossingunder (fullcircle scaled 5cm)) + withpen pencircle scaled 1mm withcolor .625red ; +) ; +\stopbuffer + +\typebuffer[a] + +The next variant uses a different order: + +\typebuffer[b] + +The results are shown in \in {figure} [fig:crossingunder]. The internal variable +\type {crossingscale} can be used to make the gap wider or narrower. The gap has +a default value of 20. + +\startplacefigure[title=Crossing paths without touching,reference=fig:crossingunder] + \startcombination + {\processMPbuffer[a]} {} + {\processMPbuffer[b]} {} + \stopcombination +\stopplacefigure + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/metafun/metafun-colofon-paper.tex b/doc/context/sources/general/manuals/metafun/metafun-colofon-paper.tex new file mode 100644 index 000000000..1a611a325 --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/metafun-colofon-paper.tex @@ -0,0 +1,19 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\startcomponent metafun-colofon-paper + +\environment metafun-environment + +\startstandardmakeup + + \vfill + + \setupalign[flushright,broad] + + \component metafun-colofon + +\stopstandardmakeup + +\stopcomponent diff --git a/doc/context/sources/general/manuals/metafun/metafun-colofon-screen.tex b/doc/context/sources/general/manuals/metafun/metafun-colofon-screen.tex new file mode 100644 index 000000000..590c7725f --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/metafun-colofon-screen.tex @@ -0,0 +1,21 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\startcomponent metafun-colofon-screen + +\environment metafun-environment + +\page + +\start + + \setupalign[flushright,broad] + + \component metafun-colofon + +\stop + +\page + +\stopcomponent diff --git a/doc/context/sources/general/manuals/metafun/metafun-colofon.tex b/doc/context/sources/general/manuals/metafun/metafun-colofon.tex new file mode 100644 index 000000000..b4c162a89 --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/metafun-colofon.tex @@ -0,0 +1,56 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\startcomponent metafun-colofon + +\environment metafun-environment + +\introsubject{For them} + +I owe much inspiration to both my parents. My mother Jannie constantly +demonstrated me that computer graphics will never improve nature. She also +converted one of my first \METAPOST\ graphics into a patchwork that will remind +me forever that handcraft is more vivid than computer artwork. My father Hein has +spent a great deal of his life teaching math, and I'm sure he would have loved +\METAPOST. I inherited his love for books. I therefore dedicate this document to +them. + +\introsubject{Colofon} + +This manual is typeset with \CONTEXT\ \MKIV. No special tricks are used and +everything you see in here, is available for \CONTEXT\ users. The text is typeset +in Palatino and Computer Modern Typewriter. We used \LUATEX\ as \TEX\ processing +engine. Since this document is meant to be printed in color, some examples will +look sub||optimal when printed in black and white. + +\introsubject{Graphics} + +The artist impression of one of Hasselts canals at \at {page} [canal] is made by +Johan Jonker. The \CDROM\ production process graphic at \at {page} [hacker] is a +scan of a graphic made by Hester de Weert. + +\introsubject{Copyright} + +\startlines +Hans Hagen, PRAGMA Advanced Document Engineering, Hasselt NL +copyright: 1999-\currentdate[year] / version 4: \currentdate +\stoplines + +\introsubject{Publisher} + +\startlines +publisher: Boekplan, NL +isbn-ean: 978-94-90688-02-8 +website: www.boekplan.nl +\stoplines + +\introsubject{Info} + +\startlines +internet: www.pragma-ade.com +support: ntg-context@ntg.nl +context: www.contextgarden.net +\stoplines + +\stopcomponent diff --git a/doc/context/sources/general/manuals/metafun/metafun-contents.tex b/doc/context/sources/general/manuals/metafun/metafun-contents.tex new file mode 100644 index 000000000..0767a0248 --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/metafun-contents.tex @@ -0,0 +1,17 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\startcomponent metafun-contents + +\environment metafun-environment + +\starttitle[reference=content,title={Content}] + + \startcolumns + \placelist[chapter,section] + \stopcolumns + +\stoptitle + +\stopcomponent diff --git a/doc/context/sources/general/manuals/metafun/metafun-conventions.tex b/doc/context/sources/general/manuals/metafun/metafun-conventions.tex new file mode 100644 index 000000000..6a6072c56 --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/metafun-conventions.tex @@ -0,0 +1,117 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\startcomponent metafun-conventions + +\environment metafun-environment + +\startchapter[title={Conventions}] + +\index {running} +\index {processing} + +When reading this manual, you may be tempted to test the examples shown. This can +be done in several ways. You can make a file and process that file by \METAPOST. +Such a file looks like: + +\starttyping +beginfig(1) ; + fill fullcircle scaled 5cm withcolor red ; % a graphic +endfig ; + +end . +\stoptyping + +Don't forget the semi||colons that end the statements. If the file is saved as +\type {yourfile.mp}, then the file can be processed. Before we process this file, +we first need to load some basic \METAPOST\ definitions, because the built in +repertoire of commands is rather limited. Such a set is called a format. The +standard format is called {metapost} but we will use a more extensive set of +macros \type {metafun}. In the past such a set was converted into a \type {mem} +file and running the above file was done with: + +\starttyping +mpost --mem=metafun.mem yourfile +\stoptyping + +However, this is no longer the case and macros need to be loaded at startup as +follows: + +\starttyping +mpost --ini metafun.mpii yourfile.mp +\stoptyping + +Watch the suffix \type {mpii}: this refers to the stand alone, the one that +doesn't rely on \LUATEX. + +After the run the results are available in \type {yourfile.1} and can be viewed +with \GHOSTSCRIPT. You don't need to close the file so reprocessing is very +convenient. + +Because we will go beyond standard \METAPOST, we will use the \type {mpiv} files. +These work with the library which in turn means that we will run from within +\CONTEXT. This has the advantage that we also have advanced font support at our +hands. In that case, a simple file looks like: + +\starttyping +\starttext + \startMPpage + fill fullcircle scaled 5cm withcolor red ; + \stopMPpage + \startMPpage + fill unitsquare scaled 5cm withcolor red ; + \stopMPpage +\stoptext +\stoptyping + +If the file is saved as \type {yourfile.tex}, then you can produce a \PDF\ file +with: \footnote {In fact, you could also process the \METAPOST\ file directly +because the \type {context} script will recognize it as such and wrap it into +a page.} + +\starttyping +context yourfile +\stoptyping + +The previous call will use \LUATEX\ and \CONTEXT\ \MKIV\ to produce a file with +two pages using the built in \METAPOST\ library with \METAFUN. When you use this +route you will automatically get the integrated text support shown in this +manual, including \OPENTYPE\ support. If one page is enough, you can also say: + +\starttyping +\startMPpage +fill fullcircle scaled 5cm withcolor red ; +\stopMPpage +\stoptyping + +So when you have a running \CONTEXT\ on your system you don't need to bother +about installing \METAPOST\ and running \METAFUN. + +We will use lots of color. Don't worry if your red is not our red, or your yellow +does not match ours. We've made color definitions to match the overall design of +this document, but you should feel free to use any color of choice in the +upcoming examples. + +By default, \CONTEXT\ has turned its color mechanism on. If you don't want your +graphics to have color, you should say: + +\starttyping +\setupcolors[state=stop] +\stoptyping + +but in todays documents color is so normal that you will probably never do that. +Because \METAFUN\ hooks into the \CONTEXT\ color mechanism, you can also use its +color space and conversion related features. + +You need to keep in mind that just like \CONTEXT\ \MKII\ is frozen, the \type +{mpii} macros are also not extended. From now on we assume that you use \CONTEXT\ +\MKIV\ which exclusively uses \type {mpiv} macros. + +Even if you want to use \METAFUN\ but not \CONTEXT, you can still best use the +mentioned page method as it will give you decent text processing. You need to +know (and use) only a few \CONTEXT\ commands then. + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/metafun/metafun-debugging.tex b/doc/context/sources/general/manuals/metafun/metafun-debugging.tex new file mode 100644 index 000000000..4174d34e1 --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/metafun-debugging.tex @@ -0,0 +1,383 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\startcomponent mfun-debugging + +\environment metafun-environment + +\startchapter[reference=sec:debugging,title={Debugging}] + +\index{debugging} + +\startintro + +Those familiar with \CONTEXT\ will know that it has quite some visual debugging +features build in. So, what can you expect of the \METAPOST\ macros that come +with \CONTEXT ? In this chapter we will introduce a few commands that show some +insight in what \METAPOST\ is doing. + +\stopintro + +\startsection[title=Showing paths] + +Since the outcome of \METAPOST\ code is in many respects more predictable than +that of \TEX\ code, we don't need that advanced visual debugging features. +Nevertheless we provide a few, that are all based on visualizing paths. + +\startbuffer +path p ; p := fullcircle scaled 4cm ; +drawpath p ; drawpoints p ; drawpointlabels p ; +\stopbuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +This visualization is achieved by using dedicated drawing commands: + +\typebuffer + +Since control points play an important role in defining the shape, visualizing +them may shed some insight in what \METAPOST\ is doing. + +\startbuffer +path p ; p := fullcircle xscaled 4cm yscaled 3cm ; +drawpath p ; drawcontrollines p ; +drawpoints p ; drawcontrolpoints p ; drawpointlabels p ; +\stopbuffer + +\typebuffer + +The pre and post control points show up as small dots and are connected to their +parent point with thin lines. + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +You can deduce the direction of a path from the way the +points are numbered, but using an arrow to indicate the +direction is more clear. + +\startbuffer +path p ; p := fullcircle xscaled 4cm yscaled 3cm ; +drawarrowpath p ; drawcontrollines p ; +drawpoints p ; drawcontrolpoints p ; drawpointlabels p ; +\stopbuffer + +\typebuffer + +The \type {drawarrowpath} is responsible for the arrow. Especially when you are +in the process of defining macros that have to calculate intersections or take +subpaths, knowing the direction may be of help. + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +The next table summarizes the special drawing commands: + +\starttabulate[|lT|l|] +\HL +\NC drawpath \NC the path \NC \NR +\NC drawarrowpath \NC the direction of the path \NC \NR +\NC drawcontrollines \NC the lines to the control points \NC \NR +\NC drawpoints \NC the points that make up the path \NC \NR +\NC drawcontrolpoints \NC the control points of the points \NC \NR +\NC drawpointlabels \NC the numbers of the points \NC \NR +\HL +\stoptabulate + +You can set the characteristics of these like you set \type {drawoptions}. The +default settings are as follows: + +\starttyping +drawpathoptions (withpen pencircle scaled 5 withcolor .8white) ; +drawpointoptions (withpen pencircle scaled 4 withcolor black) ; +drawcontroloptions(withpen pencircle scaled 2.5 withcolor black) ; +drawlineoptions (withpen pencircle scaled 1 withcolor .5white) ; +drawlabeloptions () ; +\stoptyping + +Two more options are \type {draworiginoptions} and \type {drawboundoptions} which +are used when visualizing the bounding box and origin. + +\startbuffer +swappointlabels := true ; +path p ; p := fullcircle xscaled 4cm yscaled 3cm ; +drawarrowpath p ; drawcontrollines p ; +drawpoints p ; drawcontrolpoints p ; drawpointlabels p ; +drawboundingbox p ; draworigin ; +\stopbuffer + +\typebuffer + +In this example we have set \type {swappointlabels} to change the place of the +labels. You can set the variable \type {originlength} to tune the appearance of +the origin. + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +You can pass options directly, like you do with \type {draw} and \type {fill}. +Those options override the defaults. + +\startbuffer +path p ; p := fullcircle xscaled 6cm yscaled 3cm rotated 15 ; +drawarrowpath p ; +drawcontrollines p withcolor .625red ; +drawpoints p withcolor .625yellow ; +drawcontrolpoints p withcolor .625yellow ; +drawpointlabels p withcolor .625yellow ; +drawboundingbox p ; +draworigin withcolor .625red ; +\stopbuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +Here we used the options: + +\typebuffer + +Sometimes it makes sense to draw a simple coordinate system, and for that purpose +we have three more macros. They draw axis and tickmarks. + +\startbuffer +drawticks unitsquare xscaled 4cm yscaled 3cm shifted (-1cm,-1cm) ; +\stopbuffer + +\typebuffer + +The system drawn is based on the bounding box specification of the path passed to +the macro. You can also draw one axis, using \type {drawxticks} or \type +{drawyticks}. Here we show the previous command. + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +By default, the ticks are placed at .5cm distance, but you can change this by +setting \type {tickstep} to a different value. + +\startbuffer +tickstep := 1cm ; ticklength := 2mm ; +drawticks fullsquare xscaled 4cm yscaled 3cm ; +tickstep := tickstep/2 ; ticklength := ticklength/2 ; +drawticks fullsquare xscaled 4cm yscaled 3cm ; +\stopbuffer + +\typebuffer + +The \type {ticklength} variable specifies the length of a tick. Here we +manipulated both the variables to get a more advanced system. + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +If visualizing a path would mean that we would have to key in al those +draw||commands, you could hardly call it a comfortable tool. Therefore, we can +say: + +\startbuffer +drawwholepath fullsquare scaled 3cm rotated 30 randomized 5mm ; +\stopbuffer + +\typebuffer + +The \type {drawwholepath} command shows everything except the axis. + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +If even this is too much labour, you may say: + +\starttyping +visualizepaths ; +\stoptyping + +This redefines the \type {draw} and \type {fill} command in such a way that they +also show all the information. + +\startbuffer +visualizepaths ; +draw fullsquare scaled 3cm rotated 30 randomized 2mm ; +\stopbuffer + +\typebuffer + +You may compare this feature to the \type {\showmakeup} command available in +\CONTEXT, that redefines the \TEX\ primitives that deal with boxes, glues, +penalties, and alike. + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +Of course you may want to take a look at the \METAPOST\ manual for its built in +(more verbose) tracing options. One command that may prove to be useful is \type +{show}, that you can apply to any variable. This command reports the current +value (if known) to the terminal and log file. + +\startlinecorrection[blank] +{\showmakeup\processMPbuffer} +\stoplinecorrection + +The previous picture shows what is typeset when we also say \type {\showmakeup}. +This command visualizes \TEX's boxes, skips, kerns and penalties. As you can see, +there are some boxes involved, which is due to the conversion of \METAPOST\ +output to \PDF. + +\starttyping +\startlinecorrection[blank] +... the graphic ... +\stoplinecorrection +\stoptyping + +The small bar is a kern and the small rectangles are penalties. More details on +this debugger can be found in the \CONTEXT\ manuals and the documentation of the +modules involved. + +\stopsection + +\startsection[title=Comments] + +Sometimes, when trouble strikes, you might want to peek in the \PDF\ file to see +what gets written there. Each graphic is marked with a number but when you +have many it might make sense to add a comment to help you locate the code. + +\startbuffer +\startMPcode + comment("test graphic") ; + message("processing a test graphic") ; + draw fullsquare scaled 1cm ; +\stopMPcode +\stopbuffer + +\typebuffer + +This renders as: + +\startlinecorrection[blank] + \getbuffer +\stoplinecorrection + +On the console we get these messages: + +\starttyping +metapost > message : processing a test graphic +metapost > warning : processing a test graphic +\stoptyping + +And in the \PDF\ file we will find: + +\starttyping +% mps graphic 1: begin +% mps graphic 1: test graphic +q 0 g 0 G 10 M 1 j 1 J +0.500000000 w +-14.173233032 -14.173233032 m +14.173233032 -14.173233032 l +14.173233032 14.173233032 l +-14.173233032 14.173233032 l +-14.173233032 -14.173233032 l +h S +0 g 0 G Q +% mps graphic 1: end +\stoptyping + +Here are some examples of constructed messages: + +\starttyping +message "2: okay (done)" ; +message "1: " & dq & "okay" & dq & " (done)" ; +message "3: " & quotation "okay" & " (done)" ; +message "3: " & quote "okay" & " (done)" ; +message "4: " & quotation 123 & " (done)" ; +message "5: " & quotation true & " (done)" ; +message "6: " & quote true & " (done)" ; +message "7: " & tostring true & " (done)" ; +message "8: " & tostring (1,2) & " (done)" ; +message "9: " & topair (1,2) & " (done)" ; +\stoptyping + +and this is what you get: + +\starttyping +metapost > message : 2: okay (done) +metapost > message : 1: "okay" (done) +metapost > message : 3: "okay" (done) +metapost > message : 3: 'okay' (done) +metapost > message : 4: "123" (done) +metapost > message : 5: "true" (done) +metapost > message : 6: 'true' (done) +metapost > message : 7: true (done) +metapost > message : 8: 1 2 (done) +metapost > message : 9: (1,2) (done) +\stoptyping + +\stopsection + +\startsection[title=Pens] + +A circular pen is applied to a path in a different way than for instance a +square pen. Circular pens are mapped onto \POSTSCRIPT\ pens while for other +pens an outline is calculated that gets filled. Take this code: + +\startbuffer[a] +\startMPcode + draw fullcircle xscaled 6cm yscaled 3cm + withpen pensquare scaled 5mm rotated 30 + withcolor .625yellow ; +\stopMPcode +\stopbuffer + +\startbuffer[b] +\startMPcode + draw envelope pensquare scaled 5mm rotated 30 of + (fullcircle xscaled 6cm yscaled 3cm) + withpen pencircle scaled 1mm + withcolor .375white ; +\stopMPcode +\stopbuffer + +\startbuffer[c] +\enabletrackers[metapost.forcestroke] +\startMPcode + draw fullcircle xscaled 6cm yscaled 3cm + withpen pensquare scaled 5mm rotated 30 + withcolor .625red ; +\stopMPcode +\disabletrackers[metapost.forcestroke] +\stopbuffer + +\typebuffer[a] + +and this: + +\typebuffer[b] + +and: + +\typebuffer[c] + +When we overlay these three we get. The envelope only returns the outer curve. + +\startlinecorrection[blank] +\startoverlay + {\getbuffer[a]} + {\getbuffer[b]} + {\getbuffer[c]} +\stopoverlay +\stoplinecorrection + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/metafun/metafun-document.tex b/doc/context/sources/general/manuals/metafun/metafun-document.tex new file mode 100644 index 000000000..bb5540850 --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/metafun-document.tex @@ -0,0 +1,118 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\startcomponent metafun-document + +\environment metafun-environment + +\startchapter[title={This document}] + +\startintro + +This document is produced in \CONTEXT\ and can serve as an example of how to +integrate \METAPOST\ graphics into \TEX. In this appendix we will discuss some +details of producing this document. + +\stopintro + +We did not use any special tricks, so most of the examples you have seen are +coded just as shown. We used buffers to ensure that the code used to produce the +accompanying graphic is identical to the typeset code in the document. Here is an +example. + +\starttyping +\startbuffer[dummy] +draw fullcircle + xscaled 3cm yscaled 2cm + rotatedaround(origin,30) + withcolor .625red ; +\stopbuffer +\stoptyping + +Instead of using \type {\getbuffer}, we used the following command: + +\starttyping +\startlinecorrection[blank] +\processMPbuffer[dummy] +\stoplinecorrection +\stoptyping + +The line correction commands take care of proper spacing around the graphic. If +you want to process more buffers at once, you can pass their names as a comma +separated list. Alternatively, we could have said: + +\starttyping +\startuseMPgraphic{dummy} + draw fullcircle + xscaled 3cm yscaled 2cm + rotatedaround(origin,30) + withcolor .625red ; +\stopuseMPgraphic +\stoptyping + +When including this graphic, we again take care of spacing. + +\starttyping +\startlinecorrection[blank] +\useMPgraphic{dummy} +\stoplinecorrection +\stoptyping + +The first version of this manual was produced with \PDFTEX\ and call|-|outs to +\METAPOST. Because the number of graphics is large, we processed that version +using the \type {--automp} directive (at that moment we were using \TEXEXEC). And +even then runtime was so unconveniently long that updating this manual became +less and less fun. The current version is produced with \LUATEX\ and \CONTEXT\ +\MKIV, which brings down the runtime (including runtime calls to independent +\CONTEXT\ runs for the outline examples) to some 45 seconds on a 2.2 Gig Dell +M90. Given that (at the time of writing this) over 1700 graphics are generated on +the fly, this is not bad at all. On my current machine, a Dell M6700 with an +Intel Core i7|-|3840QM running at 2.8 (3.9) Ghz (and Windows~8) the runtime of +the third version was just above 20 seconds all|-|in and some 25\percent\ less +when using \LUAJITTEX. When I started with updating to version 4 of this manual, +I timed about 15 seconds on the same machine (but with Windows-10) which means +that in the meantime the \CONTEXT|/|\LUATEX\ combination gained some 25\% +performance. Using the new Bash|-|On|-|Windows subsystem gives the same +performance. Of course each update adds pages so in the end we need more time +with each update but it remains a nice test case. The tight integration of \TEX, +\METAPOST\ and \LUA\ pays off. + +The document style is not that complicated. The main complication in such a +document is to make sure that \METAPOST\ is operating under the same font regime, +but in \MKIV\ this happens automatically. As document font we use the URW +Palatino for the running text combined with Computer Modern Typewriter. Because +this document is available as paper and screen document, some large graphics are +scaled down in the screen version. + +We don't use any special tricks in typesetting this document, but when we added +the section about transparency, a dirty trick was needed in a few cases in order to +get the described results. Because the screen document has gray backgrounds, +exclusive transparencies come out \quote {wrong}. In the function drawing example +we use the following trick to get a black background behind the graphics only. We +have a buffer that contains a few lines of code: + +% buffer only available in screen mode + +\starttyping +picture savedpicture ; +savedpicture := currentpicture ; +currentpicture := nullpicture ; +draw savedpicture withcolor black ; +draw savedpicture ; +\stoptyping + +Since we use buffers for the graphics as well, we can now process a buffer with +name \type {example} as follows: + +\starttyping +\processbuffer[example,wipe] +\stoptyping + +This means that the example code is included two times. After it is processed, we +recolor the currentpicture black, and after that we add the original picture once +again. + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/metafun/metafun-effects.tex b/doc/context/sources/general/manuals/metafun/metafun-effects.tex new file mode 100644 index 000000000..74e7d487e --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/metafun-effects.tex @@ -0,0 +1,2596 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +% graphic text takes 5 sec on 21 + +\startcomponent metafun-effects + +\environment metafun-environment + +\useMPlibrary[outlines] + +\startchapter[reference=sec:effects,title={Special effects}] + +\startintro + +Sometimes we want to go beyond \METAPOST's native features. Examples of such an +extension are \CMYK\ colors, shading and transparency. Although features like +this should be used with care, sometimes the documents look and feel can profit +from it. + +If you don't want the whole graphic, but only a part of it, clipping comes into +play. In addition to the standard clipping features, we can use \METAPOST\ to +provide a decent clipping path. In this chapter we will uncover the details. + +We will also introduce ways to include externally defined graphics and outline +fonts. We will demonstrate that within reasonable bounds you can manipulate such +graphics. + +\stopintro + +\startsection[title={Spot colors}] + +You can define spot and multitone colors directly in \METAFUN, although normally +you will do it at the \TEX\ end for consistency. At the \TEX\ end we define this: + +\startbuffer +\definecolor [SpotBlue] [c=1,m=.38,y=0,k=.64] +\definecolor [SpotYellow] [c=0,m=.28,y=1,k=.06] +\definemultitonecolor [MultiColor] [SpotBlue=.5,SpotYellow=.25] +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +draw image ( + fill unitsquare shifted (7,0) + withcolor namedcolor("MultiColor") ; + fill unitsquare shifted (6,0) + withcolor .6 * spotcolor("temp1",red) ; + fill unitsquare shifted (5,0) + withcolor .4 * spotcolor("temp1",red) ; + fill unitsquare shifted (4,0) + withcolor .5 * spotcolor("temp2",.5green) ; + fill unitsquare shifted (3,0) + withcolor .5 * spotcolor("temp3",green) ; + fill unitsquare shifted (2,0) + withcolor multitonecolor("temp4",blue/2,yellow/2,green/2,magenta/3) ; +) xsized TextWidth ; +\stopbuffer + +Next we process this graphic: + +\typebuffer + +and get: + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +\stopsection + +\startsection[title={Transparency}] + +\index{transparency} + +{\em In the screen version we use a light gray background color. As a result, +some of the transparency methods demonstrated here give unexpected results. The +A4 version of this document demonstrates the real effects.} + +Although transparent colors have been around for some time already, it was only +around 2000 that they made it as a high level feature into document format +languages like \PDF. Supporting such a feature at a higher abstraction level is +not only more portable, but also less sensitive for misinterpretation. + +\startbuffer[mpdef] +vardef ColorCircle (expr method, factor, ca, cb, cc) = + save u, p ; path p ; p := fullcircle shifted (1/4,0) ; + image + ( fill p rotated 90 withcolor ca withtransparency (method,factor) ; + fill p rotated 210 withcolor cb withtransparency (method,factor) ; + fill p rotated 330 withcolor cc withtransparency (method,factor) ; ) +enddef ; +\stopbuffer + +\typebuffer[mpdef] + +\startbuffer[mp] +draw ColorCircle ("normal", .5, red, green, blue) xsized 3cm ; +currentpicture := currentpicture shifted (-4cm,0) ; +draw ColorCircle ("exclusion", .5, red, green, blue) xsized 3cm ; +currentpicture := currentpicture shifted (-4cm,0) ; +draw ColorCircle ("exclusion", 1, red, green, blue) xsized 3cm ; +\stopbuffer + +\typebuffer[mp] + +\startlinecorrection[blank] +\processMPbuffer[mpdef,mp] +\stoplinecorrection + +\startbuffer[mp] +cmykcolor xcyan ; xcyan := (1,0,0,0) ; +cmykcolor xmagenta ; xmagenta := (0,1,0,0) ; +cmykcolor xyellow ; xyellow := (0,0,1,0) ; + +draw ColorCircle ("exclusion", .5, xcyan, xmagenta, xyellow) xsized 3cm ; +\stopbuffer + +\typebuffer[mp] + +\startlinecorrection[blank] +\processMPbuffer[mpdef,mp] +\stoplinecorrection + +You can be tempted to use transparency as a convenient way to achieve soft +colors. In that case you should be aware of the fact that rendering transparent +colors takes more time than normal colors \footnote {When your printer does not +support this feature natively, the intermediate (\POSTSCRIPT) file send to the +printing engine is also larger.} + +Fortunatey, \METAPOST\ provides a similar mechanism. The last circle in the +following row demonstrates how we can trigger colors proportionally to other +colors. Normally \type {background} is white, but you can set predefined color +variables to another value. + +\startbuffer[mp] +path p ; p := fullcircle scaled 2cm ; +fill p shifted (0cm,0) withcolor blue ; +fill p shifted (3cm,0) withcolor .5blue ; +fill p shifted (6cm,0) withcolor transparent (1,0.5,blue) ; +fill p shifted (9cm,0) withcolor .5[blue,white] ; +\stopbuffer + +\typebuffer[mp] + +\startlinecorrection[blank] +\processMPbuffer[mp] +\stoplinecorrection + +The next series demonstrates that we use the complementary factor \type {.7} in +the \METAPOST\ soft color to achieve the same softness as the \type {.3} +transparency. + +\startbuffer[mp] +path p ; p := fullcircle scaled 2cm ; +fill p shifted (0cm,0) withcolor red ; +fill p shifted (3cm,0) withcolor .7red ; +fill p shifted (6cm,0) withcolor transparent (1,0.3,red) ; +fill p shifted (9cm,0) withcolor .7[red,white] ; +\stopbuffer + +\typebuffer[mp] + +\startlinecorrection[blank] +\processMPbuffer[mp] +\stoplinecorrection + +\startbuffer[mp] +vardef SampleText (expr t, c) = + save p ; picture p ; + p := image (draw t infont "\truefontname{Regular}") ; + draw (p shifted (- xpart center p,0)) scaled 5 withcolor c; +enddef ; + +SampleText ("Much Of This" , transparent(1, .5, red )) ; +SampleText ("Functionality" , transparent(1, .5, green)) ; +SampleText ("Was Written" , transparent(1, .5, blue )) ; +SampleText ("While Listening", transparent(1, .5, cmyk(1,0,0,0))) ; +SampleText ("To the CD's Of" , transparent(1, .5, cmyk(0,1,0,0))) ; +SampleText ("Tori Amos" , transparent(1, .5, cmyk(0,0,1,0))) ; +\stopbuffer + +So far we have applied transparent colors to shapes but text can also be the +target. + +\typebuffer[mp] + +The source code of this example illustrates that the \CMYK\ color space is also +supported. The \type {\truefontname} macro communicates the running font from +\TEX\ to \METAPOST. Instead of such low level code one can of course also use the +\type {textext} macro. + +\startbuffer[mp] +vardef SampleText (expr t) = + draw textext(t) scaled 5 ; +enddef ; + +SampleText ("\colored[a=1,t=.5,r=1]{Much Of This}") ; +SampleText ("\colored[a=1,t=.5,g=1]{Functionality}") ; +SampleText ("\colored[a=1,t=.5,b=1]{Was Written}") ; +SampleText ("\colored[a=1,t=.5,c=1]{While Listening}") ; +SampleText ("\colored[a=1,t=.5,m=1]{To the CD's Of}") ; +SampleText ("\colored[a=1,t=.5,y=1]{Tori Amos}") ; +\stopbuffer + +However, as we do the typesetting in \TEX\ in \MKIV\ this is the way to go: + +\typebuffer[mp] + +As expected we get: + +\startlinecorrection[blank] +\processMPbuffer[mp] +\stoplinecorrection + +Currently the 12 in \PDF\ available transparency methods are supported. \footnote +{In the future we may also support more control over the individual methods.} You +can use both numbers and names. As you may expect, both \CONTEXT\ and \METAFUN\ +support transparency in the same way. \in {Figure} [fig:transparencies] shows how +the method affects the result. + +\startuseMPgraphic{test} +numeric u ; u := if lua.mp.mode("screen") : 12mm else : 20mm fi ; + +path p ; p := fullcircle scaled u shifted (u/4,0); + +% cmykcolor xyellow ; xyellow := (0,0,1,0) ; +% color xgreen ; xgreen := (0,1,0) ; +% color xblue ; xblue := (0,0,1) ; + +% fill p rotated 90 withcolor transparent("\MPvar{a}",.5,xyellow) ; +% fill p rotated 210 withcolor transparent("\MPvar{a}",.5,xgreen) ; +% fill p rotated 330 withcolor transparent("\MPvar{a}",.5,xblue) ; + +fill p rotated 90 withcolor (0,0,1,0) withtransparency("\MPvar{a}",.5) ; +fill p rotated 210 withcolor (0,1,0) withtransparency("\MPvar{a}",.5) ; +fill p rotated 330 withcolor (0,0,1) withtransparency("\MPvar{a}",.5) ; +\stopuseMPgraphic + +\startplacefigure[location=here,reference=fig:transparencies,title={The 12 transparency alternatives by name.}] + \doifelsemode {screen} { + \setupcombination[nx=8,ny=2] + } { + \setupcombination[nx=4,ny=4] + } + \startcombination + {\useMPgraphic{test}{a=normal}} {\tttf normal} + {\useMPgraphic{test}{a=multiply}} {\tttf multiply} + {\useMPgraphic{test}{a=screen}} {\tttf screen} + {\useMPgraphic{test}{a=overlay}} {\tttf overlay} + {\useMPgraphic{test}{a=softlight}} {\tttf softlight} + {\useMPgraphic{test}{a=hardlight}} {\tttf hardlight} + {\useMPgraphic{test}{a=colordodge}} {\tttf colordodge} + {\useMPgraphic{test}{a=colorburn}} {\tttf colorburn} + {\useMPgraphic{test}{a=darken}} {\tttf darken} + {\useMPgraphic{test}{a=lighten}} {\tttf lighten} + {\useMPgraphic{test}{a=difference}} {\tttf difference} + {\useMPgraphic{test}{a=exclusion}} {\tttf exclusion} + {\useMPgraphic{test}{a=hue}} {\tttf hue} + {\useMPgraphic{test}{a=saturation}} {\tttf saturation} + {\useMPgraphic{test}{a=color}} {\tttf color} + {\useMPgraphic{test}{a=luminosity}} {\tttf luminosity} + \stopcombination +\stopplacefigure + +In \CONTEXT\ a transparent color is defined in a similar way as \quote {normal} +colors. The transparency method is specified with the \type {a} key (either by +number or by name) and the factor \type {t}. + +\startbuffer +\definecolor [tred] [r=1,t=.5,a=exclusion] +\definecolor [tgreen] [g=1,t=.5,a=exclusion] +\definecolor [tblue] [b=1,t=.5,a=exclusion] +\stopbuffer + +\typebuffer \getbuffer + +Both keys are needed. You can define your own symbolic names using: + +\starttyping +\definetransparency [myowndefault] [1] +\stoptyping + +The \type {\MPcolor} macro passes a color from \CONTEXT\ to \METAPOST, including +the transparency specification. + +\startbuffer[mp] +u := 2cm ; path p ; p := fullcircle scaled u shifted (u/4,0); + +fill p rotated 90 withcolor \MPcolor{tred} ; +fill p rotated 210 withcolor \MPcolor{tgreen} ; +fill p rotated 330 withcolor \MPcolor{tblue} ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer[mp] +\stoplinecorrection + +Of course this also works well for \CMYK\ colors. + +\startbuffer +\definecolor[tred] [c=1,k=.2,t=.5,a=1] +\definecolor[tgreen][m=1,k=.2,t=.5,a=1] +\definecolor[tblue] [y=1,k=.2,t=.5,a=1] +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer[mp] +\stoplinecorrection + +Gray scales work as well: + +\startbuffer +\definecolor[ta][s=.9,t=.7,a=11] +\definecolor[tb][s=.7,t=.7,a=11] +\definecolor[tc][s=.5,t=.7,a=11] +\stopbuffer + +\typebuffer \getbuffer + +We apply this to some text. By using an overlay we can conveniently explore the +difference in fonts. + +% \startbuffer +% def SampleText (expr s, f, c) = +% draw s infont f scaled 5 withcolor c ; +% enddef ; + +% SampleText("Hello", "\truefontname{Regular}" , \MPcolor{ta}) ; +% SampleText("Hello", "\truefontname{RegularBold}" , \MPcolor{tb}) ; +% SampleText("Hello", "\truefontname{RegularSlanted}", \MPcolor{tc}) ; +% \stopbuffer + +\startbuffer +draw textext("\color[ta]{\tf Hello}") scaled 5 ; +draw textext("\color[tb]{\bf Hello}") scaled 5 ; +draw textext("\color[tc]{\sl Hello}") scaled 5 ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +\stopsection + +\startsection[title={Shading}] + +\startsubsection[title=Introduction] + +\index{shading} + +In this section we introduce different kinds of shading. Since \METAPOST\ does +not support this feature directly, we have to fall back on a few tricks. For the +moment shading is only supported in \PDF. In the following examples, we will use +the next three colors: + +\startbuffer +\definecolor[a][darkyellow] +\definecolor[b][s=.8] +\definecolor[c][darkred] +\stopbuffer + +\typebuffer + +\getbuffer + +Shading support evolved in steps and alongside development of the backend code. Also, +as it became more used a second interface came available. We discuss both here. + +\stopsubsection + +\startsubsection[title=The old method] + +First we discuss the old method which is still valid and also available in +\MKII. It illustrates some of the principles. + +\startbuffer[a] +\startuniqueMPgraphic{CircularShade} + path p ; + p := unitsquare xscaled \overlaywidth yscaled \overlayheight ; + circular_shade(p,0,\MPcolor{a},\MPcolor{b}) ; +\stopuniqueMPgraphic + +\startuniqueMPgraphic{LinearShade} + path p ; + p := unitsquare xscaled \overlaywidth yscaled \overlayheight ; + linear_shade(p,0,\MPcolor{a},\MPcolor{b}); +\stopuniqueMPgraphic +\stopbuffer + +\startbuffer[b] +\defineoverlay[circular shade][\uniqueMPgraphic{CircularShade}] +\defineoverlay[linear shade] [\uniqueMPgraphic{LinearShade}] +\stopbuffer + +\startbuffer[c] +\framed + [background=circular shade,frame=off] + {\bf \white Hi there, I'm Circular!} +\stopbuffer + +\startbuffer[d] +\framed + [background=linear shade,frame=off] + {\bf \white Whow, this is Linear!} +\stopbuffer + +A shade is a fill with a stepwise change in color. In \POSTSCRIPT\ (level 2), the +way this color changes can be circular, linear, or according to a user defined +function. Circular and linear shades look like this: + +\startlinecorrection[blank] +\getbuffer[a,b,c] +\stoplinecorrection + +\startlinecorrection[blank] +\getbuffer[a,b,d] +\stoplinecorrection + +As you can see, the shade lays behind the text, as a background overlay. These +overlays are unique \METAPOST\ graphics, so they will adapt themselves to the +dimensions of the foreground. + +\typebuffer[b] + +The two framed texts are defined as: + +\typebuffer[c] + +and: + +\typebuffer[d] + +We still have to define the graphics. Here we use a macro that takes four +arguments: a path, a number identifying the center of shading, and the colors to +start and end with. + +\typebuffer[a] + +The \METAPOST\ macros, \type {circular_shade} and \type {linear_shade}, add +information to the \METAPOST\ output file, which is interpreted by the converter +built in \CONTEXT. Shading comes down to interpolation between two or more points +or user supplied ranges. A poor mans way of doing this, is to build the graphics +piecewise with slightly changing colors. But, instead of \quote {manually} +stepping through the color values, we can use the more efficient and generalized +\POSTSCRIPT\ level~2 and \PDF\ level~1.3 shading feature. + +\def\SomeShade#1#2#3% waarom unique ? + {\startuniqueMPgraphic{shade-#1} + width := \overlaywidth ; + height := \overlayheight ; + path p ; p := unitsquare xscaled width yscaled height ; + #2_shade(p,#3,\MPcolor{a},\MPcolor{b}) ; + \stopuniqueMPgraphic + \defineoverlay[shade-#1][\uniqueMPgraphic{shade-#1}]% + \framed[background=shade-#1,width=2cm,height=2cm,frame=off]{}} + +\startlinecorrection[blank] +\startcombination[5*1] + {\SomeShade{20}{circular}{0}} {circular 0} + {\SomeShade{21}{circular}{1}} {circular 1} + {\SomeShade{22}{circular}{2}} {circular 2} + {\SomeShade{23}{circular}{3}} {circular 3} + {\SomeShade{24}{circular}{4}} {circular 4} +\stopcombination +\stoplinecorrection + +\startlinecorrection[blank] +\startcombination[4*2] + {\SomeShade{32}{linear}{1}} {linear 1} + {\SomeShade{32}{linear}{2}} {linear 2} + {\SomeShade{33}{linear}{3}} {linear 3} + {\SomeShade{34}{linear}{4}} {linear 4} + {\SomeShade{35}{linear}{5}} {linear 5} + {\SomeShade{36}{linear}{6}} {linear 6} + {\SomeShade{37}{linear}{7}} {linear 7} + {\SomeShade{38}{linear}{8}} {linear 8} +\stopcombination +\stoplinecorrection + +% % This limitation si no longer present in mpiv. +% +% Shading is not a \METAPOST\ feature, which means that it has to be implemented +% using so called specials, directives that end up in the output file. +% Unfortunately these are not coupled to the specific path, which means that we +% have to do a significant amount of internal bookkeeping. Also, in \PDF\ we have +% to make sure that the graphics and their resources (being the shading functions) +% are packaged together. +% +% Because of this implementation, shading may behave somewhat unexpected at times. +% A rather normal case is the next one, where we place 5~shaded circles in a row. +% +% \startbuffer +% path p ; p := fullcircle scaled 1cm ; +% for i=0 step 2cm until 8cm : +% circular_shade(p shifted (i,0),0,\MPcolor{a},\MPcolor{b}) ; +% endfor ; +% \stopbuffer +% +% \typebuffer +% +% \startlinecorrection[blank] +% \processMPbuffer +% \stoplinecorrection +% +% At first sight, in the next situation, we would expect something similar, because +% we simply copy the same circle 5~times. However, due to the way we have +% implemented shading in \CONTEXT, we do indeed copy the circles, but the shade +% definition is frozen and the same one is used for all 5~circles. This means that +% the center of the shading stays at the first circle. +% +% \startbuffer +% circular_shade(fullcircle scaled 1cm,0,\MPcolor{a},\MPcolor{b}) ; +% picture s ; s := currentpicture ; currentpicture := nullpicture ; +% for i=0 step 2cm until 8cm : +% addto currentpicture also s shifted (i,0) ; +% endfor ; +% \stopbuffer +% +% \typebuffer +% +% \startlinecorrection[blank] +% \processMPbuffer +% \stoplinecorrection +% +% Unlike \TEX, \METAPOST\ does not keep its specials attached to the current path, +% and flushes them before the graphic data. Since we use these specials to register +% shading information, it is rather hard to tightly connect a specific shade with a +% certain fill, especially if an already performed fill is not accessible, which is +% the case when we copy a picture. +% +% This may seem a disadvantage, but fortunately it also has its positive side. In +% the next example we don't copy, but reuse an already defined shade. By storing +% the reference to this shade, and referring to it by using \type {withshade}, we +% can use a shade that operates on multiple shapes. + +\startbuffer +sh := define_circular_shade + (origin,origin,0,8cm,\MPcolor{a},\MPcolor{b}) ; +for i=0 step 2cm until 8cm : + fill fullcircle scaled 1cm shifted (i,0) withshade sh ; +endfor ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +The low level macro \type {define_circular_shade} is fed with two pairs (points), +two radius, and two colors. The shade is distributed between the colors according +to the radius. + +Shading can hardly be called an easy issue. The macros that we provide here are +in fact simplifications, which means that at a lower level, one can do more +advanced things. Here we limit ourselves to the more common cases. In the +previous examples, we used an arrow to indicate the direction and magnitude of +the shade. The next macro demonstrates the principles in a different way. + +\startbuffer[a] +def test_shade (expr a, b, ra, rb) = + pickup pencircle scaled 1mm ; + + color ca ; ca := \MPcolor{a} ; + color cb ; cb := \MPcolor{b} ; + color cc ; cc := \MPcolor{c} ; + + path pa ; pa := fullcircle scaled 2ra shifted a ; + path pb ; pb := fullcircle scaled 2rb shifted b ; + + sh := define_circular_shade(a,b,ra,rb,ca,cb) ; + + fill pb withshade sh ; + draw pb withcolor cc ; + draw pa withcolor cc ; +enddef ; +\stopbuffer + +\typebuffer[a] + +The shade is distributed between two circles, each with a radius and center +point. All four can be set, but as the next calls demonstrate, we can normally do +with less, which is why we provided the macro with less parameters. + +\startbuffer[b] +test_shade(origin, origin, 0cm, 1cm) ; +\stopbuffer +\startbuffer[c] +test_shade(origin, origin, .25cm, 1cm) ; +\stopbuffer +\startbuffer[d] +test_shade(origin, origin, .50cm, 1cm) ; +\stopbuffer + +\startbuffer[f] +\startlinecorrection[blank] +\hbox + {\processMPbuffer[a,b]\quad + \processMPbuffer[a,c]\quad + \processMPbuffer[a,d]} +\stoplinecorrection +\stopbuffer + +\typebuffer[b,c,d] \getbuffer[f] + +\startbuffer[b] +test_shade(origin, origin shifted (.25cm,0), 0cm, 1cm) ; +\stopbuffer +\startbuffer[c] +test_shade(origin, origin shifted (.25cm,0), .25cm, 1cm) ; +\stopbuffer +\startbuffer[d] +test_shade(origin, origin shifted (.25cm,0), .50cm, 1cm) ; +\stopbuffer + +\typebuffer[b,c,d] \getbuffer[f] + +\startbuffer[b] +test_shade(origin shifted (.25cm,0), origin, 0cm, 1cm) ; +\stopbuffer +\startbuffer[c] +test_shade(origin shifted (.25cm,0), origin, .25cm, 1cm) ; +\stopbuffer +\startbuffer[d] +test_shade(origin shifted (.25cm,0), origin, .50cm, 1cm) ; +\stopbuffer + +\typebuffer[b,c,d] \getbuffer[f] + +\startbuffer[a] +def test_shade (expr a, b) = + pickup pencircle scaled 1mm ; + + color ca ; ca := \MPcolor{a} ; + color cb ; cb := \MPcolor{b} ; + color cc ; cc := \MPcolor{c} ; + + sh := define_linear_shade(a,b,ca,cb) ; + + fill fullsquare scaled 2cm withshade sh ; + draw a withcolor cc ; + draw b withcolor cc ; +enddef ; +\stopbuffer + +In a similar fashion, we can define a linear shade. This time we only pass two +points and two colors. + +\typebuffer[a] + +Although one can control shading to a large extend, in practice only a few cases +really make sense. + +\startbuffer[b] +test_shade(origin, origin shifted (1cm,0)) ; +\stopbuffer +\startbuffer[c] +test_shade(origin shifted (-1cm,0), origin shifted (1cm,0)) ; +\stopbuffer +\startbuffer[d] +test_shade(origin shifted (-1cm,-1cm), origin shifted (1cm,1cm)) ; +\stopbuffer + +\startbuffer[f] +\startlinecorrection[blank] +\hbox + {\processMPbuffer[a,b]\quad + \processMPbuffer[a,c]\quad + \processMPbuffer[a,d]} +\stoplinecorrection +\stopbuffer + +\typebuffer[b,c,d] \getbuffer[f] + +\stopsubsection + +\startsubsection[title=The new method] + +By now the shader macros are rather advanced and specifications are easier than +before. Here we discuss the new method. An example is: + +\startbuffer +fill fullsquare xyscaled (TextWidth,1cm) + withshademethod "linear" + withshadevector (1,0) + withshadecolors (darkred,darkgreen) +; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] + \processMPbuffer +\stoplinecorrection + +There are several properties that can be set: + +\starttabulate[|l|p|] +\NC domain \NC The range over which the colors run, with a minimum of 0 and maximum of 1. \NC \NR +\NC color \NC A color to start from and one to end with, we default from black to white. \NC \NR +\NC type \NC The shading can be linear or circular. \NC \NR +\NC center \NC The origin of the shade vector. \NC \NR +\NC radius \NC The radius vector of a circular shade. \NC \NR +\NC vector \NC Where we start and end the shading. \NC \NR +\stoptabulate + +For a linear shade the centers are the lower left and upper right corners, for a +circular shade it's the center of the path. For a circular shade the radius runs +from zero to the maximum distance from the center as determined by the +boundingbox. + +The vector is used as follows: the first coordinate (xpart) determines the point +on the path where we start, the second coordinate (ypart) the point on the +path where we end. + +\startbuffer[a] +fill fullsquare xyscaled (TextWidth,1cm) + withshademethod "linear" + withshadevector (1,0) + withshadecolors (darkred,darkgreen) +; +\stopbuffer + +\startbuffer[b] +draw fullsquare xyscaled (TextWidth,1cm) + shownshadevector (1,0) + withpen pencircle scaled 2 + withcolor .5white ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] + \processMPbuffer[a,b] +\stoplinecorrection + +In the end only the x coordinate matters, but using a point on the path sort of +fits in \METAPOST. In the case of a rectangle we have 4 points while circle has 8 +points. + +\startbuffer[a] +fill fullcircle xyscaled (TextWidth,1cm) + withshademethod "linear" + withshadevector (2,4) + withshadecolors (darkred,darkgreen) +; +\stopbuffer + +\startbuffer[b] +draw fullcircle xyscaled (TextWidth,1cm) + shownshadevector (2,4) + withpen pencircle scaled 2 + withcolor .5white ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] + \processMPbuffer[a,b] +\stoplinecorrection + +A triangle has three points. Using 1 and 2 as second vector value gives the same +results as do values in the range 0 upto 1 and 2 upto 3 (0 again). + +\startbuffer[a] +fill fulltriangle xyscaled (TextWidth,1cm) + withshademethod "linear" + withshadevector (0.25,0.75) + withshadecolors (darkred,darkgreen) +; +\stopbuffer + +\startbuffer[b] +draw fulltriangle xyscaled (TextWidth,1cm) + shownshadevector (0.25,0.75) + withpen pencircle scaled 2 + withcolor .5white ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] + \processMPbuffer[a,b] +\stoplinecorrection + +The shadevector relates to (the x coordinates of) points on the path. A variant is +to use the boundingbox: + +\startbuffer[a] +for i=1 upto 3 : + fill fulltriangle xyscaled (TextWidth,1cm) + shifted (0,-i*15mm) + withshademethod "linear" + withshadedirection (1,1-i/4) + withshadecolors (darkgreen,darkblue) + ; +endfor ; +\stopbuffer + +\startbuffer[b] +for i=1 upto 3 : + draw fulltriangle xyscaled (TextWidth,1cm) + shifted (0,-i*15mm) + shownshadevector (1,1-i/4) + withpen pencircle scaled 2 + withcolor .5white ; +endfor ; +\stopbuffer + +\typebuffer[a] + +\startlinecorrection[blank] + \processMPbuffer[a,b] +\stoplinecorrection + +So, where a vector is defined as going from {\em point xpart a of pth} to +{\em point ypart a of pth}, a direction goes from {\em point xpart a of +boundingbox pth} to {\em point ypart a of boundingbox pth}. + +To make life convenient we provide a few constants that indicate directions: + +\starttyping +pair shadedup ; shadedup := (0.5,2.5) ; +pair shadeddown ; shadeddown := (2.5,0.5) ; +pair shadedleft ; shadedleft := (1.5,3.5) ; +pair shadedright ; shadedright := (3.5,1.5) ; +\stoptyping + +\startbuffer[a] +for d = shadedup, shadeddown, shadedleft, shadedright : + fill fullsquare xyscaled (TextWidth,1cm) + withshademethod "linear" + withshadedirection d + withshadecolors (darkgreen,darkblue) + ; + currentpicture := currentpicture shifted (0,15mm) ; +endfor ; +\stopbuffer + +\startbuffer[b] +currentpicture := currentpicture shifted (0,-60mm) ; +for d = shadedup, shadeddown, shadedleft, shadedright : + draw fullsquare xyscaled (TextWidth,1cm) + shownshadedirection d + withpen pencircle scaled 2 + withcolor .5white ; + currentpicture := currentpicture shifted (0,15mm) ; +endfor ; +\stopbuffer + +\typebuffer[a] + +\startlinecorrection[blank] + \processMPbuffer[a,b] +\stoplinecorrection + +In case of a circular shade another method comes in handy: + +\startbuffer[a] +fill fullcircle xyscaled (TextWidth,4cm) + withshademethod "circular" + withshadecenter (.7,.9) + withshadecolors (darkblue,darkyellow) +; +\stopbuffer + +\startbuffer[b] +draw fullcircle xyscaled (TextWidth,4cm) + shownshadecenter (.7,.9) + withpen pencircle scaled 2 + withcolor .5white ; +\stopbuffer + +\typebuffer + +Here the values relate to the center of path i.e.\ they shift the center by the +given fraction of the width and height of the boundingbox devided by 2. + +\startlinecorrection[blank] + \processMPbuffer[a,b] +\stoplinecorrection + +You can set a center directly i.e.\ unrelated to the center of the path as +follows: + +\startbuffer[a] +fill fullcircle xyscaled (TextWidth,4cm) + withshademethod "circular" + withshadeorigin (-30mm,-15mm) + withshadecolors (darkblue,darkyellow) +; +\stopbuffer + +\startbuffer[b] +draw fullcircle xyscaled (TextWidth,4cm) + shownshadeorigin (-30mm,-15mm) + withpen pencircle scaled 2 + withcolor .5white ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] + \processMPbuffer[a,b] +\stoplinecorrection + +In a similar way you can set an explicit radius: + +\startbuffer[a] +fill fullcircle xyscaled (TextWidth,1cm) + withshademethod "circular" + withshaderadius (10mm,50mm) + withshadecolors (darkblue,darkyellow) +; +currentpicture := currentpicture shifted (0,15mm) ; +fill fullcircle xyscaled (TextWidth,1cm) + withshademethod "circular" + withshaderadius (50mm,10mm) + withshadecolors (darkgreen,darkred) +; +currentpicture := currentpicture shifted (0,15mm) ; +fill fullcircle xyscaled (TextWidth,1cm) + withshademethod "circular" + withshaderadius (TextWidth/3,0mm) + withshadecolors (darkmagenta,darkcyan) +; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] + \processMPbuffer[a] +\stoplinecorrection + +A more fancy feature is combined shades. This works as follows: + +\startbuffer[a] +fill fullsquare xyscaled (TextWidth,1cm) + withshademethod "linear" + withshadevector (0,1) + withshadestep ( + withshadefraction .3 + withshadecolors (red,green) + ) + withshadestep ( + withshadefraction .5 + withshadecolors (green,blue) + ) + withshadestep ( + withshadefraction .7 + withshadecolors (blue,red) + ) + withshadestep ( + withshadefraction 1 + withshadecolors (red,yellow) + ) +; +\stopbuffer + +\typebuffer[a] + +By stepwise defining the colored bands you get: + +\startlinecorrection[blank] + \processMPbuffer[a] +\stoplinecorrection + +Shades work well with colors and transparencies. This involves quite some +resource managament in the backend but it's hidden by the interface. + +\startbuffer[a] +fill fullsquare scaled 5cm + withshademethod "linear" + withshadefactor 1 + withshadedomain (0,1) + withshadevector (0.5,2.75) + withshadecolors (red,green) ; + +fill fullcircle scaled 5cm + withshademethod "circular" + withshadefactor 1 + withshadedomain (0,1) + withshadecenter (.25,.25) + withshadecolors (green,blue) ; + +fill fulltriangle scaled 5cm + withshademethod "circular" + withshadefactor 1 + withshadedomain (0,1) + withshadecenter (.25,.25) + withshadecolors (blue,yellow) ; +\stopbuffer + +\startbuffer[b] +fill fullsquare scaled 5cm + withcolor white ; +fill fullsquare scaled 5cm + withshademethod "linear" + withshadevector (0.5,2.75) + withshadecolors (red,green) + withtransparency (1,.5) ; + +fill fullcircle scaled 5cm + withcolor white ; +fill fullcircle scaled 5cm + withshademethod "circular" + withshadecenter (.25,.25) + withshadecolors (green,blue) + withtransparency (1,.5) ; + +fill fulltriangle scaled 5cm + withcolor white ; +fill fulltriangle scaled 5cm + withshademethod "circular" + withshadecenter (.25,.25) + withcolor blue shadedinto yellow + withtransparency (1,.5) ; +\stopbuffer + +\startbuffer[c] +fill fullsquare scaled 5cm + withshademethod "linear" + withshadevector (0.5,2.75) + withshadecolors (red,green) + withtransparency (1,.5) ; + +fill fullcircle scaled 5cm + withshademethod "circular" + withshadecenter (.25,.25) + withcolor green shadedinto blue + withtransparency (1,.5) ; + +fill fulltriangle scaled 5cm + withshademethod "circular" + withshadecenter (.25,.25) + withcolor blue shadedinto yellow + withtransparency (1,.5) ; +\stopbuffer + +Here are some shades without transparency: + +\typebuffer[a] + +When the background is white, transparency is just a way to achieve soft colors. +We leave out the defaults. + +\typebuffer[b] + +Real transparency will show op darker due to the accumulated colors. This time we +demonstrate an alternative color specification. + +\typebuffer[c] + +\startplacefigure[reference=shades:transparency,title={Transparency applied to shades.}] + \startcombination[3*1] + {\processMPbuffer[a]} {no transparency} + {\processMPbuffer[b]} {transparency on white} + {\processMPbuffer[c]} {real transparency} + \stopcombination +\stopplacefigure + +Within reasonable bounds you can move around and adapt shaded paths but you need +to keep in mind that due to the fact that we are dealing with relatively complex +data structures there are some limits. For instance it is possible to define a +shade as (kind of) variable and reuse it. it's also possible then to overload +some properties. + +% % still supported but not advertized: +% +% numeric n ; n = define_linear_shade (center fullcircle,center fullsquare,red,green) ; +% +% fill fullcircle randomized 1cm xyscaled(10cm,8cm) withshade n ; + +\startbuffer +defineshade myshade + withshademethod "circular" + withshadefactor 1 + withshadedomain (0,1) + withshadecolors (black,white) + withtransparency (1,.5) +; + +for i=1 upto 5 : + fill fullcircle randomized 1 xyscaled(5cm,3cm) + shaded myshade ; +endfor ; + +draw image ( + for i=1 upto 5 : + fill fullcircle randomized 1 + shaded myshade + withshadecolors (yellow,blue) ; + endfor ; +) xyscaled(5cm,3cm) shifted (5cm,0) ; +\stopbuffer + +\typebuffer + +We get two groups of five overlayed shades here, one with a different color. The +shade properties can only be applied to paths (see \in {figure} +[fig:shades:defined]). + +\startplacefigure[reference=fig:shades:defined,title={Reusing defined shaded.}] + \processMPbuffer +\stopplacefigure + +In older versions one could not reposition or scale a shaded path without losing +or crippling the shade properties. Nowadays this is no longer a limitation, as we +demonstrate in the following examples. You can disable this feature if wanted. +The results are shown in \in {figure} [fig:shades:transform]. Without the +transform the vectors and such are kept which might be useful in special cases. + +\startbuffer[a] +fill fullsquare xyscaled (15mm, 15mm) + withshademethod "linear" + withshadedirection shadedright + withshadecolors (red,(1,1,1)) ; + +fill fullsquare xyscaled (10mm, 10mm) + withshademethod "circular" + withshadecolors (green,blue) ; + +currentpicture := currentpicture xysized (.4TextWidth,30mm) ; +currentpicture := currentpicture shifted (5mm,5mm) ; +\stopbuffer + +\typebuffer[a] + +The transform can be ignored with: + +\startbuffer[b] +fill fullsquare xyscaled (15mm, 15mm) + withshademethod "linear" + withshadetransform "no" + withshadedirection shadedright + withshadecolors (red,(1,1,1)) ; + +fill fullsquare xyscaled (10mm, 10mm) + withshademethod "circular" + withshadetransform "no" + withshadecolors (green,blue) ; + +currentpicture := currentpicture xysized (.4TextWidth,30mm) ; +currentpicture := currentpicture shifted (5mm,5mm) ; +\stopbuffer + +\typebuffer[b] + +\startplacefigure[reference=fig:shades:transform,title={Shifting and scaling shades.}] + \startcombination + {\processMPbuffer[a]} {with transform} + {\processMPbuffer[b]} {without transform} + \stopcombination +\stopplacefigure + +\stopsubsection + +\stopsection + +\startsection[title={Clipping}] + +\index{clipping} + +In this section we will use the graphic representation (although simplified) of a +Dutch cow to demonstrate clipping. + +\startbuffer +\placefigure + {A cow.} + {\externalfigure[cow-fun.mps][width=4cm]} +\stopbuffer + +\getbuffer + +Since this cow is defined as a \METAPOST\ graphic, we use the suffix \type {mps} +instead of \type {eps} or a number, although \CONTEXT\ will recognize each as +being \METAPOST\ output. The placement of the cow is defined as: + +\typebuffer + +Clipping is combined with a matrix, as in \in {figure} [fig:clipped cow 1]. The +content to be clipped is divided in \type {nx} by \type {ny} rectangles. For +instance, \type {nx=5} and \type {ny=8} will produce a 40~cell grid with +5~columns of 8~rows. + +\startbuffer +\startbuffer +\setupclipping[nx=3,ny=2] +\startcombination + {\clip[x=1,y=1]{\externalfigure[cow-fun.mps][width=4cm]}} {1,1} + {\clip[x=3,y=1]{\externalfigure[cow-fun.mps][width=4cm]}} {3,1} +\stopcombination +\stopbuffer + +\placefigure + [here][fig:clipped cow 1] + {A clipped cow.}{\getbuffer} +\stopbuffer + +\getbuffer + +Here we have divided the cow in six cells, so that we can clip its head and tail. +This kind of clipping enables you to zoom in or focus on a specific part of a +graphic. + +\typebuffer + +Alternatively, we can specify a \type {width}, \type {height}, \type {hoffset} +and \type {voffset}, as demonstrated in \in {figure} [fig:clipped cow 2]. + +\startbuffer +\placefigure + [here][fig:clipped cow 2] + {Another clipped cow.} + {\clip + [width=2cm,height=2cm,hoffset=0cm,voffset=0cm] + {\externalfigure[cow-fun.mps][width=4cm]}} +\stopbuffer + +\getbuffer + +\typebuffer + +Because \METAPOST\ supports clipping, it will be no surprise that both techniques +can be combined. In the next example we will zoom in on the head of the cow. We +also use this opportunity to demonstrate how you can package a clip in a figure +definition. + +\startbuffer +\startMPclip{head clip} + w := \width ; h := \height ; + clip currentpicture to + ((0,h)--(w,h){down}..{left}(0,0)--cycle) ; +\stopMPclip + +\placefigure + [here][fig:circular clipped cowhead] + {A quarter circle applied to a cows head.} + {\ruledhbox + {\clip + [nx=2,ny=2,x=1,y=1,mp=head clip] + {\externalfigure[cow-fun.mps][width=4cm]}}} +\stopbuffer + +\typebuffer + +A more advanced clip is demonstrated in \in {figure} [fig:circular clipped +cowhead]. We added \type {\ruledhbox} to demonstrate the dimensions of the +resulting graphic. Putting something in such a ruled box is often a quick way to +test spacing. + +\getbuffer + +Although a clip path definition can contain any \METAPOST\ command, even +graphics, it must contain at least one clipping path. The first one encountered +in the resulting graphic is used. In the example we used a path that is built out +of three subpaths. + +\starttyping +(0,h)--(w,h){down}..{left}(0,0)--cycle +\stoptyping + +We start in the top left corner and draw a straight line. Next we draw a curve to +the origin. Directives like \type {down} and \type {right} force the curve in a +certain direction. With \type {cycle} we close the path. Because we use this path +as a clipping path, we use \type {clip} instead of \type {draw} or \type {fill}. + +\startbuffer +w := 4cm ; h := 2cm ; +draw (0,h)--(w,h){down}..{left}(0,0)--cycle + withpen pencircle scaled 1mm withcolor .625red ; +\stopbuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +Clipping as such is not limited to graphics. Take for instance the text buffer: + +\startbuffer +\startbuffer[sample] +\framed + [align=middle,width=4cm,background=screen,frame=off] + {A \METAPOST\ clip is not the same as a video clip, + although we can use \METAPOST\ to produce a video clip.} +\stopbuffer +\stopbuffer + +\typebuffer + +\getbuffer + +We can call up such a buffer as if it were an external figure. \in {Figure} +[fig:clipped text 1] shows the result. This time we use a different clip path: + +\startbuffer[a] +\startMPclip{text clip} + clip currentpicture to fullcircle shifted (.5,.5) + xscaled \width yscaled \height ; +\stopMPclip +\stopbuffer + +\typebuffer[a] + +To load a buffer, we have to specify its name and type, as in: + +\startbuffer[b] +\placefigure + [here][fig:clipped text 1] + {A clipped buffer (text).} + {\clip + [nx=1,ny=1,mp=text clip] + {\externalfigure[sample][type=buffer,width=4cm]}} +\stopbuffer + +\typebuffer[b] + +\getbuffer[a,b] + +The next few lines demonstrate that we can combine techniques like backgrounds +and clipping. + +\startbuffer +\startuseMPgraphic{clip outline} + draw fullcircle + xscaled \overlaywidth yscaled \overlayheight + withpen pencircle scaled 4mm + withcolor .625red ; +\stopuseMPgraphic + +\defineoverlay[clip outline][\useMPgraphic{clip outline}] + +\placefigure + [here][fig:clipped text 2] + {A clipped buffer (text).} + {\framed + [background=clip outline,offset=overlay,frame=off] + {\clip + [nx=1,ny=1,mp=text clip] + {\externalfigure[sample][type=buffer,width=4cm]}}} +\stopbuffer + +\typebuffer + +We could have avoided the \type {\framed} here, by using the \typ{clip outline} +overlay as a background of the sample. In that case, the resulting linewidth +would have been 2.5~mm instead of 5~mm, since the clipping path goes through the +center of the line. + +\getbuffer + +In most cases, the clip path will be a rather simple path and defining such a +path every time you need it, can be annoying. \in {Figure} [fig:clipping paths] +shows a collection of predefined clipping paths. These are available after +loading the \METAPOST\ clipping library. + +\starttyping +\useMPlibrary[clp] +\stoptyping + +We already saw how the circular clipping path was defined. The diamond is defined +in a similar way, using the predefined path \type {diamond}: + +\starttyping +\startMPclip{diamond} + clip currentpicture to unitdiamond + xscaled \width yscaled \height ; +\stopMPclip +\stoptyping + +The definition of the negated ellipse (\type {negellipse}) uses the primary \type +{peepholed}. This primary is defined in one of the \METAPOST\ modules that come +with \CONTEXT. + +\starttyping +\startMPclip{negellipse} + clip currentpicture to (unitcircle peepholed unitsquare) + xscaled \width yscaled \height ; +\stopMPclip +\stoptyping + +The definition of \type {peepholed} is rather dirty and using \type {peepholed} +is restricted to well defined situations (like here). It's called a primary +because it acts as an operator at the same level as \type {*} and \type {scaled}. + +\startbuffer +\setupclipping [nx=1,ny=1,x=1,y=1] +\setupblackrules[width=2cm,height=1cm] +\startcombination[6*3] + {\clip[mp=urellipse] {\darkred\blackrule}} {urellipse} + {\clip[mp=ulellipse] {\darkred\blackrule}} {ulellipse} + {\clip[mp=llellipse] {\darkred\blackrule}} {llellipse} + {\clip[mp=lrellipse] {\darkred\blackrule}} {lrellipse} + {\clip[mp=ellipse] {\darkred\blackrule}} {ellipse} + {\clip[mp=negellipse]{\darkred\blackrule}} {negellipse} + {\clip[mp=tellipse] {\darkred\blackrule}} {tellipse} + {\clip[mp=bellipse] {\darkred\blackrule}} {bellipse} + {\clip[mp=lellipse] {\darkred\blackrule}} {lellipse} + {\clip[mp=rellipse] {\darkred\blackrule}} {rellipse} + {} {} + {} {} + {\clip[mp=urtriangle]{\darkred\blackrule}} {urtriangle} + {\clip[mp=ultriangle]{\darkred\blackrule}} {ultriangle} + {\clip[mp=lltriangle]{\darkred\blackrule}} {lltriangle} + {\clip[mp=lrtriangle]{\darkred\blackrule}} {lrtriangle} + {\clip[mp=diamond] {\darkred\blackrule}} {diamond} + {\clip[mp=negdiamond]{\darkred\blackrule}} {negdiamond} +\stopcombination +\stopbuffer + +\placefigure + [here][fig:clipping paths] + {A collection of predefined clipping paths.} + {\getbuffer} + +\stopsection + +\startsection[title={Including graphics}] + +\index{graphics+including} + +This document demonstrates that it is no big problem to include \METAPOST\ +graphics in a \TEX\ document. But how about including graphics in a \METAPOST\ +picture? In this section we will explore a couple of macros that provide you this +feature. + +Before we go into details, we introduce a very impressive program called +\PSTOEDIT\ by Wolfgang Glunz. This program runs on top of \GHOSTSCRIPT\ and is +able to convert \POSTSCRIPT\ code into other formats, among them \METAPOST\ (that +part of the \PSTOEDIT\ code is due to Scott Pakin). Some of the graphics that we +use in this section are produced that way. For us, the next call works well, but +the exact call may differ per version or platform. + +\starttyping +pstoedit -ssp -dt -f mpost yourfile.ps newfile.mp +\stoptyping + +We have converted the Dutch cow that shows up in many \CONTEXT\ documents into +\METAPOST\ using this program. The resulting \METAPOST\ file encapsulates the cow +in \METAPOST\ figure~1: \type {beginfig(1)}. Of course you can process this file +like any other, but more interesting is to use this code in an indirect way. + +\startbuffer +loadfigure "mycow.mp" number 1 scaled .5 ; +\stopbuffer + +\typebuffer + +This call will load figure~1 from the specified \METAPOST\ file, in such a way +that there is no interference with the current (encapsulating) figure. + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +Because this graphic is the result from a conversion, there are only paths. If +you want to import a more complex graphic, you need to make sure that the +variables used in there do not conflict with the one currently in use. + +\METAPOST\ is good in drawing vector graphics, but lacks natural support for +bitmaps, but the next macro offers a way out. This macro permits you to include +graphics in \PNG, \PDF, and \JPG\ format, or more precise: those formats +supported by \PDFTEX.\pagereference[hacker] + +\startbuffer +draw externalfigure "hacker.png" scaled 5cm shifted (-6cm,0) ; +draw externalfigure "hacker.png" scaled 5cm slanted .5 ; +\stopbuffer + +\typebuffer + +You can apply the usual transformations, but only those applied directly will be +taken into account. This means that you (currently) cannot store external figures +in picture variables in order to transform them afterwards. + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +Although you are limited in what you can do with such graphics, you can include +them multiple times with a minimum of overhead. Graphics are stored in objects +and embedded only once. + +\startbuffer +numeric s ; pair d, c ; +for i := 1 upto 5 : + s := 3cm randomized 1cm ; % size of picture + c := .5(s,s) ; % center of picture + d := (2cm*i,.5cm) randomized .5cm ; % displacement + draw externalfigure "hacker.png" + scaled s rotatedaround (c,0 randomized 30) shifted d ; +endfor ; +\stopbuffer + +\typebuffer + +Because we cannot store the graphic in a picture and scale afterwards, we +calculate the scale in advance, so that we can rotate around the center. + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +As long as you don't mess around with a stored external figure, you're safe. The +following example demonstrates how we can combine two special driven features: +figure inclusion and shading. + +\startbuffer +picture p ; +p := externalfigure "hacker.png" scaled 150pt ; +clip p to unitcircle scaled 150pt ; +circular_shade(boundingbox p enlarged 10pt, 0, .2red, .9red) ; +addto currentpicture also p ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +We end this section with a few more words to \METAPOST\ inclusion. It may seem +that in order to use the features discussed here, you need to use \CONTEXT\ as +typesetting engine. This is not true. First of all, you can use the small \TEX\ +package \MPTOPDF\ (described in another manual) or you can make small \CONTEXT\ +files with one page graphics. The advantage of the last method is that you can +manipulate graphics a bit. + +\starttyping +\setupcolors[cmyk=yes,rgb=no,state=start] + +\starttext + +\startMPpage[offset=6pt] + loadfigure "niceone.mp" number 10 ; +\stopMPpage + +\stoptext +\stoptyping + +The resulting \PDF\ file can be included as any other graphic +and has the advantage that it is self contained. + +\stopsection + +\startsection[reference=sec:conversion,title={Changing colors}] + +\index{color+manipulating} + +One of the advantages of \METAPOST\ graphics is that it is rather easy to force +consistency in colors and line widths. You seldom can influence third party +graphics that way, but we can use some \METAFUN\ trickery to get around this +limitation. + +\startbuffer +loadfigure "mycow.mp" number 1 scaled .35 ; +refill currentpicture withcolor .625red ; +\stopbuffer + +Say that we want a red cow instead of a black one. The following code does the +trick: + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +In a similar way we can influence the width and colors of the lines. + +\startbuffer +loadfigure "mycow.mp" number 1 scaled .35 ; +refill currentpicture withcolor .625red ; +redraw currentpicture withpen pencircle scaled 2pt withcolor .625yellow ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +Of course we can also use the more fancy features of \METAFUN, like transparency +and shading. + +\startbuffer +loadfigure "mycow.mp" number 1 scaled .35 ; +numeric sh ; sh := define_linear_shade + (llcorner currentpicture,urcorner currentpicture,.625red, .625yellow) ; +refill currentpicture withshade sh ; +redraw currentpicture withpen pencircle scaled 2pt withcolor .5white; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +Before we show a next trick, we draw a few circles. + +\startbuffer[a] +fill fullcircle scaled 2cm withcolor yellow ; +fill fullcircle scaled 2cm shifted (3cm,0) withcolor red ; +\stopbuffer + +\typebuffer[a] + +\startlinecorrection[blank] +\processMPbuffer[a] +\stoplinecorrection + +The yellow and red color do not match the main document colors, but this is no +problem: we can remap them, without spoiling the original definition. + +\startbuffer[b] +remapcolor(yellow,.625yellow) ; +remapcolor(red ,.625red) ; +recolor currentpicture ; +resetcolormap ; +\stopbuffer + +\typebuffer[a,b] + +\startlinecorrection[blank] +\processMPbuffer[a,b] +\stoplinecorrection + +We can combine the inclusion technique with remapping colors. This time using an +artist impression of one of Hasselts Canals (gracht in Dutch)\pagereference +[canal]. + +\startbuffer[a] +loadfigure "gracht.mp" number 1 scaled .5 ; +\stopbuffer + +\typebuffer[a] + +\startlinecorrection[blank] +\processMPbuffer[a] +\stoplinecorrection + +If you think that the sky is too bright in this picture, and given that you also +know which color is used, you can fool the reader by remapping a few colors. + +\startbuffer[b] +color skycolor ; skycolor := (0.8,0.90,1.0) ; +color watercolor ; watercolor := (0.9,0.95,1.0) ; +remapcolor(skycolor ,.8skycolor ) ; +remapcolor(watercolor,.8watercolor) ; +recolor currentpicture ; +resetcolormap ; +\stopbuffer + +\typebuffer[a,b] + +\startlinecorrection[blank] +\processMPbuffer[a,b] +\stoplinecorrection + +Including another \METAPOST\ graphic, refilling, redrawing, and recoloring are +all relatively simple features that use no real tricks. Opposite to the next +feature, which is implemented using the \METAPOST\ special driver that comes with +\CONTEXT. + +\METAPOST\ is not really meant for manipulating graphics, but the previous +examples demonstrated that we have some control over individual colors. In the +next series of examples we will treat the picture as a whole. First we invert the +colors using \type {inverted}. + +\startbuffer +loadfigure "gracht.mp" number 1 scaled .5 ; +addto currentpicture also + inverted currentpicture + shifted (bbwidth(currentpicture)+.5cm,0) ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] \processMPbuffer \stoplinecorrection + +This is a special case of \type {uncolored}. In the next example we explicitly +specify the color. + +\startbuffer +loadfigure "gracht.mp" number 1 scaled .5 ; +addto currentpicture also + (currentpicture uncolored green) + shifted (bbwidth(currentpicture)+.5cm,0) ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] \processMPbuffer \stoplinecorrection + +You can also multiply each color using \type {softened}. In the next sample, the +colors have 80\% of their value. + +\startbuffer +loadfigure "gracht.mp" number 1 scaled .5 ; +addto currentpicture also + (currentpicture softened .8) + shifted (bbwidth(currentpicture)+.5cm,0) ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] \processMPbuffer \stoplinecorrection + +You can also use this operator to harden colors, simply by +providing a value larger than~1. Keep in mind that colors +are clipped at~1 anyway. + +\startbuffer +loadfigure "gracht.mp" number 1 scaled .5 ; +addto currentpicture also + (currentpicture softened 1.2) + shifted (bbwidth(currentpicture)+.5cm,0) ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] \processMPbuffer \stoplinecorrection + +By providing a triplet, you can treat each color component +independently. + +\startbuffer +loadfigure "gracht.mp" number 1 scaled .5 ; +addto currentpicture also + (currentpicture softened (.7,.8,.9)) + shifted (bbwidth(currentpicture)+.5cm,0) ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] \processMPbuffer \stoplinecorrection + +After these examples your are probably sick of seeing this picture in color, so +let's turn the colors into a weigthed grayscales (in a way similar to the way +black and white television treated color). + +\startbuffer +loadfigure "gracht.mp" number 1 scaled .5 ; +addto currentpicture also + grayed currentpicture + shifted (bbwidth(currentpicture)+.5cm,0) ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] \processMPbuffer \stoplinecorrection + +\stopsection + +% \startsection[title={Outline fonts}] +% +% \index{text+outlines} +% \index{outlines} +% +% Outline fonts don't belong to \METAPOST's repertoire of features. Nevertheless we +% can simulate this in a reasonable way. We will not discuss all details here, +% because most details are covered in the \MAKEMPY\ manual. +% +% The macro responsible for outline fonts is \type {graphictext}. The first +% argument should be a string. This string is processed by \TEX. Additionally you +% can provide transformation directives and color specifications. The next example +% demonstrates this. +% +% \startbuffer +% graphictext "\bf Fun" scaled 4 zscaled (1,1.5) +% withdrawcolor blue +% withfillcolor .5white +% withpen pencircle scaled 5pt +% \stopbuffer +% +% \typebuffer +% +% Once the text is typeset by \TEX, it is converted to \POSTSCRIPT\ and converted +% into \METAPOST\ by the \PSTOEDIT\ program. The resulting graphic is imported, +% analyzed, and processed conforming the specifications of \type {graphictext}. +% +% \startlinecorrection[blank] +% \processMPbuffer +% \stoplinecorrection +% +% By default the shapes are filled after they are drawn. This has the advantage +% that in characters built out of pieces, disturbing lines fragments are covered. +% The drawback is that you get only half the linewidth. You can reverse the drawing +% order by adding the \type {reversefill} directive. The previous graphic then +% comes out as: +% +% \startbuffer +% graphictext "\bf Fun" scaled 4 zscaled (1,1.5) +% reversefill +% withdrawcolor blue +% withfillcolor .5white +% withpen pencircle scaled 5pt +% \stopbuffer +% +% \typebuffer +% +% The \type {reversefill} directive can be countered by \type {outlinefill}. +% +% \startlinecorrection[blank] +% \processMPbuffer +% \stoplinecorrection +% +% The next example is taken from the \MAKEMPY\ manual. It demonstrates that you can +% combine \TEX's powerful line breaking with \METAPOST's graphic capabilities. +% +% \startbuffer +% \startuseMPgraphic{quotation} +% picture one ; one := image ( graphictext +% \MPstring{text} +% scaled 1.5 +% withdrawcolor .625blue +% withfillcolor .625white +% withpen pencircle scaled 1pt ; ) ; +% picture two ; two := image ( graphictext +% \MPstring{author} +% scaled 2 +% withdrawcolor .625red +% withfillcolor .625white +% withpen pencircle scaled 2pt ; ) ; +% currentpicture := one ; +% addto currentpicture also two +% shifted lrcorner one +% shifted - 1.125 lrcorner two +% shifted (0, - 1.250 * ypart urcorner two) ; +% setbounds currentpicture to boundingbox currentpicture enlarged 3pt ; +% \stopuseMPgraphic +% \stopbuffer +% +% \typebuffer \getbuffer +% +% In this graphic, we have two text fragments, the first one is a text, the second +% one the name of the author. We combine the quotation and author into this graphic +% using the following definitions: +% +% \startbuffer +% \setMPtext{text} {\vbox{\hsize 8.5cm \input zapf }} +% \setMPtext{author}{\hbox{\sl Hermann Zapf}} +% \stopbuffer +% +% \typebuffer \getbuffer +% +% These definitions assume that the file \type {zapf.tex} is present on the system +% (which is the case when you have installed \CONTEXT). The graphic can now be +% typeset using the following call: +% +% \startbuffer +% \placefigure +% {A text does not need to be an outline in order to be +% typeset in an outline font.} +% {\useMPgraphic{quotation}} +% \stopbuffer +% +% \typebuffer \getbuffer +% +% The quality of the output depends on how the glyphs are constructed. For +% instance, in \TEX, math symbols are sometimes composed of glyph fragments and +% rules. +% +% \startbuffer +% graphictext +% "$$\sqrt{1+x}$$" +% scaled 8 +% withdrawcolor .625red +% withpen pencircle scaled 1.5pt +% \stopbuffer +% +% \typebuffer +% +% \startlinecorrection[blank] +% \processMPbuffer +% \stoplinecorrection +% +% This is not really a problem because we can also fill the shapes. It is the +% reason why the fill is applied after the draw and in such case the effective line +% width is half the size specified. +% +% \startbuffer +% graphictext +% "$$\left({{\sqrt{1+x}}\over{\sqrt{2+x^2}}}\right)$$" +% scaled 4 +% dashed evenly +% withdrawcolor .625red +% withfillcolor .850white +% withpen pencircle scaled 1.5pt +% \stopbuffer +% +% \typebuffer +% +% In this example we also use a dashed line. Instead of normal colors, we could +% have used shades or transparent colors. +% +% \startlinecorrection[blank] +% \processMPbuffer +% \stoplinecorrection +% +% Instead of supplying the text directly, you can use the indirect method. This +% permits you to process rather complex data without messing up your \METAPOST\ +% code. +% +% \startbuffer +% \setMPtext {some math}% +% {\usemodule[mathml] +% \xmlprocessdata +% {main} +% {<math xmlns='http://www.w3c.org/mathml' version='2.0'> +% <apply> <log/> +% <logbase> <cn> 2 </cn> </logbase> +% <apply> <plus/> +% <ci> x </ci> +% <cn> 1 </cn> +% </apply> +% </apply> +% </math>} +% {}} +% \stopbuffer +% +% \typebuffer \getbuffer +% +% Here we feed some \MATHML\ into \TEX, which in turn shows up as a \METAPOST\ +% graphic. +% +% \startbuffer +% graphictext +% \MPstring{some math} +% scaled 4 +% withdrawcolor .625red +% withfillcolor .625white +% withpen pencircle scaled 1.5pt +% \stopbuffer +% +% \typebuffer +% +% \startlinecorrection[blank] +% \processMPbuffer +% \stoplinecorrection +% +% \stopsection + +\startsection[title={Outline fonts}] + +\index{text+outlines} +\index{outlines} + +Outline fonts don't belong to \METAPOST's repertoire of features. Nevertheless we +can simulate this in a reasonable way. The current version of \METAFUN\ uses the +outline subsystem of \CONTEXT\ \MKIV, but in earlier days we used an external +process: a \PDF\ file is generated that has the snippet, that gets converted to +\POSTSCRIPT, which in turn is converted to \METAPOST\ with \type {pstoedit} and +from that result we filter the outlines. This method uses \type {graphictext} and +is covered in the \MAKEMPY\ manual. Here we discuss the new method using \type +{outlinetext}. + +\startbuffer +draw outlinetext.b("\bf Funky") + (withcolor .5white) + (withcolor blue withpen pencircle scaled 1/5) + scaled 4 zscaled (1,0.5) ; +\stopbuffer + +\typebuffer + +Once the text is typeset by \TEX, the result (a node list) is parsed and a +\METAPOST\ representation is created. The glyphs are converted to outlines that +are taken from the original font. For the moment this only works for \OPENTYPE\ +fonts. + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +\startbuffer[1] +draw outlinetext ("\bf Funky") + scaled 3 ; +\stopbuffer + +\startbuffer[2] +draw outlinetext.d ("\bf Funky") + (withcolor red withpen pencircle scaled 1/5) + scaled 3 ; +\stopbuffer + +\startbuffer[3] +draw outlinetext.f ("\bf Funky") + (withcolor blue) + scaled 3 ; +\stopbuffer + +\startbuffer[4] +draw outlinetext.b ("\bf Funky") + (withcolor blue) + (withcolor red withpen pencircle scaled 1/5) + scaled 3 ; +\stopbuffer + +\startbuffer[5] +draw outlinetext.r ("\bf Funky") + (withcolor blue) + (withcolor red withpen pencircle scaled 1/5) + scaled 3 ; +\stopbuffer + +\startplacetable[reference=tab:outlinetext,title={The four variants of \type {graphictext}.}] + \bTABLE[offset=1ex] + \dorecurse{5}{\bTR \bTD \processMPbuffer[#1] \eTD \bTD \typebuffer[#1] \eTD \eTR} + \eTABLE +\stopplacetable + +The five variants of this command are shown in \in {table} [tab:outlinetext]: the +suffix determines the number of arguments and rendering. The \type {r} suffix +reverses the order: the fill comes over the draw. There is a \type {p} suffix +that returns just the picture. + +The next example demonstrates that you can combine \TEX's powerful line breaking +algorithm with \METAPOST's graphic capabilities. + +\startbuffer +\startuseMPgraphic{quotation} + picture one ; one := image ( draw outlinetext.b + (\MPstring{text}) + (withcolor .625white) + (withcolor .625blue withpen pencircle scaled 1/5) + scaled 1.5 + ) ; + picture two ; two := image ( draw outlinetext.b + (\MPstring{author}) + (withcolor .625white) + (withcolor .625red withpen pencircle scaled 1/5) + scaled 2 + ) ; + currentpicture := one ; + addto currentpicture also two + shifted lrcorner one + shifted - 1.125 lrcorner two + shifted (0, - 2 * ypart urcorner two) ; + setbounds currentpicture to boundingbox currentpicture enlarged 3pt ; +\stopuseMPgraphic +\stopbuffer + +\typebuffer \getbuffer + +In this graphic, we have two text fragments, the first one is a text, the second +one the name of the author. We combine the quotation and author into this graphic +using the following definitions: + +\startbuffer +\setMPtext + {text} + {\vbox + {\setupalign[verytolerant,stretch] + \hsize 8.5cm + \input zapf }} +\setMPtext + {author} + {\hbox + {\sl Hermann Zapf}} +\stopbuffer + +\typebuffer \getbuffer + +These definitions assume that the file \type {zapf.tex} is present on the system +(which is the case when you have installed \CONTEXT). The graphic can now be +typeset using the following call: + +\startbuffer +\placefigure + [here] + [fig:zapf] + {A text does not need to be an outline in order to be + typeset in an outline font.} + {\useMPgraphic{quotation}} +\stopbuffer + +\typebuffer + +The result is \in {figure} [fig:zapf]. The quality of the output depends on how +the glyphs are constructed. For instance, in \TEX, math symbols are sometimes +composed of glyph fragments and rules. + +\start + \def||{-} + \getbuffer +\stop + +\startbuffer +draw outlinetext.d + ("\mathematics{\sqrt{1+x}}") + (withcolor .625red withpen pencircle scaled 1/5) + scaled 8 +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +This is not really a problem because we can also fill the shapes. It is the +reason why the fill is applied after the draw and in such case the effective line +width is half the size specified. + +\startbuffer +draw outlinetext.b + ("\mathematics{\left({{\sqrt{1+x}}\over{\sqrt{2+x^2}}}\right)}") + (withcolor .850white) + (withcolor .625red + dashed evenly scaled .1 + withpen pencircle scaled 1/5) + scaled 8 +\stopbuffer + +\typebuffer + +In this example (shown in \in {figure} [fig:dashedoutline]) we also use a dashed +line. + +\placefigure + [here] + [fig:dashedoutline] + {A dashed outline text.} + {\processMPbuffer} + +Instead of supplying the text directly, you can use the indirect method. This +permits you to process rather complex data without messing up your \METAPOST\ +code. + +\startbuffer +\usemodule[mathml] + +\setMPtext {some math}% + {\xmlprocessdata + {main} + {<math xmlns='http://www.w3c.org/mathml' version='2.0'> + <apply> <log/> + <logbase> <cn> 2 </cn> </logbase> + <apply> <plus/> + <ci> x </ci> + <cn> 1 </cn> + </apply> + </apply> + </math>} + {}} +\stopbuffer + +\typebuffer \getbuffer + +Here we feed some \MATHML\ into \TEX, which in turn shows up as a \METAPOST\ +graphic (\in {figure} [fig:mathml]). + +\startbuffer +draw outlinetext.b + (\MPstring{some math}) + (withcolor .625white) + (withcolor .625red withpen pencircle scaled 1/5) + scaled 8 +\stopbuffer + +\typebuffer + +\placefigure + [here] + [fig:mathml] + {A \MATHML\ snippet turned into outlines.} + {\processMPbuffer} + +Outlines are fun to look at. Here are a few ways to visualize a glyph: + +\startbuffer[1] +\startcombination[3*1] + {\ruledhbox\bgroup + \showshape[character=(,alternative=text]% + \egroup} {} + {\ruledhbox\bgroup + \showshape[character=a,alternative=text]% + \egroup} {} + {\ruledhbox\bgroup + \showshape[character=x,alternative=text]% + \egroup} {} +\stopcombination +\stopbuffer + +\typebuffer[1] + +You can control the rendering a bit by setting \type {option}. Possible options +are: \type {box}, \type {width}, \type {min}, \type {max} and \type {comment}. +The \type {simple} option disables all. The simple results are shown in +\in{figure} [fig:showshape]. + +\startbuffer[2] +\startcombination[3*1] + {\ruledhbox\bgroup + \showshape[character=(,alternative=text,option=simple]% + \egroup} {} + {\ruledhbox\bgroup + \showshape[character=a,alternative=text,option=simple]% + \egroup} {} + {\ruledhbox\bgroup + \showshape[character=x,alternative=text,option=simple]% + \egroup} {} +\stopcombination +\stopbuffer + +\typebuffer[2] + +\startplacefigure[reference=fig:showshape,title={Showing shapes.}] + \getbuffer[2] +\stopplacefigure + +When you use this feature you need to be aware of the fact that fonts can have +features, for instance ligatures and kerns between characters. In \in {figure} +[fig:outlines:features] we see a few examples with and without features, one with +Pagella (the Zapf quote) and one with Optima Nova (the Tufte quote). + +\startplacefigure[reference=fig:outlines:features,title={Pagela (\OPENTYPE) and Optima Nova (\TYPEONE)}] + \startcombination[1*4] + \bgroup + \def|#1|{-}% + \definedfont[texgyrepagella-regular.otf*none]% + \startMPcode + draw outlinetext.b + ("\framed[align=normal,width=max]{\input{zapf}}") + (withcolor .375white) + (withcolor .625red withpen pencircle scaled 1/10) ; + \stopMPcode + \egroup {pagella / no features} + \bgroup + \def|#1|{-}% + \definedfont[texgyrepagella-regular.otf*default]% + \startMPcode + draw outlinetext.b + ("\framed[align=normal,width=max]{\input{zapf}}") + (withcolor .375white) + (withcolor .625blue withpen pencircle scaled 1/10) ; + \stopMPcode + \egroup {pagella / default features} + \bgroup + \def|#1|{-}% + \definedfont[lt55476.afm*none]% optima nova + \startMPcode + draw outlinetext.b + ("\framed[align=normal,width=max]{\input{tufte}}") + (withcolor .375white) + (withcolor .625green withpen pencircle scaled 1/10) ; + \stopMPcode + \egroup {optima nova / no features} + \bgroup + \def|#1|{-}% + \definedfont[lt55476.afm*default]% optima nova + \startMPcode + draw outlinetext.b + ("\framed[align=normal,width=max]{\input{tufte}}") + (withcolor .375white) + (withcolor .625yellow withpen pencircle scaled 1/10) ; + \stopMPcode + \egroup {optima nova / default features} + \stopcombination +\stopplacefigure + +Given that a shape has a path that is suitable for it, you can use special effects, +like: + +\startbuffer + draw image ( + draw outlinetext.d + ("Abracadabra") + (withpen pencircle scaled 1/10 dashed withdots scaled 1/20) ; + ) xsized TextWidth ; +\stopbuffer + +\typebuffer + +\startlinecorrection + \processMPbuffer +\stoplinecorrection + +\stopsection + +\startsection[title=Transparency groups] + +The following feature is not that usefull but implemented anyway. The \PDF\ reference says: + +\startitemize + \startitem + A group may be isolated or non-isolated, which shall determine the + initial backdrop against which its stack is composited. + \stopitem + \startitem + A group may be knockout or non-knockout, which shall determine whether + the objects within its stack are composited with one another or only with + the group’s backdrop. + \stopitem +\stopitemize + +and then carries on with a detailed explanation of groups. Here we stick to just +mentioning how one can create a group in a picture. First we define a helper: + +\startbuffer +\startMPdefinitions + def ShowGroup (expr clr) (text grouped) = + draw image ( + drawarrow (10,0) -- (0,0) + withtransparency(1,.5) + withcolor clr ; + ) grouped ; + currentpicture := currentpicture xsized (TextWidth/8) ; + setbounds currentpicture to boundingbox currentpicture enlarged 2mm ; + addbackground withcolor .5white ; + enddef ; +\stopMPdefinitions +\stopbuffer + +\typebuffer \getbuffer + +\startlinecorrection[blank] + \startcombination[5*1] + {\startMPcode ShowGroup(.5red) () \stopMPcode} {\tttf no group} + {\startMPcode ShowGroup(.5green) (asgroup "") \stopMPcode} {\tttf group} + {\startMPcode ShowGroup(.5blue) (asgroup "isolated") \stopMPcode} {\tttf isolated} + {\startMPcode ShowGroup(.5cyan) (asgroup "knockout") \stopMPcode} {\tttf knockout} + {\startMPcode ShowGroup(.5magenta)(asgroup "isolated,knockout") \stopMPcode} {\tttf isolated\crlf knockout} + \stopcombination +\stoplinecorrection + +The syntax is: + +\starttyping +draw somepicture|somepath grouped "[isolated|knockout] ; +\stoptyping + +The group becomes an object and is no longer part of the stream of graphic +operators but a reference. For what it's worth: I never needed this feature. + +\stopsection + +\startsection[title=Decorating] + +Although the \METAPOST\ language is quite powerful the number of data types is +not that large and when it comes to drawing stuff there are only paths and +pictures. A path is a list of points (with controlpoints) and a few properties, +like the pen, linewidth, linecap, color and such. For a long time in \METAFUN\ we +used so called specials to implement extensions (like shading). This was done by +using special colors and associating these with entries in the special section at +the top of the output. + +Nowadays we use the pre- and postscript properties of paths. The advantage is +that we can add whatever we want, as long as the backend supports it and because +the backend is written in \LUA\ there are no real limitations. So, instead of +extending \METAPOST\ we extend the \METAFUN\ macros and backend. + +Most extensions use the prescripts. Think of this: + +\starttyping +draw fullcircle + withprescript "do this" + withprescript "and that" + withprescript "and even more" ; +\stoptyping + +Eventually this becomes a string: + +\starttyping +and even more<newline>and that<newline>do this +\stoptyping + +\typebuffer + +The prescripts get prepended, while the postscripts (that we use for text only) +get appended. When we draw a picture with properties (like color) they get +overwritten but not so (with good reason) for the pre- and postscripts: these +just accumulate. We will now demonstrate how we can manipulate the picture +(a bit). + +\startbuffer +picture MyShape ; MyShape := image ( + fill fullsquare xyscaled (4,1) withcolor .625red ; + fill fullsquare xyscaled (3,1) withcolor .625green ; + fill fullsquare xyscaled (2,1) withcolor .625blue ; + fill fullsquare xyscaled (1,1) withcolor .625yellow ; +) xysized (TextWidth,1cm) ; + +draw MyShape; +\stopbuffer + +\typebuffer + +We just draw the (natural) picture: + +\startlinecorrection[blank] + \processMPbuffer +\stoplinecorrection + +When we draw the picture with a new color, all its components get recolored: + +\startbuffer +draw MyShape + withcolor .625magenta ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] + \processMPbuffer +\stoplinecorrection + +However, when we add a transparency only the first component gets adapted because +we use prescripts for this extension. (An extension using the postscripts would +affect the last component.) + +\startbuffer +draw MyShape + withcolor .625magenta + withtransparency (1,.5) ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] + \processMPbuffer +\stoplinecorrection + +The same logic applied to the \type {image}: prescripts get prepended to the +first copmponent, postscripts to the last. + +\startbuffer +draw image (draw MyShape) + withcolor .625cyan ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] + \processMPbuffer +\stoplinecorrection + +\startbuffer +draw image (draw MyShape) + withcolor .625cyan + withtransparency (1,.5) ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] + \processMPbuffer +\stoplinecorrection + +The \type {undecorated} macro ignores the properties. We can't reset the scripts as +this could ruin the effects like shading. + +\startbuffer +draw undecorated (draw MyShape) + withcolor .625white ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] + \processMPbuffer +\stoplinecorrection + +The \type {decorated} macro applies the properties to each component. + +\startbuffer +draw decorated (draw MyShape) + withtransparency (1,.5) ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] + \processMPbuffer +\stoplinecorrection + +Here we kept the colors as they are but next we redo them: + +\startbuffer +draw decorated (draw MyShape) + withcolor .625magenta + withtransparency (1,.5) ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] + \processMPbuffer +\stoplinecorrection + +The \type {redecorated} macro is the most intrusive as it resets the properties. +This also means that you will loose texts, shades etc. + +\startbuffer +draw redecorated (draw MyShape) + withtransparency (1,.5) ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] + \processMPbuffer +\stoplinecorrection + +Indeed we get no color (but black) but we can bring back some color: + +\startbuffer +draw redecorated (draw MyShape) + withcolor .625yellow + withtransparency (1,.5) ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] + \processMPbuffer +\stoplinecorrection + +\stopsection + +\startsection[title=Properties] + +The (plain) \METAPOST\ macro \type {drawoptions} stored its arguments +in a macro that gets expanded when something is drawn (or filled). So, when you say + +\starttyping +drawoptions(withcolor red) ; +draw somepath ; +\stoptyping + +This effectively is: + +\starttyping +draw somepath withcolor red ; +\stoptyping + +A disadvantage is that there is not much control over where it gets applied, +especially when you hide drawing operations in macros. It's the reason why +personally I always prefer explicit options. If you want some abstraction +you can use the properties feature: + +\startbuffer +\startMPcode + property p[] ; + p1 = properties(withcolor "darkred") ; + p2 = properties(withcolor "darkblue") ; + p3 = properties(withcolor "darkgreen") ; + fill fullsquare xysized (TextWidth,12mm) withproperties p1 ; + fill fullsquare xysized (TextWidth, 8mm) withproperties p2 ; + fill fullsquare xysized (TextWidth, 4mm) withproperties p3 ; + fill fullsquare xysized (TextWidth, 2mm) withproperties p1 ; +\stopMPcode +\stopbuffer + +\typebuffer + +We get: + +\startlinecorrection +\getbuffer +\stoplinecorrection + +Here we use an \quote {array} of properties but a single property is also possible: + +\startbuffer +\startMPcode + property p ; + p = properties(withcolor "darkyellow") ; + fill fullsquare xysized (TextWidth,4mm) withproperties p ; +\stopMPcode +\stopbuffer + +\typebuffer + +We get: + +\startlinecorrection +\getbuffer +\stoplinecorrection + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/metafun/metafun-embedding.tex b/doc/context/sources/general/manuals/metafun/metafun-embedding.tex new file mode 100644 index 000000000..10383fa3a --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/metafun-embedding.tex @@ -0,0 +1,1208 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\startcomponent metafun-embedding + +\environment metafun-environment + +\startchapter[reference=sec:embedding,title={Embedded graphics}] + +\startintro + +In addition to the \type {beginfig}||\type {endfig} method, there are other ways +to define and include a \METAPOST\ graphic. Each method has its advantages and +disadvantages. + +In the previous chapter we were still assuming that the graphic was defined in +its own file. In this chapter we will introduce the interface between \CONTEXT\ +and \METAPOST\ and demonstrate how the definitions of the graphics can be +embedded in the document source. + +\stopintro + +\startsection[title={Getting started}] + +\index{running} +\index{processing} + +From now on, we will assume that you have \CONTEXT\ running on your platform. +Since \PDF\ has full graphics support, we also assume that you use \LUATEX\ in +combination with \CONTEXT\ \MKIV, although most will also work with other engines +and \MKII. Since this document is not meant as a \CONTEXT\ tutorial, we will +limit this introduction to the basics needed to run the examples. + +A simple document looks like: + +\starttyping +\starttext + Some text. +\stoptext +\stoptyping + +You can process this document with the \LUA\ based command line interface to +\CONTEXT. If the source code is embedded in the file \type {mytext.tex}, you can +say: + +\starttyping +context mytext +\stoptyping + +We will use color, and in \MKIV\ color is enabled by default. If you don't want +color you can tell \CONTEXT, so + +\starttyping +\setupcolors[state=stop] +\starttext + Some \color[blue]{text} and/or \color[green]{graphics}. +\stoptext +\stoptyping + +comes out in black and white. + +In later chapters we will occasionally see some more \CONTEXT\ commands show up. +If you want to know more about what \CONTEXT\ can do for you, we recommend the +beginners manual and the reference manual, as well as the wiki pages. + +\stopsection + +\startsection[title={External graphics}] + +\index {graphics+external} + +Since \TEX\ has no graphic capabilities built in, a graphic is referred to as an +external figure. A \METAPOST\ graphic often has a number as suffix, so embedding +such a graphic is done by: + +\starttyping +\externalfigure[graphic.123][width=4cm] +\stoptyping + +An alternative method is to separate the definition from the inclusion. An +example of a definition is: + +\starttyping +\useexternalfigure[pentastar][star.803][height=4cm] +\useexternalfigure[octostar] [star.804][pentastar] +\stoptyping + +Here, the second definition inherits the characteristics from the first one. +These graphics can be summoned like: + +\starttyping +\placefigure + {A five||point star drawn by \METAPOST.} + {\externalfigure[pentastar]} +\stoptyping + +Here the stars are defined as stand||alone graphics, in a file called \type +{star.mp}. Such a file can look like: + +\starttyping +def star (expr size, n, pos) = + for a=0 step 360/n until round(360*(1-1/n)) : + draw (origin -- (size/2,0)) + rotatedaround (origin,a) shifted pos ; + endfor ; +enddef ; + +beginfig(803) ; + pickup pencircle scaled 2mm ; star(2cm,5,origin) ; +endfig ; + +beginfig(804) ; + pickup pencircle scaled 1mm ; star(1cm,8,origin) ; + pickup pencircle scaled 2mm ; star(2cm,7,(3cm,0)) ; +endfig ; + +end. +\stoptyping + +This \type {star} macro will produce graphics like: + +\startbuffer +def star (expr size, n, pos) = + for a=0 step 360/n until round(360*(1-1/n)) : + draw (origin -- (size/2,0)) + rotatedaround (origin,a) shifted pos ; + endfor ; +enddef ; + +for i=5 upto 10 : + drawoptions (withpen pencircle scaled 2mm withcolor .625red) ; + star(1cm,i,origin shifted (i*2cm,0)) ; +endfor ; +\stopbuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +But, now that we have instant \METAPOST\ available in \LUATEX, there is no need +for external images and we can collect them in libraries, as we will see later +on. + +\stopsection + +\startsection[title={Integrated graphics}] + +\index{graphics+embedded} + +An integrated graphic is defined in the document source or in a style definition +file. The most primitive way of doing this is just inserting the code: + +\starttyping +\startMPcode + fill fullcircle scaled 200pt withcolor .625white ; +\stopMPcode +\stoptyping + +Such a graphic is used once at the spot where it is defined. In this document we +also generate graphics while we finish a page, so there is a good chance that +when we have constructed a graphic which will be called on the next page, the +wrong graphic is placed. + +For this reason there are are more convenient ways of defining and using +graphics, which have the added advantage that you can predefine multiple +graphics, thereby separating the definitions from the usage. + +The first alternative is a {\em usable} graphic. Such a graphic is calculated +anew each time it is used. An example of a usable graphic is: + +\starttyping +\startuseMPgraphic{name} + fill fullcircle scaled 200pt withcolor .625yellow ; +\stopuseMPgraphic +\stoptyping + +When you put this definition in the preamble of your document, you can place this +graphic anywhere in the file, saying: + +\starttyping +\useMPgraphic{name} +\stoptyping + +As said, this graphic is calculated each time it is placed, which can be time +consuming. Apart from the time aspect, this also means that the graphic itself is +incorporated many times. Therefore, for graphics that don't change, \CONTEXT\ +provides {\em reusable} graphics: + +\starttyping +\startreusableMPgraphic{name} + fill fullcircle scaled 200pt withcolor .625yellow; +\stopreusableMPgraphic +\stoptyping + +This definition is accompanied by: + +\starttyping +\reuseMPgraphic{name} +\stoptyping + +Imagine that we use a graphic as a background for a button. We can create a +unique and reusable graphic by saying: + +\starttyping +\def\MyGraphic + {\startreusableMPgraphic{name:\overlaywidth:\overlayheight} + path p ; p := unitsquare + xscaled OverlayWidth yscaled OverlayHeight ; + fill p withcolor .625yellow ; + draw p withcolor .625red ; + \stopreusableMPgraphic + \reuseMPgraphic{name:\overlaywidth:\overlayheight}} +\stoptyping + +Notice the use of \type {OverlayWidth} and \type {OverlayHeight}. These variables +are set for each call to \METAPOST. After this we can say: + +\starttyping +\defineoverlay[my graphic][\MyGraphic] +\button[background=my graphic,frame=off]{Go Home}[firstpage] +\stoptyping + +Say that we have a 30pt by 20pt button, then the identifier will be \type +{name:30pt:20pt}. Different dimensions will lead to other identifiers, so this +sort of makes the graphics unique. + +We can bypass the ugly looking \type {\def} by using a third class of embedded +graphics, the {\em unique} graphics. + +\starttyping +\startuniqueMPgraphic{name} + path p ; p := unitsquare + xscaled OverlayWidth yscaled OverlayHeight ; + fill p withcolor .625yellow ; + draw p withcolor .625red ; +\stopuniqueMPgraphic +\stoptyping + +Now we can say: + +\starttyping +\defineoverlay[my graphic][\uniqueMPgraphic{name}] +\button[background=my graphic,frame=off]{Go Home}[firstpage] +\stoptyping + +A shorter variant is: + +\starttyping +\startuniqueMPgraphic{name} + fill OverlayBox withcolor .625yellow ; + draw OverlayBox withcolor .625red ; +\stopuniqueMPgraphic +\stoptyping + +You may wonder why unique graphics are needed when a single graphic might be used +multiple times by scaling it to fit the situation. Since a unique graphic is +calculated for each distinctive case, we can be sure that the current +circumstances are taken into account. Also, scaling would result in incomparable +graphics. Consider the following definition: + +\startbuffer[a] +\startuseMPgraphic{demo} + draw unitsquare + xscaled 5cm yscaled 1cm + withpen pencircle scaled 2mm + withcolor .625red ; +\stopuseMPgraphic +\stopbuffer + +\typebuffer[a] + +Since we reuse the graphic, the dimensions are sort of fixed, and because the +graphic is calculated once, scaling it will result in incompatible line widths. + +\startbuffer[b] +\hbox \bgroup + \scale[width=5cm,height=1cm]{\useMPgraphic{demo}}\quad + \scale[width=8cm,height=1cm]{\useMPgraphic{demo}}% +\egroup +\stopbuffer + +\startlinecorrection[blank] +\getbuffer[a,b] +\stoplinecorrection + +These graphics were placed with: + +\typebuffer[b] + +Imagine what happens when we add some buttons to an interactive document without +taking care of this side effect. All the frames would look different. Consider +the following example. + +\startbuffer[a] +\startuniqueMPgraphic{right or wrong} + pickup pencircle scaled .075 ; + fill unitsquare withcolor .8white ; + draw unitsquare withcolor .625red ; + currentpicture := currentpicture + xscaled OverlayWidth yscaled OverlayHeight ; +\stopuniqueMPgraphic +\stopbuffer + +\typebuffer[a] + +Let's define this graphic as a background to some buttons. + +\startbuffer[b] +\defineoverlay[button][\uniqueMPgraphic{right or wrong}] +\setupbuttons[background=button,frame=off] +\stopbuffer + +\startbuffer[c] +\hbox + {\button {previous} [previouspage]\quad + \button {next} [nextpage]\quad + \button {index} [index]\quad + \button {table of contents} [content]} +\stopbuffer + +\typebuffer[b,c] + +The buttons will look like: + +\startlinecorrection[blank] +\setupinteraction[state=start,color=,contrastcolor=] +\getbuffer[a,b,c] +\stoplinecorrection + +Compare these with: + +\startbuffer[a] +\startuniqueMPgraphic{wrong or right} + pickup pencircle scaled 3pt ; + path p ; p := unitsquare + xscaled OverlayWidth yscaled OverlayHeight ; + fill p withcolor .8white ; + draw p withcolor .625red ; +\stopuniqueMPgraphic +\stopbuffer + +\startlinecorrection[blank] +\getbuffer[a,b] +\defineoverlay[button][\uniqueMPgraphic{wrong or right}] +\setupinteraction[state=start,color=,contrastcolor=] +\getbuffer[c] +\stoplinecorrection + +Here the graphic was defined as: + +\typebuffer[a] + +The last class of embedded graphics are the {\em runtime} graphics. When a +company logo is defined in a separate file \type {mylogos.mp}, you can run this +file by saying: + +\starttyping +\startMPrun + input mylogos ; +\stopMPrun +\stoptyping + +The source for the logo is stored in a file named \type {mylogos.mp}. + +\startbuffer +beginfig(21) ; + draw fullsquare withcolor .625red ; + draw fullsquare rotated 45 withcolor .625red ; + picture cp ; cp := currentpicture ; + def copy = addto currentpicture also cp enddef ; + copy scaled .9 withcolor .625white ; + copy scaled .7 withcolor .625yellow ; + copy scaled .6 withcolor .625white ; + copy scaled .4 withcolor .625red ; + copy scaled .3 withcolor .625white ; + fill fullcircle scaled .2 withcolor .625yellow ; + currentpicture := currentpicture scaled 50 ; +endfig ; +end . +\stopbuffer + +\typebuffer + +In this example the result is available in the virtual file \type {mprun.21}. +This file can be included in the normal way, using: + +\starttyping +\externalfigure[mprun.21][width=5cm] +\stoptyping + +\startuseMPgraphic{dummy logo} + draw fullsquare withcolor .625red ; + draw fullsquare rotated 45 withcolor .625red ; + picture cp ; cp := currentpicture ; + def copy = addto currentpicture also cp enddef ; + copy scaled .9 withcolor .625white ; + copy scaled .7 withcolor .625yellow ; + copy scaled .6 withcolor .625white ; + copy scaled .4 withcolor .625red ; + copy scaled .3 withcolor .625white ; + fill fullcircle scaled .2 withcolor .625yellow ; + currentpicture := currentpicture scaled 3cm ; +\stopuseMPgraphic + +\placefigure + {The logo is defined in the file \type {mylogos.mp} as + figure~21 and processed by means of the \type {mprun} + method.} + {\useMPgraphic{dummy logo}} + +Optionally you can specify a name and an instance. This has the advantage that +the graphics don't interfere with the regular inline graphics. Here the instance +used is \type {extrafun} and the name where the run is stored is \type {mydemo}. + +\startbuffer +\startMPrun{extrafun::mydemo} + input mfun-mrun-demo.mp ; +\stopMPrun + +\placefigure + {An external file can have multiple graphics. Here we show a few + images that we used to use on the \PRAGMA\ \CONTEXT\ website.} + {\startcombination[2*2] + {\externalfigure[mprun:extrafun::mydemo.1][height=6cm]} {downloads} + {\externalfigure[mprun:extrafun::mydemo.2][height=6cm]} {links} + {\externalfigure[mprun:extrafun::mydemo.3][height=6cm]} {mirrors} + {\externalfigure[mprun:extrafun::mydemo.4][height=6cm]} {team} + \stopcombination} +\stopbuffer + +\typebuffer + +Keep in mind that the whole file will be processed (using the built in library) +in order to get one graphic. Normally this is no big deal. + +\getbuffer + +\stopsection + +\startsection[title={Using \METAFUN\ but not \CONTEXT}] + +\index{graphics+standalone} + +If you don't want to use \CONTEXT\ but still want to use \METAFUN, a rather +convenient method is the following. Create a file that + +\starttyping +\startMPpage + % Your mp code goes here. You can use the textext + % macro as discussed later to deal with typeset text. +\stopMPpage +\stoptyping + +When you process that file with the \type {context} command you will get a \PDF\ +file that you can include in any application that can embed a \PDF\ image. In +this case your exposure to \CONTEXT\ is minimal. + +\stopsection + +\startsection[title={Graphic buffers}] + +\index{graphics+buffers} +\index{buffers} + +In addition to the macros defined in the previous section, you can use \CONTEXT's +buffers to handle graphics. This can be handy when making documentation, so it +makes sense to spend a few words on them. + +A buffer is a container for content that is to be (re|)|used later on. The main +reason for their existence is that they were needed for typesetting manuals and +articles on \TEX. By putting the code snippets in buffers, we don't have to key +in the code twice, since we can either show the code of buffers verbatim, or +process the code as part of the text flow. This means that the risk of mismatch +between the code shown and the typeset text is minimized. + +\startbuffer[a] +\startbuffer +You are reading the \METAFUN\ manual. +\stopbuffer +\stopbuffer + +\typebuffer[a] + +This buffer can be typeset verbatim using \type {\typebuffer} and processed using +\type {\getbuffer}, as we will do now: + +\blank \getbuffer[a] \blank + +An other advantage of using buffers, is that they help you keeping the document +source clean. In many places in this manual we put table or figure definitions in +a buffer and pass the buffer to another command, like: + +\starttyping +\placefigure{A very big table}{\getbuffer} +\stoptyping + +Sometimes it makes sense to collect buffers in separate files. In that case we +give them names. + +\startbuffer +\startbuffer[mfun] +You are reading the \METAFUN\ manual. +\stopbuffer +\stopbuffer + +This time we should say \type {\typebuffer[mfun]} to typeset the code verbatim. +Instead of \TEX\ code, we can put \METAPOST\ definitions in buffers. + +\startbuffer +\startbuffer[graphic] +draw fullcircle scaled 2cm ; +\stopbuffer +\stopbuffer + +Buffers can be used to stepwise build graphics. By putting code in multiple +buffers, you can selectively process this code. + +\startbuffer +\startbuffer[red] +drawoptions(withcolor .625red) ; +\stopbuffer + +\startbuffer[yellow] +drawoptions(withcolor .625yellow) ; +\stopbuffer +\stopbuffer + +\typebuffer + +We can now include the same graphic in two colors by simply using different +buffers. This time we use the special command \type {\processMPbuffer}, since +\type {\getbuffer} will typeset the code fragment, which is not what we want. + +\startbuffer +\startlinecorrection[blank] +\processMPbuffer[red,graphic] +\stoplinecorrection +\stopbuffer + +\typebuffer + +The line correction macros take care of proper spacing around the graphic. The +\type {[blank]} directive tells \CONTEXT\ to add more space before and after the +graphic. + +\startbuffer +\startlinecorrection[blank] +\processMPbuffer[yellow,graphic] +\stoplinecorrection +\stopbuffer + +\typebuffer + +Which mechanism you use, (multiple) buffers or (re|)|usable graphics, depends on +your preferences. Buffers are slower but don't take memory, while (re|)|usable +graphics are stored in memory which means that they are accessed faster. + +\stopsection + +\startsection[title={Communicating color}] + +\index{color} + +Now that color has moved to the desktop, even simple documents have become more +colorful, so we need a way to consistently apply color to text as well as +graphics. In \CONTEXT, colors are called by name. + +The next definitions demonstrate that we can define a color using different color +models, \RGB\ or \CMYK. Depending on the configuration, \CONTEXT\ will convert +one color system to the other, \RGB\ to \CMYK, or vice versa. The full repertoire +of color components that can be set is as follows. + +\starttyping +\definecolor[color one] [r=.1, g=.2, b=.3] +\definecolor[color two] [c=.4, m=.5, y=.6, k=.7] +\definecolor[color three][s=.8] +\stoptyping + +The numbers are limited to the range $0\dots1$ and represent percentages. Black +is represented by: + +\starttyping +\definecolor[black 1] [r=0, g=0, b=0] +\definecolor[black 2] [c=0, m=0, y=0, k=1] +\definecolor[black 3] [s=0] +\stoptyping + +Predefined colors are passed to \METAPOST\ graphics via the \type {\MPcolor}. +First we define some colors. + +\starttyping +\definecolor[darkyellow][y=.625] % a CMYK color +\definecolor[darkred] [r=.625] % a RGB color +\definecolor[darkgray] [s=.625] % a gray scale +\stoptyping + +These are the colors we used in this document. The next example uses two of them. + +\startbuffer +\startuseMPgraphic{color demo} + pickup pencircle scaled 1mm ; + path p ; p := fullcircle xscaled 10cm yscaled 1cm ; + fill p withcolor \MPcolor{darkgray} ; + draw p withcolor \MPcolor{darkred} ; +\stopuseMPgraphic + +\useMPgraphic{color demo} +\stopbuffer + +\typebuffer + +The previous example uses a pure \RGB\ red shade, combined with a gray fill. + +\startlinecorrection[blank] +\getbuffer +\stoplinecorrection + +Originally \METAPOST\ only supported only the \RGB\ and gray color spaces. In \METAFUN\ +we also supported \CMYK\ and spot colors, using an extension mechanism that hooked into +the backend. At some point \METAPOST\ got native support for \CMYK. When you use mixed +color models you need to be aware of the fact that their related variables have different +types: + +\starttabulate[||T|T|] +\NC gray \NC numeric \NC s \NC \NR +\NC rgb \NC color \NC (r,g,b) \NC \NR +\NC cmyk \NC cmykcolor \NC (c,m,y,k) \NC \NR +\stoptabulate + +Because in \METAFUN\ (\type {mpiv}) we hook deeply into the \CONTEXT\ color +mechanisms we can use symbolic names instead. and these are just strings. + +There is a fundamental difference between a yellow as defined in \CONTEXT\ using +\CMYK\ and a \RGB\ yellow. + +\startbuffer +\definecolor[cmyyellow] [y=1] +\definecolor[rgbyellow] [r=1,g=1] + +\definecolor[cmydarkyellow][y=.625] +\definecolor[rgbdarkyellow][r=.625,g=.625] +\stopbuffer + +\typebuffer \getbuffer + +\in {Figure} [fig:many yellows:pass] demonstrates what happens when we multiply +colors by a factor. Since we are not dealing with real \CMYK\ colors, +multiplication gives different results for \CMYK\ colors passed as \type +{\MPcolor}. \in {Figure} [fig:many yellows:fetch] we show the same colors but +this time we use a different method, one that avoids the \TEX\ macro. This method +can be used in \MKIV. We will use both methods in examples. + +\def\TestColor#1% + {\startuseMPgraphic{yellow} + fill unitsquare xscaled (.30*\the\hsize) yscaled 1cm withcolor #1 ; + \stopuseMPgraphic + \useMPgraphic{yellow}} + +\startbuffer +\setuptype[style=\ttx]% +\startcombination[3*3] + {\TestColor{(0,0,1,0)}} {\type{(0,0,1,0)}} + {\TestColor{(1,1,0)}} {\type{(1,1,0)}} + {\TestColor{(.5,.5,0)}} {\type{(.5,.5,0)}} + {\TestColor{\MPcolor{rgbyellow}}} {\type{\MPcolor{rgbyellow}}} + {\TestColor{\MPcolor{rgbdarkyellow}}} {\type{\MPcolor{rgbdarkyellow}}} + {\TestColor{.5\MPcolor{rgbyellow}}} {\type{.5\MPcolor{rgbyellow}}} + {\TestColor{\MPcolor{cmyyellow}}} {\type{\MPcolor{cmyyellow}}} + {\TestColor{\MPcolor{cmydarkyellow}}} {\type{\MPcolor{cmydarkyellow}}} + {\TestColor{.5\MPcolor{cmyyellow}}} {\type{.5\MPcolor{cmyyellow}}} +\stopcombination +\stopbuffer + +\placefigure + [here][fig:many yellows:pass] + {All kinds of yellow (passing valued from \TEX).} + {\getbuffer} + +\startbuffer +\setuptype[style=\ttx]% +\startcombination[3*3] + {\TestColor{(0,0,1,0)}} {\type{(0,0,1,0)}} + {\TestColor{(1,1,0)}} {\type{(1,1,0)}} + {\TestColor{(.5,.5,0)}} {\type{(.5,.5,0)}} + {\TestColor{"rgbyellow"}} {\type{"rgbyellow"}} + {\TestColor{"rgbdarkyellow"}} {\type{"rgbdarkyellow"}} + {\TestColor{.5namedcolor("rgbyellow")}} {\type{.5namedcolor("rgbyellow")}} + {\TestColor{"cmyyellow"}} {\type{"cmyyellow"}} + {\TestColor{"cmydarkyellow"}} {\type{"cmydarkyellow"}} + {\TestColor{.5namedcolor("cmyyellow")}} {\type{.5namedcolor("cmyyellow")}} +\stopcombination +\stopbuffer + +\placefigure + [here][fig:many yellows:fetch] + {All kinds of yellow (fetching values from \TEX).} + {\getbuffer} + +So, \type {.625red} is the same as \type {[r=.5]}, but \type {.625yellow} is not +the same as \type {[y=.5]}, but matches \type {[r=.5,g=.5]}. \in {Figure} +[fig:some reds] shows the pure and half reds. + +\def\TestColor#1% + {\startMPcode + fill unitsquare xscaled (.30*\the\hsize) yscaled 1cm withcolor #1 ; + \stopMPcode} + +\startbuffer +\setuptype[style=\ttx]\setupcolors[mpcmyk=no] +\startcombination[3*2] + {\TestColor{red}} {\type{red}} + {\TestColor{(1,0,0)}} {\type{(1,0,0)}} + {\TestColor{(.625,0,0)}} {\type{(.625,0,0)}} + {\TestColor{"red"}} {\type{"red")}} + {\TestColor{"darkred"}} {\type{"darkred")}} + {\TestColor{.625namedcolor("red")}} {\type{.625namedcolor("red")}} +\stopcombination +\stopbuffer + +\placefigure + [here][fig:some reds] + {Some kinds of red.} + {\getbuffer} + +In order to prevent problems, we advise you to stick to \RGB\ color +when you create documents for screen and \CMYK\ when producing for print. + +In the \METAFUN\ macro collection there is a macro \type {cmyk} that takes four +arguments, representing the cyan, magenta, yellow, and black component. Nowadays +you don't need it as we have native \CMYK. + +\startbuffer +fill unitsquare xyscaled (10cm, 5mm) withcolor cmyk(1,0,.3,.3) ; +fill unitsquare xyscaled (10cm,-5mm) withcolor (1,.3,0,.3) ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +If you take a close look at the numbers, you will notice that the cyan component +results in a 100\% ink contribution. You will also notice that 30\% black ink is +added. This means that we cannot safely convert this color to \RGB\ ($r=1-c-k<0$) +without losing information. Nevertheless the previous blue bar is presented all +right. This is due to the fact that in \METAFUN\ the \CMYK\ colors are handled as +they should, even when \METAPOST\ does not support this color model. + +If you use this feature independent of \CONTEXT, you need to enable it by setting +\type {cmykcolors} to \type {true}. You have to convert the resulting graphic to +\PDF\ by using for instance the \type {mptopdf} suite. + +In \CONTEXT\ you can influence this conversion by changing parameters related to +color handling: + +\starttyping +\setupcolors[cmyk=yes,rgb=no] +\stoptyping + +Unless you know what you are doing, you don't have to change the default settings +(both \type {yes}). In the \CONTEXT\ reference manual you can also read how color +reduction can be handled. + +Special care should be paid to gray scales. Combining equal quantities of the +three color inks will not lead to a gray scale, but to a muddy brown shade. + +\startbuffer +fill fullsquare xyscaled (10cm, 2cm) withcolor .5white ; +fill fullsquare xyscaled ( 6cm,1.5cm) withcolor cmyk(.5,.5,.5,0) ; +fill fullsquare xyscaled ( 2cm, 1cm) withcolor cmyk(0,0,0,.5) ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +In \in {figure} [fig:cmyk 1] \in {and} [fig:cmyk 2] you can see some more colors +defined in the \CMYK\ color space. When you display the screen version of this +document, you will notice that the way colors are displayed can differ per +viewer. This is typical for \CMYK\ colors and has to do with the fact that some +assumptions are made with respect to the (print) medium. + +\startbuffer[mp] + fill fullcircle xyscaled (3cm,1cm) withcolor \MPcolor{test} ; +\stopbuffer + +\startbuffer[cmyk] +\startcombination[4*1] + {\definecolor[test][c=1,y=.3,k=.3] \processMPbuffer[mp]} {c=1 y=.3 k=.3} + {\definecolor[test][c=.9,y=.15] \processMPbuffer[mp]} {c=.9 y=.15} + {\definecolor[test][c=.25,y=.8] \processMPbuffer[mp]} {c=.25 y=.8} + {\definecolor[test][c=.45,y=.1] \processMPbuffer[mp]} {c=.45 y=.1} +\stopcombination +\stopbuffer + +\placefigure + [here][fig:cmyk 1] + {\CMYK\ support enabled.} + {\getbuffer[cmyk]} + +\placefigure + [here][fig:cmyk 2] + {\CMYK\ support disabled, no support in \METAPOST.} + {\setupcolors[cmyk=no]\getbuffer[cmyk]\setupcolors[cmyk=yes]} + +\stopsection + +% \startsection[title={Common definitions}] +% +% \index{inclusions} +% \index{common definitions} +% +% When using many graphics, there is a chance that they share common definitions. +% Such shared components can be defined by: +% +% \starttyping +% \startMPinclusions +% color mycolor ; mycolor := .625red ; +% \stopMPinclusions +% \stoptyping +% +% {\em The following is only true for \CONTEXT\ \MKII ! Users of \MKIV\ can skip +% this section.} +% +% All \METAPOST\ graphics defined in the document end up in the files \type +% {mpgraph.mp} and \type {mprun.mp}. When processed, they produce (sometimes many) +% graphic files. When you use \CONTEXT\ \MKII\ and \TEXEXEC\ to process documents, +% these two files are processed automatically after a run so that in a next run, +% the right graphics are available. +% +% When you are using the \type {web2c} distribution, \CONTEXT\ can call \METAPOST\ +% at runtime and thereby use the right graphics instantaneously. In order to use +% this feature, you have to enable \type {\write18} in the file \type {texmf.cnf}. +% Also, in the file \type {cont-sys.tex}, that holds local preferences, or in the +% document source, you should say: +% +% \starttyping +% \runMPgraphicstrue +% \stoptyping +% +% This enables runtime generation of graphics using the low level \TEX\ command +% \type {\write18}. First make sure that your local brand of \TEX\ supports this +% feature. A simple test is making a \TEX\ file with the following line: +% +% \starttyping +% \immediate\write18{echo It works} +% \stoptyping +% +% If this fails, you should consult the manual that comes with your system, locate +% an expert or ask around on the \CONTEXT\ mailing list. Of course you can also +% decide to let \TEXEXEC\ take care of processing the graphics afterwards. This has +% the advantage of being faster but has the disadvantage that you need additional +% \TEX\ runs. +% +% If you generate the graphics at run time, you should consider to turn on graphic +% slot recycling, which means that you often end up with fewer intermediate files: +% +% \starttyping +% \recycleMPslotstrue +% \stoptyping +% +% There are a few more low level switches and features, but these go beyond the +% purpose of this manual. Some of these features, like the option to add tokens to +% \type {\everyMPgraphic} are for experts only, and fooling around with them can +% interfere with existing features. +% +% \stopsection + +\startsection[title={One page graphics}] + +An advantage of using \CONTEXT\ to make your \METAPOST\ graphics is you don't +have to bother about specials, font inclusion and all those nasty things that can +spoil a good day. An example of such a graphic is the file \type {mfun-800} that +resides on the computer of the author. + +\typefile{mfun-800} + +Given that \CONTEXT\ is present on your system, you can process this file with: + +\starttyping +context mfun-800 +\stoptyping + +You can define many graphics in one file. Later you can include individual pages +from the resulting \PDF\ file in your document: + +\startbuffer +\placefigure + {A silly figure, demonstrating that stand||alone||graphics + can be made.} + {\typesetfile[mfun-800.tex][page=1]} +\stopbuffer + +\typebuffer + +In this case the \type {page=1} specification is not really needed. You can scale +and manipulate the figure in any way supported by the macro package that you use. + +\getbuffer + +\stopsection + +\startsection[title={Managing resources}] + +A graphic consists of curves, either or not filled with a given color. A graphic +can also include text, which means that fonts are used. Finally a graphic can +have special effects, like a shaded fill. Colors, fonts and special effects go +under the name resources, since they may demand special care or support from the +viewing or printing device. + +% When fonts are used, a \METAPOST\ file is not self contained. This means that the +% postprocessing program has to deal with the fonts. In \CONTEXT, the special +% driver |<|and \PDFTEX\ support is considered as such|>| takes care of this. + +Special effects, like shading, are supported by dedicated \METAPOST\ modules. +These are included in the \CONTEXT\ distribution and will be discussed later in +\in {chapter} [sec:effects]. + +Since \METAPOST\ supports color, an embedded graphic can be rather colorful. +However, when color support is disabled or set up to convert colors to gray +scales, \CONTEXT\ will convert the colors in the graphics to gray scales. + +\startbuffer[circle] + colorcircle(4cm,red,green,blue) ; +\stopbuffer + +\startbuffer +\startcombination[3*1] + {\setupcolors[state=start]\processMPbuffer[circle]} {full color} + {\setupcolors[state=stop]\processMPbuffer[circle]} {weighted gray} + {\setupcolors[state=stop,factor=no]\processMPbuffer[circle]} {linear gray} +\stopcombination +\stopbuffer + +You may wonder what the advantage is of weighted gray conversion. \in {Figure} +[fig:color circles] shows the difference between natural colors, weighted gray +scales and straightforward, non||weighted, gray scales. + +\placefigure + [here][fig:color circles] + {The advantage of weighted gray over linear gray.} + {\getbuffer\setupcolors[state=start,factor=yes]} % just to be sure + +When we convert color to gray, we use the following formula. This kind of +conversion also takes place in black and white televisions. + +\placeformula [-] + \startformula + G = .30r + .59g + .11b + \stopformula + +\in {Section} [sec:conversion] introduces the \type {grayed} operation that you +can use to convert a colored picture into a gray one. This macro uses the same +conversion method as mentioned here. + +\stopsection + +\startsection[title={Instances}] + +There are a few instances predefined and if you want to isolate your own +graphics from whatever \CONTEXT\ itself cooks up, you can define more as the +extra overhead can be neglected. + +\starttabulate[|T|T|T|T|T|] +\BC name \BC format \BC extensions \BC initializations \BC method \NC \NR +\NC metafun \NC metafun \NC yes \NC yes \NC \NC \NR +\NC extrafun \NC metafun \NC yes \NC yes \NC \NC \NR +\NC lessfun \NC metafun \NC \NC \NC \NC \NR +\NC doublefun \NC metafun \NC yes \NC yes \NC double \NC \NR +\NC binaryfun \NC metafun \NC yes \NC yes \NC binary \NC \NR +\NC decimalfun \NC metafun \NC yes \NC yes \NC decimal \NC \NR +\stoptabulate + +According to this the \type {doublefun} instance is defined as: + +\starttyping +\defineMPinstance + [doublefun] + [format=metafun, + extensions=yes, + initializations=yes, + method=double] +\stoptyping + +The \type {extensions} key relates to: + +\starttyping +\startMPextensions + % some code +\stopMPextensions +\stoptyping + +that are used to pass (common) extensions to the instance. The \type +{initializations} key relates to: + +\starttyping +\startMPinitializations + % some code +\stopMPinitializations +\stoptyping + +that are used to communicate \TEX\ properties to the instance (they are +expanded each graphic). Instance bound definitions can be set with: + +\starttyping +\startMPdefinitions{doublefun} + % some code +\stopMPdefinitions +\stoptyping + +We do have more instances, for instance for the chemical subsystem. If you load +the \type {graph} module you get a double precision \type {graph} instance. We might +use more private ones in the future. + +When you make graphic pages, you can do this: + +\starttyping +\startMPpage[instance=doublefun] + % some code +\stopMPpage +\stoptyping + +When you use the other commands you can optionally specify an instance: + +\startbuffer[metafun] +\startMPcode{metafun} + draw textext(decimal pi) scaled 2 withcolor .625red ; + draw boundingbox currentpicture enlarged 2pt ; +\stopMPcode +\stopbuffer + +\startbuffer[extrafun] +\startMPcode{extrafun} + draw textext(decimal pi) scaled 2 withcolor .625green ; + draw boundingbox currentpicture enlarged 2pt ; +\stopMPcode +\stopbuffer + +\startbuffer[doublefun] +\startMPcode{doublefun} + draw textext(decimal pi) scaled 2 withcolor .625blue ; + draw boundingbox currentpicture enlarged 2pt ; +\stopMPcode +\stopbuffer + +\startbuffer[binaryfun] +\startMPcode{binaryfun} + draw textext(decimal pi) scaled 2 withcolor .625yellow ; + draw boundingbox currentpicture enlarged 2pt ; +\stopMPcode +\stopbuffer + +\startbuffer[decimalfun] +\startMPcode{decimalfun} + draw textext(decimal pi) scaled 2 withcolor .375white ; + draw boundingbox currentpicture enlarged 2pt ; +\stopMPcode +\stopbuffer + +\typebuffer[metafun,extrafun,doublefun,binaryfun,decimalfun] + +The result is shown in \in {figure} [fig:instances] and as expected there +is a different value for $\pi$ reported. + +\startplacefigure[reference=fig:instances,title={Instances can use different number systems.}] + \startcombination[1*5] + {\getbuffer[metafun]} {metafun} + {\getbuffer[extrafun]} {extrafun} + {\getbuffer[doublefun]} {doublefun} + {\getbuffer[binaryfun]} {binaryfun} + {\getbuffer[decimalfun]} {decimalfun} + \stopcombination +\stopplacefigure + +You need to be aware of the fact that the results of a (for instance) double +instance can differ from a scaled (the default) one. As long as graphics can be +processed in both models (which is the case as long as the dimensions stay below +4096 base points) the outcome is probably not that different. However, we've seen +that the accuracy of for instance $\pi$ (just a variable) differs. I like to use +random values and the random generators are definitely different: each of the +number libraries has its own implementation. Let's look at that. We define two +random graphic generators: + +\startbuffer +\startuseMPgraphic{normaldeviate} + randomseed := 100 ; + draw fullsquare + withpen pencircle scaled 1/200 + withcolor .5white ; + for i=1 upto 500 : + draw (normaldeviate,normaldeviate) + scaled 1/3 + withpen pencircle scaled 1/30 + withtransparency (1,.5) ; + endfor ; + setbounds currentpicture to + boundingbox fullcircle + enlarged 1/2 ; + currentpicture := + currentpicture + xsized (2TextWidth/5) ; +\stopuseMPgraphic +\stopbuffer + +\typebuffer \getbuffer + +And: + +\startbuffer +\startuseMPgraphic{uniformdeviate} + randomseed := 100 ; + draw fullsquare + withpen pencircle scaled 1/200 + withcolor .5white ; + for i=1 upto 500 : + draw (-1/2 + uniformdeviate 1,-1/2 + uniformdeviate 1) + withpen pencircle scaled 1/30 + withtransparency (1,.5) ; + endfor ; + setbounds currentpicture to + boundingbox fullcircle + enlarged 1/2 ; + currentpicture := + currentpicture + xsized (2TextWidth/5) ; +\stopuseMPgraphic +\stopbuffer + +\typebuffer \getbuffer + +We show the results for a normaldeviate in \in {figure} [fig:random:1] \in {upto} +[fig:random:4] you see the randomizers per number system. In \in {figure} +[fig:random:compared] we demonstrate that the scaled version has its own variant. + +\unexpanded\def\TestRandomFun#1#2#3% + {\startMPcode{#1} + draw image(\includeMPgraphic{#2}) + withcolor #3 ; + \stopMPcode} + +\startplacefigure[reference=fig:random:1,title={The scaled randomizers.}] + \pushrandomseed + \startcombination + {\TestRandomFun{metafun} {normaldeviate} {darkred}} {normaldeviate} + {\TestRandomFun{metafun} {uniformdeviate}{darkred}} {uniformdeviate} + \stopcombination + \poprandomseed +\stopplacefigure + +\startplacefigure[reference=fig:random:2,title={The double randomizers.}] + \pushrandomseed + \startcombination + {\TestRandomFun{doublefun} {normaldeviate} {darkgreen}} {normaldeviate} + {\TestRandomFun{doublefun} {uniformdeviate}{darkgreen}} {uniformdeviate} + \stopcombination + \poprandomseed +\stopplacefigure + +\startplacefigure[reference=fig:random:3,title={The decimal randomizers.}] + \pushrandomseed + \startcombination + {\TestRandomFun{decimalfun}{normaldeviate} {darkblue}} {normaldeviate} + {\TestRandomFun{decimalfun}{uniformdeviate}{darkblue}} {uniformdeviate} + \stopcombination + \poprandomseed +\stopplacefigure + +\startplacefigure[reference=fig:random:4,title={The binary randomizers.}] + \pushrandomseed + \startcombination + {\TestRandomFun{binaryfun} {normaldeviate} {darkyellow}} {normaldeviate} + {\TestRandomFun{binaryfun} {uniformdeviate}{darkyellow}} {uniformdeviate} + \stopcombination + \poprandomseed +\stopplacefigure + +\startplacefigure[reference=fig:random:compared,title={Normaldeviate and uniformdeviate overlayed.}] + \pushrandomseed + \startcombination[2*1] + \bgroup + \startoverlay + {\TestRandomFun{metafun} {normaldeviate} {darkred}} + {\TestRandomFun{doublefun} {normaldeviate} {darkgreen}} + {\TestRandomFun{decimalfun}{normaldeviate} {darkblue}} + {\TestRandomFun{binaryfun} {normaldeviate} {darkyellow}} + \stopoverlay + \egroup {normaldeviate} + \bgroup + \startoverlay + {\TestRandomFun{metafun} {uniformdeviate}{darkred}} + {\TestRandomFun{doublefun} {uniformdeviate}{darkgreen}} + {\TestRandomFun{decimalfun}{uniformdeviate}{darkblue}} + {\TestRandomFun{binaryfun} {uniformdeviate}{darkyellow}} + \stopoverlay + \egroup {uniformdeviate} + \stopcombination + \poprandomseed +\stopplacefigure + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/metafun/metafun-environment-layout.tex b/doc/context/sources/general/manuals/metafun/metafun-environment-layout.tex new file mode 100644 index 000000000..409839cba --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/metafun-environment-layout.tex @@ -0,0 +1,151 @@ +\startenvironment metafun-environment-layout + +\setupsystem + [random=big] + +\setupfootertexts + [section][] % [Preliminary Version \currentdate][] + [][section] % [][Preliminary Version \currentdate] + +\useMPlibrary + [clp,txt] + +\definepapersize + [mine] + [width=21cm, + height=28cm] + +\setuppapersize + [mine] + [A4] + +\setuplayout + [topspace=1cm, + backspace=3cm, + cutspace=3cm, + leftmargin=.75cm, + leftmargindistance=.5cm, + rightmargin=1.25cm, + rightmargindistance=1cm, + header=1cm, + headerdistance=1cm, + footer=1cm, + footerdistance=1cm, + width=middle, + height=middle, + % marking=on, + location=middle] + +\startmode[book] + + % \definepapersize + % [mine] + % [width=21cm, + % height=24cm] + % + % \setuppapersize + % [mine] + % [oversized] + % + % \setuplayout + % [backspace=2.5cm, + % cutspace=3.5cm] + + \setuplayout + [marking=on, + scale=\luaexpr{24/28}] + +\stopmode + +\startmode[print] + + \setuppapersize + [mine] + [mine] + +\stopmode + +\setupcolumns + [distance=1cm] + +\setuppagenumbering + [alternative=doublesided] + +\definetypeface [metafunbodyfont] [rm] [serif] [pagella] [default] +\definetypeface [metafunbodyfont] [ss] [sans] [modern] [default] +\definetypeface [metafunbodyfont] [tt] [mono] [modern] [default] +\definetypeface [metafunbodyfont] [mm] [math] [palatino] [default] + +\setupbodyfont [metafunbodyfont,10pt] % 11 pt and 12pt -> errors due to intersection mess + +\definefont[RotFont][RegularBold*default] + +% \setupindenting +% [medium,yes] + +\setupwhitespace + [medium] + +\setuptyping + [margin=standard, + blank=halfline] + +\definecolor [darkred] [r=.625] +\definecolor [darkyellow] [r=.625,g=.625] % not: [y=.625] +\definecolor [darkgray] [s=.625] +\definecolor [lightgray] [s=.875] + +\definecolor [metafun] [darkred] + +\startMPinclusions + color darkred ; darkred := \MPcolor{darkred} ; + color darkyellow ; darkyellow := \MPcolor{darkyellow} ; + color darkgray ; darkgray := \MPcolor{darkgray} ; + color lightgray ; lightgray := \MPcolor{lightgray} ; +\stopMPinclusions + +\setupinteraction % otherwise funny page dimensions due to + [state=start, % grouping half way the file in demo text + style=, + color=, + contrastcolor=] + +% \enabledirectives[refences.linkmethod=page] + +% \setupstructure % needs \startchapter +% [state=start] + +\placebookmarks + [chapter,title,section] + [all] + [force=yes] + +\setuptolerance + [verytolerant] + +\definestartstop + [intro] + [style=slanted, + after=\blank] + +\setupquote + [before=\blank\startnarrower, + after=\stopnarrower\blank] + +\setuplist + [chapter] + [after={\blank[line]}] + +\setupcombinedlist + [content] + [aligntitle=yes, + alternative=c, + interaction=all] + +\setuptabulate + [rulecolor=darkyellow, + rulethickness=1pt] + +\setuplist[chapter][style=bold] + +\stopenvironment diff --git a/doc/context/sources/general/manuals/metafun/metafun-environment-samples.tex b/doc/context/sources/general/manuals/metafun/metafun-environment-samples.tex new file mode 100644 index 000000000..5991a61d5 --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/metafun-environment-samples.tex @@ -0,0 +1,321 @@ +\startenvironment metafun-environment-sample + +\startuseMPgraphic{sample setup} + numeric Scale ; Scale := 2cm ; + numeric Size ; Size := 2.5mm/Scale ; + numeric Pen ; Pen := .25mm/Scale ; + path Path ; + pickup pencircle scaled (4Pen) ; + def InRed = withcolor .625red enddef ; + def InYellow = withcolor .625yellow enddef ; + def InGray = withpen pencircle scaled Pen withcolor .625white enddef ; + def InBetween= withpen pencircle scaled (4Pen) withcolor .800white enddef ; + def InBlack = withpen pencircle scaled Pen enddef ; + def InWhite = withpen pencircle scaled Pen withcolor white enddef ; + def DrawArrow text t = + draw t ; Path := boundingbox currentpicture ; + drawarrow t ; setbounds currentpicture to Path ; + enddef ; + def ColorCircle = + fill llcircle withcolor .625red ; + fill lrcircle withcolor .625green ; + fill urcircle withcolor .625blue ; + fill ulcircle withcolor .625yellow ; + enddef ; + evenly := dashpattern(on (3mm/Scale) off (3mm/Scale)) ; + withdots := dashpattern(off (2.5mm/Scale) on 0 off (2.5mm/Scale)) ; + ahlength := 4mm/Scale ; ahangle := 30 ; + draw (origin shifted (0,Size)--origin shifted (0,-Size)) ; + draw (origin shifted (Size,0)--origin shifted (-Size,0)) ; + picture Origin ; Origin := currentpicture ; + setbounds Origin to origin--cycle ; + currentpicture := nullpicture ; +\stopuseMPgraphic + +\startuseMPgraphic{sample finish} + draw boundingbox currentpicture InBlack ; + draw Origin InGray ; + currentpicture := currentpicture scaled Scale ; +\stopuseMPgraphic + +% fm = metafun macro +% fv = metafun variable +% mc = metapost concept +% mm = metapost macro +% mp = metapost primitive +% mv = metapost variable + +\starttexdefinition unexpanded DoDoSampleHead#1#2#3 + \setbox\scratchbox\vbox { + \tabskip\zeropoint + \tt\tfx + \halign { + \strut\hss##\unskip\unskip + \cr#3\cr#1\cr + } + } + \ht\scratchbox\ht\strutbox + \dp\scratchbox\dp\strutbox + \noligature{#2}\black + \hfill + \box\scratchbox + \ignorespaces +\stoptexdefinition + +\starttexdefinition unexpanded DoSampleHead #1#2#3 + \processaction + [#1] + [fm=>\DoDoSampleHead{metafun macro}{#2}{#3}, + fv=>\DoDoSampleHead{metafun variable}{#2}{#3}, + mc=>\DoDoSampleHead{metapost concept}{#2}{#3}, + mm=>\DoDoSampleHead{metapost macro}{#2}{#3}, + mp=>\DoDoSampleHead{metapost primitive}{#2}{#3}, + mv=>\DoDoSampleHead{metapost variable}{#2}{#3}] +\stoptexdefinition + +\starttexdefinition unexpanded SampleHead #1#2#3 + \expanded{\extrosubject{\DoSampleHead{#1}{#2}{\detokenize{#3}}}} +\stoptexdefinition + +\starttexdefinition unexpanded StartSample + \doquintuplegroupempty\doStartSample +\stoptexdefinition + +\starttexdefinition unexpanded StopSample + % dummy +\stoptexdefinition + +\starttexdefinition unexpanded doStartSample #1#2#3#4#5#6 StopSample + \bgroup + \SampleHead{#1}{#2}{#3} + \startuseMPgraphic{dummy} + \includeMPgraphic{sample setup} + #6 + \includeMPgraphic{sample finish} + \stopuseMPgraphic + \blank[samepage] + \startlinecorrection[blank] + \useMPgraphic{dummy} + \stoplinecorrection + \egroup +\stoptexdefinition + +\starttexdefinition unexpanded ShowSampleZ #1#2#3 + \bgroup + \SampleHead{#1}{#2}{} + \blank[samepage] + #3 + \par + \egroup +\stoptexdefinition + +\starttexdefinition unexpanded ShowSampleA #1#2#3 + \StartSample{#1}{#2}{#3} + path p ; p := #3 ; % freeze randomized + if length(p)>0 : + DrawArrow p InRed ; + fi ; + drawpoints p InBetween ; + \StopSample +\stoptexdefinition + +\starttexdefinition unexpanded ShowSampleB #1#2#3#4 + \StartSample{#1}{#2}{#4} + DrawArrow (#3) InRed ; + DrawArrow (#4) InYellow ; + drawpoints (#3) InBetween ; + drawpoints (#4) InBetween ; + \StopSample +\stoptexdefinition + +\starttexdefinition unexpanded ShowSampleC #1#2#3#4 + \StartSample{#1}{#2}{#4} + path bb ; bb := boundingbox #3 ; + DrawArrow #3 InRed ; + draw #4 withpen pencircle scaled .15 InYellow ; + setbounds currentpicture to bb ; + \StopSample +\stoptexdefinition + +\starttexdefinition unexpanded ShowSampleD #1#2#3#4 + \StartSample{#1}{#2}{#4} + DrawArrow #3 InRed ; + setbounds currentpicture to #4 ; + \StopSample +\stoptexdefinition + +\starttexdefinition unexpanded ShowSampleDD #1#2#3#4 + \StartSample{#1}{#2}{#4} + DrawArrow #3 InRed ; + DrawArrow #4 InYellow ; + \StopSample +\stoptexdefinition + +\starttexdefinition unexpanded ShowSampleE #1#2#3#4 + \StartSample{#1}{#2}{#4} + fill fullcircle scaled 1cm InRed ; + currentpicture := currentpicture #3 ; + Scale := 1 ; + \StopSample +\stoptexdefinition + +\starttexdefinition unexpanded ShowSampleF #1#2#3#4 + \StartSample{#1}{#2}{#4} + DrawArrow #3 InRed ; + drawdot #4 InYellow ; + \StopSample +\stoptexdefinition + +\starttexdefinition unexpanded ShowSampleG #1#2#3#4 + \StartSample{#1}{#2}{#4} + draw #3 InRed ; + drawdot #4 InYellow ; + \StopSample +\stoptexdefinition + +\starttexdefinition unexpanded ShowSampleH #1#2#3#4#5 + \StartSample{#1}{#2}{#5} + DrawArrow #3 InRed ; + DrawArrow #4 InYellow ; + drawdot #5 InWhite ; + \StopSample +\stoptexdefinition + +\starttexdefinition unexpanded ShowSampleHH #1#2#3 + \StartSample{#1}{#2}{#3} + draw #3 InRed ; + \StopSample +\stoptexdefinition + +\starttexdefinition unexpanded ShowSampleI #1#2#3 + \StartSample{#1}{#2}{#3} + draw fullcircle InRed #3 ; + \StopSample +\stoptexdefinition + +\starttexdefinition unexpanded ShowSampleII #1#2#3 + \StartSample{#1}{#2}{#3} + draw fullcircle #3 InRed ; + \StopSample +\stoptexdefinition + +\starttexdefinition unexpanded ShowSampleJ #1#2#3 + \StartSample{#1}{withpen #2}{withpen #3 scaled 2mm} + draw fullcircle xscaled 2 withpen #3 scaled Pen InRed ; + \StopSample +\stoptexdefinition + +\starttexdefinition unexpanded ShowSampleK #1#2#3 + \StartSample{#1}{withpen #2}{withpen #3} + draw fullcircle xscaled 2 withpen #3 InRed ; + \StopSample +\stoptexdefinition + +\starttexdefinition unexpanded ShowSampleL #1#2#3 + \StartSample{#1}{#2}{#2 #3} + #2 #3 InRed; + \StopSample +\stoptexdefinition + +\starttexdefinition unexpanded ShowSampleM #1#2#3 + \StartSample{#1}{#2}{#2 #3} + fill boundingbox (#3--cycle) InRed ; + #2 #3 ; + \StopSample +\stoptexdefinition + +\starttexdefinition unexpanded ShowSampleN #1#2#3#4 + \StartSample{#1}{#2}{#3} + #3 ; + draw #4 withpen pencircle scaled 25Pen InRed ; + \StopSample +\stoptexdefinition + +\starttexdefinition unexpanded ShowSampleO #1#2#3 + \StartSample{#1}{#2}{#3} + drawdot origin InRed ; + #3 scaled (2.5/Scale) InYellow ; + \StopSample +\stoptexdefinition + +\starttexdefinition unexpanded ShowSampleP #1#2#3 + \StartSample{#1}{#2}{#3} + drawdot origin InRed ; + #3 scaled (2.5/Scale) InYellow ; + \StopSample +\stoptexdefinition + +\starttexdefinition unexpanded ShowSampleQ #1#2#3 + \StartSample{#1}{#2}{#3} + #2 #3 withpen pencircle scaled 25Pen InRed ; + \StopSample +\stoptexdefinition + +\starttexdefinition unexpanded ShowSampleQQ #1#2#3 + \StartSample{#1}{#2}{#3} + #3 scaled (2.5/Scale) withpen pencircle scaled Pen InYellow ; + \StopSample +\stoptexdefinition + +\starttexdefinition unexpanded ShowSampleQQQ #1#2#3 + \StartSample{#1}{#2}{#3} + #3 scaled (2.5/Scale) withpen pencircle scaled Pen ; + \StopSample +\stoptexdefinition + +\starttexdefinition unexpanded ShowSampleR #1#2#3 + \StartSample{#1}{#2}{#3} + ColorCircle ; + addto currentpicture also (#3) shifted (bbwidth(currentpicture)+.1,0) ; + \StopSample +\stoptexdefinition + +\starttexdefinition unexpanded ShowSampleS #1#2#3 + \StartSample{#1}{#2}{#3} + Pen := Pen * Scale ; Scale := 1 ; #3 ;% + \StopSample +\stoptexdefinition + +\starttexdefinition unexpanded ShowSampleT #1#2#3#4 + \StartSample{#1}{#2}{#3} + #4 ; + \StopSample +\stoptexdefinition + +\starttexdefinition unexpanded ShowSampleU #1#2#3 + \StartSample{#1}{#2}{#3} + Scale := Scale / 5 ; + #3 ; + \StopSample +\stoptexdefinition + +\starttexdefinition unexpanded ShowSampleUU #1#2#3 + \StartSample{#1}{#2}{#3} + Scale := Scale / 10 ; + #3 ; + \StopSample +\stoptexdefinition + +\starttexdefinition unexpanded ShowSampleV #1#2#3#4 + \StartSample{#1}{#2}{#3} + Scale := Scale / 5 ; + Pen := Pen * 20 ; + #4 ; + Pen := Pen / 20 ; + \StopSample +\stoptexdefinition + +\starttexdefinition unexpanded ShowSampleW #1#2#3#4 + \StartSample{#1}{#2}{#3} + Scale := 1 ; + #4 ; + \StopSample +\stoptexdefinition + +\starttexdefinition unexpanded ShowSampleX #1#2#3 + \StartSample{#1}{#2}{#3} + #3 InRed ; + \StopSample +\stoptexdefinition + +\stopenvironment diff --git a/doc/context/sources/general/manuals/metafun/metafun-environment-screen.tex b/doc/context/sources/general/manuals/metafun/metafun-environment-screen.tex new file mode 100644 index 000000000..afeea7008 --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/metafun-environment-screen.tex @@ -0,0 +1,139 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\startenvironment mfun-environment-screen + +\enablemode[screen] + +\setuppapersize + [S6][S6] + +\setuplayout + [backspace=60pt, + topspace=60pt, + cutspace=0pt, + header=0pt, + footer=0pt, + bottom=20pt, + bottomdistance=40pt, + top=20pt, + topdistance=40pt, + leftmargin=30pt, + leftmargindistance=25pt, + rightmargin=0pt, + edge=0pt, + width=middle, + height=middle] + +\setupbodyfont + [9pt] + +\setuppagenumbering + [alternative=singlesided] + +\setupinteraction + [state=start, + style=bold, + color=darkred, + contrastcolor=darkred, + symbolset=navigation 3, + menu=on] + +\setupsymbolset + [navigation 3] + +\setupinteractionscreen + [option=max] + +\setupinteractionmenu + [bottom] + [unknownreference=yes, + state=start] + +\setuptoptexts + [] + [{\lightgray \bf Page \pagenumber + \doifcontent\quad{}{}\hbox{\getmarking[section]}}] + +\startinteractionmenu[bottom] + \txt \bf \lightgray \getmarking[chapter] \\ + \hfill + \bgroup + \setupinteraction[color=white,contrastcolor=white] + \got [CloseDocument] exit \\ + \egroup + \got [content] content \\ + \got [index] index \\ +% \got [commands] commands \\ + \got [reference] reference \\ + \setupinteraction[color=white,contrastcolor=white] + \got [PreviousJump] \symbol[PreviousJump] \\ + \got [previouspage] \symbol[previouspage] \\ + \got [nextpage] \symbol[nextpage] \\ + \got [NextJump] \symbol[NextJump] \\ +\stopinteractionmenu + +\starttexdefinition unexpanded ChapterCommand #1#2 + \framed [ + background=titled, + frame=off + ] { + #1 + \quad + #2 + } +\stoptexdefinition + +\startuseMPgraphic{PageFrame} + StartPage ; + save p, q, ranx, rany, minx, miny, maxx, maxy ; + pickup pencircle scaled 4pt ; + pair p[] ; path q[] ; numeric ranx, rany, minx, miny, maxx, maxy ; + minx := BackSpace/2 ; maxx := PaperWidth -minx ; ranx := minx/2 ; + miny := TopSpace /2 ; maxy := PaperHeight-miny ; rany := miny/2 ; + p[0] := llcorner Page ; + p[1] := (minx,0) randomshifted (ranx,0) ; + p[2] := (maxx,0) randomshifted (ranx,0) ; + p[3] := lrcorner Page ; + p[4] := (PaperWidth,miny) randomshifted (0,rany) ; + p[5] := (PaperWidth,maxy) randomshifted (0,rany) ; + p[6] := urcorner Page ; + p[7] := (maxx,PaperHeight) randomshifted (ranx,0) ; + p[8] := (minx,PaperHeight) randomshifted (ranx,0) ; + p[9] := ulcorner Page ; + p[10] := (0,maxy) randomshifted (0,rany) ; + p[11] := (0,miny) randomshifted (0,rany) ; + def page_color = (.4+uniformdeviate.3)*white enddef ; + fill Page withcolor \MPcolor{lightgray} ; + q[1] := p[9]--p[6]--p[ 5]--p[10]--cycle ; + q[2] := p[6]--p[3]--p[ 2]--p[ 7]--cycle ; + q[3] := p[3]--p[0]--p[11]--p[ 4]--cycle ; + q[4] := p[0]--p[9]--p[ 8]--p[ 1]--cycle ; + for i=1 upto 4: fill q[i] withcolor page_color ; endfor ; + q[1] := p[9]--p[8]--((p[8]--p[ 1]) intersectionpoint (p[10]--p[ 5]))--p[10]--cycle ; + q[2] := p[6]--p[5]--((p[5]--p[10]) intersectionpoint (p[ 2]--p[ 7]))--p[ 7]--cycle ; + q[3] := p[3]--p[4]--((p[4]--p[11]) intersectionpoint (p[ 7]--p[ 2]))--p[ 2]--cycle ; + q[4] := p[0]--p[1]--((p[1]--p[ 8]) intersectionpoint (p[ 4]--p[11]))--p[11]--cycle ; + for i=1 upto 4: fill q[i] withcolor page_color ; endfor ; + q[1] := p[ 8]--p[1] ; + q[2] := p[ 7]--p[2] ; + q[3] := p[10]--p[5] ; + q[4] := p[11]--p[4] ; + for i=1 upto 4: draw q[i] withcolor \MPcolor{darkred} ; endfor ; + StopPage ; +\stopuseMPgraphic + +% \setupbackgrounds[page][background=PageFrame] + +\setupbackgrounds + [page] + [background={PageFrame,backgraphics,foreground,foregraphics}] + +\defineoverlay[PageFrame][\useMPgraphic{PageFrame}] + +\startMPinclusions + background := \MPcolor{lightgray} ; +\stopMPinclusions + +\stopenvironment diff --git a/doc/context/sources/general/manuals/metafun/metafun-environment.tex b/doc/context/sources/general/manuals/metafun/metafun-environment.tex new file mode 100644 index 000000000..ca9fc24b3 --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/metafun-environment.tex @@ -0,0 +1,595 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\startenvironment metafun-environment + +\environment metafun-environment-layout + +\usemodule[abr-01,syntax] + +\startuseMPgraphic{cover page} + + numeric w ; w := PaperWidth -eps ; % or clip + numeric h ; h := PaperHeight-eps ; % or clip + + for i=0cm step 1cm until w : + for j=0cm step 1cm until h : + fill unitsquare scaled 1cm shifted (i,j) withcolor (.6+uniformdeviate.35)*white ; + endfor ; + endfor ; + + % clip currentpicture to unitsquare xyscaled (w,h) ; + + for i=0cm step 1cm until w+.5cm : + draw (i,0) -- (i,h) withpen pensquare scaled .5mm withcolor .625yellow ; + endfor ; + + for i=0cm step 1cm until h+.5cm : + draw (0,i) -- (w,i) withpen pensquare scaled .5mm withcolor .625yellow ; + endfor ; + +\stopuseMPgraphic + +\startuseMPgraphic{title page} + + StartPage ; + + \includeMPgraphic{cover page} + + picture p ; p := image (draw rawtextext("\darkred\definedfont[Sans]metafun" )) ; + picture q ; q := image (draw rawtextext("\darkred\definedfont[Sans]Hans Hagen")) ; + % picture r ; r := image (draw rawtextext("\darkred\definedfont[Sans]\doifnotmode{book}{context mkiv}")) ; + picture r ; r := image (draw rawtextext("\darkred\definedfont[Sans]context mkiv")) ; + + p := p xsized(PaperHeight - 2cm) ; + q := q xsized(PaperWidth - 8cm) ; + r := r xsized(6cm) ; + + p := p rotated 90 ; + r := r rotated 90 ; + + draw p shifted (urcorner Page - urcorner p - (1cm,1cm) - (-1mm,0) ) ; + draw q shifted (1cm, 1cm) ; + draw r shifted (urcorner Page - urcorner r - (5cm,2cm) ) ; + + StopPage ; + + setbounds currentpicture to Page ; + +\stopuseMPgraphic + +\startuseMPgraphic{back page} + + \includeMPgraphic{cover page} + +\stopuseMPgraphic + +\startuseMPgraphic{small grid} + + numeric w ; w := \overlaywidth ; + numeric h ; h := \overlayheight ; + numeric d ; d := .25cm ; + + drawoptions(withcolor (.6+uniformdeviate.35)*white) ; + + for i=0cm step d until w : + for j=0cm step d until h : + fill unitsquare scaled d shifted (i,j) ; + endfor ; + endfor ; + + drawoptions(withpen pencircle scaled .125mm withcolor .625yellow) ; + + for i=0 step d until w+d : draw (i,0) -- (i,h) ; endfor ; + for i=0 step d until h+d : draw (0,i) -- (w,i) ; endfor ; + +\stopuseMPgraphic + +\defineoverlay[title page][\useMPgraphic{title page}] + +\startnotmode[proof] + \defineoverlay[back page][\useMPgraphic{back page}] + \defineoverlay[small grid][\useMPgraphic{small grid}] +\stopnotmode + +% could be all in mp + +\starttexdefinition unexpanded OnGrid#1 + \hbox to \hsize \bgroup + \ifodd\realpageno + \hss + \fi + \setbox\scratchbox=\hbox { + \color[darkred]{#1} + } + \scratchoffset.25cm + \scratchwidth\wd\scratchbox + \ifdim\scratchwidth>\zeropoint + \advance \scratchwidth by .5\scratchoffset + \divide \scratchwidth by \scratchoffset + \multiply\scratchwidth by \scratchoffset + \advance \scratchwidth by 2\scratchoffset + \else + \scratchwidth8\scratchoffset + \fi + \dp\scratchbox \scratchoffset + \ht\scratchbox 2\scratchoffset + \framed [ + background=small grid, + frame=off, + offset=overlay + ] { + \hbox to \scratchwidth { + \hss + \box\scratchbox + \hss + } + } + \unless \ifodd\realpageno + \hss + \fi + \egroup +\stoptexdefinition + +\setupfootertexts + [margin] + [] + [\OnGrid{\doifelsetext{\getmarking[chapter]}{\getmarking[chapter]}{\getmarking[title]}}] + +\startuseMPgraphic{circled} + pickup pencircle scaled 1mm ; + drawoptions(withcolor (.6+uniformdeviate.35)*white) ; + fill fullcircle xscaled 1.5cm yscaled 1cm ; + drawoptions(withcolor .625yellow) ; + draw fullcircle xscaled 1.5cm yscaled 1cm ; +\stopuseMPgraphic + +\startnotmode[proof] + \defineoverlay[circled][\useMPgraphic{circled}] +\stopnotmode + +\starttexdefinition unexpanded Circled #1 + \framed [ + background=circled, + frame=off, + offset=overlay + ] { + \color[darkred]{#1} + } +\stoptexdefinition + +\setuppagenumbering + [location=] + +\setupheadertexts + [margin] + [][\hbox to \hsize{\hss\Circled\pagenumber\hss}] + +\setupheader + [style=bold] + +\setupfooter + [style=bold] + +\startuniqueMPgraphic{titled} + path p ; p := unitsquare xscaled OverlayWidth yscaled OverlayHeight ; + pickup pencircle scaled 1mm ; + drawoptions(withcolor .625yellow) ; + draw llcorner p -- lrcorner p ; + setbounds currentpicture to p ; +\stopuniqueMPgraphic + +\defineoverlay[titled][\uniqueMPgraphic{titled}] + +\starttexdefinition unexpanded ChapterCommand #1#2 + \ifconditional\headshownumber + \ifdim\leftmarginwidth<\rightmarginwidth + \donetrue + \else + \donefalse + \fi + \hskip-\ifdone\leftmargintotal\else\rightmargintotal\fi + \framed [ + background=titled, + frame=off, + offset=0pt + ] { + \hbox to \ifdone\leftmarginwidth\else\rightmarginwidth\fi { + #1 + \hss + } + \hskip\ifdone\leftmargindistance\else\rightmargindistance\fi + #2 + } + \else + \framed [ + background=titled, + frame=off, + offset=0pt + ] { + #2 + } + \fi +\stoptexdefinition + +\starttexdefinition unexpanded TitleCommand #1#2 + \framed [ + background=titled, + frame=off, + offset=0pt + ] { + #2 + } +\stoptexdefinition + +\starttexdefinition unexpanded IntroTitleCommand #1#2 + \framed [ + background=titled, + frame=off, + offset=0pt, + width=\textwidth + ] { + \hfill + #2 + } +\stoptexdefinition + +\starttexdefinition unexpanded ExtroTitleCommand #1#2 + \framed [ + background=titled, + frame=off, + offset=0pt, + width=\textwidth + ] { + \hss + #2 + \hss + } +\stoptexdefinition + +\setuphead + [chapter,section,subsection,subsubsection] + [color=darkred] + +\setuphead + [chapter] + [style=\bfc] + +\setuphead + [section] + [style=\bfa] + +\setuphead + [subsection] + [style=\bf] + +\setuphead + [subsubsection] + [style=\bf] + +\setuphead + [chapter,section,subsection,subsubsection] + [command=\ChapterCommand] + +\setuphead + [title,subject,subsubject,subsubsubject] + [command=\TitleCommand] + + +\definehead [introsubject] [subsubject] +\definehead [extrosubject] [subsubject] + +\setuphead [introsubject] [command=\IntroTitleCommand] +\setuphead [extrosubject] [command=\ExtroTitleCommand] + +\setuphead + [subsection,subsubject] + [before=\blank, + after=\blank] + +% charts + +\usemodule[chart] + +\setupFLOWcharts + [offset=0pt, + width=6\bodyfontsize, + height=3\bodyfontsize, + dx=\bodyfontsize, + dy=\bodyfontsize] + +\setupFLOWshapes + [framecolor=darkred] + +\setupFLOWlines + [color=darkyellow] + +% hm, slows down the whole doc + +\setupbackgrounds + [page] + [background={backgraphics,foreground,foregraphics}] + +\defineoverlay [backgraphics] [\positionoverlay{backgraphics}] +\defineoverlay [foregraphics] [\positionoverlay{foregraphics}] + +\startbuffer[shape-a] +\startuniqueMPgraphic{meta:hash}{linewidth,linecolor,angle,gap} + if unknown context_back : input mp-back ; fi ; + some_hash ( OverlayWidth, OverlayHeight , + \MPvar{linewidth}, \MPvar{linecolor} , + \MPvar{angle}, \MPvar{gap} ) ; +\stopuniqueMPgraphic +\stopbuffer + +\startbuffer[shape-b] +\setupMPvariables + [meta:hash] + [gap=.25\bodyfontsize, + angle=45, + linewidth=\overlaylinewidth, + linecolor=\overlaylinecolor] +\stopbuffer + +\startbuffer[shape-c] +\def\metahashoverlay#1{\uniqueMPgraphic{meta:hash}{angle=#1}} + +\defineoverlay[meta:hash:right] [\metahashoverlay{ +45}] +\defineoverlay[meta:hash:left] [\metahashoverlay{ -45}] +\defineoverlay[meta:hash:horizontal][\metahashoverlay{+180}] +\defineoverlay[meta:hash:vertical] [\metahashoverlay{ -90}] +\stopbuffer + +\startbuffer[symb-a] +\startuniqueMPgraphic{meta:button}{type,size,linecolor,fillcolor} + if unknown context_butt : input mp-butt ; fi ; + some_button ( \MPvar{type}, + \MPvar{size}, + \MPvar{linecolor}, + \MPvar{fillcolor} ) ; +\stopuniqueMPgraphic +\stopbuffer + +\startbuffer[symb-b] +\setupMPvariables + [meta:button] + [type=1, + size=2\bodyfontsize, + fillcolor=gray, + linecolor=darkred] +\stopbuffer + +\startbuffer[symb-c] +\def\metabuttonsymbol#1{\uniqueMPgraphic{meta:button}{type=#1}} + +\definesymbol[menu:left] [\metabuttonsymbol{101}] +\definesymbol[menu:right] [\metabuttonsymbol{102}] +\definesymbol[menu:list] [\metabuttonsymbol{103}] +\definesymbol[menu:index] [\metabuttonsymbol{104}] +\definesymbol[menu:person][\metabuttonsymbol{105}] +\definesymbol[menu:stop] [\metabuttonsymbol{106}] +\definesymbol[menu:info] [\metabuttonsymbol{107}] +\definesymbol[menu:down] [\metabuttonsymbol{108}] +\definesymbol[menu:up] [\metabuttonsymbol{109}] +\definesymbol[menu:print] [\metabuttonsymbol{110}] +\stopbuffer + +\hyphenation{tool-kit} + +\startbuffer[pagetext] +\subject{Edward R. Tufte} \input tufte \par +\subject{Donald E. Knuth} \input knuth \par +\subject{Douglas R. Hostadter} \input douglas \page +\stopbuffer + +\startbuffer[back-0] +\defineoverlay[page][\useMPgraphic{page}] +\setupbackgrounds[page][background=page] +\stopbuffer + +\startbuffer[back-1] +\startuseMPgraphic{page} + StartPage ; + path Main ; + if OnRightPage : + Main := lrcorner Field[OuterMargin][Text] -- + llcorner Field[Text] [Text] -- + ulcorner Field[Text] [Text] -- + urcorner Field[OuterMargin][Text] -- cycle ; + else : + Main := llcorner Field[OuterMargin][Text] -- + lrcorner Field[Text] [Text] -- + urcorner Field[Text] [Text] -- + ulcorner Field[OuterMargin][Text] -- cycle ; + fi ; + Main := Main enlarged 6pt ; + pickup pencircle scaled 2pt ; + fill Page withcolor .625white ; + fill Main withcolor .850white ; + draw Main withcolor .625red ; + StopPage ; +\stopuseMPgraphic +\stopbuffer + +\startbuffer[back-2] +\startuseMPgraphic{page} + StartPage ; + pickup pencircle scaled 2pt ; + fill Page withcolor .625white ; + fill Field[OuterMargin][Text] withcolor .850white ; + fill Field[Text] [Text] withcolor .850white ; + draw Field[OuterMargin][Text] withcolor .625red ; + draw Field[Text] [Text] withcolor .625red ; + StopPage ; +\stopuseMPgraphic +\stopbuffer + +\startbuffer[back-3] +\startuseMPgraphic{page} + StartPage ; + pickup pencircle scaled 2pt ; + fill Page withcolor .625white ; + fill Field[Text][Text] enlarged .5cm withcolor .850white ; + draw Field[Text][Text] enlarged .5cm withcolor .625red ; + StopPage ; +\stopuseMPgraphic +\stopbuffer + +\startbuffer[back-4] +\startuseMPgraphic{page} + StartPage ; + def somewhere = + (uniformdeviate 1cm,uniformdeviate 1cm) + enddef ; + path Main ; + Main := Field[Text][Text] lrmoved somewhere -- + Field[Text][Text] llmoved somewhere -- + Field[Text][Text] ulmoved somewhere -- + Field[Text][Text] urmoved somewhere -- cycle ; + pickup pencircle scaled 2pt ; + fill Page withcolor .625white ; + fill Main withcolor .850white ; + draw Main withcolor .625red ; + StopPage ; +\stopuseMPgraphic +\stopbuffer + +\startbuffer[back-4x] +\startuseMPgraphic{page} + StartPage ; + path Main ; Main := Field[Text][Text] randomized 1cm ; + pickup pencircle scaled 2pt ; + fill Page withcolor .625white ; + fill Main withcolor .850white ; + draw Main withcolor .625red ; + StopPage ; +\stopuseMPgraphic +\stopbuffer + +\startbuffer[back-5] +\startuseMPgraphic{page} + StartPage + for i=Top,Header,Text,Footer,Bottom : + for j=LeftEdge,LeftMargin,Text,RightMargin,RightEdge : + draw Field[i][j] withpen pencircle scaled 2pt withcolor .625red ; + endfor ; + endfor ; + StopPage +\stopuseMPgraphic +\stopbuffer + +\starttexdefinition unexpanded Literature #1#2#3 + \blank + \noindentation + #1 + \space + \begingroup + \bf + #2 + \endgroup + \space + #3 + \blank +\stoptexdefinition + +\environment metafun-environment-samples + +\startbuffer[handwrit] + +\usetypescript[serif][chorus] + +\definefont[SomeHandwriting][TeXGyreChorus-MediumItalic*default at 12pt] + +\start \SomeHandwriting\setstrut + +\startMPpage + StartPage ; + numeric l, n ; path p ; + l := 1.5LineHeight ; + n := 0 ; + p := origin shifted (l,0) -- origin shifted (PaperWidth-l,0) ; + for i=PaperHeight-l step -l until l : + n := n + 1 ; + fill p shifted (0,i+StrutHeight) -- + reverse p shifted (0,i-StrutDepth ) -- cycle + withcolor .85white ; + draw p shifted (0,i) + withpen pencircle scaled .25pt + withcolor .5white ; + draw p shifted (0,i+ExHeight) + withpen pencircle scaled .25pt + withcolor .5white ; + draw textext.origin("\strut How are those penalty lines called + in english? I may not steal candies ..." & decimal n) + shifted (l,i) + shifted (0,-StrutDepth) ; + endfor ; + StopPage ; +\stopMPpage +\stop +\stopbuffer + +\startbuffer[gridpage] +\startMPpage + StartPage ; + width := PaperWidth ; height := PaperHeight ; unit := cm ; + drawoptions(withpen pencircle scaled .2pt withcolor .8white) ; + draw vlingrid(0, width /unit, 1/10, width, height) ; + draw hlingrid(0, height/unit, 1/10, height, width ) ; + drawoptions(withpen pencircle scaled .5pt withcolor .4white) ; + draw vlingrid(0, width /unit, 1, width, height) ; + draw hlingrid(0, height/unit, 1, height, width ) ; + StopPage ; +\stopMPpage +\stopbuffer + +% needed to get white backgrounds + +\startmode[screen] + +\startbuffer[wipe] +picture savedpicture ; +savedpicture := currentpicture ; +currentpicture := nullpicture ; +draw savedpicture withcolor black ; +draw savedpicture ; +\stopbuffer + +\stopmode + +\startnotmode[screen] + +\startbuffer[wipe] + % nothing to whipe +\stopbuffer + +\stopnotmode + +\startbuffer[backtext] + + This document introduces you in the world of the graphic programming language + \MetaPost. Not only the language itself is covered in detail, but also the way to + interface with the typographic language \TeX. We also present the collection of + \MetaPost\ extensions that come with the \ConTeXt\ typesetting system. This + collection goes under the name \MetaFun. + + \blank + + All aspects of the \MetaPost\ language are covered. The first chapters focus on + the language itself, later chapters cover aspects like color, graphic + inclusions, adding labels, and stepwise constructing graphics. We finish with a + graphical overview of commands. + +\stopbuffer + +\startbuffer[backbanner] + + \WidthSpanningText + {PRAGMA Advanced Document Engineering, Hasselt NL, \currentdate[year]} + {\hsize} + {RegularBold} + +\stopbuffer + +\stopenvironment diff --git a/doc/context/sources/general/manuals/metafun/metafun-examples.tex b/doc/context/sources/general/manuals/metafun/metafun-examples.tex new file mode 100644 index 000000000..4e5e0eed3 --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/metafun-examples.tex @@ -0,0 +1,3269 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\startcomponent metafun-examples + +\environment metafun-environment + +\startchapter[title={A few applications}] + +\startintro + +For those who need to be inspired, we will demonstrate how \METAPOST\ can be used +to enhance your document with simple graphics. In these examples we will try to +be not too clever, simply because we lack the experience to be that clever. The +real tricks can be found in the files that come with \METAPOST. + +\stopintro + +\startsection[reference={sec:coils,sec:springs},title={Simple drawings}] + +In the words of John Hobby, the creator of \METAPOST, \quotation {\METAPOST\ is +particularly well||suited for generating figures for technical documents where +some aspects of a picture may be controlled by mathematical or geometrical +constraints that are best expressed symbolically. In other words, \METAPOST\ is +not meant to take the place of a freehand drawing tool or even an interactive +graphics editor}. + +An example of such a picture is the following one, which is dedicated to David +Arnold, who asked me once how to draw a spring. So, imagine that we want to draw +a schematic view of a system of four springs. + +\startbuffer[a] +def spring (expr a, b, w, h, n) = + ( ( (0,0) -- (0,h) -- + for i=1 upto n-1: (if odd(i) : - fi w/2,i+h) -- endfor + (0,n+h) -- (0,n+2h) ) + yscaled ((xpart (b-a) ++ ypart (b-a))/(n+2h)) + rotatedaround(origin,-90+angle(b-a)) + shifted a ) +enddef ; +\stopbuffer + +\startbuffer[b] +vardef spring (expr a, b, w, h, n) = + pair vec ; path pat ; numeric len ; numeric ang ; + vec := (b-a) ; + pat := for i=1 upto n-1: (if odd(i):-fi w/2,i)--endfor (0,n) ; + pat := (0,0)--(0,h)-- pat shifted (0,h)--(0,n+h)--(0,n+2h) ; + len := (xpart vec ++ ypart vec)/(n+2h) ; + ang := -90+angle(vec) ; + ( pat yscaled len rotatedaround(origin,ang) shifted a ) +enddef ; +\stopbuffer + +\startbuffer[c] +path p ; p := + (0,0)--spring((.5cm,0),(2.5cm,0),.5cm,0,10)--(3cm,0) ; + +draw p withpen pencircle scaled 2pt ; +draw p withpen pencircle scaled 1pt withcolor .8white; +\stopbuffer + +\startbuffer[d] +z1 = (+2cm,0) ; z2 = (0,+2cm) ; +z3 = (-2cm,0) ; z4 = (0,-2cm) ; + +pickup pencircle scaled 1.5pt ; + +drawoptions (withcolor .625red) ; + +draw spring (z1, z2, .75cm, 2, 10) ; draw z1 -- 1.5 z1 ; +draw spring (z2, z3, .75cm, 2, 9) ; draw z2 -- 1.1 z2 ; +draw spring (z3, z4, .75cm, 2, 8) ; draw z3 -- 1.5 z3 ; +draw spring (z4, z1, .75cm, 2, 7) ; draw z4 -- 1.1 z4 ; +\stopbuffer + +\startbuffer[e] +drawarrow + (0,0)--spring((.5cm,0),(2.5cm,0),.5cm,0,10)--(3cm,0) + withpen pencircle scaled 2pt withcolor .625red ; +\stopbuffer + +\startbuffer[f] +numeric u ; u := 1mm ; pickup pencircle scaled (u/2) ; +drawoptions (withcolor .625red) ; +draw (0,0)--spring((5u,0),(25u,0),5u,0,10)--(30u,0) ; +drawoptions (dashed evenly withcolor .5white) ; +draw (0,0)--spring((5u,0),(35u,0),(25/35)*5u,0,10)--(40u,0) ; +\stopbuffer + +\startlinecorrection[blank] +\processMPbuffer[a,d] +\stoplinecorrection + +A rather natural way to define such a system is: + +\typebuffer[d] + +Here, the macro \type {spring} takes 5~arguments: two points, the width of the +winding, the length of the connecting pieces, and the number of elements (half +windings). The definition of \type {spring} is less complicated than readable. + +\typebuffer[a] + +First we build a path starting in the origin, going left or right depending on +the counter being an odd number. + +\starttyping +pat := (0,0) ; +for i=1 upto n-1: + if odd(i) : + pat := pat -- (-w/2,i) ; + else : + pat := pat -- (+w/2,i) ; + fi ; +endfor ; +pat := pat -- (0,n) ; +\stoptyping + +Once you are accustomed to the way \METAPOST\ interprets (specialists may say +expand) the source code, you will start using \type {if} and \type {for} +statements in assignments. The previous code can be converted in a one liner, +using the pattern: + +\starttyping +pat := for i=1 upto n-1: (x,y)-- endfor (0,n) ; +\stoptyping + +The loop splits out a series of \type {(x,y)--} but the last point is added +outside the loop. Otherwise \type {pat} would have ended with a dangling \type +{--}. Of course we need to replace \type {(x,y)} by something meaningful, so we +get: + +\starttyping +pat := for i=1 upto n-1: (if odd(i):-fi w/2,i)--endfor (0,n) ; +\stoptyping + +We scale this path to the length needed. The expression $b-a$ calculates a +vector, starting at $a$ and ending at $b$. In \METAPOST, the expression \type +{a++b} is identical to $\sqrt{a^2+b^2}$. Thus, the expression \typ {xpart (b-a) +++ ypart (b-a)} calculates the length of the vector $b-a$. Because the unscaled +spring has length $n+2h$, scaling by the expression \typ {((xpart (b-a) ++ ypart +(b-a)) / (n+2h))} gives the spring the same length as the vector $b-a$. + +Because we have drawn our spring in the vertical position, we first rotate it 90 +degrees clockwise to a horizontal position, and then rotate it through an angle +equal to the angle in which the vector $b-a$ is pointing. After that, we shift it +to the first point. The main complications are that we also want to draw +connecting lines at the beginning and end, as well as support springs that +connect arbitrary points. Since no check is done on the parameters, you should be +careful in using this macro. + +When we want to improve the readability, we have to use intermediate variables. +Since the macro is expected to return a path, we must make sure that the content +matches this expectation. + +\typebuffer[b] + +If you use \type {vardef}, then the last statement is the return value. Here, +when \typ {p := spring (z1, z2, .75cm, 2, 10)} is being parsed, the macro is +expanded, the variables are kept invisible for the assignment, and the path at +the end is considered to be the return value. In a \type {def} the whole body of +the macro is \quote {pasted} in the text, while in a \type {vardef} only the last +line is visible. We will demonstrate this with a simple example. + +\starttyping +def one = (n,n) ; n := n+1 ; enddef ; +def two = n := n + 1 ; (n,n) enddef ; +\stoptyping + +Now, when we say: + +\starttyping +pair a, b ; numeric n ; n= 10 ; a := one ; b := two ; +\stoptyping + +we definitely get an error message. This is because, when macro \type {two} is +expanded, \METAPOST\ sees something: + +\starttyping +b := n := n + 1 ; +\stoptyping + +By changing the second definition in + +\starttyping +vardef two = n := n + 1 ; (n,n) enddef ; +\stoptyping + +the increment is expanded out of sight for \type {b :=} and the pair \type +{(n,n)} is returned. + +We can draw a slightly better looking spring by drawing twice with a different +pen. The following commands use the spring macro implemented by the \type +{vardef}. + +\typebuffer[c] + +This time we get: + +\startlinecorrection[blank] +\processMPbuffer[a,c] +\stoplinecorrection + +Since the \type {spring} macro returns a path, you can do whatever is possible +with a path, like drawing an arrow: + +\startlinecorrection[blank] +\processMPbuffer[a,e] +\stoplinecorrection + +Or even (watch how we use the neutral unit \type {u} to specify the dimensions): + +\startlinecorrection[blank] +\processMPbuffer[a,f] +\stoplinecorrection + +This was keyed in as: + +\typebuffer[e] + +and: + +\typebuffer[f] + +\stopsection + +\startsection[reference=sec:free labels,title={Free labels}] + +\index {labels} + +The \METAPOST\ label macro enables you to position text at certain points. This +macro is kind of special, because it also enables you to influence the +positioning. For that purpose it uses a special kind of syntax which we will not +discuss here in detail. + +\startbuffer[a] +pickup pencircle scaled 1mm ; +path p ; p := fullcircle scaled 3cm ; +draw p withcolor .625yellow ; +dotlabel.rt ("right" , point 0 of p) ; +dotlabel.urt ("upper right" , point 1 of p) ; +dotlabel.top ("top" , point 2 of p) ; +dotlabel.ulft ("upper left" , point 3 of p) ; +dotlabel.lft ("left" , point 4 of p) ; +dotlabel.llft ("lower left" , point 5 of p) ; +dotlabel.bot ("bottom" , point 6 of p) ; +dotlabel.lrt ("lower right" , point 7 of p) ; +\stopbuffer + +\typebuffer[a] + +The \type {label} command just typesets a text, while \type {dotlabel} also draws +a dot at the position of the label. The \type {thelabel} (not shown here) command +returns a picture. + +\startlinecorrection[blank] +\processMPbuffer[a] +\stoplinecorrection + +There is a numeric constant \type {labeloffset} that can be set to influence the +distance between the point given and the content of the label. When we set the +offset to zero, we get the following output. + +\startbuffer[x] +interim labeloffset := 0pt ; % local assignment +\stopbuffer + +\startlinecorrection[blank] +\processMPbuffer[x,a] +\stoplinecorrection + +This kind of positioning works well as long as we know where we want the label to +be placed. However, when we place labels automatically, for instance in a macro, +we have to apply a few clever tricks. There are for sure many ways to accomplish +this goal, but here we will follow the mathless method. + +\startbuffer[a] +pickup pencircle scaled 1mm ; +path p ; p := fullcircle scaled 3cm ; +draw p withcolor .625yellow ; +vardef do (expr str) = + save currentpicture ; picture currentpicture ; + currentpicture := thelabel(str,origin) ; + draw boundingbox currentpicture withpen pencircle scaled .5pt ; + currentpicture +enddef ; +\stopbuffer + +\startbuffer[b] +dotlabel.rt (do("right") , point 0 of p) ; +dotlabel.urt (do("upper right") , point 1 of p) ; +dotlabel.top (do("top") , point 2 of p) ; +dotlabel.ulft (do("upper left") , point 3 of p) ; +dotlabel.lft (do("left") , point 4 of p) ; +dotlabel.llft (do("lower left") , point 5 of p) ; +dotlabel.bot (do("bottom") , point 6 of p) ; +dotlabel.lrt (do("lower right") , point 7 of p) ; +\stopbuffer + +\startlinecorrection[blank] +\processMPbuffer[x,a,b] +\stoplinecorrection + +The previous graphic visualizes the bounding box of the labels. This bounding box +is rather tight and therefore the placement of labels will always be suboptimal. +Compare the alignment of the left- and rightmost labels. The \type {btex}||\type +{etex} method is better, since then we can add struts, like: + +\starttyping +btex \strut right etex +\stoptyping + +to force labels with uniform depths and heights. The next graphic demonstrates +that this looks better indeed. Also, as \TEX\ does the typesetting we get the +current text font instead of the label font and the content will be properly +typeset; for instance kerning will be applied when applicable. Spending some time +on such details pays back in better graphics. + +\startbuffer[b] +dotlabel.rt (do(btex \strut right etex) , point 0 of p) ; +dotlabel.urt (do(btex \strut upper right etex) , point 1 of p) ; +dotlabel.top (do(btex \strut top etex) , point 2 of p) ; +dotlabel.ulft (do(btex \strut upper left etex) , point 3 of p) ; +dotlabel.lft (do(btex \strut left etex) , point 4 of p) ; +dotlabel.llft (do(btex \strut lower left etex) , point 5 of p) ; +dotlabel.bot (do(btex \strut bottom etex) , point 6 of p) ; +dotlabel.lrt (do(btex \strut lower right etex) , point 7 of p) ; +\stopbuffer + +\startlinecorrection[blank] +\processMPbuffer[x,a,b] +\stoplinecorrection + +Now, what happens when we want to place labels in other positions? In the worst +case, given that we place the labels manually, we end up in vague arguments in +favour for one or the other placement. + +\startbuffer[y] +p := p rotatedaround(center p, 22.5) ; +\stopbuffer + +\startlinecorrection[blank] +\processMPbuffer[x,a,y,b] +\stoplinecorrection + +Although any automatic mechanism will be sub||optimal, we can give it a try to +write a macro that deals with arbitrary locations. This macro will accept three +arguments and return a picture. + +\starttyping +thefreelabel("some string or picture",a position,the origin) +\stoptyping + +Our testcase is just a simple \type {for} loop that places a series of labels. +The \type {freedotlabel} macro is derived from \type {thefreelabel}. + +\startbuffer[c] +pickup pencircle scaled 1mm ; +path p ; p := fullcircle scaled 3cm ; +draw p withcolor .625yellow ; +for i=0 step .5 until 7.5 : + freedotlabel ("text" , point i of p, center p) ; +endfor ; +\stopbuffer + +\typebuffer[c] + +As a first step we will simply place the labels without any correction. We also +visualize the bounding box. + +\startbuffer[b] +vardef freedotlabel (expr str, loc, ori) = + drawdot loc ; draw thefreelabel(str,loc,ori) ; +enddef ; + +vardef freelabel (expr str, loc, ori) = + draw thefreelabel(str,loc,ori) ; +enddef ; +\stopbuffer + +\startbuffer[a] +vardef thefreelabel (expr str, loc, ori) = + save s ; picture s ; s := thelabel(str,loc) ; + draw boundingbox s withpen pencircle scaled .5pt ; + s +enddef ; +\stopbuffer + +\typebuffer[a] + +To make our lives more easy, we also define a macro that draws the dot as well as +a macro that draws the label. + +\typebuffer[b] + +Now we get: + +\startlinecorrection[blank] +\processMPbuffer[x,a,b,c] +\stoplinecorrection + +The original label macros permits us to align the label at positions, 4~corners +and 4~points halfway the sides. It happens that circles are also composed of +8~points. Because in most cases the label is to be positioned in the direction of +the center of a curve and the point at hand, it makes sense to take circles as +the starting points for positioning the labels. + +To help us in positioning, we define a special square path, \type {freesquare}. +This path is constructed out of 8~points that match the positions that are used +to align labels. + +\startbuffer[d] +path freesquare ; + +freesquare := ((-1,0)--(-1,-1)--(0,-1)--(+1,-1)-- + (+1,0)--(+1,+1)--(0,+1)--(-1,+1)--cycle) scaled .5 ; +\stopbuffer + +\typebuffer[d] + +We now show this free path together with a circle, using the following +definitions: + +\startbuffer[e] +drawpath fullcircle scaled 3cm ; +drawpoints fullcircle scaled 3cm ; +drawpointlabels fullcircle scaled 3cm ; +currentpicture := currentpicture shifted (5cm,0) ; +drawpath freesquare scaled 3cm ; +drawpoints freesquare scaled 3cm ; +drawpointlabels freesquare scaled 3cm ; +\stopbuffer + +\typebuffer[e] + +We use two drawing macros that are part of the suite of visual debugging macros. + +\startlinecorrection[blank] +\processMPbuffer[x,d,e] +\stoplinecorrection + +As you can see, point~1 is the corner point that suits best for alignment when a +label is put at point~1 of the circle. We will now rewrite \type {thefreelabel} +in such a way that the appropriate point of the associated \type {freesquare} is +found. + +\startbuffer[a] +vardef thefreelabel (expr str, loc, ori) = + save s, p, q, l ; picture s ; path p, q ; pair l ; + s := thelabel(str,loc) ; + p := fullcircle scaled (2*length(loc-ori)) shifted ori ; + q := freesquare xyscaled (urcorner s - llcorner s) ; + l := point (xpart (p intersectiontimes (ori--loc))) of q ; + draw q shifted loc withpen pencircle scaled .5pt ; + draw l shifted loc withcolor .625yellow ; + draw loc withcolor .625red ; + s +enddef ; +\stopbuffer + +\typebuffer[a] + +The macro xyscaled is part of \METAFUN\ and scales in two directions at once. The +\METAPOST\ primitive \type {intersectiontimes} returns a pair of time values of +the point where two paths intersect. The first part of the pair concerns the +first path. + +\startlinecorrection[blank] +\processMPbuffer[x,a,b,c] +\stoplinecorrection + +We are now a small step from the exact placement. If we change the last line of +the macro into: + +\starttyping +(s shifted -l) +\stoptyping + +we get the displacement we want. Although the final look and feel is also +determined by the text itself, the average result is quite acceptable. + +\startbuffer[a] +vardef thefreelabel (expr str, loc, ori) = + save s, p, q, l ; picture s ; path p, q ; pair l ; + s := thelabel(str,loc) ; + p := fullcircle scaled (2*length(loc-ori)) shifted ori ; + q := freesquare xyscaled (urcorner s - llcorner s) ; + l := point (xpart (p intersectiontimes (ori--loc))) of q ; + draw q shifted loc withpen pencircle scaled .5pt ; + draw l shifted loc withcolor .625yellow ; + draw loc withcolor .625red ; + (s shifted -l) +enddef ; +\stopbuffer + +\startlinecorrection[blank] +\processMPbuffer[x,a,b,c] +\stoplinecorrection + +Because we also want to pass pictures, and add a bit of offset too, the final +implementation is slightly more complicated. The picture is handled with an +additional condition, and the offset with the \METAFUN\ macro \type {enlarged}. + +\startbuffer[a] +newinternal freelabeloffset ; freelabeloffset := 3pt ; + +vardef thefreelabel (expr str, loc, ori) = + save s, p, q, l ; picture s ; path p, q ; pair l ; + interim labeloffset := freelabeloffset ; + s := if string str : thelabel(str,loc) + else : str shifted -center str shifted loc fi ; + setbounds s to boundingbox s enlarged freelabeloffset ; + p := fullcircle scaled (2*length(loc-ori)) shifted ori ; + q := freesquare xyscaled (urcorner s - llcorner s) ; + l := point (xpart (p intersectiontimes (ori--loc))) of q ; + setbounds s to boundingbox s enlarged -freelabeloffset ; + (s shifted -l) +enddef ; +\stopbuffer + +\typebuffer[a] + +Watch how we temporarily enlarge the bounding box of the typeset label text. We +will now test this macro on a slightly rotated circle, using labels typeset by +\TEX. The \type {reverse} is there purely for cosmetic reasons, to suit the label +texts. + +\startbuffer[b] +pickup pencircle scaled 1mm ; +path p ; p := reverse fullcircle rotated -25 scaled 3cm ; +draw p withcolor .625yellow ; pair cp ; cp := center p ; +freedotlabel (btex \strut We can etex, point 0 of p, cp) ; +freedotlabel (btex \strut go on etex, point 1 of p, cp) ; +freedotlabel (btex \strut and on etex, point 2 of p, cp) ; +freedotlabel (btex \strut in etex, point 3 of p, cp) ; +freedotlabel (btex \strut defining etex, point 4 of p, cp) ; +freedotlabel (btex \strut funny etex, point 5 of p, cp) ; +freedotlabel (btex \strut macros. etex, point 6 of p, cp) ; +freedotlabel (btex \strut Can't we? etex, point 7 of p, cp) ; +\stopbuffer + +\startlinecorrection[blank] +\processMPbuffer[a,b] +\stoplinecorrection + +\typebuffer[b] + +Unfortunately we can run into problems due to rounding errors. Therefore we use a +less readable but more safe expression for calculating the intersection points. +Instead of using point \type {loc} as endpoint we use \type {loc} shifted over a +very small distance into the direction \type {loc} from \type{ori}. In the +assignment to~\type {l} we replace \type {loc} by: + +\starttyping + ( (1+eps) * arclength(ori--loc) * unitvector(loc-ori) ) +\stoptyping + +\stopsection + +\startsection[title={Marking angles}] + +\index{angles} + +A convenient \METAPOST\ macro is \type {unitvector}. When we draw a line segment +from the origin to the point returned by this macro, the segment has a length of +1~base point. This macro has a wide range of applications, but some basic +knowledge of vector algebra is handy. The following lines of \METAPOST\ code +demonstrate the basics behind unitvectors. + +\startbuffer +pair uv ; pickup pencircle scaled 1mm ; autoarrows := true ; +draw fullcircle scaled 2cm withcolor .625red ; +for i=(10,35), (-40,-20), (85,-15) : + draw origin--i dashed evenly withcolor .625white ; + drawarrow origin--unitvector(i) scaled 1cm withcolor .625yellow ; +endfor ; +draw origin withcolor .625red ; +\stopbuffer + +\typebuffer + +The circle has a radius of 1cm, and the three line segments are drawn from the +origin in the direction of the points that are passed as arguments. Because the +vector has length of~1, we scale it to the radius to let it touch the circle. By +setting \type {autoarrows} we make sure that the arrowheads are scaled +proportionally to the linewidth of 1~mm. + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +An application of this macro is drawing the angle between two lines. In the +\METAPOST\ manual you can find two macros for drawing angles: \type {mark_angle} +and \type {mark_rt_angle}. You may want to take a look at their definitions +before we start developing our own alternatives. + +\startbuffer[x] +pickup pencircle scaled 1mm ; autoarrows := true ; +drawoptions(withcolor .625white) ; +\stopbuffer + +\startbuffer[a] +def anglebetween (expr a, b) = + (unitvector(a){a rotated 90} .. unitvector(b)) +enddef ; +\stopbuffer + +\startbuffer[b] +pair a, b ; a := (2cm,-1cm) ; b := (3cm,1cm) ; +drawarrow origin--a ; drawarrow origin--b ; +drawarrow anglebetween(a,b) scaled 1cm withcolor .625red ; +\stopbuffer + +\startlinecorrection[blank] +\processMPbuffer[x,a,b] +\stoplinecorrection + +The previous graphic demonstrates what we want to accomplish: a circular curve +indicating the angle between two straight lines. The lines and curve are drawn +with the code: + +\typebuffer[b] + +where \type {anglebetween} is defined as: + +\typebuffer[a] + +Both unitvectors return just a point on the line positioned 1~unit (later scaled +to 1cm) from the origin. We connect these points by a curve that starts in the +direction at the first point. If we omit the \type {a rotated 90} direction +specifier, we get: + +\startbuffer[a] +def anglebetween (expr a, b) = + (unitvector(a) .. unitvector(b)) +enddef ; +\stopbuffer + +\startlinecorrection[blank] +\processMPbuffer[x,a,b] +\stoplinecorrection + +These definitions of \type {anglebetween} are far from perfect. If we don't start +in the origin, we get the curve in the wrong place and when we swap both points, +we get the wrong curve. + +\startbuffer[a] +def anglebetween (expr endofa, endofb, common, length) = + (unitvector (endofa-common){(endofa-common) rotated 90} .. + unitvector (endofb-common)) scaled length shifted common +enddef ; +\stopbuffer + +\startbuffer[b] +pair a, b, c ; a := (2cm,-1cm) ; b := (3cm,1cm) ; c := (-1cm,.5cm) ; +drawarrow c--a ; drawarrow c--b ; +drawarrow anglebetween(a,b,c,1cm) withcolor .625red ; +\stopbuffer + +The solution for the displacement is given in the \METAPOST\ manual and looks +like this (we package the macro a bit different): + +\typebuffer[a] + +As you can see, we compensate for the origin of both vectors. This macro is +called with a few more parameters. We need to pass the length, since we want to +add the shift to the macro and the shift takes place after the scaling. + +\typebuffer[b] + +That the results are indeed correct, is demonstrated by the output of following +example: + +\startlinecorrection[blank] +\processMPbuffer[x,a,b] +\stoplinecorrection + +However, when we swap the points, we get: + +\startbuffer[a] +def anglebetween (expr endofb, endofa, common, length) = + (unitvector (endofa-common){(endofa-common) rotated 90} .. + unitvector (endofb-common)) scaled length shifted common +enddef ; +\stopbuffer + +\startlinecorrection[blank] +\processMPbuffer[x,a,b] +\stoplinecorrection + +This means that instead of rotating over $90$ degrees, we have to rotate over +$-90$ or $270$ degrees. That way the arrow will also point in the other +direction. There are undoubtedly more ways to determine the direction, but the +following method also demonstrates the use of \type {turningnumber}, which +reports the direction of a path. For this purpose we compose a dummy cyclic path. + +\startbuffer[a] +vardef anglebetween (expr endofa, endofb, common, length) = + save tn ; tn := turningnumber(common--endofa--endofb--cycle) ; +show tn ; + (unitvector(endofa-common){(endofa-common) rotated (tn*90)} .. + unitvector(endofb-common)) scaled length shifted common +enddef ; +\stopbuffer + +\typebuffer[a] + +Because we use an intermediate variable, just to keep things readable, we have to +use \type {vardef} to hide the assignment for the outside world. We demonstrate +this macro using the following code: + +\startbuffer[b] +pair a, b, c ; a := (2cm,-1cm) ; b := (3cm,1cm) ; c := (-1cm,.5cm) ; +drawarrow c--a ; drawarrow c--b ; +drawarrow anglebetween(a,b,c,0.75cm) withcolor .625red ; +drawarrow anglebetween(b,a,c,1.50cm) withcolor .625red ; +\stopbuffer + +\typebuffer[b] + +Watch how both arrows point in the direction of the line that is determined by +the second point. + +\startlinecorrection[blank] +\processMPbuffer[x,a,b] +\stoplinecorrection + +We now have the framework of an angle drawing macro ready and can start working +placing the label. + +\startbuffer[a] +vardef anglebetween (expr endofa, endofb, common, length, str) = + save curve, where ; path curve ; numeric where ; + where := turningnumber (common--endofa--endofb--cycle) ; + curve := (unitvector(endofa-common){(endofa-common) rotated (where*90)} + .. unitvector(endofb-common)) scaled length shifted common ; + draw thefreelabel(str,point .5 of curve,common) withcolor black ; + curve +enddef ; +\stopbuffer + +\typebuffer[a] + +The macro \type {thefreelabel} is part of \METAFUN\ and is explained in detail in +\in {section} [sec:free labels]. This macro tries to place the label as good as +possible without user interference. + +\startbuffer[b] +pair a ; a := (2cm,-1cm) ; drawarrow origin--a ; +pair b ; b := (3cm, 1cm) ; drawarrow origin--b ; +drawarrow + anglebetween(a,b,origin,1cm,btex $\alpha$ etex) + withcolor .625red ; +\stopbuffer + +\typebuffer[b] + +Instead of a picture we may also pass a string, but using \TEX\ by means of \type +{btex}||\type {etex} often leads to better results. + +\startlinecorrection[blank] +\processMPbuffer[x,a,b] +\stoplinecorrection + +Because in most cases we want the length to be consistent between figures and +because passing two paths is more convenient than passing three points, the final +definition looks slightly different. + +\startbuffer[a] +numeric anglelength ; anglelength := 20pt ; + +vardef anglebetween (expr a, b, str) = % path path string + save endofa, endofb, common, curve, where ; + pair endofa, endofb, common ; path curve ; numeric where ; + endofa := point length(a) of a ; + endofb := point length(b) of b ; + if round point 0 of a = round point 0 of b : + common := point 0 of a ; + else : + common := a intersectionpoint b ; + fi ; + where := turningnumber (common--endofa--endofb--cycle) ; + curve := (unitvector (endofa-common){(endofa-common) rotated (where*90)} .. + unitvector (endofb-common)) scaled anglelength shifted common ; + draw thefreelabel(str,point .5 of curve,common) withcolor black ; + curve +enddef ; +\stopbuffer + +\typebuffer[a] + +This macro has a few more \type {if}'s than its predecessor. First we test if the +label is a string, and if so, we calculate the picture ourselves, otherwise we +leave this to the user. + +\startbuffer[b] +path a, b, c, d, e, f ; +a := origin--( 2cm, 1cm) ; b := origin--( 1cm, 2cm) ; +c := origin--(-2cm, 2cm) ; d := origin--(-2cm,-1cm) ; +e := origin--(-1cm,-2cm) ; f := origin--( 1cm,-2cm) ; +for i=a, b, c, d, e, f : drawarrow i ; endfor ; +anglelength := 1.0cm ; drawoptions(withcolor .625red) ; +drawarrow anglebetween(a,b,btex $\alpha $ etex) ; +drawarrow anglebetween(c,d,btex $\gamma $ etex) ; +drawarrow anglebetween(e,f,btex $\epsilon$ etex) ; +anglelength := 1.5cm ; drawoptions(withcolor .625yellow) ; +drawdblarrow anglebetween(b,c,btex $\beta $ etex) ; +drawarrow reverse anglebetween(d,e,btex $\delta $ etex) ; +drawarrow anglebetween(a,f,btex $\zeta $ etex) ; +\stopbuffer + +\typebuffer[b] + +Because \type {anglebetween} returns a path, you can apply transformations to it, +like reversing. Close reading of the previous code learns that the macro handles +both directions. + +\startlinecorrection[blank] +\processMPbuffer[x,a,b] +\stoplinecorrection + +Multiples of 90 degrees are often identified by a rectangular symbol. We will now +extend the previously defined macro in such a way that more types can be drawn. + +\startbuffer[a] +numeric anglelength ; anglelength := 20pt ; +numeric anglemethod ; anglemethod := 1 ; + +vardef anglebetween (expr a, b, str) = % path path string + save pointa, pointb, common, middle, offset ; + pair pointa, pointb, common, middle, offset ; + save curve ; path curve ; + save where ; numeric where ; + if round point 0 of a = round point 0 of b : + common := point 0 of a ; + else : + common := a intersectionpoint b ; + fi ; + pointa := point anglelength on a ; + pointb := point anglelength on b ; + where := turningnumber (common--pointa--pointb--cycle) ; + middle := ((common--pointa) rotatedaround (pointa,-where*90)) + intersectionpoint + ((common--pointb) rotatedaround (pointb, where*90)) ; + if anglemethod = 1 : + curve := pointa{unitvector(middle-pointa)}.. pointb; + middle := point .5 along curve ; + elseif anglemethod = 2 : + middle := common rotatedaround(.5[pointa,pointb],180) ; + curve := pointa--middle--pointb ; + elseif anglemethod = 3 : + curve := pointa--middle--pointb ; + elseif anglemethod = 4 : + curve := pointa..controls middle..pointb ; + middle := point .5 along curve ; + fi ; + draw thefreelabel(str, middle, common) withcolor black ; + curve +enddef ; +\stopbuffer + +\typebuffer[a] + +\startbuffer[p] +anglemethod := 1 ; +\stopbuffer + +\startbuffer[q] +anglemethod := 2 ; +\stopbuffer + +\startbuffer[r] +anglemethod := 3 ; +\stopbuffer + +\startbuffer +\startcombination[3*1] + {\processMPbuffer[x,a,p,b]} {method 1} + {\processMPbuffer[x,a,q,b]} {method 2} + {\processMPbuffer[x,a,r,b]} {method 3} +\stopcombination +\stopbuffer + +\placefigure + [here][fig:three methods] + {Three ways of marking angles.} + {\getbuffer} + +\in {Figure} [fig:three methods] shows the first three alternative methods +implemented here. Instead of using \typ {unitvectors}, we now calculate the +points using the \typ {arctime} and \typ {arclength} primitives. Instead of +complicated expressions, we use the \METAFUN\ operators \type {along} and \type +{on}. The following expressions are equivalent. + +\starttyping +pointa := point anglelength on a ; +middle := point .5 along curve ; + +pointa := point (arctime anglelength of a) of a ; +middle := arctime (.5(arclength curve)) of curve) of curve ; +\stoptyping + +The third method can be implemented in different, more math intensive ways, but +the current implementation suits rather well and is understood by the author. + +\stopsection + +\startsection[reference=sec:color circles,title={Color circles}] + +\index{color} + +In \in {chapter} [sec:embedding] we showed a few color circles. Drawing such a +graphic can be done in several ways, and here we will show a few methods. First +we will demonstrate how you can apply \type {cutafter} and \type {cutbefore}, +next we will show how the \METAPOST\ macro \type {buildpath} can be used, and +finally we will present a clean solution using \type {subpath}. We will assume +that the circle is called with the macro: + +\starttyping +colorcircle (4cm, red, green, blue) ; +\stoptyping + +\startbuffer[circle] +vardef colorcircle (expr size, red, green, blue) = + save r, g, b, rr, gg, bb, cc, mm, yy ; + save b_r, b_g, g_r, g_b ; + save radius ; + + path r, g, b, rr, bb, gg, cc, mm, yy ; + pair b_r, b_g, g_r, g_b ; + + numeric radius ; radius := 3cm ; + + pickup pencircle scaled (radius/20) ; + + r := g := b := fullcircle scaled radius shifted (0,radius/4); + + r := r rotatedaround(origin, 15) ; % drawarrow r withcolor red ; + g := g rotatedaround(origin,135) ; % drawarrow g withcolor green ; + b := b rotatedaround(origin,255) ; % drawarrow b withcolor blue ; + + b_r := b intersectionpoint r ; % draw b_r ; + b_g := b intersectionpoint g ; % draw b_g ; + g_r := reverse g intersectionpoint r ; % draw g_r ; + g_b := reverse g intersectionpoint b ; % draw g_b ; + + bb := b cutafter b_r ; bb := bb cutbefore b_g ; % drawarrow bb ; + gg := g cutbefore b_g ; gg := gg cutafter g_r ; % drawarrow gg ; + rr := r cutbefore g_r & r cutafter b_r ; % drawarrow rr ; + + cc := b cutbefore b_r ; cc := cc cutafter g_b ; % drawarrow br ; + yy := g cutbefore g_r ; yy := yy cutafter g_b ; % drawarrow rg ; + mm := r cutbefore g_r & r cutafter b_r ; % drawarrow gb ; + + bb := gg -- rr -- reverse bb -- cycle ; + gg := bb rotatedaround(origin,120) ; + rr := bb rotatedaround(origin,240) ; + + cc := mm -- cc -- reverse yy -- cycle ; + yy := cc rotatedaround(origin,120) ; + mm := cc rotatedaround(origin,240) ; + + fill fullcircle scaled radius withcolor white ; + + fill rr withcolor red ; fill cc withcolor white-red ; + fill gg withcolor green ; fill mm withcolor white-green ; + fill bb withcolor blue ; fill yy withcolor white-blue ; + + for i = rr,gg,bb,cc,mm,yy : draw i withcolor .5white ; endfor ; + + currentpicture := currentpicture xsized size ; +enddef ; +\stopbuffer + +We need to calculate seven paths. The first implementation does all the handywork +itself and thereby is rather long, complicated and unreadable. It does not really +use the strength of \METAPOST\ yet. + +\typebuffer[circle] + +In determining the right intersection points, you need to know where the path +starts and in what direction it moves. In case of doubt, drawing the path as an +arrow helps. If you want to see the small paths used, you need to comment the +lines with the \type {fill}'s and uncomment the lines with \type {draw}'s. Due to +the symmetry and the fact that we keep the figure centered around the origin, we +only need to calculate two paths since we can rotate them. + +There are for sure more (efficient) ways to draw such a figure, but this one +demonstrates a few new tricks, like grouping. We use grouping here because we +want to use \type {mm} to indicate the magenta path, and \type {mm} normally +means millimeter. Within a group, you can save variables. These get their old +values when the group is left. + +With \type {for} we process multiple paths after each other. In this case it +hardly saves tokens, but it looks more clever. + +One of the more efficient methods is using the \type {buildcycle} macro. This +macro takes two or more paths and calculates the combined path. Although this is +a rather clever macro, you should be prepared to help it a bit when paths have +multiple intersection points. Again, we could follow a more secure mathematical +method, but the next one took only a few minutes of trial and error. To save some +memory, we redefine the \type {colors} graphic. + +\startbuffer[demo] +colorcircle(4cm, red, green, blue) ; +\stopbuffer + +When we call this macro as: + +\typebuffer[demo] + +we get: + +\startlinecorrection[blank] +\processMPbuffer[circle,demo] +\stoplinecorrection + +Of course this macro is only used for demonstration purposes and has no real use. + +\startbuffer[circle] +vardef colorcircle (expr size, red, green, blue) = + save r, g, b, rr, gg, bb, cc, mm, yy ; save radius ; + path r, g, b, rr, bb, gg, cc, mm, yy ; numeric radius ; + + radius := 5cm ; pickup pencircle scaled (radius/25) ; + + r := g := b := fullcircle scaled radius shifted (0,radius/4) ; + + r := r rotatedaround (origin, 15) ; + g := g rotatedaround (origin,135) ; + b := b rotatedaround (origin,255) ; + + r := r rotatedaround(center r,-90) ; + g := g rotatedaround(center g, 90) ; + + gg := buildcycle(buildcycle(reverse r,b),g) ; + cc := buildcycle(buildcycle(b,reverse g),r) ; + + rr := gg rotatedaround(origin,120) ; + bb := gg rotatedaround(origin,240) ; + + yy := cc rotatedaround(origin,120) ; + mm := cc rotatedaround(origin,240) ; + + fill fullcircle scaled radius withcolor white ; + + fill rr withcolor red ; fill cc withcolor white-red ; + fill gg withcolor green ; fill mm withcolor white-green ; + fill bb withcolor blue ; fill yy withcolor white-blue ; + + for i = rr,gg,bb,cc,mm,yy : draw i withcolor .5white ; endfor ; + + currentpicture := currentpicture xsized size ; +enddef ; +\stopbuffer + +\typebuffer [circle] + +Since we don't want to duplicate a graphic, this time we show the dark +alternatives. + +\startbuffer[demo] +colorcircle(4cm, .5red, .5green, .5blue) ; +\stopbuffer + +\typebuffer[demo] + +This kind of unsafe path calculations are very sensitive to breaking. Changing +the \type {radius/4} into something else demonstrates this but we will not +challenge this macro that much. Therefore, the 50\% color circle shows up as: + +\startlinecorrection[blank] +\processMPbuffer[circle,demo] +\stoplinecorrection + +This command is part of \METAFUN\ and can be used to determine nice color +combinations by also looking at their complementary colors. + +\startbuffer[demo] +colorcircle (4cm, .7red, .5green, .3blue) ; +\stopbuffer + +\typebuffer[demo] + +\startlinecorrection[blank] +\processMPbuffer[circle,demo] +\stoplinecorrection + +The next circle that we draw shows the three main colors used in this document. +This circle is not that beautiful. + +\startbuffer[demo] +colorcircle(4cm,.625red,.625yellow,.625white) ; +\stopbuffer + +\typebuffer[demo] + +\startlinecorrection[blank] +\processMPbuffer[circle,demo] +\stoplinecorrection + +This definition can be cleaned up a bit by using \type {transform}, but the fuzzy +\type {buildcycle}'s remain. + +\startbuffer[circle] +vardef colorcircle (expr size, red, green, blue) = + save r, g, b, rr, gg, bb, cc, mm, yy ; save radius ; + path r, g, b, rr, bb, gg, cc, mm, yy ; numeric radius ; + + radius := 5cm ; pickup pencircle scaled (radius/25) ; + + transform t ; t := identity rotatedaround(origin,120) ; + + r := fullcircle scaled radius + shifted (0,radius/4) rotatedaround(origin,15) ; + + g := r transformed t ; b := g transformed t ; + + r := r rotatedaround(center r,-90) ; + g := g rotatedaround(center g, 90) ; + + gg := buildcycle(buildcycle(reverse r,b),g) ; + cc := buildcycle(buildcycle(b,reverse g),r) ; + + rr := gg transformed t ; bb := rr transformed t ; + yy := cc transformed t ; mm := yy transformed t ; + + fill fullcircle scaled radius withcolor white ; + + fill rr withcolor red ; fill cc withcolor white-red ; + fill gg withcolor green ; fill mm withcolor white-green ; + fill bb withcolor blue ; fill yy withcolor white-blue ; + + for i = rr,gg,bb,cc,mm,yy : draw i withcolor .5white ; endfor ; + + currentpicture := currentpicture xsized size ; +enddef ; +\stopbuffer + +\typebuffer [circle] + +\startbuffer[demo] +colorcircle(4cm,(.4,.6,.8),(.8,.4,.6),(.6,.8,.4)); +\stopbuffer + +\startlinecorrection[blank] +\processMPbuffer[circle,demo] +\stoplinecorrection + +This rather nice circle is defined as: + +\typebuffer[demo] + +The final implementation, which is part of \METAFUN, is slightly more efficient. + +\startbuffer[circle] +vardef colorcircle (expr size, red, green, blue) = + save r, g, b, c, m, y, w ; save radius ; + path r, g, b, c, m, y, w ; numeric radius ; + + radius := 5cm ; pickup pencircle scaled (radius/25) ; + + transform t ; t := identity rotatedaround(origin,120) ; + + r := fullcircle rotated 90 scaled radius + shifted (0,radius/4) rotatedaround(origin,135) ; + + b := r transformed t ; g := b transformed t ; + + c := buildcycle(subpath(1,7) of g, subpath(1,7) of b) ; + y := c transformed t ; m := y transformed t ; + + w := buildcycle(subpath(3,5) of r, + subpath(3,5) of g, subpath(3,5) of b) ; + + pushcurrentpicture ; + + fill r withcolor red ; + fill g withcolor green ; + fill b withcolor blue ; + fill c withcolor white-red ; + fill m withcolor white-green ; + fill y withcolor white-blue ; + fill w withcolor white ; + + for i = r,g,b,c,m,y : draw i withcolor .5white ; endfor ; + + currentpicture := currentpicture xsized size ; + + popcurrentpicture ; +enddef ; +\stopbuffer + +\typebuffer [circle] + +Here, we first fill the primary circles, next we fill the secondary ones. These +also cover the center, which is why finally we fill the center with white. + +\startbuffer[demo] +colorcircle(4cm,(.2,.5,.8),(.8,.2,.5),(.5,.8,.2)); +\stopbuffer + +\startlinecorrection[blank] +\processMPbuffer[circle,demo] +\stoplinecorrection + +The circle uses the following colors: + +\typebuffer[demo] + +The next graphic demonstrates how the subpaths look that build the shapes. + +\startbuffer[circle] +vardef colorcircle (expr size, red, green, blue) = + save r, g, b, c, m, y, w ; save radius ; + path r, g, b, c, m, y, w ; numeric radius ; + + radius := 5cm ; pickup pencircle scaled (radius/25) ; + + transform t ; t := identity rotatedaround(origin,120) ; + + r := fullcircle rotated 90 scaled radius + shifted (0,radius/4) rotatedaround(origin,135) ; + + b := r transformed t ; g := b transformed t ; + + c := buildcycle(subpath(1,7) of g,subpath(1,7) of b) ; + y := c transformed t ; m := y transformed t ; + + w := buildcycle(subpath(3,5) of r, + subpath(3,5) of g, subpath(3,5) of b) ; + + pushcurrentpicture ; + + def do_it = + fill r withcolor red ; + fill g withcolor green ; + fill b withcolor blue ; + fill c withcolor white-red ; + fill m withcolor white-green ; + fill y withcolor white-blue ; + fill w withcolor white ; + for i = r,g,b,c,m,y : draw i withcolor .5white ; endfor ; + enddef ; + + autoarrows := true ; + + do_it ; + for i=r,g,b : drawarrow i withcolor black ; endfor ; + currentpicture := currentpicture shifted (-2radius,0) ; + + do_it ; + for i=r,g,b : drawarrow subpath(1,7) of i withcolor black ; endfor ; + currentpicture := currentpicture shifted (-2radius,0) ; + + do_it ; + for i=r,g,b : drawarrow subpath(3,5) of i withcolor black ; endfor ; + currentpicture := currentpicture shifted (+4radius,2radius) ; + + drawarrow r withpen pencircle scaled (radius/10) withcolor red ; + drawarrow g withpen pencircle scaled (radius/20) withcolor green ; + drawarrow b withpen pencircle scaled (radius/40) withcolor blue ; + currentpicture := currentpicture shifted (-2radius,0) ; + + drawarrow c withpen pencircle scaled (radius/10) withcolor white-red ; + drawarrow m withpen pencircle scaled (radius/20) withcolor white-green ; + drawarrow y withpen pencircle scaled (radius/40) withcolor white-blue ; + currentpicture := currentpicture shifted (-2radius,0) ; + + drawarrow w withcolor black ; + + currentpicture := currentpicture xsized 3size ; + + popcurrentpicture ; +enddef ; +\stopbuffer + +\startlinecorrection[blank] +\processMPbuffer[circle,demo] +\stoplinecorrection + +We did not mention what the push and pop commands are responsible for. Scaling +the current picture is well defined as long as we deal with one graphic. However, +if the current picture already has some content, this content is also scaled. The +push and pop commands let us add content to the current picture as well as +manipulating the picture as a whole without any side effects. The final result is +put on top of the already drawn content. Instead of the sequence: + +\starttyping +pushcurrentpicture ; + ... + currentpicture := currentpicture ... transformations ... ; +popcurrentpicture ; +\stoptyping + +you can say: + +\starttyping +pushcurrentpicture ; + ... +popcurrentpicture ... transformations ... ; +\stoptyping + +Both are equivalent to: + +\starttyping +draw image ( ... ) ... transformations ... ; +\stoptyping + +For larger sequences of commands, the push||pop alternative gives a bit more more +readable code. + +\stopsection + +\startsection[title={Fool yourself}] + +When doing a literature search on the human perception of black||white edges, I +ran into several articles with graphics that I remember having seen before in +books on psychology, physiology and|/|or ergonomics. One of the articles was by +Edward H.~Adelson of MIT and we will use a few of his example graphics in our +exploration to what extend \METAPOST\ can be of help in those disciplines. Since +such graphics normally occur in typeset documents, we will define them in the +document source. + +\startbuffer[a] +\startbuffer +interim linecap := butt ; numeric u ; u := 1cm ; +pickup pencircle scaled .5u ; +for i=1u step u until 5u : + draw (0,i) -- (5u,i) ; +endfor ; +for i=2u step u until 4u : + draw (u,i) -- (2u,i) withcolor .5white ; + draw ((3u,i) -- (4u,i)) shifted (0,-.5u) withcolor .5white ; +endfor ; +\stopbuffer +\stopbuffer + +\startbuffer[b] +\placefigure + [here][fig:tricked 1] + {White's illusion.} + {\processMPbuffer} +\stopbuffer + +\getbuffer[a,b] + +Unless you belong to the happy few whose visual capabilities are not distorted by +neural optimizations, in \in {figure} [fig:tricked 1] the gray rectangles at the +left look lighter than those on the right. Alas, you can fool yourself, but +\METAPOST\ does not cheat. This graphic, referred to as White's illusion, is +defined as follows. + +\typebuffer[a] + +Watch how we include the code directly. We have packaged this graphic in a buffer +which we include as a floating figure. + +\typebuffer[b] + +When passed to \METAPOST, this code is encapsulated in its \type {beginfig} and +\type {endfig} macros and thereby grouped. But any change to a variable that is +not explicitly saved, migrates to the outer level. In order to prevent all +successive graphics to have butt'd linecaps, we have to change this line +characteristic locally. Because \type {linecap} is defined as an internal +variable, we have to use \type {interim} to overload its value. Because \type {u} +is a rather commonly used scratch variable, we don't save its value. + +Watch how we use \type {u} as the loop step. In spite of what your eyes tell you, +this graphic only has two explicit color directives, both being 50\% black. In +the next example we will use some real colors. + +\startbuffer[a] +\startuseMPgraphic{first} + numeric size, delta ; + size := 2.5cm ; delta := size/3 ; + color mainshade, topshade, bottomshade, centershade ; + mainshade := \MPcolor{funcolor} ; + topshade := .9mainshade ; bottomshade := .5mainshade ; + centershade := .5[topshade,bottomshade] ; +\stopuseMPgraphic +\stopbuffer + +\startbuffer[b] +\startuseMPgraphic{second} + \includeMPgraphic{first} + fill fullsquare scaled size withcolor topshade ; + fill fullsquare scaled delta withcolor centershade ; +\stopuseMPgraphic +\stopbuffer + +\startbuffer[c] +\startuseMPgraphic{third} + \includeMPgraphic{first} + fill fullsquare scaled size withcolor bottomshade ; + fill fullsquare scaled delta withcolor centershade ; +\stopuseMPgraphic +\stopbuffer + +\getbuffer[a,b,c] + +\startbuffer[d] +\startcombination[5*2] + {\definecolor[funcolor][red] \useMPgraphic{second}} {} + {\definecolor[funcolor][green] \useMPgraphic{second}} {} + {\definecolor[funcolor][blue] \useMPgraphic{second}} {} + {\definecolor[funcolor][yellow]\useMPgraphic{second}} {} + {\definecolor[funcolor][white] \useMPgraphic{second}} {} + {\definecolor[funcolor][red] \useMPgraphic{third}} {} + {\definecolor[funcolor][green] \useMPgraphic{third}} {} + {\definecolor[funcolor][blue] \useMPgraphic{third}} {} + {\definecolor[funcolor][yellow]\useMPgraphic{third}} {} + {\definecolor[funcolor][white] \useMPgraphic{third}} {} +\stopcombination +\stopbuffer + +\placefigure + [here][fig:tricked 2] + {The simultaneous contrast effect.} + {\getbuffer[d]} + +In \in {figure} [fig:tricked 2] the small squares in the center of each colored +pair of big squares have the same shade, but the way we perceive them are +influenced by their surroundings. Both sets of squares are defined using usable +graphics. The top squares are defined as: + +\typebuffer[b] + +and the bottom squares are coded as: + +\typebuffer[c] + +Because both graphics share code, we have defined that code as a separate +graphic, that we include. The only point of interest in this definition is the +fact that we let \METAPOST\ interpolate between the two colors using \type {.5[ +]}. + +\typebuffer[a] + +The color \type {funcolor} is provided by \CONTEXT, and since we want to use this +graphic with different colors, this kind of mapping is quite convenient. The +bunch of graphics is packaged in a combination with empty captions. Note how we +set the color before we include the graphic. + +\typebuffer[d] + +We use a similar arrangement for the following graphic, where we have replaced +the definitions of \type {first}, \type {second} and \type {third} by new +definitions. + +\startbuffer[a] +\startuseMPgraphic{first} + numeric height, width, radius, gap ; gap := 1mm ; + height = 2.5cm ; width := height/2 ; radius := height/2.5 ; + color mainshade, leftshade, rightshade, centershade ; + mainshade := \MPcolor{funcolor} ; + leftshade := .9mainshade ; rightshade := .5mainshade ; + centershade := .5[leftshade,rightshade] ; + fill unitsquare xyscaled ( width,height) withcolor leftshade ; + fill unitsquare xyscaled (-width,height) withcolor rightshade ; + draw (fullcircle scaled radius) shifted (0,height/2) + withpen pencircle scaled (radius/2) withcolor centershade ; +\stopuseMPgraphic +\stopbuffer + +\startbuffer[b] +\startuseMPgraphic{second} + \includeMPgraphic{first} + interim linecap := butt ; pickup pencircle scaled gap ; + draw (0,0) -- (0,height) withcolor white ; +\stopuseMPgraphic +\stopbuffer + +\startbuffer[c] +\startuseMPgraphic{third} + \includeMPgraphic{first} + picture p, q ; p := q := currentpicture ; + clip p to unitsquare xscaled width yscaled height ; + clip q to unitsquare xscaled -width yscaled height ; + currentpicture := p ; + addto currentpicture also q shifted (0,radius/2) ; +\stopuseMPgraphic +\stopbuffer + +\getbuffer[a,b,c] + +\startbuffer[d] +\startcombination[5*3] + {\definecolor[funcolor][red] \useMPgraphic{first}} {} + {\definecolor[funcolor][green] \useMPgraphic{first}} {} + {\definecolor[funcolor][blue] \useMPgraphic{first}} {} + {\definecolor[funcolor][yellow]\useMPgraphic{first}} {} + {\definecolor[funcolor][white] \useMPgraphic{first}} {} + {\definecolor[funcolor][red] \useMPgraphic{second}} {} + {\definecolor[funcolor][green] \useMPgraphic{second}} {} + {\definecolor[funcolor][blue] \useMPgraphic{second}} {} + {\definecolor[funcolor][yellow]\useMPgraphic{second}} {} + {\definecolor[funcolor][white] \useMPgraphic{second}} {} + {\definecolor[funcolor][red] \useMPgraphic{third}} {} + {\definecolor[funcolor][green] \useMPgraphic{third}} {} + {\definecolor[funcolor][blue] \useMPgraphic{third}} {} + {\definecolor[funcolor][yellow]\useMPgraphic{third}} {} + {\definecolor[funcolor][white] \useMPgraphic{third}} {} +\stopcombination +\stopbuffer + +\placefigure + [here][fig:tricked 3] + {Koffka's examples of manipulating contrast by changing + the spatial configuration.} + {\getbuffer[d]} + +The definition of the first row of \in {figure} [fig:tricked 3] is used in the +second and third and therefore is the most complicated. We use quite some scratch +variables to reach a high level of abstraction. The \type {xyscaled} operator is +a \METAFUN\ macro. + +\typebuffer[a] + +The graphics of the second row extends those of the first by drawing a white line +through the middle. In this example setting the linecap is not really needed, +because rounded top and bottoms in white are invisible and the part that extends +beyond the points does not count in calculating the bounding box. + +\typebuffer[b] + +The third row graphics again extend the first graphic. First we copy the picture +constructed so far. Watch the double assignment. Next we clip the pictures in +half, and shift the right half down over the width of the circle. + +\typebuffer[c] + +\stopsection + +% \startsection[title={Puzzles}] +% +% {\em Maybe.} +% +% \stopsection +% +% \startsection[title={Flow charts}] +% +% {\em Instead of starting anew every time, you can use predefined macros, like +% those in the flow chart module. Let's see how we can influence the \METAPOST\ +% code. Maybe not here.} +% +% \stopsection +% +% \startsection[title={Chemistry}] +% +% {\em \METAPOST\ can do it's work unseen, as in the chemistry module that comes +% with \CONTEXT. There, \METAPOST\ is used as one of the graphical plug||ins. It +% demonstrates that we can put \METAPOST\ to work without seeing any code.} +% +% \stopsection + +\startsection[title={Growing graphics}] + +Although \METAPOST\ is not really suited as a simulation engine, it is possible +to build graphics that are built and displayed incrementally with a sequence of +mouse clicks. The following example is the result of an email discussion David +Arnold and the author had while \METAFUN\ evolved. + +Instead of defining the graphics in a separate \METAPOST\ file, we will +incorporate them in the document source in which they are used. We can use +several methods. + +\startitemize[n] +\startitem + Define macros and figures in a separate file and include the graphics as + external graphics. +\stopitem +\startitem + Define everything in the document source as usable graphics and include the + graphics using \type {\useMPgraphic}. +\stopitem +\startitem + Package the graphic components in buffers and paste those together as + graphics that can be processed at run time. +\stopitem +\stopitemize + +The first method is the most independent one, which has its advantages if we want +to use the graphics in other applications too. The second method works well in +graphics where parts of the definitions change between invocations of the +graphic. This method follows the template: + +\starttyping +\startuseMPgraphic{whatever} + ... +\stopuseMPgraphic + +\startuseMPgraphic{result} + ... + \includeMPgraphic{whatever} + ... +\stopuseMPgraphic + +\useMPgraphic{result} +\stoptyping + +The disadvantage of this method is that it cannot be combined with \type +{btex}||\type {etex} since it is nearly impossible to determine when, how, and to +what extent the content of a graphic should be expanded before writing it to the +temporary \METAPOST\ file. + +Therefore, we will demonstrate how buffers can be used. This third method closely +parallels the first way of defining graphics. A nice side effect is that we can +easily typeset these buffers verbatim, which we did to typeset this document. + +We are going to do a classic compass and straightedge construction, the bisection +of a line segment joining two arbitrary points. We will construct five graphics, +where each one displays one step of the construction. We will embed each graphic +in a start||stop command. Later we will see the advantage of this strategy. + +\startbuffer +\startbuffer[a] +def start_everything = enddef ; +def stop_everything = enddef ; +\stopbuffer +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\startbuffer[b] +numeric u, w ; u := .5cm ; w := 1pt ; + +pickup pencircle scaled w ; + +def draw_dot expr p = + draw p withpen pencircle scaled 3w ; +enddef ; + +def stand_out = + drawoptions(withcolor .625red) ; +enddef ; +\stopbuffer +\stopbuffer + +We are going to draw a few dots, and to force consistency we first define a macro +\type {draw_dot}. The current step will be highlighted in red using \type +{stand_out}. + +\typebuffer \getbuffer + +\startbuffer +\startbuffer[c] +def draw_basics = + pair pointA, pointB ; path lineAB ; + pointA := origin ; pointB := pointA shifted (5u,0) ; + lineAB := pointA -- pointB ; + draw lineAB ; + draw_dot pointA ; label.lft(btex A etex, pointA) ; + draw_dot pointB ; label.rt (btex B etex, pointB) ; +enddef ; +\stopbuffer +\stopbuffer + +First, we construct the macro that will plot two points $A$ and $B$ and connect +them with a line segment. + +\typebuffer \getbuffer + +\startbuffer +\startbuffer[1] +start_everything ; + stand_out ; draw_basics ; +stop_everything ; +\stopbuffer +\stopbuffer + +The code in this buffer executes the preceding macros. The \type {..._everything} +commands are still undefined, but later we can use these hooks for special +purposes. + +\typebuffer \getbuffer + +This graphic can now be embedded by the \CONTEXT\ command +\type {\processMPbuffer}. This command, like the ordinary +buffer inclusion commands, accepts a list of buffers. + +\startbuffer +\startlinecorrection[blank] +\ruledhbox{\processMPbuffer[a,b,c,1]} +\stoplinecorrection +\stopbuffer + +\typebuffer + +We use \type {\ruledhbox} to show the tight bounding box of the graphic. The line +correction takes care of proper spacing around non textual content, like +graphics. \footnote {These spacing commands try to get the spacing around the +content visually compatible, and take the height and depth of the preceding and +following text into account.} This is only needed when the graphic is part of the +text flow! + +\getbuffer + +Next, we draw two circles of equal radius, one centered at point $A$, the other +at point $B$. + +\startbuffer +\startbuffer[d] +def draw_circles = + path circleA, circleB ; numeric radius, distance ; + distance := (xpart pointB) - (xpart pointA) ; + radius := 2/3 * distance ; + circleA := fullcircle scaled (2*radius) ; + circleB := circleA shifted pointB ; + draw circleA ; + draw circleB ; +enddef ; +\stopbuffer +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\startbuffer[2] +start_everything ; + draw_basics ; stand_out ; draw_circles ; +stop_everything ; +\stopbuffer +\stopbuffer + +As you can see, we move down the \type {stand_out} macro so that only the +additions are colored red. + +\typebuffer \getbuffer + +We now use \type{\processMPbuffer[a,b,c,d,2]} to include the latest step. + +\startlinecorrection[blank] +\ruledhbox{\processMPbuffer[a,b,c,d,2]} +\stoplinecorrection + +The next step in the construction of the perpendicular bisector requires that we +find and label the points of intersection of the two circles centered at points +$A$ and $B$. The intersection points are calculated as follows. Watch the \type +{reverse} operation, which makes sure that we get the second intersection point. + +\startbuffer +\startbuffer[e] +def draw_intersection = + pair pointC, pointD ; + pointC := circleA intersectionpoint circleB ; + pointD := (reverse circleA) intersectionpoint (reverse circleB) ; + draw_dot pointC ; label.lft(btex C etex, pointC shifted (-2w,0)) ; + draw_dot pointD ; label.lft(btex D etex, pointD shifted (-2w,0)) ; +enddef ; +\stopbuffer +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\startbuffer[3] +start_everything ; + draw_basics ; draw_circles ; stand_out ; draw_intersection ; +stop_everything ; +\stopbuffer +\stopbuffer + +In placing the label, we must make sure that the text runs free of the lines and +curves. Again, move the \type {stand_out} macro just prior to \type +{draw_intersection} macro, so that this step is highlighted in the drawing color, +while prior steps are drawn in the default color (in this case black). + +\typebuffer \getbuffer + +\startlinecorrection[blank] +\ruledhbox{\processMPbuffer[a,b,c,d,e,3]} +\stoplinecorrection + +The line drawn through points $C$ and $D$ will be the perpendicular bisector of +the line segment connecting points $A$ and $B$. In the next step we will draw a +line using the plain \METAPOST\ \type {drawdblarrow} macro that draws arrowheads +at each end of a path. + +\startbuffer +\startbuffer[f] +def draw_bisector = + path lineCD ; + lineCD := origin -- origin shifted (2*distance,0) ; + lineCD := lineCD rotated 90 shifted 0.5[pointA,pointB] ; + lineCD := lineCD shifted (0,-distance) ; + drawdblarrow lineCD ; +enddef ; +\stopbuffer + +\startbuffer[4] +start_everything ; + draw_basics ; draw_circles ; draw_intersection ; stand_out ; + draw_bisector ; +stop_everything ; +\stopbuffer +\stopbuffer + +\typebuffer \getbuffer + +\startlinecorrection[blank] +\ruledhbox{\processMPbuffer[a,b,c,d,e,f,4]} +\stoplinecorrection + +The following code draws the intersection of line $C-D$ and line segment $A-B$, +which can be shown to be the midpoint of segment $A-B$. + +\startbuffer +\startbuffer[g] +def draw_midpoint = + pair pointM ; + pointM := lineCD intersectionpoint lineAB ; + draw_dot pointM ; label.llft(btex M etex, pointM) ; +enddef ; +\stopbuffer + +\startbuffer[5] +start_everything ; + draw_basics ; draw_circles ; draw_intersection ; draw_bisector ; + stand_out ; draw_midpoint ; +stop_everything ; +\stopbuffer +\stopbuffer + +\typebuffer \getbuffer + +\startlinecorrection[blank] +\ruledhbox{\processMPbuffer[a,b,c,d,e,f,g,5]} +\stoplinecorrection + +As long as we place the graphics as individual insertions in our document, +everything is fine. However, if we wish to place them all at once, or as we shall +see later, place them on top of one another in a fieldstack, it makes sense to +give them all the same bounding box. We can do this by completing the \type +{start_everything} and \type {stop_everything} commands. + +\startbuffer +\startbuffer[a] +def start_everything = + path bb ; + draw_basics ; + draw_circles ; + draw_intersection ; + draw_bisector ; + draw_midpoint ; + bb := boundingbox currentpicture ; + currentpicture := nullpicture ; +enddef ; + +def stop_everything = + setbounds currentpicture to bb ; +enddef ; +\stopbuffer +\stopbuffer + +\typebuffer \getbuffer + +In \in {figure} [fig:1 till 5] we demonstrate the effect of this redefinition. +For this purpose we scale down the graphic to a comfortable 40\%, of course by +using an additional buffer. We also visualize the bounding box. + +\startbuffer +\startbuffer[h] +def stop_everything = + setbounds currentpicture to bb ; + draw bb withpen pencircle scaled .5pt withcolor .625yellow ; + currentpicture := currentpicture scaled .4 ; +enddef ; +\stopbuffer +\stopbuffer + +\typebuffer \getbuffer + +The graphic itself is defined as follows. Watch how we use the default buffer to +keep the definitions readable. + +\startbuffer +\startbuffer +\startcombination[5*1] + {\processMPbuffer[a,b,c,h,d,e,f,g,1]} {step 1} + {\processMPbuffer[a,b,c,h,d,e,f,g,2]} {step 2} + {\processMPbuffer[a,b,c,h,d,e,f,g,3]} {step 3} + {\processMPbuffer[a,b,c,h,d,e,f,g,4]} {step 4} + {\processMPbuffer[a,b,c,h,d,e,f,g,5]} {step 5} +\stopcombination +\stopbuffer + +\placefigure + [here][fig:1 till 5] + {The five graphics, each with the same bounding box.} + {\getbuffer} +\stopbuffer + +\typebuffer \getbuffer + +As the original purpose of these graphics was not to show them side by side, but +to present them as field stack in a document to be viewed at the computer screen. +For this purpose we have to define the graphics as symbols. + +\startbuffer +\definesymbol[step 1][{\processMPbuffer[a,b,c,d,e,f,g,1]}] +\definesymbol[step 2][{\processMPbuffer[a,b,c,d,e,f,g,2]}] +\definesymbol[step 3][{\processMPbuffer[a,b,c,d,e,f,g,3]}] +\definesymbol[step 4][{\processMPbuffer[a,b,c,d,e,f,g,4]}] +\definesymbol[step 5][{\processMPbuffer[a,b,c,d,e,f,g,5]}] +\stopbuffer + +\typebuffer \getbuffer + +A field stack is a sequence of overlayed graphics. We will arrange these to cycle +manually, with clicks of the mouse, through the sequence of graphs depicting the +construction of the midpoint of segment $A-B$. So, in fact we are dealing with a +manual simulation. The definition of such a stack is as follows: + +\startbuffer +\definefieldstack + [midpoint construction] + [step 1, step 2, step 3, step 4, step 5] + [frame=on,offset=3pt,framecolor=darkyellow,rulethickness=1pt] +\stopbuffer + +\typebuffer \getbuffer + +The first argument is to be a unique identifier, the second argument takes a list +of symbols, while the third argument accepts settings. More on this command can +be found in the \CONTEXT\ manuals. + +The stack is shown as \in {figure} [fig:steps]. Its caption provides a button, +which enables the reader to cycle through the stack. We call this a stack because +the graphics are positioned on top of each other. Only one of them is visible at +any time. + +\startbuffer +\placefigure + [here][fig:steps] + {Bisecting a line segment with compass and straightedge? Just + click \goto {here} [JS(Walk_Field{midpoint construction})] to + walk through the construction! (This stack is only visible + in a \PDF\ viewer that supports widgets.)} + {\framed{\startoverlay + {\symbol[step 1]} + {\fieldstack[midpoint construction]} + \stopoverlay}} +\stopbuffer + +\typebuffer + +We cheat a bit and overlay the stack over the first symbol because otherwise +nothing shows up in print (nowadays I mostly use sumatrapdf). + +{\setupinteraction[color=darkred,contrastcolor=darkred]\getbuffer} + +At the start of this section, we mentioned three methods. When we use the first +method of putting all the graphics in an external \METAPOST\ file, the following +framework suits. We assume that the file is called \type {step.mp} and that it is +kept by the user along with his document source. We start with the definitions of +the graphic steps. These are the same as the ones shown previously. + +\starttyping +def draw_basics = ... enddef ; +def draw_circles = ... enddef ; +def draw_intersection = ... enddef ; +def draw_bisector = ... enddef ; +def draw_midpoint = ... enddef ; +def stand_out = ... enddef ; +\stoptyping + +We can safe some code by letting the \type {..._everything} take care of the +\type {beginfig} and \type {endfig} macros. + +\starttyping +def start_everything (expr n) = beginfig(n) ; ... enddef ; +def stop_everything = ... ; endfig ; enddef ; +\stoptyping + +The five graphics now become: + +\starttyping +start_everything (1) ; + stand_out ; draw_basics ; +stop_everything ; + +start_everything (2) ; + draw_basics ; stand_out ; draw_circles ; +stop_everything ; + +start_everything (3) ; + draw_basics ; draw_circles ; stand_out ; draw_intersection ; +stop_everything ; + +start_everything (4) ; + draw_basics ; draw_circles ; draw_intersection ; stand_out ; + draw_bisector ; +stop_everything ; + +start_everything (5) ; + draw_basics ; draw_circles ; draw_intersection ; draw_bisector ; + stand_out ; draw_midpoint ; +stop_everything ; +\stoptyping + +The definitions of the symbols now refer to an external +figure. + +\starttyping +\definesymbol[step 1][{\externalfigure[step.1]}] +\definesymbol[step 2][{\externalfigure[step.2]}] +\definesymbol[step 3][{\externalfigure[step.3]}] +\definesymbol[step 4][{\externalfigure[step.4]}] +\definesymbol[step 5][{\externalfigure[step.5]}] +\stoptyping + +Which method is used, depends on the way the graphics are used. In this example +we wanted to change the definition of \type {..._everything}, so here the third +method was quite useful. + +\stopsection + +\startsection[title={Simple Logos}] + +\startbuffer[ns] +numeric width, height, line, delta ; +width = 5cm ; height = width/2 ; line = height/4 ; delta = line ; + +linejoin := mitered ; pickup pencircle scaled line ; + +color nsblue ; nsblue := (0,0,1) ; +color nsyellow ; nsyellow := (1,1,0) ; + +z1 = (0, height/2) ; +z2 = (width/2-height/4, y1) ; +z3 = (width/2+height/4, y4) ; +z4 = (width, 0) ; + +z5 = (x4+height/2, y1) ; +z6 = (x4, 2y1) ; +z7 = 1.5[z5,z6] ; + +path p ; p := z1--z2--z3--z4 ; path q ; q := z3--z4--z5--z7 ; + +numeric d, lx, ly, ux, uy ; d = line/2 ; + +lx = -3d - d/3 ; ly = -d ; ux = rt x5 + d/3 ; uy = top y6 ; + +path r ; r := (lx,ly)--(ux,ly)--(ux,uy)--(lx,uy)--cycle; + +lx := lx-delta ; ly := ly-delta ; ux := ux+delta ; uy := uy+delta ; + +path s ; s := (lx,ly)--(ux,ly)--(ux,uy)--(lx,uy)--cycle; + +draw p withcolor nsblue ; draw q withcolor nsblue ; + +addto currentpicture also currentpicture + rotatedaround (.5[z2,z3],180) shifted (height/4,height/2) ; + +picture savedpicture ; savedpicture := currentpicture ; + +clip currentpicture to r ; +setbounds currentpicture to r ; + +savedpicture := currentpicture ; currentpicture := nullpicture ; + +fill s withcolor nsyellow ; +addto currentpicture also savedpicture ; +\stopbuffer + +Many company logos earn their beauty from their simplicity. One of the logos that +most Dutch people have imprinted in their mind is that of the Dutch Railway +Company (NS). An interesting feature of this logo is that, although it is widely +known, drawing it on a piece of paper from mind is a task that many people fail. + +\startlinecorrection[blank] +\processMPbuffer[ns] +\stoplinecorrection + +This logo makes a good candidate for demonstrating a few fine points of drawing +graphics, like using linear equations, setting line drawing characteristics, +clipping and manipulating bounding boxes. + +The implementation below is quite certainly not according to the official +specifications, but it can nevertheless serve as an example of defining such +logos. + +\startbuffer[a] +numeric width ; width = 3cm ; +numeric height ; height = width/2 ; +numeric line ; line = height/4 ; +\stopbuffer + +As always, we need to determine the dimensions first. Here, both the height and +line width depend on the width of the graphic. + +Instead of calculating the blue shape such that it will be a filled outline, we +will draw the logo shape using line segments. This is why we need the \type +{line} parameter. + +\typebuffer[a] + +We want sharp corners which can be achieved by setting \type {linejoin} to \type +{mitered}. + +\startbuffer[b] +linejoin := mitered ; pickup pencircle scaled line ; +\stopbuffer + +\typebuffer[b] + +The colors are rather primary blue and yellow. At the time of writing this +manual, Dutch trains are still painted yellow, so we will use that shade as +background color. + +\startbuffer[c] +color nsblue ; nsblue := (0,0,1) ; +color nsyellow ; nsyellow := (1,1,0) ; +\stopbuffer + +\typebuffer[c] + +We will now describe the main curves. Although these expressions are not that +advanced, they demonstrate that we can express relationships instead of using +assignments. + +\startbuffer[d] +z1 = (0, height/2) ; +z2 = (width/2-height/4, y1) ; +z3 = (width/2+height/4, y4) ; +z4 = (width, 0) ; + +path p ; p := z1--z2--z3--z4 ; +\stopbuffer + +\typebuffer[d] + +Although it is accepted to consider \type {z} to be a variable, it is in fact a +\type {vardef} macro, that expands into a pair \type {(x,y)}. This means that the +previous definitions internally become: + +\starttyping +(x1,y1) = (0, height/2) ; +(x2,y2) = (width/2-height/4, y1) ; +(x3,y3) = (width/2+height/4, y4) ; +(x4,y4) = (width, 0) ; +\stoptyping + +These 8 relations can be solved by \METAPOST, since all dependencies are known. + +\starttyping +x1 = 0 ; y1 = height/2 ; +x2 = width/2-height/4 ; y2 = y1 ; +x3 = width/2+height/4 ; y3 = y4 ; +x4 = width ; y4 = 0 ; +\stoptyping + +Since we express the variables \type {x} and \type {y} in terms of relations, we +cannot reuse them, because that would mean that inconsistent relations occur. So, +the following lines will lead to an error message: + +\starttyping +z1 = (10,20) ; z1 = (30,50) ; +\stoptyping + +For similar reasons, we may not assign a value (using \type {:=}) to such a \type +{z} variable. Within a \METAPOST\ figure, \type {z} variables are automatically +saved, which means that they can be reused for each figure. + +\startbuffer[x] +drawpath p ; drawpoints p ; drawpointlabels p ; +\stopbuffer + +So far, we have defined the following segment of the logo. + +\startlinecorrection[blank] +\processMPbuffer[a,b,c,d,x] +\stoplinecorrection + +\startbuffer[e] +z5 = (x4+height/2, y1) ; +z6 = (x4, 2y1) ; +z7 = 1.5[z5,z6] ; + +path q ; q := z3--z4--z5--z7 ; +\stopbuffer + +The next expressions are used to define the second segment. The third expression +determines \type {z7} to be positioned on the line \type {z5--z6}, where we +extend this line by 50\%. + +\typebuffer[e] + +\startbuffer[x] +drawpath q ; drawpoints q ; drawpointlabels q ; +\stopbuffer + +\startlinecorrection[blank] +\processMPbuffer[a,b,c,d,e,x] +\stoplinecorrection + +If we combine these two segments, we get: + +\startbuffer[x] +drawpath p ; drawpoints p ; drawpointlabels p ; +swappointlabels := true ; +drawpath q ; drawpoints q ; drawpointlabels q ; +\stopbuffer + +\startlinecorrection[blank] +\processMPbuffer[a,b,c,d,e,x] +\stoplinecorrection + +However, when we draw them using the right linewidth and color, you will notice +that we're not yet done: + +\startbuffer[f] +draw p withcolor nsblue ; draw q withcolor nsblue ; +\stopbuffer + +\startlinecorrection[blank] +\processMPbuffer[a,b,c,d,e,f] +\stoplinecorrection + +The second curve is similar to the first one, but rotated over 180 degrees. + +\startbuffer[g] +addto currentpicture also currentpicture + rotatedaround (.5[z2,z3],180) shifted (height/4,height/2) ; +\stopbuffer + +\typebuffer[g] + +\startlinecorrection[blank] +\processMPbuffer[a,b,c,d,e,f,g] +\stoplinecorrection + +In order to get the sharp edges, we need to clip off part of +the curves and at first sight, we may consider using a +scaled bounding box. However, when we show the natural +bounding box, you will notice that a more complicated bit of +calculations is needed. + +\startbuffer[x] +draw boundingbox currentpicture + withpen pencircle scaled .5mm withcolor .625white ; +\stopbuffer + +\startlinecorrection[blank] +\processMPbuffer[a,b,c,d,e,f,g,x] +\stoplinecorrection + +The right clip path is calculated using the following expressions. Watch how we +use \type {rt} and \type {top} to correct for the linewidth. + +\startbuffer[h] +numeric d, lx, ly, ux, uy ; d = line/2 ; + +lx = -3d - d/3 ; ly = -d ; ux = rt x5 + d/3 ; uy = top y6 ; + +path r ; r := (lx,ly)--(ux,ly)--(ux,uy)--(lx,uy)--cycle; +\stopbuffer + +\typebuffer[h] + +The clipping path is applied by saying: + +\startbuffer[i] +clip currentpicture to r ; +\stopbuffer + +\typebuffer[i] + +The result is quite acceptable: + +\startlinecorrection[blank] +\processMPbuffer[a,b,c,d,e,f,g,h,i] +\stoplinecorrection + +But, if you watch closely to how this graphic extends into to left margin of this +document, you will see that the bounding box is not yet right. + +\startlinecorrection[blank] +\processMPbuffer[a,b,c,d,e,f,g,h,i,x] +\stoplinecorrection + +\startbuffer[j] +setbounds currentpicture to r ; +\stopbuffer + +\typebuffer[j] + +We use the same path \type {r} to correct the bounding box. + +\startlinecorrection[blank] +\processMPbuffer[a,b,c,d,e,f,g,h,i,j,x] +\stoplinecorrection + +There are a few subtle points involved, like setting the \type {linejoin} +variable. If we had not set it to \type {mitered}, we would have got round +corners. We don't set the \type {linecap}, because a flat cap would not extend +far enough into the touching curve and would have left a small hole. The next +example shows what happens if we set these variables to the wrong values: + +\startbuffer[bb] +linejoin := rounded ; linecap := mitered ; +\stopbuffer + +\startlinecorrection[blank] +\processMPbuffer[a,b,bb,c,d,e,f,g,h,i,j] +\stoplinecorrection + +In fact we misuse the fact that both curves overlay each other. + +\startbuffer[f] +draw p withcolor nsblue ; draw q withcolor .625white ; +\stopbuffer + +\startlinecorrection[blank] +\processMPbuffer[a,b,c,d,e,f,g,h,i,j] +\stoplinecorrection + +The complete logo definition is a bit more extensive because we also want to add +a background. Because we need to clip the blue foreground graphic, we must +temporarily store it when we fill the background. + +\typebuffer[ns] + +For practical use it makes sense to package this definition in a macro to which +we pass the dimensions. + +\stopsection + +\startsection[title={Music sheets}] + +The next example demonstrates quite some features. Imagine that we want to make +us a couple of sheets so that we can write a musical masterpiece. Let's also +forget that \TEX\ can draw lines, which means that somehow we need to use +\METAPOST. + +Drawing a bar is not that complicated as the following code demonstrates. + +\startbuffer +\startusableMPgraphic{bar} + vardef MusicBar (expr width, gap, linewidth, barwidth) = + image + ( interim linecap := butt ; + for i=1 upto 5 : + draw ((0,0)--(width,0)) shifted (0,(i-1)*gap) + withpen pencircle scaled linewidth ; + endfor ; + for i=llcorner currentpicture -- ulcorner currentpicture , + lrcorner currentpicture -- urcorner currentpicture : + draw i withpen pencircle scaled barwidth ; + endfor ; ) + enddef ; +\stopusableMPgraphic +\stopbuffer + +\typebuffer \getbuffer + +We can define the sidebars a bit more efficient using two predefined subpaths: + +\starttyping +for i=leftboundary currentpicture, rightboundary currentpicture : +\stoptyping + +We define a macro \type {MusicBar} that takes four arguments. The first two +determine the dimensions, the last two concern the line widths. Now watch how we +can use this macro: + +\startbuffer +\includeMPgraphic{bar} ; +draw MusicBar (200pt, 6pt, 1pt, 2pt) ; +draw MusicBar (300pt, 6pt, 1pt, 2pt) shifted (0,-30pt) ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +As you can see in this example, the bar is a picture that can be transformed +(shifted in our case). However, a close look at the macro teaches us that it does +a couple of draws too. This is possible because we wrap the whole in an image +using the \type {image} macro. This macro temporary saves the current picture, +and at the end puts the old \type {currentpicture} under the new one. + +We wrap the whole in a \type {vardef}. This means that the image is returned as +if it was a variable. Actually, the last thing in a \type {vardef} should be a +proper return value, in our case a picture. This also means that we may not end +the \type {vardef} with a semi colon. So, when the content of the \type {vardef} +is expanded, we get something + +\starttyping +draw some_picture ... ; +\stoptyping + +Because we are still drawing something, we can add transform directives and set +attributes, like the color. + +The second \type {for} loop demonstrates two nice features. Instead of repeating +the draw operation by copying code, we apply it to a list, in our case a list of +paths. This list contains two simple line paths. Because an \type {image} starts +with a fresh \type {currentpicture}, we can safely use the bounding box data to +determine the height of the line. + +The next step in producing the sheets of paper is to put several bars on a page, +preferable with the width of the current text. This time we will use a reusable +graphic, because each bar is the same. + +\startbuffer +\startreusableMPgraphic{bars} + \includeMPgraphic{bar} ; + draw MusicBar (TextWidth, 6pt, 1pt, 2pt) withcolor .625yellow ; +\stopreusableMPgraphic +\stopbuffer + +\typebuffer \getbuffer + +\startlinecorrection[blank] +\reuseMPgraphic{bars} +\stoplinecorrection + +Instead of going through the trouble of letting \METAPOST\ calculate the positions +of the bars, we will use \TEX. We put 12 bars on a page and let \TEX\ take care +of the inter||bar spacing. Because we only want stretchable space between bars, +called glue in \TEX, we need to remove the last added glue. + +\startnotmode[screen] + +\startbuffer[music] +\startstandardmakeup[doublesided=no,page=] + \dorecurse{15}{\reuseMPgraphic{bars}\vfill}\removelastskip +\stopstandardmakeup +\stopbuffer + +\stopnotmode + +\startmode[screen] + +\startbuffer[music] +\startstandardmakeup[doublesided=no,page=] + \dorecurse{10}{\reuseMPgraphic{bars}\vfill}\removelastskip +\stopstandardmakeup +\stopbuffer + +\stopmode + +\typebuffer[music] + +\startusableMPgraphic{bar} + vardef MusicBar (expr width, gap, linewidth, barwidth) = + image + ( interim linecap := butt ; + for i=1 upto 5 : + draw ((0,0)--(width,0)) + randomized (1pt,1.5pt) + shifted (0,(i-1)*gap) + withpen pencircle scaled linewidth ; + endfor ; + for i=llcorner currentpicture -- ulcorner currentpicture , + lrcorner currentpicture -- urcorner currentpicture : + draw i randomized 2pt shifted (0,-1pt) + withpen pencircle scaled barwidth ; + endfor ; ) + enddef ; +\stopusableMPgraphic + +\startreusableMPgraphic{bars} % trigger a new one + \includeMPgraphic{bar} ; + draw MusicBar (TextWidth, 6pt, 1pt, 2pt) withcolor .625yellow ; +\stopreusableMPgraphic + +It may add to the atmosphere of handy||work if you slightly randomize the lines. +We leave it up to the reader to figure out how the code should be changed to +accomplish this. + +\startlinecorrection[blank] +\reuseMPgraphic{bars} +\stoplinecorrection + +The complete result is shown on the next page. + +\startpostponing +\getbuffer[music] +\stoppostponing + +\stopsection + +\startsection[title={The euro symbol}] + +When Patrick Gundlach posted a nice \METAPOST\ version of the euro symbol to the +\CONTEXT\ discussion list, he added the comment \quotation {The official +construction is ambiguous: how thick are the horizontal bars? How much do they +stick out to the left? Is this thing a circle or what? Are the angles on the left +side of the bars the same as the one on the right side? \unknown} The alternative +below is probably not as official as his, but permits a finetuning. You are +warned: whatever you try, the euro {\em is} and {\em will remain} an ugly symbol. + +We use a couple of global variables to control the euro shape within reasonable +bounds. Then we define two circles. Next we define a vertical line that we use in +a couple of cut and paste operations. Watch how the top left point of the outer +circle determines the slant of the line that we use to slice the vertical bars. + +\startbuffer[euro] +boolean trace_euro ; trace_euro := false ; + +vardef euro_symbol = image ( % begin_of_euro + +if unknown euro_radius : euro_radius := 2cm ; fi ; +if unknown euro_width : euro_width := 3euro_radius/16 ; fi ; +if unknown euro_r_offset : euro_r_offset := euro_width ; fi ; +if unknown euro_l_offset : euro_l_offset := euro_radius/32 ; fi ; +if unknown euro_l_shift : euro_l_shift := euro_r_offset ; fi ; +if unknown euro_v_delta : euro_v_delta := euro_width/4 ; fi ; + +save + outer_circle, inner_circle, hor_bar, + right_line, right_slant, top_slant, bot_slant, + euro_circle, euro_topbar, euro_botbar ; + +path + outer_circle, inner_circle, hor_bar, + right_line, right_slant, top_slant, bot_slant, + euro_circle, euro_topbar, euro_botbar ; + +outer_circle := fullcircle scaled euro_radius ; +inner_circle := fullcircle scaled (euro_radius-euro_width) ; + +if trace_euro : for i = outer_circle, inner_circle : + draw i withpen pencircle scaled 1pt withcolor .5white ; +endfor ; fi ; + +right_line := + (lrcorner outer_circle -- urcorner outer_circle) + shifted (-euro_r_offset,0) ; + +outer_circle := outer_circle cutbefore right_line ; + +right_slant := + point 0 of outer_circle + -- origin shifted (0,ypart lrcorner outer_circle) ; + +euro_circle := buildcycle(outer_circle, right_line, + reverse inner_circle, reverse right_slant) ; + +hor_bar := (-euro_radius,0) -- (euro_radius,0) ; + +top_slant := + right_slant shifted (-euro_radius+euro_r_offset-euro_l_offset,0) ; + +bot_slant := + top_slant shifted (0,-euro_l_shift) ; + +if trace_euro : for i = right_line, right_slant, top_slant, bot_slant : + draw i withpen pencircle scaled 1pt withcolor .5white ; +endfor ; fi ; + +euro_topbar := buildcycle + (top_slant, hor_bar shifted (0, euro_v_delta), + right_slant, hor_bar shifted (0, euro_v_delta+euro_width/2)) ; + +euro_botbar := buildcycle + (bot_slant, hor_bar shifted (0,-euro_v_delta), + right_slant, hor_bar shifted (0,-euro_v_delta-euro_width/2)) ; + +for i = euro_circle, euro_topbar, euro_botbar : + draw i withpen pencircle scaled 0 ; +endfor ; +for i = euro_circle, euro_topbar, euro_botbar : + fill i withpen pencircle scaled 0 ; +endfor ; + +if trace_euro : + drawpoints euro_circle withcolor red ; + drawpoints euro_topbar withcolor green ; + drawpoints euro_botbar withcolor blue ; +fi ; + +) enddef ; % end_of_euro +\stopbuffer + +\typebuffer[euro] + +We only set a parameter when it is not yet set. This has +the advantage that we don't have to set them when we change +one. This way of manipulating paths (cutting and building) +does not always work well because of rounding errors, but +here it does work. + +\startbuffer[demo] +euro_radius := 4cm ; trace_euro := true ; draw euro_symbol ; +\stopbuffer + +\typebuffer[demo] + +For educational purposes, we have added a bit of +tracing. When enabled, the euro shows up as: + +\startlinecorrection[blank] +\processMPbuffer[euro,demo] +\stoplinecorrection + +Of course it would be best to define the euro as one shape, but we won't go +though that process right now. By packaging the combined paths in an image, we +can conveniently color the euro symbol: + +\startbuffer[demo] +draw euro_symbol withcolor .625red ; +\stopbuffer + +\typebuffer[demo] + +\startlinecorrection[blank] +\processMPbuffer[euro,demo] +\stoplinecorrection + +You may wonder why we both draw and fill the euro, using a pen with zero width. +We've done this in order to demonstrate the \type {redraw} and \type {refill} +macros. + +\startbuffer[extra] +redraw currentpicture withpen pencircle scaled 4pt withcolor .625yellow ; +refill currentpicture withcolor .625white ; +setbounds currentpicture to boundingbox currentpicture enlarged 2pt ; +\stopbuffer + +\typebuffer[extra] + +\startlinecorrection[blank] +\processMPbuffer[euro,demo,extra] +\stoplinecorrection + +\stopsection + +\startsection[title={Killing time}] + +Not seldom \TEX\ users want to use this program and its meta||relatives as +general purpose tools, even at the cost of quite some effort or suboptimal +results. Imagine that you are under way from our planet to Mars. After a long +period of sleep you wake up and start wondering on what track you are. You even +start questioning the experts that send you on your way, so you pop open your +laptop, launch your editor and start metaposting. + +First you need to determine the begin and end points of your journey. For now it +is enough to know the relative angle of the paths that both planets follow as +well as the path themselves. We assume circular paths. + +\startbuffer +path a ; a := fullcircle scaled 3cm ; +path b ; b := fullcircle scaled 2cm rotated 120 ; + +draw a withpen pencircle scaled 1mm withcolor .625red ; +draw b withpen pencircle scaled 1mm withcolor .625yellow ; + +draw point 0 of a withpen pencircle scaled 2mm ; +draw point 0 of b withpen pencircle scaled 2mm ; +\stopbuffer + +\typebuffer + +The rotation 120 can be calculated from the relative starting points and time the +journey will take. Alternatively we can use the time along the path, but this +would be a bit more fuzzy later on. \footnote {In case you wonder why \METAPOST\ +talks about the time on a path, you now have a cue.} + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +After a bit of playing with drawing paths between the two points, you decide to +make a macro. We want to feed the angle between the paths but also the connecting +path. So, we have to pass a path, but unfortunately we don't have direct access +to the points. By splitting the argument definition we can pass an expression +first, and a wildcard argument next. + +\startbuffer +\startuseMPgraphic{gamble} +def Gamble (expr rot) (text track) = + path a ; a := fullcircle scaled 3cm ; + path b ; b := fullcircle scaled 2cm rotated rot ; + + pair aa ; aa := point 0 of a ; + pair bb ; bb := point 0 of b ; + path ab ; ab := track ; + + draw a withpen pencircle scaled 1mm withcolor .625red ; + draw b withpen pencircle scaled 1mm withcolor .625yellow ; + + draw aa withpen pencircle scaled 2mm ; + draw bb withpen pencircle scaled 2mm ; + + drawarrow ab withpen pencircle scaled 1mm withcolor .625white ; + + setbounds currentpicture to boundingbox a enlarged 2mm ; + draw boundingbox currentpicture withpen pencircle scaled .25mm ; +enddef ; +\stopuseMPgraphic +\stopbuffer + +\typebuffer \getbuffer + +Because at this distance nobody will bother us with the thickness of the pen and +colors, we code them the hard way. We create our own universe by setting a fixed +boundingbox. + +We leave the Earth in the most popular way, straight upwards and after a few +cycles, we leave it parallel to the surface. The path drawn reminds much of the +trajectories shown in popular magazines. + +\startbuffer +\startMPcode +\includeMPgraphic{gamble} ; +Gamble(120, aa {(0,1)} .. bb) ; +\stopMPcode +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] \getbuffer \stoplinecorrection + +According to \METAPOST, when we leave the Earth straight upwards and want a +smooth trajectory, we have to pass through outer space. + +\startbuffer +\startMPcode +\includeMPgraphic{gamble} ; +Gamble(120,aa {(1,0)} .. bb) ; +\stopMPcode +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] \getbuffer \stoplinecorrection + +Given that we want a smooth path as well as a short journey, we can best follow +Mars' path. Here we face the risk that when we travel slower than Mars does, we +have a problem. + +\startbuffer +\startMPcode +\includeMPgraphic{gamble} ; +Gamble(120,aa {dir 90} .. {precontrol 0 of b rotated 90} bb) ; +\stopMPcode +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] \getbuffer \stoplinecorrection + +We can even travel a shorter path when we leave Earth at the surface that faces +the point of arrival. + +\startbuffer +\startMPcode +\includeMPgraphic{gamble} ; +Gamble(120,aa .. {precontrol 0 of b rotated 90} bb) ; +\stopMPcode +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] \getbuffer \stoplinecorrection + +In the end we decide that although the trajectories look impressive, we will not +trust our lives to \METAPOST. A beautiful path is not neccessarily a good path. +But even then, this macro provides a nice way to experiment with directions, +controls and tensions. + +\stopsection + +% \startsection[title={Animations}] +% +% {\em Although \METAPOST\ is not that well suited for free hand drawings, you can +% use it to make stylistics animations.} +% +% \stopsection + +\startsection[title={Selective randomization}] + +In this document we have used a lot of randomization. Because \CONTEXT\ often +needs multiple runs to sort out cross references, positions, tables of contents, +and so on, being real random every run would result in endless runs to get things +right, because the size of graphics changes. This is prevented by storing the +random seed betweeen runs. You can remove the \type {tuc} file to get a new seed +(or run \type {context --purgeall}). + +Here is another example of randomization. This time we only randomize the control +points so the main shape sort of remains intact which can be handy when you use +such random shapes around text but still want a predictable size. + +\startbuffer +\startMPcode +fill fullcircle scaled 2cm + randomizedcontrols 0.1cm + withcolor darkred + withtransparency (1,.5) ; +fill ((1cm,0)--(0,1cm)--(-1cm,0)--cycle) + randomizedcontrols 0.1cm + withcolor darkblue + withtransparency (1,.5) ; +\stopMPcode +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] \getbuffer \stoplinecorrection + +\startbuffer +\startMPcode +draw image ( + fill fullcircle scaled 2cm + withcolor darkred + withtransparency (1,.5) ; + fill ((1cm,0)--(0,1cm)--(-1cm,0)--cycle) + withcolor darkblue + withtransparency (1,.5) ; +) randomizedcontrols 0.1cm ; +\stopMPcode +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] \getbuffer \stoplinecorrection + +\stopsection + +\startsection[title=Snapping] + +There are quite some helpers in \METAFUN\ and I must admit that I forgot +about most. Some just ended up in the core because they can be useful, others +serve as illustration. Here's one of them: \type {snapped}. First we define +a few helpers that we then use to check out a few shapes. + +\startbuffer +\startMPdefinitions +def ShowSnapGrid(text shape) = + fill (shape xsized 77mm) withcolor white/3 ; + draw image ( + for i=10mm step 5mm until 100mm : + draw fullsquare scaled i ; + endfor ; + ) withcolor 2white/3 ; + drawpoints (shape xsized 77mm) withcolor black ; +enddef ; + +vardef SnapShape expr shape = + image ( + draw shape ; + drawpoints shape ; + ) +enddef ; + +vardef ShowSnapShape expr shape = + ShowSnapGrid(shape); + + draw SnapShape(shape xsized 77mm snapped -5mm ) withcolor red ; + draw SnapShape(shape xsized 77mm snapped 5mm ) withcolor red ; + draw SnapShape(shape xsized 77mm snapped (5mm,10mm)) withcolor green ; + draw SnapShape(shape xsized 77mm snapped (5mm,15mm)) withcolor blue ; + draw SnapShape(shape xsized 77mm snapped (5mm,20mm)) withcolor yellow ; +enddef ; +\stopMPdefinitions +\stopbuffer + +\typebuffer \getbuffer + +In \in {figures} [fig:snapper:1], \in [fig:snapper:2] and \in [fig:snapper:3] we +see how the original shape gets snapped on the grid. Of course in more complex +images the direction of the snapping can change the result in an unwanted way, +like overlapping shapes that obscure others, but normally this snapping is only +useful for simple predictable cases (like title pages). + +\startplacefigure[reference=fig:snapper:1,title={Messing with \type{fullcircle}.}] +\startMPcode + ShowSnapShape(fullcircle); +\stopMPcode +\stopplacefigure + +\startplacefigure[reference=fig:snapper:2,title={\type{fullsquare}}] +\startMPcode + ShowSnapShape(fullsquare); +\stopMPcode +\stopplacefigure + +\startplacefigure[reference=fig:snapper:3,title={\type{fulltriangle}}] +\startMPcode + ShowSnapShape(fulltriangle); +\stopMPcode +\stopplacefigure + +\stopsection + +\startsection[title=Arrowheads] + +Arrows are actually drawn quite well in \METAPOST, as the arrowheads nicely adapt +to the direction of the point where the arrowhead is attached. There are however +some limitations as the following examples demonstrate: arrows don't work well +with transparency and you can probably figure out why. Alan Braslau came up with +an extension that allows to set the dimple of the head. You can see all this +in \in {figure} [fig:arrowheads]. + +\startbuffer[a] +numeric unit ; unit := mm ; + +drawoptions(withcolor .6blue withtransparency (1,.25)) ; + +pickup pencircle scaled 2unit ; ahlength := 6unit ; + +picture p ; p := image ( + drawarrow reverse fullcircle rotated - 5 scaled 50unit ; + drawarrow reverse fullcircle rotated -10 scaled 30unit ; +) shifted ( -45unit, 0unit) ; + +for i=0 step 90 until 360 : draw p rotated i ; endfor ; + +currentpicture := currentpicture shifted - center currentpicture ; + +p := currentpicture ; p := image ( + draw llcorner p -- center p ; + drawarrow llcorner p -- 0.875[llcorner p,center p] ; +) ; + +for i=0 step 90 until 360 : draw p rotated i ; endfor ; + +clip currentpicture to boundingbox (fullcircle scaled 80unit) ; + +if lua.mp.mode("screen") : + currentpicture := currentpicture ysized .4TextHeight ; +else : + currentpicture := currentpicture xsized .4TextWidth ; +fi ; +\stopbuffer + +\typebuffer[a] + +\startbuffer[b] + resetarrows ; +\stopbuffer + +\startbuffer[a1] + ahvariant := 1 ; +\stopbuffer +\startbuffer[a2] + ahvariant := 2 ; +\stopbuffer + +\startbuffer[a3] + ahvariant := 1 ; ahdimple := 1/2 ; +\stopbuffer +\startbuffer[a4] + ahvariant := 1 ; ahdimple := 1 ; +\stopbuffer +\startbuffer[a5] + ahvariant := 1 ; ahdimple := 5/2 ; +\stopbuffer + +\startplacefigure[reference=fig:arrowheads,title=The way arrowheads are constructed.] + \doifelsemode {screen} { + \setupcombination[nx=3,ny=2] + } { + \setupcombination[nx=2,ny=3] + } + \startcombination[distance=2em] + {\processMPbuffer[a, b]} {\tttf ahvariant=0} + {\processMPbuffer[a1,a,b]} {\tttf ahvariant=1} + {\processMPbuffer[a2,a,b]} {\tttf ahvariant=2} + {\processMPbuffer[a3,a,b]} {\tttf ahvariant=1, ahdimple=1/2} + {\processMPbuffer[a4,a,b]} {\tttf ahvariant=1, ahdimple=1} + {\processMPbuffer[a5,a,b]} {\tttf ahvariant=1, ahdimple=5/2} + \stopcombination +\stopplacefigure + +\stopsection + +\startsection[title=Teaser] + +Sometimes, when playing with \METAPOST\ you run into interesting cases. Here is +one. The result is shown in \in {figure} [fig:teaser:1]. + +\startbuffer +\startusableMPgraphic{BackgroundTeaser} + fill OverlayBox enlarged 1mm withcolor darkyellow ; % bleed + path p ; p := OverlayBox enlarged -5mm ; + path q ; q := OverlayBox enlarged -10mm ; + fill q withcolor white ; + drawoptions(withcolor darkred) ; + fill reverse topboundary q -- topboundary p -- cycle ; + fill reverse bottomboundary q -- bottomboundary p -- cycle ; + drawoptions(withcolor darkgreen) ; + fill reverse leftboundary q -- leftboundary p -- cycle ; + fill reverse rightboundary q -- rightboundary p -- cycle ; +\stopusableMPgraphic + +\defineoverlay + [BackgroundTeaser] + [\useMPgraphic{BackgroundTeaser}] + +\framed + [frame=off, + offset=15mm, + background=BackgroundTeaser, + align=normal] + {\input knuth } +\stopbuffer + +\typebuffer + +\startplacefigure[reference=fig:teaser:1,title=Can you guess what happens here?] + \getbuffer +\stopplacefigure + +\stopsection + +\startsection[title={Lists}] + +For some specific purpose I needed to sort a list of paths and therefore +\METAFUN\ comes with a quick sort macro. Its working can be demonstrated by an +example. + +\startbuffer[a] +pair p[], pp[] ; numeric n ; n := 25 ; +for i=1 upto n : p[i] := origin randomized 4cm ; endfor ; +\stopbuffer + +\startbuffer[b] +copylist(p,pp) ; % unsorted +drawarrow listtolines(pp) shifted ( 0,0) withcolor darkblue ; +\stopbuffer + +\startbuffer[c] +copylist(p,pp) ; sortlist(pp)() ; % sorted +drawarrow listtolines(pp) shifted (300,0) withcolor darkyellow ; +\stopbuffer + +\startbuffer[d] +copylist(p,pp) ; sortlist(pp)(xpart) ; +drawarrow listtolines(pp) shifted (100,0) withcolor darkred ; + +\stopbuffer +\startbuffer[e] +copylist(p,pp) ; sortlist(pp)(ypart) ; +drawarrow listtolines(pp) shifted (200,0) withcolor darkgreen ; +\stopbuffer + +\startbuffer[f] +vardef whow expr p = (xpart p + ypart p) enddef ; + +copylist(p,pp) ; sortlist(pp)(whow) ; +drawarrow listtolines(pp) shifted (400,0) withcolor darkcyan ; +\stopbuffer + +\startbuffer[g] +vardef whow expr p = (xpart p ++ ypart p) enddef ; + +copylist(p,pp) ; sortlist(pp)(whow) ; +drawarrow listtolines(pp) shifted (500,0) withcolor darkmagenta ; +\stopbuffer + +\typebuffer[a,b,c,d,e,f,g] + +The result of this code is shown in \in {figure} [fig:sorting]. + +\startplacefigure[reference=fig:sorting,title={Using the sorter.}] + \startcombination[3*2] + {\processMPbuffer[a,b]} {\tttf unsorted} + {\processMPbuffer[a,c]} {\tttf sorted} + {\processMPbuffer[a,d]} {\tttf xpart} + {\processMPbuffer[a,e]} {\tttf ypath} + {\processMPbuffer[a,f]} {\tttf xpart p + ypart p} + {\processMPbuffer[a,g]} {\tttf xpart p ++ ypart p} + \stopcombination +\stopplacefigure + +There is a helper that converts a list of paths into a shape that covers all +of them. In \in {figure} [fig:shapedlist] three shaped lists are shown. + +\startbuffer[a] + def ShowShape(expr e) = + draw image ( + + save p ; path p[] ; + + def MakeShape(expr i,w,h,x,y) = + p[i] := e + xysized ((w,h) randomized (2mm,1mm)) + shifted ((x,y) randomized (2mm,1mm)) ; + enddef ; + + MakeShape(1,40mm,6mm,10mm, 0mm) ; + MakeShape(2,50mm,5mm, 5mm,-10mm) ; + MakeShape(3,20mm,8mm,30mm,-20mm) ; + MakeShape(4,55mm,5mm,10mm,-30mm) ; + MakeShape(5,55mm,5mm, 5mm,-50mm) ; + + save s ; path s ; s := shapedlist(p) ; drawarrow s ; + + linejoin := butt ; + + for i=1 upto 5 : + fill p[i] withcolor .75white withtransparency (1,.5) ; + draw thetextext("\tttf " & decimal i, center p[i]) ; + endfor ; + + ) ysized 4cm ; + enddef ; +\stopbuffer + +\typebuffer[a] + +\startbuffer[b] +ShowShape(unitsquare) +\stopbuffer + +\startbuffer[c] +ShowShape(unitcircle) +\stopbuffer + +\startbuffer[d] +ShowShape(unittriangle) +\stopbuffer + +\startplacefigure[reference=fig:shapedlist,title={The \type {shapedlist} macro returns the envelope that covers all the paths in the list.}] + \startcombination[3*1] + {\processMPbuffer[a,b]} {\tttf unitsquare} + {\processMPbuffer[a,c]} {\tttf unitcircle} + {\processMPbuffer[a,d]} {\tttf unittriangle} + \stopcombination +\stopplacefigure + +\stopsection + +\startsection[title=Table cells] + +Sometimes a standard \CONTEXT\ feature doesn't work out as expected. Take the +following table: + +\startbuffer +\bTABLE[frame=on,framecolor=blue,rulethickness=1pt] + \bTR + \bTD test \eTD + \bTD test \eTD + \bTD test \eTD + \bTD[framecolor=magenta] test \eTD + \bTD test \eTD + \bTD test \eTD + \eTR + \bTR + \bTD test \eTD + \bTD[framecolor=red] test \eTD + \bTD test \eTD + \bTD test \eTD + \bTD test \eTD + \bTD[framecolor=green] test \eTD + \eTR +\eTABLE +\stopbuffer + +\typebuffer + +Because cells are drawn top|-|down and left|-|right a next cell border +overruns the previous one. + +\startlinecorrection +\getbuffer +\stoplinecorrection + +\startbuffer +\bTABLE[frame=on,framecolor=blue,rulethickness=1pt] + \bTR + \bTD test \eTD + \bTD test \eTD + \bTD test \eTD + \bTD[framecolor=magenta,frameoffset=-.5pt] test \eTD + \bTD test \eTD + \bTD test \eTD + \eTR + \bTR + \bTD test \eTD + \bTD[framecolor=red,frameoffset=-.5pt] test \eTD + \bTD test \eTD + \bTD test \eTD + \bTD test \eTD + \bTD[framecolor=green,frameoffset=-.5pt] test \eTD + \eTR +\eTABLE +\stopbuffer + +You can try this: + +\typebuffer + +which gives us something that is not okay either for cells that touch an edge: + +\startlinecorrection +\getbuffer +\stoplinecorrection + +but we can cheat: + +\startlinecorrection +\framed + [offset=overlay, + frameoffset=.5pt, + framecolor=blue, + rulethickness=1pt] + {\getbuffer} +\stoplinecorrection + +This is achieved by framing the whole table: + +\starttyping +\framed + [offset=overlay, + frameoffset=.5pt, + framecolor=blue, + rulethickness=1pt] + {...} +\stoptyping + +\startbuffer +\startuseMPgraphic{cell:innerframe}{innercolor} + draw OverlayBox enlarged -1.5OverlayLineWidth + withpen pensquare scaled OverlayLineWidth + withcolor \MPvar{innercolor} ; +\stopuseMPgraphic + +\defineoverlay + [innerframe] + [{\uniqueMPgraphic{cell:innerframe}% + {innercolor=\framedparameter{innercolor}}}] + +\bTABLE[frame=on,framecolor=blue,rulethickness=1pt,innercolor=magenta] + \bTR + \bTD test \eTD + \bTD test \eTD + \bTD test \eTD + \bTD[background=innerframe] test \eTD + \bTD test \eTD + \bTD test \eTD + \eTR + \bTR + \bTD test \eTD + \bTD[background=innerframe,innercolor=red] test \eTD + \bTD test \eTD + \bTD test \eTD + \bTD test \eTD + \bTD[background=innerframe,innercolor=green] test \eTD + \eTR +\eTABLE +\stopbuffer + +A \METAPOST\ alternative is also possible and it gives a bit nicer +interface too: + +\typebuffer + +We get: + +\startlinecorrection +\getbuffer +\stoplinecorrection + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/metafun/metafun-functions.tex b/doc/context/sources/general/manuals/metafun/metafun-functions.tex new file mode 100644 index 000000000..780127408 --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/metafun-functions.tex @@ -0,0 +1,611 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\startcomponent metafun-functions + +\environment metafun-environment + +\startchapter[title={Functions}] + +\index{functions} + +\startintro + +\METAPOST\ provides a wide range of functions, like \type {sind} and \type +{floor}. We will discuss most of them here and define a few more. We will also +introduce a few methods for drawing grids and functions. + +\stopintro + +\startsection[title={Overview}] + +What follows is a short overview of the functions that can be applied to numeric +expressions and strings. Functions that operate on pairs, colors, paths and +pictures are discussed in other chapters. + +First of all we have \type {+}, \type {-}, \type {/} and \type {*}. For as far as +is reasonable, you can apply these to numerics, pairs and colors. Strings can be +concatenated by \type {&}. + +Pythagorean addition is accomplished by \type {++}, while Pythagorean subtraction +is handled by \type {+-+}. The \type {**} operator gives you exponentiation. The +nature of the \METAPOST\ language is such that you can easily define interesting +functions using such symbols. + +The logarithmic functions are based on bytes. This makes them quite accurate but +forces you to think like a computer. + +\starttabulate[|lT|l|] +\HL +\NC mexp(x) \NC expential function with base 256 \NC \NR +\NC mlog(x) \NC logarithm with base 256 \NC \NR +\HL +\stoptabulate + +The basic goniometric functions operate on degrees, which is why they have a +\quote {d} in their name. + +\starttabulate[|lT|l|] +\HL +\NC cosd(x) \NC cosine of $x$ with $x$ in degrees \NC \NR +\NC sind(x) \NC sine of $x$ with $x$ in degrees \NC \NR +\HL +\stoptabulate + +There are three ways to truncate numbers. The \type {round} function can also +handle pairs and colors. + +\starttabulate[|lT|l|] +\HL +\NC ceiling(x) \NC the least integer greater than or equal to $x$ \NC \NR +\NC floor(x) \NC the greatest integer less than or equal to $x$ \NC \NR +\NC round(x) \NC round each component of $x$ to the nearest integer \NC \NR +\HL +\stoptabulate + +Of course we have: + +\starttabulate[|lT|l|] +\HL +\NC x mod y \NC the remainder of $x/y$ \NC \NR +\NC x div y \NC the integer part of $x/y$ \NC \NR +\NC abs(x) \NC the absolute value of $x$ \NC \NR +\NC sqrt(x) \NC the square root of $x$ \NC \NR +\NC x dotprod y \NC the dot product of two vectors \NC \NR +\HL +\stoptabulate + +What would life be without a certain randomness and uncertainty: + +\starttabulate[|lT|l|] +\HL +\NC normaldeviate \NC a number with mean 0 and standard deviation 1 \NC \NR +\NC uniformdeviate(x) \NC a number between zero and $x$ \NC \NR +\HL +\stoptabulate + +The following functions are actually macros: + +\starttabulate[|lT|l|] +\HL +\NC decr(x,n) \NC decrement $x$ by $n$ \NC \NR +\NC incr(x,n) \NC increment $x$ by $n$ \NC \NR +\NC max(a,b,..) \NC return the maximum value in the list \NC \NR +\NC min(a,b,..) \NC return the minimum value in the list \NC \NR +\HL +\stoptabulate + +The \type {min} and \type {max} funtions can be applied to numerics as well as +strings. + +The following functions are related to strings: + +\starttabulate[|lT|l|] +\HL +\NC oct s \NC string representation of an octal number \NC \NR +\NC hex s \NC string representation of a hexadecimal number \NC \NR +\NC str s \NC string representation for a suffix \NC \NR +\NC ASCII s \NC \ASCII\ value of the first character \NC \NR +\NC char x \NC character of the given \ASCII\ code \NC \NR +\NC decimal x \NC decimal representation of a numeric \NC \NR +\HL +\stoptabulate + +With \type {substring (i,j) of s} you can filter the substring bounded by the +given indices from the given string. + +In \METAFUN\ we provide a few more functions (you can take a look in \type +{mp-tool.mp} to see how they are defined. You need to be aware of very subtle +rounding errors. Normally these only show up when you reverse an operation. This +is a result from mapping to and from internal quantities. + +\starttabulate[|Tl|ml|] +\HL +\NC sqr(x) \NC x^2 \NC \NR +\NC log(x) \NC \log(x) \NC \NR +\NC ln(x) \NC \ln(x) \NC \NR +\NC exp(x) \NC {\rm e}^x \NC \NR +\NC pow(x, p) \NC x^p \NC \NR +\NC inv(x) \NC 1/x \NC \NR +\HL +\stoptabulate + +The following sine and cosine functions take radians instead of angles in +degrees. + +\starttabulate[|Tl|Tl|Tl|] +\HL +\NC sin(x) \NC asin(x) \NC invsin(x) \NC \NR +\NC cos(x) \NC acos(x) \NC invcos(x) \NC \NR +\HL +\stoptabulate + +There are no tangent functions, so we provide both the radian and degrees +versions: + +\starttabulate[|Tl|Tl|] +\HL +\NC tan(x) \NC tand(x) \NC \NR +\NC cot(x) \NC cotd(x) \NC \NR +\HL +\stoptabulate + +Here are a couple of hyperbolic functions. + +\starttabulate[|Tl|Tl|] +\HL +\NC sinh(x) \NC asinh(x) \NC \NR +\NC cosh(x) \NC acosh(x) \NC \NR +\HL +\stoptabulate + +We end with a few additional string converters. + +\starttabulate[|Tl|l|] +\HL +\NC ddecimal x \NC decimal representation of a pair \NC \NR +\NC dddecimal x \NC decimal representation of a color \NC \NR +\NC condition x \NC string representation of a boolean \NC \NR +\HL +\stoptabulate + +\stopsection + +\startsection[title={Grids}] + +\index{grids} +\index{axis} + +Some day you may want to use \METAPOST\ to draw a function like graphic. In the +regular \TEX\ distributions you will find a module \type {graph.mp} that provides +many ways to accomplish this. For the moment, \METAFUN\ does not provide advanced +features with respect to drawing functions, so this section will be relatively +short. + +When drawing a functions (for educational purposes) we need to draw a couple of +axis or a grid as well as a shape. Along the axis we can put labels. For this we +can use the \METAPOST\ package \type {format.mp}, but this does not integrate +that well into the way \METAFUN\ deals with text typeset by \TEX. + +For those who love dirty tricks and clever macros, close reading of the code in +\type {format.mp} may be worthwhile. The format macros in there use \TEX\ to +typeset the core components of a number, and use the dimensions of those +components to compose combinations of signs, numbers and superscripts. + +In \METAFUN\ we have the module \type {mp-form.mp} which contains most of the +code in \type {format.mp} but in a form that is a bit more suited for fine +tuning. This permits us to use either the composition method, or to fall back on +the \type {textext} method that is part of \METAFUN. That way we can also handle +fonts that have digits with different dimensions. Another \quote {change} +concerns the pattern separator. Instead of a \type {%} we use \type {@}; you can +choose to set another separator, but for embedded definitions \type {%} is +definitely a bad choice because \TEX\ sees it as a comment and ignores everything +following it. + +\startbuffer[grd] +drawoptions(withpen pencircle scaled 1pt withcolor .625yellow) ; + +draw hlingrid(0, 10, 1, 3cm, 3cm) ; +draw vlingrid(0, 10, 1, 3cm, 3cm) ; + +draw hlingrid(0, 10, 1, 3cm, 3cm) shifted ( 3.5cm,0) ; +draw vloggrid(0, 10, 1, 3cm, 3cm) shifted ( 3.5cm,0) ; + +draw hloggrid(0, 10, 1, 3cm, 3cm) shifted ( 7.0cm,0) ; +draw vlingrid(0, 10, 1, 3cm, 3cm) shifted ( 7.0cm,0) ; + +draw hloggrid(0, 10, 1, 3cm, 3cm) shifted (10.5cm,0) ; +draw vloggrid(0, 10, 1, 3cm, 3cm) shifted (10.5cm,0) ; +\stopbuffer + +\typebuffer[grd] + +\startlinecorrection[blank] +\processMPbuffer[grd] +\stoplinecorrection + +\startbuffer[grd] +drawoptions(withpen pencircle scaled 1pt withcolor .625yellow) ; + +draw hlingrid(0, 10, 1, 3cm, 3cm) slanted .5 ; +draw vlingrid(0, 10, 1, 3cm, 3cm) slanted .5 ; +\stopbuffer + +\typebuffer[grd] + +\startlinecorrection[blank] +\processMPbuffer[grd] +\stoplinecorrection + +Using macros like these often involves a bit of trial and error. The arguments to +these macros are as follows: + +\starttyping +hlingrid (Min, Max, Step, Length, Width) +vlingrid (Min, Max, Step, Length, Height) +hloggrid (Min, Max, Step, Length, Width) +vloggrid (Min, Max, Step, Length, Height) +\stoptyping + +The macros take the following text upto the semi||colon into account and return a +picture. We will now apply this knowledge to a more meaningful example. First we +draw a grid. + +You can use the grid drawing macros to produce your own paper, for instance using +the following mixed \TEX ||\METAFUN\ code: + +\typebuffer[gridpage] + +This produces a page (as in \in {figure} [fig:gridpage]) with a metric grid. If +you're hooked to the inch, you can set \type {unit := 1in}. If you want to +process this code, you need to wrap it into the normal document producing +commands: + +\starttyping +\setupcolors[state=start] + +\starttext + ... definitions ... +\stoptext +\stoptyping + +\placefigure + [page] + [fig:gridpage] + {Quick and dirty grid paper.} + {\typesetfile + [mfun-901.tex] + [page=1,height=.9\textheight]} + +\stopsection + +\startsection[title={Drawing functions}] + +Today there are powerful tools to draw functions on grids, but for simple +functions you can comfortably use \METAPOST. Let's first draw a simple +log||linear grid. + +\startbuffer[grd] +drawoptions(withpen pencircle scaled .25pt withcolor .5white) ; + +draw hlingrid (0, 20, .2, 20cm, 10cm) ; +draw vloggrid (0, 10, .5, 10cm, 20cm) ; + +drawoptions(withpen pencircle scaled .50pt) ; + +draw hlingrid (0, 20, 1, 20cm, 10cm) ; +draw vloggrid (0, 10, 1, 10cm, 20cm) ; +\stopbuffer + +\typebuffer[grd] + +To this grid we add some labels: + +\startbuffer[txt] +fmt_pictures := false ; % use TeX as formatting engine +textextoffset := ExHeight ; % a variable set by ConTeXt + +draw hlintext.lft(0, 20, 5, 20cm, "@3e") ; +draw vlogtext.bot(0, 10, 9, 10cm, "@3e") ; +\stopbuffer + +\typebuffer[txt] + +The arguments to the text placement macros are similar to the ones for drawing +the axes. Here we provide a format string. + +\starttyping +hlintext (Min, Max, Step, Length, Format) +vlintext (Min, Max, Step, Length, Format) +hlogtext (Min, Max, Step, Length, Format) +vlogtext (Min, Max, Step, Length, Format) +\stoptyping + +When drawing a smooth function related curve, you need to provide enough sample +points. The \type {function} macro will generate them for you, but you need to +make sure that for instance the maximum and minimum values are part of the +generated series of points. Also, a smooth curve is not always the right curve. +Therefore we provide three drawing modes: + +\starttabulate[|cT|l|] +\HL +\NC \bf method \NC \bf result \NC \NR +\HL +\NC 1 \NC a punked curve, drawn using \type {--} \NC \NR +\NC 2 \NC a smooth curve, drawn using \type {..} \NC \NR +\NC 3 \NC a tight curve, drawn using \type {...} \NC \NR +\HL +\stoptabulate + +If method~2 or~3 do not give the desired outcome, you can try a smaller step +combined with method~1. + +\startbuffer[log] +draw + function(1,"log(x)","x",1,10,1) xyscaled (10cm,2cm) + withpen pencircle scaled 5mm withcolor transparent(1,.5,yellow) ; + +draw + function(2,".5log(x)","x",1,10,1) xyscaled (10cm,2cm) + withpen pencircle scaled 5mm withcolor transparent(1,.5,blue) ; +\stopbuffer + +\typebuffer[log] + +\placefigure + [page] + {An example of a graphic with labels along the axes.} + {\doifmodeelse{screen} + {\scale[height=.85\textheight]{\processMPbuffer[grd,txt,log]}} + {\processMPbuffer[grd,txt,log]}} + +The first argument to the \type {function} macro specifies the drawing method. +The last three arguments are the start value, end value and step. The second and +third argument specify the function to be drawn. In this case the pairs \type +{(x,x)} and \type {(.5log(x),x)} are calculated. + +\startbuffer[gon] +textextoffset := ExHeight ; + +drawoptions(withpen pencircle scaled .50pt) ; + +draw hlingrid(-10, 10, 1, 10cm, 10cm) ; +draw vlingrid( 0, 20, 1, 10cm, 20cm) shifted (0,-10cm) ; + +drawoptions() ; + +draw + function(2,"x","sind(x)",0,360,10) xyscaled (1cm/36,10cm) + withpen pencircle scaled 5mm withcolor transparent(1,.5,blue) ; + +draw + function(2,"x","sin(x*pi)",0,epsed(2),.1) xyscaled (10cm/2,5cm) + withpen pencircle scaled 5mm withcolor transparent(1,.5,yellow) ; + +draw + function(2,"x","cosd(x)",0,360,10) xyscaled (1cm/36,10cm) + withpen pencircle scaled 5mm withcolor transparent(1,.5,red) ; + +draw + function(2,"x","cos(x*pi)",0,epsed(2),.1) xyscaled (10cm/2,5cm) + withpen pencircle scaled 5mm withcolor transparent(1,.5,green) ; +\stopbuffer + +\typebuffer[gon] + +\placefigure + [page] + {By using transparent colors, we don't have to calculate + and mark the common points: they already stand out.} + {\doifmodeelse{screen} + {\scale[height=.85\textheight]{\processMPbuffer[gon]}} + {\processMPbuffer[gon]}} + +In this example we draw sinus and cosine functions using degrees and radians. In +the case of radians the end points are not calculated due to rounding errors. In +such case you can use the \type {epsed} value, which gives slightly more +playroom. + +\startbuffer[mix] +draw function (1, "x", "sin(2x)" , 1, 10, .01) scaled 1.5cm + withpen pencircle scaled 1mm withcolor transparent(1,.5,red) ; +draw function (1, "x", "sin(2x*x)" , 1, 10, .01) scaled 1.5cm + withpen pencircle scaled 1mm withcolor transparent(1,.5,green) ; +draw function (1, "x", "sin(2x*x+x)", 1, 10, .01) scaled 1.5cm + withpen pencircle scaled 1mm withcolor transparent(1,.5,blue) ; +\stopbuffer + +\typebuffer[mix] + +Of course you can do without a grid. The next example demonstrates a nice +application of transparencies. + +\startlinecorrection[blank] +\processMPbuffer[mix] +\stoplinecorrection + +If we use the \type {exclusion} method for the transparencies, combined with no +transparency, we get the following alternative. + +\startbuffer[mix] +draw function (2, "x", "sin(x)" , 0, 2pi, pi/40) scaled 2cm + withpen pencircle scaled 5mm withcolor transparent("exclusion",1,red) ; +draw function (2, "x", "sin(2x)", 0, 2pi, pi/40) scaled 2cm + withpen pencircle scaled 5mm withcolor transparent("exclusion",1,green) ; +draw function (2, "x", "sin(3x)", 0, 2pi, pi/40) scaled 2cm + withpen pencircle scaled 5mm withcolor transparent("exclusion",1,blue) ; +\stopbuffer + +\typebuffer[mix] + +\startlinecorrection[blank] +\processMPbuffer[mix,wipe] +\stoplinecorrection + +The next alternative uses a larger step, and as a result (in drawing mode~2) +gives worse results. (Without the \type {epsed} it would have looked even worse +in the end points. + + \startbuffer[mix] +draw function (2, "x", "sin(x)" , 0, epsed(2pi), pi/10) scaled 2cm + withpen pencircle scaled 5mm withcolor transparent("exclusion",1,red) ; +draw function (2, "x", "sin(2x)", 0, epsed(2pi), pi/10) scaled 2cm + withpen pencircle scaled 5mm withcolor transparent("exclusion",1,green) ; +draw function (2, "x", "sin(3x)", 0, epsed(2pi), pi/10) scaled 2cm + withpen pencircle scaled 5mm withcolor transparent("exclusion",1,blue) ; +\stopbuffer + +\typebuffer[mix] + +\startlinecorrection[blank] +\processMPbuffer[mix,wipe] +\stoplinecorrection + +There are enough applications out there to draw nice functions, like gnuplot for +which Mojca Miklavec made a backend that works well with \CONTEXT. Nevertheless +it can be illustrative to explore the possibilities of the \CONTEXT, \LUATEX, +\METAPOST\ combination using functions. + +First of all you can use \LUA\ to make paths and this is used in some of the +debugging and tracing options that come with \CONTEXT. For instance, if you +process a document with + +\starttyping +context --timing yourdoc.tex +\stoptyping + +then you can afterwards process a file that is generated while processing this +document: + +\starttyping +context --extras timing yourdoc +\stoptyping + +This will give you a document with graphics that show where \LUATEX\ spent its +time on. Of course these graphics are generated with \METAPOST. + +There are a few helpers built in (and more might follow). For example: + +\startbuffer +draw + \ctxlua { + metapost.metafun.topath { + { x=1, y=1 }, + { x=1, y=3 }, + { 4, 1}, + "cycle" + } + } + xysized(4cm,3cm) + withpen pencircle scaled 1mm + withcolor .625 red ; +\stopbuffer + +\typebuffer + +The \type {topath} function takes a table of points or strings. + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +You can pass a connector so + +\startbuffer +draw + \ctxlua { + metapost.metafun.topath ( + { + { x=1, y=1 }, + { x=1, y=3 }, + { 4, 1 }, + "cycle" + }, + "--" + ) + } + xysized(4cm,3cm) + withpen pencircle scaled 1mm + withcolor .625 red ; +\stopbuffer + +\typebuffer + +gives: + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +Writing such \LUA\ functions is no big deal. For instance we have available: + +\starttyping +function metapost.metafun.interpolate(f,b,e,s,c) + tex.write("(") + for i=b,e,(e-b)/s do + local d = loadstring ( + string.formatters["return function(x) return %s end"](f) + ) + if d then + d = d() + if i > b then + tex.write(c or "...") + end + tex.write(string.formatters["(%F,%F)"](i,d(i))) + end + end + tex.write(")") +end +\stoptyping + +An example of usage is: + +\startbuffer +draw + \ctxlua{metapost.metafun.interpolate( + "math.sin(x^2+2*x+math.sqrt(math.abs(x)))", + -math.pi/2,math.pi/2,100 + )} + xysized(6cm,3cm) + withpen pencircle scaled 1mm + withcolor .625 red ; +\stopbuffer + +\typebuffer + +And indeed we get some drawing: + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +Let's see what happens when we use less accuracy and a different connector: + +\startbuffer +draw + \ctxlua{metapost.metafun.interpolate( + "math.sin(x^2+2*x+math.sqrt(math.abs(x)))", + -math.pi/2,math.pi/2,10,"--" + )} + xysized(6cm,3cm) + withpen pencircle scaled 1mm + withcolor .625 red ; +\stopbuffer + +\typebuffer + +Now we get: + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +Of course we could extend this \LUA\ function with all kind of options and we +might even do that when we need it. + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/metafun/metafun-gadgets.tex b/doc/context/sources/general/manuals/metafun/metafun-gadgets.tex new file mode 100644 index 000000000..9010fc403 --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/metafun-gadgets.tex @@ -0,0 +1,548 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\startcomponent metafun-gadgets + +\environment metafun-environment + +\startchapter[title={Shapes, symbols and buttons}] + +\startintro + +One can use \METAPOST\ to define symbols and enhance buttons. Here we introduce +some of the gadgets that come with \CONTEXT, as well as explain how to integrate +such gadgets yourself. + +\stopintro + +\startsection[title={Interfacing to \TEX}] + +\index {interfacing} + +\startbuffer[a] +\setupMPvariables + [EnglishRule] + [height=1ex, + width=\availablehsize, + color=darkgray] + +\startuniqueMPgraphic{EnglishRule}{height,width,color} + numeric height ; height = \MPvar{height} ; + x1 = 0 ; x3 = \MPvar{width} ; x2 = x4 = .5x3 ; + y1 = y3 = 0 ; y2 := -y4 = height/2 ; + fill z1 .. z2 .. z3 & z3 .. z4 .. z1 & cycle + withcolor \MPvar{color} ; +\stopuniqueMPgraphic +\stopbuffer + +\startbuffer[b] +\defineblank + [EnglishRule] + [medium] + +\unexpanded\def\EnglishRule + {\start + \dontcomplain + \startlinecorrection[EnglishRule] + \noindent \reuseMPgraphic{EnglishRule} + \stoplinecorrection + \stop} +\stopbuffer + +\getbuffer[a,b] + +In the early days of \METAPOST\ support in \CONTEXT, Tobias Burnus asked me if it +was possible to define English rules. What exactly does an english rule look +like? Here is one: + +\EnglishRule + +As you can see, such a rule has to adapt itself to the current text width, +normally \type {\hsize} in \TEX, or on request \type {\availablehsize} in +\CONTEXT. We need to set the height to a reasonable size, related to the font +size, and we also need to take care of proper spacing. Of course we want to run +\METAPOST\ as less times as possible, so we need to use unique graphics. Let's +start with the graphic. + +\typebuffer[a] + +As you can see, we pass two arguments to the graphic definition. The first +argument is the name, the second argument is a comma separated list of variables. +This list serves two purposes. First this list is used to create a unique profile +for the graphic. This means that when we change the value of a variable, a new +graphic is generated that reflects the change. A second purpose of the list is to +convert \TEX\ data structures into \METAPOST\ ones, especially dimensions and +colors. The graphic itself is not that spectacular. We use \type {&} because we +don't want smooth connections. + +\typebuffer[b] + +When setting the variables, we used \type {\availablehsize}. We need to use \type +{\noindent}, a rather familiar \TEX\ primitive, that we use here to start a non +indented paragraph, being the graphic. The line correction is needed to get the +spacing around the rule (graphic) right. We pass a blank skip identifier that is +mapped to a convenient medium skip. + +\startbuffer[c] +Why is this called an English line? + +\startnarrower + \EnglishRule + Is it because they cannot draw a straight one? This could be true + after a few strong beers, but then, how do Germans draw a line? + \EnglishRule +\stopnarrower +\stopbuffer + +\typebuffer[c] + +As expected, the rule adapts itself to the current width of the text. The height +of the rule in the middle matches the height of a character with no ascenders and +descenders. + +\getbuffer[c] + +\stopsection + +\startsection[title={Random graphics}] + +\index{randomization} + +\startbuffer[a] +\startuseMPgraphic{fuzzycount} + begingroup + save height, vstep, hsize, span, drift, d, cp ; + height := 3/ 4 * \the \bodyfontsize * \currentfontscale ; + span := 1/ 3 * height ; + drift := 1/10 * height ; + hsize := \the\hsize ; + vstep := \the\lineheight ; + xmax := hsize div 5span ; + pickup pencircle scaled (1/12 * height) ; + def d = (uniformdeviate drift) enddef ; + for i := 1 upto \MPvar{n} : + xpos := ((i-1) mod (5*xmax))*span ; + ypos := ((i-1) div (5*xmax))*vstep ; + draw + if (i mod 5)=0 : ((-d-4.5span,d)--(+d-0.5span,height-d)) + else : ((-d,+d)--(+d,height-d)) fi + shifted (xpos,-ypos+d-drift) ; + endfor; + picture cp ; cp := currentpicture ; + if (ypart ulcorner cp - ypart llcorner cp) <= vstep : + setbounds currentpicture to + (llcorner cp shifted (0,-ypart llcorner cp) -- + lrcorner cp shifted (0,-ypart lrcorner cp) -- + urcorner cp -- ulcorner cp -- cycle) ; + fi + endgroup ; +\stopuseMPgraphic +\stopbuffer + +\startbuffer[b] +\useMPgraphic{fuzzycount}{n=1001} +\stopbuffer + +Given enough time and paper, we can probably give you some + +\startlinecorrection[blank] +\getbuffer[a,b] +\stoplinecorrection + +reasons why \METAPOST\ is fun. To mention a few: you can enhance the layout with +graphic ornaments, you can tune your graphics at runtime, and simple high quality +graphics can be very effective. + +\startbuffer[c] +\startuseMPgraphic{fuzzycount} + begingroup + save height, span, drift, d, cp ; + height := 3/ 5 * \baselinedistance ; + span := 1/ 3 * height ; + drift := 1/10 * height ; + pickup pencircle scaled (1/12 * height) ; + def d = (uniformdeviate drift) enddef ; + for i := 1 upto \MPvar{n} : + draw + if (i mod 5)=0 : ((-d-4.5span,d)--(+d-0.5span,height-d)) + else : ((-d,+d)--(+d,height-d)) fi + shifted (span*i,d-drift) ; + endfor; + picture cp ; cp := currentpicture ; % for readability + setbounds currentpicture to + (llcorner cp shifted (0,-ypart llcorner cp) -- + lrcorner cp shifted (0,-ypart lrcorner cp) -- + urcorner cp -- ulcorner cp -- cycle) ; + endgroup ; +\stopuseMPgraphic +\stopbuffer + +\startbuffer[d] +\setupMPvariables[fuzzycount][n=10] +\stopbuffer + +\getbuffer[c,d] + +The previous graphics draws exactly 1001 lines in a scratch||numbers||in||a||wall +fashion. In 1998, the \NTG\ did a survey among its members, and in the report, we +used this fuzzy counter to enhance the rather dull tables. + +\startbuffer +\starttabulate[|l|c|l|] +\HL +\NC system \NC \% \NC \# users \NC\NR +\HL +\NC Atari \NC 10.4 \NC \useMPgraphic{fuzzycount}{n=11} \NC\NR +\NC MSDOS \NC 49.1 \NC \useMPgraphic{fuzzycount}{n=52} \NC\NR +\NC OS/2 \NC ~9.4 \NC \useMPgraphic{fuzzycount}{n=10} \NC\NR +\NC MacOS \NC ~5.7 \NC \useMPgraphic{fuzzycount}{n= 6} \NC\NR +\NC UNIX \NC 51.9 \NC \useMPgraphic{fuzzycount}{n=55} \NC\NR +\NC WINDOWS \NC 64.2 \NC \useMPgraphic{fuzzycount}{n=68} \NC\NR +\HL +\stoptabulate +\stopbuffer + +\placetable + [here][tab:fuzzy] + {Operating system (n=106).}{\getbuffer} + +\in {Table} [tab:fuzzy] demonstrates how scratch numbers can be used. An +interesting side effect is that when you look long enough to these kind of +graphics, it looks like the lines are no longer horizontal. This table is defined +as follows: + +\typebuffer + +You will notice that we pass a variable to the graphic using a second argument. +We can access this variable with \type {\MPvar}. The graphic is defined as usable +graphic, because we want to generate a unique random one each time. + +\typebuffer[c] + +The core of the macro is the \type {for} loop. Within this loop, we draw groups +of four plus one lines. The draw path's look a bit complicated, but this has to +do with the fact that a \type {mod} returns $0-4$ while we like to deal with +$1-5$. + +The height adapts itself to the height of the line. The bounding box correction +at the end ensures that the baseline is consistent and that the random vertical +offsets fall below the baseline. + +Because we want to be sure that \type {n} has a value, we preset it by saying: + +\typebuffer[d] + +In the table, it makes sense to adapt the drawing to the lineheight, but a more +general solution is to adapt the height to the fontsize. + +\starttyping +height := 3/ 4 * \the \bodyfontsize * \currentfontscale ; +\stoptyping + +\getbuffer[a] + +In the table we called the graphic directly, but how about making it available as +a conversion macro? In \CONTEXT\ this is not that hard: + +\startbuffer +\def\fuzzycount#1{{\tx\useMPgraphic{fuzzycount}{n=#1}}} +\defineconversion[fuzzy][\fuzzycount] +\stopbuffer + +\typebuffer \getbuffer + +Because such a counter should not be that large, we use \type {\tx} to switch to +a smaller font. This also demonstrates how the graphic adapts itself to the font +size. + +We can now use this conversion for instance in an itemize. To save space we use +three columns and no white space between the lines. The \type {2*broad} directive +makes sure that we have enough room for the number. + +\startbuffer +\startitemize[fuzzy,pack,2*broad,columns,three] +\item one \item two \item three +\item four \item five \item six +\item seven \item eight \item nine +\stopitemize +\stopbuffer + +\getbuffer + +\typebuffer + +A careful reader will have noticed that the previous definition of the fuzzy +counter drawing is not suited to generate the graphics we started with. + +\typebuffer[b] + +This time we want to limit the width to the current \type {\hsize}. We only need +to add a few lines of code. Watch how we don't recalculate the bounding box when +more lines are used. + +\typebuffer[a] + +\stopsection + +\startsection[title={Graphic variables}] + +\index{graphics+variables} +\index{variables} + +In the previous sections we have seen that we can pass information to the graphic +by means of variables. How exactly does this mechanism work? + +\startbuffer[def] +\setupMPvariables[smile][type=1,height=1.25ex,color=darkred] + +\startuniqueMPgraphic{smile}{type,height,color} + numeric size ; size := \MPvar{height} ; + drawoptions(withcolor \MPvar{color}) ; + pickup pencircle xscaled (size/6) yscaled (size/12) ; + draw halfcircle rotated -90 scaled size ; + pickup pencircle scaled (size/4) ; + if \MPvar{type}=1 : + for i=-1,+1 : draw origin shifted (0,i*size/4) ; endfor ; + elseif \MPvar{type}=2 : + for i=-1,+1 : draw origin shifted (-size/2,i*size/4) ; endfor ; + pickup pencircle scaled (size/6) ; + draw (size/4,0) -- (-size/4,0) ; + fi ; +\stopuniqueMPgraphic +\stopbuffer + +\startbuffer[sym] +\definesymbol[smile] [\uniqueMPgraphic{smile}{type=1}] +\definesymbol[smilemore][\uniqueMPgraphic{smile}{type=2}] +\stopbuffer + +\startbuffer[exa] +Say it with a \symbol [smile]\ or maybe even a \symbol +[smilemore], although seeing too many \dorecurse {10} +{\symbol [smile]\ } \unskip in one text may make you cry. +\stopbuffer + +\getbuffer[def,sym] + +A nice application of setting up variables for a specific graphic (or class of +graphics) is the following. In an email message the author can express his own or +the readers expected emotions with so called smilies like: \symbol [smile]. If +you want them in print, you can revert to combinations of characters in a font, +but as a \TEX\ user you may want to include nicer graphics. + +A convenient way to implement these is to make them into symbols, one reason +being that in that case they will adapt themselves to the current font size. + +\typebuffer[exa] \getbuffer[exa] + +Because we want an efficient implementation, we will use unique graphics, because +these will only be generated when the circumstances change. + +\typebuffer[sym] + +The definition itself then becomes: + +\typebuffer[def] + +We can now change some characteristics of the smilies without the need to +redefine the graphic. + +\startbuffer[set] +\setupMPvariables[smile][height=1ex,color=darkred] +\stopbuffer + +\typebuffer[set] + +\getbuffer[set,exa] + +In order to keep the smilies unique there is some magic involved, watch the +second argument in the next line: + +\starttyping +\startuniqueMPgraphic{smile}{type,height,color} +\stoptyping + +Because unique graphics often are used in backgrounds, its uniqueness is +determined by the overlay characteristics. In our case however the uniqueness is +determined by the smilies type, height and color. By explicitly specifying these, +we make sure that they count in the creation of the uniqueness stamp. + +\startbuffer[exa] +\midaligned{\switchtobodyfont[60pt]\symbol[smile]} +\stopbuffer + +\typebuffer[exa] + +Because we use the ex||height, the previous call works as expected. + +\startlinecorrection[blank] +\getbuffer[exa] +\stoplinecorrection + +\stopsection + +\startsection[title={Shape libraries}] + +\index{graphics+libraries} + +Unfortunately it takes some effort to define graphics, attach them to an overlay, +and invoke the background. However, the good news is that since in many cases we +want a consistent layout, we only have to do it once. The next table has some +hashed backgrounds. (More information about how to define tables can be found in +the \CONTEXT\ documentation and Up||To||Date documents.) + +\startbuffer +\bTABLE[frame=off,meta:hash:linecolor=darkyellow,offset=3ex] + \bTR + \bTD[background=meta:hash:right] right \eTD + \bTD[background=meta:hash:left] left \eTD + \bTD[background=meta:hash:horizontal] horizontal \eTD + \bTD[background=meta:hash:vertical] vertical \eTD + \eTR +\eTABLE +\stopbuffer + +\getbuffer[shape-a,shape-b,shape-c] + +\placetable + {A hashed table.} + {\getbuffer} + +This table is defined as: + +\typebuffer + +The graphics themselves are defined in a \METAPOST\ module. In this particular +example, the macro \type {some_hash} is defined in the file \type {mp-back.mp}. +This macro takes six arguments: + +\starttyping +some_hash (width, height, linewidth, linecolor, angle, gap) ; +\stoptyping + +Because we don't want to define a specific overlay for each color and linewidth, +we will use variables in the definition of the unique graphic. + +\typebuffer[shape-a] + +These variables are preset using \type {\setupMPvariables}: + +\typebuffer[shape-b] + +The last step in this process is to define the different +alternatives as overlays: + +\typebuffer[shape-c] + +As we can see in the definition of the table, we can pass settings to the \type +{\bTABLE} command. Actually, we can pass such settings to each command that +supports backgrounds, or more precisely \type {\framed}. \in {Table} [tab:hashes] +is for instance defined as: + +\startbuffer +\bTABLE[frame=off,meta:hash:linewidth=.4pt,align=middle,offset=2ex] + \bTR + \bTD[background={meta:hash:left,meta:hash:right}, + meta:hash:linecolor=darkyellow] + left \par \& \par right \eTD + \bTD[background={meta:hash:horizontal,meta:hash:vertical}, + meta:hash:linecolor=darkred] + horizontal \par \& \par vertical \eTD + \eTR +\eTABLE +\stopbuffer + +\typebuffer + +The long names are somewhat cumbersome, but in that way we can prevent name +clashes. Also, since the \METAPOST\ interface is english, the variables are also +english. + +\placetable + [here][tab:hashes] + {A double hashed table.} + {\getbuffer} + +\stopsection + +\startsection[title={Symbol collections}] + +\index{graphics+symbols} +\index{symbols} + +In \CONTEXT, a symbol can be defined without much coding. The advantage of using +symbols is that you can redefine them depending on the situation. So, + +\starttyping +\definesymbol [yes] [\em Yes!] +\stoptyping + +creates a symbol, that lets \type {\symbol[yes]} expand into {\em Yes!} Since +nearly anything can be a symbol, we can also say: + +\starttyping +\definesymbol [yes] [\mathematics{\star}] +\stoptyping + +or even the already defined symbol \symbol[star], by saying: + +\starttyping +\definesymbol [yes] [{\symbol[star]}] +\stoptyping + +It may be clear that we can use a graphic as well: + +\typebuffer[symb-c] + +Since we have collected some nice buttons in a \METAPOST\ file already, we can +use a rather simple definition: + +\typebuffer[symb-a] + +This leaves a few settings: + +\typebuffer[symb-b] + +These symbols are collected in \in {table} [tab:symbols], and are called up with +the \CONTEXT\ commands like \type {\symbol[menu:left]}. If needed, we can collect +these button symbols in a so called symbol set, which permits us to instantly +switch between sets with similar symbols. + +\startbuffer +\bTABLE[frame=off,width=36pt,align=middle] + \bTR \bTD \dontleavehmode \symbol[menu:left] \eTD + \bTD \dontleavehmode \symbol[menu:right] \eTD + \bTD \dontleavehmode \symbol[menu:list] \eTD + \bTD \dontleavehmode \symbol[menu:index] \eTD + \bTD \dontleavehmode \symbol[menu:person] \eTD + \bTD \dontleavehmode \symbol[menu:stop] \eTD + \bTD \dontleavehmode \symbol[menu:info] \eTD + \bTD \dontleavehmode \symbol[menu:down] \eTD + \bTD \dontleavehmode \symbol[menu:up] \eTD + \bTD \dontleavehmode \symbol[menu:print] \eTD \eTR + \bTR \bTD left \eTD + \bTD right \eTD + \bTD list \eTD + \bTD index \eTD + \bTD person \eTD + \bTD stop \eTD + \bTD info \eTD + \bTD down \eTD + \bTD up \eTD + \bTD print \eTD \eTR +\eTABLE +\stopbuffer + +\getbuffer[symb-a,symb-b,symb-c] + +\placetable + [here][tab:symbols] + {A collection of button symbols.} + {\getbuffer} + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/metafun/metafun-graphics.tex b/doc/context/sources/general/manuals/metafun/metafun-graphics.tex new file mode 100644 index 000000000..79c5df0df --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/metafun-graphics.tex @@ -0,0 +1,21 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\startcomponent metafun-graphics + +\environment metafun-environment + +\startchapter[title={Example graphics}] + +\startintro + +In this chapter we will show some of the graphics that we made the last few years +using \METAPOST. They give an impression of what kind of non||mathematical +drawings can be made. + +\stopintro + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/metafun/metafun-index.tex b/doc/context/sources/general/manuals/metafun/metafun-index.tex new file mode 100644 index 000000000..8be313d85 --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/metafun-index.tex @@ -0,0 +1,25 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\startcomponent metafun-index + +\environment metafun-environment + +\startchapter[reference=index,title={Index}] + + \startcolumns + \placeregister[index] + \stopcolumns + +\stopchapter + +% \startchapter[reference=commands,title={Commands}] +% +% \startcolumns +% \placeregister[command] +% \stopcolumns +% +% \stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/metafun/metafun-introduction.tex b/doc/context/sources/general/manuals/metafun/metafun-introduction.tex new file mode 100644 index 000000000..b519055c0 --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/metafun-introduction.tex @@ -0,0 +1,101 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\startcomponent metafun-introduction + +\environment metafun-environment + +\starttitle[title={Introduction}] + +This document is about \METAPOST\ and \TEX. The former is a graphic programming +language, the latter a typographic programming language. However, in this +document we will not focus on real programming, but more on how we can interface +between those two languages. We will do so by using \CONTEXT, a macro package +written in \TEX, in which support for \METAPOST\ is integrated in the core. The +\TEX\ macros are integrated in \CONTEXT, and the \METAPOST\ macros are bundled in +\METAFUN. + +When Donald Knuth wrote his typographical programming language \TEX\ he was in +need for fonts, especially mathematical fonts. So, as a side track, he started +writing \METAFONT, a graphical language. When you read between the lines in the +\METAFONT\ book and the source code, the name John Hobby is mentioned alongside +complicated formulas. It will be no surprise then, that, since he was tightly +involved in the development of \METAFONT, after a few years his \METAPOST\ showed +up. + +While its ancestor \METAFONT\ was originally targeted at designing fonts, +\METAPOST\ is more oriented to drawing graphics as used in scientific +publications. Since \METAFONT\ produced bitmap output, some of its operators make +use of this fact. \METAPOST\ on the other hand produces \POSTSCRIPT\ code, which +means that it has some features not present in \METAFONT\ and vice versa. + +With \METAFUN\ I will demonstrate that \METAPOST\ can also be used, or misused, +for less technical drawing purposes. We will see that \METAPOST\ can fill in some +gaps in \TEX, especially its lack of graphic capabilities. We will demonstrate +that graphics can make a document more attractive, even if it is processed in a +batch processing system like \TEX. Most of all, we will see that embedding +\METAPOST\ definitions in the \TEX\ source enables a smooth communication between +both programs. + +The best starting point for using \METAPOST\ is the manual written by its author +John Hobby. You can find this manual at every main \TEX\ repository. Also, a copy +of the \METAFONT\ book from Donald Knuth is worth every cent, if only because it +will give you the feeling that many years of graphical fun lays ahead. + +In this \METAFUN\ manual we will demonstrate how you can embed graphics in a +\TEX\ document, but we will also introduce most of the features of \METAPOST. For +this reason you will see a lot of \METAPOST\ code. For sure there are better +methods to solve problems, but I have tried to demonstrate different methods and +techniques as much as possible. + +I started using \METAPOST\ long after I started using \TEX, and I never regret +it. Although I like \TEX\ very much, I must admit that sometimes using \METAPOST\ +is even more fun. Therefore, before we start exploring both in depth, I want to +thank their creators, Donald Knuth and John Hobby, for providing me these +fabulous tools. Of course I also need to thank \THANH, for giving the \TEX\ +community \PDFTEX, as well as providing me the hooks I considered necessary for +implementing some of the features presented here. In the meantime Taco Hoekwater +has created the \METAPOST\ library so that it can be an integral component of +\LUATEX. After that happened, the program was extended to deal with more than one +number implementation: in addition to scaled integers we now can switch to floats +and arbitrary precision decimal or binary calculations. I myself prototyped a +simple but efficient \LUA\ script interface. With Luigi Scarso, who is now the +maintainer of \METAPOST, we keep improving the system, so who knows what will +show up next. + +I also want to thank David Arnold and Ton Otten for their fast proofreading, for +providing me useful input, and for testing the examples. Without David's patience +and help, this document would be far from perfect English and less complete. +Without Ton's help, many small typos would have gone unnoticed. + +In the second version of this manual the content was been adapted to \CONTEXT\ +\MKIV\ that uses \LUATEX\ and the built in \METAPOST\ library. In the meantime +some \LUA\ has been brought into the game, not only to help construct graphics, +but also as a communication channel. In the process some extra features have been +added and some interfacing has been upgraded. The third version of this document +deals with that too. It makes no sense to maintain compatibility with \CONTEXT\ +\MKII, but many examples can be used there as well. In the meantime most +\CONTEXT\ users have switched to \MKIV, so this is no real issue. In the fourth +update some new features are presented and the discussion of obsolete ones have +been removed. + +The fifth update describes the \MPIV\ version of \METAFUN\ which brings some more +and improved functionality. Some examples are inspired from questions by users and +examples that Alan Braslau, Luigi Scarso and I made when testing new features and +macros. Some examples can be rewritten in a more efficient way but are kept as +they are. Therefore this manual presents different ways to solve problems. +Hopefully this is not too confusing. Numerous examples can be found in the other +manuals and test suite. + +\blank[big,samepage] + +\startlines +Hans Hagen +Hasselt NL +\currentdate[month,year] +\stoplines + +\stoptitle + +\stopcomponent diff --git a/doc/context/sources/general/manuals/metafun/metafun-layout.tex b/doc/context/sources/general/manuals/metafun/metafun-layout.tex new file mode 100644 index 000000000..2be7e19ff --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/metafun-layout.tex @@ -0,0 +1,990 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\startcomponent metafun-layout + +\environment metafun-environment + +\startchapter[title={Enhancing the layout}] + +\startintro + +One of the most powerful and flexible commands of \CONTEXT\ is \type {\framed}. +We can use the background features of this command to invoke and position +graphics that adapt themselves to the current situation. Once understood, +overlays will become a natural part of the \CONTEXT\ users toolkit. + +\stopintro + +\startsection[title={Overlays}] + +\index{overlays} + +Many \CONTEXT\ commands support overlays. The term {\em overlay} is a bit +confusing, since such an overlay in most cases will lay under the text. However, +because there can be many layers on top of each other, the term suits its +purpose. + +When we want to put a \METAPOST\ graphic under some text, we go through a three +step process. First we define the graphic itself: + +\startbuffer +\startuniqueMPgraphic{demo circle} + path p ; + p := fullcircle xscaled \overlaywidth yscaled \overlayheight ; + fill p withcolor .85white ; + draw p withpen pencircle scaled 2pt withcolor .625red ; +\stopuniqueMPgraphic +\stopbuffer + +\typebuffer + +\getbuffer + +This graphic will adapt itself to the width and height of the overlay. Both \type +{\overlaywidth} and \type {\overlayheight} are macros that return a dimension +followed by a space. The next step is to register this graphic as an overlay. + +\startbuffer +\defineoverlay[demo circle][\uniqueMPgraphic{demo circle}] +\stopbuffer + +\typebuffer + +\getbuffer + +We can now use this overlay in any command that provides the \type {\framed} +functionality. Since this graphic is defined as unique, \CONTEXT\ will try to +reuse already calculated and embedded graphics when possible. + +\startbuffer +\framed[background=demo circle]{This text is overlayed.} +\stopbuffer + +\typebuffer + +The background can be set to \type {color}, \type {screen}, an overlay +identifier, like \typ {demo circle}, or a comma separated list of those. + +\startlinecorrection[blank] +\getbuffer +\stoplinecorrection + +The \type {\framed} command automatically draws a ruled box, which can be quite +useful when debugging a graphic. However, in this case we want to turn the frame +off. + +\startbuffer +\framed + [background=demo circle,frame=off] + {This text is overlayed.} +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\getbuffer +\stoplinecorrection + +In this case, it would have made sense to either set the \type {offset} to a +larger value, or to set \type {backgroundoffset}. In the latter case, the ellipse +is positioned outside the frame. + +The difference between the three offsets \type {offset}, \type {frameoffset} and +\type {backgroundoffset} is demonstrated in \in {figure} [fig:offsets]. While the +\type {offset} is added to the (natural or specified) dimensions of the content +of the box, the other two are applied to the frame and background and don't add +to the dimensions. + +In the first row we only set the \type {offset}, while in the second row, the +(text) offset is set to \type {3pt}. When not specified, the \type {offset} has a +comfortable default value of \type {.25ex} (some 25\% of the height of an~x). + +\startbuffer +\setupframed + [width=.3\textwidth, + background=demo circle] +\startcombination[3*3] + {\framed[offset=none] {\TeX}} {\tt offset=none} + {\framed[offset=overlay] {\TeX}} {\tt offset=overlay} + {\framed[offset=0pt] {\TeX}} {\tt offset=0pt} + {\framed[offset=1pt] {\TeX}} {\tt offset=1pt} + {\framed[offset=2pt] {\TeX}} {\tt offset=2pt} + {\framed[offset=4pt] {\TeX}} {\tt offset=4pt} + {\framed[offset=3pt] {\TeX}} {\tt offset=3pt} + {\framed[frameoffset=3pt] {\TeX}} {\tt frameoffset=3pt} + {\framed[backgroundoffset=3pt]{\TeX}} {\tt backgroundoffset=3pt} +\stopcombination +\stopbuffer + +\typebuffer + +\placefigure + [here][fig:offsets] + {The three offsets.} + {\getbuffer} + +As the first row in \in {figure} [fig:offsets] demonstrates, instead of a value, +one can pass a keyword. The \type {overlay} keyword implies that there is no +offset at all and that the lines cover the content. With \type {none} the frame +is drawn tight around the content. When the offset is set to \type {0pt} or more, +the text is automatically set to at least the height of a line. You can turn this +feature off by saying \type {strut=off}. More details can be found in the +\CONTEXT\ manual. + +In \in {figure} [fig:all offsets] we have set {offset} to \type {3pt}, \type +{frameoffset} to \type {6pt} and \type {backgroundoffset} to \type {9pt}. Both +the frame and background offset are sort of imaginary, since they don't +contribute to the size of the box. + +\startbuffer +\ruledhbox + {\framed + [offset=3pt,frameoffset=6pt,backgroundoffset=9pt, + background=screen,backgroundscreen=.85] + {Welcome in the hall of frame!}} +\stopbuffer + +\typebuffer + +\placefigure + [here][fig:all offsets] + {The three offsets.} + {\getbuffer} + +\stopsection + +\startsection[title={Overlay variables}] + +The communication between \TEX\ and embedded \METAPOST\ graphics takes place by +means of some macros. + +\starttabulate[|l|p|] +\HL +\NC overlay status macro \NC meaning \NC \NR +\HL +\NC \tex {overlaywidth} \NC the width of the graphic, as + calculated from the actual + width and background offset \NC \NR +\NC \tex {overlayheight} \NC the height of the graphic, as + calculated from the actual + height, depth and background + offset \NC \NR +\NC \tex {overlaydepth} \NC the depth of the graphic, if + available \NC \NR +\NC \tex {overlaycolor} \NC the background color, if given \NC \NR +\NC \tex {overlaylinecolor} \NC the color of the frame \NC \NR +\NC \tex {overlaylinewidth} \NC the width of the frame \NC \NR +\HL +\stoptabulate + +The dimensions of the overlay are determined by dimensions of the background, +which normally is the natural size of a \type {\framed}. When a background offset +is specified, it is added to \type {overlayheight} and \type {overlaywidth}. + +Colors can be converted by \type {\MPcolor} and in addition to the macros +mentioned, you can use all macros that expand into a dimension or dimen register +prefixed by the \TEX\ primitive \type {\the} (this and other primitives are +explained in \quotation {The \TeX book}, by Donald Knuth). + +\stopsection + +\startsection[title={Stacking overlays}] + +A background can be a gray scale (\type {screen}), a color (\type {color}), a +previously defined overlay identifier, or any combination of these. The next +assignments are therefore valid: + +\starttyping +\framed[background=color,backgroundcolor=red]{...} +\framed[background=screen,backgroundscreen=.8]{...} +\framed[background=circle]{...} +\framed[background={color,cow},backgroundcolor=red]{...} +\framed[background={color,cow,grid},backgroundcolor=red]{...} +\stoptyping + +In the last three cases of course you have to define \type {circle}, \type {cow} +and \type {grid} as overlay. These items are packed in a comma separated list, +which has to be surrounded by \type {{}}. + +\stopsection + +\startsection[title={Foregrounds}] + +\startbuffer[a] +\startuniqueMPgraphic{backfore} + draw fullcircle + xscaled \overlaywidth yscaled \overlayheight + withpen pencircle scaled 2pt + withcolor .625yellow ; +\stopuniqueMPgraphic + +\defineoverlay[backfore][\uniqueMPgraphic{backfore}] +\stopbuffer + +\startbuffer[b] +\framed + [background=backfore,backgroundoffset=4pt] + {one, two, three, \unknown} +\stopbuffer + +\startbuffer[c] +\framed + [background={foreground,backfore},backgroundoffset=4pt] + {one, two, three, \unknown} +\stopbuffer + +The overlay system is actually a system of layers. Sometimes we are confronted +with a situation in which we want the text behind another layer. This can be +achieved by explicitly placing the foreground layer, as in \in {figure} +[fig:foreground]. + +\getbuffer[a] + +\placefigure + [here][fig:foreground] + {Foreground material moved backwards.} + {\setupframed[linewidth=1pt]% + \startcombination + {\getbuffer[b]} {frame on top layer} + {\getbuffer[c]} {frame on bottom layer} + \stopcombination} + +The graphic layer is defined as follows: + +\typebuffer[a] + +The two framed texts have a slightly different definition. The leftmost graphic +is defined as: + +\typebuffer[b] + +The rightmost graphic is specified as: + +\typebuffer[c] + +The current values of the frame color and frame width are passed to the overlay. +It often makes more sense to use colors defined at the document level, if only to +force consistency. + +\startbuffer +\startuniqueMPgraphic{super ellipse} + path p ; p := unitsquare + xscaled \overlaywidth yscaled \overlayheight + superellipsed .85 ; + pickup pencircle scaled \overlaylinewidth ; + fill p withcolor \MPcolor{\overlaycolor} ; + draw p withcolor \MPcolor{\overlaylinecolor} ; +\stopuniqueMPgraphic + +\defineoverlay[super ellipse][\uniqueMPgraphic{super ellipse}] +\stopbuffer + +\typebuffer \getbuffer + +This background demonstrates that a super ellipse is rather well suited as frame. + +\startbuffer +\framed + [background=super ellipse, + frame=off, + width=3cm, + align=middle, + framecolor=darkyellow, + rulethickness=2pt, + backgroundcolor=darkgray] + {\white This is a\\Super Ellipsed\\sentence.} +\stopbuffer + +\typebuffer + +Such a super ellipse looks quite nice and is a good candidate for backgrounds, +for which the superness should be at least~.85. + +\startlinecorrection[blank] +\getbuffer +\stoplinecorrection + +\stopsection + +\startsection[title={Typesetting graphics}] + +I have run into people who consider it kind of strange when you want to use \TEX\ +for non||mathematical typesetting. If you agree with them, you may skip this +section with your eyes closed. + +One of the \CONTEXT\ presentation styles (number 15, tagged as balls) stepwise +builds screens full of sentences, quotes or concepts, packages in balloons and +typesets them as a paragraph. We will demonstrate that \TEX\ can typeset graphics +using the following statement. + +% \let\processword\relax + +\startbuffer[lions] +\processwords{As you may know, \TEX's ambassador is a lion, while {\METAFONT} +is represented by a lioness. It is still unclear if they have a relationship, +but if so, and if a cub is born, may it enjoy \METAFUN.} +\stopbuffer + +\startquotation +\def\processwords#1{#1}\getbuffer[lions] +\stopquotation + +The low level \CONTEXT\ macro \type {\processwords} provides a mechanism to treat +the individual words of its argument. The macro is called as follows: + +\typebuffer[lions] + +In order to perform a task, you should also define a macro \type {\processword}, +which takes one argument. The previous quote was typeset with the following +definition in place: + +\starttyping +\def\processword#1{#1} +\stoptyping + +A slightly more complicated definition is the following: + +\startbuffer +\def\processword#1{\noindent\framed{#1}\space} +\stopbuffer + +\typebuffer \getbuffer + +We now get: + +\blank\getbuffer[lions]\blank + +If we can use \type {\framed}, we can also use backgrounds. + +\startbuffer +\def\processword#1% + {\noindent\framed[frame=off,background=lions]{#1} } +\stopbuffer + +\typebuffer \getbuffer + +We can add a supperellipsed frame using the following definition: + +\startbuffer +\startuniqueMPgraphic{lions a} + path p ; p := fullsquare + xyscaled (\overlaywidth,\overlayheight) superellipsed .85 ; + pickup pencircle scaled 1pt ; + fill p withcolor .850white ; draw p withcolor .625yellow ; +\stopuniqueMPgraphic + +\defineoverlay[lions][\uniqueMPgraphic{lions a}] +\stopbuffer + +\typebuffer \getbuffer + +\bgroup \blank \veryraggedright\getbuffer[lions]\unskip \blank \egroup + +\startbuffer +\startuseMPgraphic{lions b} + path p ; p := fullsquare + xyscaled (\overlaywidth,\overlayheight) randomized 5pt ; + pickup pencircle scaled 1pt ; + fill p withcolor .850white ; draw p withcolor .625yellow ; +\stopuseMPgraphic + +\defineoverlay[lions][\uniqueMPgraphic{lions b}] +\stopbuffer + +\typebuffer \getbuffer + +\bgroup \blank \veryraggedcenter\getbuffer[lions]\unskip \blank \egroup + +\startbuffer +\startuniqueMPgraphic{lions c} + path p ; p := fullsquare + xyscaled (\overlaywidth,\overlayheight) squeezed 2pt ; + pickup pencircle scaled 1pt ; + fill p withcolor .850white ; draw p withcolor .625yellow ; +\stopuniqueMPgraphic + +\defineoverlay[lions][\uniqueMPgraphic{lions c}] +\stopbuffer + +\typebuffer \getbuffer + +\bgroup \blank \veryraggedleft\getbuffer[lions]\unskip \blank \egroup + +These paragraphs were typeset with the following settings. + +\starttyping +\setupalign[broad, right] % == \veryraggedright +\setupalign[broad, middle] % == \veryraggedcenter +\setupalign[broad, left] % == \veryraggedleft +\stoptyping + +The \type {broad} increases the raggedness. We defined three different graphics +(a, b and c) because we want some to be unique, which saves some processing. Of +course we don't reuse the random graphics. In the definition of \type +{\processword} we have to use \type {\noindent} because otherwise \TEX\ will put +each graphic on a line of its own. Watch the space at the end of the macro. + +\stopsection + +\startsection[title={Graphics and macros}] + +Because \TEX's typographic engine and \METAPOST's graphic engine are separated, +interfacing between them is not as natural as you may expect. In \CONTEXT\ we +have tried to integrate them as much as possible, but using the interface is not +always as convenient as it should be. What method you follow, depends on the +problem at hand. + +The official \METAPOST\ way to embed \TEX\ code into graphics is to use \typ +{btex ... etex}. As soon as \CONTEXT\ writes the graphic data to the intermediate +\METAPOST\ file, it looks for these commands. When it has encountered an \type +{etex}, \CONTEXT\ will make sure that the text that is to be typeset by \TEX\ is +{\em not} expanded. This is what you may expect, because when you would embed +those commands in a stand||alone graphic, they would also not be expanded, if +only because \METAPOST\ does not know \TEX. With expansion we mean that \TEX\ +commands are replaced by their meaning (which can be quite extensive). + +{\em Users of \CONTEXT\ MKIV\ can skip the next paragraph}. + +When \METAPOST\ sees a \type {btex} command, it will consult a so called \type +{mpx} file. This file holds the \METAPOST\ representation of the text typeset by +\TEX. Before \METAPOST\ processes a graphic definition file, it first calls +another program that filters the \type {btex} commands from the source file, and +generates a \TEX\ file from them. This file is then processed by \TEX, and after +that converted to a \type {mpx} file. In \CONTEXT\ we let \TEXEXEC\ take care of +this whole process. + +Because the \typ {btex ... etex} commands are filtered from the raw \METAPOST\ +source code, they cannot be part of macro definitions and loop constructs. When +used that way, only one instance would be found, while in practice multiple +instances may occur. + +This drawback is overcome by \METAFUN's \type {textext} command. This command +still uses \typ {btex ... etex} but writes these commands to a separate job +related file each time it is used. \footnote {It took the author a while to find +out that there is a \METAPOST\ module called \type {tex.mp} that provides a +similar feature, but with the disadvantage that each text results in a call to +\TEX. Each text goes into a temporary file, which is then included and results in +\METAPOST\ triggering \TEX.} After the first \METAPOST\ run, this file is merged +with the original file, and \METAPOST\ is called again. So, at the cost of an +additional run, we can use text typeset by \TEX\ in a more versatile way. Because +\METAPOST\ runs are much faster than \TEX\ runs, the price to pay in terms of run +time is acceptable. Unlike \typ {btex ... etex}, the \TEX\ code in \type +{textext} command is expanded, but as long as \CONTEXT\ is used this is seldom a +problem, because most commands are somewhat protected. + +If we define a graphic with text to be typeset by \TEX, there is a good chance +that this text is not frozen but passes as argument. A \TEX||like solution for +passing arbitrary content to such a graphic is the following: \footnote {The \type +{\unexpanded} prefix makes the command robust for being passed as argument. It is not +to be confused with the primitive. We had this feature already when the primitive +showed up and it was considered to be inconvenient for other macro packages to adapt to +the \CONTEXT\ situation. So keep that in mind when you mix macro packages.} + +\startbuffer[def] +\unexpanded\def\RotatedText#1#2% + {\startuseMPgraphic{RotatedText} + draw btex #2 etex rotated #1 ; + \stopuseMPgraphic + \useMPgraphic{RotatedText}} +\stopbuffer + +\typebuffer[def] \getbuffer[def] + +This macro takes two arguments (the \type {#} identifies an +argument): + +\startbuffer[exa] +\RotatedText{15}{Some Rotated Text} +\stopbuffer + +\typebuffer[exa] + +The text is rotated over 15 degrees about the origin in a counterclockwise +direction. + +\startlinecorrection[blank] +\getbuffer[exa] +\stoplinecorrection + +In \CONTEXT\ we seldom pass settings like the angle of rotation in this manner. +You can use \type {\setupMPvariables} to set up graphic||specific variables. Such +a variable can be accessed with \type {\MPvar}. + +\startbuffer[def] +\setupMPvariables[RotatedText][rotation=90] + +\startuseMPgraphic{RotatedText} + draw textext{Some Text} rotated \MPvar{rotation} ; +\stopuseMPgraphic +\stopbuffer + +\typebuffer[def] \getbuffer[def] + +An example: + +\startbuffer[exa] +\RotatedText{-15}{Some Rotated Text} +\stopbuffer + +\typebuffer[exa] + +\startlinecorrection[blank] +\getbuffer[exa] +\stoplinecorrection + +In a similar fashion we can isolate the text. This permits us to use the same +graphics with different settings. + +\startbuffer[def] +\setupMPvariables[RotatedText][rotation=270] + +\setMPtext{RotatedText}{Some Text} + +\startuseMPgraphic{RotatedText} + draw \MPbetex{RotatedText} rotated \MPvar{rotation} ; +\stopuseMPgraphic +\stopbuffer + +\typebuffer[def] \getbuffer[def] + +This works as expected: + +\startbuffer[exa] +\RotatedText{165}{Some Rotated Text} +\stopbuffer + +\typebuffer[exa] + +\startlinecorrection[blank] +\getbuffer[exa] +\stoplinecorrection + +It is now a small step towards an encapsulating macro (we assume that you are +familiar with \TEX\ macro definitions). + +\startbuffer[def] +\def\RotatedText[#1]#2% + {\setupMPvariables[RotatedText][#1]% + \setMPtext{RotatedText}{#2}% + \useMPgraphic{RotatedText}} + +\setupMPvariables[RotatedText][rotation=90] + +\startuseMPgraphic{RotatedText} + draw \MPbetex{RotatedText} rotated \MPvar{rotation} ; +\stopuseMPgraphic +\stopbuffer + +\typebuffer[def] \getbuffer[def] + +Again, we default to a 90 degrees rotation, and pass both the settings and text +in an indirect way. This method permits you to build complicated graphics and +still keep macros readable. + +\startbuffer[exa] +\RotatedText[rotation=240]{Some Rotated Text} +\stopbuffer + +\typebuffer[exa] + +\startlinecorrection[blank] +\getbuffer[exa] +\stoplinecorrection + +You may wonder why we don't use the variable mechanism to pass the text. The main +reason is that the text mechanism offers a few more features, one of which is +that it passes the text straight on, without the danger of unwanted expansion of +embedded macros. Using \type {\setMPtext} also permits you to separate \TEX\ and +\METAPOST\ code and reuse it multiple times (imagine using the same graphic in a +section head command). + +There are three ways to access a text defined with \type {\setMPtext}. Imagine +that we have the following definitions: + +\startbuffer +\setMPtext {1} {Now is this \TeX\ or not?} +\setMPtext {2} {See what happens here.} +\setMPtext {3} {Text streams become pictures.} +\stopbuffer + +\typebuffer \getbuffer + +The \type {\MPbetex} macro returns a \typ {btex ... etex} construct. The \type +{\MPstring} returns the text as a \METAPOST\ string, between quotes. The raw text +can be fetched with \type {\MPtext}. + +\startbuffer +\startMPcode + picture p ; p := \MPbetex {1} ; + picture q ; q := textext( \MPstring{2} ) ; + picture r ; r := thelabel("\MPtext {3}",origin) ; + + for i=p, boundingbox p : draw i withcolor .625red ; endfor ; + for i=q, boundingbox q : draw i withcolor .625yellow ; endfor ; + for i=r, boundingbox r : draw i withcolor .625white ; endfor ; + + currentpicture := currentpicture scaled 2 ; + draw origin + withpen pencircle scaled 5.0mm withcolor white ; + draw origin + withpen pencircle scaled 2.5mm withcolor black ; + draw boundingbox currentpicture + withpen pencircle scaled .1mm + dashed evenly ; +\stopMPcode +\stopbuffer + +\typebuffer + +The first two lines return text typeset by \TEX, while the last line leaves this +to \METAPOST. + +\startlinecorrection[blank] +\getbuffer +\stoplinecorrection + +If you watch closely, you will notice that the first (red) alternative is +positioned with the baseline on the origin. + +\startbuffer +\startMPcode + picture p ; p := \MPbetex {1} ; + picture q ; q := textext.origin( \MPstring{2} ) ; + picture r ; r := thelabel.origin("\MPtext {3}",origin) ; + + for i=p, boundingbox p : draw i withcolor .625red ; endfor ; + for i=q, boundingbox q : draw i withcolor .625yellow ; endfor ; + for i=r, boundingbox r : draw i withcolor .625white ; endfor ; + + currentpicture := currentpicture scaled 2 ; + draw origin withpen pencircle scaled 5.0mm + withcolor white ; + draw origin withpen pencircle scaled 2.5mm + withcolor black ; + draw boundingbox currentpicture + withpen pencircle scaled .1mm + dashed evenly ; +\stopMPcode +\stopbuffer + +\typebuffer + +This draws: + +\startlinecorrection[blank] +\getbuffer +\stoplinecorrection + +This picture demonstrates that we can also position \type {textext}'s and \type +{label}'s on the baseline. For this purpose the repertoire of positioning +directives (\type {top}, \type {lft}, etc.) is extended with an \type {origin} +directive. Another extra positioning directive is \type {raw}. This one does not +do any positioning at all. + +\starttyping +picture q ; q := textext.origin( \MPstring{2} ) ; +picture r ; r := thelabel.origin("\MPtext {3}",origin) ; +\stoptyping + +We will now apply this knowledge of text inclusion in graphics to a more advanced +example. The next definitions are the answer to a question on the \CONTEXT\ +mailinglist with regards to framed texts with titles. + +\startbuffer[a] +\defineoverlay[FunnyFrame][\useMPgraphic{FunnyFrame}] + +\defineframedtext[FunnyText][frame=off,background=FunnyFrame] + +\def\StartFrame{\startFunnyText} +\def\StopFrame {\stopFunnyText } + +\def\FrameTitle#1% + {\setMPtext{FunnyFrame}{\hbox spread 1em{\hss\strut#1\hss}}} + +\setMPtext{FunnyFrame}{} % initialize the text variable +\stopbuffer + +\startbuffer[b] +\startuseMPgraphic{FunnyFrame} + picture p ; numeric w, h, o ; + p := textext.rt(\MPstring{FunnyFrame}) ; + w := OverlayWidth ; h := OverlayHeight ; o := BodyFontSize ; + p := p shifted (2o,h-ypart center p) ; draw p ; + drawoptions (withpen pencircle scaled 1pt withcolor .625red) ; + draw (2o,h)--(0,h)--(0,0)--(w,0)--(w,h)--(xpart urcorner p,h) ; + draw boundingbox p ; + setbounds currentpicture to unitsquare xyscaled(w,h) ; +\stopuseMPgraphic +\stopbuffer + +\startbuffer[c1] +\FrameTitle{Zapf (1)} + +\StartFrame +Coming back to the use of typefaces in electronic +publishing: many of the new typographers receive their +knowledge and information about the rules of typography from +books, from computer magazines or the instruction manuals +which they get with the purchase of a PC or software. +\StopFrame +\stopbuffer + +\getbuffer[a,b,c1] + +In this example, the title is positioned on top of the frame. Title and text are +entered as: + +\typebuffer[c1] + +The implementation is not that complicated and uses the frame commands that are +built in \CONTEXT. Instead of letting \TEX\ draw the frame, we use \METAPOST, +which we also use for handling the title. The graphic is defined as follows: + +\typebuffer[b] + +Because the framed title is partly positioned outside the main frame, and because +the main frame will be combined with the text, we need to set the boundingbox +explicitly. This is a way to create so called free figures, where part of the +figure lays beyond the area that is taken into account when positioning the +graphic. The shift + +\starttyping +... shifted (2o,h-ypart center p) +\stoptyping + +ensures that the title is vertically centered over the top line of the main box. + +The macros that use this graphic combine some techniques of defining macros, +using predefined \CONTEXT\ classes, and passing information to graphics. + +\typebuffer[a] + +There is a little bit of low level \TEX\ code involved, like a horizontal box +(\type {\hbox}) that stretches one em||space beyond its natural size (\type +{spread 1em}) with a centered text (two times \type {\hss}). Instead of applying +this spread, we could have enlarged the frame on both sides. + +\startbuffer[b] +\startuseMPgraphic{FunnyFrame} + picture p ; numeric o ; path a, b ; pair c ; + p := textext.rt(\MPstring{FunnyFrame}) ; + a := unitsquare xyscaled(OverlayWidth,OverlayHeight) ; + o := BodyFontSize ; + p := p shifted (2o,OverlayHeight-ypart center p) ; + drawoptions (withpen pencircle scaled 1pt withcolor .625red) ; + b := a randomized (o/2) ; + fill b withcolor .85white ; draw b ; + b := (boundingbox p) randomized (o/8) ; + fill b withcolor .85white ; draw b ; + draw p withcolor black; + setbounds currentpicture to a ; + \stopuseMPgraphic +\stopbuffer + +In the previous graphic we calculated the big rectangle taking the small one into +account. This was needed because we don't use a background fill. The next +definition does, so there we can use a more straightforward approach by just +drawing (and filling) the small rectangle on top of the big one. + +\typebuffer[b] \getbuffer[b] + +\startbuffer[c2] +\FrameTitle{Zapf (2)} + +\StartFrame +There is not so much basic instruction, as of now, as there +was in the old days, showing the differences between good +and bad typographic design. +\StopFrame +\stopbuffer + +\getbuffer[c2] + +Because we use a random graphic, we cannot guarantee beforehand that the left and +right edges of the small shape touch the horizontal lines in a nice way. The next +alternative displaces the small shape plus text so that its center lays on the +line. On the average, this looks better. + +\startbuffer[b] +\startuseMPgraphic{FunnyFrame} + picture p ; numeric o ; path a, b ; pair c ; + p := textext.rt(\MPstring{FunnyFrame}) ; + a := unitsquare xyscaled(OverlayWidth,OverlayHeight) ; + o := BodyFontSize ; + p := p shifted (2o,OverlayHeight-ypart center p) ; + drawoptions (withpen pencircle scaled 1pt withcolor .625red) ; + b := a randomized (o/2) ; + fill b withcolor .85white ; draw b ; + c := center p ; + c := b intersectionpoint (c shifted (0,-o)--c shifted(0,o)) ; + p := p shifted (c-center p) ; + b := (boundingbox p) randomized (o/8) ; + fill b withcolor .85white ; draw b ; + draw p withcolor black; + setbounds currentpicture to a ; + \stopuseMPgraphic +\stopbuffer + +\typebuffer[b] \getbuffer[b] + +\getbuffer[c2] + +Yet another definition uses super ellipsed shapes instead of random ones. We need +a high degree of superness (.95) in order to make sure that the curves don't +touch the texts. + +\startbuffer[b] +\startuseMPgraphic{FunnyFrame} + picture p ; numeric o ; path a, b ; pair c ; + p := textext.rt(\MPstring{FunnyFrame}) ; + o := BodyFontSize ; + a := unitsquare xyscaled(OverlayWidth,OverlayHeight) ; + p := p shifted (2o,OverlayHeight-ypart center p) ; + drawoptions (withpen pencircle scaled 1pt withcolor .625red) ; + b := a superellipsed .95 ; + fill b withcolor .85white ; draw b ; + b := (boundingbox p) superellipsed .95 ; + fill b withcolor .85white ; draw b ; + draw p withcolor black ; + setbounds currentpicture to a ; +\stopuseMPgraphic +\stopbuffer + +\typebuffer[b] \getbuffer[b] + +\startbuffer[c3] +\FrameTitle{Zapf (3)} + +\StartFrame +Many people are just fascinated by their PC's tricks, and +think that a widely||praised program, called up on the +screen, will make everything automatic from now on. +\StopFrame +\stopbuffer + +\getbuffer[c3] + +There are quite some hard coded values in these graphics, like the linewidths, +offsets and colors. Some of these can be fetched from the \type {\framed} +environment either by using \TEX\ macros or dimensions, or by using their +\METAFUN\ counterparts. In the following table we summarize both the available +\METAPOST\ variables and their \TEX\ counterparts. They may be used +interchangeably. + +\starttabulate[|l|Tl|l|] +\HL +\NC \bf \METAPOST\ variable \NC \rm \bf \TEX\ command \NC \bf meaning \NC\NR +\HL +\NC OverlayWidth \NC \string\overlaywidth + \NC current width \NC\NR +\NC OverlayHeight \NC \string\overlayheight + \NC current height \NC\NR +\NC OverlayDepth \NC \string\overlayheight + \NC current depth (often zero) \NC\NR +\NC OverlayColor \NC \string\MPcolor\string{\string\overlaycolor\string} + \NC background color \NC\NR +\NC OverlayLineWidth \NC \string\overlaylinewidth + \NC width of the frame \NC\NR +\NC OverlayLineColor \NC \string\MPcolor\string{\overlaylinecolor\string} + \NC color of the frame \NC\NR +\NC BaseLineSkip \NC \string\the\string\baselineskip + \NC main line distance \NC\NR +\NC LineHeight \NC \string\the\string\baselineskip + \NC idem \NC\NR +\NC BodyFontSize \NC \string\the\string\bodyfontsize + \NC font size of the running text \NC\NR +\NC StrutHeight \NC \string\strutheight + \NC space above the baseline \NC\NR +\NC StrutDepth \NC \string\strutdepth + \NC space below the baseline \NC\NR +\NC ExHeight \NC 1ex + \NC height of an x \NC \NR +\NC EmWidth \NC 1em + \NC width of an m-dash \NC \NR +\HL +\stoptabulate + +\startbuffer[b] +\startuseMPgraphic{FunnyFrame} + picture p ; numeric o ; path a, b ; pair c ; + p := textext.rt(\MPstring{FunnyFrame}) ; + o := BodyFontSize ; + a := unitsquare xyscaled(OverlayWidth,OverlayHeight) ; + p := p shifted (2o,OverlayHeight-ypart center p) ; + pickup pencircle scaled OverlayLineWidth ; + b := a superellipsed .95 ; + fill b withcolor OverlayColor ; + draw b withcolor OverlayLineColor ; + b := (boundingbox p) superellipsed .95 ; + fill b withcolor OverlayColor ; + draw b withcolor OverlayLineColor ; + draw p withcolor black ; + setbounds currentpicture to a ; +\stopuseMPgraphic +\stopbuffer + +\typebuffer[b] \getbuffer[b] + +\startbuffer[d] +\setupframedtexts + [FunnyText] + [backgroundcolor=lightgray, + framecolor=darkred, + rulethickness=2pt, + offset=\bodyfontsize, + before={\blank[big,medium]}, + after={\blank[big]}, + width=\textwidth] +\stopbuffer + +\getbuffer[d,c3] + +We used the following command to pass the settings: + +\typebuffer[d] + +In a real implementation, we should also take care of some additional spacing +before the text, which is why we have added more space before than after the +framed text. + +We demonstrated that when defining graphics that are part of the layout, you need +to have access to information known to the typesetting engine. Take \in {figure} +[fig:penalty]. The line height needs to match the font and the two thin +horizontal lines should match the {\em x}||height. We also need to position the +baseline, being the lowest one of a pair of lines, in such a way that it suits +the proportions of the line as specified by the strut. A strut is an imaginary +large character with no width. You should be aware of the fact that while \TEX\ +works its way top||down, in \METAPOST\ the origin is in the lower left corner. + +\startmode[screen] + +\placefigure + [page][fig:penalty] + {Penalty lines.} + {\typesetfile[mfun-902.tex][page=1,frame=on,height=.85\textheight]} + +\stopmode + +\startnotmode[screen] + +\placefigure + [here][fig:penalty] + {Penalty lines.} + {\typesetfile[mfun-902.tex][page=1,frame=on,height=.50\textheight]} + +\stopnotmode + +\typebuffer[handwrit] + +This code demonstrates the use of \type {LineHeight}, \type {ExHeight}, \type +{StrutHeight} and \type {StrutDepth}. We set the interline spacing to 1.5 so that +we get a bit more loose layout. The variables mentioned are set each time a +graphic is processed and thereby match the current font settings. + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/metafun/metafun-lua.tex b/doc/context/sources/general/manuals/metafun/metafun-lua.tex new file mode 100644 index 000000000..da35cccde --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/metafun-lua.tex @@ -0,0 +1,1060 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +% this is an extension of about-lua + +\startcomponent mfun-lua + +\environment metafun-environment + +\startchapter[title={Lua}] + +\index{\LUA} + +\startintro + +Already for some years I have been wondering how it would be if we could escape +to \LUA\ inside \METAPOST, or in practice, use \MPLIB\ in \LUATEX. The idea is +simple: embed \LUA\ code in a \METAPOST\ file that gets run as soon as it's seen. +In case you wonder why \LUA\ code makes sense, imagine generating graphics using +external data. The capabilities of \LUA\ to deal with that is more flexible and +advanced than in \METAPOST. Of course we could generate a \METAPOST\ definition +of a graphic from data but often it makes more sense to do the reverse. I finally +found time and reason to look into this and in the following sections I will +describe how it's done. + +\stopintro + +\startsection[title=Introduction] + +\stopsection + +\startsection[title=The basics] + +The approach is comparable to \LUATEX's \type {\directlua}. That primitive can be +used to execute \LUA\ code and in combination with \type {tex.print} we can pipe +back strings into the \TEX\ input stream. There a complication is that that we +have to be able to operate under different so called catcode regimes: the meaning +of characters can differ per regime. We also have to deal with line endings in +special ways as they relate to paragraphs and such. In \METAPOST\ we don't have +that complication so getting back input into the \METAPOST\ input, we can do so +with simple strings. For that a mechanism similar to \type {scantokens} can be +used. That way we can return anything (including nothing) as long as \METAPOST\ +can interpret it and as long as it fulfils the expectations. + +\starttyping +numeric n ; n := scantokens("123.456") ; +\stoptyping + +A script is run as follows: + +\starttyping +numeric n ; n := runscript("return '123.456'") ; +\stoptyping + +This primitive doesn't have the word \type {lua} in its name so in principle any +wrapper around the library can use it as hook. In the case of \LUATEX\ the script +language is of course \LUA. At the \METAPOST\ end we only expect a string. How +that string is constructed is completely up to the \LUA\ script. In fact, the +user is completely free to implement the runner any way she or he wants, like: + +\starttyping +local function scriptrunner(code) + local f = loadstring(code) + if f then + return tostring(f()) + else + return "" + end +end +\stoptyping + +This is hooked into an instance as follows: + +\starttyping +local m = mplib.new { + ... + run_script = scriptrunner, + ... +} +\stoptyping + +Now, beware, this is not the \CONTEXT\ way. We provide print functions and other +helpers, which we will explain in the next section. + +\stopsection + +\startsection[title=Helpers] + +After I got this feature up and running I played a bit with possible interfaces +at the \CONTEXT\ (read: \METAFUN) end and ended up with a bit more advanced runner +where no return value is used. The runner is wrapped in the \type {lua} macro. + +\startbuffer +numeric n ; n := lua("mp.print(12.34567)") ; +draw textext(n) xsized 4cm withcolor darkred ; +\stopbuffer + +\typebuffer + +This renders as: + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +In case you wonder how efficient calling \LUA\ is, don't worry: it's fast enough, +especially if you consider suboptimal \LUA\ code and the fact that we switch +between machineries. + +\startbuffer +draw image ( + lua("statistics.starttiming()") ; + for i=1 upto 10000 : draw + lua("mp.pair(math.random(-200,200),math.random(-50,50))") ; + endfor ; + setbounds currentpicture to fullsquare xyscaled (400,100) ; + lua("statistics.stoptiming()") ; +) withcolor darkyellow withpen pencircle scaled 1 ; +draw textext(lua("mp.print(statistics.elapsedtime())")) + ysized 50 withcolor darkred ; +\stopbuffer + +\typebuffer + +Here the line: + +\starttyping +draw lua("mp.pair(math.random(-200,200),math.random(-50,50))") ; +\stoptyping + +effectively becomes (for instance): + +\starttyping +draw scantokens "(25,40)" ; +\stoptyping + +which in turn becomes: + +\starttyping +draw scantokens (25,40) ; +\stoptyping + +The same happens with this: + +\starttyping +draw textext(lua("mp.print(statistics.elapsedtime())")) ... +\stoptyping + +This becomes for instance: + +\starttyping +draw textext(scantokens "1.23") ... +\stoptyping + +and therefore: + +\starttyping +draw textext(1.23) ... +\stoptyping + +We can use \type {mp.print} here because the \type {textext} macro can deal with +numbers. The next also works: + +\starttyping +draw textext(lua("mp.quoted(statistics.elapsedtime())")) ... +\stoptyping + +Now we get (in \METAPOST\ speak): + +\starttyping +draw textext(scantokens (ditto & "1.23" & ditto) ... +\stoptyping + +Here \type {ditto} represents the double quotes that mark a string. Of course, +because we pass the strings directly to \type {scantokens}, there are no outer +quotes at all, but this is how it can be simulated. In the end we have: + +\starttyping +draw textext("1.23") ... +\stoptyping + +What you use, \type {mp.print} or \type {mp.quoted} depends on what the expected +code is: an assignment to a numeric can best be a number or an expression +resulting in a number. + +This graphic becomes: + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +The runtime on my current machine is some 0.25 seconds without and 0.12 seconds +with caching. But to be honest, speed is not really a concern here as the amount +of complex \METAPOST\ graphics can be neglected compared to extensive node list +manipulation. With \LUAJITTEX\ generating the graphic takes 15\% less time. + +\startbuffer +numeric n ; n := lua("mp.print(1) mp.print('+') mp.print(2)") ; +draw textext(n) xsized 1cm withcolor darkred ; +\stopbuffer + +The three print command accumulate their arguments: + +\typebuffer + +As expected we get: + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +\startbuffer +numeric n ; n := lua("mp.print(1,'+',2)") ; +draw textext(n) xsized 1cm withcolor darkred ; +\stopbuffer + +Equally valid is: + +\typebuffer + +This gives the same result: + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +Of course all kind of action can happen between the prints. It is also legal to +have nothing returned as could be seen in the 10.000 dot example: there the timer +related code returns nothing so effectively we have \type {scantokens("")}. Another +helper is \type {mp.quoted}, as in: + +\startbuffer +draw + textext(lua("mp.quoted('@0.3f'," & decimal n & ")")) + withcolor darkred ; +\stopbuffer + +\typebuffer + +This typesets \processMPbuffer. Watch the \type {@}. When no percent character is +found in the format specifier, we assume that an \type {@} is used instead. + +\startbuffer +\startluacode +table.save("demo-data.lua", + { + { 1, 2 }, { 2, 4 }, { 3, 3 }, { 4, 2 }, + { 5, 2 }, { 6, 3 }, { 7, 4 }, { 8, 1 }, + } +) +\stopluacode +\stopbuffer + +But, the real benefit of embedded \LUA\ is when we deal with data that is stored +at the \LUA\ end. First we define a small dataset: + +\typebuffer + +\getbuffer + +There are several ways to deal with this table. I will show clumsy as well as +better looking ways. + +\startbuffer +lua("MP = { } MP.data = table.load('demo-data.lua')") ; +numeric n ; +lua("mp.print('n := ',\#MP.data)") ; +for i=1 upto n : + drawdot + lua("mp.pair(MP.data[" & decimal i & "])") scaled cm + withpen pencircle scaled 2mm + withcolor darkred ; +endfor ; +\stopbuffer + +\typebuffer + +Here we load a \LUA\ table and assign the size to a \METAPOST\ numeric. Next we +loop over the table entries and draw the coordinates. + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +We will stepwise improve this code. In the previous examples we omitted wrapper +code but here we show it: + +\startbuffer +\startluacode + MP.data = table.load('demo-data.lua') + function MP.n() + mp.print(#MP.data) + end + function MP.dot(i) + mp.pair(MP.data[i]) + end +\stopluacode + +\startMPcode + numeric n ; n := lua("MP.n()") ; + for i=1 upto n : + drawdot + lua("MP.dot(" & decimal i & ")") scaled cm + withpen pencircle scaled 2mm + withcolor darkred ; + endfor ; +\stopMPcode +\stopbuffer + +\typebuffer + +So, we create a few helpers in the \type {MP} table. This table is predefined so +normally you don't need to define it. You may however decide to wipe it clean. + +\startlinecorrection[blank] +\getbuffer +\stoplinecorrection + +You can decide to hide the data: + +\startbuffer +\startluacode + local data = { } + function MP.load(name) + data = table.load(name) + end + function MP.n() + mp.print(#data) + end + function MP.dot(i) + mp.pair(data[i]) + end +\stopluacode +\stopbuffer + +\typebuffer \getbuffer + +It is possible to use less \LUA, for instance in: + +\startbuffer +\startluacode + local data = { } + function MP.loaded(name) + data = table.load(name) + mp.print(#data) + end + function MP.dot(i) + mp.pair(data[i]) + end +\stopluacode + +\startMPcode + for i=1 upto lua("MP.loaded('demo-data.lua')") : + drawdot + lua("MP.dot(",i,")") scaled cm + withpen pencircle scaled 4mm + withcolor darkred ; + endfor ; +\stopMPcode +\stopbuffer + +\typebuffer + +Here we also omit the \type {decimal} because the \type {lua} macro is clever +enough to recognize it as a number. + +\startlinecorrection[blank] +\getbuffer +\stoplinecorrection + +By using some \METAPOST\ magic we can even go a step further in readability: + +\startbuffer +\startMPcode{doublefun} + lua.MP.load("demo-data.lua") ; + + for i=1 upto lua.MP.n() : + drawdot + lua.MP.dot(i) scaled cm + withpen pencircle scaled 4mm + withcolor darkred ; + endfor ; + + for i=1 upto MP.n() : + drawdot + MP.dot(i) scaled cm + withpen pencircle scaled 2mm + withcolor white ; + endfor ; +\stopMPcode +\stopbuffer + +\typebuffer + +Here we demonstrate that it also works ok in \type {double} mode, which makes +much sense when processing data from other sources. Watch how we omit the +type {lua.} prefix: the \type {MP} macro will deal with that. + +\startlinecorrection[blank] +\getbuffer +\stoplinecorrection + +So in the end we can simplify the code that we started with to: + +\starttyping +\startMPcode{doublefun} + for i=1 upto MP.loaded("demo-data.lua") : + drawdot + MP.dot(i) scaled cm + withpen pencircle scaled 2mm + withcolor darkred ; + endfor ; +\stopMPcode +\stoptyping + +\stopsection + +\startsection[title=Access to variables] + +The question with such mechanisms is always: how far should we go. Although +\METAPOST\ is a macro language it has properties of procedural languages. It also +has more introspective features at the user end. For instance, one can loop over +the resulting picture and manipulate it. This means that we don't need full +access to \METAPOST\ internals. However, it makes sense to provide access to +basic variables: \type {numeric}, \type {string}, and \type {boolean}. + +\startbuffer +draw textext(lua("mp.quoted('@0.15f',mp.get.numeric('pi')-math.pi)")) + ysized 1cm + withcolor darkred ; +\stopbuffer + +\typebuffer + +In double mode you will get zero printed but in scaled mode we definitely get a +difference: + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +\startbuffer +boolean b ; b := true ; +draw textext(lua("mp.quoted(mp.get.boolean('b') and 'yes' or 'no')")) + ysized 1cm + withcolor darkred ; +\stopbuffer + +In the next example we use \type {mp.quoted} to make sure that indeed we pass a +string. The \type {textext} macro can deal with numbers but an unquoted \type +{yes} or \type {no} is asking for problems. + +\typebuffer + +Especially when more text is involved it makes sense to predefine a helper in +the \type {MP} namespace if only because \METAPOST\ (currently) doesn't like +newlines in the middle of a string, so a \type {lua} call has to be on one line. + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +Here is an example where \LUA\ does something that would be close to impossible, +especially if more complex text is involved. + +% \enabletrackers[metapost.lua] + +\startbuffer +string s ; s := "ΤΕΧ" ; % "τεχ" +draw textext(lua("mp.quoted(characters.lower(mp.get.string('s')))")) + ysized 1cm + withcolor darkred ; +\stopbuffer + +\typebuffer + +As you can see here, the whole repertoire of helper functions can be used in +a \METAFUN\ definition. + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +\stopsection + +\startsection[title=The library] + +In \CONTEXT\ we have a dedicated runner, but for the record we mention the +low level constructor: + +\starttyping +local m = mplib.new { + ... + script_runner = function(s) return loadstring(s)() end, + script_error = function(s) print(s) end, + ..., +} +\stoptyping + +An instance (in this case \type {m}) has a few extra methods. Instead you can use +the helpers in the library. + +\starttabulate[|l|l|] +\HL +\NC \type {m:get_numeric(name)} \NC returns a numeric (double) \NC \NR +\NC \type {m:get_boolean(name)} \NC returns a boolean (\type {true} or \type {false}) \NC \NR +\NC \type {m:get_string (name)} \NC returns a string \NC \NR +\HL +\NC \type {mplib.get_numeric(m,name)} \NC returns a numeric (double) \NC \NR +\NC \type {mplib.get_boolean(m,name)} \NC returns a boolean (\type {true} or \type {false}) \NC \NR +\NC \type {mplib.get_string (m,name)} \NC returns a string \NC \NR +\HL +\stoptabulate + +In \CONTEXT\ the instances are hidden and wrapped in high level macros, so there +you cannot use these commands. + +\stopsection + +\startsection[title=\CONTEXT\ helpers] + +The \type {mp} namespace provides the following helpers: + +\starttabulate[|l|l|] +\HL +\NC \type {print(...)} \NC returns one or more values \NC \NR +\NC \type {pair(x,y)} + \type {pair(t)} \NC returns a proper pair \NC \NR +\NC \type {triplet(x,y,z)} + \type {triplet(t)} \NC returns an \RGB\ color \NC \NR +\NC \type {quadruple(w,x,y,z)} + \type {quadruple(t)} \NC returns an \CMYK\ color \NC \NR +\NC \type {format(fmt,...)} \NC returns a formatted string \NC \NR +\NC \type {quoted(fmt,...)} + \type {quoted(s)} \NC returns a (formatted) quoted string \NC \NR +\NC \type {path(t[,connect][,close])} \NC returns a connected (closed) path \NC \NR +\HL +\stoptabulate + +The \type {mp.get} namespace provides the following helpers: + +\starttabulate[|l|l|] +\HL +\NC \type {numeric(name)} \NC gets a numeric from \METAPOST \NC \NR +\NC \type {boolean(name)} \NC gets a boolean from \METAPOST \NC \NR +\NC \type {string(name)} \NC gets a string from \METAPOST \NC \NR +\HL +\stoptabulate + +\stopsection + +\startsection[title=Paths] + +In the meantime we got several questions on the \CONTEXT\ mailing list about turning +coordinates into paths. Now imagine that we have this dataset: + +\startbuffer[dataset] +10 20 20 20 -- sample 1 +30 40 40 60 +50 10 + +10 10 20 30 % sample 2 +30 50 40 50 +50 20 + +10 20 20 10 # sample 3 +30 40 40 20 +50 10 +\stopbuffer + +\typebuffer[dataset] + +In this case I've put the data in a buffer so that it can be shown +here as well as used in a demo. Watch how we can add comments. The +following code converts this into a table with three subtables. + +\startbuffer +\startluacode + MP.myset = mp.dataset(buffers.getcontent("dataset")) +\stopluacode +\stopbuffer + +\typebuffer \getbuffer + +We use the \type {MP} (user) namespace to store the table. Next we turn +these subtables into paths: + +\startbuffer +\startMPcode + for i=1 upto lua("mp.print(mp.n(MP.myset))") : + draw + lua("mp.path(MP.myset[" & decimal i & "])") + xysized (HSize-.25ExHeight,10ExHeight) + withpen pencircle scaled .25ExHeight + withcolor basiccolors[i]/2 ; + endfor ; +\stopMPcode +\stopbuffer + +\typebuffer + +This gives: + +\startlinecorrection[blank] \getbuffer \stoplinecorrection + +Instead we can fill the path in which case we also need to close it. The +\type {true} argument deals with that: + +\startbuffer +\startMPcode + for i=1 upto lua("mp.print(mp.n(MP.myset))") : + path p ; p := + lua("mp.path(MP.myset[" & decimal i & "],true)") + xysized (HSize,10ExHeight) ; + fill p + withcolor basiccolors[i]/2 + withtransparency (1,.5) ; + endfor ; +\stopMPcode +\stopbuffer + +\typebuffer + +We get: + +\startlinecorrection[blank] \getbuffer \stoplinecorrection + +\startbuffer +\startMPcode + for i=1 upto lua("mp.print(mp.n(MP.myset))") : + path p ; p := + lua("mp.path(MP.myset[" & decimal i & "])") + xysized (HSize,10ExHeight) ; + p := + (xpart llcorner boundingbox p,0) -- + p -- + (xpart lrcorner boundingbox p,0) -- + cycle ; + fill p + withcolor basiccolors[i]/2 + withtransparency (1,.25) ; + endfor ; +\stopMPcode +\stopbuffer + +The following makes more sense: + +\typebuffer + +So this gives: + +\startlinecorrection[blank] \getbuffer \stoplinecorrection + +This (area) fill is so common that we have a helper for it: + +\startbuffer +\startMPcode + for i=1 upto lua("mp.size(MP.myset)") : + fill area + lua("mp.path(MP.myset[" & decimal i & "])") + xysized (HSize,5ExHeight) + withcolor basiccolors[i]/2 + withtransparency (2,.25) ; + endfor ; +\stopMPcode +\stopbuffer + +\typebuffer + +So this gives: + +\startlinecorrection[blank] \getbuffer \stoplinecorrection + +A variant call is the following: \footnote {Getting that to work properly in the +library was non||trivial as the loop variable \type {i} is an abstract nameless +variable at the \METAPOST\ end. When investigating this Luigi Scarso and I found out +that the internals of \METAPOST\ are not really geared for interfacing this way +but in the end it worked out well.} + +\startbuffer +\startMPcode + for i=1 upto lua("mp.size(MP.myset)") : + fill area + lua("mp.path(MP.myset[mp.get.numeric('i')])") + xysized (HSize,5ExHeight) + withcolor basiccolors[i]/2 + withtransparency (2,.25) ; + endfor ; +\stopMPcode +\stopbuffer + +\typebuffer + +The result is the same: + +\startlinecorrection[blank] \getbuffer \stoplinecorrection + +\startbuffer +\startluacode + MP.mypath = function(i) + return mp.path(MP.myset[mp.get.numeric(i)]) + end +\stopluacode +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\startMPcode + for i=1 upto lua("mp.size(MP.myset)") : + fill area + lua("MP.mypath('i')") + xysized (HSize,5ExHeight) + withcolor basiccolors[i]/2 + withtransparency (2,.25) ; + endfor ; +\stopMPcode +\stopbuffer + +\typebuffer + +This snippet of \METAPOST\ code still looks kind of horrible so how can we make +it look better? Here is an attempt, First we define a bit more \LUA: + +\startbuffer +\startluacode +local data = mp.dataset(buffers.getcontent("dataset")) + +MP.dataset = { + Line = function(n) mp.path(data[n]) end, + Size = function() mp.size(data) end, +} +\stopluacode +\stopbuffer + +\typebuffer \getbuffer + +We can now make the \METAPOST\ look more natural. Of course this is possible +because in \METAFUN\ the \type {lua} macro does some extra work. + +\startbuffer +\startMPcode + for i=1 upto lua.MP.dataset.Size() : + path p ; p := + lua.MP.dataset.Line(i) + xysized (HSize-ExHeight,20ExHeight) ; + draw + p + withpen pencircle scaled .25ExHeight + withcolor basiccolors[i]/2 ; + drawpoints + p + withpen pencircle scaled ExHeight + withcolor basiccolors[i]/2 ; + endfor ; +\stopMPcode +\stopbuffer + +\typebuffer + +As expected, we get the desired result: + +\startlinecorrection[blank] \getbuffer \stoplinecorrection + +Once we start making things look nicer and more convenient, we quickly end up +with helpers like the once in the next example. First we save some demo data +in files: + +\startbuffer +\startluacode + io.savedata("foo.tmp","10 20 20 20 30 40 40 60 50 10") + io.savedata("bar.tmp","10 10 20 30 30 50 40 50 50 20") +\stopluacode +\stopbuffer + +\typebuffer \getbuffer + +We load the data in datasets: + +\startbuffer +\startMPcode + lua.mp.datasets.load("foo","foo.tmp") ; + lua.mp.datasets.load("bar","bar.tmp") ; + fill area + lua.mp.datasets.foo.Line() + xysized (HSize/2-EmWidth-.25ExHeight,10ExHeight) + withpen pencircle scaled .25ExHeight + withcolor darkyellow ; + fill area + lua.mp.datasets.bar.Line() + xysized (HSize/2-EmWidth-.25ExHeight,10ExHeight) + shifted (HSize/2+EmWidth,0) + withpen pencircle scaled .25ExHeight + withcolor darkred ; +\stopMPcode +\stopbuffer + +\typebuffer + +Because the datasets are stores by name we can use them without worrying about +them being forgotten: + +\startlinecorrection[blank] \getbuffer \stoplinecorrection + +If no tag is given, the filename (without suffix) is used as tag, so the following is +valid: + +\starttyping +\startMPcode + lua.mp.datasets.load("foo.tmp") ; + lua.mp.datasets.load("bar.tmp") ; +\stopMPcode +\stoptyping + +The following methods are defined for a dataset: + +\starttabulate[|l|pl|] +\HL +\NC \type {method} \NC usage \NC \NR +\HL +\NC \type {Size} \NC the number of subsets in a dataset \NC \NR +\NC \type {Line} \NC the joined pairs in a dataset making a non|-|closed path \NC \NR +\NC \type {Data} \NC the table containing the data (in subsets, so there is always at least one subset) \NC \NR +\HL +\stoptabulate + +{\em In order avoid interference with suffix handling in \METAPOST\ the methods +start with an uppercase character.} + +\stopsection + +\startsection[title=Passing variables] + +You can pass variables from \METAPOST\ to \CONTEXT. Originally that happened via +a temporary file and so called \METAPOST\ specials. Nowadays it's done via \LUA. +Here is an example: + +\startbuffer +\startMPcalculation + +passvariable("version","1.0") ; +passvariable("number",123) ; +passvariable("string","whatever") ; +passvariable("point",(1.5,2.8)) ; +passvariable("triplet",(1/1,1/2,1/3)) ; +passvariable("quad",(1.1,2.2,3.3,4.4)) ; +passvariable("boolean",false) ; +passvariable("path",fullcircle scaled 1cm) ; +path p[] ; p[1] := fullcircle ; p[2] := fullsquare ; +passarrayvariable("list",p,1,2,1) ; % first last step +\stopMPcalculation +\stopbuffer + +\typebuffer + +\getbuffer + +We can visualize the result with + +\startbuffer +\startluacode +context.tocontext(metapost.variables) +\stopluacode +\stopbuffer + +\typebuffer + +\getbuffer + +In \TEX\ you can access these variables as follows: + +\startbuffer +\MPrunvar{version} +\MPruntab{quad}{3} +(\MPrunset{triplet}{,}) + +$(x,y) = (\MPruntab{point}{1},\MPruntab{point}{2})$ +$(x,y) = (\MPrunset{point}{,})$ +\stopbuffer + +\typebuffer + +This becomes: % we need a hack as we cross pages and variables get replace then + +\startlines +\getbuffer +\stoplines + +Here we passed the code between \type {\startMPcalculation} and \type +{\stopMPcalculation} which does not produce a graphic and therefore takes no +space in the flow. Of course it also works with normal graphics. + +\startbuffer +\startMPcode +path p ; p := fullcircle xyscaled (10cm,2cm) ; +path b ; b := boundingbox p ; +startpassingvariable("mypath") + passvariable("points",p) ; + startpassingvariable("metadata") + passvariable("boundingbox",boundingbox p) ; + stoppassingvariable ; +stoppassingvariable ; +fill p withcolor .625red ; +draw b withcolor .625yellow ; +\stopMPcode +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] + \getbuffer +\stoplinecorrection + +This time we get: + +\ctxlua{context.tocontext(metapost.variables)} + +You need to be aware of the fact that a next graphic resets the previous +variables. You can easily overcome that limitation by saving the variables (in +\LUA). It helps that when a page is being shipped out (which can involve +graphics) the variables are protected. You can push and pop variable sets with +\type {\MPpushvariables} and \type {\MPpopvariables}. Because you can nest +the \type {start}||\type{stop} pairs you can create quite complex indexed +and hashed tables. If the results are not what you expect, you can enable a +tracker to follow what gets passed: + +\starttyping +\enabletrackers[metapost.variables] +\stoptyping + +Serializing variables can be done with the \type {tostring} macro, for instance: + +\startbuffer +\startMPcode +message("doing circle",fullcircle); +draw fullcircle ; +\stopMPcode +\stopbuffer + +In this case the \type {tostring} is redundant as the message already does the +serialization. + +\stopsection + +\stopchapter + +% \startMPcode{doublefun} +% numeric n ; n := 123.456 ; +% lua("print('>>>>>>>>>>>> number',mp.get.number('n'))") ; +% lua("print('>>>>>>>>>>>> number',mp.get.boolean('n'))") ; +% lua("print('>>>>>>>>>>>> number',mp.get.string('n'))") ; +% boolean b ; b := true ; +% lua("print('>>>>>>>>>>>> boolean',mp.get.number('b'))") ; +% lua("print('>>>>>>>>>>>> boolean',mp.get.boolean('b'))") ; +% lua("print('>>>>>>>>>>>> boolean',mp.get.string('b'))") ; +% string s ; s := "TEST" ; +% lua("print('>>>>>>>>>>>> string',mp.get.number('s'))") ; +% lua("print('>>>>>>>>>>>> string',mp.get.boolean('s'))") ; +% lua("print('>>>>>>>>>>>> string',mp.get.string('s'))") ; +% \stopMPcode + +% \usemodule[graph] +% +% \startluacode +% local d = nil +% function MP.set(data) +% d = data +% end +% function MP.n() +% mp.print(d and #d or 0) +% end +% function MP.get(i,j) +% mp.print(d and d[i] and d[i][j] or 0) +% end +% \stopluacode +% +% \startluacode +% MP.set { +% { 1, 0.5, 2.5 }, +% { 2, 1.0, 3.5 }, +% } +% \stopluacode +% +% \startMPpage[instance=graph,offset=2mm] +% +% draw begingraph(3cm,5cm); +% numeric a[]; +% for j = 1 upto MP.n() : +% path b; +% augment.b(MP.get(j,1),MP.get(j,2)); +% augment.b(MP.get(j,1),MP.get(j,3)); +% setrange(0,0,3,4); +% gdraw b; +% endfor ; +% endgraph ; +% \stopMPpage + +% \starttext +% +% % \enabletrackers[metapost.variables] +% +% \startMPcode +% numeric n[] ; for i=1 upto 10: n[i] := 1/i ; endfor ; +% path p[] ; for i=1 upto 10: p[i] := fullcircle xyscaled (cm*i,cm/i) ; endfor ; +% numeric r[][] ; for i=1 upto 4 : for j=1 upto 3 : r[i][j] := uniformdeviate(1) ; endfor ; endfor ; +% pair u[][] ; for i=1 step 0.5 until 4 : for j=1 step 0.1 until 2 : u[i][j] := (i,j) ; endfor ; endfor ; +% +% passvariable("x",12345) ; +% passarrayvariable("n-array",n,1,7,1) ; +% passarrayvariable("p-array",p,1,7,1) ; +% passvariable("p",(1,1) .. (2,2)) ; +% +% startpassingvariable("b") +% for i=1 upto 4 : +% startpassingvariable(i) +% for j=1 upto 3 : +% passvariable(j,r[i][j]) +% endfor +% stoppassingvariable +% endfor +% stoppassingvariable ; +% +% startpassingvariable("a") +% startpassingvariable("test 1") +% passvariable(1,123) +% passvariable(2,456) +% stoppassingvariable ; +% startpassingvariable("test 2") +% passvariable(0,123) +% passvariable(1,456) +% passvariable(2,789) +% passvariable(999,987) +% stoppassingvariable ; +% startpassingvariable("test 3") +% passvariable("first",789) +% passvariable("second",987) +% stoppassingvariable +% stoppassingvariable ; +% +% startpassingvariable("c") +% for i=1 step 0.5 until 4 : +% startpassingvariable(i) +% for j=1 step 0.1 until 2 : +% passvariable(j,u[i][j]) +% endfor +% stoppassingvariable +% endfor +% stoppassingvariable ; +% +% draw fullcircle scaled 1cm ; +% \stopMPcode +% +% \ctxluacode{inspect(metapost.variables)} +% +% \ctxcommand{mprunvar("x")} + +\stoptext + + diff --git a/doc/context/sources/general/manuals/metafun/metafun-macros.tex b/doc/context/sources/general/manuals/metafun/metafun-macros.tex new file mode 100644 index 000000000..e1df13c92 --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/metafun-macros.tex @@ -0,0 +1,91 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\startcomponent metafun-macros + +\environment metafun-environment + +\startchapter[title={\METAFUN\ macros}] + +\index{metafun} + +\startintro + +\CONTEXT\ comes with a series of \METAPOST\ modules. In this chapter we will +summarize the most important \TEX\ and \METAPOST\ macros. More information can be +found in the documentation of the modules. + +\stopintro + +There are several ways to use the power of \METAFUN, either or not using +\CONTEXT. + +\startitemize[n] + +\startitem + You can create an independent \type {mp} file and process it with the + \METAPOST\ program or \MPTOPDF. Depending on what features you use, the + succes of a run depends on the proper set up of the programs that take care + of running \TEX\ for \type {btex}. +\stopitem + +\startitem + You can embed the graphic in a \type {\startMPpage} construct and process it + with \CONTEXT\ \MKIV. In that case you have the full \METAFUN\ functionality + available. If for some reason you still want to use \MKII, you need to use + \TEXEXEC\ as before processing the file, it will do a couple of checks on the + file. It will also make sure that the temporary files (\type {mpt} for \type + {textext}'s and \type {mpo} for outline fonts) are taken care of too. +\stopitem + +\startitem + You can integrate the graphic in the document flow, using buffers, \METAPOST\ + code sections, or (reusable) graphic containers. In that case the graphics + are processed runtime or between runs. This happens automatically. +\stopitem + +\stopitemize + +Unless you want to write low level \CONTEXT\ code yourself, there is no real +reason to look into the modules that deal with \METAPOST\ support. The +traditional (partly generic) code is collected in: + +\starttabulate[|lT|p|] +\NC supp-mps.tex \NC low level inclusion macros and housekeeping \NC\NR +\NC supp-mpe.tex \NC experimental extensions (like specials) \NC\NR +\NC supp-pdf.tex \NC \METAPOST\ to \PDF\ conversion \NC\NR +\stoptabulate + +Especially the last two can be used in other macro packages. However, in +\CONTEXT\ we have regrouped the code (plus more) in other files: + +\starttabulate[|lT|p|] +\NC meta-***.tex \NC definition and managing \NC\NR +\NC mlib-***.tex \NC processing and conversion \NC\NR +\stoptabulate + +The last category will certainly grow. Some of these modules are preloaded, +others can be loaded using the command \type {\useMPlibrary}, like + +\starttyping +\useMPlibrary[clp,txt] +\stoptyping + +for loading the predefined clipping paths and text tricks. + +The \METAPOST\ code is organized in files named \type {mp-****.mp}. The core file +is \type {mp-tool.mp} and this file can comfortably be used in stand||alone +graphics. The file \type {metafun.mp} is used to load the collection of modules +into a format. The collection of \METAPOST\ code files will grow in due time, but +as long as you use the \METAFUN\ format, you don't have to keep track of the +organization of files. Most files relate to subsystems and are loaded +automatically, like the files that implement page layout support and flow charts. + +Although this document is the main source of information, occasionally the source +code of \METAFUN, and in many cases the source code of \CONTEXT\ may contain +additional information and examples. + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/metafun/metafun-positioning.tex b/doc/context/sources/general/manuals/metafun/metafun-positioning.tex new file mode 100644 index 000000000..5a3b1ece0 --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/metafun-positioning.tex @@ -0,0 +1,1013 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\startcomponent metafun-positioning + +\environment metafun-environment + +\startchapter[reference=sec:positioning,title={Positional graphics}] + +\startintro + +In this chapter, we will explore one of the more advanced, but also conceptually +more difficult, graphic capabilities of \CONTEXT. It took quite a few experiments +to find the {\em right} way to support these kind of graphics, and you can be +sure that in due time extensions will show up. You can skip this chapter if you +are no \CONTEXT\ user. Because we're now a decade into \MKIV\ the tricks here +will assume that you use \CONTEXT\ \MKIV\ because we have a more convenient +interface there. For old|-|school \MKII\ usage you can look in old \METAFUN\ +manuals or in the \type {mkii} source files. Of course we remain compatible, it's +just that more (convenient) interfaces were added. + +\stopintro + +\startsection[title={The status quo}] + +After \TEX\ has read a paragraph of text, it will try to break this paragraph +into lines. When this is done, the result is flushed and after that \TEX\ will +check if a page should be split off. As a result, we can hardly predict how a +document will come out. Therefore, when we want graphics to adapt themselves to +this text, maybe even to text broken across lines, we have to deal with this +asynchronous feature of \TEX\ in a rather advanced way. Before we present a way +of dealing with this complexity, we will elaborate on the nature of embedded +graphics in \TEX. + +When \TEX\ entered the world of typesetting, desktop printers were not that +common, let alone color desktop printers. But times have changed and nowadays we +want color and graphics and if possible we want them integrated in the text. When +\METAPOST\ showed up it depended on the \DVI\ processor to recognize the +\POSTSCRIPT\ code as being produced by \METAPOST\ and therefore also include the +fonts that were used. But color was still limited to \RGB. When \PDFTEX\ evolved +I wrote an interpreter (in \TEX) that could translate the output to \PDF. This +also opened up the possibility to add features to \METAPOST, like \CMYK\ colors, +shading, transparencies etc. But basically the \TEX\ and \METAPOST\ processes +were rather isolated. We could of course pass information to \METAPOST\ and pick +up information from \METAPOST\ in a second pass. That has changed in \LUATEX. + +In order to really integrate \METAPOST\ graphics into the flow you need to know +where you are on the page and how large graphics should be, especially when you +want them to depend on the layout. A first solution to this was to embed specials +in the \DVI\ that could later be used to extract positions. In retrospect this +was a relative trivial extension, something that could have been around much +earlier but somehow didn't happen. Anyhow, after some experiments \PDFTEX\ got a +native position tracker which meant that no post processor was needed. Of course +\LUATEX\ inherited this feature too. Because positioning is rather bound to the +macro package reading this chapter only makes sense when you use \CONTEXT. + +\stopsection + +\startbuffer[arrow:1] +\startMPpositionmethod{mypos:arrow} + \startMPpositiongraphic{mypos:arrow} + save pa, pb, pm, pab, na, nb, sa, sb ; + path pa, pb, pm, pab ; numeric na, nb ; string sa, sb ; + % the tags + sa := texstr("from") ; + sb := texstr("to") ; + % we need to check page crossing so we fetch the page numbers + na := positionpage(sa) ; + nb := positionpage(sb) ; + % we use the repositioned shapes + pa := positionbox(sa) ; + pb := positionbox(sb) ; + % but want circles instead of rectangles + pa := llcorner pa .. lrcorner pa .. urcorner pa .. ulcorner pa .. cycle ; + pb := llcorner pb .. lrcorner pb .. urcorner pb .. ulcorner pb .. cycle ; + pickup pencircle scaled 1pt ; + if na = nb : + % both are on the same page + fill pa withcolor .800white ; + fill pb withcolor .800white ; + draw pa withcolor .625yellow ; + draw pb withcolor .625yellow ; + pm := .5[center pa,center pb] shifted (0,2*LineHeight) ; + pab := center pa .. pm .. center pb ; + pab := pab cutbefore (pab intersectionpoint pa) ; + pab := pab cutafter (pab intersectionpoint pb) ; + drawarrow pab dashed evenly withcolor .625red ; + positionatanchor(sa) ; + elseif nb < na : + % they are on different pages and we're at the first one + fill pb withcolor .800white ; + draw pb withcolor .625yellow ; + pab := center pb {up} .. ulcorner bbox pb ; + pab := pab cutbefore (pab intersectionpoint pb) ; + drawarrow pab dashed evenly withcolor .625red ; + positionatanchor(sb) ; + else : + % they are on different pages and we're at the last one + fill pa withcolor .800white ; + draw pa withcolor .625yellow ; + pab := center pa {up} .. urcorner bbox pa ; + pab := pab cutbefore (pab intersectionpoint pa) ; + drawarrow pab dashed evenly withcolor .625red ; + positionatanchor(sa) ; + fi ; + \stopMPpositiongraphic + % we put it here at the first position + \MPpositiongraphic{mypos:arrow} + % we need to carry information forward and make sure that we also + % check and flush at the second position of the pair + \ifnum\MPp{\MPvar{from}}<\MPp{\MPvar{to}}\relax + \expanded{\setMPpositiongraphic{\MPvar{to}}{mypos:arrow}{to=\MPvar{from}}} + \fi +\stopMPpositionmethod +\stopbuffer + +\startbuffer[arrow:2] +\setMPpositiongraphic{A-1}{mypos:arrow}{to=A-2} +\stopbuffer + +\startbuffer[box:1] +\startMPpositiongraphic{mpos:box}{fillcolor,linecolor,linewidth} + string tag; tag := "\MPvar{self}" ; + path box ; box := positionbox(tag) ; + box := box enlarged \MPvar{filloffset} ; + fill box + withcolor \MPvar{fillcolor} ; + draw box + withcolor \MPvar{linecolor} + withpen pencircle scaled \MPvar{linewidth} ; + positioninregion ; +\stopMPpositiongraphic +\stopbuffer + +\startbuffer[box:1:also] +\startMPpositiongraphic{mpos:box}{fillcolor,linecolor,linewidth} + path box ; box := positionbox(texstr("self")) ; + box := box enlarged texvar("filloffset") ; + fill box + withcolor texvar("fillcolor") ; + draw box + withcolor texvar("linecolor") + withpen pencircle scaled texvar("linewidth") ; + positioninregion ; +\stopMPpositiongraphic +\stopbuffer + +\startbuffer[box:2] +\setupMPvariables + [mpos:box] + [linecolor=blue, + linewidth=\linewidth, + fillcolor=lightgray, + filloffset=2pt] + +\setupMPvariables[mpos:box][linecolor=darkred] +\setupMPvariables[mpos:par][linecolor=darkred] + +\startpositionoverlay{backgraphics} + \setMPpositiongraphic{A-0}{mpos:box}{self=A-0} + \setMPpositiongraphic{A-3}{mpos:box}{self=A-3} + \setMPpositiongraphic{A-4}{mpos:box}{self=A-4} +\stoppositionoverlay +\stopbuffer + +\getbuffer[arrow:1,arrow:2] +\getbuffer[box:1,box:2] + +\startsection[title={The concept}] + +\index {graphics+positioning} +\index {positioning} +\index {anchoring} + +Because we have a \LUA\ connection in \MPLIB, we have implemented a couple of +helpers that make live easier. This is also why the following examples are \MKIV\ +specific, although \MKII\ can do the same, but with a bit different set of +helpers. We can for instance query properties of \hpos {A-0} {positions} without +using \TEX\ macros but can use \METAPOST\ macros instead. Let's give an example. +The background and frame behind the word \type {position} in this paragraph is +not done with \type {\framed} but using a different mechanism: + +\starttyping +to get \hpos {A-0} {positions} sorted +\stoptyping + +The \type {\hpos} refers to a position and we have bound that position to a graphic: + +\starttyping +\setMPpositiongraphic{A-0}{mpos:box}{self=A-0} +\stoptyping + +The graphic itself is defined with: + +\typebuffer[box:1] + +A variant that has no macro calls and does all via the \LUA\ intercaface in \MKIV\ is +the following: + +\typebuffer[box:1:also] + +A \type {\hpos} position has several properties: the coordinates of the origin: +\type {x} and \type {y}, the dimensions of the boxed content, \type {w}, \type +{h} and \type {d}, and the page number \type {p}. An additional helper \type +{positioninregion} will move the drawing to the right spot in the region. +Examples or regions are the page, text area or some overlay. The \type +{positionatanchor} variant relocates to the anchor of the given tag. The first +helper is actually a shortcut for: + +\starttyping +currentpicture := currentpicture shifted - positionxy(positionanchor) ; +\stoptyping + +In our case we use a dedicated layer \type {backgraphics} that we have hooked into +the page backgrounds: + +\starttyping +\setupbackgrounds + [page] + [background={backgraphics,foreground,foregraphics}] + +\defineoverlay [backgraphics] [\positionoverlay{backgraphics}] +\defineoverlay [foregraphics] [\positionoverlay{foregraphics}] +\stoptyping + +The relation between position graphics and that layer are defined as follows +(we will come back to this in a moment): + +\typebuffer[box:2] + +\stopsection + +\startsection[title={A more detailed view}] + +As we know, a decent portion of \TEX's attention is focused on breaking +paragraphs into lines and determining the optimal point to split off the page. +Trying to locate the optimal points to break lines is a dynamic process. The +space between words is flexible and we don't know in advance when a \hpos {A-1} +{word} or piece of a word |<|maybe it's best to talk of typographic \hpos {A-2} +{globs} instead|>| will end up on the page. It might even cross the page +boundary. + +In the previous section we saw \hpos {A-3} {word} and \hpos {A-4} {globs} +encircled and connected by an arrow. This graphic can be drawn only when the +position and dimensions are known. Unfortunately, this information is only +available after the paragraph is typeset and the best breakpoints are chosen. +\bpos {A-5} Because the text must be laid on top of the graphic, the graphic must +precede the first word in the typeset stream or it must be positioned on a +separate layer. In the latter case it can be calculated directly after the +paragraph is typeset, but in the former case a second pass is needed. \epos {A-5} +Because such graphics are not bound to one paragraph, the multi||pass option +suits better because it gives us more control: the more we know about he final +state, the better we can act upon it. Think of graphics on the first page that +depend on the content of the last page \bpos {A-6} or, as in this paragraph, +backgrounds that depend on the typeset text. \epos {A-6} + +The arrows that connect the shapes are drawn with the following code that now +looks familiar: + +\typebuffer[arrow:1] + +and + +\typebuffer[arrow:2] + +However, here we anchor at one of the positions because we don't flush in a layer +but at the position itself. Indeed it looks complex. + +It may be clear now that we need some positional information in order to provide +features like the ones shown here. The fact that we will act upon in a second +pass simplifies the task, although it forces us to store the positional +information between runs in some place. This may look uncomfortable at first +sight, but it also enables us to store some additional information. Now why is +that needed? + +A position has no dimensions, it's just a place somewhere on the page. In order +to do tricks like those shown here, we also need to know the height and depth of +lines at a specific point as well as the width of the box(es) we're dealing with. +In the encircled examples, the dimensions of the box following the positional +node are stored along with the position. + +In order to process the graphics, we tag each point with a name, so that we can +attach actions to those points. In fact they become trigger points. As we will +demonstrate, we also need to store the current page number. This brings the data +stored with a point to: + +\starttyping +<identifier> <pagenumber> <x> <y> <width> <height> <depth> +\stoptyping + +Actually we store more information, for example the region in which the positions +sit. Depending on the use we can also get access to paragraph and line properties +but discussing these is beyond this manual. These are for instance used in the +text backgrounds. + +The page number is needed in order to let the graphics engine determine boundary +conditions. Backgrounds like those shown here can span multiple pages. In order +to calculate the right backgrounds, some additional information must be +available, like the top and bottom of the current text area. In fact, these are +just normal points that can be saved while processing the split off page. So, +apart from positioning anchors in the text we need anchors on crucial points of +the layout. This means that this kind of support cannot be fully integrated into +the \TEX\ kernel, unless we also add extensive support for layout definitions, +and that is probably not what we want. + +As soon as something like $(x,y)$ shows up, a logical question is where $(0,0)$ +is located. Although this is a valid question, the answer is less important than +you may expect. Even if we know that ($0,0)$ is \quote {officially} located in +the bottom left corner of the page, the simple fact that in \CONTEXT\ we are +dealing with a mixed page concept, like paper size and print paper size, or left +and right pages, forces us to think in relative positions instead of absolute +ones. Therefore, graphics, even those that involve multiple positions, are +anchored to a position on the layer on which they are located. + +Users who simply want to use these features may wonder why we go into so much +detail. The main reason is that in the end many users will want to go beyond the +simple cases, and when dealing with these issues, you must be aware not only of +height, depth and width, but also of the crossing of a page boundary, and the +height and depth of lines. In some cases your graphics may have to respond to +layout characteristics, like differences between odd and even pages. Given that +unique identifiers are used for anchor points, in \CONTEXT\ you can have access +to all the information needed. Here are some of the helpers: + +\starttabulate[|T||] +\NC positionpath (tag) \NC the path determined by width, height and depth \NC \NR +\NC positionxy (tag) \NC the origin \NC \NR +\NC positionwhd (tag) \NC the dimensions (in a triplet) \NC \NR +\NC positionpage (tag) \NC the page number fo the position \NC \NR +\NC positionregion(tag) \NC the region that the position sits in \NC \NR +\NC positionbox (tag) \NC the positioned box (path shifted over coordinates) \NC \NR +\NC positionanchor \NC the current anchor of the region \NC \NR +\stoptabulate + +The \type {positionwhd} macro returns a triplet that you can query, like: + +\starttyping +triplet whd ; whd := positionwhd("\MPvar{from}"); +numeric wd; wd := wdpart whd ; +\stoptyping + +We will add more such convenient helpers in the future. In the \CONTEXT\ +distribution you can find examples (in manuals or librarties) that demonstrate +other tricks with positioning. + +\stopsection + +\startsection[title={Anchors and layers}] + +\index{anchoring} +\index{layers} + +\startbuffer[g-circle] +\startMPpositiongraphic{mypos:circle} + path p ; p := positionbox(texstr("self")) ; + p := fullcircle xsized (bbwidth(p)+4pt) shifted center p ; + pickup pencircle scaled 1pt ; + fill p withcolor .800white ; + draw p withcolor .625yellow ; + positioninregion ; +\stopMPpositiongraphic +\stopbuffer + +\startbuffer[g-line] +\startMPpositiongraphic{mypos:line} + path pa, pb, pab ; numeric na, nb ; string ta, tb ; + ta := texstr("from") ; + tb := texstr("to") ; + na := positionpage(ta) ; + nb := positionpage(tb) ; + pa := positionbox(ta) ; + pb := positionbox(tb) ; + pa := fullcircle xsized (bbwidth(pa)+4pt) shifted center pa ; + pb := fullcircle xsized (bbwidth(pb)+4pt) shifted center pb ; + if na = nb : + pab := center pa -- center pb ; + pab := pab cutbefore (pab intersectionpoint pa) ; + pab := pab cutafter (pab intersectionpoint pb) ; + pickup pencircle scaled 1pt ; + draw pab withcolor .625yellow ; + positioninregion ; + fi ; +\stopMPpositiongraphic +\stopbuffer + +\getbuffer[g-circle,g-line] + +\startbuffer[a] +\setMPpositiongraphic{X-1}{mypos:arrow}{to=X-2} +\setMPpositiongraphic{X-2}{mypos:arrow}{to=X-3} +\stopbuffer + +\startbuffer[b] +In a previous section we saw that some \hpos {X-1} {words} were +\hpos {X-2} {circled} and connected by an \hpos {X-3} {arrow}. +As with most things in \CONTEXT, marking these words is separated +from declaring what to do with those words. This paragraph is keyed +in as: +\stopbuffer + +\getbuffer[a,b] + +\typebuffer[b] + +We see three position anchors, each marked by an identifier: \type {X-1}, \type +{X-2} and \type {X-3}. Each of these anchors can be associated with a (series) of +graphic operations. Here we defined: + +\typebuffer[a] + +These examples clearly demonstrate that we cannot control to what extent graphics +will cover text and vice versa. A solution to this problem is using position +overlays. We can define such an overlay as follows: + +\startbuffer +\startpositionoverlay{backgraphics} + \setMPpositiongraphic{G-1}{mypos:circle} + \setMPpositiongraphic{G-2}{mypos:circle} + \setMPpositiongraphic{G-3}{mypos:circle} + \setMPpositiongraphic{G-4}{mypos:circle} +\stoppositionoverlay + +\startpositionoverlay{foregraphics} + \setMPpositiongraphic{G-1}{mypos:line}{to=G-2} + \setMPpositiongraphic{G-2}{mypos:line}{to=G-3} + \setMPpositiongraphic{G-3}{mypos:line}{to=G-4} +\stoppositionoverlay +\stopbuffer + +\getbuffer \typebuffer + +\startbuffer +First we have defined an \hpos {G-1} {\strut overlay}. This +overlay can be attached to some overlay layer, like, in our +case, the \hpos {G-2} {\strut page}. We define four small \hpos +{G-3} {\strut circles}. These are drawn as soon as the page +overlay is typeset. Because they are located in the +background, they don't cover the \hpos {G-4} {\strut text}, while +the lines do. The previous paragraph was typeset by saying: +\stopbuffer + +\getbuffer \typebuffer + +As said, the circles are on the background layer, but the lines are not! They are +positioned on top of the text. This is a direct result of the definition of the +page background: + +\starttyping +\defineoverlay [foregraphics] [\positionoverlay{foregraphics}] +\defineoverlay [backgraphics] [\positionoverlay{backgraphics}] + +\setupbackgrounds + [page] + [background={backgraphics,foreground,foregraphics}] +\stoptyping + +\doifmode{screen}{\writestatus{CHECK}{POSITION GRAPHICS}} + +In this definition, the predefined overlay \type {foreground} inserts the page +data itself, so the foreground graphics end up on top. This example also +demonstrates that you should be well aware of the way \CONTEXT\ builds a page. +There are six main layers, in some cases with sublayers. The body text goes into +the main text layer, which, unless forced otherwise, lays on top. + +\startitemize[packed,n,columns,three] +\item paper background +\item area backgrounds +\item page backgrounds +\item text areas +\item logo areas +\item main text +\stopitemize + +The paper background is used for special (sometimes internal) purposes. There are +three page backgrounds: left, right and both. The text areas, logo areas and +backgrounds form a $5 \times 5$ matrix with columns containing the leftedge, +leftmargin, text, rightmargin, and rightedge. The rows of the matrix contain the +top, header, text, footer, and bottom. The main text is what you are reading now. + +Since the page background is applied last, the previous layers can be considered +to be the foreground to the page background layer. And, indeed, it is available +as an overlay under the name \type {foreground}, as we already saw in the +example. Foregrounds are available in most cases, but (for the moment) not when +we are dealing with the text area. Since anchoring the graphics is implemented +rather independent of the position of the graphics themselves, this is no real +problem, we can put them all on the page layer, if needed in separate overlays. + +How is such a graphic defined? In fact these graphics are a special case of the +already present mechanism of including \METAPOST\ graphics. The circles are +defined as follows: + +\typebuffer[g-circle] + +Drawing the lines is handled in a similar fashion. + +\typebuffer[g-line] + +The command \tex {startMPpositiongraphic} defines a graphic, in this example we +have called it \type {mypos:circle}. Here we show the definition out of order but +normally you need to define it before you refer to it. + +The \METAPOST\ macro \type {positionbox} returns a box that is constructed from +the coordinates and dimensions. After this call, the corners are available via +\type {llcorner}, \type {lrcorner}, \type {urcorner} and \type {ulcorner}. The +center is accessible by \type {center}. When we are finished drawing the graphic, +we can anchor the result with \type {positioninregion}. This macro automatically +handles positioning on specific layers. The helper macros are not loaded by +default, you do that with: + +\typebuffer[g-include] + +The position macro \type {\MPpos} returns the current characteristics of a +position. The previously defined G~positions return: + +\starttabulate[|c|c|c|c|c|c|c|] +\HL +\NC position\NC page\NC$x$\NC$y$\NC width\NC height\NC depth\NC\NR +\HL +\NC G-1\NC\MPp{G-1}\NC\MPx{G-1}\NC\MPy{G-1}\NC\MPw{G-1}\NC\MPh{G-1}\NC\MPd{G-1}\NC\NR +\NC G-2\NC\MPp{G-2}\NC\MPx{G-2}\NC\MPy{G-2}\NC\MPw{G-2}\NC\MPh{G-2}\NC\MPd{G-2}\NC\NR +\NC G-3\NC\MPp{G-3}\NC\MPx{G-3}\NC\MPy{G-3}\NC\MPw{G-3}\NC\MPh{G-3}\NC\MPd{G-3}\NC\NR +\NC G-4\NC\MPp{G-4}\NC\MPx{G-4}\NC\MPy{G-4}\NC\MPw{G-4}\NC\MPh{G-4}\NC\MPd{G-4}\NC\NR +\HL +\stoptabulate + +The numbers represent the real pagenumber~$p$, the current position $(x,y)$, and +the dimensions of the box $(w,h,d)$ if known. These values are fed directly into +\METAPOST\ graphics but the individual components can be asked for by \type +{\MPp}, \type {\MPx}, \type {\MPy}, \type {\MPw}, \type {\MPh} and \type {\MPd}. + +In the previous definition of the graphic, we saw another macro, \type {\MPvar}. +When we invoke a graphic or attach a graphic to a layer, we can pass variables. +We can also set specific variables in other ways, as we will see later. + +\starttyping +\setMPpositiongraphic{G-1}{mypos:circle} +\setMPpositiongraphic{G-1}{mypos:line}{to=G-2} +\stoptyping + +In the second definition, we let the variable \type {to} point to another +position. When needed, we can ask for the value of \type {to} by \type +{\MPvar{to}}. For reasons of convenience, the current position is assigned +automatically to \type {from} and \type {self}. This means that in the line we +saw in the graphic: + +\starttyping +path p ; p := positionbox(texstr("self")) ; +\stoptyping + +\type {texstr("self")} will return the current position, which, fed to \type +{positionbox} will return a box with the right dimensions. We already warned the +reader: this is not an easy chapter. + +\stopsection + +\startsection[title={More layers}] + +\index{layers} + +\setupbackgrounds + [state=repeat] + +Overlays are one of the nicer features of \CONTEXT\ and even more nice things can +be build on top of them. Overlays are defined first and then assigned to framed +boxes using the \type {background} variable. + +You can stack overlays, which is why they are called as such. You can use the +special overlay called \type {foreground} to move the topmost (often text) layer +down in the stack. + +\starttabulate +\HL +\NC background overlay \NC a text, graphic, hyperlink or widget \NC \NR +\NC position overlay \NC a series of macros triggered by positions \NC \NR +\NC background layer \NC a box that can hold boxes with offsets \NC \NR +\HL +\stoptabulate + +The last kind of layer can be used in other situations as well, but in most cases +it will be hooked into a background overlay. + +\startbuffer +\definelayer[MyLayer][option=test] + +\setupbackgrounds[text][leftmargin][background=MyLayer] + +\setlayer[MyLayer][x=.5cm,y=5cm] + {\rotate{\framed{This goes to the background}}} +\stopbuffer + +\typebuffer \getbuffer \setuplayer[MyLayer][option=] % no frames + +In this case the framed text will be placed in the background of the (current) +page with the given offset to the topleft corner. Instead of a fixed position, +you can inherit the current position using the \type {position} directive. Say +that we have a layer called \type {YourLayer} which we put in the background of +the text area. + +\startbuffer +\definelayer[YourLayer] +\setupbackgrounds[text][text][background=YourLayer] +\stopbuffer + +\typebuffer \getbuffer + +We can now move some framed text to this layer using \type {\setlayer} with the +directive \type {position} set to \type {yes}. + +\startbuffer +here: \setlayer[YourLayer][position=yes]{\inframed{Here}} +\stopbuffer + +\typebuffer + +You can influence the placement by explicitly providing an offset (\type +{hoffset} and|/|or \type {voffset}), a position (\type {x} and|/|or \type {y}) or +a location directive (\type {location}). Normally you will use the offsets for +the layer as a whole and the positions for individual contributions. The next +example demonstrates the use of a location directive. + +\startbuffer +here: \setlayer[YourLayer][position=yes,location=c]{\inframed{Here}} +\stopbuffer + +\typebuffer \getbuffer + +Many layers can be in use at the same time. In the next example we put something +in the page layer. By default, we turn on position tracking, which visualizes the +bounding box of the content and shows the reference point. + +\startbuffer +\definelayer[BackLayer][position=yes] +\setupbackgrounds[page][background=BackLayer] +\stopbuffer + +\typebuffer \getbuffer + +\setupbackgrounds + [page] + [background={PageFrame,BackLayer,backgraphics,foreground,foregraphics}] + +Next we define an overlay that we can put behind for instance framed texts. We +use \METAPOST\ to draw \type {Shape}. + +\startbuffer +\defineoverlay[Shape] [BackLayer] [\uniqueMPgraphic{Shape}] + +\startuniqueMPgraphic{Shape} + path p ; p := fullcircle xyscaled(OverlayWidth,OverlayHeight) ; + fill p withcolor \MPcolor{lightgray} ; + draw p withpen pencircle scaled 1pt withcolor \MPcolor{darkred} ; +\stopuniqueMPgraphic +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer[def] +\defineframed[Shaped][background=Shape,frame=off,location=low] +\stopbuffer + +\getbuffer[def] + +We can now put this background shape behind the running text, for instance with: + +\startbuffer +.... some \inframed[background=Shape]{text} with a frame ... +.... some \Shaped{text} with a frame ... +\stopbuffer + +\typebuffer + +\startlines +\getbuffer +\stoplines + +The \type {\Shaped} macro was defined as: + +\typebuffer[def] + +Watch how the graphics are moved to the background while the frame of the first +text stays on top, since it remains part of the text flow. + +\startbuffer[def] +\setuplayer[BackLayer][direction=reverse] +\stopbuffer + +\getbuffer[def] + +\startlines +\getbuffer +\stoplines + +In the previous instance of the example we have reversed the stacking. Reversal +can be done with the \type {direction} directive. + +\typebuffer[def] + +% next series + +\startbuffer +\setuplayer + [BackLayer] + [position=no,corner=bottom,height=\paperheight] + +\setlayer[BackLayer][x=2cm,y=10cm,location=bl] + {\externalfigure[somecow.pdf][width=1cm]} + +\setlayer[BackLayer][x=1cm,y=8cm,location=br] + {\externalfigure[somecow.pdf][width=1cm]} + +\setlayer[BackLayer][x=2cm,y=4cm,location=tl] + {\externalfigure[somecow.pdf][width=1cm]} + +\setlayer[BackLayer][x=10cm,y=1cm,location=tr] + {\externalfigure[somecow.pdf][width=1cm]} +\stopbuffer + +You can influence the placement of a background component by using a different +anchor point. + +\typebuffer {\setuplayer[option=test]\getbuffer} + +\startbuffer[xx] +\setuplayer + [BackLayer] + [position=no,corner=bottom,height=\paperheight] + +\setlayer[BackLayer][x=15cm,y=5cm,location=bl] + {\externalfigure[somecow.pdf][width=3cm]} + +\setlayer[BackLayer][x=15cm,y=5cm,location=br] + {\externalfigure[somecow.pdf][width=3cm]} + +\setlayer[BackLayer][x=15cm,y=5cm,location=tl] + {\externalfigure[somecow.pdf][width=2cm]} + +\setlayer[BackLayer][x=15cm,y=5cm,location=tr] + {\externalfigure[somecow.pdf][width=2cm]} + +\setlayer[BackLayer][x=15cm,y=5cm,location=c] + {\externalfigure[somecow.pdf][width=3cm]} +\stopbuffer + +% \startpostponing + +Instead of using relative positions, you can also use absolute ones. Of course +you need to know how your coordinates relate to the rest of the layout +definition. + +\typebuffer[xx] + +These examples again demonstrate how we can influence the placement by assigning +an anchor point to \type {position}. Here we also put the reference point in the +lower left corner (\type {bottom}). This mechanism only works when we also use +\type {height}. + +{\setuplayer[option=test]\getbuffer[xx]} + +\page + +% \stoppostponing + +\setupbackgrounds + [page] + [background={PageFrame,DemoLayer,backgraphics,foreground,foregraphics}] + +\definelayer + [DemoLayer] + [position=yes] + +\startbuffer +\definelayer + [DemoLayer] + [position=yes] + +\startplacefigure[title={Demo 1}] + \ruledhbox\bgroup + \setlayerframed + [DemoLayer] [hoffset=-10mm,voffset=5mm] + {\startMPcode + fill fullcircle scaled 2cm withcolor .625red ; + \stopMPcode}% + \setlayerframed + [DemoLayer] [voffset=-10mm] + {\startMPcode + fill fullcircle scaled 2cm withcolor .625green ; + \stopMPcode}% + \setlayerframed + [DemoLayer] [hoffset=10mm,voffset=5mm] + {\startMPcode + fill fullcircle scaled 2cm withcolor .625blue ; + \stopMPcode}% + \egroup +\stopplacefigure +\stopbuffer + +\getbuffer + +One of the reasons for developing the layer mechanism was that we needed to +slightly change the position of figures in the final stage of typesetting. The +previous pages demonstrate how one can position anything anywhere on the page, +but in the case of figures the position may depend on where the text ends up on +the page. + +Normally, when you manipulate a document this way, you are in the final stage of +typesetting. You may qualify this as desk top publishing without actually using a +desktop. + +\typebuffer + +\startbuffer[demo] +\startbuffer +\setlayer [DemoLayer] + [position=yes, + voffset=-1.5cm, + width=3cm, + height=2cm] + {\MPfigure{somecow.pdf}{scaled .5 slanted .5}} +\stopbuffer + +\placefigure[right]{}{\ruledhbox{\getbuffer}} +\stopbuffer + +{\setuplayer[option=test]\getbuffer[demo]} + +The previous example also demonstrated the use of \METAPOST\ for rotating the +picture. The \type {\MPfigure} macro encapsulates the code in a shortcut. You can +achieve special effects by using the layers behind floating bodies and alike, but +always keep in mind that the readability of the text should not be violated too +much. + +\typebuffer[demo] + +In these examples we added a \type {\ruledhbox} around the pseudo graphics so +that you can see what the size is of those graphics. + +% summary + +We have already seen a lot of parameters that can be used to control the content +of a layer. There are a few more. General housekeeping takes place with: + +\starttabulate[|Tl|Tl|l|] +\HL +\NC state \NC start \NC enable the layer \NC \NR +\NC \NC stop \NC disable the layer \NC \NR +\NC position \NC no \NC use absolute positions \NC \NR +\NC \NC yes \NC use relative positions \NC \NR +\NC \NC overlay \NC idem, but ignore the size \NC \NR +\NC direction \NC normal \NC put new data on top \NC \NR +\NC \NC reverse \NC put new data below old data \NC \NR +\HL +\stoptabulate + +Sometimes all data needs to be offset in a similar way. You can use both offset +parameters for that. + +\starttabulate[|Tl|l|] +\HL +\NC hoffset \NC an additional horizontal displacement \NC \NR +\NC voffset \NC an additional vertical displacement \NC \NR +\HL +\stoptabulate + +You can position data anywhere in the layer. When positioning is turned on, the +current position will get a placeholder. You can change the dimensions of that +placeholder (when \type {position} is set to \type {overlay}), zero dimensions +are used. + +\starttabulate[|Tl|l|] +\HL +\NC x \NC the horizontal displacement \NC \NR +\NC y \NC the vertical displacement \NC \NR +\NC width \NC the (non natural) width \NC \NR +\NC height \NC the (non natural) height \NC \NR +\NC location \NC \tttf l r t b c lt lb rt rb \NC \NR +\HL +\stoptabulate + +The \type {location} directive determines what point of the data is used as +reference point. You can keep track of this point and the placement when you +enable test mode. This is how the rectangles in the previous examples were +drawn. + +\starttabulate[|Tl|Tl|l|] +\HL +\NC option \NC test \NC show positioning information \NC \NR +\HL +\stoptabulate + +When you are enhancing the final version of a document, you can explicitly +specify on what page the data will go. Use this option with care. + +\starttabulate[|Tl|l|] +\HL +\NC page \NC the page where the data will go \NC \NR +\HL +\stoptabulate + +Because layers can migrate to other pages, they may disappear due to the +background not being recalculated. In case of doubt, you can force repetitive +background calculation by: + +\starttyping +\setupbackgrounds[state=repeat] +\stoptyping + +% restore 'm + +\setupbackgrounds + [page] + [background={PageFrame,backgraphics,foreground,foregraphics}] + +\setupbackgrounds + [state=start] + +\stopsection + +\startsection[title={Complex text in graphics}] + +\index{text} + +If you like to embed \METAPOST\ snippets in \CONTEXT, you may want to combine +text and graphics and let \METAPOST\ provide the position and the dimensions of +the text to be typeset outside by \TEX. For most applications using the \METAFUN\ +\type {textext} macro works well enough, but when the typeset text needs to +communicate with the typesetting engine, for instance because it contains +hyperlinks or references, you can use the following method: + +\startitemize[packed] +\item define a layer +\item define a (reusable) graphic +\item put your text into the layer +\item combine the graphic with the text +\stopitemize + +You must be aware of the fact that when the layer is flushed, its content is +gone. You can take advantage of this by using the same graphic with multiple +texts. + +\startbuffer +\definelayer[test] +\stopbuffer + +\typebuffer \getbuffer + +You don't need to pass the width and height explicitly, but when you do so, you +have access to them later. + +\startbuffer +\startuseMPgraphic{oeps} + path p ; p := fullcircle scaled 6cm ; + fill p withcolor .8white ; + draw p withpen pencircle scaled 1mm withcolor .625red ; + register ("somepos-1",0cm,0cm,center currentpicture) ; + register ("somepos-2",3cm,1cm,(-1cm,-1cm)) ; + register ("somepos-3",2cm,0cm,(-2cm,2cm)) ; +\stopuseMPgraphic +\stopbuffer + +\typebuffer \getbuffer + +The \METAFUN\ \type {register} macro takes the following arguments: + +\starttyping +register ("tag",width,height,(x offset,y offset)) ; +\stoptyping + +The width and height are available in the macros \type {\MPlayerwidth} and \type +{\MPlayerheight} and are equivalent to \type {\MPw{tag}} and \type {\MPh{tag}}, + +\startbuffer +\setMPlayer [test] [somepos-1] [location=c] + {Does it work al right?} + +\setMPlayer [test] [somepos-2] + {\framed + [width=\MPlayerwidth,height=\MPlayerheight, + background=color,backgroundcolor=white] + {It Works!}} + +\setMPlayer [test] [somepos-3] + {\externalfigure[cow-fun.mps][width=2cm]} +\stopbuffer + +\typebuffer \getbuffer + +Combining the graphic and the text is handled by the macro \type {\getMPlayer}. + +\startbuffer +\getMPlayer [test] {\useMPgraphic{oeps}} +\stopbuffer + +\typebuffer \getbuffer + +The macro \type {\getMPlayer} is built on top of \type {\framed}. The settings +passed in the (optional) second argument are the same as those to \type +{\framed}. + +\starttyping +\getMPlayer + [test] + [frame=on,offset=5pt] + {\useMPgraphic{oeps}} +\stoptyping + +As you see, you need a bit of a twisted mind to handle graphics this way, but at +least the functionality is there to create complex graphics in a declarative way. + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/metafun/metafun-reference.tex b/doc/context/sources/general/manuals/metafun/metafun-reference.tex new file mode 100644 index 000000000..6eb177949 --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/metafun-reference.tex @@ -0,0 +1,659 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\startcomponent metafun-reference + +\environment metafun-environment + +\startchapter[reference=reference,title={Reference}] + +\startintro + +In this chapter, we will demonstrate most of the drawing related primitives and +macros as present in plain \METAPOST\ and \METAFUN\ extensions. + +If a path is shown and|/|or a transformation is applied, we show the original in +red and the transformed path or point in yellow. The small dark gray crosshair is +the origin and the black rectangle the bounding box. In some drawings, in light +gray we show the points that make up the path. + +This list describes traditional \METAPOST\ and the stable part of \METAFUN. As +\METAPOST\ evolves, new primitives are added but they are not always that +relevant to us. If you browse the \METAFUN\ sources you will for sure notice more +functionality than summarized here. Most of that is meant for usage in \CONTEXT\ +and not exposed to the user. Other macros are still somewhat experimental but +might become more official at some point. The same is true for \METAFUN\ +commands: not all make sense for daily usage and some are just there as helper +for additional modules. + +\stopintro + +\startsection[title={Paths}] + +\index{paths} + +\ShowSampleA {mc} {pair} {(1,.5)} +\ShowSampleA {mm} {pair .. pair} {(0,0)..(.75,0)..(1,.25)..(1,1)} +\ShowSampleA {mm} {pair ... pair} {(0,0)..(.75,0)...(1,.25)..(1,1)} +\ShowSampleA {mm} {pair -- pair\quad (a)} {(0,0)--(.75,0)--(1,.25)--(1,1)} +\ShowSampleA {mm} {pair -- pair\quad (b)} {(0,0)..(.75,0)--(1,.25)..(1,1)} +\ShowSampleA {mm} {pair --- pair} {(0,0)..(.75,0)---(1,.25)..(1,1)} + +\ShowSampleA {mm} {pair softjoin pair} {(0,0)..(.75,0) softjoin (1,.25)..(1,1)} +\ShowSampleA {mp} {controls pair} {(0,0)..controls (.75,0)..(1,1)} +\ShowSampleA {mp} {controls pair and pair} {(0,0)..controls (.75,0) and (1,.25)..(1,1)} +\ShowSampleA {mp} {tension numeric} {(0,0)..(.75,0)..tension 2.5..(1,.25)..(1,1)} +\ShowSampleA {mp} {tension num.. and num..} {(0,0)..(.75,0)..tension 2.5 and 1.5..(1,.25)..(1,1)} +\ShowSampleA {mp} {tension atleast numeric} {(0,0)..(.75,0)..tension atleast 1..(1,.25)..(1,1)} + +\ShowSampleA {mp} {cycle} {(0,0)--(1,0)--(1,1)--cycle} +\ShowSampleA {mp} {curl numeric} {(0,0){curl 1}..(.75,0)..(1,.25)..(1,1)} +\ShowSampleA {mp} {dir numeric} {(0,0){dir 30}..(1,1)} +\ShowSampleA {mm} {left} {(0,0){left}..(1,1)} +\ShowSampleA {mm} {right} {(0,0){right}..(1,1)} +\ShowSampleA {mm} {up} {(0,0){up}..(1,1)} +\ShowSampleA {mm} {down} {(0,0){down}..(1,1)} + +\ShowSampleA {mp} {path \& path} {(0,0)..(.75,.25) \& (.75,.25)..(1,1)} + +\ShowSampleA {mv} {unitvector} {origin--unitvector(1,1)} +\ShowSampleA {mp} {dir} {origin--dir(45)} +\ShowSampleA {mp} {angle} {origin--dir(angle(1,1))} + +\ShowSampleA {mv} {fullcircle} {fullcircle} +\ShowSampleA {fv} {unitcircle} {unitcircle} +\ShowSampleA {fv} {fullsquare} {fullsquare} +\ShowSampleA {mv} {unitsquare} {unitsquare} +\ShowSampleA {fv} {fulltriangle}{fulltriangle} +\ShowSampleA {fv} {unittriangle}{unittriangle} +\ShowSampleA {fv} {fulldiamond} {fulldiamond} +\ShowSampleA {fv} {unitdiamond} {unitdiamond} + +\ShowSampleA {mv} {halfcircle} {halfcircle} +\ShowSampleA {mv} {quartercircle} {quartercircle} + +\ShowSampleA {fv} {llcircle} {llcircle} +\ShowSampleA {fv} {lrcircle} {lrcircle} +\ShowSampleA {fv} {urcircle} {urcircle} +\ShowSampleA {fv} {ulcircle} {ulcircle} +\ShowSampleA {fv} {tcircle} {tcircle} +\ShowSampleA {fv} {bcircle} {bcircle} +\ShowSampleA {fv} {lcircle} {lcircle} +\ShowSampleA {fv} {rcircle} {rcircle} + +\ShowSampleA {fv} {triangle} {triangle} +\ShowSampleA {fv} {righttriangle} {righttriangle} +\ShowSampleA {fv} {uptriangle} {uptriangle} +\ShowSampleA {fv} {lefttriangle} {lefttriangle} +\ShowSampleA {fv} {downtriangle} {downtriangle} + +\ShowSampleA {fv} {lltriangle} {lltriangle} +\ShowSampleA {fv} {lrtriangle} {lrtriangle} +\ShowSampleA {fv} {urtriangle} {urtriangle} +\ShowSampleA {fv} {ultriangle} {ultriangle} + +\ShowSampleA {mm} {flex(pair,pair,pair)} + {flex ((0,0),(1,1),(1,0))} +\ShowSampleA {mm} {superellipse(pair,p..,p..,p..,num..)} + {superellipse((1,.5),(.5,1),(0,.5),(.5,0),.75)} + +\ShowSampleA {fm} {path smoothed numeric/pair} {unitsquare scaled 1.5 smoothed .2} +\ShowSampleA {fm} {path cornered numeric/pair} {lltriangle scaled 1.5 cornered .2} +\ShowSampleA {fm} {path superellipsed numeric} {unitsquare scaled 1.5 superellipsed .75} +\ShowSampleA {fm} {path randomized numeric/pair} {unitsquare scaled 1.5 randomized (.2,.2)} +\ShowSampleA {fm} {path randomizedcontrols numeric/pair} {fullcircle scaled 1.5 randomizedcontrols (.2,.2)} +\ShowSampleA {fm} {path squeezed numeric/pair} {unitsquare scaled 1.5 squeezed (.2,.1)} +\ShowSampleA {fm} {path snapped numeric/pair} {fullcircle scaled 1.5 snapped (.2,.1)} + +\ShowSampleB {fm} {punked path} + {unitcircle scaled 1.5} + {punked unitcircle scaled 1.5} + +\ShowSampleB {fm} {curved path} + {((0,0)--(.2,1)--(1,.2)--cycle)} + {curved ((0,0)--(.2,1)--(1,.2)--cycle)} + +\ShowSampleB {fm} {laddered path} + {((0,0)--(1.4,.8)--(2.8,1.2)--(6.2,1.6))} + {laddered ((0,0)--(1.4,.8)--(2.8,1.2)--(6.2,1.6))} + +\ShowSampleB {fm} {path paralleled distance} + {((0,0)--(5,1))} + {((0,0)--(5,1)) paralleled .25} + +\ShowSampleB {fm} {shortened path} + {((0,0)--(6,1))} + {((0,0)--(6,1)) shortened 1} + +\ShowSampleB {fm} {unspiked path} + {((0,0)--(1,0)--(1,1)--(2,1)--(1,1)--(0,1)) shifted (-3,0)} + {unspiked ((0,0)--(1,0)--(1,1)--(2,1)--(1,1)--(0,1))} + +\ShowSampleB {fm} {simplified path} + {((0,0)--(1,0)--(2,0)--(2,1)--(0,1)--cycle) shifted (-3,0)} + {simplified ((0,0)--(1,0)--(2,0)--(2,1)--(0,1)--cycle)} + +\ShowSampleB {fm} {path blownup numeric/pair} + {fullcircle scaled 1.5} + {(fullcircle scaled 1.5) blownup .1} + +\ShowSampleB {fm} {path stretched numeric/pair\quad (a)} + {fullcircle scaled 1.5} + {(fullcircle scaled 1.5) stretched (1.1,0.8)} + +\ShowSampleB {fm} {path stretched numeric\quad (b)} + {((0,0)--(1,1))} + {((0,0)--(1,1)) stretched 1.5} + +\ShowSampleB {fm} {path xstretched numeric} + {fullcircle} + {fullcircle xstretched 5} + +\ShowSampleB {fm} {path ystretched numeric} + {fullcircle} + {fullcircle ystretched 1.5} + +\ShowSampleB {fm} {path enlonged numeric} + {((0,0)--(1,1))} + {((0,0)--(1,1)) enlonged 1.5} + +\ShowSampleB {fm} {path shorted numeric} + {((0,0)--(2,2))} + {((0,0)--(2,2)) shortened 0.5} + +\ShowSampleA {fm} {roundedsquare(num..,num..,num..)} + {roundedsquare(2,1,.2)} + +\ShowSampleA {fm} {tensecircle(num..,num..,num..)} + {tensecircle(2,1,.2)} + +\ShowSampleA {fm} {pair crossed size} + {origin crossed 1} + +\ShowSampleA {fm} {path crossed size} + {fullcircle scaled 2 crossed .5} + +\ShowSampleA {fm} {(constructed)function} + {constructedfunction("--")("x","sin(x)",0,2pi,pi/10)} + +\ShowSampleA {fm} {curvedfunction} + {curvedfunction("x","sin(x)",0,2pi,pi/10)} + +\ShowSampleA {fm} {straightfunction} + {straightfunction("x","sin(x)",0,2pi,pi/10)} + +\ShowSampleA {fm} {constructedpath} + {constructedpath("..")((0,0),(1,2),(2,1),(3,2))} + +\ShowSampleA {fm} {curvedpath} + {curvedpath((0,0),(1,2),(2,1),(3,2))} + +\ShowSampleA {fm} {straightpath} + {straightpath((0,0),(1,2),(2,1),(3,2))} + +\ShowSampleA {fm} {leftarrow} + {leftarrow(fullcircle,3,2)} + +\ShowSampleA {fm} {rightarrow} + {rightarrow(fullcircle,3,2)} + +\ShowSampleA {fm} {centerarrow} + {centerarrow(fullcircle,3,2)} + +\ShowSampleX {fm} {arrowhead} {draw arrowhead fullcircle} +\ShowSampleX {fm} {arrowpath} {draw arrowpath fullcircle} + +\ShowSampleA {mm} {buildcycle} + {buildcycle(fullcircle,fullsquare)} + +\ShowSampleA {fm} {circularpath} {circularpath(4)} +\ShowSampleA {fm} {squarepath} {squarepath(4)} +\ShowSampleA {fm} {linearpath} {linearpath(4)} + +\stopsection + +\startsection[title={Transformations}] + +\index{transformations} + +\ShowSampleB {mp} {path scaled numeric} {fullcircle} {fullcircle scaled .50} +\ShowSampleB {mp} {path xscaled numeric} {fullcircle} {fullcircle xscaled .25} +\ShowSampleB {mp} {path yscaled numeric} {fullcircle} {fullcircle yscaled .25} +\ShowSampleB {mp} {path zscaled pair} {fullcircle} {fullcircle zscaled (2,.25)} +\ShowSampleB {mp} {path xyscaled numeric/pair} {fullcircle} {fullcircle xyscaled (.5,.7)} +\ShowSampleB {mp} {path xyscaled pair} {fullcircle} {fullcircle xyscaled (2,.25)} +\ShowSampleB {mp} {path shifted pair} {fullcircle} {fullcircle shifted (2,.25)} + +\ShowSampleB {fm} {path leftenlarged numeric} {fullsquare} {fullsquare leftenlarged .25} +\ShowSampleB {fm} {path topenlarged numeric} {fullsquare} {fullsquare topenlarged .25} +\ShowSampleB {fm} {path rightenlarged numeric} {fullsquare} {fullsquare rightenlarged .25} +\ShowSampleB {fm} {path bottomenlarged numeric} {fullsquare} {fullsquare bottomenlarged .25} + +\ShowSampleB {fm} {path enlarged numeric} {fullcircle} {fullcircle enlarged .25} +\ShowSampleB {fm} {path enlarged pair} {fullcircle} {fullcircle enlarged (1,.25)} +\ShowSampleB {fm} {path llenlarged numeric} {fullcircle} {fullcircle llenlarged .25} +\ShowSampleB {fm} {path lrenlarged numeric} {fullcircle} {fullcircle lrenlarged .25} +\ShowSampleB {fm} {path urenlarged numeric} {fullcircle} {fullcircle urenlarged .25} +\ShowSampleB {fm} {path ulenlarged numeric} {fullcircle} {fullcircle ulenlarged .25} +\ShowSampleB {fm} {path llenlarged pair} {fullcircle} {fullcircle llenlarged (1,.25)} +\ShowSampleB {fm} {path lrenlarged pair} {fullcircle} {fullcircle lrenlarged (1,.25)} +\ShowSampleB {fm} {path urenlarged pair} {fullcircle} {fullcircle urenlarged (1,.25)} +\ShowSampleB {fm} {path ulenlarged pair} {fullcircle} {fullcircle ulenlarged (1,.25)} +\ShowSampleB {fm} {path llmoved numeric} {fullcircle} {fullcircle llmoved .25} +\ShowSampleB {fm} {path lrmoved numeric} {fullcircle} {fullcircle lrmoved .25} +\ShowSampleB {fm} {path urmoved numeric} {fullcircle} {fullcircle urmoved .25} +\ShowSampleB {fm} {path ulmoved numeric} {fullcircle} {fullcircle ulmoved .25} +\ShowSampleB {fm} {path llmoved pair} {fullcircle} {fullcircle llmoved (1,.25)} +\ShowSampleB {fm} {path lrmoved pair} {fullcircle} {fullcircle lrmoved (1,.25)} +\ShowSampleB {fm} {path urmoved pair} {fullcircle} {fullcircle urmoved (1,.25)} +\ShowSampleB {fm} {path ulmoved pair} {fullcircle} {fullcircle ulmoved (1,.25)} +\ShowSampleB {mp} {path slanted numeric} {fullcircle} {fullcircle slanted .5} +\ShowSampleB {mp} {path rotated numeric} {fullsquare} {fullsquare rotated 45} + +\ShowSampleB {mm} {path rotatedaround(pair,numeric)} {fullsquare} {fullsquare rotatedaround((.25,.5),45)} +\ShowSampleB {mm} {path reflectedabout(pair,pair)} {fullcircle} {fullcircle reflectedabout((.25,-1),(.25,+1))} +\ShowSampleB {mp} {reverse path} {fullcircle} {reverse fullcircle shifted(.5,0)} +\ShowSampleB {mm} {counterclockwise path} {fullcircle} {counterclockwise fullcircle shifted(.5,0)} +\ShowSampleB {mm} {tensepath path} {fullcircle} {tensepath fullcircle} + +\ShowSampleB {mp} {subpath (numeric,numeric) of path} {fullcircle} {subpath (1,5) of fullcircle} +\ShowSampleB {mm} {path cutbefore pair} {fullcircle} {fullcircle cutbefore point 3 of fullcircle} +\ShowSampleB {mm} {path cutafter pair} {fullcircle} {fullcircle cutafter point 3 of fullcircle} +\ShowSampleB {mm} {path cutends .1} {fullcircle} {fullcircle cutends .5} + +\ShowSampleC {mp} {llcorner path} {fullcircle} {llcorner fullcircle} +\ShowSampleC {mp} {lrcorner path} {fullcircle} {lrcorner fullcircle} +\ShowSampleC {mp} {urcorner path} {fullcircle} {urcorner fullcircle} +\ShowSampleC {mp} {ulcorner path} {fullcircle} {ulcorner fullcircle} +\ShowSampleC {mm} {center path} {fullcircle} {center fullcircle} + +\ShowSampleD {fm} {boundingbox path} {fullcircle} {boundingbox fullcircle} +\ShowSampleD {fm} {boundingcircle path} {fullsquare} {boundingcircle fullsquare} +\ShowSampleD {fm} {innerboundingbox path} {fullcircle} {innerboundingbox fullcircle} +\ShowSampleD {fm} {outerboundingbox path} {fullcircle} {outerboundingbox fullcircle} + +\ShowSampleDD {fm} {bottomboundary path} {fullcircle} {bottomboundary fullcircle} +\ShowSampleDD {fm} {leftboundary path} {fullcircle} {leftboundary fullcircle} +\ShowSampleDD {fm} {topboundary path} {fullcircle} {topboundary fullcircle} +\ShowSampleDD {fm} {rightboundary path} {fullcircle} {rightboundary fullcircle} + +\ShowSampleP {fm} {bbwidth path} {draw textext(decimal bbwidth (fullcircle xscaled 100 yscaled 200))} +\ShowSampleP {fm} {bbwidth path} {draw textext(decimal bbheight (fullcircle xscaled 100 yscaled 200))} + +\ShowSampleE {fm} {path/picture xsized numeric} {xsized 3cm} {currentpicture xsized 5cm} +\ShowSampleE {fm} {path/picture ysized numeric} {ysized 2cm} {currentpicture ysized 2cm} +\ShowSampleE {fm} {path/picture xysized numeric} {xysized (3cm,2cm)} {currentpicture xysized (3cm,2cm)} + +\ShowSampleP {fm} + {area path} + {draw area ((0,10)--(20,20)--(30,5)--(40,10)--(50,5)--(60,5))} + +\ShowSampleT {mp} + {setbounds picture} + {draw fullcircle ; setbounds currentpicture to unitsquare} + {draw fullcircle scaled .5 InGray; setbounds currentpicture to unitsquare scaled .5} + +\ShowSampleT {mm} + {clip path} + {fill fullcircle ; clip currentpicture to fullsquare scaled 0.9} + {fill fullcircle scaled 1 InRed ; clip currentpicture to fullsquare scaled 0.9} + +\ShowSampleT {mm} + {path peepholed path} + {fill (fullcircle peepholed fullsquare)} + {fill (fullcircle peepholed fullsquare) InRed} + +\ShowSampleT {fm} + {anchored} + {draw anchored.urt(textext("ll"),origin)} + {draw anchored.urt(textext("ll") xsized (5mm/Scale),origin) InRed ;} + +% \ShowSampleT {fm} +% {autoalign} +% {draw textext.autoalign(260)("260")} +% {draw textext.autoalign(260)("260")} + +% draw textext.autoalign(260)("\strut oeps 3") ; + +\ShowSampleX {fm} + {path crossingunder path} + {draw (fullsquare rotated 45) crossingunder fullsquare} + +\stopsection + +\startsection[title={Points}] + +\index{points} + +%ShowSampleF {mp} {center path} {fullcircle} {center fullcircle} +\ShowSampleF {mm} {top pair} {fullcircle} {top center fullcircle} +\ShowSampleF {mm} {bot pair} {fullcircle} {bot center fullcircle} +\ShowSampleF {mm} {lft pair} {fullcircle} {lft center fullcircle} +\ShowSampleF {mm} {rt pair} {fullcircle} {rt center fullcircle} +\ShowSampleF {mp} {point numeric of path} {fullcircle} {point 2 of fullcircle} +\ShowSampleF {fm} {point numeric on path} {fullcircle} {point .5 on fullcircle} +\ShowSampleF {fm} {point numeric along path} {fullcircle} {point 1cm along fullcircle} +\ShowSampleF {mp} {precontrol numeric of path} {fullcircle} {precontrol 2 of fullcircle} +\ShowSampleF {mp} {postcontrol numeric of path} {fullcircle} {postcontrol 2 of fullcircle} +\ShowSampleF {mp} {directionpoint pair of path} {fullcircle} {directionpoint (2,3) of fullcircle} + +\ShowSampleG {mc} {numeric[pair,pair]} {(1,1)} {.5[(0,0),(1,1)]} + +\ShowSampleH {mm} {path intersectionpoint path} {fullcircle} {fulldiamond} + {fullcircle intersectionpoint fulldiamond} + +\ShowSampleHH {mm} {interpath(numeric,path,path} + {interpath(.8,fullcircle,fullsquare)} + +\ShowSampleHH {fm} {interpolated(numeric,path,path} + {interpolated(.8,fullcircle,fullsquare)} + +\ShowSampleO {mm} {right} {draw left} +\ShowSampleO {mm} {up} {draw up} +\ShowSampleO {mm} {left} {draw left} +\ShowSampleO {mm} {down} {draw down} + +\stopsection + +\startsection[title={Colors}] + +\index{colors} + +\ShowSampleI {mp} {withcolor rgbcolor} {withcolor (.625,0,0)} +\ShowSampleI {mp} {withrgbcolor rgbcolor} {withrgbcolor (.625,0,0)} +\ShowSampleI {mp} {withcmykcolor cmykcolor} {withcmykcolor (.375,0,0,0)} +\ShowSampleI {mp} {withgray / withgrey numeric} {withgray .625} +\ShowSampleI {mp} {withcolor namedcolor} {withcolor namedcolor("darkblue")} +\ShowSampleI {mp} {withcolor spotcolor} {withcolor spotcolor("tempone",red/2)} +\ShowSampleI {mp} {withcolor multitonecolor} {withcolor .2 * multitonecolor("temptwo",blue/2,yellow/3)} + +Remark: at the time of this writing only Acrobat shows spot- and multitonecolors +properly. Possible indications of a viewing problem are factors not being applied +(in the page stream) or colors that are way off. + +\ShowSampleU {mp} {red} {fill fullcircle scaled 2 withcolor red/2} +\ShowSampleU {mp} {green} {fill fullcircle scaled 2 withcolor green/2} +\ShowSampleU {mp} {blue} {fill fullcircle scaled 2 withcolor blue/2} +\ShowSampleU {mp} {cyan} {fill fullcircle scaled 2 withcolor cyan/2} +\ShowSampleU {mp} {magenta} {fill fullcircle scaled 2 withcolor magenta/2} +\ShowSampleU {mp} {yellow} {fill fullcircle scaled 2 withcolor yellow/2} +\ShowSampleU {mp} {black} {fill fullcircle scaled 2 withcolor black/2} +\ShowSampleU {mp} {white} {fill fullcircle scaled 2 withcolor white/2} + +\ShowSampleU {mp} {blackcolor} {fill fullcircle withcolor blackcolor red} + +%ShowSampleI {fm} {withcolor cmyk(c,m,y,k)} {withcolor cmyk(0,.625,.625,0)} +%ShowSampleI {fm} {withcolor transparent(n.m,color)} {withcolor transparent(1,.625,red)} + +\ShowSampleI {fm} {withtransparency(num,num)} {withcolor red withtransparency (1,.625)} + +% \ShowSampleZ {fm} {withshade numeric} {Shades need to be declared before they can be (re)used.} + +\startMPinclusions + defineshade cshade withshademethod "circular" ; + defineshade lshade withshademethod "linear" ; +\stopMPinclusions + +\ShowSampleW {fm} {shaded someshade } + {fill fullsquare shaded lshade} + {fill fullsquare scaled 2cm shaded lshade} + +This assumes the definition: + +\starttyping +defineshade lshade withshademethod "linear" ; +\stoptyping + +\ShowSampleW {fm} {shaded someshade} + {fill fullcircle shaded cshade} + {fill fullcircle scaled 2cm shaded cshade} + +This assumes the definition: + +\starttyping +defineshade cshade withshademethod "circular" ; +\stoptyping + +% withshadefactor 1 +% withshadedomain (0,1) +% withshadecolors (black,white) +% withtransparency (1,.5) + +% \startMPcode +% fill fullcircle scaled 3cm +% shaded myshade +% withshadefactor 0.7 +% ; +% \stopMPcode + +% \startMPcode +% fill fullcircle scaled 3cm +% shaded myshade +% withshadecolors (red,green) +% withshadefactor 1 +% withtransparency (1,.75) +% ; +% \stopMPcode + +% \startMPcode +% fill fullcircle scaled 3cm +% shaded myshade ; +% withshadefactor 1 +% withshadedomain (0,1) +% withshadecolors (green,blue) +% withtransparency (1,.5) +% ; +% \stopMPcode + +% \startMPcode +% fill fullcircle scaled 3cm +% shaded myshade ; +% withshadefactor 1 +% withshadedomain (0,1) +% withcolor blue shadedinto yellow +% withtransparency (1,.5) +% ; +% \stopMPcode + +\ShowSampleV {mp} + {basiccolors} + {for i=0 upto 21 : fill ... withcolor basiccolors[i] ; endfor} + {for i=0 upto 21 : fill fullcircle shifted (i,0) withcolor basiccolors[i] ; endfor} + +\stopsection + +\startsection[title={Attributes}] + +\index{attributes} + +\ShowSampleII {mp} {dashed withdots} {dashed withdots} +\ShowSampleII {mp} {dashed evenly} {dashed evenly} +\ShowSampleII {mp} {dashed oddly} {dashed oddly} +\ShowSampleII {mp} {dashpattern} {dashed dashpattern (on .1 off .2 on .3 off .4)} +\ShowSampleII {mp} {undashed} {dashed evenly undashed} + +\ShowSampleJ {mm} {pencircle transform} {pencircle} +\ShowSampleJ {mm} {pensquare transform} {pensquare} +\ShowSampleJ {mm} {penrazor transform} {penrazor} +\ShowSampleK {mm} {penspeck transform} {penspeck} + +\ShowSampleL {mm} {draw} {fullcircle} +\ShowSampleL {mm} {fill} {fullcircle} +\ShowSampleL {mm} {filldraw} {fullcircle} +\ShowSampleL {mm} {drawfill} {fullcircle} +\ShowSampleL {mm} {drawdot} {origin} +\ShowSampleL {mm} {drawarrow} {fullcircle} +\ShowSampleL {mm} {drawdblarrow} {fullcircle} + +\ShowSampleL {fm} {eofill} {fullcircle} + +\ShowSampleM {mm} {undraw} {fullcircle} +\ShowSampleM {mm} {unfill} {fullcircle} +\ShowSampleM {mm} {unfilldraw} {fullcircle} +\ShowSampleM {mm} {undrawfill} {fullcircle} +\ShowSampleM {mm} {undrawdot} {origin} + +\ShowSampleQ {mm} {cutdraw} {origin--(1,1)} + +\ShowSampleN {mv} {butt} {linecap := butt} {(0,.5)--(.5,0)--(1,1)} +\ShowSampleN {mv} {rounded} {linecap := rounded} {(0,.5)--(.5,0)--(1,1)} +\ShowSampleN {mv} {squared} {linecap := squared} {(0,.5)--(.5,0)--(1,1)} + +\ShowSampleN {mv} {mitered} {linejoin := mitered} {(0,.5)--(.5,0)--(1,1)} +\ShowSampleN {mv} {rounded} {linejoin := rounded} {(0,.5)--(.5,0)--(1,1)} +\ShowSampleN {mv} {beveled} {linejoin := beveled} {(0,.5)--(.5,0)--(1,1)} + +\ShowSampleR {fm} {inverted picture} {inverted currentpicture} +\ShowSampleR {fm} {picture uncolored color} {currentpicture uncolored green} +\ShowSampleR {fm} {picture softened numeric} {currentpicture softened .8} +\ShowSampleR {fm} {picture softened color} {currentpicture softened (.7,.8,.9)} +\ShowSampleR {fm} {grayed picture} {grayed currentpicture} + +\stopsection + +\startsection[title={Text}] + +\index{text} + +\ShowSampleO {mm} {label} {label("MetaFun",origin)} +\ShowSampleO {mm} {label.top} {label.top("MetaFun",origin)} +\ShowSampleO {mm} {label.bot} {label.bot("MetaFun",origin)} +\ShowSampleO {mm} {label.lft} {label.lft("MetaFun",origin)} +\ShowSampleO {mm} {label.rt} {label.rt("MetaFun",origin)} +\ShowSampleO {mm} {label.llft} {label.llft("MetaFun",origin)} +\ShowSampleO {mm} {label.lrt} {label.lrt("MetaFun",origin)} +\ShowSampleO {mm} {label.urt} {label.urt("MetaFun",origin)} +\ShowSampleO {mm} {label.ulft} {label.ulft("MetaFun",origin)} + +\ShowSampleW {mp} {dotlabel} + {dotlabel.bot("\tttf metafun",(2cm,1cm))} + {dotlabel.bot("\tttf metafun",(2cm,1cm))} + +\ShowSampleW {mp} {dotlabels + range .. thru ..} + {z1 = ... ; dotlabels.bot(range 1 thru 3)} + {z1=(0,0); z2=(10mm,10mm); z3=(20mm,15mm); ; z4=(30mm,5mm); dotlabels.bot(range 1 thru 4)} + +\ShowSampleW {mp} {labels + range .. thru ..} + {z1 = ... ; labels.bot(range 1 thru 3)} + {z1=(0,0); z2=(10mm,10mm); z3=(20mm,15mm); ; z4=(30mm,5mm); labels.bot(range 1 thru 4)} + +\ShowSampleQQ {fm} + {thelabel(string,pair)} + {draw thelabel("MetaFun",(2cm,0))} + +\ShowSampleQQ {fm} + {formatted(string)} + {draw textext(formatted("@0.5f",1.234))} + +\ShowSampleQQ {fm} + {format(string) : graph package} + {draw textext(format("@5E-2",1.234))} + +\ShowSampleP {mp} + {btex text etex} + {draw btex MetaTeX etex} + +\ShowSampleQQ {fm} + {textext(string)} + {draw textext("MetaFun")} + +\ShowSampleQQ {fm} + {thetextext(string,pair)} + {draw thetextext("MetaFun",(2cm,0))} + +% \ShowSampleQQ {fm} +% {graphictext string ...} +% {graphictext "MetaFun"} + +\ShowSampleQQQ {fm} + {outlinetext.d("string")(d)} + {draw outlinetext.d("MetaFun")(InRed)} + +\ShowSampleQQQ {fm} + {outlinetext.f("string")(f)} + {draw outlinetext.f("MetaFun")(InYellow)} + +\ShowSampleQQQ {fm} + {outlinetext.b("string")(f)(d)} + {draw outlinetext.b("MetaFun")(InYellow)(InRed)} + +\ShowSampleQQQ {fm} + {outlinetext.r("string")(d)(f)} + {draw outlinetext.r("MetaFun")(InRed)(InYellow)} + +\ShowSampleUU {fm} + {outlinetext.p("string")} + {draw outlinetext.p("MetaFun")} + +\stopsection + +\startsection[title={Control}] + +\index{loops} + +\ShowSampleU {mp} {for (positive step) until} {for i=0 step 2 until 8: drawdot (i,0) ; endfor} +\ShowSampleU {mp} {for (negative step) until} {for i=6 step -2 until 0: drawdot (i,0) ; endfor} +\ShowSampleU {mm} {for upto} {for i=0 upto 12: drawdot (i,0) ; endfor} +\ShowSampleU {mm} {for downto} {for i=10 downto 0: drawdot (i,0) ; endfor} +\ShowSampleU {mm} {forsuffixes} {forsuffixes i=1,4,6,12: drawdot (i,0) ; endfor} + +\stopsection + +\startsection[title={Graphics}] + +\index{graphics} + +\ShowSampleS {fm} + {loadfigure string number numeric ...} + {loadfigure "mycow.mp" number 1 scaled .25} + +\ShowSampleS {fm} + {externalfigure string ...} + {draw externalfigure "mycow.pdf" scaled 3cm} + +\ShowSampleT {fm} {addbackground text} + {addbackground withcolor .625 yellow} + {fill fullcircle xyscaled (2,1) InRed; addbackground InYellow} + +\ShowSampleQQ {mm} {image (text)} + {draw image(draw fullcircle) xscaled 4cm yscaled 1cm} + +\ShowSampleT {mm} {decorated (text) text} + {draw decorated (....) withcolor red} + {draw decorated (fill fullcircle) InRed} + +\ShowSampleT {mm} {undecorated (text) text} + {draw undecorated (.... withcolor yellow) withcolor red} + {draw undecorated (fill fullcircle InYellow) InRed} + +\ShowSampleT {mm} {redecorated (text) text} + {draw redecorated (.... withcolor yellow) withcolor red} + {draw redecorated (fill fullcircle InYellow) InRed} + +\ShowSampleS {mm} + {bitmapimage (w,h,data)} + {draw bitmapimage (2,2,"114477AA") rotated 15 scaled 4cm} + +\ShowSampleT {mm} + {withmask string} + {draw externalfigure "m-1.png" scaled 2cm withmask "m-2.png"} + {Scale := 1 ; + draw externalfigure "m-2.png" scaled 2cm shifted (-3cm,0) ; + draw externalfigure "m-1.png" scaled 2cm shifted (-6cm,0) ; + draw externalfigure "m-1.png" scaled 2cm withmask "m-2.png"} + +\stopsection + +\stopchapter + +\stopcomponent + +%% draw leftpath fullcircle scaled 1cm withpen pencircle scaled 1mm withcolor .625red ; +%% draw reverse leftpath (reverse fullcircle scaled 2cm) withpen pencircle scaled 1mm withcolor .625yellow ; +%% draw rightpath fullcircle scaled 3cm withpen pencircle scaled 1mm withcolor .625white ; +%% +%% path p ; p := (0,0) .. (1,2) .. cycle ; +%% draw leftpath p scaled 1cm withpen pencircle scaled 1mm withcolor .625red ; +%% draw reverse leftpath (reverse p scaled 2cm) withpen pencircle scaled 1mm withcolor .625yellow ; +%% draw rightpath p scaled 3cm withpen pencircle scaled 1mm withcolor .625white ; diff --git a/doc/context/sources/general/manuals/metafun/metafun-sneaky.tex b/doc/context/sources/general/manuals/metafun/metafun-sneaky.tex new file mode 100644 index 000000000..02c502cf0 --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/metafun-sneaky.tex @@ -0,0 +1,60 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\startcomponent metafun-conventions + +\environment metafun-environment + +\startchapter[title={Conventions}] + +\startsection[title={Suffixes}] + +One characteristic of using \METAFUN\ in \CONTEXT\ is that it is basically one +long run. The code snippets become figures that then get converted to \PDF\ and +embedded. If text is involved, each figure is actually processed twice, once to +identify what needs to be typeset, and once with the result(ing metrics). +Normally that gets unnoticed. You can check for the state by consulting the +boolean \type {mfun_trial_run}. + +A consequence of the one run cq.\ multiple runs is that you need to be careful with +undefined or special variables. Consider the following: + +\starttyping +vardef foo@#(text t) = + save s ; string s ; s := str @# ; + if length(s) > 0 : + textext(s) + else : + nullpicture + fi +enddef ; +\stoptyping + +The following works ok in the first run when bar is undefined: + +\starttyping +draw foo.bar("a") ; +\stoptyping + +But if afterwards we say: + +\starttyping +vardef bar(expr x) = + 123 +enddef ; +\stoptyping + +and expand \type {foo.bar} again we will get an error message because this time +\type {bar} expands. Suffixes are always expanded! + +The lesson is: when you get unexpected results or errors, check your variable +definitions. You can use the \type {begingroup} and \type {endgroup} primitives +to protect your variables but then you also need to explicitly use \type {save} +to store their meanings and allocate new ones after that inside the group. + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/metafun/metafun-styles.tex b/doc/context/sources/general/manuals/metafun/metafun-styles.tex new file mode 100644 index 000000000..f82359117 --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/metafun-styles.tex @@ -0,0 +1,445 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\startcomponent metafun-styles + +\environment metafun-environment + +\startchapter[title={Defining styles}] + +\index {layout} +\index {styles} + +\startintro + +Since the integration of \METAPOST\ into \CONTEXT, a complete new range of layout +fetaures became available. In this document we have introduced several ways to +include graphics in your document definition. In this chapter we go one step +further and make dynamic graphics part of a document style. + +\stopintro + +\startsection[title={Adaptive buttons}] + +So far we have seen a lot of graphic ingredients that you can use to make your +documents more attractive. In this chapter we will define a simple document +style. This style was written for the \PDFTEX\ presentations at the TUG 2000 +conference in Oxford (UK). + +This style exploits a few tricks, like graphics calculated using positional +information. It also demonstrates how you can make menu buttons that dynamically +adapt their shapes to the rest of the page layout. + +\startbuffer[screens] +\startlinecorrection[blank] +\setupcombinations[distance=.0125\textwidth] +\startcombination[5*1] + {\typesetfile[mfun-77\ScrNum.tex][page=1,width=.19\textwidth]} {page 1} + {\typesetfile[mfun-77\ScrNum.tex][page=2,width=.19\textwidth]} {page 2} + {\typesetfile[mfun-77\ScrNum.tex][page=3,width=.19\textwidth]} {page 3} + {\typesetfile[mfun-77\ScrNum.tex][page=4,width=.19\textwidth]} {page 4} + {\typesetfile[mfun-77\ScrNum.tex][page=5,width=.19\textwidth]} {page 5} +\stopcombination +\stoplinecorrection +\stopbuffer + +\def\ScrNum{1} \getbuffer[screens] + +Later we will see an instance with some more randomness in the graphics. While +writing this style, the random alternative made me think of those organic +buildings with non equal windows |<|we have a few of those in The Netherlands|>|, +so I decided to label this style as \type {pre-organic}. If you use \CONTEXT, you +can load this style with: + +\starttyping +\usemodule[pre-organic] +\stoptyping + +At the end of this file, there is a small test file, so when you process the file +\type {s-pre-19.tex} \footnote {This style is the 19\high{th} presentation style. +Those numbered styles are internally mapped onto more meaningful names like in +this case \type {pre-organic}.} with the options \type {--mode=demo} and \type +{--pdf}, you will get a demo document. + +We use one of the standard screen \quote {paper} sizes, and map it onto the same +size, so that we get a nicely cropped page. Other screen sizes are \type {S4} and +\type {S5}. + +\starttyping +\setuppapersize[S6][S6] +\stoptyping + +Like in this \METAFUN\ manual, we use the Palatino as main bodyfont. This font is +quite readable on even low resolution screens, although I admit that this style +is developed using an $1400\times1050$ pixel \kap {lcd} screen, so the author may +be a little biased. + +\starttyping +\setupbodyfont[ppl] +\stoptyping + +The layout specification sets up a text area and a right edge area where the +menus will go (see \in {chapter} [sec:page] for a more in depth discussion on the +layout areas). Watch how we use a rather large edge distance. By setting the +header and footer dimensions to zero, we automatically get rid of page body +ornaments, like the page number. + +\starttyping +\setuplayout + [topspace=48pt, + backspace=48pt, + cutspace=12pt, + width=400pt, + margin=0cm, + rightedge=88pt, + rightedgedistance=48pt, + header=0cm, + footer=0cm, + height=middle] +\stoptyping + +We use a moderate, about a line height, inter||paragraph white space. + +\starttyping +\setupwhitespace[big] +\stoptyping + +Of course we use colors, since on computer displays they come for free. + +\starttyping +\setupcolors[state=start] + +\definecolor [red] [r=.75] +\definecolor [yellow] [r=.75,g=.75] +\definecolor [gray] [s=.50] +\definecolor [white] [s=.85] +\stoptyping + +Because it is an interactive document, we have to enable hyperlinks and alike. +However, in this style, we disable the viewer's \quote {highlight a hyperlink +when it's clicked on} feature. We will use a menu, so we enable menus. Later we +will see the contrast color |<|hyperlinks gets that color when we are already on +the location|>| in action. + +\starttyping +\setupinteraction + [state=start, + click=off, + color=red, + contrastcolor=gray, + menu=on] +\stoptyping + +The menu itself is set up as follows. Because we will calculate menu buttons +based on their position on the page, we have to keep track of the positions. +Therefore, we set the \type {position} variable to \type {yes}. + +\starttyping +\setupinteractionmenu + [right] + [frame=off, + position=yes, + align=middle, + topoffset=-.75cm, + bottomoffset=-.75cm, + color=gray, + contrastcolor=gray, + style=bold, + before=, + after=] +\stoptyping + +The menu content is rather sober: just a list of topics and a close button. Later +we will define the command that generates topic entries. The alternative \type +{right} lets the topic list inherit its characteristics from the menu. + +\starttyping +\startinteractionmenu[right] + \placelist[Topic][alternative=right] + \vfill + \but [CloseDocument] close \\ +\stopinteractionmenu +\stoptyping + +We have now arrived at the more interesting part of the style definition: the +graphic that goes in the page background. Because this graphic will change, we +define a useable \METAPOST\ graphic. Page backgrounds are recalculated each page, +opposite to the other backgrounds that are calculated when a new background is +defined, or when repetitive calculation is turned on. + +\starttyping +\setupbackgrounds [page] [background=page] +\defineoverlay [page] [\useMPgraphic{page}] +\setupMPvariables [page] [alternative=3] +\stoptyping + +We will implement three alternative backgrounds. First we demonstrate the +relatively simple super ellipsed one. The main complication is that we want the +button shapes to follow the right edge of the curve that surrounds the text. We +don't know in advance how many lines of text there will be in a button, and we +also don't know at what height it will end up. Therefore, we need to calculate +each button shape independently and for that purpose we need to know its position +(see \in {chapter} [sec:positioning]). In \in {figure} [fig:style] you can see +what lines we need in order to be calculate the button shapes. + +\startpostponing + +\startmode[screen] + \placefigure + [here][fig:style] + {The lines used to calculate the button shapes.} + {\externalfigure[mfun-774.pdf][page=1,height=.85\textheight]} +\stopmode + +\startnotmode[screen] + \placefigure + [here][fig:style] + {The auxiliary lines used to calculate the button shapes.} + {\rotate{\externalfigure[mfun-774.pdf][page=1,height=\textwidth]}} +\stopnotmode + +\page + +\stoppostponing + +We separate the calculation of the button shape from the rest by embedding it in +its own usable graphic container. The \type {StartPage}||\type {StopPage} pair +takes care of proper placement of the whole graphic. + +\starttyping +\startuseMPgraphic{page} + + \includeMPgraphic{rightsuperbutton} + + StartPage ; + + path p, q ; pickup pencircle scaled 3pt ; + + p := Field[Text][Text] enlarged 36pt superellipsed .90 ; + + fill Page withcolor \MPcolor{yellow} ; + fill p withcolor \MPcolor{white} ; + draw p withcolor \MPcolor{red} ; + + p := Field[Text][Text] enlarged 48pt superellipsed .90 ; + + def right_menu_button (expr nn, rr, pp, xx, yy, ww, hh, dd) = + if (pp>0) and (rr>0) : + q := rightsuperbutton(p,xx,yy,RightEdgeWidth,hh) ; + fill q withcolor \MPcolor{white} ; + draw q withcolor if rr=2 : \MPcolor{gray} + else : \MPcolor{red} fi ; + fi ; + enddef ; + + \MPmenubuttons{right} + + StopPage ; +\stopuseMPgraphic +\stoptyping + +The \TEX\ macro \type {\MPmenubuttons} expands into a list of (in this case four) +calls to the \METAPOST\ macro \type {right_menu_button}. This list is generated +by \CONTEXT\ when it generates the menu. Because the page background is applied +last, this list is available at that moment. + +\starttyping +... (expr nn, rr, pp, xx, yy, ww, hh, dd) ... +\stoptyping + +This rather long list of arguments represents the following variables: number, +referred page, current page, x coordinate, y coordinate, width, height and depth. +The last six variables originate from the positioning mechanism. Because the +variables are only available after a second \TEX\ pass, we only draw a button +shape when the test for the page numbers succeeds. + +\starttyping +\startuseMPgraphic{rightsuperbutton} + vardef rightsuperbutton (expr pat, xpos, ypos, wid, hei) = + + save p, ptop, pbot, t, b, edge, shift, width, height ; + path p, ptop, pbot ; pair t, b ; + numeric edge, shift, width, height ; + + edge := xpos + wid ; shift := ypos + hei ; + + p := rightpath pat ; + + ptop := ((-infinity,shift)--(edge,shift)) ; + pbot := ((-infinity,shift-hei)--(edge,shift-hei)) ; + + t := p intersectionpoint ptop ; + b := p intersectionpoint pbot ; + + p := subpath(0,xpart (p intersectiontimes ptop)) of p ; + p := subpath(xpart (p intersectiontimes pbot),length(p)) of p ; + + (p -- t -- point 1 of ptop & + point 1 of ptop -- point 1 of pbot & + point 1 of pbot -- b + -- cycle) + + enddef ; +\stopuseMPgraphic +\stoptyping + +The calculation of the button itself comes down to combining segments of the main +shape and auxiliary lines. The \type {rightpath} macro returns the right half of +the path provided. This half is shown as a non dashed line. + +Topics are identified with \type {\Topic}, which is an instance of chapter +headings. The number is made invisible. Since it still is a numbered section +header, \CONTEXT\ will write the header to the table of contents. + +\starttyping +\definehead [Topic] [chapter] +\setuphead [Topic] [number=no] +\stoptyping + +We will use a bold font in the table of contents. We also force a complete list. + +\starttyping +\setuplist + [Topic] + [criterium=all, + style=bold, + before=, + after=] +\stoptyping + +The \type {\TitlePage} macro looks horrible, because we want to keep the +interface simple: a list of small sentences, separated by \type {\\}. + +\starttyping +\def\TitlePage#1% + {\startstandardmakeup + \switchtobodyfont[big] + \def\\{\vfill\bfb\let\\=\par} + \bfd\setupinterlinespace\gray + \vskip.5cm#1\\\vskip.5cm % \\ is really needed -) + \stopstandardmakeup} +\stoptyping + +A presentation that uses this style, may look like the one below. You can choose +among three alternatives. + +\starttyping +\useenvironment[pre-organic] \setupoutput[pdftex] + +\setupMPvariables[page][alternative=1] + +\starttext + +\TitlePage + {A Few Nice Quotes\\ + A Simple Style Demo\\ + Hans Hagen, August 2000} + +\Topic {Douglas R. Hofstadter} \input douglas \page +\Topic {Donald E. Knuth} \input knuth \page +\Topic {Edward R. Tufte} \input tufte \page +\Topic {Hermann Zapf} \input zapf \page + +\stoptext +\stoptyping + +We will not implement the two other alternative shapes: squeezed and randomized. + +\def\ScrNum{2} \getbuffer[screens] +\def\ScrNum{3} \getbuffer[screens] + +We combine all alternatives into one page graphic. The alternative is chosen by +setting the \type {alternative} variable, as we demonstrated in the example. + +\starttyping +\startuseMPgraphic{page} + + \includeMPgraphic{rightsuperbutton} + + StartPage ; + + numeric alternative, seed, superness, squeezeness, randomness ; + path p, q ; transform t ; +\stoptyping + +This is one of those cases where a transform variable is useful. We need to store +the random seed value because we want the larger path that is used in the +calculations to have the same shape. + +\starttyping + alternative := \MPvar{alternative} ; + seed := uniformdeviate 100 ; + + if alternative > 10 : + superness := .85 + ((\realfolio-1)/max(\lastpage,1)) * .25 ; + squeezeness := 12pt - ((\realfolio-1)/max(\lastpage,1)) * 10pt ; + else : + superness := .90 ; + squeezeness := 12pt ; + fi ; + + randomness := squeezeness ; + + alternative := alternative mod 10 ; +\stoptyping + +If you read closely, you will notice that when we add 10 to the alternative, we +get a page dependant graphic. So, in fact we have five alternatives. We use +\CONTEXT\ macros to fetch the (real) page number and the number of the last page. +In further calculations we use the lower alternative numbers, which is why we +apply a \type {mod}. + +The rest of the code is not so much different from the previous definition. The +hard coded point sizes match the page dimensions (600pt by 450pt) quite well. + +\starttyping + t := identity if alternative=3: shifted (9pt,-9pt) fi ; + + randomseed := seed ; + + p := Field[Text][Text] enlarged if + alternative = 1 : 36pt superellipsed superness elseif + alternative = 2 : 36pt squeezed squeezeness elseif + alternative = 3 : 36pt randomized randomness else + : 36pt fi ; + + pickup pencircle scaled 3pt ; + + fill Page withcolor \MPcolor{yellow} ; + fill p withcolor \MPcolor{white} ; + draw p withcolor \MPcolor{red} ; + + randomseed := seed ; + + p := ( Field[Text][Text] enlarged if + alternative = 1 : 48pt superellipsed superness elseif + alternative = 2 : 48pt squeezed squeezeness elseif + alternative = 3 : 36pt randomized randomness else + : 48pt fi ) transformed t ; + + def right_menu_button (expr nn, rr, pp, xx, yy, ww, hh, dd) = + if (pp>0) and (rr>0) : + q := rightsuperbutton(p,xx,yy,RightEdgeWidth,hh) ; + fill q withcolor \MPcolor{white} ; + draw q withcolor if rr=2 : \MPcolor{gray} + else : \MPcolor{red} fi ; + fi ; + enddef ; + + \MPmenubuttons{right} + + StopPage ; +\stopuseMPgraphic +\stoptyping + +When we choose the alternatives~21 and~22 we get this result: + +\def\ScrNum{5} \getbuffer[screens] +\def\ScrNum{6} \getbuffer[screens] + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/metafun/metafun-syntax.tex b/doc/context/sources/general/manuals/metafun/metafun-syntax.tex new file mode 100644 index 000000000..9407b1dd0 --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/metafun-syntax.tex @@ -0,0 +1,1130 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +% eoclip: no postscript possible yet +% +% mpprocset mpxbreak + +% path expression -> path + +% listsize +% copylist +% sortlist +% shapedlist +% listtocurves +% listtolines + +\startcomponent metafun-syntax + +\environment metafun-environment + +\startchapter[title={\METAPOST\ syntax}] + +\index{syntax} +\index{language} + +\startintro + +In the \METAFONT\ book as well as the \METAPOST\ manual, you can find the exact +specification of the language. Below you find the full \METAPOST\ syntax, to +which we add the basic \METAFUN\ extensions. If this page looks too cryptic, you +can safely skip to the next chapter. We don't distinguish between primitives and +functionality defined in the \METAPOST\ format, simply because the core is kept +small and a macro package is supposed to extend that core. + +\stopintro + +% \startsection[title={Syntax diagrams}] + +The following syntax diagrams are derived from the diagrams in the \METAPOST\ +manual. The \mathematics {\rightarrow} represents \quote {means} and the +\mathematics {\vert} symbol stands for \quote {or}. + +The diagrams describe the hard coded \METAPOST\ syntax as well as most of the +macros and variables defined in the plain \METAPOST\ format that belongs to the +core of the system. They also include most of the fundamental \METAFUN\ commands. +We have omitted the \METAPOST\ and \METAFONT\ commands that make no sense any +more or are irrelevant for common usage. Specific \METAFUN\ modules are not +included here, only general tools, text helpers and extensions to the built||in +capabilities like transparency. If you feel that something is missing that should +be specified here, just let me know. + +\start \switchtobodyfont[8pt] % small] + +\StartSyntax +\S{atom} + \M \S{variable} \S{argument} + \O \S{number or fraction} + \O \S{internal variable} + \O \( \S{expression} \) + \O \L{begingroup} \S{statement list} \S{expression} \L{endgroup} + \O \S{nullary op} + \O \L{btex} \S{typesetting command} \L{etex} + % \O \L{verbatimtex} \S{typesetting command} \L{etex} + \O \S{pseudo function} +\StopSyntax + +\StartSyntax +\S{primary} + \M \S{atom} + \O \( \S{numeric expression} \L{,} \S{numeric expression} \) + \O \( \S{numeric expression} \L{,} \S{numeric expression} \L{,} \S{numeric expression} \) + \O \( \S{numeric expression} \L{,} \S{numeric expression} \L{,} \S{numeric expression} \L{,} \S{numeric expression} \) + \O \S{of operator} \S{expression} \L{of} \S{primary} + \O \S{numeric expression} \S{expression} \FL{along} \S{path expression} + \O \S{numeric expression} \S{expression} \FL{on} \S{path expression} + \O \S{unary op} \S{primary} + \O \L{str} \S{suffix} + \O \L{z} \S{suffix} + \O \S{numeric atom} \[ \S{expression} \L{,} \S{expression} \] + \O \S{scalar multiplication op} \S{primary} + \O \S{color expression} \FL{shadedinto} \S{color expression} + \O \S{picture expression} \FL{asgroup} \S{string expression} + \O \S{picture expression} \FL{onlayer} \S{string expression} +\StopSyntax + +\StartSyntax +\S{secondary} + \M \S{primary} + \O \S{secondary} \S{primary binop} \S{primary} + \O \S{secondary} \S{transformer} +\StopSyntax + +\StartSyntax +\S{tertiary} + \M \S{secondary} + \O \S{tertiary} \S{secondary binop} \S{secondary} +\StopSyntax + +\StartSyntax +\S{subexpression} + \M \S{tertiary} + \O \S{path expression} \S{path join} \S{path knot} +\StopSyntax + +\StartSyntax +\S{expression} + \M \S{subexpression} + \O \S{expression} \S{tertiary binop} \S{tertiary} + \O \S{path subexpression} \S{direction specifier} + \O \S{path subexpression} \S{path join} \L{cycle} +\StopSyntax + +\StartSyntax +\S{path knot} + \M \S{tertiary} +\StopSyntax + +\StartSyntax +\S{path join} + \M \L{--} + \O \S{direction specifier} \S{basic path join} \S{direction specifier} +\StopSyntax + +\StartSyntax +\S {direction specifier} + \M \S{empty} + \O \{ \L{curl} \S{numeric expression} \} + \O \{ \S{pair expression} \} + \O \{ \S{numeric expression} \L{,} \S{numeric expression} \} +\StopSyntax + +\StartSyntax +\S{basic path join} + \M \L{..} + \O \L{...} + \O \L{..} \S{tension} \L{..} + %O \L{..} \S{tension} \L{..} % check what got lost here + \O \L{..} \S{controls} \L{..} +\StopSyntax + +\StartSyntax % atleast added +\S{tension} + \M \L{tension} \S{numeric primary} + \O \L{tension} \L{atleast} \S{numeric primary} + \O \L{tension} \S{numeric primary} \L{and} \S{numeric primary} +\StopSyntax + +\StartSyntax +\S{controls} + \M controls \S{pair primary} + \O controls \S{pair primary} \L{and} \S{pair primary} +\StopSyntax + +\StartSyntax +\S{argument} + \M \S{symbolic token} +\StopSyntax + +\StartSyntax +\S{number or fraction} + \M \S{number} \L{/} \S{number} + \O \S{number} \Q{not followed by} \L{/} \S{number} +\StopSyntax + +\StartSyntax +\S{scalar multiplication op} + \M \L{+} \O \L{-} + \O \S{number or fraction} \Q{not followed by} \S{add op} \S{number} +\StopSyntax + +\StartSyntax +\S{transformer} + \M \L {rotated} \S {numeric primary} + \O \L {scaled} \S {numeric primary} + \O \L {shifted} \S {pair primary} + \O \L {slanted} \S {numeric primary} + \O \L {transformed} \S {transform primary} + \O \L {xscaled} \S {numeric primary} \O \L {yscaled} \S {numeric primary} \O \FL{xyscaled} \S {numeric or pair primary} + \O \L {zscaled} \S {pair primary} + \O \L {reflectedabout} \L \( \S{pair expression} \L{,} \S{pair expression} \) + \O \L {rotatedaround} \L \( \S{pair expression} \L{,} \S{numeric expression} \) + \O \FL{xsized} \S {numeric primary} \O \FL{ysized} \S {numeric primary} \O \FL{xysized} \S {numeric or pair primary} + \O \FL{blownup} \S {numeric or pair primary} + \O \FL{enlarged} \S {numeric or pair primary} + \O \FL{xstretched} \S {numeric primary} \O \FL{ystretched} \S{numeric primary} \O \FL{stretched} \S{numeric or pair primary} + \O \FL{shortened} \S {numeric or pair primary} + \O \FL{enlonged} \S {numeric or pair primary} + \O \FL{crossed} \S {numeric primary} + \O \FL{paralelled} \S {numeric primary} + \O \FL{curved} \S {numeric primary} + \O \FL{laddered} + \O \FL{leftenlarged} \S{numeric primary} \O \FL{llenlarged} \S{numeric primary} \O \FL{llmoved} \S{numeric primary} + \O \FL{rightenlarged} \S{numeric primary} \O \FL{lrenlarged} \S{numeric primary} \O \FL{lrmoved} \S{numeric primary} + \O \FL{topenlarged} \S{numeric primary} \O \FL{urenlarged} \S{numeric primary} \O \FL{urmoved} \S{numeric primary} + \O \FL{bottomenlarged} \S{numeric primary} \O \FL{ulenlarged} \S{numeric primary} \O \FL{ulmoved} \S{numeric primary} + \O \FL{randomized} \S{numeric or pair or color primary} + \O \FL{randomizedcontrols} \S{numeric or pair} + \O \FL{snapped} \S{numeric or pair primary} + \O \FL{cornered} \S{numeric or pair} + \O \FL{peepholed} \S{path expression} + \O \FL{smoothed} \S{numeric or pair} + \O \FL{squeezed} \S{numeric or pair primary} + \O \FL{superellipsed} \S{numeric primary} + \O \FL{randomshifted} \S{numeric or pair primary} + \O \FL{uncolored} \S{color primary} + \O \FL{softened} \S{numeric or color primary} + \O \FL{asgroup} \S{string primary} + \O \L {gobbled} \S{primary} + % + \O \FL {insideof} \S{path expression} + \O \FL {outsideof} \S{path expression} + \O \FL {crossinunder} \S{path expression} +\StopSyntax + +\StartSyntax +\S{numeric or pair primary} + \M \S{numeric primary} + \O \S{pair primary} +\StopSyntax + +\StartSyntax +\S{numeric or pair or color primary} + \M \S{numeric primary} + \O \S{pair primary} + \O \S{color primary} +\StopSyntax + +\StartSyntax +\S{numeric or color primary} + \M \S{numeric primary} + \O \S{color primary} +\StopSyntax + +\StartSyntax +\S{nullary op} + \M \L{false} \O \L{true} + \O \L{normaldeviate} + \O \L{nullpen} \O \L{nullpicture} \O \L{pencircle}% + \O \L{whatever} +\StopSyntax + +\StartSyntax +\S{unary op} + \M \S{type} + \O \L {ASCII} + \O \FL{asin} \O \FL{asinh} \O \FL{acos} \O \FL{acosh} \O \FL{atan} \O \L {cosd} \O \FL{cos} \O \FL{cosh} \O \FL{cot} \O \FL{cotd} \O \L {sind} \O \FL{sin} \O \FL{sinh} \O \FL{tand} \O \FL{tan} + \O \L {inverse} \O \FL{inv} \O \FL{invcos} \O \FL{invsin} \O \FL{invtan} + \O \FL{sqr} \O \L {sqrt} \O \L {pow} \O \FL{exp} \O \L {mexp} \O \L {mlog} \O \FL{ln} \O \FL{log} \O \L {uniformdeviate} + \O \L {abs} \O \L {round} \O \L {odd} \O \L {ceiling} \O \L {floor} + \O \L {dir} \O \L {angle} \O \L {length} \O \L {arclength} + \O \L {bbox} \O \FL{bbwidth} \O \FL{bbheight} + \O \L {bot} \O \L {lft} \O \L {rt} \O \L {top} \O \L {center} + \O \FL{colordecimals} \O \L {decimal} \O \FL{ddecimal} \O \FL{dddecimal} \O \FL{ddddecimal} \O \FL{condition} \O \FL{tostring} + \O \FL{boundingbox} \O \FL{outerboundingbox} \O \FL{innerboundingbox} \O \L {bbox} + \O \L {colorpart} \O {fontpart} \O \L {pathpart} \O \L {penpart} \O \L {textpart} \O \L {dashpart} + \O \L {redpart} \O \L {greenpart} \O \L {bluepart} \O \L {greypart} \O \L {graypart} + \O \L {cyanpart} \O \L {magentapart} \O \L {yellowpart} \O \L {blackpart} + \O \L {postscriptpart} \O \L {prescriptpart} + \O \L {clipped} \O \L {bounded} \O \L {stroked} \O \L {filled} \O \L {textual} + \O \FL{punked} \O \L{paralleled} + \O \FL{leftboundary} \O \FL{rightboundary} \O \FL{topboundary} \O \FL{bottomboundary} + \O \L {xpart} \O \L {xxpart} \O \L {xypart} \O \L {ypart} \O \L {yxpart} \O \L {yypart} + \O \L {oct} \O \L {hex} + \O \L {colortype} + \O \FL{grayed} \O \FL{greyed} + \O \L {llcorner} \O \L {lrcorner} \O \L {ulcorner} \O \L {urcorner} + \O \L {not} \O \L {known} \O \L {unknown} + \O \FL{blackcolor} \O \FL{whitecolor} \O \L {colormodel} + \O \L {char} \O \L {fontsize} + \O \L {cycle} \O \L {reverse} \O \L {counterclockwise} + \O \L {makepath} \O \L {makepen} + \O \L {unitvector} + \O \L {turningnumber} + \O \L {circularpath} \O \L {squarepath} \O \L {linearpath} + % maybe pseudo functions: + \O \FL{area} \O \FL{inverted} \O \FL{simplified} \O \FL{unspiked} +\StopSyntax + +\StartSyntax +\S{type} + \M \L{boolean} \O \L{numeric} \O \L{pair} \O \L{path} + \O \L{pen} \O \L{picture} \O \L{string} \O \L{transform} + \O \L{color} \O \L{cmykcolor} \O \FL {greycolor} \FL {graycolor}\O \L{rgbcolor} + \O \FL{property}\O \FL{transparency} + \O \L{outer} \O \L{inner} +\StopSyntax + +\StartSyntax +\S{primary binop} + \M \L{*} \O \L{/} \O \L{**} \O \L{and} + \O \L{dotprod} \O \L{div} \O \L{infont} \O \L{mod} +\StopSyntax + +\StartSyntax +\S{secondary binop} + \M \L{+} \O \L{-} \O \L{++} \O \L{+-+} \O \L{or} + \O \L{intersectionpoint} \O \L{intersectiontimes} +\StopSyntax + +\StartSyntax +\S{tertiary binop} + \M \L{&} \O \L{<} \O \L{<=} \O \L{<>} \O \L{=} \O \L{>} \O \L{>=} + \O \L{cutafter} \O \L{cutbefore} \O \FL{cutends} + \O \L{softjoin} +\StopSyntax + +\StartSyntax +\S{of operator} + \M \L{arctime} \O \L{direction} \O \L{directiontime} \O \L{directionpoint}% + \O \L{penoffset} \O \L{point} + \O \L{postcontrol} \O \L{precontrol} \O \L{subpath} \O \L{substring} + \O \L{takepower} +\StopSyntax + +\StartSyntax +\S{variable} + \M \S{predefined numeric variable} + \O \S{predefined path variable} + \O \S{predefined picture variable} + \O \S{predefined transform variable} + \O \S{predefined pair variable} + \O \S{predefined pen variable} + \O \S{predefined string variable} + \O \S{predefined dashpattern} + \O \S{predefined rgbcolor variable} + \O \S{predefined macro} + \O \S{tag} \S{suffix} +\StopSyntax + +\StartSyntax +\S{predefined numeric variable} + \M \FL{nothing yet} +\StopSyntax + +\StartSyntax +\S{predefined picture variable} + \M \FL{blankpicture} + \O \L{currentpicture} +\StopSyntax + +\StartSyntax +\S{predefined transform variable} + \M \L{identity} \O \L{currenttransform} +\StopSyntax + +\StartSyntax +\S{predefined path variable} + \M \FL{originpath} + \O \FL{fullcircle} \O \FL{fullsquare} \O \FL{fulldiamond} \O \FL{fulltriangle} + \O \FL{unitcircle} \O \FL{unitsquare} \O \FL{unitdiamond} \O \FL{unittriangle} + \O \FL{halfcircle} \O \FL{quartercircle} + \O \FL{llcircle} \O \FL{lrcircle} \O \FL{urcircle} \O \FL{ulcircle} + \O \FL{bcircle} \O \FL{tcircle} \O \FL{lcircle} \O \FL{rcircle} + \O \FL{triangle} + \O \FL{righttriangle} \O \FL{uptriangle} \O \FL{lefttriangle} \O \FL{downtriangle} + \O \FL{lltriangle} \O \FL{lrtriangle} \O \FL{urtriangle} \O \FL{ultriangle} + \O \L{cuttings} +\StopSyntax + +\StartSyntax +\S{predefined pair variable} + \M \L{right} \O \L{up} \O \L{left} \O \L{down} + \M \L{shadedright} \O \L{shadedup} \O \L{shadedleft} \O \L{shadeddown} +\StopSyntax + +\StartSyntax +\S{predefined pen variable} + \M \FL{pensquare} \O \FL{penrazor} \O \FL{penspec} + \O \L{currentpen} +\StopSyntax + +\StartSyntax +\S{predefined string variable} + \M \FL{EOF} + \O \FL{CRLF} \O \FL{crlf} + \O \FL{DQUOTE} \O \FL{dquote} \O \L{ditto} + \O \FL{SPACE} \O \FL{space} + \O \FL{PERCENT} \O \FL{percent} + \O \L{defaultfont} + \O \L{extra_beginfig} \O \L {extra_endfig} + \O \FL{pathconnectors} +\StopSyntax + +\StartSyntax +\S{predefined dashpattern} + \M \L{evenly} \O \FL{oddly} \O \L{withdots} +\StopSyntax + +\StartSyntax +\S{predefined rgbcolor variable} + \M \L{red} \O \L{green} \O \L{blue} \O \L{white} + \O \L{cyan} \O \L{magenta} \O \L{yellow} \O \L{black} + \O \L{background} + \O \FL{basiccolors} +\StopSyntax + +\StartSyntax +\S{predefined macro} + \M \FL{shipit} \O \FL{bye} + \O \FL{resetdrawoptions} + \O \FL{visualizepaths} \O \FL{naturalizepaths} +\StopSyntax + +\StartSyntax +\S{suffix} + \M \S{empty} + \O \S{suffix} \S{subscript} + \O \S{suffix} \S{tag} + \O \S{suffix parameter} +\StopSyntax + +\StartSyntax +\S{subscript} + \M \S{number} + \O \[ \S{numeric expression} \] +\StopSyntax + +\StartSyntax +\S{internal variable} + \M \L{ahangle} \O \L{ahlength} + \O \L{bboxmargin} \O \L{labeloffset} + \O \L{charcode} + \O \L{defaultcolormodel} \O \L{defaultpen} \O \L{defaultscale} + \O \L{linecap} \O \L{linejoin} \O \L{miterlimit} + \O \L{outputformat} \O \L{outputtemplate} \O \O \L{prologues} + \O \L{showstopping} \L{pausing} + \O \L{tracingoutput} \O \L{tracingcapsules} \O \L{tracingchoices} \O \L{tracingcommands} \O \L{tracingequations} + \O \L{tracinglostchars} \O \L{tracingmacros} \O \L{tracingonline} \O \L{tracingrestores} \O \L{tracingspecs} + \O \L{tracingstats} \O \L{tracingtitles} + \O \L{truecorners} \O \L{warningcheck} + \O \L{dotlabeldiam} + \O \L{day} \O \L{month} \O \L{year} \O \L{hour} \O \L{minute} \O \L{time} + \O \L{mm} \O \L{pt} \O \L{dd} \O \L{bp} \O \L{cm} \O \L{pc} \O \L{cc} \O \L{in} + \O \L{butt} \O \L{rounded} \O \L{squared} \O \L{mitered} \O \L{beveled} + \O \FL{pi} \O \FL{radian} \O \FL{eps} \O \FL{epsilon} + \O \FL{nocolormodel} \O \FL{greycolormodel} \O \FL{graycolormodel} \O \FL{rgbcolormodel} \O \FL{cmykcolormodel} + % \O \FL{shadefactor} + \O \FL{textextoffset} + \O \FL{maxdimensions} + \O \L{infinity} + \O \FL{charscale} + \O \FL{metapostversion} + \O \FL{normaltransparent} \O \FL{multiplytransparent} \O \FL{screentransparent} \O \FL{overlaytransparent} + \O \FL{softlighttransparent} \O \FL{hardlighttransparent} \O \FL{colordodgetransparent} \O \FL{colorburntransparent} + \O \FL{darkentransparent} \O \FL{lightentransparent} \O \FL{differencetransparent} \O \FL{exclusiontransparent} + \O \FL{huetransparent} \O \FL{saturationtransparent} \O \FL{colortransparent} \O \FL{luminositytransparent} + \O \S{symbolic token defined by \L{newinternal}} + \O \L{ahangle} \O \L{ahlength} + \O \L{bboxmargin} + \O \L{pen_bot} \O \L{pen_top} \O \L{pen_lft} \O \L{pen_rt} + \O \L{join_radius} + \O \L{crossingscale} \O \L{crossingoption} +\StopSyntax + +\StartSyntax +\S{pseudo function} + \M \L {min} \( \S{expression list} \)% + \O \L {max} \( \S{expression list} \) + \O \L {incr} \( \S{numeric variable} \)% + \O \L {decr} \( \S{numeric variable} \) + \O \L {dashpattern} \( \S{on/off list} \) + \O \L {interpath} \( \S{numeric expression} \L{,} \S{path expression} \L{,} \S{path expression} \) + \O \FL{interpolated} \( \S{numeric expression} \L{,} \S{path expression} \L{,} \S{path expression} \) + \O \L {buildcycle} \( \S{path expression list} \) + \O \L {thelabel} \S{label suffix} \( \S{expression} \L{,} \S{pair expression} \) + \O \FL{thefreelabel} \( \S{expression}\L{,} \S{pair expression} \L{,} \S{pair expression} \) + \O \FL{anglebetween} \( \S{path expression} \L{,} \S{path expression} \L{,} \S{expression} \) + \O \L {flex} \( \S{text} \) + \O \L {hide} \( \S{text} \) + \O \L {gobble} \S{primary} + \O \L {clearit} + \O \L {clearpen} + \O \L {clearxy} + \O \FL{pointarrow} \( \S{path expression} \L{,} \S{numeric or pair primary} \L{,} \S{numeric expression} \) + \O \FL{centerarrow} \( \S{path expression} \L{,} \S{numeric or pair primary} \L{,} \S{numeric expression} \) + \O \FL{leftarrow} \( \S{path expression} \L{,} \S{numeric or pair primary} \L{,} \S{numeric expression} \) + \O \FL{rightarrow} \( \S{path expression} \L{,} \S{numeric or pair primary} \L{,} \S{numeric expression} \) + \O \FL{paired} \( \S{numeric or pair} \)% + \O \FL{tripled} \( \S{numeric or color} \) + \O \FL{remappedcolor} \( \S{color expression} \) + \O \FL{superellipse} \( \S{numeric primary} \L{,} \S{numeric primary} \L{,} \S{numeric primary} \L{,} \L{numeric primary} \L{,} \N \L{numeric primary} \) + \O \FL{roundedsquare} \( \S{numeric primary} \L{,} \S{numeric primary} \L{,} \S{numeric primary} \) + \O \FL{tensecircle} \( \S{numeric primary} \L{,} \S{numeric primary} \L{,} \S{numeric primary} \) + \O \FL{tensepath} \( \S{path primary} \) + \O \FL{(constructed)function}% + \( \S{string expression} \)% + \( \S{string primary} \L{,} \S{string primary} \L{,} \S{numeric primary} \L{,} + \N \S{numeric primary} \L{,} \S{numeric primary} \) + \O \FL{straightfunction} \( \S{string primary} \L{,} \S{string primary} \L{,} \S{numeric primary} \L{,} \S{numeric primary} \L{,} + \N \S{numeric primary} \) + \O \FL{curvedfunction} \( \S{string primary} \L{,} \S{string primary} \L{,} \S{numeric primary} \L{,} \S{numeric primary} \L{,} + \N \S{numeric primary} \) + %\O \FL{punkedfunction} \( \S{string primary} \L{,} \S{string primary} \L{,} \S{numeric primary} \L{,} \S{numeric primary} \L{,} \S{numeric primary} \) + %\O \FL{tightfunction} \( \S{string primary} \L{,} \S{string primary} \L{,} \S{numeric primary} \L{,} \S{numeric primary} \L{,} \S{numeric primary} \) + \O \FL{constructedpairs} \( \S{string expression} \) \( \S{pair array} \) + \O \FL{straightpairs} \( \S{pair array} \) + \O \FL{curvedpairs} \( \S{pair array} \) + %\O \FL{punkedpairs} \( \S{pair array} \) + %\O \FL{tightpairs} \( \S{pair array} \) + \O \FL{constructedpath} \( \S{string expression} \) \( \S{text} \) + \O \FL{straightpath} \( \S{text} \) + \O \FL{curvedpath} \( \S{text} \) + %\O \FL{punkedpath} \( \S{text} \) + %\O \FL{tightpath} \( \S{text} \) + \O \FL{epsed} \S{numeric primary} + \O \FL{arrowhead} \S{path primary} + \O \FL{arrowpath} \S{path primary} + \O \FL{infinite} \S{path primary} + % + \O \FL{tolist} \( \S{pair array} \) \( \S{text} \) + \O \FL{topath} \( \S{pair array} \) \( \S{text} \) + \O \FL{tocycle} \( \S{pair array} \) \( \S{text} \) + \O \FL{pencilled} \( \S{path expression} \) \( \S{pen expression} \) +\StopSyntax + +\StartSyntax +\S{color expression} + \M \S{basic color expression} + \O \S{string primary} + \O \FL{namedcolor} \( \S{string primary} \) + \O \FL{spotcolor} \( \S{string primary} \L{,} \S{basic color expression} \) + \O \FL{multitonecolor} \( \S{string primary} \L{,} \S{basic color expression list} \) +\StopSyntax + +\StartSyntax +\S{basic color expression} + \M \S{rgb color expression} + \O \S{cmyk color expression} + \O \S{gray color expression} +\StopSyntax + +\StartSyntax +\S{basic color expression list} + \M \S{basic color expression} + \O \S{basic color expression list} \L{,} \S{basic color expression} +\StopSyntax + +\StartSyntax +\S{rgb color expression} + \M \S\( \S{numeric primary} \L{,} \S{numeric primary} \L{,} \S{numeric primary} \S\) +\StopSyntax + +\StartSyntax +\S{cmyk color expression} + \M \S\( \S{numeric primary} \L{,} \S{numeric primary} \L{,} \S{numeric primary} \L{,} \S{numeric primary} \S\) +\StopSyntax + +\StartSyntax +\S{gray color expression} + \M \S\( \S{numeric primary} \S\) + \O \S{numeric primary} +\StopSyntax + +\StartSyntax +\S{path expression list} + \M \S{path expression} + \O \S{path expression list} \L{,} \S{path expression} +\StopSyntax + +\StartSyntax +\S{on/off list} + \M \S{on/off list} \S{on/off clause} + \O \S{on/off clause} +\StopSyntax + +\StartSyntax +\S{on/off clause} + \M \L{on} \S{numeric tertiary} + \O \L{off} \S{numeric tertiary} +\StopSyntax + +\StartSyntax +\S{boolean expression} \M \S{expression} +\S{cmyk expression} \M \S{expression} +\S{color expression} \M \S{expression} +\S{numeric atom} \M \S{atom} +\S{numeric expression} \M \S{expression} +\S{numeric primary} \M \S{primary} +\S{numeric tertiary} \M \S{tertiary} +\S{numeric variable} \M \S{variable} \O \S{internal variable} +\S{pair expression} \M \S{expression} +\S{pair primary} \M \S{primary} +\S{path expression} \M \S{expression} +\S{path subexpression} \M \S{subexpression} +\S{pen expression} \M \S{expression} +\S{picture expression} \M \S{expression} +\S{picture variable} \M \S{variable} +\S{rgb expression} \M \S{expression} +\S{string expression} \M \S{expression} +\S{suffix parameter} \M \S{parameter} +\S{transform primary} \M \S{primary} +\StopSyntax + +\StartSyntax +\S{program} + \M \S{statement list} \L{end} +\StopSyntax + +\StartSyntax +\S{statement list} + \M \S{empty} + \O \S{statement list} \L{;} \S{statement} +\StopSyntax + +\StartSyntax +\S{statement} + \M \S{empty} + \O \S{equation} + \O \S{assignment} + \O \S{declaration} + \O \S{macro definition} + \O \S{compound} + \O \S{pseudo procedure} + \O \S{command} +\StopSyntax + +\StartSyntax +\S{compound} + \M \L{begingroup} \S{statement list} \L{endgroup} + \O \L{beginfig} \( \S{numeric expression} \) \L{;} \S{statement list} \S{;} \L{endfig} + \O \FL{beginglyph} \( \S{glyph property list} \) \L{;} \S{statement list} \S{;} \L{endglyph} + \O \L{image builder} \( \S{statement list} \) +\StopSyntax + +\StartSyntax +\S{image builder} + \M {image} \O \FL {decorated} \O \FL {redecorated} \O \FL {undecorated} +\StopSyntax + +\StartSyntax +\S{glyph property list} + \M \S{numeric expression} \L{,} \S{numeric expression} \L{,} \S{numeric expression} \L{,} \S{numeric expression} +\StopSyntax + +\StartSyntax +\S{equation} + \M \S{expression} \L{=} \S{right-hand side} +\StopSyntax + +\StartSyntax +\S{assignment} + \M \S{variable} \L{:=} \S{right-hand side} + \O \S{internal variable} \L{:=} \S{right-hand side} +\StopSyntax + +\StartSyntax +\S{right-and side} + \M \S{expression} + \O \S{equation} + \O \S{assignment} +\StopSyntax + +\StartSyntax +\S{declaration} + \M \S{type} \S{declaration list} +\StopSyntax + +\StartSyntax +\S{declaration list} + \M \S{generic variable} + \O \S{declaration list} \L{,} \S{generic variable} +\StopSyntax + +\StartSyntax +\S{generic variable} + \M \S{Symbolic token} \S{generic suffix} +\StopSyntax + +\StartSyntax +\S{generic suffix} + \M \S{empty} + \O \S{generic suffix} \S{tag} + \O \S{generic suffix} \L{[]} +\StopSyntax + +\StartSyntax +\S{macro definition} + \M \S{macro heading} \L{=} \S{replacement text} \L{enddef} +\StopSyntax + +\StartSyntax +\S{macro heading} + \M \L{def} \S{Symbolic token} \S{delimited part} \S{undelimited part} + \O \L{vardef} \S{generic variable} \S{delimited part} \S{undelimited part} + \O \L{vardef} \S{generic variable} \L{@#} \S{delimited part} \S{undelimited part} + \O \S{binary def} \S{parameter} \S {symbolic token} \S{parameter} +\StopSyntax + +\StartSyntax +\S{delimited part} + \M \S{empty} + \O \S{delimited part} \( \S{parameter type} \S{parameter tokens} \) +\StopSyntax + +\StartSyntax +\S{parameter type} + \M \L{expr} + \O \L{suffix} + \O \L{text} +\StopSyntax + +\StartSyntax +\S{parameter tokens} + \M \S{parameter} + \O \S{parameter tokens} \L{,} \S{parameter} +\StopSyntax + +\StartSyntax +\S{parameter} + \M \S{Symbolic token} +\StopSyntax + +\StartSyntax +\S{undelimited part} + \M \S{empty} + \O \S{parameter type} \S{parameter} + \O \S{precedence level} \S{parameter} + \O \L{expr} \S{parameter} \L{of} \S{parameter} +\StopSyntax + +\StartSyntax +\S{precedence level} + \M \L{primary} + \O \L{secondary} + \O \L{tertiary} +\StopSyntax + +\StartSyntax +\S{binary def} + \M \S{primarydef} + \O \S{secondarydef} + \O \S{tertiarydef} +\StopSyntax + +\StartSyntax +\S{pseudo procedure} + \M \L {drawoptions} \( \S{option list} \) + \O \L {label} \S{label suffix} \( \S{expression} \L{,} \S{pair expression} \) + \O \L {thelabel} \S{label suffix} \( \S{expression} \L{,} \S{pair expression} \) + \O \L {dotlabel} \S{label suffix} \( \S{expression} \L{,} \S{pair expression} \) + \O \L {makelabel} \S{makelabel} + \O \L {labels} \S{label suffix} \( \S{point number list} \) + \O \L {dotlabels} \S{label suffix} \( \S{point number list} \) + \O \FL{textext} \S{label suffix} \( \S{expression} \) + \O \FL{infotext} \S{label suffix} \( \S{expression}, \S{numeric expression} \) + \O \FL{thetextext} \S{label suffix} \( \S{expression}, \S{pair expression} \) + \O \FL{rawtextext} \( \S{expression} \) + \O \FL{verbatim} \S{string expression} + \O \FL{freelabel} \( \S{expression} \L{,} \S{pair expression} \L{,} \S{pair expression} \) + \O \FL{freedotlabel} \( \S{expression} \L{,} \S{pair expression} \L{,} \S{pair expression} \) + \O \FL{remapcolor} \( \S{color expression} \L{,} \S{color expression} \) + \O \FL{resetcolormap} + \O \FL{recolor} \S{picture expression} + \O \FL{bitmapimage} \( \S{numeric primary} \L{,} \S{numeric primary} \L{,} \S{string primary} \) + \O \FL{pushboundingbox} \O \FL{popboundingbox} + \O \FL{pushcurrentpicture} \O \FL{popcurrentpicture} + \O \FL{externalfigure} \S{string expression} \S{transformer} + \O \FL{loadfigure} \S{string expression} \L{number} \S{numeric expression} \S{transformer} + \O \FL{properties} + \O \L {anchored} \S{label suffix} \( \S{expression} \L{,} \S{pair expression} \) +\StopSyntax + +\StartSyntax +\S{point number list} + \M \S{suffix} \O \S{point number list} \L{,} \S{suffix} +\StopSyntax + +\StartSyntax +\S{label suffix} + \M \S{empty} + \O \L{lft} \O \L{rt}\O \L{top} \O \L{bot} \O \L{ulft} \O \L{urt}% + \O \L{llft} \O \L{lrt} \O \FL{raw} \O \FL{origin} +\StopSyntax + +\StartSyntax +\S{command} + \M \L{clip} \S{picture variable} \L{to} \S{path expression} + \O \L{interim} \S{internal variable} \L{:=} \S{right-hand side} + \O \L{let} \S{symbolic token} \L{=} \S{symbolic token} + \O \L{pickup} \S{expression} + \O \L{randomseed} \L{:=} \S{numeric expression} + \O \L{save} \S{symbolic token list} + \O \L{delimiters} \S{character} \S{character} + \O \L{setbounds} \S{picture variable} \L{to} \S{path expression} + \O \L{shipout} \S{picture expression} + \O \L{special} \S{string expression} + \O \L{endinput} + \O \L{expandafter} + \O \S{addto command} + \O \S{drawing command} + \O \S{font metric command} + \O \S{newinternal command} + \O \S{message command} + \O \S{mode command} + \O \S{show command} + \O \S{special command} + \O \S{tracing command} + \O \S{scantokens} \S{string expression} + \O \FL{defineshade} \S{symbolic token} \S{shading expression} + \O \L{write} \S{string expression} \L{to} \S{string expression} + \O \L{readfrom} \S{string expression} + \O \FL{readfile} \S{string expression} + \O \L{readstring} + \O \L{restoreclipcolor} + \O \L{savepen} + \O \L{runscript} + \O \L{relax} +\StopSyntax + +\StartSyntax +\S{show command} + \M \L{show} \S{expression list} + \O \L{showvariable} \S{symbolic token list} + \O \L{showtoken} \S{symbolic token list} + \O \L{showdependencies} +\StopSyntax + +\StartSyntax +\S{symbolic token list} + \M \S{symbolic token} + \O \S{symbolic token} \L{,} \S{symbolic token list} +\StopSyntax + +\StartSyntax +\S{expression list} + \M \S{expression} + \O \S{expression list} \L{,} \S{expression} +\StopSyntax + +\StartSyntax +\S{addto command} + \M \L{addto} \S{picture variable} \L{also} \S{picture expression} \S{option list} + \O \L{addto} \S{picture variable} \L{contour} \S{path expression} \S{option list} + \O \L{addto} \S{picture variable} \L{doublepath} \S{path expression} \S{option list} +\StopSyntax + +\StartSyntax +\S{option list} + \M \S{empty} + \O \S{drawing option} \S{option list} +\StopSyntax + +\StartSyntax +\S{drawing option} + \M \L {withcolor} \S{color expression}% + \O \FL {withgrey} \S{numeric expression}% + \O \FL {withgray} \S{numeric expression} + \O \L {withrgbcolor} \S{rgb expression}% + \O \L {withcmykcolor} \S{cmyk expression}% + \O \L {withgreyscale} \S{numeric expression} + \O \L {withoutcolor} + \O \L {withprescript} \S{string expression}% + \O \L {withpostscript} \S{string expression} + \O \L {withpen} \S{pen expression} + \O \L {dashed} \S{picture expression} + \O \FL{undashed} + \O \FL{withshade} \S{numeric expression} \O \FL{shaded} \S{shading expression} + \O \FL{withproperties} \S{property primary} + \O \FL{withtransparency} \S{pair primary} + \O \FL{withlinearshade} \(% + \S{path expression} \L{,}% + \S{path expression} \L{,}% + \S{color expression} \L{,}% + \S{color expression} \) + \O \FL{withcircularshade} \(% + \S{path ex} \L{,}% + \S{path ex} \L{,}% + \S{numeric ex} \L{,}% + \S{numeric ex} \L{,}% + \S{color ex} \L{,}% + \S{color ex} \) + \O \S{shading expression} + \O \FL{onlayer} \S{string expression} + \O \FL{withmask} \S{string expression} +\StopSyntax + +\StartSyntax +\S{property expression} + \M \( {drawing option} \) +\StopSyntax + +\StartSyntax +\S{shading expression} + \M \FL{withshademethod} \L{string expression} + \O \FL{withshadefactor} \L{numeric expression} + \O \FL{withshadedomain} \L{pair expression} + \O \FL{withshadevector} \L{pair expression} + \O \FL{withshaderadius} \L{pair expression} + \O \FL{withshadeorigin} \L{pair expression} + \O \FL{withshadecolors} \( \S{color expression} \L{,} \S{color expression} \) + \O \FL{withshadecenter} \L{pair expression} +\StopSyntax + +\StartSyntax +\S{drawing command} + \M \L{draw} \S{picture expression} \S{option list} + \O \S{fill type} \S{path expression} \S{option list} +\StopSyntax + +\StartSyntax +\S{fill type} + \M \L {fill} \O \L{unfill} \O \FL{refill} + \O \L {draw} \O \L{undraw} \O \FL{redraw} + \O \L {filldraw} \O \FL{drawfill} \O \L{undrawfill} \O \L{unfilldraw} + \O \FL{eofill} \O \FL{nofill} \O \FL{fillup} + \O \L {drawdot} + \O \L {drawarrow} \O \L{drawdblarrow} + \O \L {cutdraw} + \O \L {visualizer} + \O \FL{normaldraw} \O \FL{normalfill} +\StopSyntax + +\StartSyntax +\S{visualizer} + \M \FL{drawboundary} \O \FL{drawboundingbox} \O \FL{drawboundoptions} + \O \FL{drawcontrollines} \O \FL{drawcontroloptions} \O \FL{drawcontrolpoints} + \O \FL{drawlabeloptions} \O \FL{drawlineoptions} \O \FL{drawoptions} + \O \FL{draworigin} \O \FL{draworiginoptions} + \O \FL{drawpath} \O \FL{drawpathoptions} + \O \FL{drawpoint} \O \FL{drawpointlabels} \O \FL{drawpointoptions} + \O \FL{drawpoints} \O \FL{drawwholepath} + \O \FL{visualizeddraw} \O \FL{visualizedfill} +\StopSyntax + +\StartSyntax +\S{newinternal command} + \M \L{newinternal} \S{internal type} \S{symbolic token list} + \O \S{newinternal} \S{symbolic token list} +\StopSyntax + +\StartSyntax +\S{message command} + \M \L{errhelp} \S{string expression} + \O \L{errmessage} \S{string expression} + \O \L{filenametemplate} \S{string expression} + \O \L{message} \S{string expression} +\StopSyntax + +\StartSyntax +\S{mode command} + \M \L{batchmode} + \O \L{nonstopmode} + \O \L{scrollmode} + \O \L{errorstopmode} + \O \L{interact} +\StopSyntax + +\StartSyntax +\S{special command} + \M \L{fontmapfile} \S{string expression} + \O \L{fontmapline} \S{string expression} + \O \L{special} \S{string expression} + \O \L{input} \S{string expression} + \O \L{prologies} \S{numeric expression} + \O \L{outputtemplate} \S{string expression} + \O \L{outputformat} \S{string expression} +\StopSyntax + +\StartSyntax +\S{tracing command} + \M \L{tracingall} + \O \L{loggingall} + \O \L{tracingnone} +\StopSyntax + +\StartSyntax +\S{if test} + \M \L{if} \S{boolean expression} \L{:} \S{balanced tokens} \S{alternatives} \L{fi} +\StopSyntax + +\StartSyntax +\S{alternatives} + \M \S{empty} + \O \L{else} \L{:} \S{balanced tokens} + \O \L{elseif} \S{boolean expression} \S{:} \S{balanced tokens} \S{alternatives} + \O \L{exit} \O \L{exitif} \S{boolean expression} \O \L{exitunless} \S{boolean expression} + \O \L{break} +\StopSyntax + +\StartSyntax +\S{loop} + \M \S{loop header} \L{:} \S{loop text} \L{endfor} +\StopSyntax + +\StartSyntax +\S{loop header} + \M \L{for} \S{symbolic token} \L{=} \S{progression} + \O \L{for} \S{symbolic token} \L{=} \S{for list} + \O \L{for} \S{symbolic token} \L{within} \S{picture expression} + \O \L{forsuffixes} \S{symbolic token} \L{=} \S{suffix list} + \O \L{forever} +\StopSyntax + +\StartSyntax +\S{progression} + \M \S{numeric expression} \L{upto} \S{numeric expression} + \O \S{numeric expression} \L{downto} \S{numeric expression} + \O \S{numeric expression} \L{step} \S{numeric expression} \L{until} \S{numeric expression} + \O \L{range} \S{numeric expression} \L{thru} \S{numeric expression} +\StopSyntax + +\StartSyntax +\S{for list} + \M \S{expression} + \O \S{for list} \L{,} \S{expression} +\StopSyntax + +\StartSyntax +\S{suffix list} + \M \S{suffix} + \O \S{suffix list} \L{,} \S{suffix} +\StopSyntax + +\stop + +% \stopsection + +\stopchapter + +\stopcomponent + +% \startsection[title={Left overs}] + +% There are a few more concepts and commands available in \METAFUN, like color +% remapping, shading and graphic inclusion. Because they have their own small +% syntax world, we present them here. +% +% You may consider shades to be internally represented by a hidden datastructure. +% The end user has access to a shade by means of a pointer, expressed in a numeric. +% +% \start \switchtobodyfont[small] +% +% \StartSyntax +% \S{pseudo procedure} +% \M \FL{linear_shade}% +% \( \S{path expression} \L{,} \S{numeric expression}% +% \L{,} \S{color expression} \L{,} \S{color expression} \) +% \O \FL{circular_shade}% +% \( \S{path expression} \L{,} \S{numeric expression}% +% \L{,} \S{color expression} \L{,} \S{color expression} \) +% \StopSyntax +% +% \StartSyntax +% \S{pseudo function} +% \M \FL{define_linear_shade}% +% \( \S{pair expr} \L{,} \S{pair expr}% +% \L{,} \S{color expr} \L{,} \S{color expr} \) +% \O \FL{define_circular_shade}% +% \( \S{pair expr} \L{,} \S{pair expr}% +% \L{,} \S{path expr} \L{,} \S{path expr}% +% \L{,} \S{color expr} \L{,} \S{color expr} \) +% \O \FL{predefined_linear_shade}% +% \( \S{path expr} \L{,} \S{numeric expr}% +% \L{,} \S{color expr} \L{,} \S{color expr} \) +% \O \FL{predefined_circular_shade}% +% \( \S{path expr} \L{,} \S{numeric expr}% +% \L{,} \S{color expr} \L{,} \S{color expr} \) +% \StopSyntax +% +% \stop + +% External figures are just files, so the string passed as first argument needs to +% be a valid filename. Additionally, they need to be given dimensions. + +% \start \switchtobodyfont[small] +% +% \StartSyntax +% \S{pseudo procedure} +% \M \FL{externalfigure} \S{string expression} \S{transformer} +% \StopSyntax +% +% \stop + +% An external \METAPOST\ graphic can be loaded by filename and figure number. The +% normal transformations can be applied. +% +% \start \switchtobodyfont[small] +% +% \StartSyntax +% \S{pseudo procedure} +% \M \FL{loadfigure} \S{string expression} \L{number} \S{numeric expression} \S{transformer} +% \StopSyntax +% +% \stop + +% A graphic text is (normally) an outline representation of a snippet of text +% typeset by \TEX. This procedure has a couple of dedicated options. + +% \start \switchtobodyfont[small] + +% \StartSyntax +% \S{pseudo procedure} +% \M \FL{graphictext} \S{string expression} \S{transformer} \S{text option list} +% \O \FL{regraphictext} \S{transformer} \S{text option list} +% \StopSyntax + +% \StartSyntax +% \S{text option list} +% \M \S{empty} +% \O \S{text drawing option} \S{text option list} +% \StopSyntax + +% \StartSyntax +% \S{text drawing option} +% \M \S{drawing option} +% \O \FL{reversefill} +% \O \FL{outlinefill} +% \O \FL{withdrawcolor} \S{color expression} +% \O \FL{withfillcolor} \S{color expression} +% \StopSyntax + +% \StartSyntax +% \S{pseudo procedure} +% \M \FL{resetgraphictextdirective} +% \O \FL{graphictextdirective} \S {string expression} +% \StopSyntax + +% \StartSyntax +% \S{internal variable} +% \M \FL{graphictextformat} +% \StopSyntax + +% \stop + +% \stopsection + +% \stopchapter + +% \stopcomponent diff --git a/doc/context/sources/general/manuals/metafun/metafun-text.tex b/doc/context/sources/general/manuals/metafun/metafun-text.tex new file mode 100644 index 000000000..f70f53ac3 --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/metafun-text.tex @@ -0,0 +1,1784 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\startcomponent metafun-text + +\environment metafun-environment + +\startchapter[reference=sec:typesetting,title={Typesetting in \METAPOST}] + +\startintro + +It is said that a picture tells more than a thousand words. So you might expect +that text in graphics becomes superfluous. Out of experience we can tell you that +this is not the case. In this chapter we explore the ways to add text to +\METAPOST\ graphics, and let you choose whether or not to have it typeset by +\TEX. + +\stopintro + +\startsection[title={The process}] + +\index{text} + +You can let \METAPOST\ process text that is typeset by \TEX. Such text is first +embedded in the \METAPOST\ file in the following way: + +\starttyping +btex Some text to be typeset by \TEX etex +\stoptyping + +This returns a picture, but only after \METAPOST\ has made sure that \TEX\ has +converted it into something useful. This process of conversion is slightly system +dependent and even a bit obscure. Traditional \METAPOST\ calls a program that +filters the \type {btex}|\unknown|\type {etex} commands, next it calls \TEX\ by +passing the output routine, in order to make sure that each piece of text ends up +on its own page, and afterwards it again calls a program that converts the \DVI\ +pages into \METAPOST\ pictures. In \LUATEX's \MPLIB\ a different route is +followed. + +In \CONTEXT\ \MKII, when using \WEBC, you can generate the graphics at run||time. +This takes more time than processing the graphics afterwards, but has the +advantage that \TEX\ knows immediately what graphic it is dealing with. When +enabled, \CONTEXT\ will call either \METAPOST, or, when the graphic contains +\type {btex}||\type {etex} commands, call \TEXEXEC, which in turn makes sure that +the right auxiliary programs are executed. + +In \CONTEXT\ \MKIV\ you won't notice this at all because everything is tightly +integrated with \LUATEX's \MPLIB. This has an enormous speed gain: when this +manual had about 425 pages, on my laptop with mobile 3840QM processor, one run of +this document takes 18 seconds (14.5 with \LUAJITTEX) and that includes loadint a +bunch of (outline) fonts and processing some 2200 \METAPOST\ images. While +writing the first version of this manual runtime was upto 50 times slower for +half the number of pages so compared to \MKII\ we have gained a lot. + +\startFLOWchart[metatex] + \startFLOWcell + \name {script 1} + \location {1,1} + \shape {action} + \text {\type{context}} + \connection [rl] {context 1} + \stopFLOWcell + \startFLOWcell + \name {context 1} + \location {2,1} + \shape {action} + \text {\CONTEXT} + \connection [bt] {metapost 1} + \connection [rl] {script 2} + \stopFLOWcell + \startFLOWcell + \name {metapost 1} + \location {2,2} + \shape {action} + \text {\METAPOST} + \stopFLOWcell + \startFLOWcell + \name {script 2} + \location {3,1} + \shape {action} + \text {\type{context}} + \connection [rl] {context 2} + \connection [bt] {metapost 2} + \stopFLOWcell + \startFLOWcell + \name {context 2} + \location {4,1} + \shape {action} + \text {\CONTEXT} + \stopFLOWcell + \startFLOWcell + \name {metapost 2} + \location {3,2} + \shape {action} + \text {\METAPOST} + \stopFLOWcell +\stopFLOWchart + +\startplacefigure[title={How \TEX\ and \METAPOST\ work together.}] + \FLOWchart[metatex] +\stopplacefigure + +\stopsection + +\startsection[title={Environments}] + +\index{environments} + +In case you want to pass code that is shared by all \type {btex}||\type {etex} +pictures, \METAPOST\ provides: + +\starttyping +verbatimtex \DefineSomeCommands etex ; +\stoptyping + +However, in \CONTEXT\ one has a better mechanism available. In \CONTEXT\ \MKII\ +the advised method is passing environments. The best way to pass them is the +following. As an example we switch to the 15 basic \POSTSCRIPT\ fonts. + +\startbuffer[pos] +\startMPenvironment + \usetypescript[palatino][texnansi] % mkii has encodings + \setupbodyfont[palatino] +\stopMPenvironment +\stopbuffer + +\typebuffer[pos] + +This means that in code like the following, a Palatino font will be used. + +\starttyping +\startMPcode +draw btex Meta is a female lion! etex + xysized (\the\textwidth,\the\textheight) ; +\stopMPcode +\stoptyping + +However, in \CONTEXT\ \MKIV\ this method is no longer recomended as all +processing happens in the same run anyway. + +% beware: extensive scaling can make acrobat crash and okular drop the ! + +\startbuffer[lioncode] +\startMPcode +numeric w, h ; w := \the\textwidth ; h := w/2 ; + +picture p ; p := btex \colored[r=.375,g=.375]{Meta is a female lion!} etex + xysized (w,h) ; +picture q ; q := btex \colored[r=.625] {Meta is a female lion!} etex + xysized (w,h) ; + +path b ; b := boundingbox p ; draw p ; + +for i=(.28w,.90h),(.85w,.90h),(w,.05h) : + picture r ; r := q ; + path s ; s := (fullsquare xscaled .05w yscaled .4h) shifted i ; + clip r to s ; draw r ; % draw s ; +endfor ; + +setbounds currentpicture to b ; +\stopMPcode +\stopbuffer + +\typebuffer[lioncode] + +\in {Figure} [lionclip] shows the previous sentence in a slightly different look. +You may consider coloring the dots to be an exercise in clipping. + +\getbuffer[pos] + +\placefigure + [here][lionclip] + {An example of clipping.} + {\getbuffer[lioncode]} + +\resetMPenvironment + +An environment can be reset with \typ {\resetMPenvironment} or by passing \type +{reset} to \typ {\startMPenvironment}. + +\starttyping +\startMPenvironment[reset] + \usetypescript[postscript][texnansi] % mkii + \setupbodyfont[postscript] +\stopMPenvironment +\stoptyping + +So, to summarize: if you're using \CONTEXT\ \MKIV\ you might as well forgot what +you just read. + +\stopsection + +\startsection[title={Labels}] + +\index{labels} + +In \METAPOST\ you can use the \type {label} macro to position text at certain +points. + +\starttyping +label("x", origin) ; +\stoptyping + +The font and scale are determined by two variables, \type {defaultfont} and \type +{defaultscale}, the former expecting the name of a font in the form of a string, +the latter expecting a numeric to be used in the scaling of the font. Should you +choose not to set these yourself, they default to \type {"Mono"} and \type +{1.0}, respectively. However, you can change the defaults as follows: + +\starttyping +defaultfont := "texgyrepagella-regular*default" ; +defaultscale := 1.2 ; +\stoptyping + +These settings selects Pagella at about 12pt. You can also set these variables +to \CONTEXT\ related values. For \CONTEXT\ graphics they are set to: + +\starttyping +defaultfont := "\truefontname{Regular}*default" ; +defaultscale := \the\bodyfontsize/10 ; +\stoptyping + +This means that they will adapt themselves to the current body font (in this +document we get \truefontname{Regular}) and the current size of the bodyfont +(here \the\bodyfontsize/10). + +\stopsection + +\startsection[title={\TeX\ text}] + +\index{text} + +In the next example we will use a special mechanism for building graphics step by +step. The advantage of this method is that we can do intermediate calculations in +\TEX. Our objective is to write a macro that draws text along a circular path. +While doing so we want to achieve the following: + +\startitemize[packed] +\item the text should be properly kerned, i.e.\ the + spacing between characters should be optimal, +\item the position on the circle should vary, and +\item the radius of the circle should vary. +\stopitemize + +This implementation is not the most straightforward one, but by doing it step by +step, at least we see what is involved. Later, we will see a better method. If +you run these examples yourself, you must make sure that the \TEX\ environment of +your document matches the one used by \METAPOST. + +We let the bodyfont match the font used in this document, and define \type +{RotFont} to be the regular typeface, the one you are reading right now, but +bold. + +\startbuffer +\definefont[RotFont][RegularBold*default] +\stopbuffer + +\typebuffer \getbuffer + +Since \METAPOST\ is unaware of kerning, we have to use \TEX\ to keep track of the +positions. We will split the text into tokens (often characters) and store the +result in an array of pictures (\type {pic}). We will also store the accumulated +width in an array (\type {len}). The number of characters is stored in~\type {n}. +In a few paragraphs we will see why the other arrays are needed. + +While defining the graphic, we need \TEX\ to do some calculations. Therefore, we +will use \type {\startMPdrawing} to stepwise construct the definition. The basic +pattern we will follow is: + +\starttyping +\resetMPdrawing +\startMPdrawing + metapost code +\stopMPdrawing +tex code +\startMPdrawing + metapost code +\stopMPdrawing +\MPdrawingdonetrue +\getMPdrawing +\stoptyping + +In the process, we will use a few variables. We will store the individual +characters of the text in the variable \type {pic}, its width in \type {wid} and +the length of the string so far in \type {len}. Later we will use the \type {pos} +array to store the position where a character ends up. The variable \type {n} +holds the number of tokens. + +\startbuffer[init] +\resetMPdrawing +\startMPdrawing + picture pic[] ; + numeric wid[], len[], pos[], n ; + wid[0] := len[0] := pos[0] := n := 0 ; +\stopMPdrawing +\stopbuffer + +\typebuffer[init] + +We also started fresh by resetting the drawing. From now on, each start command +will add some more to this graphic. The next macro is responsible for collecting +the data. Each element is passed on to \TEX, using the \type {btex} construct. +So, \METAPOST\ itself will call \TEX ! + +\startbuffer[toks] +\def\whatever#1% + {\appendtoks#1\to\MPtoks + \setbox\MPbox=\hbox{\bfd\the\MPtoks}% + \startMPdrawing + n := n + 1 ; len[n] := \the\wd\MPbox ; + \stopMPdrawing + \startMPdrawing[-] + pic[n] := textext("\bfd\setstrut\strut#1") ; + pic[n] := pic[n] shifted - llcorner pic[n] ; + \stopMPdrawing} + +\handletokens MetaPost is Fun!\with\whatever +\stopbuffer + +\typebuffer[toks] + +We use the low level \CONTEXT\ macro \type {\appendtoks} to extend the token list +\type {\MPtoks}. The \type {\handletokens} macro passes each token (character) of +\typ {MetaPost is Fun!} to the macro \type {\whatever}. The tokens are appended +to the token register \type {\MPtoks} (already defined). Then we typeset the +content of \type {\MPtoks} in \type {\MPbox} (also already defined). The width of +the box is passed to \METAPOST\ and stored in \type {len}. + +By default the content of the drawing is expanded, which means that the macro is +replaced by its current meaning, so the current width ends up in the \METAPOST\ +file. The next part of the drawing, starting with \type {btex}, puts the token in +a picture. This time we don't expand the drawing, since we want to pass font +information. Here, the \type {[-]} suppresses expansion of \typ {btex \bfd #1 +etex}. The process is iterated by \type {\handletokens} for each character of the +text \typ {MetaPost is Fun!}. + +Before we typeset the text, now available in pieces in \type {pic}, in a circle, +we will first demonstrate what they look like. You may like to take a look at the +file \type {mpgraph.mp} to see what is passed to \METAPOST. + +\startbuffer[test] +\startMPdrawing + pair len ; len := origin ; + for i=1 upto n : + draw pic[i] shifted len ; + draw boundingbox pic[i] shifted len + withpen pencircle scaled .25pt withcolor red ; + len := len+(xpart urcorner pic[i]-xpart llcorner pic[i],0) ; + endfor ; +\stopMPdrawing +\stopbuffer + +\typebuffer[test] + +\startbuffer[show] +\MPdrawingdonetrue\getMPdrawing +\stopbuffer + +We can call up this drawing with \type {\getMPdrawing}, but first we inform the +compiler that our \METAPOST\ drawing is completed. + +\typebuffer[show] + +This results in: + +\startlinecorrection[blank] +\getbuffer[init,toks,test,show] +\stoplinecorrection + +Compare this text with the text as typeset by \TEX: + +\blank \start \bfd MetaPost is Fun!\par \stop \blank + +and you will see that the text produced by \METAPOST\ is not properly kerned. +When putting characters after each other, \TEX\ uses the information available in +the font, to optimize the spacing between characters, while \METAPOST\ looks at +characters as separate entities. But, since we have stored the optimal spacing in +\type {len}, we can let \METAPOST\ do a better job. Let's first calculate the +correction needed. + +\startbuffer[kern] +\startMPdrawing + for i=1 upto n : + wid[i] := abs(xpart urcorner pic[i] - xpart llcorner pic[i]) ; + pos[i] := len[i]-wid[i] ; + endfor ; +\stopMPdrawing +\stopbuffer + +\typebuffer[kern] + +This compares well to the text as typeset by \TEX: + +\blank \start \bfd MetaPost is Fun!\par \stop \blank + +We can now use the values in \type {pos} to position the pictures according to +what \TEX\ considered to be the best (relative) position. + +\startbuffer[test] +\startMPdrawing + for i=1 upto n : + draw pic[i] shifted (pos[i],0) ; + draw boundingbox pic[i] shifted (pos[i],0) + withpen pencircle scaled .25pt withcolor red ; + endfor ; +\stopMPdrawing +\stopbuffer + +\typebuffer[test] + +That this correction is adequate, is demonstrated in the next graphic. If you +look closely, you will see that for instance the \quote {o} is moved to the left, +under the capital \quote {P}. + +\startlinecorrection[blank] +\getbuffer[init,toks,kern,test,show] +\stoplinecorrection + +When we want to position the pictures along a circle, we need to apply some +rotations, especially because we want to go clockwise. Since we don't want to use +\quote {complicated} math or more advanced \METAPOST\ code yet, we will do it in +steps. + +\startbuffer[swap] +\startMPdrawing + for i=1 upto n: + pic[i] := pic[i] rotatedaround(origin,-270) ; + endfor ; +\stopMPdrawing +\stopbuffer + +\typebuffer[swap] + +\startlinecorrection[blank] +\getbuffer[init,toks,kern,swap,test,show] +\stoplinecorrection + +\startbuffer[cent] +\startMPdrawing + for i=1 upto n : + pic[i] := pic[i] + shifted (0,ypart -.5[ulcorner pic[i],llcorner pic[i]]) ; + endfor ; +\stopMPdrawing +\stopbuffer + +We will now center the pictures around the baseline. Centering comes down to +shifting over half the height of the picture. This can be expressed by: + +\starttyping +ypart -.5[ulcorner pic[i],llcorner pic[i]] +\stoptyping + +but different ways of calculating the distance are possible +too. + +\typebuffer[cent] + +So, now we have: + +\startlinecorrection[blank] +\getbuffer[init,toks,kern,swap,cent,test,show] +\stoplinecorrection + +When we typeset on a (half) circle, we should map the actual length onto a +partial circle. We denote the radius with an~\type {r} and shift the pictures to +the left. + +\startbuffer[shif] +\startMPdrawing + numeric r ; r := len[n]/pi ; + for i=1 upto n : + pic[i] := pic[i] shifted (-r,0) ; + endfor ; +\stopMPdrawing +\stopbuffer + +\typebuffer[shif] + +You can now use the following code to test the current state of the pictures. Of +course this code should not end up in the final definitions. + +\startbuffer[test] +\startMPdrawing + draw origin + withpen pencircle scaled 5pt withcolor red ; + for i=1 upto n : + draw pic[i] ; + draw boundingbox pic[i] + withpen pencircle scaled .25pt withcolor red ; + endfor ; +\stopMPdrawing +\stopbuffer + +\typebuffer[test] + +\startlinecorrection[blank] +\getbuffer[init,toks,kern,swap,cent,shif,test,show] +\stoplinecorrection + +Later we will write a compact, efficient macro to take care of rotation. However, +for the moment, so as not to overwhelm you with complicated code, we will rotate +each individual picture with the following code fragment. + +\startbuffer[rots] +\startMPdrawing + numeric delta, extra, radius, rot[] ; + + delta := extra := radius := 0 ; + + for i=1 upto n : + rot[i] := extra+delta-((pos[i]+.5wid[i])/len[n])*(180+2delta) ; + endfor ; +\stopMPdrawing +\stopbuffer + +\typebuffer[rots] + +Here we introduce a few variables that we can use later to tune the result a bit. +With \type {delta}, the space between the characters can be increased, while +\type {extra} rotates the whole string around the origin. The \type {radius} +variable can be used to increase the distance to the origin. Without these +variables, the assignment would have been: + +\starttyping +rot[i] := ((pos[i]+.5wid[i])/len[n])*180 ; +\stoptyping + +Placing the pictures is now rather easy: + +\startbuffer[done] +\startMPdrawing + for i=1 upto n : + draw pic[i] shifted (-radius,0) rotatedaround(origin,rot[i]) ; + endfor ; +\stopMPdrawing +\stopbuffer + +\typebuffer[done] + +The pictures are now positioned on half a circle, properly kerned. + +\startlinecorrection[blank] +\getbuffer[init,toks,kern,swap,cent,shif,rots,done,show] +\stoplinecorrection + +A bit more insight is given in the next picture: + +\startbuffer[test] +\startMPdrawing + def moved(expr i) = + shifted (-radius,0) rotatedaround(origin,rot[i]) + enddef ; + pickup pencircle scaled .5pt ; + for i=1 upto n : + draw pic[i] moved(i) ; + draw boundingbox pic[i] moved(i) withcolor red ; + draw origin -- center pic[i] moved(i) withcolor green ; + endfor ; + draw tcircle scaled 2r withcolor blue ; +\stopMPdrawing +\stopbuffer + +\startlinecorrection[blank] +\getbuffer[init,toks,kern,swap,cent,shif,rots,test,show] +\stoplinecorrection + +This was defined as follows. The path variable \type {tcycle} is predefined to +the top half of a fullcircle. + +\typebuffer[test] + +We will now package all of this into a nice, efficient macro, using, of course, +the predefined scratch registers \type {\MPtoks} and \type {\MPbox}. First we +define the token processor. Note again the expansion inhibition switch \type +{[-]}. + +\startbuffer +\def\processrotationtoken#1% + {\appendtoks#1\to\MPtoks + \setbox\MPbox=\hbox{\RotFont\the\MPtoks}% + \startMPdrawing + n := n + 1 ; len[n] := \the\wd\MPbox ; + \stopMPdrawing + \startMPdrawing[-] + pic[n] := textext("\RotFont\setstrut\strut#1") ; + pic[n] := pic[n] shifted - llcorner pic[n] ; + \stopMPdrawing} +\stopbuffer + +\typebuffer + +\getbuffer + +The main macro is a bit more complicated but by using a few scratch numerics, we +can keep it readable. + +\startbuffer +\def\rotatetokens#1#2#3#4% delta extra radius tokens + {\vbox\bgroup + \MPtoks\emptytoks + \resetMPdrawing + \startMPdrawing + picture pic[] ; + numeric wid, len[], rot ; + numeric delta, extra, radius, n, r ; + len[0] := n := 0 ; + delta := #1 ; extra := #2 ; radius := #3 ; + \stopMPdrawing + \handletokens#4\with\processrotationtoken + \startMPdrawing + r := len[n]/pi ; + for i=1 upto n : + wid := abs(xpart lrcorner pic[i] - + xpart llcorner pic[i]) ; + rot := extra + delta - + ((len[i]-.5wid)/len[n]) * (180+2delta) ; + draw pic[i] + rotatedaround (origin,-270) shifted (-r-radius, + ypart -.5[ulcorner pic[i], llcorner pic[i]]) + rotatedaround (origin,rot) ; + endfor ; + \stopMPdrawing + \MPdrawingdonetrue + \getMPdrawing + \resetMPdrawing + \egroup} +\stopbuffer + +\typebuffer + +\getbuffer + +\startbuffer +\startcombination[3*1] + {\rotatetokens {0} {0}{0}{Does it work ok?}} {A} + {\rotatetokens{20} {0}{0}{Does it work ok?}} {B} + {\rotatetokens{20}{30}{0}{Does it work ok?}} {C} +\stopcombination +\stopbuffer + +We can use this macro as follows: + +\typebuffer + +\startlinecorrection[blank] +\getbuffer +\stoplinecorrection + +The previous macro is not really an example of generalization, but we used it for +demonstrating how to build graphics in a stepwise way. If you put the steps in +buffers, you can even combine steps and replace them at will. This is how we made +the previous step by step examples: We put each sub||graphic in a buffer and then +called the ones we wanted. + +We now present a more general approach to typesetting along a given path. This +method is not only more robust and general, it is also a more compact definition, +especially if we omit the tracing and testing code. We use a familiar auxiliary +definition. The \type {\setstrut} and \type {\strut} commands ensure that the +lines have the proper depth and height. + +\startbuffer +\def\processfollowingtoken#1% + {\appendtoks#1\to\MPtoks + \setbox\MPbox=\hbox{\RotFont\setstrut\strut\the\MPtoks}% + \startMPdrawing + n := n + 1 ; len[n] := \the\wd\MPbox ; + \stopMPdrawing + \startMPdrawing[-] + pic[n] := btex \RotFont\setstrut\strut#1 etex ; + pic[n] := pic[n] shifted -llcorner pic[n] ; + \stopMPdrawing} +\stopbuffer + +\typebuffer \getbuffer + +In \MKII\ the previous code is collected in the macro \type {\followtokens} but +in \MKIV\ we use a different approach. There we use a mix of \TEX, \METAPOST, and +\LUA\ to define that macro. The principles remain the same but the code is more +robust. + +\input meta-imp-txt.mkiv % we need to force a reload \useMPlibrary[txt] + +So, how does this compare to earlier results? The original, full text as typeset +by \TEX, looks like: + +\blank \start \RotFont We now follow some arbitrary path ... \stop \blank + +In the examples, the text is typeset along the path with: + +\startbuffer[toks] +\followtokens{We now follow some arbitrary path ...} +\stopbuffer + +\typebuffer[toks] + +\startlinecorrection[blank] +\getbuffer[toks] +\stoplinecorrection + +Since we did not set a path, a dummy path is used. We can provide a path by +(re)defining the graphic \type {followtokens}. + +\startbuffer[trac] +\startMPinclusions + boolean TraceRot ; TraceRot := true ; +\stopMPinclusions +\stopbuffer + +\startbuffer[draw] +\startuseMPgraphic{followtokens} + path RotPath ; RotPath := fullcircle ; +\stopuseMPgraphic +\stopbuffer + +\startbuffer +\typebuffer[draw] +\startlinecorrection[blank] +\hbox + {\getbuffer[draw,toks]\hskip1cm + \getbuffer[trac,draw,toks]} +\stoplinecorrection +\stopbuffer + +\getbuffer + +\startbuffer[draw] +\startuseMPgraphic{followtokens} + path RotPath ; RotPath := reverse fullcircle ; +\stopuseMPgraphic +\stopbuffer + +\getbuffer + +\startbuffer[draw] +\startuseMPgraphic{followtokens} + path RotPath ; RotPath := (-3cm,-1cm)--(0,1cm)--(3cm,-1cm) ; +\stopuseMPgraphic +\stopbuffer + +\getbuffer + +\startbuffer[draw] +\startuseMPgraphic{followtokens} + path RotPath ; RotPath := (-3cm,0)--(3cm,1cm) ; +\stopuseMPgraphic +\stopbuffer + +\getbuffer + +\startbuffer[draw] +\startuseMPgraphic{followtokens} + path RotPath ; RotPath := (-3cm,0)..(-1cm,1cm)..(3cm,0) ; +\stopuseMPgraphic +\stopbuffer + +\getbuffer + +\startbuffer[draw] +\startuseMPgraphic{followtokens} + path RotPath ; RotPath := (-3cm,0)..(-1cm,1cm)..(0cm,-2cm)..(3cm,0) ; +\stopuseMPgraphic +\stopbuffer + +\getbuffer + +When turned on, tracing will produce bounding boxes as well as draw the path. +Tracing can be turned on by saying: + +\typebuffer[trac] + +% let's turn it off now + +\startMPinclusions + boolean TraceRot ; TraceRot := false ; +\stopMPinclusions + +The next example is dedicated to Giuseppe Bilotta who wants to handle multiple +strings and uses a patched version of \type {\followtokens}. To avoid a +complicated explanation, we will present an alternative here that uses overlays. +This method also avoids complicated path definitions. + +\startbuffer +\startoverlay + {\startuseMPgraphic{followtokens} + draw fullcircle scaled 5cm . + withpen pencircle scaled 1pt withcolor .625yellow ; + draw fullsquare scaled 5.25cm + withpen pencircle scaled 1pt withcolor .625red ; + drawoptions (withcolor .625red) ; + path RotPath ; RotPath := halfcircle scaled 5cm ; + setbounds currentpicture to boundingbox fullcircle scaled 5.25cm ; + \stopuseMPgraphic + \followtokens { Met{\`a} superiore }} + {\startuseMPgraphic{followtokens} + drawoptions (withcolor .625red) ; + path RotPath ; RotPath := halfcircle rotated 90 scaled 5cm ; + setbounds currentpicture to boundingbox fullcircle scaled 5.25cm ; + \stopuseMPgraphic + \followtokens { {$\star$} }} + {\startuseMPgraphic{followtokens} + drawoptions (withcolor .625red) ; + path RotPath ; RotPath := halfcircle rotated 180 scaled 5cm ; + setbounds currentpicture to boundingbox fullcircle scaled 5.25cm ; + \stopuseMPgraphic + \followtokens { Met{\`a} inferiore }} + {\startuseMPgraphic{followtokens} + drawoptions (withcolor .625red) ; + path RotPath ; RotPath := halfcircle rotated 270 scaled 5cm ; + setbounds currentpicture to boundingbox fullcircle scaled 5.25cm ; + \stopuseMPgraphic + \followtokens { {$\star$} }} +\stopoverlay +\stopbuffer + +\typebuffer + +In order to fool the overlay macro that each graphic has the same size, we force +a bounding box. + +\startlinecorrection[blank] +\getbuffer +\stoplinecorrection + +\stopsection + +\startsection[title={Talking to \TEX}] + +Sometimes, others may say oftentimes, we are in need for some fancy typesetting. +If we want to typeset a paragraph of text in a non standard shape, like a circle, +we have to fall back on \type {\parshape}. Unfortunately, \TEX\ is not that +strong in providing the specifications of more complicated shapes, unless you are +willing to do some complicated arithmetic \TEX. Given that \METAPOST\ knows how +to deal with shapes, the question is: \quotation {Can \METAPOST\ be of help?} + +In the process of finding out how to deal with this, we first define a simple +path. Because we are going to replace pieces of code, we will compose the graphic +from components. First, we create the path. + +\startbuffer +\startuseMPgraphic{text path} + path p ; p := ((0,1)..(-1,0)..(1,0)--cycle) scaled 65pt ; +\stopuseMPgraphic +\stopbuffer + +\typebuffer \getbuffer + +This shape is not that beautiful, but it has a few characteristics that will help +us to identify bordercases. + +\startbuffer +\startuseMPgraphic{text draw} + drawarrow p withpen pencircle scaled 1pt withcolor red ; +\stopuseMPgraphic +\stopbuffer + +\typebuffer \getbuffer + +Now we use \CONTEXT's \type {\includeMPgraphic} command to build our graphic from +the previously defined components. + +\startbuffer +\startuseMPgraphic{text} + \includeMPgraphic{text path} + \includeMPgraphic{text draw} +\stopuseMPgraphic +\stopbuffer + +\typebuffer \getbuffer + +When called with \type {\useMPgraphic{text}}, we get: + +\startlinecorrection[blank] +\useMPgraphic{text} +\stoplinecorrection + +For the moment we start the path at $(x=0,y>0)$, but later using more complicated +macros, we will see that we can use arbitrary paths. + +We are going to split the path in two, and will use the points that make up the +bounding box as calcutated by \METAPOST. The next graphic shows one of these +points, the lower left corner, available as point \typ {llcorner p}. + +\startbuffer +\startuseMPgraphic{text draw} + draw p withpen pencircle scaled 3pt withcolor red ; + draw boundingbox p withpen pencircle scaled 1pt ; + draw llcorner p withpen pencircle scaled 5pt ; +\stopuseMPgraphic +\stopbuffer + +\typebuffer \getbuffer + +\startlinecorrection[blank] +\useMPgraphic{text} +\stoplinecorrection + +The five points that \METAPOST\ can report for each path or picture are: + +\starttabulate[|Tl|l|] +\NC llcorner \NC lower left corner \NC \NR +\NC lrcorner \NC lower right corner \NC \NR +\NC urcorner \NC upper right corner \NC \NR +\NC ulcorner \NC upper left corner \NC \NR +\NC center \NC intersection of the diagonals \NC \NR +\stoptabulate + +If we want to typeset text inside this circle, we need to know where a line +starts and ends. Given that lines are horizontal and straight, we therefore need +to calculate the intersection points of the lines and the path. As a first step, +we calculate the top and bottom of the path and after that we split off the left +and right path. + +\startbuffer +\startuseMPgraphic{text split} + pair t, b ; path l, r ; + + t := (ulcorner p -- urcorner p) intersectionpoint p ; + b := (llcorner p -- lrcorner p) intersectionpoint p ; + + l := p cutbefore t ; l := l cutafter b ; + r := p cutbefore b ; r := r cutafter t ; +\stopuseMPgraphic +\stopbuffer + +\typebuffer \getbuffer + +The \type {intersectionpoint} macro returns the point where two paths cross. If +the paths don't cross, an error is reported, when the paths cross more times, +just one point is returned. The \type {cutafter} and \type {cutbefore} commands +do as their names say and return a path. + +In the \type {text split} code fragment, \type {t} and \type {b} are the top +points of the main path, while \type {l} and \type {r} become the left and right +half of path \type {p}. + +We now draw the original path using a thick pen and both halves with a thinner +pen on top of the original. The arrows show the direction. + +\startbuffer +\startuseMPgraphic{text draw} + draw p withpen pencircle scaled 3pt withcolor red ; + drawarrow l withpen pencircle scaled 1pt withcolor green ; + drawarrow r withpen pencircle scaled 1pt withcolor blue ; +\stopuseMPgraphic +\stopbuffer + +\typebuffer \getbuffer + +We use \type {\includeMPgraphic} to assemble the components: + +\startbuffer +\startuseMPgraphic{text} + \includeMPgraphic{text path} + \includeMPgraphic{text split} + \includeMPgraphic{text draw} +\stopuseMPgraphic +\stopbuffer + +\typebuffer \getbuffer + +This graphic is typeset with \type {\useMPgraphic{text}}: + +\startlinecorrection[blank] +\useMPgraphic{text} +\stoplinecorrection + +Before we are going to use them, we define some variables that specify the text. +We use a baseline distance of 8~points. The part of the line above the baseline +is 7.2~points, while the (maximum) depth is 2.8~points. These ratios are the ones +we use in \CONTEXT. Because we don't want the text to touch the circle so we +define an offset too. + +\startbuffer +\startuseMPgraphic{text vars} + baselineskip := 8pt ; + strutheight := (7.2/10) * baselineskip ; + strutdepth := (2.8/10) * baselineskip ; + offset := baselineskip/2 ; + topskip := strutheight ; +\stopuseMPgraphic +\stopbuffer + +\typebuffer \getbuffer + +We more or less achieve the offset by scaling the path. In doing so, we use the +width and height, which we call \type {hsize} and \type {vsize}, thereby +conforming to the \TEX\ naming scheme. + +First we calculate both dimensions from the bounding box of the path. Next we +down scale the path to compensate for the offset. When done, we recalculate the +dimensions. + +\startbuffer +\startuseMPgraphic{text move} + pair t, b ; path q, l, r ; + + hsize := xpart lrcorner p - xpart llcorner p ; + vsize := ypart urcorner p - ypart lrcorner p ; + + q := p xscaled ((hsize-2offset)/hsize) + yscaled ((vsize-2offset)/vsize) ; + + hsize := xpart lrcorner q - xpart llcorner q ; + vsize := ypart urcorner q - ypart lrcorner q ; +\stopuseMPgraphic +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\startuseMPgraphic{text split} + t := (ulcorner q -- urcorner q) intersectionpoint q ; + b := (llcorner q -- lrcorner q) intersectionpoint q ; + + l := q cutbefore t ; l := l cutafter b ; + r := q cutbefore b ; r := r cutafter t ; +\stopuseMPgraphic +\stopbuffer + +We adapt the \type {text split} code to use the reduced path +instead of the original. + +\typebuffer \getbuffer + +\startbuffer +\startuseMPgraphic{text draw} + drawarrow p withpen pencircle scaled 1pt withcolor red ; + draw t withpen pencircle scaled 2pt ; + draw b withpen pencircle scaled 2pt ; + drawarrow l withpen pencircle scaled 1pt withcolor green ; + drawarrow r withpen pencircle scaled 1pt withcolor blue ; +\stopuseMPgraphic +\stopbuffer + +In order to test what we have reached so far, we draw the original path, the left +and right part of the reduced path, and both the top and bottom point. + +\typebuffer \getbuffer + +Again we use \type {\includeMPgraphic} to combine the +components into a graphic. + +\startbuffer +\startuseMPgraphic{text} + \includeMPgraphic{text path} \includeMPgraphic{text vars} + \includeMPgraphic{text move} \includeMPgraphic{text split} + \includeMPgraphic{text draw} +\stopuseMPgraphic +\stopbuffer + +\typebuffer \getbuffer + +Then we use \type {\useMPgraphic{text}} to call up the picture. + +\startlinecorrection[blank] +\useMPgraphic{text} +\stoplinecorrection + +The offset is not optimal. Note the funny gap at the top. We could try to fix +this, but there is a better way to optimize both paths. + +We lower the top edge of \type {q}'s bounding box by \type {topskip}, then cut +any part of the left and right pieces of \type {q} that lie above it. Similarly, +we raise the bottom edge and cut off the pieces that fall below this line. + +\startbuffer +\startuseMPgraphic{text cutoff} + path tt, bb ; + + tt := (ulcorner q -- urcorner q) shifted (0,-topskip) ; + bb := (llcorner q -- lrcorner q) shifted (0,strutdepth) ; + + l := l cutbefore (l intersectionpoint tt) ; + l := l cutafter (l intersectionpoint bb) ; + r := r cutbefore (r intersectionpoint bb) ; + r := r cutafter (r intersectionpoint tt) ; +\stopuseMPgraphic +\stopbuffer + +\typebuffer \getbuffer + +Because we use \type {\includeMPgraphic} to construct the graphic, we can +redefine \type {text draw} to show the result of this effort. + +\startbuffer +\startuseMPgraphic{text draw} + drawarrow p withpen pencircle scaled 1pt withcolor red ; + drawarrow l withpen pencircle scaled 1pt withcolor green ; + drawarrow r withpen pencircle scaled 1pt withcolor blue ; +\stopuseMPgraphic +\stopbuffer + +\typebuffer \getbuffer + +The \type {text} graphic now becomes: + +\startbuffer +\startuseMPgraphic{text} + \includeMPgraphic{text path} \includeMPgraphic{text vars} + \includeMPgraphic{text move} \includeMPgraphic{text split} + \includeMPgraphic{text cutoff} \includeMPgraphic{text draw} +\stopuseMPgraphic +\stopbuffer + +\typebuffer \getbuffer + +Or, as graphic: + +\startlinecorrection[blank] +\useMPgraphic{text} +\stoplinecorrection + +We are now ready for an attempt to calculate the shape of the text. For each +line, we have to calculate the left and right intersection points, and since a +line has a height and depth, we have to determine which part touches first. + +\startbuffer +\startuseMPgraphic{text calc} + vardef found_point (expr lin, pat, sig) = + pair a, b ; + a := pat intersection_point (lin shifted (0,strutheight)) ; + if intersection_found : + a := a shifted (0,-strutheight) ; + else : + a := pat intersection_point lin ; + fi ; + b := pat intersection_point (lin shifted (0,-strutdepth)) ; + if intersection_found : + if sig : + if xpart b > xpart a : a := b shifted (0,strutdepth) fi ; + else : + if xpart b < xpart a : a := b shifted (0,strutdepth) fi ; + fi ; + fi ; + a + enddef ; +\stopuseMPgraphic +\stopbuffer + +\typebuffer \getbuffer + +Instead of using \METAPOST's \type {intersectionpoint} macro, we use one that +comes with \CONTEXT. That way we don't get an error message when no point is +found, and can use a boolean flag to take further action. Since we use a \type +{vardef}, all calculations are hidden and the~\type {a} at the end is returned, +so that we can use this macro in an assignment. The \type {sig} variable is used +to distinguish between the beginning and end of a line (the left and right +subpath). + +\startbuffer +\startuseMPgraphic{text step} + path line; pair lll, rrr ; + + for i=topskip step baselineskip until vsize : + + line := (ulcorner q -- urcorner q) shifted (0,-i) ; + + lll := found_point(line,l,true ) ; + rrr := found_point(line,r,false) ; +\stopuseMPgraphic +\stopbuffer + +\typebuffer \getbuffer + +Here we divide the available space in lines. The first line starts at \type +{strutheight} from the top. + +We can now finish our graphic by visualizing the lines. Both the height and depth +of the lines are shown. + +\startbuffer +\startuseMPgraphic{text line} + fill (lll--rrr--rrr shifted (0,strutheight)--lll + shifted (0,strutheight)--cycle) withcolor .5white ; + fill (lll--rrr--rrr shifted (0,-strutdepth)--lll + shifted (0,-strutdepth)--cycle) withcolor .7white ; + draw lll withpen pencircle scaled 2pt ; + draw rrr withpen pencircle scaled 2pt ; + draw (lll--rrr) withpen pencircle scaled .5pt ; +\stopuseMPgraphic + +\startuseMPgraphic{text done} + endfor ; +\stopuseMPgraphic +\stopbuffer + +\typebuffer \getbuffer + +The result is still a bit disappointing. + +\startbuffer +\startuseMPgraphic{text} + \includeMPgraphic{text path} \includeMPgraphic{text vars} + \includeMPgraphic{text move} \includeMPgraphic{text split} + \includeMPgraphic{text cutoff} \includeMPgraphic{text draw} + \includeMPgraphic{text calc} \includeMPgraphic{text step} + \includeMPgraphic{text line} \includeMPgraphic{text done} +\stopuseMPgraphic +\stopbuffer + +\typebuffer \getbuffer +\startlinecorrection[blank] +\useMPgraphic{text} +\stoplinecorrection + +In order to catch the overflow at the bottom, we need to change the \type +{for}||loop a bit, so that the number of lines does not exceed the available +space. The test that surrounds the assignment of \type {vvsize} makes sure that +we get better results when we (on purpose) take a smaller height. + +\startbuffer +\startuseMPgraphic{text step} + path line; pair lll, rrr ; numeric vvsize ; + + if (strutheight+strutdepth<baselineskip) : + vvsize := vsize ; + else : + vvsize := (vsize div baselineskip) * baselineskip ; + fi ; + + for i=topskip step baselineskip until vvsize : + + line := (ulcorner q -- urcorner q) shifted (0,-i) ; + + lll := found_point(line,l,true ) ; + rrr := found_point(line,r,false) ; +\stopuseMPgraphic +\stopbuffer + +\typebuffer \getbuffer + +\startlinecorrection[blank] +\useMPgraphic{text} +\stoplinecorrection + +We can manipulate the heigth and depth of the lines to give different (and maybe +better) results. + +\startbuffer +\startuseMPgraphic{text vars} +baselineskip := 8pt ; +strutheight := 4pt ; +strutdepth := 2pt ; +offset := 4pt ; +topskip := 3pt ; +\stopuseMPgraphic +\stopbuffer + +\typebuffer \getbuffer + +\startlinecorrection[blank] +\useMPgraphic{text} +\stoplinecorrection + +This kind of graphic trickery in itself is not enough to get \TEX\ into +typesetting within the bounds of a closed curve. Since \METAPOST\ can write +information to a file, and \TEX\ can read such a file, a natural way to handle +this is to let \METAPOST\ write a \type {\parshape} specification. + +\startbuffer +\startuseMPgraphic{text macro} + def provide_parshape (expr p, offset, baselineskip, + strutheight, strutdepth, topskip) = + + \includeMPgraphic{text move} + \includeMPgraphic{text split} + \includeMPgraphic{text cutoff} + \includeMPgraphic{text draw} + \includeMPgraphic{text calc} + \includeMPgraphic{text loop} + \includeMPgraphic{text save} + + enddef ; +\stopuseMPgraphic +\stopbuffer + +\typebuffer \getbuffer + +We have to adapt the for||loop to register the information about the lines. After +the loop we write those values to a file using another loop. + +\startbuffer +\startuseMPgraphic{text loop} + path line; pair lll, rrr ; numeric vvsize, n ; n := 0 ; + + if (strutheight+strutdepth<baselineskip) : + vvsize := vsize ; + else : + vvsize := (vsize div baselineskip) * baselineskip ; + fi ; + + for i=topskip step baselineskip until vvsize : + + line := (ulcorner q -- urcorner q) shifted (0,-i) ; + + lll := found_point(line,l,true ) ; + rrr := found_point(line,r,false) ; + + n := n + 1 ; + + indent[n] := abs(xpart lll - xpart llcorner q) ; + width[n] := abs(xpart rrr - xpart lll) ; + + endfor ; +\stopuseMPgraphic + +\startuseMPgraphic{text save} + write "\parshape " & decimal n to "mfun-mp-data.txt" ; + for i=1 upto n: + write decimal indent[i]&"bp " & + decimal width[i]&"bp " to "mfun-mp-data.txt" ; + endfor ; + write EOF to "mfun-mp-data.txt" ; +\stopuseMPgraphic +\stopbuffer + +\typebuffer \getbuffer + +We can call this macro using the part we used in the previous examples. + +\startbuffer +\startuseMPgraphic{text} + \includeMPgraphic{text macro} + + path p ; p := ((0,1)..(-1,0)..(1,0)--cycle) scaled 65pt ; + + provide_parshape + (p, % shape path + .5*\baselinedistance, % offset + \baselinedistance, % distance between lines + \strutheight, % height of a line + \strutdepth, % depth of a line + \strutheight) ; % height of first line +\stopuseMPgraphic +\stopbuffer + +\typebuffer \getbuffer + +After we called \type {\useMPgraphic{text}}, the resulting file looks as follows. +You can call up this file by its anonymous name \type {\MPdatafile}, since this +macro gets the value of the graphic at hand. + +\startnointerference + \useMPgraphic{text} +\stopnointerference + +\typefile{mfun-mp-data.txt} + +% \blank{\em todo: mp data file}\blank +% \writestatus{!!!!}{todo: mp data file} + +So, reading in this file at the start of a paragraph will setup \TEX\ to follow +this shape. + +The final implementation is a bit more complicated since it takes care of paths +that are not centered around the origin and don't start at the top point. We +achieve this by moving the path to the center: + +\starttyping +cp := center p ; q := p shifted - cp ; +\stoptyping + +The arbitrary starting point is taken care of by a slightly more complicated path +cutter. First we make sure that the path runs counterclockwise. + +\starttyping +if xpart directionpoint t of q < 0 : q := reverse q fi ; +\stoptyping + +Knowing this, we can split the path in two, using a slightly different splitter: + +\starttyping +l := q cutbefore t ; +l := l if xpart point 0 of q < 0 : & q fi cutafter b ; +r := q cutbefore b ; +r := r if xpart point 0 of q > 0 : & q fi cutafter t ; +\stoptyping + +As always, when implementing a feature like this, some effort goes into a proper +user interface. In doing so, we need some \TEX\ trickery that goes beyond this +text, like collecting text and splitting of the part needed. Also, we want to be +able to handle multiple shapes at once, like the next example demonstrates. + +\stopsection + +\startsection[title={Libraries}] + +\index{graphics+libraries} + +The macro discussed in the previous section is included in one of the \METAPOST\ +libraries, so we first have to say: + +\startbuffer +\useMPlibrary[txt] +\stopbuffer + +\typebuffer + +\getbuffer + +We define four shapes. They are not really beautiful, but they demonstrate what +happens in border cases. For instance, too small first lines are ignored. First +we define a circle. Watch how the dimensions are set in the graphic. The +arguments passed to \type {build_parshape} are: path, an offset, an additional +horizontal and vertical displacement, the baseline distance, the height and depth +of the line, and the height of the first line (topskip in \TEX\ terminology). The +height and depth of a line are often called strut height and depth, with a strut +being an invisible character with maximum dimensions. + +\startbuffer +\startuseMPgraphic{test 1} + path p ; p := fullcircle scaled 6cm ; + + build_parshape(p,6pt,0,0,\baselinedistance, + \strutheight,\strutdepth,\strutheight) ; + + draw p withpen pencircle scaled 1pt ; +\stopuseMPgraphic +\stopbuffer + +\typebuffer \getbuffer + +The second shape is a diamond. This is a rather useless shape, unless the text +suits the small lines at the top and bottom. + +\startbuffer +\startuseMPgraphic{test 2} + path p ; p := fullsquare rotated 45 scaled 5cm ; + + build_parshape(p,6pt,0,0,\baselinedistance, + \strutheight,\strutdepth,\strutheight) ; + + draw p withpen pencircle scaled 1pt ; +\stopuseMPgraphic +\stopbuffer + +\typebuffer \getbuffer + +The third and fourth shape demonstrate that providing a suitable offset is not +always trivial. + +\startbuffer +\startuseMPgraphic{test 3} + numeric w, h ; w := h := 6cm ; + path p ; p := (.5w,h) -- (0,h) -- (0,0) -- (w,0) & + (w,0) .. (.75w,.5h) .. (w,h) & (w,h) -- cycle ; + + build_parshape(p,6pt,0,0,\baselinedistance, + \strutheight,\strutdepth,\strutheight) ; + + draw p withpen pencircle scaled 1pt ; +\stopuseMPgraphic +\stopbuffer + +\typebuffer \getbuffer + +Contrary to the first three shapes, here we use a different path for the +calculations and the drawing. Watch carefully! If, instead of an offset, we pass +a path, \METAPOST\ is able to calculate the right dimensions and offsets. This is +needed, since we need these later on. + +\startbuffer +\startuseMPgraphic{test 4} + numeric w, h, o ; + + def shape = (o,o) -- (w-o,o) & (w-o,o) .. (.75w-o,.5h) .. + (w-2o,h-o) & (w-2o,h-o) -- (o,h-o) -- cycle + enddef ; + + w := h := 6cm ; o := 6pt ; path p ; p := shape ; + w := h := 6cm ; o := 0pt ; path q ; q := shape ; + + build_parshape(p,q,6pt,6pt,\baselinedistance, + \strutheight,\strutdepth,\strutheight) ; + + draw q withpen pencircle scaled 1pt ; +\stopuseMPgraphic +\stopbuffer + +\typebuffer \getbuffer + +Since we also want these graphics as backgrounds, we define them as overlays. If +you don't want to show the graphic, you may omit this step. + +\startbuffer +\defineoverlay[test 1][\useMPgraphic{test 1}] +\defineoverlay[test 2][\useMPgraphic{test 2}] +\defineoverlay[test 3][\useMPgraphic{test 3}] +\defineoverlay[test 4][\useMPgraphic{test 4}] +\stopbuffer + +\typebuffer \getbuffer + +As text, we use a quote from Douglas R.~Hofstadter's book \quotation {Metamagical +Themas, Questing for the Essence of Mind and Pattern}. Watch how we pass a list +of shapes. + +\startbuffer[text] +\startshapetext[test 1,test 2,test 3,test 4] + \forgetall % as it says + \setupalign[verytolerant,stretch,normal]% + \input douglas % Douglas R. Hofstadter +\stopshapetext +\stopbuffer + +\typebuffer[text] + +Finally we combine text and shapes. Since we also want a background, we use \type +{\framed}. The macros \type {\parwidth} and \type {\parheight} are automatically +set to the current shape dimensions. The normal result is shown in \in {figure} +[fig:shapes]. + +\startbuffer[shapes] +\startbuffer +\setupframed + [offset=overlay,align=normal,frame=off, + width=\parwidth,height=\parheight] +\startcombination[2*2] + {\framed[background=test 1]{\getshapetext}} {test 1} + {\framed[background=test 2]{\getshapetext}} {test 2} + {\framed[background=test 3]{\getshapetext}} {test 3} + {\framed[background=test 4]{\getshapetext}} {test 4} +\stopcombination +\stopbuffer +\stopbuffer + +\typebuffer[shapes] + +\getbuffer[shapes] + +By using a buffer we keep \type {\placefigure} readable. + +\startbuffer[a] +\placefigure + [here][fig:shapes] + {A continuous text, typeset in a non||standard shape, + spread over four areas, and right aligned.} + {\getbuffer} +\stopbuffer + +\startbuffer[b] +\placefigure + [here][fig:shapes] + {A continuous text, typeset in a non||standard shape, + spread over four areas.} + {\scale[factor=max,height=.9\textheight]{\getbuffer}} +\stopbuffer + +\typebuffer[a] + +\doifmodeelse{screen}{\getbuffer[text,b]}{\getbuffer[text,a]} + +The traced alternative is shown in \in {figure} [fig:traced shapes]. This one is +defined as: + +\startbuffer[a] +\placefigure + [here][fig:traced shapes] + {A continuous text, typeset in a non||standard shape, + spread over four areas (tracing on).} + {\startMPinclusions + boolean trace_parshape ; trace_parshape := true ; + \stopMPinclusions + \getbuffer} +\stopbuffer + +\startbuffer[b] +\placefigure + [here][fig:traced shapes] + {A continuous text, typeset in a non||standard shape, + spread over four areas (tracing on).} + {\startMPinclusions + boolean trace_parshape ; trace_parshape := true ; + \stopMPinclusions + \scale[factor=max,height=.9\textheight]{\getbuffer}} +\stopbuffer + +\typebuffer[a] + +\doifmodeelse{screen}{\getbuffer[text,b]}{\getbuffer[text,a]} + +% {\em This mechanism is still somewhat experimental and will be optimized and +% extended with name spaces and more.} + +\blank + +We can combine all those tricks, although the input is somewhat fuzzy. First we +define a quote typeset in a circular paragraph shape. + +\startbuffer[shape] +\startuseMPgraphic{center} + build_parshape(fullcircle scaled 8cm,0,0,0,\baselinedistance, + \strutheight,\strutdepth,\strutheight) ; +\stopuseMPgraphic + +\startshapetext[center] + \input douglas +\stopshapetext + +\defineoverlay[center][\useMPgraphic{center}] +\stopbuffer + +\typebuffer[shape] + +We will surround this text with a circular line, that we define as follows. By +using a buffer we keep things organized. + +\startbuffer +\startbuffer[circle] +\startuseMPgraphic{followtokens} + path RotPath ; RotPath := reverse fullcircle + rotatedaround(origin,90) + xscaled \overlaywidth yscaled \overlayheight ; + drawoptions (withcolor .625red) ; +\stopuseMPgraphic + +\followtokens + {This is just a dummy text, kerned by \TeX\ and typeset + in a circle using \MetaPost.\quad} +\stopbuffer + +\defineoverlay[edge][{\getbuffer[circle]}] +\stopbuffer + +\typebuffer \getbuffer + +The text and graphics come together in a framed text: + +\startbuffer +\startbuffer[quote] +\framed + [offset=24pt, + background=edge, + frame=off, + backgroundoffset=-18pt] + {\getshapetext} +\stopbuffer + +\placefigure + {One more time Hofstadter's quotation (normal).} + {\getbuffer[shape,quote]} + +\placefigure + {One more time Hofstadter's quotation (traced).} + {\startMPinclusions + boolean TraceRot ; TraceRot := true ; + \stopMPinclusions + \getbuffer[shape,quote]} +\stopbuffer + +\typebuffer \getbuffer + +% {\em Here also, I will rewrite things a bit so that we can avoid \type +% {\startMPdrawing} outside the macro, and thereby avoid problems. I can also add +% the maps cdrom cover as example.} + +\stopsection + +% \startsection[title={Visualizing \TEX}] +% +% The next example is a bit out of place in this manual, but nevertheless +% demonstrates how one can use \METAPOST\ to get insight in what \TEX\ is doing +% inside. +% +% The author of \PDFTEX, \THANH, has extended the paragraph builder with a +% provision for protruding characters and glyphs substitution, also known as {\it +% hz} (which stands for Hermann Zapf). The {\it hz} optimization involves an +% additional pass over the lines and|/|or paragraph, in order to determine how +% inconsistency in gaps can be reduced by substituting an \quote {\scale [sx=1.01] +% {a}} by an \quote {\scale [sx=5] {a}} or \quote {\scale [sx=.5] {a}}. In \in +% {figure} [fig:hz] you can find the visualization in action. By means of colors we +% indicate in what way glyphs are substituted by slightly larger or smaller values. +% More details on how the {\it hz} optimization works can be found in \THANH's +% thesis. +% +% \placefigure +% [page][fig:hz] +% {When we feed \TEX\ code into \METAPOST\ and back, we +% can visualize {\it hz}||optimization in a colorful way.} +% {\doifmodeelse{screen} +% {\externalfigure[mfun-hzs.pdf][height=.8\textheight]} +% {\externalfigure[mfun-hzp.pdf][height=.8\textheight]}} +% +% In order to avoid a complicated discussion about how to set up \PDFTEX\ to use +% {\it hz} |<|this can best be left over to the macro package that you use|>| we +% will illustrate the method behind this kind of visualizations in a more simple +% case. +% +% When you include a \METAPOST\ graphic in \PDFTEX, the output produced by +% \METAPOST\ is interpreted by a bunch of macros and converted into raw \PDF\ code. +% In the process special extensions, like shading, transparency, graphic inclusion, +% are taken care of. When the converter encounters a font inclusion directive, +% i.e.\ the \POSTSCRIPT\ \type {fshow} operator, it uses the \TEX\ font handler to +% take care of the font. A benefit of this approach is that \TEX\ and \METAPOST\ +% share the same font resources and therefore the inclusion is done in the way +% expected. +% +% The low level macro that takes care of the font inclusion provides a couple of so +% called hooks, that permit us to do additional manipulations with the character +% sequences that are encountered. +% +% \startbuffer[demo] +% draw +% btex \definedfont[cmr10]% +% Combine the power of \TeX\ and \MetaPost ! +% etex scaled 2 ; +% \stopbuffer +% +% \typebuffer[demo] +% +% When processed, this gives the graphic: +% +% \startlinecorrection[blank] +% \processMPbuffer[demo] +% \stoplinecorrection +% +% The result is not spectacular, and there is no indication that \METAPOST\ has +% been in action. The following line of code sets the hook \type {\MPfshowcommand} +% |<|this commands takes one argument|>| to produce a ruled horizontal box. +% +% \startbuffer +% \let\MPfshowcommand\ruledhbox +% \stopbuffer +% +% \typebuffer +% +% \startlinecorrection[blank] +% \getbuffer \processMPbuffer[demo] +% \stoplinecorrection +% +% If you watch closely, you will see that the ruled boxes contain one or more +% characters (or more precise glyphs). This is a result from \TEX\ explicitely +% kerning characters. +% +% A second hook is provided in the macro that takes care of the font switch. This +% command is defined as follows: +% +% \starttyping +% \def\setMPfshowfont#1#2% +% {\font\temp=#1\space at #2\relax\temp} +% \stoptyping +% +% The first argument is the raw font name, and the second argument specifies the +% desired size. If we want to see what fonts are involved, we can redefine the +% hooks as follows. +% +% \starttyping +% \def\setMPfshowfont#1#2% +% {\message{[using #1 at #2 in mp graphic]}% +% \font\temp=#1\space at #2\relax\temp} +% \stoptyping +% +% It happens that two fonts are used: \type {cmr10} and \type {logo10}. Once we +% know this, we can apply some magic: we set the color to the fontname and define a +% couple of colors that match the name. +% +% \startbuffer +% \definecolor [cmr10] [darkred] +% \definecolor [logo10] [darkyellow] +% +% \def\setMPfshowfont#1#2% +% {\color[#1]\font\temp=#1\space at #2\relax\temp} +% \stopbuffer +% +% \typebuffer +% +% In the case of the \type {\it hz} examples we had to define a couple of more +% colors, but the principle remains. +% +% \startlinecorrection[blank] +% \getbuffer \processMPbuffer[demo] +% \stoplinecorrection +% +% We don't expect the user to use tricks like this on a daily basis, but it +% demonstrates that with a bit of knowlegde of the internals of \CONTEXT, you can +% produce nice examples of typographic programming. +% +% \stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/metafun/metafun-titlepage-paper.tex b/doc/context/sources/general/manuals/metafun/metafun-titlepage-paper.tex new file mode 100644 index 000000000..558e3b798 --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/metafun-titlepage-paper.tex @@ -0,0 +1,23 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\doifmode{book}{\endinput} + +\startcomponent mfun-titlepage-paper + +\environment metafun-environment + +\setupbackgrounds + [rightpage] + [background=title page] + +\startstandardmakeup + % title page +\stopstandardmakeup + +\setupbackgrounds + [rightpage] + [background=] + +\stopcomponent diff --git a/doc/context/sources/general/manuals/metafun/metafun-titlepage-screen.tex b/doc/context/sources/general/manuals/metafun/metafun-titlepage-screen.tex new file mode 100644 index 000000000..6350bdbda --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/metafun-titlepage-screen.tex @@ -0,0 +1,30 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\startcomponent metafun-titlepage-screen + +\environment metafun-environment + +\startstandardmakeup[topstate=empty] + + \definefont[Big] [RegularBold*default at 60pt] + \definefont[Medium][RegularBold*default at 48pt] + \definefont[Small] [RegularBold*default at 32pt] + \definefont[Tiny] [RegularBold*default at 24pt] + +% \showstruts + + \startcolor[darkyellow] + + \Big METAFUN \par + \Tiny \setstrut \strut context mkiv \par + \vfill + \Tiny \setstrut \hfill \strut \currentdate \par + \Small \setstrut \hfill \strut Hans Hagen \par + + \stopcolor + +\stopstandardmakeup + +\stopcomponent diff --git a/doc/context/sources/general/manuals/metafun/metafun-welcome.tex b/doc/context/sources/general/manuals/metafun/metafun-welcome.tex new file mode 100644 index 000000000..425d15796 --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/metafun-welcome.tex @@ -0,0 +1,3502 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\startcomponent metafun-welcome + +\environment metafun-environment + +\startchapter[reference=sec:welcome,title={Welcome to MetaPost}] + +\startintro + +In this chapter, we will introduce the most important \METAPOST\ concepts as well +as demonstrate some drawing primitives and operators. This chapter does not +replace the \METAFONT\ book or \METAPOST\ manual, both of which provide a lot of +explanations, examples, and (dirty) tricks. + +As its title says, the \METAFONT\ book by Donald.\ E.\ Knuth is about fonts. +Nevertheless, buying a copy is worth the money, because as a \METAPOST\ user you +can benefit from the excellent chapters about curves, algebraic expressions, and +(linear) equations. The following sections are incomplete in many aspects. More +details on how to define your own macros can be found in both the \METAFONT\ book +and \METAPOST\ manual, but you will probably only appreciate the nasty details if +you have written a few simple figures yourself. This chapter will give you a +start. + +A whole section is dedicated to the basic extensions to \METAPOST\ as provided by +\METAFUN. Most of them are meant to make defining graphics like those shown in +this document more convenient. + +Many of the concepts introduced here will be discussed in more detail in later +chapters. So, you may consider this chapter to be an appetizer for the following +chapters. If you want to get started quickly, you can safely skip this chapter +now. + +\stopintro + +\startsection[title={Paths}] + +\index{paths} + +Paths are the building blocks of \METAPOST\ graphics. In its simplest form, a +path is a single point. + +\startuseMPgraphic{axis} + tickstep := 1cm ; ticklength := 2mm ; + drawticks unitsquare xscaled 4cm yscaled 3cm shifted (-1cm,-1cm) ; + tickstep := tickstep/2 ; ticklength := ticklength/2 ; + drawticks unitsquare xscaled 4cm yscaled 3cm shifted (-1cm,-1cm) ; +\stopuseMPgraphic + +\startlinecorrection[blank] +\startMPcode + \includeMPgraphic{axis} + drawpoint "1cm,1.5cm" ; +\stopMPcode +\stoplinecorrection + +Such a point is identified by two numbers, which represent the horizontal and +vertical position, often referred to as $x$ and $y$, or $(x,y)$. Because there +are two numbers involved, in \METAPOST\ this point is called a pair. Its related +datatype is therefore \type {pair}. The following statements assigns the point we +showed previously to a pair variable. + +\starttyping +pair somepoint ; somepoint := (1cm,1.5cm) ; +\stoptyping + +A pair can be used to identify a point in the two dimensional coordinate space, +but it can also be used to denote a vector (being a direction or displacement). +For instance, \type {(0,1)} means \quote {go up}. Looking through math glasses, +you may consider them vectors, and if you know how to deal with them, \METAPOST\ +may be your friend, since it knows how to manipulate them. + +You can connect points and the result is called a path. A path is a straight or +bent line, and is not necessarily a smooth curve. An example of a simple +rectangular path is: \footnote {In the next examples we use the debugging +features discussed in \in {chapter} [sec:debugging] to visualize the points, +paths and bounding boxes.} + +\startuseMPgraphic{path} + path p ; + p := unitsquare xyscaled (2cm,1cm) shifted (.5cm,.5cm) ; +\stopuseMPgraphic + +\startlinecorrection[blank] +\startMPcode + \includeMPgraphic{axis} + \includeMPgraphic{path} + drawpath p ; +\stopMPcode +\stoplinecorrection + +This path is constructed out of four points: + +\startlinecorrection[blank] +\startMPcode + \includeMPgraphic{axis} + \includeMPgraphic{path} + swappointlabels := true ; drawpath p ; drawpoints p ; +\stopMPcode +\stoplinecorrection + +Such a path has both a beginning and end and runs in a certain direction: + +\startlinecorrection[blank] +\startMPcode + \includeMPgraphic{axis} + \includeMPgraphic{path} + autoarrows := true ; + swappointlabels := true ; drawarrowpath p ; drawpoints p ; +\stopMPcode +\stoplinecorrection + +A path can be open or closed. The previous path is an example of a closed path. +An open path looks like this: + +\startuseMPgraphic{path} + path p ; p := (1cm,1cm)..(1.5cm,1.5cm)..(2cm,0cm) ; +\stopuseMPgraphic + +\startlinecorrection[blank] +\startMPcode + \includeMPgraphic{axis} + \includeMPgraphic{path} + swappointlabels := true ; drawpath p ; drawpoints p ; +\stopMPcode +\stoplinecorrection + +When we close this path |<|and in a moment we will see how to do this|>| the path +looks like: + +\startbuffer +\startlinecorrection[blank] +\startMPcode + \includeMPgraphic{axis} + \includeMPgraphic{path} + p := p .. cycle ; + swappointlabels := true ; drawpath p ; drawpoints p ; +\stopMPcode +\stoplinecorrection +\stopbuffer + +\getbuffer + +The open path is defined as: + +\starttyping +(1cm,1cm)..(1.5cm,1.5cm)..(2cm,0cm) +\stoptyping + +The \quote {double period} connector \type {..} tells \METAPOST\ that we want to +connect the lines by a smooth curve. If you want to connect points with straight +line segments, you should use \type {--}. + +Closing the path is done by connecting the first and last point, using the \type +{cycle} command. + +\starttyping +(1cm,1cm)..(1.5cm,1.5cm)..(2cm,0cm)..cycle +\stoptyping + +Feel free to use \type {..} or \type {--} at any point in your path. + +\starttyping +(1cm,1cm)--(1.5cm,1.5cm)..(2cm,0cm)..cycle +\stoptyping + +\startuseMPgraphic{path} +path p ; p := (1cm,1cm)--(1.5cm,1.5cm)..(2cm,0cm)..cycle ; +\stopuseMPgraphic + +This path, when drawn, looks like this: + +\getbuffer + +As you can see in some of the previous examples, \METAPOST\ is capable of drawing +a smooth curve through the three points that make up the path. We will now +examine how this is done. + +\startlinecorrection[blank] +\startMPcode + \includeMPgraphic{axis} + \includeMPgraphic{path} + p := p .. cycle ; swappointlabels := true ; + drawpath p ; drawcontrollines p ; drawpoints p ; drawcontrolpoints p ; +\stopMPcode +\stoplinecorrection + +The six small points are the so called control points. These points pull their +parent point in a certain direction. The further away such a point is, the +stronger the pull. + +Each point has at most two control points. As you can see in the following +graphic, the endpoints of a non closed curve have only one control point. + +\startuseMPgraphic{path} +path p ; p := (1.5cm,1.5cm)..(2cm,0cm)..(1cm,1cm) ; +\stopuseMPgraphic + +\startbuffer[path] +\startlinecorrection[blank] +\startMPcode + \includeMPgraphic{axis} + \includeMPgraphic{path} + swappointlabels := true ; + drawpath p ; drawcontrollines p ; drawpoints p ; drawcontrolpoints p ; +\stopMPcode +\stoplinecorrection +\stopbuffer + +\getbuffer[path] + +This time we used the path: + +\starttyping +(1.5cm,1.5cm)..(2cm,0cm)..(1cm,1cm) +\stoptyping + +When you connect points by a smooth curve, \METAPOST\ will calculate the control +points itself, unless you specify one or more of them. + +\startuseMPgraphic{path} + path p ; p := (1cm,1cm)..(1.5cm,1.5cm)..controls (3cm,2cm)..(2cm,0cm) ; +\stopuseMPgraphic + +\getbuffer[path] + +This path is specified as: + +\starttyping +(1cm,1cm)..(1.5cm,1.5cm)..controls (3cm,2cm)..(2cm,0cm) +\stoptyping + +In this path, the second and third point share a control point. Watch how the +curve is pulled in that direction. It is possible to pull a bit less by choosing +a different control point: + +\starttyping +(1cm,1cm)..(1.5cm,1.5cm)..controls (2.75cm,1.25cm)..(2cm,0cm) +\stoptyping + +Now we get: + +\startuseMPgraphic{path} + path p ; p := (1cm,1cm)..(1.5cm,1.5cm)..controls (2.75cm,1.25cm)..(2cm,0cm) ; +\stopuseMPgraphic + +\getbuffer[path] + +We can also specify a different control point for each connecting segment. + +\startuseMPgraphic{path} + path p ; p := (1cm,1cm)..controls (.5cm,2cm) and (2.5cm,2cm)..(2cm,.5cm) ; +\stopuseMPgraphic + +\getbuffer[path] + +This path is defined as: + +\starttyping +(1cm,1cm)..controls (.5cm,2cm) and (2.5cm,2cm)..(2cm,.5cm) +\stoptyping + +\stopsection + +\startsection[title={Transformations}] + +\index{transformations} + +We can store a path in a path variable. Before we can use such a variable, we +have to allocate its memory slot with \type {path}. + +\starttyping +path p ; p := (1cm,1cm)..(1.5cm,2cm)..(2cm,0cm) ; +\stoptyping + +Although we can manipulate any path in the same way, using a variable saves us +the effort to key in a path more than once. + +\startuseMPgraphic{axis} + tickstep := 1cm ; ticklength := 2mm ; + drawticks unitsquare xscaled 8cm yscaled 4cm ; + tickstep := tickstep/2 ; ticklength := ticklength/2 ; + drawticks unitsquare xscaled 8cm yscaled 4cm ; +\stopuseMPgraphic + +\startuseMPgraphic{path} + path p ; p := (1cm,1cm)..(1.5cm,2cm)..(2cm,0cm)..cycle ; + path q ; q := p shifted (4cm,2cm) ; +\stopuseMPgraphic + +\startbuffer[path] +\startlinecorrection[blank] +\startMPcode + \includeMPgraphic{axis} + \includeMPgraphic{path} + swappointlabels := true ; + drawpath p ; drawcontrollines p ; drawpoints p ; drawcontrolpoints p ; + drawpath q ; drawcontrollines q ; drawpoints q ; drawcontrolpoints q ; +\stopMPcode +\stoplinecorrection +\stopbuffer + +\getbuffer[path] + +In this graphic, the path stored in \type {p} is drawn twice, once in its +displaced form. The displacement is defined as: + +\starttyping +p shifted (4cm,2cm) +\stoptyping + +In a similar fashion you can rotate a path. You can even combine shifts and +rotations. First we rotate the path 15 degrees counter||clockwise around the +origin. + +\starttyping +p rotated 15 +\stoptyping + +\startuseMPgraphic{path} + path p ; p := (1cm,1cm)..(1.5cm,2cm)..(2cm,0cm)..cycle ; + path q ; q := p rotated 15 ; +\stopuseMPgraphic + +\getbuffer[path] + +This rotation becomes more visible when we also shift the path to the right by +saying: + +\starttyping +rotated 15 shifted (4cm,0cm) +\stoptyping + +Now we get: + +\startuseMPgraphic{path} + path p ; p := (1cm,1cm)..(1.5cm,2cm)..(2cm,0cm)..cycle ; + path q ; q := p rotated 15 shifted (4cm,0cm) ; +\stopuseMPgraphic + +\getbuffer[path] + +Note that \type {rotated 15} is equivalent to \typ {p rotatedaround (origin, +15)}. + +It may make more sense to rotate the shape around its center. This can easily be +achieved with the \type {rotatedaround} command. Again, we move the path to the +right afterwards. + +\starttyping +p rotatedaround(center p, 15) shifted (4cm,0cm) +\stoptyping + +\startuseMPgraphic{axis} + tickstep := 1cm ; ticklength := 2mm ; + drawticks unitsquare xscaled 10cm yscaled 3cm ; + tickstep := tickstep/2 ; ticklength := ticklength/2 ; + drawticks unitsquare xscaled 10cm yscaled 3cm ; +\stopuseMPgraphic + +\startuseMPgraphic{path} + path p ; p := (1cm,1cm)..(1.5cm,2cm)..(2cm,0cm)..cycle ; + path q ; q := p rotatedaround(center p, 15) shifted (4cm,0cm) ; +\stopuseMPgraphic + +\getbuffer[path] + +Yet another transformation is slanting. Just like characters can be upright or +slanted, a graphic can be: + +\starttyping +p slanted 1.5 shifted (4cm,0cm) +\stoptyping + +\startuseMPgraphic{path} + path p ; p := (1cm,1cm)..(1.5cm,2cm)..(2cm,0cm)..cycle ; + path q ; q := p slanted 1.5 shifted (4cm,0cm) ; +\stopuseMPgraphic + +\getbuffer[path] + +The slant operation's main application is in tilting fonts. The $x$||coodinates +are increased by a percentage of their $y$||coordinate, so here every $x$ becomes +$x+1.5y$. The $y$||coordinate is left untouched. The following table summarizes +the most important primitive transformations that \METAPOST\ supports. + +\starttabulate[|lT|l|] +\HL +\NC \METAPOST\ code \NC mathematical equivalent \NC \NR +\HL +\NC (x,y) shifted (a,b) \NC $(x+a,y+b)$ \NC \NR +\NC (x,y) scaled s \NC $(sx,sy)$ \NC \NR +\NC (x,y) xscaled s \NC $(sx,y)$ \NC \NR +\NC (x,y) yscaled s \NC $(x,sy)$ \NC \NR +\NC (x,y) zscaled (u,v) \NC $(xu-yv,xv+yu)$ \NC \NR +\NC (x,y) slanted s \NC $(x+sy,y)$ \NC \NR +\NC (x,y) rotated r \NC $(x\cos(r)-y\sin(r),x\sin(r)+y\cos(r))$ \NC \NR +\HL +\stoptabulate + +The previously mentioned \type {rotatedaround} is not a primitive but a macro, +defined in terms of shifts and rotations. Another transformation macro is +mirroring, or in \METAPOST\ terminology, \type {reflectedabout}. + +\startbuffer[path] +\startlinecorrection[blank] +\startMPcode + \includeMPgraphic{axis} + \includeMPgraphic{path} + swappointlabels := true ; + drawpath p ; drawpoints p ; + drawpath q ; drawpoints q ; +\stopMPcode +\stoplinecorrection +\stopbuffer + +\startuseMPgraphic{path} + path p ; p := unitsquare scaled 2cm shifted (2cm,.5cm) ; + path q ; q := unitsquare scaled 2cm shifted (2cm,.5cm) reflectedabout((2.4cm,-.5),(2.4cm,3cm)) ; + draw (2.4cm,-.5cm)--(2.4cm,3cm) ; +\stopuseMPgraphic + +\getbuffer[path] + +The reflection axis is specified by a pair of points. For example, in the graphic +above, we used the following command to reflect the square about a line through +the given points. + +\starttyping +p reflectedabout((2.4cm,-.5),(2.4cm,3cm)) +\stoptyping + +The line about which the path is mirrored. Mirroring does not have to be parallel +to an axis. + +\starttyping +p reflectedabout((2.4cm,-.5),(2.6cm,3cm)) +\stoptyping + +The rectangle now becomes: + +\startuseMPgraphic{path} + path p ; p := unitsquare scaled 2cm shifted (2cm,.5cm) ; + path q ; q := unitsquare scaled 2cm shifted (2cm,.5cm) reflectedabout((2.4cm,-.5),(2.6cm,3cm)) ; + draw (2.4cm,-.5cm)--(2.6cm,3cm) ; +\stopuseMPgraphic + +\getbuffer[path] + +\pagereference [zscaled]The table also mentions \type {zscaled}. + +\startuseMPgraphic{path} +path p ; p := unitsquare scaled (1cm) shifted (1cm,.5cm) ; +path q ; q := unitsquare scaled (1cm) zscaled (2,.5) shifted (1cm,.5cm) ; +\stopuseMPgraphic + +\getbuffer[path] + +A \type {zscaled} specification takes a vector as argument: + +\starttyping +p zscaled (2,.5) +\stoptyping + +The result looks like a combination of scaling and rotation, and conforms to the +formula in the previous table. + +Transformations can be defined in terms of a transform matrix. Such a matrix is +stored in a transform variable. For example: + +\starttyping +transform t ; t := identity scaled 2cm shifted (4cm,1cm) ; +\stoptyping + +We use the associated keyword \type {transformed} to apply this matrix to a path +or picture. + +\starttyping +p transformed t +\stoptyping + +In this example we've taken the \type {identity} matrix as starting point but you +can use any predefined transformation. The identity matrix is defined in such a +way that it scales by a factor of one in both directions and shifts over the +zero||vector. + +Transform variables can save quite some typing and may help you to force +consistency when many similar transformations are to be done. Instead of changing +the scaling, shifting and other transformations you can then stick to just +changing the one transform variable. + +\stopsection + +\startsection[title={Constructing paths}] + +\index{paths} + +In most cases, a path will have more points than the few shown here. Take for +instance a so called {\em super ellipse}. + +\startlinecorrection[blank] +\startMPcode +path p ; p := fullsquare xyscaled (5cm,3cm) superellipsed .85 ; +drawpath p ; drawpoints p ; +visualizepaths ; draw p shifted (6cm,0cm) withcolor .625yellow ; +\stopMPcode +\stoplinecorrection + +These graphics provide a lot of information. In this picture the crosshair in the +center is the {\em origin} and the dashed rectangle is the {\em bounding box} of +the super ellipse. The bounding box specifies the position of the graphic in +relation to the origin as well as its width and height. + +In the graphic on the right, you can see the points that make up the closed path +as well as the control points. Each point has a number with the first point +numbered zero. Because the path is closed, the first and last point coincide. + +\startuseMPgraphic{axis} + tickstep := 1cm ; ticklength := 2mm ; + drawticks unitsquare xscaled 8cm yscaled 3cm ; + tickstep := tickstep/2 ; ticklength := ticklength/2 ; + drawticks unitsquare xscaled 8cm yscaled 3cm ; +\stopuseMPgraphic + +\startbuffer +\startlinecorrection[blank] +\startMPcode + string tmp ; defaultfont := "\truefontname{Mono}" ; + \includeMPgraphic{axis} + \includeMPgraphic{points} + \includeMPgraphic{path} + label.lft(verbatim(tmp),(14.5cm,2.5cm)) ; + drawwholepath scantokens(tmp) ; +\stopMPcode +\stoplinecorrection +\stopbuffer + +We've used the commands \type {..} and \type {--} as path connecting directives. +In the next series of examples, we will demonstrate a few more. However, before +doing that, we define a few points, using the predefined \type {z} variables. + +\startuseMPgraphic{points} + z0 = (0.5cm,1.5cm) ; z1 = (2.5cm,2.5cm) ; + z2 = (6.5cm,0.5cm) ; z3 = (3.0cm,1.5cm) ; +\stopuseMPgraphic + +\starttyping +z0 = (0.5cm,1.5cm) ; z1 = (2.5cm,2.5cm) ; +z2 = (6.5cm,0.5cm) ; z3 = (3.0cm,1.5cm) ; +\stoptyping + +Here \type {z1} is a short way of saying \type {(x1,y1)}. When a \type {z} +variable is called, the corresponding \type {x} and \type {y} variables are +available too. Later we will discuss \METAPOST\ capability to deal with +expressions, which are expressed using an \type {=} instead of \type {:=}. In +this case the expression related to \type {z0} is expanded into: + +\starttyping +z0 = (x0,y0) = (0.5cm,1.5cm) ; +\stoptyping + +But for this moment let's forget about their expressive nature and simply see +them as points which we will now connect by straight line segments. + +\startuseMPgraphic{path} + tmp := "z0--z1--z2--z3--cycle" ; +\stopuseMPgraphic + +\getbuffer + +The smooth curved connection, using \type {..} looks like: + +\startuseMPgraphic{path} + tmp := "z0..z1..z2..z3..cycle" ; +\stopuseMPgraphic + +\getbuffer + +If we replace the \type {..} by \type {...}, we get a tighter path. + +\startuseMPgraphic{path} + tmp := "z0...z1...z2...z3...cycle" ; +\stopuseMPgraphic + +\getbuffer + +Since there are \type {..}, \type {--}, and \type {...}, it will be no surprise +that there is also \type {---}. + +\startuseMPgraphic{path} + tmp := "z0---z1---z2---z3---cycle" ; +\stopuseMPgraphic + +\getbuffer + +If you compare this graphic with the one using \type {--} the result is the same, +but there is a clear difference in control points. As a result, combining \type +{..} with \type {--} or \type {---} makes a big difference. Here we get a +non||smooth connection between the curves and the straight line. + +\startuseMPgraphic{path} + tmp := "z0..z1..z2--z3..cycle" ; +\stopuseMPgraphic + +\getbuffer + +As you can see in the next graphic, when we use \type {---}, we get a smooth +connection between the straight line and the rest of the curve. + +\startuseMPgraphic{path} + tmp := "z0..z1..z2---z3..cycle" ; +\stopuseMPgraphic + +\getbuffer + +So far, we have joined the four points as one path. Alternatively, we can +constrict subpaths and connect them using the ampersand symbol, \type {&}. + +\startuseMPgraphic{path} + tmp := "z0..z1..z2 & z2..z3..z0 & cycle" ; +\stopuseMPgraphic + +\getbuffer + +So far we have created a closed path. Closing is done by \type {cycle}. The +following path may look closed but is in fact open. + +\startuseMPgraphic{path} + tmp := "z0..z1..z2..z3..z0" ; +\stopuseMPgraphic + +\getbuffer + +Only a closed path can be filled. The closed alternative looks as follows. We +will see many examples of filled closed paths later on. + +\startuseMPgraphic{path} + tmp := "z0..z1..z2..z3..z0..cycle" ; +\stopuseMPgraphic + +\getbuffer + +Here the final \type {..} will try to make a smooth connection, but because we +already are at the starting point, this is not possible. However, the \type +{cycle} command can automatically connect to the first point. Watch the +difference between the previous and the next path. + +\startuseMPgraphic{path} + tmp := "z0..z1..z2..z3..cycle" ; +\stopuseMPgraphic + +\getbuffer + +It is also possible to combine two paths into one that don't have common head and +tails. First we define an open path: + +\startuseMPgraphic{path} + tmp := "z0..z1..z2" ; +\stopuseMPgraphic + +\getbuffer + +The following path is a closed one, and crosses the previously shown path. + +\startuseMPgraphic{path} + tmp := "z0..z3..z1..cycle" ; +\stopuseMPgraphic + +\getbuffer + +With \type {buildcycle} we can combine two paths into one. + +\startuseMPgraphic{path} + tmp := "buildcycle(z0..z1..z2 , z0..z3..z1..cycle)" ; +\stopuseMPgraphic + +\getbuffer + +We would refer readers to the \METAFONT\ book and the \METAPOST\ manual for an +explanation of the intricacies of the \type {buildcycle} command. It is an +extremely complicated command, and there is just not enough room here to do it +justice. We suffice with saying that the paths should cross at least once before +the \type {buildcycle} command can craft a combined path from two given paths. We +encourage readers to experiment with this command. + +In order to demonstrate another technique of joining paths, we first draw a few +strange paths. The last of these three graphics demonstrates the use of \type +{softjoin}. + +\startuseMPgraphic{path} + tmp := "z0--z1..z2--z3" ; +\stopuseMPgraphic + +\getbuffer + +\startuseMPgraphic{path} + tmp := "z0..z1..z2--z3" ; +\stopuseMPgraphic + +\getbuffer + +Watch how \type {softjoin} removes a point in the process of smoothing a +connection. The smoothness is accomplished by adapting the control points of the +neighbouring points in the appropriate way. + +\startuseMPgraphic{path} + tmp := "z0--z1 softjoin z2--z3" ; +\stopuseMPgraphic + +\getbuffer + +Once a path is known, you can cut off a slice of it. We will demonstrate a few +alternative ways of doing so, but first we show one more time the path that we +take as starting point. + +\startuseMPgraphic{path} + tmp := "z0..z1..z2..z3..cycle" ; +\stopuseMPgraphic + +\getbuffer + +This path is made up out of five points, where the cycle duplicates the first +point and connects the loose ends. The first point has number zero. + +We can use these points in the \type {subpath} command, which takes two +arguments, specifying the range of points to cut of the path specified after the +keyword \type {of}. + +\startuseMPgraphic{path} + tmp := "subpath(2,4) of (z0..z1..z2..z3..cycle)" ; +\stopuseMPgraphic + +\getbuffer + +The new (sub|)|path is a new path with its own points that start numbering at +zero. The next graphic shows both the original and the subpath from point 1 +upto~3. + +\startuseMPgraphic{path} + tmp := "(z0..z1..z2..z3..cycle)" ; + sub := "subpath(1,3)" ; +\stopuseMPgraphic + +\startbuffer[sub] +\startlinecorrection[blank] +\startMPcode + string tmp, sub ; defaultfont := "\truefontname{Mono}" ; + \includeMPgraphic{axis} + \includeMPgraphic{points} + \includeMPgraphic{path} + label.lft(verbatim(tmp),(14.5cm,2.5cm)) ; + label.lft(verbatim(sub),(14.5cm,2.0cm)) ; + sub := sub & " of " & tmp ; + path p ; p := scantokens(tmp) ; + path q ; q := scantokens(sub) ; + drawwholepath p ; swappointlabels := true ; + drawpath q withcolor .625yellow ; + drawpoints q withcolor .625red ; + drawpointlabels q ; +\stopMPcode +\stoplinecorrection +\stopbuffer + +\getbuffer[sub] + +In spite of what you may think, a point is not fixed. This is why in \METAPOST\ a +point along a path is officially called a time. The next example demonstrates +that we can specify any time on the path. + +\startuseMPgraphic{path} + tmp := "(z0..z1..z2..z3..cycle)" ; + sub := "subpath(2.45,3.85)" ; +\stopuseMPgraphic + +\getbuffer[sub] + +Often we want to take a slice starting at a specific point. This is provided by +\type {cutafter} and its companion \type {cutbefore}. Watch out, this time we use +a non||cyclic path. + +\startuseMPgraphic{path} + tmp := "(z0..z1..z2..z3)" ; +\stopuseMPgraphic + +\getbuffer + +When you use \type {cutafter} and \type {cutbefore} it really helps if you know +in what direction the path runs. + +\startuseMPgraphic{path} + tmp := "(z0..z1..z2..z3) cutafter z2" ; +\stopuseMPgraphic + +\getbuffer + +\startuseMPgraphic{path} + tmp := "(z0..z1..z2..z3) cutbefore z1" ; +\stopuseMPgraphic + +\getbuffer + +Here is a somewhat silly way of accomplishing the same thing, but it is a nice +introduction to \METAPOST's \type {point} operation. In order to use this command +effectively, you need to know how many points make up the path. + +\startuseMPgraphic{path} + tmp := "(z0..z1..z2..z3) cutbefore point 2 of (z0..z1..z2..z3)" ; +\stopuseMPgraphic + +\getbuffer + +As with \type {subpath}, you can use fractions to specify the time on the path, +although the resulting point is not necessarily positioned linearly along the +curve. + +\startuseMPgraphic{path} + tmp := "(z0..z1..z2..z3) cutbefore point 2.5 of (z0..z1..z2..z3)" ; +\stopuseMPgraphic + +\getbuffer + +If you really want to know the details of where fraction points are positioned, +you should read the \METAFONT\ book and study the source of \METAFONT\ and +\METAPOST, where you will find the complicated formulas that are used to +calculate smooth curves. + +\startuseMPgraphic{path} + tmp := "z0..z1..cycle" ; +\stopuseMPgraphic + +\getbuffer + +Like any closed path, this path has points where the tangent is horizontal or +vertical. Early in this chapter we mentioned that a pair (or point) can specify a +direction or vector. Although any angle is possible, we often use one of four +predefined directions: + +\starttabulate[|Tl|Tl|] +\HL +\NC right \NC ( 1, 0) \NC \NR +\NC up \NC ( 0, 1) \NC \NR +\NC left \NC (-1, 0) \NC \NR +\NC down \NC ( 0,-1) \NC \NR +\HL +\stoptabulate + +We can use these predefined directions in combination with \type {directionpoint} +and \type {cutafter}. The following command locates the first point on the path +that has a tangent that points vertically upward, and then feeds this point to +the \type {cutafter} command. + +\startuseMPgraphic{path} + tmp := "(z0..z1..cycle) cutafter directionpoint up of (z0..z1..cycle)" ; +\stopuseMPgraphic + +\getbuffer + +You are not limited to predefined direction vectors. You can provide a pair to +indicate a direction. In the next example we use the following cyclic path: + +\startuseMPgraphic{path} + tmp := "z0..z1..cycle" ; +\stopuseMPgraphic + +\getbuffer + +Using \type {( )} is not mandatory but makes the expression look less +complicated. + +\startuseMPgraphic{path} + tmp := "(z0..z1..cycle) cutafter directionpoint (1,1) of (z0..z1..cycle)" ; +\stopuseMPgraphic + +\getbuffer + +We will apply these commands in the next chapters, but first we will finish our +introduction in \METAPOST. We have seen how a path is constructed and what can be +done with it. Now it is time to demonstrate how such a path is turned into a +graphic. + +\stopsection + +\startsection[title={Angles}] + +\index{angles} +\index{rotation} + +You can go from angles to vectors and vice versa using the \type {angle} and +\type {dir} functions. The next example show both in action. + +\startbuffer +pickup pencircle scaled 2mm ; +draw (origin -- dir(45) -- dir(0) -- cycle) + scaled 3cm withcolor .625red ; +draw (origin -- dir(angle(1,1)) -- dir(angle(1,0)) -- cycle) + scaled 3cm shifted (3.5cm,0) withcolor .625yellow ; +draw (origin -- (1,1) -- (1,0) -- cycle) + scaled 3cm shifted (7cm,0) withcolor .625white ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +The \type {dir} command returns an unit vector, which is why the first two shapes +look different and are smaller than the third one. We can compensate for that by +an additional scaling: + +\startbuffer +pickup pencircle scaled 2mm ; +draw (origin -- dir(45) -- dir(0) -- cycle) + scaled sqrt(2) scaled 3cm withcolor .625red ; +draw (origin -- dir(angle(1,1)) -- dir(angle(1,0)) -- cycle) + scaled sqrt(2) scaled 3cm shifted (4.5cm,0) withcolor .625yellow ; +draw (origin -- (1,1) -- (1,0) -- cycle) + scaled 3cm shifted (9cm,0) withcolor .625white ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +\stopsection + +\startsection[title={Drawing pictures}] + +\index{drawing} + +Once a path is defined, either directly or as a variable, you can turn it into a +picture. You can draw a path, like we did in the previous examples, or you can +fill it, but only if it is closed. + +\startlinecorrection[blank] +\startMPcode +visualizepaths ; +path p ; p := (0cm,1cm)..(2cm,2cm)..(4cm,0cm)..cycle ; +draw p withcolor .625red ; +fill p shifted (7cm,0) withcolor .625white ; +\stopMPcode +\stoplinecorrection + +Drawing is done by applying the \type {draw} command to a path, as in: + +\starttyping +draw (0cm,1cm)..(2cm,2cm)..(4cm,0cm)..cycle ; +\stoptyping + +The rightmost graphic was made with \type {fill}: + +\starttyping +fill (0cm,1cm)..(2cm,2cm)..(4cm,0cm)..cycle ; +\stoptyping + +If you try to duplicate this drawing, you will notice that you will get black +lines instead of red and a black fill instead of a gray one. When drawing or +filling a path, you can give it a color, use all kinds of pens, and achieve +special effects like dashes or arrows. + +\startlinecorrection[blank] +\startMPcode +visualizepaths ; +path p ; p := (0cm,1cm)..(2cm,2cm)..(4cm,0cm)..(2.5cm,1cm)..cycle ; +drawarrow p withcolor .625red ; +draw p shifted (7cm,0) dashed withdots withcolor .625yellow ; +\stopMPcode +\stoplinecorrection + +These two graphics were defined and drawn using the following commands. Later we +will explain how you can set the line width (or penshape in terms of \METAPOST). + +\starttyping +path p ; p := (0cm,1cm)..(2cm,2cm)..(4cm,0cm)..(2.5cm,1cm)..cycle ; +drawarrow p withcolor .625red ; +draw p shifted (7cm,0) dashed withdots withcolor .625yellow ; +\stoptyping + +Once we have drawn one or more paths, we can store them in a picture variable. +The straightforward way to store a picture is to copy it from the current +picture: + +\starttyping +picture pic ; pic := currentpicture ; +\stoptyping + +The following command effectively clears the picture memory and allows us to +start anew. + +\starttyping +currentpicture := nullpicture ; +\stoptyping + +We can shift, rotate and slant the picture stored in \type {pic} as we did with +paths. We can say: + +\starttyping +draw pic rotated 45 withcolor red ; +\stoptyping + +A picture can hold multiple paths. You may compare a picture to grouping as +provided by drawing applications. + +\starttyping +draw (0cm,0cm)--(1cm,1cm) ; draw (1cm,0cm)--(0cm,1cm) ; +picture pic ; pic := currentpicture ; +draw pic shifted (3cm,0cm) ; draw pic shifted (6cm,0cm) ; +pic := currentpicture ; draw pic shifted (0cm,2cm) ; +\stoptyping + +We first draw two paths and store the resulting \quote {cross} in a picture +variable. Then we draw this picture two times, so that we now have three copies +of the cross. We store the accumulated drawing again, so that after duplication, +we finally get six crosses. + +\startlinecorrection[blank] +\startMPcode +path p ; p := (0cm,0cm)--(1cm,1cm) ; +path q ; q := (1cm,0cm)--(0cm,1cm) ; +for i=p,q : + drawpath i ; drawcontrollines i ; drawpoints i ; drawcontrolpoints i ; +endfor ; +picture pic ; pic := currentpicture ; +draw pic shifted (3cm,0cm) ; +draw pic shifted (6cm,0cm) ; +pic := currentpicture ; +draw pic shifted (0cm,2cm) ; +\stopMPcode +\stoplinecorrection + +You can often follow several routes to reach the same solution. Consider for +instance the following graphic. + +\startbuffer[points] +w := 4cm ; h := 2cm ; ww := 1cm ; hh := 1.5cm ; +\stopbuffer + +\startbuffer[common] +drawoptions(withcolor .625white) ; +\stopbuffer + +\startbuffer[background] +fill (unitsquare xscaled w yscaled h) enlarged 2mm withcolor .625yellow ; +\stopbuffer + +\startbuffer[shape] +fill (0,0)--(ww,0)--(ww,hh)--(w,hh)--(w,h)--(0,h)--cycle ; +fill (ww,0)--(w,0)--(w,hh)--cycle ; +\stopbuffer + +\typebuffer[shape] + +\startlinecorrection[blank] +\processMPbuffer[common,points,shape] +\stoplinecorrection + +The points that are used to construct the paths are defined using the constants +\type {w}, \type {h}, \type {ww} and \type {hh}. These are defined as follows: + +\typebuffer[points] + +In this case we draw two shapes that leave part of the rectangle uncovered. If +you have a background, this technique allows the background to \quote {show +through} the graphic. + +\startlinecorrection[blank] +\processMPbuffer[common,points,background,shape] +\stoplinecorrection + +A not uncommon practice when making complicated graphics is to use unfill +operations. Since \METAPOST\ provides one, let us see what happens if we apply +this command. + +\startbuffer[shape] +fill (0,0)--(w,0)--(w,h)--(0,h)--cycle ; +unfill (ww,0)--(w,hh)--(ww,hh)--cycle ; +\stopbuffer + +\typebuffer[shape] + +\startlinecorrection[blank] +\processMPbuffer[common,points,background,shape] +\stoplinecorrection + +This does not always give the desired effect, because \METAPOST's \type {unfill} +is not really an unfill, but a \type {fill} with color \type {background}. Since +this color is white by default, we get what we just showed. So, if we set \type +{background} to \type {black}, using \typ {background := black}, we get: + +\startbuffer[back] +background := black ; +\stopbuffer + +\startlinecorrection[blank] +\processMPbuffer[back,common,points,background,shape] +\stoplinecorrection + +Of course, you can set the variable \type {background} to a different color, but +this does not hide the fact that \METAPOST\ lacks a real unfill operation. + +\startbuffer[shape] +fill (0,0)--(0,h)--(w,h)--(w,0)--(ww,0)--(w,hh)--(ww,hh)-- + (ww,0)--cycle ; +\stopbuffer + +\startbuffer[path] +autoarrows := true ; +path p ; p := (0,0)--(0,h)--(w,h)--(w,0)--(ww,0)--(w,hh)--(ww,hh)-- + (ww,0)--cycle ; +draw p withpen pencircle scaled 1mm withcolor .625red; +numeric l ; l := length(p)-1 ; +for i=0 upto l : + drawarrow subpath(i,i+1) of p + withpen pencircle scaled 1mm + withcolor (.5+.5(i/l))*red ; +endfor ; +\stopbuffer + +\startlinecorrection[blank] +\processMPbuffer[common,points,background,shape] +\stoplinecorrection + +Since we don't consider this \type {unfill} a suitable operator, you may wonder +how we achieved the above result. + +\typebuffer[shape] + +\startlinecorrection[blank] +\processMPbuffer[common,points,background,shape,path] +\stoplinecorrection + +This feature depends on the \POSTSCRIPT\ way of filling closed paths, which comes +down to filling either the left or the right hand side of a curve. The following +alternative works too. + +\startbuffer[shape] +fill (0,0)--(0,h)--(w,h)--(w,hh)--(ww,hh)--(ww,0)--(w,hh)-- + (w,0)--cycle ; +\stopbuffer + +\typebuffer[shape] + +\startlinecorrection[blank] +\processMPbuffer[common,points,background,shape] +\stoplinecorrection + +The next alternative will fail. This has to do with the change in direction at +point \type {(0,0)} halfway through the path. Sometimes changing direction can +give curious but desirable effects, but here it brings no good. + +\startbuffer[shape] +fill (0,0)--(0,h)--(w,h)--(w,0)--(0,0)--(ww,0)--(ww,hh)-- + (w,hh)--(ww,0)--cycle ; +\stopbuffer + +\typebuffer[shape] + +This path fails because of the way \POSTSCRIPT\ implements its fill operator. +More details on how \POSTSCRIPT\ defines fills can be found in the reference +manuals. + +\startlinecorrection[blank] +\processMPbuffer[common,points,background,shape] +\stoplinecorrection + +Some of the operations we have seen are hard coded into \METAPOST\ and are called +primitives. Others are defined as macros, that is, a sequence of \METAPOST\ +commands. Since they are used often, you may expect \type {draw} and \type {fill} +to be primitives, but they are not. They are macros defined in terms of +primitives. + +Given a path \type {pat}, you can consider a \type {draw} to be defined in terms +of: + +\starttyping +addto currentpicture doublepath pat +\stoptyping + +The \type {fill} command on the other hand is defined as: + +\starttyping +addto currentpicture contour pat +\stoptyping + +Both macros are actually a bit more complicated but this is mainly due to the +fact that they also have to deal with attributes like the pen and color they draw +with. + +You can use \type {doublepath} and \type {contour} directly, but we will use +\type {draw} and \type {fill} whenever possible. + +Given a picture \type {pic}, the following code is valid: + +\starttyping +addto currentpicture also pic +\stoptyping + +You can add pictures to existing picture variables, where \type {currentpicture} +is the picture that is flushed to the output file. Watch the subtle difference +between adding a \type {doublepath}, \type {contour} or \type {picture}. + +\stopsection + +\startsection[title={Variables}] + +\index{variables} + +At this point you may have noted that \METAPOST\ is a programming language. +Contrary to some of today's languages, \METAPOST\ is a simple and clean language. +Actually, it is a macro language. Although \METAPOST\ and \TEX\ are a couple, the +languages differ in many aspects. If you are using both, you will sometimes wish +that features present in one would be available in the other. When using both +languages, in the end you will understand why the conceptual differences make +sense. + +Being written in \PASCAL, it will be no surprise that \METAPOST\ has some +\PASCAL||like features, although some may also recognize features from \ALGOL68\ +in it. + +First there is the concept of variables and assignments. There are several data +types, some of which we already have seen. + +\starttabulate +\HL +\NC numeric \NC real number in the range $-4096 \ldots +4096$ \NC \NR +\NC boolean \NC a variable that takes one of two states: true or false \NC \NR +\NC pair \NC point or vector in 2||dimensional space \NC \NR +\NC path \NC a piecewise collection of curves and line segments \NC \NR +\NC picture \NC collection of stroked or filled paths \NC \NR +\NC string \NC sequence of characters, like \type {"metapost"} \NC \NR +\NC color \NC vector of three (rgb) or four (cmyk) numbers \NC \NR +\HL +\stoptabulate + +There are two additional types, \type {transform} and \type {pen}, but we will +not discuss these in depth. + +\starttabulate +\HL +\NC transform \NC transformation vector with six elements \NC \NR +\NC pen \NC pen specification \NC \NR +\HL +\stoptabulate + +You can achieve interesting effects by using pens with certain shapes. For the +moment you may consider a pen to be a path itself that is applied to the path +that is drawn. + +The \type {numeric} data type is used so often that it is the default type of any +non declared variable. This means that + +\starttyping +n := 10 ; +\stoptyping + +is the same as + +\starttyping +numeric n ; n := 10 ; +\stoptyping + +When writing collections of macros, it makes sense to use the second method, +because you can never be sure if \type {n} isn't already declared as a picture +variable, and assigning a numeric to a picture variable is not permitted. + +Because we often deal with collections of objects, such as a series of points, +all variables can be organized in arrays. For instance: + +\starttyping +numeric n[] ; n[3] := 10 ; n[5] := 13 ; +\stoptyping + +An array is a collection of variables of the same type that are assigned and +accessed by indexing the variable name, as in \type {n[3] := 5}. +Multi||dimensional arrays are also supported. Since you need a bit of imagination +to find an application for 5||dimensional arrays, we restrict ourselves to a +two||dimensional example. + +\starttyping +numeric n[][] ; n[2][3] := 10 ; +\stoptyping + +A nice feature is that the bounds of such an array needs not to be set +beforehand. This also means that each cell that you access is reported as {\em +unknown} unless you have assigned it a value. + +Behind the screens there are not really arrays. It's just a matter of creating +hash entries. It might not be obvious, but the following assignments are all +equivalent: + +\startbuffer +i_111_222 := 1cm ; +i_[111]_[222] := 1cm ; +i_[111][222] := 1cm ; +draw + image ( + draw (0cm,i_111_222) ; + draw (1cm,i_[111]_[222]) ; + draw (2cm,i_[111][222]) ; + ) + withpen pencircle scaled 5mm + withcolor .625 red ; +\stopbuffer + +\typebuffer + +Sometimes \METAPOST\ ways are mysterious: + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +\stopsection + +\startsection[title={Conditions}] + +\index{conditions} + +The existence of boolean variables indicates the presence of conditionals. +Indeed, the general form of \METAPOST's conditional follows: + +\starttyping +if n=10 : draw p ; else : draw q ; fi ; +\stoptyping + +Watch the colons after the if and else clause. They may not be omitted. The +semi||colons on the other hand, are optional and depend on the context. You may +say things like: + +\starttyping +draw if n=10 : p ; else : q ; fi ; +\stoptyping + +Here we can omit a few semi||colons: + +\starttyping +draw if n=10 : p else : q fi withcolor red ; +\stoptyping + +Adding semi||colons after \type {p} and \type {q} will definitely result in an +error message, since the semi||colon ends the draw operation and \typ {withcolor +red} becomes an isolated piece of nonsense. + +There is no case statement available, but for most purposes, the following +extension is adequate: + +\starttyping +draw p withcolor if n<10 : red elseif n=10 : green else : blue fi ; +\stoptyping + +There is a wide repertoire of boolean tests available. + +\starttyping +if picture p : +if known n : +if odd i : +if cycle q : +\stoptyping + +Of course, you can use \type {and}, \type {or}, \type {not}, and \type {( )} to +construct very advanced boolean expressions. If you have a bit of programming +experience, you will appreciate the extensive support of conditionals in +\METAPOST. + +\stopsection + +\startsection[title={Loops}] + +\index{loops} + +Yet another programming concept present in \METAPOST\ is the loop statement, the +familiar \quote {for loop} of all programming languages. + +\starttyping +for i=0 step 2 until 20 : + draw (0,i) ; +endfor ; +\stoptyping + +As explained convincingly in Niklaus Wirth's book on algorithms and +datastructures, the for loop is the natural companion to an array. Given an array +of length $n$, you can construct a path out of the points that make up the array. + +\starttyping +draw for i=0 step 1 until n-1 : p[i] .. endfor p[n] ; +\stoptyping + +If the step increment is not explicitly stated, it has an assumed value of 1. We +can shorten the previous loop construct as follows: + +\starttyping +draw for i=0 upto n-1 : p[i] .. endfor p[n] ; +\stoptyping + +After seeing \type {if} in action, the following \type {for} loop will be no +surprise: + +\startbuffer +draw origin for i=0 step 10 until 100 : ..{down}(i,0) endfor ; +\stopbuffer + +\typebuffer + +This gives the zig||zag curve: + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +You can use a loop to iterate over a list of objects. A simple 3||step iteration +is: + +\starttyping +for i=p,q,r : + fill i withcolor .8white ; + draw i withcolor red ; +endfor ; +\stoptyping +Using \type {for} in this manner can sometimes save a bit of typing. The list can +contain any expression, and may be of different types. + +In the previous example the \type {i} is an independent variable, local to the +for loop. If you want to change the loop variable itself, you need to use \type +{forsuffixes}. In the next loop the paths \type {p}, \type {q} and~\type {r} are +all shifted. + +\starttyping +forsuffixes i = p, q, r : + i := i shifted (3cm,2cm) ; +endfor ; +\stoptyping + +Sometimes you may want to loop forever until a specific condition occurs. For +this, \METAPOST\ provides a special looping mechanism: + +\startbuffer[demo] +numeric done[][], i, j, n ; n := 0 ; +forever : + i := round(uniformdeviate(10)) ; j := round(uniformdeviate(2)) ; + if unknown done[i][j] : + drawdot (i*cm,j*cm) ; n := n + 1 ; done[i][j] := n ; + fi ; + exitif n = 10 ; +endfor ; +\stopbuffer + +\typebuffer[demo] + +Here we remain in the loop until we have 10 points placed. We use an array to +keep track of placed points. The \METAPOST\ macro \type {uniformdeviate(n)} +returns a random number between 0 and~n and the \type {round} command is used to +move the result toward the nearest integer. The \type {unknown} primitive allows +us to test if the array element already exists, otherwise we exit the +conditional. This saves a bit of computational time as each point is drawn and +indexed only once. + +\startbuffer[pen] +pickup pencircle scaled 2mm ; +\stopbuffer + +\startlinecorrection[blank] +\processMPbuffer[pen,demo] +\stoplinecorrection + +The loop terminator \type {exitif} and its companion \type {exitunless} can be +used in \type {for}, \type {forsuffixes} and \type {forever}. + +\stopsection + +\startsection[title={Macros}] + +\index{macros} +\index{definitions} + +In the previous section we introduced \type {upto}. Actually this is not part of +the built in syntax, but a sort of shortcut, defined by: + +\starttyping +def upto = step 1 until enddef ; +\stoptyping + +You just saw a macro definition where \type {upto} is the name of the macro. The +counterpart of \type {upto} is \type {downto}. Whenever you use \type {upto}, it +is replaced by \typ {step 1 until}. This replacement is called expansion. + +There are several types of macros. A primary macro is used to define your own +operators. For example: + +\starttyping +primarydef p doublescaled s = + p xscaled (s/2) yscaled (s*2) +enddef ; +\stoptyping + +Once defined, the \type {doublescaled} macro is implemented as in the following +example: + +\starttyping +draw somepath doublescaled 2cm withcolor red ; +\stoptyping + +When this command is executed, the macro is expanded. Thus, the actual content of +this command becomes: + +\starttyping +draw somepath xscaled 1cm yscaled 4cm withcolor red ; +\stoptyping + +If in the definition of \type {doublescaled} we had added a semi||colon after +\type {(s*2)}, we could not have set the color, because the semicolon ends the +statement. The \type {draw} expects a path, so the macro can best return one. + +A macro can take one or more arguments, as in: + +\starttyping +def drawrandomscaledpath (expr p, s) = + draw p xscaled (s/2) yscaled (s*2) ; +enddef ; +\stoptyping + +When using this macro, it is expected that you will pass it two parameters, the +first being a path, the second a numeric scale factor. + +\starttyping +drawrandomscaledpath(fullsquare, 3cm) ; +\stoptyping + +Sometimes we want to return a value from a macro. In that case we must make sure +that any calculations don't interfere with the expectations. Consider: + +\starttyping +vardef randomscaledpath(expr p, s) = + numeric r ; r := round(1 + uniformdeviate(4)) ; + p xscaled (s/r) yscaled (s*r) +enddef ; +\stoptyping + +Because we want to use the same value of \type {r} twice, we have to use an +intermediate variable. By using a \type {vardef} we hide everything but the last +statement. It is important to distinguish \type {def} macros from those defined +with \type {vardef}. In the latter case, \type {vardef} macros are not a simple +expansion and replacement. Rather, \type {vardef} macros return the value of +their last statement. In the case of the \type {randomscaledpath} macro, a path +is returned. This macro is used in the following manner: + +\starttyping +path mypath ; mypath := randomscaledpath(unitsquare,4cm) ; +\stoptyping + +Note that we send \type {randomscaledpath} a path (\type {unitsquare}) and a +scaling factor (\type {4cm}). The macro returns a scaled path which is then +stored in the path variable \type {mypath}. + +The following argument types are accepted: + +\starttabulate +\HL +\NC expr \NC something that can be assigned to a variable \NC \NR +\NC text \NC arbitrary \METAPOST\ code ending with a \type {;} \NC \NR +\NC suffix \NC a variable bound to another variable \NC \NR +\HL +\stoptabulate +An expression is passed by value. This means that in the body of the macro, a +copy is used and the original is left untouched. On the other hand, any change to +a variable passed as suffix is also applied to the original. + +Local variables must be handled in a special manner, since they may conflict with +variables used elsewhere. This is because all variables are global by default. +The way out of this problem is using grouping in combination with saving +variables. The use of grouping is not restricted to macros and may be used +anywhere in your code. Variables saved and declared in a group are local to that +group. Once the group is exited the variables cease to exist. + +\starttyping +vardef randomscaledpath(expr p, s) = + begingroup ; save r ; numeric r ; + r := round(1 + uniformdeviate(4)) ; + p xscaled (s/r) yscaled (s*r) + endgroup +enddef ; +\stoptyping + +In this particular case, we could have omitted the grouping, since \type {vardef} +macros are always grouped automatically. Therefore, we could have defined the +macro as: + +\starttyping +vardef randomscaledpath(expr p, s) = + save r ; numeric r ; r := round(1 + uniformdeviate(4)) ; + p xscaled (s/r) yscaled (s*r) +enddef ; +\stoptyping + +The command \type {save r} declares that the variable \type {r} is local to the +macro. Thus, any changes to the (new) numeric variable \type {r} are local and +will not interfere with a variable \type {r} defined outside the macro. This is +important to understand, as variables outside the macro are global and accessible +to the code within the body of the macro. + +Macro definitions may be nested, but since most \METAPOST\ code is relatively +simple, it is seldom needed. Nesting is discouraged as it makes your code less +readable. + +Besides \type {def} and \type {vardef}, \METAPOST\ also provides the classifiers +\type {primarydef}, \type {secondarydef} and \type {tertiarydef}. You can use +these classifiers to define macros like those provided by \METAPOST\ itself: + +\starttyping +primarydef x mod y = ... enddef ; +secondarydef p intersectionpoint q = ... enddef ; +tertiarydef p softjoin q = ... enddef ; +\stoptyping +A primary macro acts like the binary operators \type {*} or \type {scaled} and +\type {shifted}. Secondary macros are like \type {+}, \type {-} and logical \type +{or}, and take less precedence. The tertiary operators like \type {<} or the path +and string concatenation operator \type {&} have tertiary macros as companions. +More details can be found in the \METAFONT\ book. When it comes to taking +precedence, \METAPOST\ tries to be as natural as possible, in the sense that you +need to provide as few \type {( )}'s as possible. When in doubt, or when +surprised by unexpected results, use parentheses. + +\stopsection + +\startsection[title={Arguments}] + +\index{arguments} +\index{macros+arguments} + +The \METAPOST\ macro language is rather flexible in how you feed arguments to +macros. If you have only one argument, the following definitions and calls are +valid. + +\starttyping +def test expr a = enddef ; test (a) ; test a ; +def test (expr a) = enddef ; test (a) ; test a ; +\stoptyping + +A more complex definition is the following. As you can see, you can call the +\type {test} macro in your favorite way. + +\starttyping +def test (expr a,b) (expr c,d) = enddef ; + +test (a) (b) (c) (d) ; +test (a,b) (c,d) ; +test (a,b,c) (d) ; +test (a,b,c,d) ; +\stoptyping + +The type of the arguments is one of \type {expr}, \type {primary} or \type +{suffix}. When fetching arguments, \METAPOST\ uses the type to determine how and +what to grab. A fourth type is \type {text}. When no parenthesis are used, a +\type {text} argument grabs everything upto the next semicolon. + +\starttyping +def test (expr a) text b = enddef ; + +test (a) ; test (a) b ; +\stoptyping + +You can use a \type {text} to grab arguments like \typ {withpen pencircle scaled +10 withcolor red}. Because \type {text} is so hungry, you may occasionally need a +two stage definition: + +\starttyping +def test expr a = dotext(a) enddef ; +def dotest (expr a) text b = ... enddef ; + +test a ; test a b ; +\stoptyping + +This definition permits arguments without parenthesis, which is something you +want with commands like \type {draw}. + +The \type {vardef} alternative behaves in a similar way. It always provides +grouping. You need to generate a return value and as a result may not end with a +semicolon. + +You may consider the whole \type {vardef} to be encapsulated into parenthesis and +thereby to be a (self contained) variable. Adding additional parenthesis often +does more harm than good: + +\starttyping +vardef test (expr a) = + ( do tricky things with a ; manipulated_a ) +enddef ; +\stoptyping + +Here the tricky things become part of the return value, which quite certainly is +something that you don't want. + +The three operator look||alike macro definitions are less flexible and have the +definition scheme: + +\starttyping +primarydef x test y = enddef ; +secondarydef x test y = enddef ; +tertiarydef x test y = enddef ; +\stoptyping + +When defining macros using this threesome you need to be aware of the associated +priorities. When using these definitions, you also have to provide your own +grouping. + +In the plain \METAPOST\ macro collection (\type {plain.mp}) you can find many +examples of clever definitions. The following (simplified) version of \type {min} +demonstrates how we use the argument handler to isolate the first argument from +the provided list, simply by using two arguments. + +\starttyping +vardef min (expr u) (text t) = + save min_u ; min_u := u ; + for uu = t : if uu<u : min_u := uu ; fi endfor + min_u +enddef ; +\stoptyping + +The special sequence \type {@#} is used to pick up a so called delimited argument: + +\starttyping +vardef TryMe@#(expr x) = + % we can now use @#, which is just text +enddef ; +\stoptyping + +This feature is used in the definition of \type {z} as used in \type {z1} or +\type {z234}: + +\starttyping +vardef z@# = (x@#,y@#) enddef ; +\stoptyping + +Other applications can be found in the label drawing macros where the anchor +point is assigned to the obscure variable \type {@#}. + +\stopsection + +\startsection[title={Pens}] + +\index{pens} + +When drawing, three attributes can be applied to it: a dashpattern, a pen +and|/|or a color. You may consider an arrowhead an attribute, but actually it is +just an additional drawing, appended to the path. + +The (predefined) \type {pencircle} attribute looks like: + +\starttyping +withpen pencircle +\stoptyping + +where \type {pencircle} is a special kind of path, stored in a pen variable. Like +any path, you can transform it. You can scale it equally in all directions: + +\starttyping +withpen pencircle scaled 1mm +\stoptyping + +You can also provide unequal scales, creating an elliptically shaped and rotated +pen. + +\starttyping +withpen pencircle xscaled 2mm yscaled 4mm rotated 30 +\stoptyping + +In the following graphic, the circle in the center is drawn without any option, +which means that the default pen is used, being a pencircle with a radius of half +a base point. The other three circles are drawn with different pen +specifications. + +\startlinecorrection[blank] +\startMPcode +path p ; p := fullcircle scaled 1cm ; +drawoptions (withcolor .625yellow) ; +draw p ; +drawoptions (withcolor .625red) ; +draw p scaled 2 withpen pencircle ; +drawoptions (withcolor .625yellow) ; +draw p scaled 3 withpen pencircle scaled 1mm ; +drawoptions (withcolor .625red) ; +draw p scaled 4 withpen pencircle xscaled 2mm yscaled 4mm rotated 30 ; +\stopMPcode +\stoplinecorrection + +If you forget about the colors, the \METAPOST\ code to achieve this is as +follows. + +\starttyping +path p ; p := fullcircle scaled 1cm ; +draw p ; +draw p scaled 2 withpen pencircle ; +draw p scaled 3 withpen pencircle scaled 1mm ; +draw p scaled 4 withpen pencircle xscaled 2mm yscaled 4mm rotated 30 ; +\stoptyping + +If this were the only way of specifying a pen, we would be faced with a +considerable amount of typing, particularly in situations where we use pens +similar to the fourth specification above. For that reason, \METAPOST\ supports +the concept of a current pen. The best way to set this pen is to use the \type +{pickup} macro. + +\starttyping +pickup pencircle xscaled 2mm yscaled 4mm rotated 30 ; +\stoptyping + +This macro also stores some characteristics of the pen in variables, so that they +can be used in (the more complicated) calculations that are involved in +situations like drawing font||like graphics. + +If we substitute \type {pencircle} by \type {pensquare}, we get a different kind +of shapes. In the non rotated pens, the top, bottom, left and right parts of the +curve are thinner. + +\startlinecorrection[blank] +\startMPcode +path p ; p := fullcircle scaled 1cm ; +drawoptions (withcolor .625yellow) ; +draw p ; +drawoptions (withcolor .625red) ; +draw p scaled 2 withpen pensquare ; +drawoptions (withcolor .625yellow) ; +draw p scaled 3 withpen pensquare scaled 1mm ; +drawoptions (withcolor .625red) ; +draw p scaled 4 withpen pensquare xscaled 2mm yscaled 4mm rotated 30 ; +\stopMPcode +\stoplinecorrection + +You should look at pens in the way an artist does. He follows a shape and in +doing so he or she twists the pen (and thereby the nib) and puts more or less +pressure on it. + +The chance that you have an appropriate pen laying at your desk is not so big, +but you can simulate the following \METAPOST's pen by taking two pencils and +holding them together in one hand. If you position them in a 45 degrees angle, +and draw a circle, you will get something like: + +\startlinecorrection[blank] +\startMPcode +path p ; p := fullcircle xscaled 2cm yscaled 3cm ; +drawoptions(withcolor .625red withpen pencircle scaled .5mm); +draw p ; draw p shifted (.3cm,.3cm) ; +\stopMPcode +\stoplinecorrection + +If you take a calligraphic pen with a thin edge of .5cm, you will get: + +\startlinecorrection[blank] +\startMPcode +drawoptions(withcolor .625red); +path p ; p := fullcircle xscaled 2cm yscaled 3cm ; +draw p withpen makepen ((0,0)--(.3cm,.3cm)) withcolor .625white ; +drawoptions(withcolor .625red withpen pencircle scaled .25mm); +draw p ; draw p shifted (.3cm,.3cm) ; +\stopMPcode +\stoplinecorrection + +You can define such a pen yourself: + +\starttyping +path p ; p := fullcircle xscaled 2cm yscaled 3cm ; +pen doublepen ; doublepen := makepen ((0,0)--(.3cm,.3cm)) ; +pickup doublepen ; draw p ; +\stoptyping + +Here we define a new pen using the \type {pen} command. Then we define a path, +and make a pen out of it using the \type {makepen} macro. The path should be a +relatively simple one, otherwise \METAPOST\ will complain. + +You can use \type {makepen} with the previously introduced \type {withpen}: + +\starttyping +draw p withpen makepen ((0,0)--(.3cm,.3cm)) ; +\stoptyping + +and \type {pickup}: + +\starttyping +pickup makepen ((0,0)--(.3cm,.3cm)) ; draw p ; +\stoptyping + +You can use \type {makepen} and \type {makepath} to convert paths into pens and +vice versa. + +Pens are very important when defining fonts, and \METAFONT\ is meant to be a font +creation tool. Since \METAPOST\ has a slightly different audience, it lacks some +features in this area, but offers a few others instead. Nevertheless, one can try +to design a font using \METAPOST. Of course, pens are among the designers best +kept secrets. But even then, not every~O is a nice looking one. + +\startlinecorrection[blank] +\startMPcode +path p ; p := fullcircle xscaled 2cm yscaled 3cm ; +draw p withpen makepen (unitsquare scaled .4cm superellipsed .85) +withcolor .625white ; +\stopMPcode +\stoplinecorrection + +\startbuffer[s00] + path p ; p := (-1,0) {down} .. {up} (1,0) ; + draw pensilled(p, pensquare scaled (1/3)) + scaled 2cm ; + draw boundingbox image(draw p) + scaled 2cm ; +\stopbuffer + +\startbuffer[s30] + path p ; p := (-1,0) {down} .. {up} (1,0) ; + draw pensilled(p, pensquare scaled (1/3) rotated 30) + scaled 2cm ; + draw boundingbox image(draw p) + scaled 2cm ; +\stopbuffer + +\startbuffer[s45] + path p ; p := (-1,0) {down} .. {up} (1,0) ; + draw pensilled(p, pensquare scaled (1/3) rotated 45) + scaled 2cm ; + draw boundingbox image(draw p) + scaled 2cm ; +\stopbuffer + +\startbuffer[c00] + path p ; p := (-1,0) {down} .. {up} (1,0) ; + draw pensilled(p, pencircle scaled (1/3)) + scaled 2cm ; + draw boundingbox image(draw p) + scaled 2cm ; +\stopbuffer + +\startbuffer[c30] + path p ; p := (-1,0) {down} .. {up} (1,0) ; + draw pensilled(p, pencircle scaled (1/3) rotated 30) + scaled 2cm ; + draw boundingbox image(draw p) + scaled 2cm ; +\stopbuffer + +\startbuffer[c45] + path p ; p := (-1,0) {down} .. {up} (1,0) ; + draw pensilled(p, pencircle scaled (1/3) rotated 45) + scaled 2cm ; + draw boundingbox image(draw p) + scaled 2cm ; +\stopbuffer + +\startbuffer[f30] + interim pensilstep := 1/6 ; + draw pensilled(fullcircle, pencircle xscaled (1/10) yscaled (2/10) rotated 30) + scaled 5cm ; + draw boundingbox fullcircle + scaled 5cm ; +\stopbuffer + +The \type {pensilled} macro is a variant on a macro used for testing some border +cases in the engine. It provides a nice way to see what actually happens when a +pen is applied. \in {Figure} [fig:pensilled] demonstrates this macro. The first +row shows a square pen: + +\typebuffer[s30] + +and the second row a circular pen: + +\typebuffer[c30] + +\startplacefigure[title={How pens are applied.},reference=fig:pensilled] + \startcombination[3*2] + {\processMPbuffer[s00]} {\tttf pensquare rotated 0} + {\processMPbuffer[s30]} {\tttf pensquare rotated 30} + {\processMPbuffer[s45]} {\tttf pensquare rotated 45} + {\processMPbuffer[c00]} {\tttf pencircle rotated 0} + {\processMPbuffer[c30]} {\tttf pencircle rotated 30} + {\processMPbuffer[c45]} {\tttf pencircle rotated 45} + \stopcombination +\stopplacefigure + +The effects of rotation and non|-|proportional scaling are demonstrated +in \in {figure} [fig:pensilled:fullcircle]. + +\typebuffer[f30] + +\startplacefigure[title={A proportionally scaled and rotated pen.},reference=fig:pensilled:fullcircle] + \processMPbuffer[f30] +\stopplacefigure + +\stopsection + +\startsection[title={Joining lines}] + +\index{joining} +\index{paths+joining} + +The way lines are joined or end is closely related to the way \POSTSCRIPT\ +handles this. By setting the variables \type {linejoin} and \type {linecap}, you +can influence the drawing process. \in {Figure} [fig:joints] demonstrates the +alternatives. The gray curves are drawn with both variables set to \type +{rounded}. + +\startnotmode[screen] + +\def\showMPline#1#2% + {\startMPcode + path p ; p := ((0,0)--(.5,1)--(1,0)) xscaled 3cm yscaled 1.5cm ; + pickup pencircle scaled 1cm ; + draw p withcolor .625white ; + interim linejoin := #1 ; + interim linecap := #2 ; + draw p withcolor transparent(1,.5,.625yellow) ; + \stopMPcode} + +\stopnotmode + +\startmode[screen] + +\def\showMPline#1#2% + {\startMPcode + path p ; p := ((0,0)--(.5,1)--(1,0)) xscaled 2.5cm yscaled 1.25cm ; + pickup pencircle scaled .75cm ; + draw p withcolor .625white ; + interim linejoin := #1 ; + interim linecap := #2 ; + draw p withcolor transparent(1,.5,.625yellow) ; + \stopMPcode} + +\stopmode + +\def\showMPtext#1#2% + {linejoin=#1\par linecap=#2} + +\startbuffer +\startcombination[3*3] + {\showMPline{mitered}{butt}} {\showMPtext{mitered}{butt}} + {\showMPline{mitered}{rounded}} {\showMPtext{mitered}{rounded}} + {\showMPline{mitered}{squared}} {\showMPtext{mitered}{squared}} + {\showMPline{rounded}{butt}} {\showMPtext{rounded}{butt}} + {\showMPline{rounded}{rounded}} {\showMPtext{rounded}{rounded}} + {\showMPline{rounded}{squared}} {\showMPtext{rounded}{squared}} + {\showMPline{beveled}{butt}} {\showMPtext{beveled}{butt}} + {\showMPline{beveled}{rounded}} {\showMPtext{beveled}{rounded}} + {\showMPline{beveled}{squared}} {\showMPtext{beveled}{squared}} +\stopcombination +\stopbuffer + +\placefigure + [here] [fig:joints] + {The nine ways to end and join lines.} + {\getbuffer} + +By setting the variable \type {miterlimit}, you can influence the mitering of +joints. The next example demonstrates that the value of this variable acts as a +trigger. + +\startbuffer +interim linejoin := mitered ; +for i :=1 step 1 until 5 : + interim miterlimit := i*pt ; + draw ((0,0)--(.5,1)--(1,0)) shifted (1.5i,0) scaled 50pt + withpen pencircle scaled 10pt withcolor .625red ; +endfor ; +\stopbuffer + +\typebuffer + +The variables \type {linejoin}, \type {linecap} and \type {miterlimit} are so +called {\em internal} variables. When we prefix their assignments by \type +{interim}, the setting will be local within groups, like \typ {beginfig ... +endfig}. + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +\stopsection + +\startsection[title={Colors}] + +\index{attributes} +\index{color} +So far, we have seen some colors in graphics. It must be said that \METAPOST\ +color model is not that advanced, although playing with colors in the \METAPOST\ +way can be fun. In later chapters we will discuss some extensions that provide +shading. + +Colors are defined as vectors with three components: a red, green and blue one. +Like pens, colors have their \type {with}||command: + +\starttyping +withcolor (.4,.5.,6) +\stoptyping + +You can define color variables, like: + +\starttyping +color darkred ; darkred := (.625,0.0) ; +\stoptyping + +You can now use this color as: + +\starttyping +withcolor darkred +\stoptyping + +Given that \type {red} is already defined, we also could have said: + +\starttyping +withcolor .625red +\stoptyping + +Because for \METAPOST\ colors are just vectors, you can do things similar to +points. A color halfway red and green is therefore accomplished with: + +\starttyping +withcolor .5[red,green] +\stoptyping + +Since only the \RGB\ color space is supported, this is about all we can tell +about colors for this moment. Later we will discuss some nasty details. + +\stopsection + +\startsection[title={Dashes}] + +\index{dashes} + +A dash pattern is a simple picture that is build out of straight lines. Any +slightly more complicated picture will be reduced to straight lines and a real +complicated one is rejected, and in this respect \METAPOST\ considers a circle to +be a complicated path. + +The next example demonstrates how to get a dashed line. First we built picture +\type {p}, that we apply to a path. Here we use a straight path, but dashing can +be applied to any path. + +\startbuffer +picture p ; p := nullpicture ; +addto p doublepath ((0,0)--(3mm,3mm)) shifted (6mm,6mm) ; +draw (0,0)--(10cm,0) dashed p withpen pencircle scaled 1mm ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +This way of defining a pattern is not that handy, especially if you start +wondering why you need to supply a slanted path. Therefore, \METAPOST\ provides a +more convenient mechanism to define a pattern. + +\startbuffer +picture p ; p := dashpattern(on 3mm off 3mm) ; +draw (0,0)--(10cm,0) dashed p withpen pencircle scaled 1mm ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +Most dashpatterns can be defined in terms of on and off. This simple on||off +dashpattern is predefined as picture \type {evenly}. Because this is a picture, +you can (and often need to) scale it. + +\startbuffer +draw (0,0)--(10cm,0) dashed (evenly scaled 1mm) + withpen pencircle scaled 1mm ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +Opposite to a defaultpen, there is no default color and default dash pattern set. +The macro \type {drawoptions} provides you a way to set the default attributes. + +\starttyping +drawoptions(dashed evenly withcolor red) ; +\stoptyping + +\stopsection + +\startsection[reference=sec:text,title={Text}] + +\index{text} + +Since \METAFONT\ is meant for designing fonts, the only means for including text +are those that permit you to add labels to positions for the sole purpose of +documentation. + +Because \METAPOST\ is derived from \METAFONT\ it provides labels too, but in +order to let users add more sophisticated text, like a math formula, to a +graphic, it also provides an interface to \TEX. + +Because we will spend a whole chapter on using text in \METAPOST\ we limit the +discussion here to a few fundamentals. + +\startbuffer[font] +defaultfont := "\truefontname{Mono}" ; +defaultscale := .8 ; +\stopbuffer + +\startbuffer[label] +pair a ; a := (3cm,3cm) ; +label.top("top",a) ; label.bot("bot",a) ; +label.lft("lft",a) ; label.rt ("rt" ,a) ; +\stopbuffer + +\typebuffer[label] + +These four labels show up at the position stored in the pair variable \type {a}, +anchored in the way specified after the period. + +\startlinecorrection[blank] +\processMPbuffer[font,label] +\stoplinecorrection + +The command \type {dotlabel} also typesets the point as a rather visible dot. + +\startbuffer[label] +pair a ; a := (3cm,3cm) ; +dotlabel.top("top",a) ; dotlabel.bot("bot",a) ; +dotlabel.lft("lft",a) ; dotlabel.rt ("rt" ,a) ; +\stopbuffer + +\typebuffer[label] + +\startlinecorrection[blank] +\processMPbuffer[font,label] +\stoplinecorrection + +The command \type {thelabel} returns the typeset label as picture that you can +manipulate or draw afterwards. + +\startbuffer[label] +pair a ; a := (3cm,3cm) ; pickup pencircle scaled 1mm ; +drawdot a withcolor .625yellow ; +draw thelabel.rt("the right way",a) withcolor .625red ; +\stopbuffer + +\typebuffer[label] + +You can of course rotate, slant and manipulate such a label picture like any +other picture. + +\startlinecorrection[blank] +\processMPbuffer[font,label] +\stoplinecorrection + +The font can be specified in the string \type {defaultfont} and the scale in +\type {defaultscale}. Labels are defined using the low level operator \type +{infont}. The next statement returns a picture: + +\startbuffer[mp] +draw "this string will become a sequence of glyphs (MP)" + infont defaultfont scaled defaultscale ; +\stopbuffer + +\typebuffer[mp] + +By default the \type {infont} operator is not that clever and does not apply +kerning. Also, typesetting math or accented characters are not supported. The way +out of this problem is using \typ {btex ... etex}. + +\startbuffer[tex] +draw btex this string will become a sequence of glyphs (\TeX) etex ; +\stopbuffer + +\typebuffer[tex] + +The difference between those two methods is shown below. The outcome of \type +{infont} depends on the current setting of the variable \type {defaultfont}. + +\startlinecorrection[blank] +\processMPbuffer[mp] +\processMPbuffer[tex] +\stoplinecorrection + +When you run inside \CONTEXT\ (as we do here) there is no difference between +\type {infont} and the \TEX\ methods. This is because we overload the \type +{infont} operator and also pass its content to \TEX. Both \type {infont} and +\type {btex} use the macro \type {textext} which is intercepted and redirects the +task to \TEX. This happens in the current run so there is no need to pass extra +information about fonts. + +Instead of passing strings to \type {infont}, you can also pass characters, using +\type {char}, for example \type {char(73)}. When you use \type {infont} you +normally expect the font to be \ASCII\ conforming. If this is not the case, you +must make sure that the encoding of the font that you use matches your +expectations. However, as we overload this macro it does not really matter since +the string is passed to \TEX\ anyway. For instance, \UTF\ encoded text should +work fine as \CONTEXT\ itself understands this encoding. + +\stopsection + +\startsection[title={Linear equations}] + +\index{equations} +\index{expressions} + +\startbuffer[a] +\defineMPinstance + [solvers] + [format=metafun, + extensions=yes, + initializations=yes] +\stopbuffer + +\startbuffer[b] +\startMPdefinitions{solvers} +def draw_problem (expr p, q, r, s, show_labels) = + begingroup ; save x, y, a, b, c, d, e, f, g, h ; + + z11 = z42 = p ; z21 = z12 = q ; z31 = z22 = r ; z41 = z32 = s ; + + a = x12 - x11 ; b = y12 - y11 ; c = x22 - x21 ; d = y22 - y21 ; + e = x32 - x31 ; f = y32 - y31 ; g = x42 - x41 ; h = y42 - y41 ; + + z11 = (x11, y11) ; z12 = (x12, y12) ; + z13 = (x12-b, y12+a) ; z14 = (x11-b, y11+a) ; + z21 = (x21, y21) ; z22 = (x22, y22) ; + z23 = (x22-d, y22+c) ; z24 = (x21-d, y21+c) ; + z31 = (x31, y31) ; z32 = (x32, y32) ; + z33 = (x32-f, y32+e) ; z34 = (x31-f, y31+e) ; + z41 = (x41, y41) ; z42 = (x42, y42) ; + z43 = (x42-h, y42+g) ; z44 = (x41-h, y41+g) ; + + pickup pencircle scaled .5pt ; + + draw z11--z12--z13--z14--cycle ; draw z11--z13 ; draw z12--z14 ; + draw z21--z22--z23--z24--cycle ; draw z21--z23 ; draw z22--z24 ; + draw z31--z32--z33--z34--cycle ; draw z31--z33 ; draw z32--z34 ; + draw z41--z42--z43--z44--cycle ; draw z41--z43 ; draw z42--z44 ; + + z1 = 0.5[z11,z13] ; z2 = 0.5[z21,z23] ; + z3 = 0.5[z31,z33] ; z4 = 0.5[z41,z43] ; + + draw z1--z3 dashed evenly ; draw z2--z4 dashed evenly ; + + z0 = whatever[z1,z3] = whatever[z2,z4] ; + mark_rt_angle (z1, z0, z2) ; % z2 is not used at all + + if show_labels > 0 : + draw_problem_labels ; + fi ; + + endgroup ; +enddef ; +\stopMPdefinitions +\stopbuffer + +\startbuffer[c] +\startMPdefinitions{solvers} +angle_radius := 10pt ; + +def mark_rt_angle (expr a, b, c) = + draw ((1,0)--(1,1)--(0,1)) + zscaled (angle_radius*unitvector(a-b)) + shifted b +enddef ; +\stopMPdefinitions +\stopbuffer + +\startbuffer[d] +\startMPdefinitions{solvers} +def draw_problem_labels = + pickup pencircle scaled 5pt ; + + dotlabel.llft("$Z_{11}$", z11) ; dotlabel.ulft("$Z_{12}$", z12) ; + dotlabel.ulft("$Z_{13}$", z13) ; dotlabel.llft("$Z_{14}$", z14) ; + + dotlabel.lrt ("$Z_{21}$", z21) ; dotlabel.llft("$Z_{22}$", z22) ; + dotlabel.urt ("$Z_{23}$", z23) ; dotlabel.ulft("$Z_{24}$", z24) ; + + dotlabel.urt ("$Z_{31}$", z31) ; dotlabel.ulft("$Z_{32}$", z32) ; + dotlabel.urt ("$Z_{33}$", z33) ; dotlabel.urt ("$Z_{34}$", z34) ; + + dotlabel.lrt ("$Z_{41}$", z41) ; dotlabel.urt ("$Z_{42}$", z42) ; + dotlabel.llft("$Z_{43}$", z43) ; dotlabel.lrt ("$Z_{44}$", z44) ; + + dotlabel.urt ("$Z_{0}$", z0) ; + dotlabel.lft ("$Z_{1}$", z1) ; dotlabel.top ("$Z_{2}$", z2) ; + dotlabel.rt ("$Z_{3}$", z3) ; dotlabel.bot ("$Z_{4}$", z4) ; +enddef ; +\stopMPdefinitions +\stopbuffer + +\startbuffer[e] +\startuseMPgraphic{solvers::one}{i,j,s} + draw_problem ( + (400pt,400pt), (300pt,600pt), + \MPvar{i}[(300pt,600pt), (550pt,800pt)], + \MPvar{j}[(400pt,400pt), (550pt,500pt)], + \MPvar{s} + ) ; +\stopuseMPgraphic +\stopbuffer + +\startbuffer[f] +\placefigure + [here][fig:problem] + {The problem.} + {\scale + [width=\textwidth] + {\useMPgraphic{solvers::one}{i=0.6,j=1.0,s=1}}} +\stopbuffer + +In the previous sections, we used the assignment operator \type {:=} to assign a +value to a variable. Although for most of the graphics that we will present in +later chapters, an assignment is appropriate, specifying a graphic in terms of +expressions is not only more flexible, but also more in the spirit of the +designers of \METAFONT\ and \METAPOST. + +The \METAFONT\ book and \METAPOST\ manual provide lots of examples, some of which +involve math that we don't consider to belong to everyones repertoire. But, even +for non mathematicians using expressions can be a rewarding challenge. + +The next introduction to linear equations is based on my first experiences with +\METAPOST\ and involves a mathematical challenge posed by a friend. I quickly +ascertained that a graphical proof was far more easy than some proof with a lot +of $\sin (this)$ and $\cos (that)$ and long forgotten formulas. + +I was expected to prove that the lines connecting the centers of four squares +drawn upon the four sides of a quadrilateral were perpendicular (see \in {figure} +[fig:problem]). + +\getbuffer[a,b,c,d,e] + +\getbuffer[f] + +This graphic was generated with the following command: + +\typebuffer[f] + +We will use this example to introduce a few new concepts, one being instances. In +a large document there can be many \METAPOST\ graphics and they might fall in +different categories. In this manual we have graphics that are generated as part +of the style as wel as examples that show what \METAFUN\ can do. As definitions +and variables in \METAPOST\ are global by default, there is a possibility that we +end up with clashes. This can be avoided by grouping graphics in instances. Here +we create an instance for the example that we're about to show. + +\typebuffer[a] + +We can now limit the scope of definitions to this specific instance. Let's start +with the macro that takes care of drawing the solution to our problem. The macro +accepts four pairs of coordinates that determine the central quadrilateral. All +of them are expressions. + +\typebuffer[b] + +Because we want to call this macro more than once, we first have to save the +locally used values. Instead of declaring local variables, one can hide their use +from the outside world. In most cases variables behave globally. If we don't save +them, subsequent calls will lead to errors due to conflicting equations. We can +omit the grouping commands, because we wrap the graphic in a figure, and figures +are grouped already. + +We will use the predefined \type {z} variable, or actually a macro that returns a +variable. This variable has two components, an \type {x} and \type {y} +coordinate. So, we don't save \type {z}, but the related variables \type {x} and +\type {y}. + +Next we draw four squares and instead of hard coding their corner points, we use +\METAPOST's equation solver. Watch the use of \type {=} which means that we just +state dependencies. In languages like \PERL, the equal sign is used in +assignments, but in \METAPOST\ it is used to express relations. + +In a first version, we will just name a lot of simple relations, as we can read +them from a sketch drawn on paper. So, we end up with quite some \type {z} +related expressions. + +For those interested in the mathematics behind this code, we add a short +explanation. Absolutely key to the construction is the fact that you traverse the +original quadrilateral in a clockwise orientation. What is really going on here +is vector geometry. You calculate the vector from $z_{11}$ to $z_{12}$ (the first +side of the original quadrilateral) with: + +\starttyping +(a,b) = z12 - z11 ; +\stoptyping + +This gives a vector that points from $z_{11}$ to $z_{12}$. Now, how about an +image that shows that the vector $(-b,a)$ is a 90 degree rotation in the +counterclockwise direction. Thus, the points $z_{13}$ and $z_{14}$ are easily +calculated with vector addition. + +\starttyping +z13 = z12 + (-b,a) ; +z14 = z11 + (-b,a) ; +\stoptyping + +This pattern continues as you move around the original quadrilateral in a +clockwise manner. \footnote {Thanks to David Arnold for this bonus explanation.} + +The code that calculates the pairs \type {a} through \type {h}, can be written in +a more compact way. + +\starttyping +(a,b) = z12 - z11 ; (c,d) = z22 - z21 ; +(e,f) = z32 - z31 ; (g,h) = z42 - z41 ; +\stoptyping + +The centers of each square can also be calculated by \METAPOST. The next lines +define that those points are positioned halfway the extremes. + +\starttyping +z1 = 0.5[z11,z13] ; z2 = 0.5[z21,z23] ; +z3 = 0.5[z31,z33] ; z4 = 0.5[z41,z43] ; +\stoptyping + +Once we have defined the relations we can let \METAPOST\ solve the equations. +This is triggered when a variable is needed, for instance when we draw the +squares and their diagonals. We connect the centers of the squares using a dashed +line style. + +Just to be complete, we add a symbol that marks the right angle. First we +determine the common point of the two lines, that lays at {\em whatever} point +\METAPOST\ finds suitable. + +The definition of \type {mark_rt_angle} is copied from the \METAPOST\ manual and +shows how compact a definition can be (see \at {page} [zscaled] for an +introduction to \type {zscaled}). + +\typebuffer[c] + +So far, most equations are rather simple, and in order to solve them, \METAPOST\ +did not have to work real hard. The only boundary condition is that in order to +find a solution, \METAPOST\ must be able to solve all dependencies. + +The actual value of the \type {whatever} variable is that it saves us from +introducing a slew of variables that will never be used again. We could write: + +\starttyping +z0 = A[z1,z3] = B[z2,z4] ; +\stoptyping + +and get the same result, but the \type {whatever} variable saves us the trouble +of introducing intermediate variables for which we have no use once the +calculation is finished. + +The macro \type{mark_rt_angle} draws the angle symbol and later we will see how +it is defined. First we draw the labels. Unfortunately we cannot package \typ +{btex ... etex} into a macro, because it is processed in a rather special way. +Each \typ {btex ... etex} occurance is filtered from the source and converted +into a snippet of \TEX\ code. When passed through \TEX, each snippet becomes a +page, and an auxiliary program converts each page into a \METAPOST\ picture +definition, which is loaded by \METAPOST. The limitation lays in the fact that +the filtering is done independent from the \METAPOST\ run, which means that loops +(and other code) are not seen at all. Later we will introduce the \METAFUN\ way +around this. + +In order to get all the labels typeset, we have to put a lot of code here. The +macro \type {dotlabel} draws a dot and places the typeset label. + +\typebuffer[d] + +Watch out: as we are in \CONTEXT, we can pass regular \TEX\ code to the label +macro. In a standalone \METAPOST\ run you'd have to use the \type {btex} variant. + +We are going to draw a lot of pictures, so we define an extra macro. This time we +hard||code some values. The fractions \type {i} and \type {j} are responsible for +the visual iteration process, while \type {s} determines the labels. We pass +these variables to the graphic using an extra argument. When you define the +(useable) graphic you need to tell what variables it can expect. + +\typebuffer[e] + +Of course we could have used a loop construct here, but defining auxiliary macros +probably takes more time than simply calling the drawing macro directly. The +results are shown on a separate page (\in{figure}[fig:solution]). + +\startbuffer[x] +\def\MyTest#1#2% + {\scale + [width=.25\textwidth] + {\useMPgraphic{solvers::one}{i=#1,j=#2,s=0}}} +\stopbuffer + +\startbuffer[y] + \startcombination[3*4] + {\MyTest{1.0}{1.0}} {1.0 / 1.0} {\MyTest{0.8}{1.0}} {0.8 / 1.0} + {\MyTest{0.6}{1.0}} {0.6 / 1.0} {\MyTest{0.4}{1.0}} {0.4 / 1.0} + {\MyTest{0.2}{1.0}} {0.2 / 1.0} {\MyTest{0.0}{1.0}} {0.0 / 1.0} + {\MyTest{0.0}{1.0}} {0.0 / 1.0} {\MyTest{0.0}{0.8}} {0.0 / 0.8} + {\MyTest{0.0}{0.6}} {0.0 / 0.6} {\MyTest{0.0}{0.4}} {0.0 / 0.4} + {\MyTest{0.0}{0.2}} {0.0 / 0.2} {\MyTest{0.0}{0.0}} {0.0 / 0.0} + \stopcombination +\stopbuffer + +We will use a helper macro (that saves us typing): + +\typebuffer[x] + +We now can say: + +\typebuffer[y] + +Watch how we pass the settings to the graphic definition using an extra argument. +We force using the \type {solvers} instance by prefixing the name. + +\startpostponing + + \startnotmode[screen] + \placefigure + [here][fig:solution] + {The solution.} + {\getbuffer[x,y]} + \stopnotmode + + \startmode[screen] + \placefigure + [here][fig:solution] + {The solution.} + {\getbuffer[x,y]} + \stopmode + + \page + +\stoppostponing + +It does not need that much imagination to see the four sided problem converge to +a three sided one, which itself converges to a two sided one. In the two sided +alternative it's not that hard to prove that the angle is indeed 90 degrees. + +As soon as you can see a clear pattern in some code, it's time to consider using +loops. In the previous code, we used semi indexes, like \type {12} in \type +{z12}. In this case \type{12} does reflect something related to square~1 and~2, +but in reality the 12 is just twelve. This does not harm our expressions. + +A different approach is to use a two dimensional array. In doing so, we can +access the variables more easily using loops. If we omit the labels, and angle +macro, the previously defined macro can be reduced considerably. + +\starttyping +def draw_problem (expr n, p, q, r, s) = % number and 4 positions + begingroup ; save x, y ; + + z[1][1] = p ; z[2][1] = q ; z[3][1] = r ; z[4][1] = s ; + + for i=1 upto 4 : + z[i][1] = (x[i][1],y[i][1]) = z[if i=1: 4 else: i-1 fi][2] ; + z[i][2] = (x[i][2],y[i][2]) ; + z[i][3] = (x[i][2]-y[i][2]+y[i][1], y[i][2]+x[i][2]-x[i][1]) ; + z[i][4] = (x[i][1]-y[i][2]+y[i][1], y[i][1]+x[i][2]-x[i][1]) ; + z[i] = 0.5[z[i][1],z[i][3]] ; + endfor ; + + z[0] = whatever[z[1],z[3]] = whatever[z[2],z[4]] ; + + pickup pencircle scaled .5pt ; + + for i=1 upto 4 : + draw z[i][1]--z[i][2]--z[i][3]--z[i][4]--cycle ; + draw z[i][1]--z[i][3] ; draw z[i][2]--z[i][4] ; + if i<3 : draw z[i]--z[i+2] dashed evenly fi ; + endfor ; + + draw ((1,0)--(1,1)--(0,1)) + zscaled (unitvector(z[1]-z[0])*10pt) + shifted z[0] ; + + endgroup ; +enddef ; +\stoptyping + +I think that we could argue quite some time about the readability of this code. +If you start from a sketch, and the series of equations does a good job, there is +hardly any need for such improvements to the code. On the other hand, there are +situations where the simplified (reduced) case can be extended more easily, for +instance to handle 10 points instead of~4. It all depends on how you want to +spend your free hours. + +\stopsection + +\startsection[title={Clipping}] + +\index{clipping} + +For applications that do something with a drawing, for instance \TEX\ embedding a +graphic in a text flow, it is important to know the dimensions of the graphic. +The maximum dimensions of a graphic are specified by its bounding box. + +\startlinecorrection[blank] +\startMPcode +path p ; p := fullcircle scaled 3cm ; +draw p withpen pencircle scaled 1mm withcolor .625red ; +draw boundingbox p withpen pencircle scaled .1mm ; +draw llcorner boundingbox p withpen pencircle scaled 2mm withcolor .625yellow ; +draw urcorner boundingbox p withpen pencircle scaled 2mm withcolor .625yellow ; +\stopMPcode +\stoplinecorrection + +A bounding box is defined by its lower left and upper right corners. If you open +the \POSTSCRIPT\ file produced by \METAPOST, you may find lines like: + +\starttyping +%%BoundingBox: -46 -46 46 46 +\stoptyping + +or, when supported, + +\starttyping +%%HiResBoundingBox: -45.35432 -45.35432 45.35432 45.35432 +\stoptyping + +The first two numbers define the lower left corner and the last two numbers the +upper right corner. From these values, you can calculate the width and height of +the graphic. + +A graphic may extend beyond its bounding box. It depends on the application that +uses the graphic whether that part of the graphic is shown. + +In \METAPOST\ you can ask for all four points of the bounding box of a path or +picture as well as the center. + +\starttabulate[|lT|l|] +\HL +\NC llcorner p \NC lower left corner \NC \NR +\NC lrcorner p \NC lower right corner \NC \NR +\NC urcorner p \NC upper right corner \NC \NR +\NC ulcorner p \NC upper left corner \NC \NR +\NC center p \NC the center point \NC \NR +\HL +\stoptabulate + +You can construct the bounding box of path~\type {p} out of the four points +mentioned: + +\starttyping +llcorner p -- lrcorner p -- urcorner p -- ulcorner p -- cycle +\stoptyping + +You can set the bounding box of a picture, which can be handy if you want to +build a picture in steps and show the intermediate results using the same +dimensions as the final picture, or when you want to show only a small piece. + +\startbuffer +fill fullcircle scaled 2cm withcolor .625yellow ; +setbounds currentpicture to unitsquare scaled 1cm ; +draw unitsquare scaled 1cm withcolor .625red ; +\stopbuffer + +\typebuffer + +Here, we set the bounding box with the command \type {setbounds}, which takes a +path. + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +The graphic extends beyond the bounding box, but the bounding box determines the +placement and therefore the spacing around the graphic. We can get rid of the +artwork outside the bounding box by clipping it. + +\startbuffer +fill fullcircle scaled 2cm withcolor .625yellow ; +clip currentpicture to unitsquare scaled 1cm ; +\stopbuffer + +\typebuffer + +The resulting picture is just as large but shows less of the picture. + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +\stopsection + +\startsection[title={Some extensions}] + +We will now encounter a couple of transformations that can make your life easy +when you use \METAPOST\ for making graphics like the ones demonstrated in this +document. These transformations are not part of standard \METAPOST, but come with +\METAFUN. + +A very handy extension is \type {enlarged}. Although you can feed it with any +path, it will return a rectangle larger or smaller than the boundingbox of that +path. You can specify a pair or a numeric. + +\startbuffer +path p ; p := fullsquare scaled 2cm ; +drawpath p ; drawpoints p ; +p := (p shifted (3cm,0)) enlarged (.5cm,.25cm) ; +drawpath p ; drawpoints p ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] \processMPbuffer \stoplinecorrection + +There are a few more alternatives, like \type {bottomenlarged}, \type +{rightenlarged}, \type {topenlarged} and \type {leftenlarged}. + +The \type {cornered} operator will replace sharp corners by rounded ones (we +could not use \type {rounded} because this is already in use). + +\startbuffer +path p ; p := ((1,0)--(2,0)--(2,2)--(1,2)--(0,1)--cycle) + xysized (4cm,2cm) ; +drawpath p ; drawpoints p ; +p := (p shifted (5cm,0)) cornered .5cm ; +drawpath p ; drawpoints p ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] \processMPbuffer \stoplinecorrection + +The \type {smoothed} operation is a less subtle one, since it operates on the +bounding box and thereby can result in a different shape. + +\startbuffer +path p ; p := ((1,0)--(2,0)--(2,2)--cycle) xysized (4cm,2cm) ; +drawpath p ; drawpoints p ; +p := (p shifted (5cm,0)) smoothed .5cm ; +drawpath p ; drawpoints p ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] \processMPbuffer \stoplinecorrection + +The next one, \type {simplified}, can be applied to paths that are constructed +automatically. Instead of testing for duplicate points during construction, you +can clean up the path afterwards. + +\startbuffer +path p ; p := + ((0,0)--(1,0)--(2,0)--(2,1)--(2,2)--(1,2)--(0,2)--(0,1)--cycle) + xysized (4cm,2cm) ; +drawpath p ; drawpoints p ; +p := simplified (p shifted (5cm,0)) ; +drawpath p ; drawpoints p ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] \processMPbuffer \stoplinecorrection + +A cousin of the previous operation is \type {unspiked}. This one removes ugly +left|-|overs. It works well for the average case. + +\startbuffer +path p ; p := + ((0,0)--(2,0)--(3,1)--(2,0)--(2,2)--(1,2)--(1,3)--(1,2)--(0,1)--cycle) + xysized (4cm,2cm) ; +drawpath p ; drawpoints p ; +p := unspiked (p shifted (5cm,0)) ; +drawpath p ; drawpoints p ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] \processMPbuffer \stoplinecorrection + +There are a couple of operations that manipulate the path in more drastic ways. +Take \type {randomized}. + +\startbuffer +path p ; p := fullsquare scaled 2cm ; +drawpath p ; drawpoints p ; +p := (p shifted (5cm,0)) randomized .5cm ; +drawpath p ; drawpoints p ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] \processMPbuffer \stoplinecorrection + +Or how about \type {squeezed}: + +\startbuffer +path p ; p := fullsquare scaled 2cm randomized .5cm ; +drawpath p ; drawpoints p ; +p := (p shifted (5cm,0)) squeezed .5cm ; +drawpath p ; drawpoints p ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] \processMPbuffer \stoplinecorrection + +A \type {punked} path is, like a punked font, a font with less smooth curves (in +our case, only straight lines). + +\startbuffer +path p ; p := fullcircle scaled 2cm randomized .5cm ; +drawpath p ; drawpoints p ; +p := punked (p shifted (5cm,0)) ; +drawpath p ; drawpoints p ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] \processMPbuffer \stoplinecorrection + +A \type {curved} path on the other hand has smooth connections. Where in many +cases a punked path becomes smaller, a curved path will be larger. + +\startbuffer +path p ; p := fullsquare scaled 2cm randomized .5cm ; +drawpath p ; drawpoints p ; +p := curved (p shifted (5cm,0)) ; +drawpath p ; drawpoints p ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] \processMPbuffer \stoplinecorrection + +Probably less usefull (although we use it in one of the \OPENTYPE\ visualizers) +is \type {laddered}: + +\startbuffer +path p ; p := fullcircle scaled 3cm ; +drawpath p ; drawpoints p ; +p := laddered (p shifted (5cm,0)) ; +drawpath p ; drawpoints p ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] \processMPbuffer \stoplinecorrection + +When writing \PPCHTEX\ (that can be used to draw chemical structure formulas) I +needed a parallelizing macro, so here it is: + +\startbuffer +path p ; p := fullcircle scaled 3cm ; +drawpath p ; drawpoints p ; +p := p paralleled 1cm ; +drawpath p ; drawpoints p ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] \processMPbuffer \stoplinecorrection + +If you use a negative argument (like \type {-1cm}) the parallel line will be +drawn at the other side. + +The \type {blownup} operation scales the path but keeps the center in the same +place. + +\startbuffer +path p ; p := fullsquare xyscaled (4cm,1cm) randomized .5cm ; +drawpath p ; drawpoints p ; +p := p blownup .5cm ; +drawpath p ; drawpoints p ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] \processMPbuffer \stoplinecorrection + +The \type {shortened} operation also scales the path but only makes it longer or +shorter. This macro only works on straight paths. + +\startbuffer +path p ; p := (0,0) -- (2cm,3cm) ; +drawpath p ; drawpoints p ; +p := p shortened 1cm ; +drawpath p ; drawpoints p ; +p := p shortened -1cm ; +drawpath p ; drawpoints p ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] \processMPbuffer \stoplinecorrection + +Here are a few more drawing helpers. Even if you don't need them you might at +some point take a look at their definitions to see what happens there. First we +give a square round corners with \type {roundedsquare}: + +\startbuffer +path p ; p := roundedsquare(2cm,4cm,.25cm) ; +drawpath p ; drawpoints p ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] \processMPbuffer \stoplinecorrection + +Next we draw a square|-|like circle (or circle|-|like square) using \type +{tensecircle}: + +\startbuffer +path p ; p := tensecircle(2cm,4cm,.25cm) ; +drawpath p ; drawpoints p ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] \processMPbuffer \stoplinecorrection + +Often I make such helpers in the process of writing larger drawing systems. Take +\type {crossed}: + +\startbuffer +path p ; p := origin crossed 1cm ; +drawpath p ; drawpoints p ; +p := (origin crossed fullcircle scaled 2cm crossed .5cm) shifted (3cm,0) ; +drawpath p ; drawpoints p ; +\stopbuffer + +\typebuffer + +These examples demonstrate that a path is made up out of points (something that +you probably already knew by now). The \METAPOST\ operator \type {of} can be used +to \quote {access} a certain point at a curve. + +\startbuffer +path p ; p := fullsquare xyscaled (3cm,2cm) randomized .5cm ; +drawpath p ; drawpoints p ; drawpointlabels p ; +draw point 2.25 of p withpen pencircle scaled 5mm withcolor .625red ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] \processMPbuffer \stoplinecorrection + +To this we add two more operators: \type {on} and \type {along}. With \type {on} +you get the point at the supplied distance from point~0; with \type {along} you +get the point at the fraction of the length of the path. + +\startbuffer +path p, q, r ; +p := fullsquare xyscaled (2cm,2cm) randomized .5cm ; +q := p shifted (3cm,0) ; r := q shifted (3cm,0) ; +drawpath p ; drawpoints p ; drawpointlabels p ; +drawpath q ; drawpoints q ; drawpointlabels q ; +drawpath r ; drawpoints r ; drawpointlabels r ; +pickup pencircle scaled 5mm ; +draw point 2.25 of p withcolor .625red ; +draw point 2.50cm on q withcolor .625yellow ; +draw point .45 along r withcolor .625white ; +\stopbuffer + +\typebuffer + +Beware: the \type {length} of a path is the number of points minus one. The +shapes below are constructed from 5~points and a length of~4. If you want the +length as dimension, you should use \type {arclength}. + +\startlinecorrection[blank] \processMPbuffer \stoplinecorrection + +We will now play a bit with simple lines. With \type {cutends}, you can (indeed) +cut off the ends of a curve. The specification is a dimension. + +\startbuffer +path p ; p := (0cm,0cm) -- (4cm,1cm) ; +path q ; q := (5cm,0cm){right} .. (9cm,1cm) ; +drawpath p ; drawpoints p ; drawpath q ; drawpoints q ; +p := p cutends .5cm ; q := q cutends .5cm ; +drawpathoptions (withpen pencircle scaled 5pt withcolor .625yellow) ; +drawpointoptions(withpen pencircle scaled 4pt withcolor .625red) ; +drawpath p ; drawpoints p ; drawpath q ; drawpoints q ; +resetdrawoptions ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] \processMPbuffer \stoplinecorrection + +As with more operators, \type {cutends} accepts a numeric or a pair. Watch the +subtle difference between the next and the previous use of \type {cutends}. + +\startbuffer +path p ; p := (0cm,0) .. (4cm,0) .. (8cm,0) .. (4cm,0) .. cycle ; +drawpath p ; drawpoints p ; p := p cutends (2cm,1cm) ; +drawpathoptions (withpen pencircle scaled 5pt withcolor .625yellow) ; +drawpointoptions(withpen pencircle scaled 4pt withcolor .625red) ; +drawpath p ; drawpoints p ; +resetdrawoptions ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] \processMPbuffer \stoplinecorrection + +When \type {stretched} is applied to a path, it is scaled but the starting point +(point~0) keeps its location. The specification is a scale. + +\startbuffer +path p ; p := (0cm,0) .. (3cm,1cm) .. (4cm,0) .. (5cm,1cm) ; +drawpath p ; drawpoints p ; p := p stretched 1.1 ; +drawpathoptions (withpen pencircle scaled 2.5pt withcolor .625yellow) ; +drawpointoptions(withpen pencircle scaled 4.0pt withcolor .625red) ; +drawpath p ; drawpoints p ; resetdrawoptions ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] \processMPbuffer \stoplinecorrection + +We can scale in two directions independently or even in one direction by +providing a zero value. In the next example we apply the stretch two times. + +\startbuffer +path p ; p := (0cm,0) .. (3cm,1cm) .. (4cm,0) .. (5cm,1cm) ; +drawpath p ; drawpoints p ; p := p stretched (.75,1.25) ; +drawpathoptions (withpen pencircle scaled 2.5pt withcolor .625yellow) ; +drawpointoptions(withpen pencircle scaled 4.0pt withcolor .625red) ; +drawpath p ; drawpoints p ; p := p stretched (0,1.5) ; +drawpathoptions (withpen pencircle scaled 4.0pt withcolor .625red) ; +drawpointoptions(withpen pencircle scaled 2.5pt withcolor .625yellow) ; +drawpath p ; drawpoints p ; resetdrawoptions ; +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] \processMPbuffer \stoplinecorrection + +We already met the \type {randomize} operator. This one is the chameleon under +the operators. + +\startbuffer +draw fullsquare xyscaled (4cm,2cm) + randomized .25cm + shifted origin randomized (1cm, 2cm) + withcolor red randomized (.625, .850) + withpen pencircle scaled (5pt randomized 1pt) ; +\stopbuffer + +\typebuffer + +So, \type {randomized} can handle a numeric, pair, path and color, and its +specification can be a numeric, pair or color, depending on what we're dealing +with. + +\startlinecorrection[blank] \processMPbuffer \stoplinecorrection + +In the previous example we also see \type {xyscaled} in action. Opposite to \type +{scaled}, \type {xscaled} and \type {yscaled}, this is not one of \METAPOST\ +build in features. The same is true for the \type {.sized} operators. + +\startbuffer[a] +picture p ; p := image + ( draw fullsquare + xyscaled (300,800) + withpen pencircle scaled 50 + withcolor .625 yellow ; ) ; +draw p xysized (3cm,2cm) shifted (bbwidth(currentpicture)+.5cm,0) ; +draw p xysized 2cm shifted (bbwidth(currentpicture)+.5cm,0) ; +draw p xsized 1cm shifted (bbwidth(currentpicture)+.5cm,0) ; +draw p ysized 2cm shifted (bbwidth(currentpicture)+.5cm,0) ; +\stopbuffer + +\typebuffer[a] + +\startlinecorrection[blank] \processMPbuffer[a] \stoplinecorrection + +Here, the \type {image} macro creates an (actually rather large) picture. The +last four lines actually draw this picture, but at the given dimensions. Watch +how the line width scales accordingly. If you don't want this, you can add the +following line: + +\startbuffer[b] +redraw currentpicture withpen pencircle scaled 2pt ; +draw boundingbox currenpicture withpen pencircle scaled .5mm ; +\stopbuffer + +\typebuffer[b] + +Watch how the boundingbox is not affected: + +\startlinecorrection[blank] \processMPbuffer[a,b] \stoplinecorrection + +In this example we also used \type {bbwidth} (which has a companion macro \type +{bbheight}). You can apply this macro to a path or a picture. + +In fact you don't always need to follow this complex route if you want to simply +redraw a path with another pen or color. + +\startbuffer +draw fullcircle scaled 1cm + withcolor .625red withpen pencircle scaled 1mm ; +draw currentpicture + withcolor .625yellow withpen pencircle scaled 3mm ; +draw boundingbox currentpicture + withpen pencircle scaled .5mm ; +\stopbuffer + +\typebuffer + +This is what you will get from this: + +\startlinecorrection[blank] \processMPbuffer \stoplinecorrection + +If you want to add a background color to a picture you can do that afterwards. +This can be handy when you don't know in advance what size the picture will have. + +\startbuffer +fill fullcircle scaled 1cm withcolor .625red ; +addbackground withcolor .625 yellow ; +\stopbuffer + +\typebuffer + +The background is just a filled rectangle that gets the same size as the current +picture, that is put on top of it. + +\startlinecorrection[blank] \processMPbuffer \stoplinecorrection + +\stopsection + +\startsection[title={Cutting and pasting}] + +\index{paths+cutting} +\index{cutting} + +When enhancing or building a graphic, often parts of already constructed paths +are needed. The \type {subpath}, \type {cutbefore} and \type {cutafter} operators +can be used to split paths in smaller pieces. In order to do so, we must know +where we are on the path that is involved. For this we use points on the path. +Unfortunately we can only use these points when we know where they are located. +In this section we will combine some techniques discussed in previous sections. +We will define a few macros, manipulate some paths and draw curves and points. + +\startbuffer +path p ; p := fullcircle yscaled 3cm xscaled .9TextWidth ; +drawpath p ; drawpoints p withcolor .625red ; drawpointlabels p ; +\stopbuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +This circle is drawn by scaling the predefined path \type {fullcircle}. This path +is constructed using 8~points. As you can see, these points are not distributed +equally along the path. In the following graphic, the second and third point of +the curve are colored red, and point 2.5 is colored yellow. Point~0 is marked in +black. This point is positioned halfway between point~2 and~3. + +\startbuffer +path p ; p := fullcircle scaled 3cm xscaled 2 ; +pickup pencircle scaled 5mm ; autoarrows := true ; +drawarrow p withcolor .625white ; +draw point 0.0 of p ; +draw point 2.0 of p withcolor .625red ; +draw point 2.5 of p withcolor .625yellow ; +draw point 3.0 of p withcolor .625red ; +\stopbuffer + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +It is clear that, unless you know exactly how the path is constructed, other +methods should be available. A specific point on a path is accessed by \typ +{point ... of}, but the next example demonstrates two more alternatives. + +\startbuffer +path p ; p := fullcircle scaled 3cm xscaled 2 ; +pickup pencircle scaled 5mm ; +draw p withcolor .625white ; +draw point 3 of p withcolor .625red ; +draw point .6 along p withcolor .625yellow ; +draw point 3cm on p ; +\stopbuffer + +\typebuffer + +So, in addition to \type {on} to specify a point by number (in \METAPOST\ +terminology called time), we have \type {along} to specify a point as fraction of +the path, and \type {on} to specify the position in a dimension. + +\startlinecorrection[blank] +\processMPbuffer +\stoplinecorrection + +The \type {on} and \type {along} operators are macros and can be defined as: + +\starttyping +primarydef len on pat = + (arctime len of pat) of pat +enddef ; + +primarydef pct along pat = + (arctime (pct * (arclength pat)) of pat) of pat +enddef ; +\stoptyping + +These macros introduce two new primitives, \type {arctime} and \type {arclength}. +While \type {arctime} returns a number denoting the time of the point on the +path, \type {arclength} returns a dimension. + +\quotation {When mathematicians draw parametric curves, they frequently need to +indicate the direction of motion. I often have need of a little macro that will +put an arrow of requested length, anchored at a point on the curve, and bending +with the curve in the direction of motion.} + +When David Arnold asked me how this could be achieved, the fact that a length was +requested meant that the solution should be sought in using the primitives and +macros we introduced a few paragraphs before. Say that we want to call for such +an arrow as follows. + +\startbuffer[a] +path p ; p := fullcircle scaled 3cm ; +pair q ; q := point .4 along p ; +pickup pencircle scaled 2mm ; +draw p withcolor .625white ; +drawarrow somearrow(p,q,2cm) withcolor .625red ; +draw q withcolor .625yellow ; +\stopbuffer + +\typebuffer[a] + +Because we want to follow the path, we need to construct the arrow from this +path. Therefore, we first reduce the path by cutting off the part before the +given point. Next we cut off the end of the resulting path so that we keep a +slice that has the length that was asked for. Since we can only cut at points, we +determine this point using the \type {arctime} primitive. + +\startbuffer[b] +vardef somearrow (expr pat, loc, len) = + save p ; path p ; p := pat cutbefore loc ; + (p cutafter point (arctime len of p) of p) +enddef ; +\stopbuffer + +\typebuffer[b] + +By using a \type {vardef} we hide the intermediate assignments. Such \type +{vardef} is automatically surrounded by \type {begingroup} and \type {endgroup}, +so the \type {save} is local to this macro. When processed, this code produces +the following graphic: + +\startbuffer[c] +autoarrows := true ; +\stopbuffer + +\startlinecorrection[blank] +\processMPbuffer[c,b,a] +\stoplinecorrection + +This graphic shows that we need a bit more control over the exact position of the +arrow. It would be nice if we could start the arrow at the point, or end there, +or center the arrow around the point. Therefore, the real implementation is a bit +more advanced. + +\startbuffer +vardef pointarrow (expr pat, loc, len, off) = + save l, r, s, t ; path l, r ; numeric s ; pair t ; + t := if pair loc : loc else : point loc along pat fi ; + s := len/2 - off ; if s<=0 : s := 0 elseif s>len : s := len fi ; + r := pat cutbefore t ; + r := (r cutafter point (arctime s of r) of r) ; + s := len/2 + off ; if s<=0 : s := 0 elseif s>len : s := len fi ; + l := reverse (pat cutafter t) ; + l := (reverse (l cutafter point (arctime s of l) of l)) ; + (l..r) +enddef ; +\stopbuffer + +\typebuffer + +This code fragment also demonstrates how we can treat the \type {loc} argument as +pair (coordinates) or fraction of the path. We calculate the piece of path before +and after the given point separately and paste them afterwards as \type {(l..r)}. +By adding braces we can manipulate the path in expressions without the danger of +handling \type {r} alone. + +We can now implement left, center and right arrows by providing this macro the +right parameters. The offset (the fourth parameter), is responsible for a +backward displacement. This may seem strange, but negative values would be even +more confusing. + +\startbuffer +def rightarrow (expr p,t,l) = pointarrow(p,t,l,-l) enddef ; +def leftarrow (expr p,t,l) = pointarrow(p,t,l,+l) enddef ; +def centerarrow(expr p,t,l) = pointarrow(p,t,l, 0) enddef ; +\stopbuffer + +\typebuffer + +We can now apply this macro as follows: + +\startbuffer[a] +path p ; p := fullcircle scaled 3cm ; +pickup pencircle scaled 2mm ; +draw p withcolor .625white ; +drawarrow leftarrow (p, .4 ,2cm) withcolor .625red ; +drawarrow centerarrow(p,point 5 of p,2cm) withcolor .625yellow ; +draw point .4 along p withcolor .625yellow ; +draw point 5 of p withcolor .625red ; +\stopbuffer + +\typebuffer[a] + +\startlinecorrection[blank] +\processMPbuffer[a] +\stoplinecorrection + +Watch how we can pass a point (\typ {point 5 of p}) as well as a fraction (\type +{.4}). The following graphic demonstrates a few more alternatives. + +\startbuffer[a] +pickup pencircle scaled 2mm; autoarrows := true ; + +path p ; p := fullcircle yscaled 3cm xscaled .9TextWidth ; + +draw p withcolor .5white; + +for i=1, 2, 3 : + drawdot point i of p withpen pencircle scaled 5mm withcolor .625white ; +endfor ; +for i=.60, .75, .90 : + drawdot point i along p withpen pencircle scaled 5mm withcolor .625white ; +endfor ; +\stopbuffer + +\startbuffer[b] +drawarrow leftarrow (p,point 1 of p,2cm) withcolor red ; +drawarrow centerarrow (p,point 2 of p,2cm) withcolor blue ; +drawarrow rightarrow (p,point 3 of p,2cm) withcolor green ; +drawarrow pointarrow (p,.60,4cm,+.5cm) withcolor yellow ; +drawarrow pointarrow (p,.75,3cm,-.5cm) withcolor cyan ; +drawarrow centerarrow (p,.90,3cm) withcolor magenta ; +\stopbuffer + +\startlinecorrection[blank] +\processMPbuffer[a,b] +\stoplinecorrection + +The arrows are drawn using the previously defined macros. Watch the positive and +negative offsets in call to \type {pointarrow}. + +\typebuffer[b] + +\stopsection + +\startsection[title={Current picture}] + +\index {pictures} + +When you draw paths, texts and|/|or pictures they are added to the so called +current picture. You can manipulate this current picture as is demonstrated in +this manual. Let's show a few current picture related tricks. + +\startbuffer + draw fullcircle scaled 1cm withpen pencircle scaled 1mm withcolor .625red ; +\stopbuffer + +\typebuffer \startlinecorrection[blank] \processMPbuffer \stoplinecorrection + +We can manipulate the picture as a whole: + +\startbuffer + draw fullcircle scaled 1cm withpen pencircle scaled 1mm withcolor .625red ; + currentpicture := currentpicture slanted .5 ; +\stopbuffer + +\typebuffer \startlinecorrection[blank] \processMPbuffer \stoplinecorrection + +Sometimes it's handy to temporarily set aside the current picture. + +\startbuffer + draw fullcircle scaled 1cm withpen pencircle scaled 1mm withcolor .625red ; + currentpicture := currentpicture slanted .5 ; + pushcurrentpicture ; + draw fullcircle scaled 1cm withpen pencircle scaled 1mm withcolor .625yellow ; + currentpicture := currentpicture slanted -.5 ; + popcurrentpicture ; +\stopbuffer + +\typebuffer \startlinecorrection[blank] \processMPbuffer \stoplinecorrection + +These are \METAFUN\ commands but \METAPOST\ itself comes with a variant, \type +{image}, and you explicitly have to draw this picture (or otherwise add it to the +currentpicture). + +\startbuffer + draw fullcircle scaled 1cm withpen pencircle scaled 1mm withcolor .625red ; + currentpicture := currentpicture slanted .5 ; + draw image ( + draw fullcircle scaled 1cm + withpen pencircle scaled 1mm withcolor .625yellow ; + currentpicture := currentpicture slanted -.5 ; + ) ; +\stopbuffer + +\typebuffer \startlinecorrection[blank] \processMPbuffer \stoplinecorrection + +Each graphic starts fresh with an empty current picture. In \METAFUN\ we make +sure that we also reset some otherwise global variables, like color, pen and some +line properties. + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/metafun/metafun.tex b/doc/context/sources/general/manuals/metafun/metafun.tex new file mode 100644 index 000000000..dc90bb611 --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/metafun.tex @@ -0,0 +1,108 @@ +% language=uk macros=mkvi + +% 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. +% +% comment : This manual was originally written for MkII and as a consequence many examples +% are coded in a bit different way than we would nowadays do in MkIV. But, as we +% try to be downward compatible, it doesn't hurt. +% +% comment : I also use this manual for benchmarking ConTeXt MkIV. On my current machine (a +% 2013 dell i7 laptop) one run takes some 18.1 seconds for LuaTeX and around 14.2 +% seconds for LuajitTeX which is quite okay given the amount of graphics (428 +% pages). +% +% comment : This is one of the manuals that can be ordered at http://www.h2o-books.com and +% it's actually meant to be read on paper. + +\enabledirectives[hyphenator.optimize] +\enabledirectives[hyphenator.flatten] +% \setuphyphenation[method=traditional] + +% \enabletrackers[*defin*] + +% \enablemode[screen] +\enablemode[print] +% \enablemode[book] + +% \usemodule[luacalls] + +% todo: check startintro .. stopintro each chapter + +% \showframe + +\startproduct metafun + +\environment metafun-environment + +\startnotmode[screen] + \component metafun-titlepage-paper + \component metafun-colofon-paper +\stopnotmode + +\startmode[screen] + \environment metafun-environment-screen + \component metafun-titlepage-screen +\stopmode + +\startfrontmatter + \component metafun-introduction + \component metafun-contents + \component metafun-conventions +\stopfrontmatter + +\startbodymatter + \component metafun-welcome + \component metafun-basics + \component metafun-embedding + \component metafun-layout + \component metafun-positioning + \component metafun-backgrounds + \component metafun-gadgets + \component metafun-effects + \component metafun-functions + \component metafun-text + \component metafun-debugging + \component metafun-styles + \component metafun-examples + \component metafun-macros + \component metafun-lua + %component metafun-graphics + \component metafun-sneaky +\stopbodymatter + +\startappendices + % \component metafun-programs + \component metafun-syntax + \component metafun-document + \component metafun-reference + % \component metafun-literature +\stopappendices + +\startbackmatter + \component metafun-index +\stopbackmatter + +\startmode[screen] + \component metafun-colofon-screen +\stopmode + +\startnotmode[screen] + \component metafun-backpage +\stopnotmode + +\stopproduct diff --git a/doc/context/sources/general/manuals/metafun/mfun-700.tex b/doc/context/sources/general/manuals/metafun/mfun-700.tex new file mode 100644 index 000000000..e393a34f3 --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/mfun-700.tex @@ -0,0 +1,17 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\starttext + +\TitlePage + {A Few Nice Quotes\\ + A Simple Style Demo\\ + Hans Hagen, August 2000} + +\Topic {Douglas R. Hofstadter} \input douglas \page +\Topic {Donald E. Knuth} \input knuth \page +\Topic {Edward R. Tufte} \input tufte \page +\Topic {Hermann Zapf} \input zapf \page + +\stoptext diff --git a/doc/context/sources/general/manuals/metafun/mfun-771.tex b/doc/context/sources/general/manuals/metafun/mfun-771.tex new file mode 100644 index 000000000..460c16f2a --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/mfun-771.tex @@ -0,0 +1,9 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\usemodule[present-organic] + +\setupMPvariables[page][alternative=1] + +\input mfun-700 diff --git a/doc/context/sources/general/manuals/metafun/mfun-772.tex b/doc/context/sources/general/manuals/metafun/mfun-772.tex new file mode 100644 index 000000000..99dec1551 --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/mfun-772.tex @@ -0,0 +1,9 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\usemodule[present-organic] + +\setupMPvariables[page][alternative=2] + +\input mfun-700 diff --git a/doc/context/sources/general/manuals/metafun/mfun-773.tex b/doc/context/sources/general/manuals/metafun/mfun-773.tex new file mode 100644 index 000000000..daefcfe66 --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/mfun-773.tex @@ -0,0 +1,9 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\usemodule[present-organic] + +\setupMPvariables[page][alternative=3] + +\input mfun-700 diff --git a/doc/context/sources/general/manuals/metafun/mfun-774.tex b/doc/context/sources/general/manuals/metafun/mfun-774.tex new file mode 100644 index 000000000..725d1199b --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/mfun-774.tex @@ -0,0 +1,103 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\usemodule[present-organic] + +\setupMPvariables[page][alternative=1] + +\startuseMPgraphic{page} + + \includeMPgraphic{rightsuperbutton} + + StartPage ; + + path p, q ; + + p := Field[Text][Text] enlarged 36pt superellipsed .90 ; + + fill Page + withcolor \MPcolor{yellow} ; + fill p + withcolor \MPcolor{white} ; + draw p + dashed dashpattern (on 9pt off 9pt) + withpen pencircle scaled 3pt + withcolor \MPcolor{red} ; + + p := Field[Text][Text] enlarged 48pt superellipsed .90 ; + + draw p + dashed dashpattern (on 9pt off 9pt) + withpen pencircle scaled 1.5pt ; + + def right_menu_button (expr nn, rr, pp, xx, yy, ww, hh, dd) = + if (pp>0) and (rr>0) : + q := rightsuperbutton(p,xx,yy,RightEdgeWidth,hh) ; + fill q + withcolor \MPcolor{white} ; + draw ptop + withpen pencircle scaled 1.5pt ; + draw pbot + withpen pencircle scaled 1.5pt ; + draw q + dashed dashpattern (on 9pt off 9pt) + withpen pencircle scaled 3pt + withcolor if rr=2 : \MPcolor{gray} else : \MPcolor{red} fi ; + fi ; + enddef ; + + \MPmenubuttons{right} + + StopPage ; +\stopuseMPgraphic + +\startuseMPgraphic{rightsuperbutton} + +vardef rightsuperbutton (expr pat, xpos, ypos, wid, hei) = + + save p, t, b, edge, shift, width, height ; + path p, ptop, pbot ; pair t, b ; numeric edge, shift, width, height ; + + edge := xpos + wid ; shift := ypos + hei ; + + p := rightpath pat ; + +draw p withpen pencircle scaled 1.5pt ; + + ptop := ((-infinity,shift)--(edge,shift)) ; + pbot := ((-infinity,shift-hei)--(edge,shift-hei)) ; + + t := p intersectionpoint ptop ; + b := p intersectionpoint pbot ; + + label.llft("t",t) ; + label.ulft("b",b) ; + + p := subpath(0,xpart (p intersectiontimes ptop)) of p ; + p := subpath(xpart (p intersectiontimes pbot),length(p)) of p ; + + (p -- t -- point 1 of ptop & + point 1 of ptop -- point 1 of pbot & + point 1 of pbot -- b + -- cycle) + +enddef ; + +\stopuseMPgraphic + + + +\starttext + +\TitlePage + {A Few Nice Quotes\\ + A Simple Style Demo\\ + Hans Hagen, August 2000} + +\Topic {Douglas R. Hofstadter} \input douglas \page +\Topic {Donald E. Knuth} \input knuth \page +\Topic {Edward R. Tufte} \input tufte \page +\Topic {Hermann Zapf} \input zapf \page + +\stoptext diff --git a/doc/context/sources/general/manuals/metafun/mfun-775.tex b/doc/context/sources/general/manuals/metafun/mfun-775.tex new file mode 100644 index 000000000..e9d2b85a7 --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/mfun-775.tex @@ -0,0 +1,9 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\usemodule[present-organic] + +\setupMPvariables[page][alternative=11] + +\input mfun-700 diff --git a/doc/context/sources/general/manuals/metafun/mfun-776.tex b/doc/context/sources/general/manuals/metafun/mfun-776.tex new file mode 100644 index 000000000..82b5c18dd --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/mfun-776.tex @@ -0,0 +1,9 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\usemodule[present-organic] + +\setupMPvariables[page][alternative=12] + +\input mfun-700 diff --git a/doc/context/sources/general/manuals/metafun/mfun-800.tex b/doc/context/sources/general/manuals/metafun/mfun-800.tex new file mode 100644 index 000000000..aa0c1260f --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/mfun-800.tex @@ -0,0 +1,27 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\setupMPpage + [offset=1pt, + background=color, + backgroundcolor=gray] + +\definecolor [gray] [s=.625] +\definecolor [red] [r=.625] +\definecolor [yellow] [r=.625,g=.625] + +\startuseMPgraphic{test} + fill fullsquare rotated 45 scaled 4cm + withcolor \MPcolor{yellow} ; +\stopuseMPgraphic + +\starttext + +\startMPpage + \includeMPgraphic{test} + fill fullcircle scaled 3cm + withcolor \MPcolor{red} ; +\stopMPpage + +\stoptext diff --git a/doc/context/sources/general/manuals/metafun/mfun-900.tex b/doc/context/sources/general/manuals/metafun/mfun-900.tex new file mode 100644 index 000000000..c295ec908 --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/mfun-900.tex @@ -0,0 +1,48 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\startcomponent mfun-900 + +\environment metafun-environment + +% Page 1 + +\getbuffer[pagetext] + +% Page 2/3 + +\getbuffer[back-0,back-1,pagetext] +\getbuffer[back-0,back-1,pagetext] + +\setupbackgrounds[page][background=] + +% Page 4/5 + +\getbuffer[back-0,back-2,pagetext] +\getbuffer[back-0,back-2,pagetext] + +\setupbackgrounds[page][background=] + +% Page 6/7 + +\getbuffer[back-0,back-3,pagetext] +\getbuffer[back-0,back-3,pagetext] + +\setupbackgrounds[page][background=] + +% Page 8/9 + +\getbuffer[back-0,back-4,pagetext] +\getbuffer[back-0,back-4,pagetext] + +\setupbackgrounds[page][background=] + +% Page 10/11 + +\getbuffer[back-0,back-5,pagetext] +\getbuffer[back-0,back-5,pagetext] + +\setupbackgrounds[page][background=] + +\stopcomponent diff --git a/doc/context/sources/general/manuals/metafun/mfun-901.tex b/doc/context/sources/general/manuals/metafun/mfun-901.tex new file mode 100644 index 000000000..23adf77b4 --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/mfun-901.tex @@ -0,0 +1,11 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\startcomponent mfun-901 + +\environment metafun-environment + +\getbuffer[gridpage] + +\stopcomponent diff --git a/doc/context/sources/general/manuals/metafun/mfun-902.tex b/doc/context/sources/general/manuals/metafun/mfun-902.tex new file mode 100644 index 000000000..7c4fed73e --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/mfun-902.tex @@ -0,0 +1,11 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\startcomponent mfun-902 + +\environment metafun-environment + +\getbuffer[handwrit] + +\stopcomponent diff --git a/doc/context/sources/general/manuals/metafun/mfun-mrun-demo.mp b/doc/context/sources/general/manuals/metafun/mfun-mrun-demo.mp new file mode 100644 index 000000000..c6589beb5 --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/mfun-mrun-demo.mp @@ -0,0 +1,212 @@ +%D Downloading + +beginfig (1) ; + + path p, q ; + + p := (0,110)..(50,110) shifted (0,-15)..(100,110)-- + (50,50) shifted (10,0) ..(50,50) shifted (0,2.5).. + (50,50) shifted(-10,0)--cycle ; + q := (5,0)--(95,0)--(95,30)..(50,0) shifted (0,10)..(5,30)--cycle ; + + pickup pencircle scaled 15 ; + drawdot (80,100) withcolor .6red ; + drawdot (65,95) withcolor .6red ; + drawdot (50,95) withcolor .6red ; + drawdot (35,95) withcolor .6red ; + + drawdot (50,60) withcolor .6red ; + drawdot (50,35) withcolor .6red ; + drawdot (50,10) withcolor .6red ; + drawdot (70,10) withcolor .6red ; + drawdot (32.5,10) withcolor .6red ; + + pickup pencircle scaled 5 ; + fill p withcolor .6green ; draw p withcolor .4green ; + fill q withcolor .6green ; draw q withcolor .4green ; + + bboxmargin := 2.5 ; p := bbox currentpicture ; + picture s ; s := currentpicture ; currentpicture := nullpicture ; + + pickup pencircle scaled 2.5 ; + fill p withcolor .4blue ; + addto currentpicture also s ; + +endfig ; + +%D WWW Links + +beginfig (2) ; + + boolean angles [], lengths[], colors [][][] ; + numeric a, l, r, g, b, n ; + path p ; + color c ; + + draw fullsquare scaled 150 withpen pencircle scaled 1 withcolor .5white ; + + n := 0 ; + forever : + a := 6 * round(uniformdeviate 60) ; + l := 40 + round(uniformdeviate 60) ; + r := 2 + round(uniformdeviate 6) ; + g := 2 + round(uniformdeviate 6) ; + b := 2 + round(uniformdeviate 6) ; + if (a>0) and not known angles [a] and not known lengths[l] and not known colors [r][g][b] : + n := n + 1 ; + angles [a] := true ; + lengths[l] := true ; + colors [r][g][b] := true ; + p := (origin--origin shifted (0,.5l)) rotatedaround(origin,a) ; + draw p withpen pencircle scaled 2 withcolor (r/10,g/10,b/10) ; + drawdot point 1 of p withpen pencircle scaled 4 withcolor (r/10,g/10,b/10) ; + p := (origin shifted (0,.5l+8)--origin shifted(0,100)) rotatedaround(origin,a) ; + draw p withpen pencircle scaled 2 withcolor (r/10,g/10,b/10) ; + drawdot point 0 of p withpen pencircle scaled 4 withcolor (r/10,g/10,b/10) ; + fi ; + exitif n >= 60 ; + endfor ; + + drawdot + origin + withpen pencircle scaled 10 + withcolor white ; + + fill + ((fullcircle scaled 130) peepholed (fullsquare scaled 150)) + withcolor (1,1,1)-(1,.62,.06); + + clip currentpicture to fullsquare scaled 130 ; + +endfig ; + +%D Mirrors + +beginfig(3) + + path a, b, p, q ; + pair s, t, u, v ; + color c ; + numeric h, w, r ; + + pickup pencircle scaled 10 ; + + h := 120 ; + w := 80 ; + r := 30 ; + + a := (0,0)..(0,.5h) shifted (-r,0)..(0,h) ; + b := (w,0)..(w,.5h) shifted ( r,0)..(w,h) ; + + draw a withcolor .4white; + draw b withcolor .4white; + + def moved (expr i) = + ((i) - 10 + uniformdeviate 20) + enddef ; + + for i=5 step 10 until h-5 : + s := (point (length(a)*(i/h)) of a) ; + t := (point (length(b)*(1-i/h)) of b) ; + u := (s--t) intersectionpoint ((.25w,0)--(.25w,h)) ; + v := (s--t) intersectionpoint ((.75w,0)--(.75w,h)) ; + p := s..(xpart u,moved(ypart u))..(xpart v,moved(ypart v))..t ; + c := (0,.4+uniformdeviate.55,0) ; + l := length(p) ; + l := .25l+uniformdeviate.5l ; + q := p cutafter point l of p ; + pickup pencircle scaled 2.5 ; + draw p withcolor c ; + pickup pencircle scaled 5 ; + drawdot point 0 of p withcolor c ; + drawdot point infinity of p withcolor c ; + endfor ; + + picture s ; s := currentpicture ; currentpicture := nullpicture ; + + bboxmargin := 2.5 ; fill bbox s withcolor .85white ; + + addto currentpicture also s ; + +endfig; + +%D Team + +def dpuppet (expr v, w) = + v - .5w + uniformdeviate w +enddef ; + +def somepuppet (expr s, r) = + picture p ; p := currentpicture ; currentpicture := nullpicture ; + draw ((-10,0)--(10,0)) ; + for i:=-10 step 5 until 10 : + draw ((i,0)--(dpuppet(i,2),-10)) ; + endfor ; + currentpicture := currentpicture rotated r shifted s ; + addto currentpicture also p ; +enddef ; + +def puppet (expr loc, sca, col) = + picture s ; s := currentpicture ; currentpicture := nullpicture ; + + pair a ; a := (dpuppet( 20,5),dpuppet( 0, 5)) ; + pair b ; b := (dpuppet(-20,5),dpuppet( 0, 5)) ; + pair c ; c := (dpuppet( 30,5),dpuppet(60,10)) ; + pair d ; d := (dpuppet(-30,5),dpuppet(60,10)) ; + pair e ; e := (dpuppet( 0,5),dpuppet(30,10)) ; + pair f ; f := (dpuppet( 0,5),dpuppet(50,10)) ; + pair g ; g := (dpuppet( 0,5),dpuppet(65,10)) ; + + pair f ; f := (.6+uniformdeviate.1)[e,g] ; + + drawoptions (withcolor col) ; + + somepuppet(a,dpuppet( 20,5)) ; + somepuppet(b,dpuppet( -20,5)) ; + somepuppet(c,dpuppet( 120,5)) ; + somepuppet(d,dpuppet(-120,5)) ; + + draw a -- e ; + draw b -- e ; + draw c -- f ; + draw d -- f ; + draw e -- g ; + draw fullcircle scaled 25 shifted (g shifted (0,12.5)); + + drawoptions () ; + + currentpicture := currentpicture scaled sca shifted loc ; + addto currentpicture also s ; +enddef ; + +beginfig (4) ; + + pickup pencircle scaled 0 ; + + color col ; col := (.4,.8,.6) ; + + puppet((-20, 0) ,.20, 0.700col) ; + puppet(( 10,10) ,.30, 0.750col) ; + puppet(( 30,20) ,.40, 0.800col) ; + puppet((-20,30) ,.35, 0.850col) ; + puppet(( 20,60) ,.20, 0.900col) ; + puppet(( -5,65) ,.25, 0.950col) ; + + picture s ; s := currentpicture ; currentpicture := nullpicture ; + + bboxmargin := 15 ; fill bbox s withcolor .8(1,1,0) ; + + addto currentpicture also s withpen pencircle scaled .8 ; + + path b ; bboxmargin := -10 ; b := bbox currentpicture ; + numeric len ; len := length(b) ; + numeric stp ; stp := 20 ; + drawoptions(withpen pencircle scaled .8 withcolor .7red) ; + for i=len/8stp step len/4stp until len+len/8stp : + pair ii ; ii := point (dpuppet(i,len/20stp)) of b ; + pair dd ; dd := (direction i of b) rotated (dpuppet(-90,10)) ; + draw ii shifted -.1dd withpen pencircle scaled 1.2 ; + draw ii--(ii shifted .25dd) ; + endfor ; + +endfig ; diff --git a/doc/context/sources/general/manuals/metafun/mycow.mp b/doc/context/sources/general/manuals/metafun/mycow.mp new file mode 100644 index 000000000..24c3e0f7d --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/mycow.mp @@ -0,0 +1,299 @@ +% 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 +pstoedit: version 3.18 / DLL interface 106 (build May 1 2000) : Copyright (C) 1993 - 2000 Wolfgang Glunz +Interpreter finished. Return status 0 diff --git a/doc/context/sources/general/manuals/metafun/mycow.pdf b/doc/context/sources/general/manuals/metafun/mycow.pdf Binary files differnew file mode 100644 index 000000000..9cc8fb0b4 --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/mycow.pdf diff --git a/doc/context/sources/general/manuals/metafun/somecow.pdf b/doc/context/sources/general/manuals/metafun/somecow.pdf Binary files differnew file mode 100644 index 000000000..1a43087fd --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/somecow.pdf diff --git a/doc/context/sources/general/manuals/nodes/nodes-sun-pia-03149.jpg b/doc/context/sources/general/manuals/nodes/nodes-sun-pia-03149.jpg Binary files differnew file mode 100644 index 000000000..4de706984 --- /dev/null +++ b/doc/context/sources/general/manuals/nodes/nodes-sun-pia-03149.jpg diff --git a/doc/context/sources/general/manuals/nodes/nodes-sun-pia-03150.jpg b/doc/context/sources/general/manuals/nodes/nodes-sun-pia-03150.jpg Binary files differnew file mode 100644 index 000000000..aa3849605 --- /dev/null +++ b/doc/context/sources/general/manuals/nodes/nodes-sun-pia-03150.jpg diff --git a/doc/context/sources/general/manuals/nodes/nodes.tex b/doc/context/sources/general/manuals/nodes/nodes.tex new file mode 100644 index 000000000..e9857f37e --- /dev/null +++ b/doc/context/sources/general/manuals/nodes/nodes.tex @@ -0,0 +1,1706 @@ +% interface=english modes=screen + +% author : Alan Braslau +% copyright : 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 : A prototype of the nodes module was presented at the ConTeXt 2016 user meeting +% and the first release was presented at the 2017 meeting. The module is part of +% the MetaFun code modules. +% +% comment : This manual orginates in an article by Alan so anything wrong in here is Hans +% fault as he converted it. +% +% comment : It is also being published as an article in TugBoat. +% +% comment : The cover images are from the NASA website. + + +% Alan : There is no need for % before \startfootnote .. the less such crap the better +% (as it might give disappearing content if one wraps). +% +% Alan : ḻṯ What is this? An editor glitch? +% +% Alan : $≠$ -> just use ≠ (also, soon the gyre fonts will have more symbols in text +% that match text. +% +% Alan : You can use \typ {x = 0} for something that breaks accross lines. + +%\enabletrackers[metapost.showlog] + +\definemeasure [layout:margin] [\paperheight/20] + +\setuplayout + [topspace=\measure{layout:margin}, + bottomspace=\measure{layout:margin}, + backspace=\measure{layout:margin}, + header=0pt, + footer=\measure{layout:margin}, + width=middle, + height=middle] + +\setupbodyfont + [dejavu,11pt] + +\setupwhitespace + [big] + +\setuphead + [chapter] + [style=\bfc, + interaction=all] + +\setuppagenumbering + [alternative=doublesided, + location=] + +\setupfootertexts + [\documentvariable{title}][\pagenumber] + [\pagenumber][\documentvariable{title}] + +\setuphead + [section] + [style=\bfb] + +\setuphead + [subsection] + [style=\bfa] + +\setuphead + [subsubsection] + [style=\bf, + after=] + +\setuplist + [interaction=all] + +\setupalign + [verytolerant,stretch] + +% \definesymbol [1] [$\cdot$] + +% Dot rather than bullet ... Alan hates bullets! Hans hates too small dots. + +\setupitemize + [symbol=2] % dash rather than bullet, I hate bullets! + +\setupnote + [footnote] + [next={ }, + split=verystrict, + scope=page] + +\setupinteraction + [state=start, + option=bookmark, + color=darkmagenta, + contrastcolor=darkmagenta] + +\setupinteractionscreen + [option=bookmark] + +\placebookmarks + [title,subject] + [title,subject] + +\enabledirectives + [references.bookmarks.preroll] + +\kindofpagetextareas\plusone % partial page. HH: low level, no high level switch (yet) + +\definetextbackground + [aside] + [location=paragraph, + frame=off, + leftoffset=1ex, + rightoffset=1ex, + topoffset=1ex, + bottomoffset=1ex, + background=color, + backgroundcolor=lightgray] + +\definedescription + [description] + [location=hanging, + width=broad, + before={\blank}, + after={\blank}] + +\defineparagraphs + [two] + [n=2, + offset=1ex, + background=color, + backgroundcolor=gray] + +\defineframed + [node] + [offset=1pt, + foregroundstyle=\tfa] + +\defineframed + [nodeGreen] + [node] + [foregroundcolor=darkgreen, + foregroundstyle=italic] + +\defineframed + [nodeSmall] + [node] + [foregroundstyle=\tfx] + +\startbuffer [bib] + @ARTICLE{Krebs1946, + author = {Krebs, H. A.}, + title = {Cyclic processes in living matter}, + journal = {Enzymologia}, + year = {1946}, + volume = {12}, + pages = {88--100} + } + + @ARTICLE{Bethe1939a, + author = {Bethe, H. A.}, + title = {Energy Production in Stars}, + journal = {Phys. Rev.}, + year = {1939}, + volume = {55}, + pages = {103–103}, + month = {Jan}, + doi = {10.1103/PhysRev.55.103}, + issue = {1}, + publisher = {American Physical Society}, + XXurl = {http://link.aps.org/doi/10.1103/PhysRev.55.103} + } + + @ARTICLE{Bethe1939b, + author = {Bethe, H. A.}, + title = {Energy Production in Stars}, + journal = {Phys. Rev.}, + year = {1939}, + volume = {55}, + pages = {434–456}, + month = {Mar}, + doi = {10.1103/PhysRev.55.434}, + issue = {5}, + publisher = {American Physical Society}, + XXurl = {http://link.aps.org/doi/10.1103/PhysRev.55.434} + } + + @BOOK{Lawvere2009, + author = {Lawvere, F. William and Schanuel, Stephen H.}, + title = {Conceptual Mathematics} + subtitle = {A first introduction to categories}, + edition = {2\high{nd}}, + publisher = {Cambridge University Press}, + address = {Cambridge, UK}, + year = {2009} + } +\stopbuffer + +\usebtxdefinitions [apa] +\setupbtxrendering [apa] [pagestate=start] % index cite pages in bibliography + +\usebtxdataset [bib.buffer] + +% Say, MP math arrows rather than font arrows: + +\useMPlibrary[mat] + +\definemathstackers + [mp] + [alternative=mp] + +\definemathextensible [mp] [leftarrow] ["2190] +\definemathextensible [mp] [rightarrow] ["2192] +\definemathextensible [mp] [leftrightarrow] ["2194] +\definemathextensible [mp] [longleftrightarrow] ["27F7] +\definemathextensible [mp] [rightoverleftarrow] ["21C4] + +\startMPinitializations + ahlength := EmWidth ; + ahangle := 30 ; + ahvariant := 1 ; % dimpled curved + ahdimple := 4/5 ; + + node_loopback_yscale := .7 ; +\stopMPinitializations + +% Only here do we use the special nodes:: instance + +\defineframed + [mynode] + [node] + [offset=1pt, + foregroundcolor=white] + +\startreusableMPgraphic{nodes::krebs} + + % The Bethe cycle for energy production in stars (1939), following + % Krebs (1946) + + save p ; path p[] ; + p1 := (for i=0 step 60 until 300: dir(90-i).. endfor cycle) scaled 2.75cm ; + p0 := p1 scaled .5 ; + p2 := p1 scaled 1.5 ; + + draw node(p1,0,"\mynode{\chemical{^{12}C}}") ; + draw node(p1,1,"\mynode{\chemical{^{13}N}}") ; + draw node(p1,2,"\mynode{\chemical{^{13}C}}") ; + draw node(p1,3,"\mynode{\chemical{^{14}N}}") ; + draw node(p1,4,"\mynode{\chemical{^{15}O}}") ; + draw node(p1,5,"\mynode{\chemical{^{15}N}}") ; + + drawarrow fromtopaths.urt (true,p1,0,p1,1,"\mynode{a}") withcolor white ; + drawarrow fromtopaths.rt (true,p1,1,p1,2,"\mynode{b}") withcolor white ; + drawarrow fromtopaths.lrt (true,p1,2,p1,3,"\mynode{c}") withcolor white ; + drawarrow fromtopaths.llft(true,p1,3,p1,4,"\mynode{d}") withcolor white ; + drawarrow fromtopaths.lft (true,p1,4,p1,5,"\mynode{e}") withcolor white ; + drawarrow fromtopaths.ulft(true,p1,5,p1,6,"\mynode{f}") withcolor white ; + + draw node(p0,0,"\mynode{\chemical{^1H}}") ; + draw node(p0,2,"\mynode{\chemical{^1H}}") ; + draw node(p0,3,"\mynode{\chemical{^1H}}") ; + draw node(p0,5,"\mynode{\chemical{^1H}}") ; + + drawarrow fromtopaths(3/10,p0,0,p1,0.5) withcolor white ; + drawarrow fromtopaths(3/10,p0,2,p1,2.5) withcolor white ; + drawarrow fromtopaths(3/10,p0,3,p1,3.5) withcolor white ; + drawarrow fromtopaths(3/10,p0,5,p1,5.5) withcolor white ; + + draw node (p2,0,"\mynode{\chemical{^4He}}") ; + draw node (p2,1,"\mynode{$γ$}") ; + draw node.lrt (p2,2,"\mynode{$\mathrm{e}^+ + ν_\mathrm{e}$}") ; + draw node (p2,3,"\mynode{$γ$}") ; + draw node (p2,4,"\mynode{$γ$}") ; + draw node.ulft(p2,5,"\mynode{$\mathrm{e}^+ + ν_\mathrm{e}$}") ; + + drawarrow fromtopaths(-1/10,p1,0.5,p2,1) withcolor white ; + drawarrow fromtopaths(-1/10,p1,1.5,p2,2) withcolor white ; + drawarrow fromtopaths(-1/10,p1,2.5,p2,3) withcolor white ; + drawarrow fromtopaths(-1/10,p1,3.5,p2,4) withcolor white ; + drawarrow fromtopaths(-1/10,p1,4.5,p2,5) withcolor white ; + drawarrow fromtopaths(-1/10,p1,5.5,p2,0) withcolor white ; + +\stopreusableMPgraphic + +\startuseMPgraphic{CoverPage} + + StartPage ; + + % Alan wanted a sun in the background combined somehow with the energy + % harvesting molecule so here we go. The images that are used come from + % the NASA website and I used them as screen saver for a while. The + % version that I generate uses a variant from the one on the user's + % machine. + + draw textext("\externalfigure[\framedparameter{imagename}]") + xsized PaperWidth ysized (PaperHeight+4cm) + shifted center Page shifted (0,2cm); + + for i=1 upto 512 : + draw (textext("\reuseMPgraphic{nodes::krebs}") scaled (1/5 randomized 1/5)) + shifted (center Page randomized (PaperWidth,PaperHeight)) ; + endfor ; + + draw (textext.ulft("\word{\documentvariable{title}}") xsized (PaperWidth/2)) + shifted (lrcorner Page) + shifted (-PaperWidth/10,2PaperWidth/10) + withcolor white; + + draw (textext.ulft("\word{\documentvariable{author}}") xsized (PaperWidth/2)) + shifted (lrcorner Page) + shifted (-PaperWidth/10,PaperWidth/10) + withcolor white; + + StopPage ; + +\stopuseMPgraphic + +\startsetups document:start + + % We each have our preferred cover... ;-) + + \doifmodeelse {atpragma} { + \startMPpage[imagename=nodes-sun-pia-03150] + \includeMPgraphic{CoverPage} + \stopMPpage + } { + \startMPpage[imagename=nodes-sun-pia-03149] + \includeMPgraphic{CoverPage} + \stopMPpage + } + +\stopsetups + +\startsetups document:stop + +\stopsetups + +% And now, the document! + +\startdocument + [title=Nodes, + author=Alan Braslau, + copyright=\ConTeXt\ development team, + version=1.0] + +\startsubject [title=Introduction] + +The graphical representation of textual diagrams is a very useful tool in the +communication of ideas. In category and topos theory, for example, many key +concepts, formulas, and theorems are expressed by means of \emph {commutative +diagrams}; these involve objects and arrows between them. Certain concepts +discovered by category theory, such as \emph {natural transformations}, are +becoming useful in areas outside of mathematics and natural science, e.g., in +philosophy. To make category and topos methods usable by both specialists and +non|-|specialists, commutative diagrams are an indispensable tool. +\startfootnote + For many examples of formal and informal commutative diagrams, see \cite + [authoryears] [Lawvere2009]. +\stopfootnote +The use of nodal diagrams is not limited to category theory, for they may +represent a flow diagram (of a process, for example), a chemical reaction +sequence or pathways, or that of phases and phase transitions, a hierarchical +structure (of anything), a timeline or sequence of events or dependencies, a tree +of descendance or ascendance, etc. + +The basic units of a node|-|based diagram include \emph {node objects}, each +attached to some point (= the \emph {node}) in some spatial relationship. Note +that to a single node might be associated a set of objects. Given a node, it also +stands in a spatial relation to some other node. The spatial relationship between +the set of nodes of a diagram need not be in a regular network, although they +quite often are. Note that the spatial relationship between nodes is graphical +and may represent, e.g., a temporal or logical relationship, or a transformation +of one object into another or into others (one interesting example might be that +representing cell division or, mitosis). + +Given a spatial relation between any two nodes, a node|-|based diagram often +includes some \emph {path segment} or segments (such as arrows or other curves) +between two given nodes that \emph {relates} them. Each path segment may be +augmented by some textual or graphical label. + +A very simple example of a node diagram is shown in \in{Figure} [fig:AB]. + +\startbuffer +\startMPcode + clearnodepath ; + nodepath = (left -- right) scaled .75cm ; + draw node(0,"A") ; + draw node(1,"B") ; + drawarrow fromto(0,0,1) ; +\stopMPcode +\stopbuffer + +\startplacefigure [reference=fig:AB] + \getbuffer +\stopplacefigure + +\startplacefigure [reference=fig:ID, + location={right,+2*hang}] +\startMPcode + clearnodepath ; nodepath = origin ; + draw node(0,"$O$") ; + drawarrow fromto.urt (.75cm,0,0) ; + setbounds currentpicture to boundingbox currentpicture + enlarged (1.2cm,0) ; +\stopMPcode +\stopplacefigure + +More precisely, a \emph {node} is a point of intersection or branching of paths, +often a point on a regular lattice. (The nodes of the above diagram are the two +endpoints of a straight line segment.) Sometimes, however, a node might be a +single point as in an \emph {identity map} of category theory, referring to +itself: +\startfootnote + The standard arrowhead in \METAPOST\ is a simple triangle, whose length and + angle can be adjusted. \METAFUN\ provides further options, allowing this + arrowhead to be barbed or dimpled. In the present article, we use the + settings: \type {ahlength := EmWidth ; ahangle := 30 ; ahvariant := 1 ; + ahdimple := 4/5 ;} The loop|-|back arrow paths used here deviate from a + circular segment, becoming ellipsoidal, through the value \type + {node_loopback_yscale := .7 ;} These are all set, of course, between a \type + {\startMPinitializations} … \type {\stopMPinitializations} pair. +\stopfootnote + +In this article we discuss a new \METAPOST\ module designed for handling +node|-|based graphics as well as a derivative simple \CONTEXT\ interface. To +illustrate, the code producing \inlinebuffer\ {could} be, in \METAPOST\ and the +\CONTEXT\ interface respectively: + +\starttwo + \METAPOST + \startTEX + \startMPcode + draw node(0,"A") ; + draw node(1,"B") ; + drawarrow fromto(0,1) ; + \stopMPcode + \stopTEX +\two + \CONTEXT + \startbuffer + \startnodes [dx=1.5cm] + \placenode [0,0] {A} + \placenode [1,0] {B} + \connectnodes [0,1] + [alternative=arrow] + \stopnodes + \stopbuffer + \typebuffer [option=TEX] +\stoptwo + +drawing an arrow from A to B (or from node 0 to node 1): \getbuffer + +\startitemize[packed] + \startitem + The \METAPOST\ code shown above has been slightly simplified, as will be + seen later. + \stopitem + \startitem + The \CONTEXT\ interface as used here is limited and will be explained a + little later. + \stopitem +\stopitemize + +For beginners or casual users of \CONTEXT\ |<|including those who might be +intimidated by \METAPOST\ syntax|>| the ability to construct simple diagrams by +means of standard \CONTEXT\ syntax is very helpful. For those who have tried the +\CONTEXT\ interface and/or want to draw more advanced diagrams, the \METAPOST\ +module is much more powerful and flexible. + +\stopsubject + +\startsubject [title=\METAPOST] + +\METAPOST\ is a vector|-|graphics language which calls upon \TeX\ to typeset text +(such as labels); in \CONTEXT, furthermore, \METAPOST\ is integrated natively +through the library MPlib as well as the macro package \METAFUN. The tight +integration of \CONTEXT\ and \METAPOST\ provides advantages over the use of +other, external graphics engines. These advantages include ease of maintaining +coherence of style, as well as extensive flexibility without bloat. \METAPOST\ +has further advantages over most other graphics engines, including a very high +degree of precision as well as the possibility to solve certain types of +algebraic equations. This last feature is rarely used but should not be +overlooked. + +It is quite natural in \METAPOST\ to locate our node objects along a path or on +differing paths. This is a much more powerful concept than merely locating a node +at some pair of coordinates, e.g., on a square or a rectangular lattice, for +example (as in a table). Furthermore, these paths may be in three dimensions (or +more); of course the printed page will only involve some projection onto two +dimensions. Nor are the nodes restricted to location on the points defining a +path: they may have, as index, any \emph {time} along a given path \type {p} +ranging from the first defining point ($t = 0$) up to the last point of that path +($t ≤ \mathtt {length(p)}$), the number of defining points of a path. +\startfootnote + Note that the time of a cyclic path is taken modulo the length of the path, + that is $t$ outside of the range $[\mathtt0,\mathtt{length(p)}]$ will return + the first or the last point of an open path, but will \quotation {wrap} for a + closed path. +\stopfootnote + +Given a path \type {p}, nodes are defined (implicitly) as \type {picture} +elements: \type {picture p.pic[] ;} This is a pseudo|-|array where the square +brackets indicates a set of numerical tokens, as in \type {p.pic[0]} or \type +{p.pic[i]} (for \type {i=0}), but also \type {p.pic0}. This number need not be an +integer, and \type {p.pic[.5]} or \type {p.pic.5} (not to be confused with \type +{p.pic5}) are also valid. These picture elements are taken to be located relative +to the path \type {p}, with the index \type {t} corresponding to a time along the +path, as in \type {draw p.pic[t] shifted point t of p;} (although it is not +necessary to draw them in this way). This convention allows the nodes to be +oriented and offset with respect to the path in an arbitrary manner. + +Note that a path can be defined, then nodes placed relative to this path. Or the +path may be declared but remain undefined, to be determined only after the nodes +are declared. In yet another possibility, the path may be adjusted as needed, as +a function of whatever nodes are to be occupied. This will be illustrated through +examples further down. + +\stopsubject + +\startsubject [title=A few simple examples] + +\startplacefigure [location=right,reference=fig:square] + \startMPcode + path p ; p := fullsquare scaled 3cm ; + draw p ; + for i=0 upto length p: + draw point i of p + withcolor red + withpen pencircle scaled 5pt ; + endfor ; + % this looks better in the figure placement: + setbounds currentpicture to boundingbox currentpicture + enlarged (.5cm,0) ; + \stopMPcode +\stopplacefigure + +Let's begin with illustration of a typical commutative diagram from category +theory. Although it may appear trivial, this example helps to introduce +\METAPOST\ syntax. At the same time, a large part of the idea behind this module +is to facilitate use of this system without having to learn much \METAPOST. + +A path is drawn as well as the points defining the path. + +%\flushsidefloats + +\startTEX +\startMPcode + path p ; p := fullsquare scaled 3cm ; draw p ; + for i=0 upto length p: + draw point i of p + withcolor red + withpen pencircle scaled 5pt ; + endfor ; +\stopMPcode +\stopTEX + +\startbuffer +\startMPcode + clearnodepath ; + nodepath = p ; + draw node(0,"\node{$G(X)$}") ; + draw node(1,"\node{$G(Y)$}") ; + draw node(2,"\node{$F(Y)$}") ; + draw node(3,"\node{$F(X)$}") ; + drawarrow fromto.bot(0,0,1, "\nodeSmall{$G(f)$}") ; + drawarrow fromto.top(0,3,2, "\nodeSmall{$F(f)$}") ; + drawarrow fromto.rt (0,2,1, "\nodeSmall{$η_Y$}") ; + drawarrow fromto.lft(0,3,0, "\nodeSmall{$η_X$}") ; +\stopMPcode +\stopbuffer + +\startplacefigure [location={right,+1*hang},reference=fig:natural, + title={Drawn using \METAPOST\ interface}] + \getbuffer +\stopplacefigure + +Given the named path \type {nodepath}, we can now define and draw nodes as well +as connections between them (see \in{Figure} [fig:natural]): + +%\flushsidefloats + +\typebuffer [option=TEX] + +\startaside +In working with \METAPOST, it is good practice to reset or clear a variable using +the directive \type {save} for the \emph {suffix} (or variable name) \type +{nodepath} contained in the directive \type {clearnodepath} (defined as +\quotation {\type {save nodepath ; path nodepath}}). The macros used here rely on +the creation of certain internal variables and may not function correctly if the +variable structure is not cleared. Indeed, any node may contain a combination of +picture elements, added successively, so it is very important to \type {save} the +variable, making its use local, rather than global. This point is particularly +true with \CONTEXT, where a single MPlib instance is used and maintained over +multiple runs. + +The \CONTEXT\ directives \type {\startMPcode} … \type {\stopMPcode} include +grouping (\METAPOST\ \type {begingroup ;}… \type {endgroup ;}) and the use of +\type {save} (in \type {clearnodepath}) will make the suffix \type {nodepath} +local to this code block. In the code for \in{Figures} [fig:square] and \in +[fig:natural], the path \type {p} itself is not declared local (through the use +of a \type {save}); it therefore remains available for other \METAPOST\ code +blocks. We cannot do this with the default suffix name \type {nodepath} without +undesired consequences. + +The directive \type {clearnodepath} used in the example above, much like the +\METAPOST\ command \type {clearxy} clearing the \type {(x,y)} pair also known as +\type {z}, uses \type {save} to clear the default suffix \type {nodepath}. +\stopaside + +Note that one should not confuse the \METAPOST\ function \type {node()} with the +\CONTEXT\ command \type {\node{}}, defined as follows: + +\starttwo + \startTEX + \defineframed + [node] + [frame=off, + offset=1pt] + \stopTEX +\two + \startTEX + \defineframed + [nodeSmall] + [node] + [foregroundstyle=small] + \stopTEX +\stoptwo + +\type {\node{}} places the text within a \CONTEXT\ frame (with the frame border +turned|-|off), whereas the \METAPOST\ function \type {node(i,"…")} sets and +returns a picture element associated with a point on path \type {nodepath} +indexed by its first argument. The second argument here is a string that gets +typeset by \TEX. (The use of \type {\node{}} adds an \type {offset}). + +By default, the \METAPOST\ function \type {fromto()} returns a path segment going +between two points of the path \type {nodepath}. The first argument (\type {0} in +the example above) can be used as a displacement to skew the path away from a +straight line (by an amount in units of the straight path length). The last +argument is a string to be typeset and placed midpoint of the segment. The +{suffix} appended to the function name gives an offset around this halfway point. +This follows standard \METAPOST\ conventions. + +It is important to draw or declare the nodes \emph {before} drawing the +connections, using \type {fromto()}, in order to be able to avoid overlapping +symbols, as one notices that the arrows drawn in the example above begin and end +on the border of the frame (or bounding box) surrounding the node text. This +would of course not be possible if the arrow were to be drawn before this text +was known. + +As will be seen further on, one can actually specify the use of any defined path, +without restriction to the built|-|in name \type {nodepath} that is used by +default. Furthermore, a function \type {fromtopaths()} can be used to draw +segments connecting any two paths which may be distinct. This too will be +illustrated further on. + +The \CONTEXT\ syntax for the current example looks like this: + +\startbuffer + \startnodes [dx=3cm,dy=3cm] + \placenode [0,0] {\node{$G(X)$}} + \placenode [1,0] {\node{$G(Y)$}} + \placenode [1,1] {\node{$F(Y)$}} + \placenode [0,1] {\node{$F(X)$}} + \connectnodes [0,1] [alternative=arrow, + label={\nodeSmall{$G(f)$}},position=bottom] + \connectnodes [3,2] [alternative=arrow, + label={\nodeSmall{$F(f)$}},position=top] + \connectnodes [2,1] [alternative=arrow, + label={\nodeSmall{$η_Y$}}, position=right] + \connectnodes [3,0] [alternative=arrow, + label={\nodeSmall{$η_X$}}, position=left] + \stopnodes +\stopbuffer + +\startplacefigure [location=right, + title={Drawn using \CONTEXT\ interface}] + \getbuffer +\stopplacefigure + +\typebuffer [option=TEX] + +\startplacefigure [reference=fig:indices, + location=right, + title={Coordinates and indices.\footnote{For variety, a rectangular oblique + lattice is drawn in \in{Figure} [fig:indices].} + }] +\stopfootnote + \startframed [frame=off,width=.33\textwidth,align=flushright] + \startnodes [dx=3cm,dy=2cm,rotation=60] + \placenode [0,0] {\node{(0,0)}} + \placenode [1,0] {\node{(1,0)}} + \placenode [1,1] {\node{(1,1)}} + \placenode [0,1] {\node{(0,1)}} + \connectnodes [0,1] [alternative=arrow, + label={\nodeSmall{$0\rightarrow1$}},position=bottom] + \connectnodes [3,2] [alternative=arrow, + label={\nodeSmall{$3\rightarrow2$}},position=top] + \connectnodes [2,1] [alternative=arrow, + label={\nodeSmall{$~2\rightarrow1$}}, position=right] + \connectnodes [3,0] [alternative=arrow, + label={\nodeSmall{$3\rightarrow0$}}, position=upperleft] + \stopnodes + \stopframed +\stopplacefigure + +This follows the more classic (and limited) approach of placing nodes on the +coordinates of a regular lattice, here defined as a 3~cm square network. +\footnote {The lattice can be square (\type {dx} $=$ \type {dy}), rectangular +(\type {dx} $≠$ \type {dy}), or oblique (through \type {rotation} $≠$ 90).} The +arguments are then $(x,y)$ coordinates of this lattice and the nodes are indexed +0, 1, 2, … in the order that they are drawn. These are used as reference indices +in the commands \type {\connectnodes} (rather than requiring two \emph {pairs} of +coordinates); see \in {Figure} [fig:indices]. This might seem a bit confusing at +first view, but it simplifies things in the end, really! + +An identity map, as shown in \in {Figure} [fig:ID], earlier, and, below, in \in +{Figure} [fig:Me] is achieved by connecting a node to itself: + +\startbuffer +\startnodes [dx=2cm,dy=1cm] + \placenode [0,0] {\node{Me}} + \placenode [1,-1] {\node{You}} + \connectnodes [0,0] [alternative=arrow, + offset=.75cm,position=topright, + label=myself] + \connectnodes [1,1] [alternative=arrow, + offset=.75cm,position=bottomright, + label=yourself] +\stopnodes +\stopbuffer + +\startplacefigure [reference=fig:Me,title=Identity maps, + location=right] + \getbuffer +\stopplacefigure + +\typebuffer [option=TEX] + +The scale (diameter) of the circular loop|-|back is set by the keyword \type +{offset=} (normally used to curve or bow|-|away a path connecting nodes from the +straight|-|line segment between them), and the \type {position=} keyword sets its +orientation. + +\page [yes] + +\startbuffer +\startMPcode +clearnodepath ; +nodepath = fullsquare scaled 2cm ; +save A ; A = 3 ; draw node(A,"\node{A}") ; +save B ; B = 2 ; draw node(B,"\node{B}") ; +save C ; C = 0 ; draw node(C,"\node{C}") ; +save D ; D = 1 ; draw node(D,"\node{D}") ; + +drawarrow fromto(0,B,C) ; +drawarrow fromto(0,A,D) crossingunder fromto(0,B,C) ; +\stopMPcode +\stopbuffer + +\startplacefigure [reference=fig:crossingunder, + location={right,+3*hang}, + title=A$\rightarrow$D under B$\rightarrow$C] + \startframed [frame=off,width=5cm,align=middle] + \getbuffer + \stopframed +\stopplacefigure + +Let us now consider the following code which illustrates the \METAFUN\ operator +\type {crossingunder} +\startfootnote + The operator \type {crossingunder} is of such general use that it has been + added to the \METAFUN\ base. +\stopfootnote +(see \in {Figure}[fig:crossingunder]). The \type {nodepath} indices are put into +variables \type {A}, \type {B}, \type {C}, and \type {D}, thus simplifying the +code. + +\typebuffer [option=TEX] + +\startplacefigure [reference=fig:sincos, + location=right, + title={\type{crossingunder}}] + \startMPcode + save u ; u := 2cm ; + save p ; path p[] ; + n := 64 ; + p2 := for i=0 upto n : if i>0 : .. fi (3u*(i/n), u*sind(720*(i/n))) endfor ; + p3 := for i=0 upto n : if i>0 : .. fi (3u*(i/n), u*cosd(720*(i/n))) endfor ; + p4 := point 0 of p2 -- point (length p2) of p2 shifted (left*.01u) ; + + draw p2 withcolor red ; + begingroup ; + interim crossingscale := 20 ; + draw (p3 crossingunder p2) crossingunder p4 withcolor blue ; + endgroup ; + drawarrow (p4 crossingunder p2) ; + \stopMPcode +\stopplacefigure + +Another illustration of the \type {crossingunder} operator in use is shown in \in +{figure} [fig:sincos]. Because the diagrams are all defined and drawn in +\METAPOST, one can easily use the power of \METAPOST\ to extend a simple node +drawing with any kind of graphical decoration. + +This brings up an important point that has limited the development of a +full|-|featured \CONTEXT\ module up to now. A pure \METAPOST\ interface affords +much more flexibility than can be conveniently reduced to a set of \TeX\ macros; +the \CONTEXT\ interface has been written to maintain only basic functionality. +\startfootnote + One can use \type {\nodeMPcode{}} to inject arbitrary \METAPOST\ code within + a \type {\startnode} … \type {\stopnode} pair, although in this example one + is probably better off using the straight \METAPOST\ interface. +\stopfootnote + +\stopsubject + +\startsubject [title=Cyclic diagrams] + +For a somewhat more complicated example, let us consider the representation of a +catalytic process such as that given by \cite [author] [Krebs1946]. \cite +[Krebs1946] The input is shown coming into the cycle from the center of a circle; +the products of the cycle are spun|-|off from the outside of the circle. We start +by defining a circular path where each point corresponds to a step in the cyclic +process. Our example will use six steps (see \in {Figure} [fig:circles]). + +We also want to define a second circular path with the same number of points at +the interior of this first circle for the input, and a third circular path at the +exterior for the output. + +The code is as follows: + +\page [yes] + +\startbuffer +\startMPcode + save p ; path p[] ; + % define a fullcircle path with nodes at 60° (rather than 45°) + p1 := (for i=0 step 60 until 300: dir(90-i) .. endfor cycle) scaled 2.5cm ; + p0 := p1 scaled .5 ; + p2 := p1 scaled 1.5 ; + + for i=0 upto 2: + draw p[i] ; + label.bot("\bf p" & decimal i, point 0 of p[i]) ; + for j=1 upto length p[i]: + draw point j of p[i] withpen currentpen scaled 10 withcolor red ; + if i=1: + label.autoalign(angle point j of p[i]) (decimal j, point j of p[i]) + withcolor red ; + fi + endfor + endfor +\stopMPcode +\stopbuffer + +\typebuffer [option=TEX] + +\startplacefigure [reference=fig:circles, + location=right, + title={The paths that we will use for the anchoring of nodes.}] + \getbuffer +\stopplacefigure + +[\type {autoalign()} is a feature defined within \METAFUN.] + +Nodes will then be drawn on each of these three circles and arrows will be used +to connect these various nodes, either on the same path or else between paths. + +The \METAPOST\ function \type {fromto()} is used to give a path segment that +points from one node to another. It \emph {assumes} the path \type {nodepath}, +and in fact calls the function \type {fromtopaths} that explicitly takes path +names as arguments. That is, \type {fromto (d, i, j, …)} is equivalent to \type +{fromtopaths (d, nodepath, i, nodepath, j, …)}. + +As stated above, this segment can be a straight line or else a path that can be +bowed|-|away from this straight line by a transverse displacement given by the +function's first argument (given in units of the straight segment length). When +both nodes are located on a single, defined path, this segment can be made to lie +on or follow this path, such as one of the circular paths defined above. This +behavior is obtained by using any non|-|numeric value (such as \type {true}) in +place of the first argument. Of course, this cannot work if the two nodes are not +located on the same path. + +The circular arc segments labeled \emph {\darkgreen a–f} are drawn on \in +{figure} [fig:Bethe] using the following: + +\startTEX +drawarrow fromtopaths.urt (true,p1,0,p1,1,"\nodeGreen{a}") ; +\stopTEX + +for example, where \type {\nodeGreen} is a frame that inherits from \type +{\node}, changing style and color: + +\startTEX +\defineframed + [nodeGreen] + [node] + [foregroundcolor=darkgreen, + foregroundstyle=italic] +\stopTEX + +The bowed|-|arrows feeding into the cyclic process and leading out to the +products, thus between different paths, from the path \type {p0} to the path +\type {p1} and from the path \type {p1} to the path \type {p2}, respectively, are +drawn using the deviations \type {+3/10} and \type {-1/10} (to and from +half|-|integer indices, thus mid|-|step, on path \type {p1}): + +\startTEX +drawarrow fromtopaths( 3/10,p0,0,p1,0.5) withcolor .6white ; +drawarrow fromtopaths(-1/10,p1,0.5,p2,1) withcolor .6white ; +\stopTEX + +\startplacefigure [reference=fig:Bethe, + title={The \cite[author] [Bethe1939a] cycle for the energy production in stars + \cite[alternative=year,left=(,right=)] [Bethe1939a+Bethe1939b] in a + \cite[author] [Krebs1946] representation of a catalytic process + \cite[alternative=year,left=(,right=)] [Krebs1946].}] +\startMPcode + + % differs slightly from \reuseMPgraphic{nodes::krebs} + + % The Bethe cycle for energy production in stars (1939), following Krebs (1946) + + save p ; path p[] ; + p1 := (for i=0 step 60 until 300: dir(90-i).. endfor cycle) scaled 2.75cm ; + p0 := p1 scaled .5 ; + p2 := p1 scaled 1.5 ; + + bboxmargin := 0pt ; + + draw node(p1,0,"\node{\chemical{^{12}C}}") ; + draw node(p1,1,"\node{\chemical{^{13}N}}") ; + draw node(p1,2,"\node{\chemical{^{13}C}}") ; + draw node(p1,3,"\node{\chemical{^{14}N}}") ; + draw node(p1,4,"\node{\chemical{^{15}O}}") ; + draw node(p1,5,"\node{\chemical{^{15}N}}") ; + + drawarrow fromtopaths.urt (true,p1,0,p1,1,"\nodeGreen{a}") ; + drawarrow fromtopaths.rt (true,p1,1,p1,2,"\nodeGreen{b}") ; + drawarrow fromtopaths.lrt (true,p1,2,p1,3,"\nodeGreen{c}") ; + drawarrow fromtopaths.llft(true,p1,3,p1,4,"\nodeGreen{d}") ; + drawarrow fromtopaths.lft (true,p1,4,p1,5,"\nodeGreen{e}") ; + drawarrow fromtopaths.ulft(true,p1,5,p1,6,"\nodeGreen{f}") ; + + draw node(p0,0,"\node{\chemical{^1H}}") ; + draw node(p0,2,"\node{\chemical{^1H}}") ; + draw node(p0,3,"\node{\chemical{^1H}}") ; + draw node(p0,5,"\node{\chemical{^1H}}") ; + + drawarrow fromtopaths(3/10,p0,0,p1,0.5) withcolor .6white ; + drawarrow fromtopaths(3/10,p0,2,p1,2.5) withcolor .6white ; + drawarrow fromtopaths(3/10,p0,3,p1,3.5) withcolor .6white ; + drawarrow fromtopaths(3/10,p0,5,p1,5.5) withcolor .6white ; + + draw node (p2,0,"\node{\chemical{^4He}}") ; + draw node (p2,1,"\node{$γ$}") ; + draw node.lrt (p2,2,"\node{$\mathrm{e}^+ + ν_\mathrm{e}$}") ; + draw node (p2,3,"\node{$γ$}") ; + draw node (p2,4,"\node{$γ$}") ; + draw node.ulft(p2,5,"\node{$\mathrm{e}^+ + ν_\mathrm{e}$}") ; + + drawarrow fromtopaths(-1/10,p1,0.5,p2,1) withcolor .6white ; + drawarrow fromtopaths(-1/10,p1,1.5,p2,2) withcolor .6white ; + drawarrow fromtopaths(-1/10,p1,2.5,p2,3) withcolor .6white ; + drawarrow fromtopaths(-1/10,p1,3.5,p2,4) withcolor .6white ; + drawarrow fromtopaths(-1/10,p1,4.5,p2,5) withcolor .6white ; + drawarrow fromtopaths(-1/10,p1,5.5,p2,0) withcolor .6white ; + +\stopMPcode +\stopplacefigure + +\startsubsubject [title={A lesson in \METAPOST}] + +An \quote {array} of paths is declared through \type {path p[] ;} it is not a +formal array, but rather a syntactic definition of a collection of path variables +\type {p0}, \type {p1}, … each of whose name is prefixed with the tag \quotation +{p} followed by any number, not necessarily an integer (e.g., \type {p3.14} is a +valid path name). The syntax allows enclosing this \quotation {index} within +square brackets, as in \type {p[0]} or, more typically, \type {p[i]}, where \type +{i} would be a numeric variable or the index of a loop. Note that the use of +brackets is required when using a negative index, as in \type {p[-1]} (for \type +{p-1} is interpreted as three tokens, representing a subtraction). Furthermore, +the variable \type {p} itself, would here be a numeric (by default), so \type +{p[p]} would be a valid syntactic construction! One could, additionally, declare +a set of variables \type {path p[][] ;} and so forth, defining also \type +{p[0][0]} (equivalently, \type {p0 0}) for example as a valid path, coexisting +with yet different from the path \type {p0}. + +\METAPOST\ also admits variable names reminiscent of a structure: \type {picture +p.pic[] ;} for example is used internally in the \type {node} macros, but this +becomes \type {picture p[]pic[] ;} when using a path \quote {array} syntax. These +variable names are associated with the suffix \type {p} and become all undefined +by \type {save p ;}. + +\stopsubsubject + +\startsubsubject [title={Putting it together}] + +What follows is simple example of a natural transformation, discovered and +articulated in the course of a philosophical research project (by Idris Samawi +Hamid). \in {Figure} [fig:NT] represents what is called the Croce Topos [named +after the Italian philosopher Benedetto Croce (1866–1952)]: + +\startbuffer +\startMPcode + save nodepath ; + path nodepath ; + nodepath = ((0,0) -- (1,0) -- (3,0) -- + (3,1) -- (1,1) -- (0,1) -- + cycle) scaled 4cm ; + draw node(0,"\node{Practical}") ; + draw node(1,"\node{Economic}") ; + draw node(2,"\node{Moral}") ; + draw node(3,"\node{Conceptual}") ; + draw node(4,"\node{Aesthetic}") ; + draw node(5,"\node{Theoretical}") ; + + drawarrow fromto.rt (.1,5,0,"\node{$γ$}") ; + drawarrow fromto.lft(.1,0,5,"\node{$γ'$}") ; + drawarrow fromto.rt (.1,4,1,"\node{$Fγ$}") ; + drawarrow fromto.lft(.1,1,4,"\node{$Fγ'$}") ; + drawarrow fromto.rt (.1,3,2,"\node{$Gγ$}") ; + drawarrow fromto.lft(.1,2,3,"\node{$Gγ'$}") ; + + drawarrow fromto.top( 0,4,3,"\node{\it concretization$_1$}") ; + drawarrow fromto.bot(.1,3,4,"\node{\it abstraction$_1$}") + dashed evenly ; + drawarrow fromto.top( 0,1,2,"\node{\it concretization$_2$}") ; + drawarrow fromto.bot(.1,2,1,"\node{\it abstraction$_2$}") + dashed evenly ; +\stopMPcode +\stopbuffer + +% Let's forget that and rather use \startnodes... + +\startbuffer +\startnodes [dx=4cm,dy=4cm,alternative=arrow] + \placenode [0,0] {\node{Practical}} + \placenode [1,0] {\node{Economic}} + \placenode [3,0] {\node{Moral}} + \placenode [3,1] {\node{Conceptual}} + \placenode [1,1] {\node{Aesthetic}} + \placenode [0,1] {\node{Theoretical}} + + \connectnodes [5,0] [offset=.1,position=right, label={\node{$γ$}}] + \connectnodes [0,5] [offset=.1,position=left, label={\node{$γ'$}}] + \connectnodes [4,1] [offset=.1,position=right, label={\node{$Fγ$}}] + \connectnodes [1,4] [offset=.1,position=left, label={\node{$Fγ'$}}] + \connectnodes [3,2] [offset=.1,position=right, label={\node{$Gγ$}}] + \connectnodes [2,3] [offset=.1,position=left, label={\node{$Gγ'$}}] + + \connectnodes [4,3] [position=top, label={\node{\it concretization$_1$}}] + \connectnodes [3,4] [postition=bottom,offset=.1, option=dashed, + label={\node{\it abstraction$_1$}}] + \connectnodes [1,2] [position=top, label={\node{\it concretization$_2$}}] + \connectnodes [2,1] [position=bottom,offset=.1, option=dashed, + label={\node{\it abstraction$_2$}}] +\stopnodes +\stopbuffer + +\startplacefigure [reference=fig:NT, + title={A representation of the Croce Topos}] + \getbuffer +\stopplacefigure + +Here we use the \CONTEXT\ interface to the node package: + +\typebuffer [option=TEX] + +\stopsubsubject + +\stopsubject + +\startsubject [title=Tree diagrams] + +The tree diagram shown in \in {Figure} [fig:DNA] is drawn using four paths, each +one defining a row or generation in the branching. The definition of the spacing +of nodes was crafted by hand and is somewhat arbitrary: 3.8, 1.7, and 1 for the +first, second and third generations. This might not be the best approach, but +this is how I was thinking when I first created this figure. + +\startplacefigure [location=force,reference=fig:DNA] +\startMPcode + % third example: A tree diagram + + save u ; u := 2.25cm ; + save n ; n := 2 ; % n children per generation + + save p ; path p[] ; + p0 := origin ; + numeric d[] ; d1 := 3.8 ; d2 := 1.7 ; d3 := 1 ; + for g=1 upto 3: + p[g] := + for i=0 upto length(p[g-1]): + for c=0 upto n-1: + if (i+c)>0: -- fi + ((point i of p[g-1]) shifted (d[g]*(c/(n-1)-.5)*u,-u)) + endfor + endfor ; + endfor + + draw node(p0,0, "\node{DNA interactions with surfaces}") ; + draw node(p1,0, "\node{repulsive:}") ; + draw node(p1,1, "\node{attractive: adsorption}") ; + draw node(p2,0, "\node{confinement}") ; + draw node(p2,1, "\node[align=middle,location=high]{depletion,\\macromolecular\\crowding}") ; + draw node(p2,2, "\node{chemisorption}") ; + draw node(p2,3, "\node{physisorption}") ; + draw node(p3,5.5,"\node{immobilized}") ; + draw node(p3,7, "\node{mobile}") ; + + drawarrow fromtopaths(0,p0,0,p1,0) ; + drawarrow fromtopaths(0,p0,0,p1,1) ; + + drawarrow fromtopaths(0,p1,0,p2,0) ; + drawarrow fromtopaths(0,p1,0,p2,1) ; + drawarrow fromtopaths(0,p1,1,p2,2) ; + drawarrow fromtopaths(0,p1,1,p2,3) ; + + drawarrow fromtopaths(0,p2,2,p3,5.5) ; + drawarrow fromtopaths(0,p2,3,p3,5.5) ; + drawarrow fromtopaths(0,p2,3,p3,7) ; + +\stopMPcode +\stopplacefigure + +Ultimately, one can do better by allowing \METAPOST\ to solve the relevant +equations and to determine this spacing automatically. Because it is a somewhat +advanced procedure, this approach will be first illustrated through a very simple +example of a diagram where the nodes will be placed on a declared but undefined +path: + +\startTEX +save p ; % path p ; +\stopTEX + +The \type {save p ;} assures that the path is undefined. This path will later ḻṯ +defined based on the contents of the nodes and a desired relative placement. In +fact, it is not even necessary to declare that the suffix will be a path, as the +path will be declared and automatically built once the positions of all the nodes +are determined. To emphasize this point, the \type {path} declaration above is +commented|-|out. + +\startdescription {Warning:} +Solving equations in \METAPOST\ can be non|-|trivial for those who are less +mathematically inclined. One needs to establish a coupled set of equations that +is solvable: that is, fully but not over|-|determined. +\stopdescription + +A few helper functions have been defined: \type {makenode()} returns a suffix +(variable name) corresponding to the node's position. The first such node can be +placed at any finite point, for example the drawing's origin. The following nodes +can be placed in relation to this first node: + +% \startframed [frame=off,align=text,offset=overlay] % keep this together on one page. +\startTEX +save nodepath ; +save first, second, third, fourth ; +pair first, second, third, fourth ; +first.i = 0 ; first = makenode(first.i, "\node{first}") ; +second.i = 1 ; second = makenode(second.i,"\node{second}") ; +third.i = 2 ; third = makenode(third.i, "\node{third}") ; +fourth.i = 3 ; fourth = makenode(fourth.i,"\node{fourth}") ; + +first = origin ; +second = first + + betweennodes.urt(nodepath,first.i, nodepath,second.i,whatever) ; +third = second + + betweennodes.lft(nodepath,second.i,nodepath,third.i, whatever) ; +fourth = third + + betweennodes.bot(nodepath,fourth.i,nodepath,first.i,3ahlength) ; +\stopTEX +% \stopframed + +The helper function \type {betweennodes()} returns a vector pointing in a certain +direction, here following the standard \METAPOST\ suffixes: \type {urt}, \type +{lft}, and \type {bot}, that takes into account the bounding boxes of the +contents of each node, plus an (optional) additional distance (here given in +units of the arrow|-|head length, \type {ahlength}). Using the keyword \type +{whatever} tells \METAPOST\ to adjust this distance as necessary. The above set +of equations is incomplete as written, so a fifth and final relation needs to be +added; the fourth node is also to be located directly to the left of the very +first node: +\startfootnote + Equivalently, we could declare that the first node located to the right of + the fourth node: \type {first = fourth + betweennodes.rt (nodepath, first.i, + nodepath, fourth.i, 3ahlength) ;} +\stopfootnote + +\startTEX +fourth = first + + betweennodes.lft(nodepath,fourth.i,nodepath,first.i,3ahlength) ; +\stopTEX + +Note that the helper function \type {makenode()} can be used as many times as +needed; if given no content, only returning the node's position. Additional nodes +can be added to this diagram along with appropriate relational equations, keeping +in mind that the equations must, of course, be solvable. This last issue is the +one challenge that most users might face. The function \type {node()} that was +used previously and returning a picture element to be drawn itself calls the +function \type {makenode()}, used here. The nodes have not yet been drawn: + +\startplacefigure [location=right,reference=fig:relative] +\startMPcode + save nodepath ; + save first, second, third, fourth ; + pair first, second, third, fourth ; + first.i = 0 ; first = makenode(first.i, "\node{first}") ; + second.i = 1 ; second = makenode(second.i,"\node{second}") ; + third.i = 2 ; third = makenode(third.i, "\node{third}") ; + fourth.i = 3 ; fourth = makenode(fourth.i,"\node{fourth}") ; + + first = origin ; + second = first + betweennodes.urt(nodepath,first.i, nodepath,second.i,whatever) ; + third = second + betweennodes.lft(nodepath,second.i,nodepath,third.i, whatever) ; + fourth = third + betweennodes.bot(nodepath,fourth.i,nodepath,first.i,3ahlength) ; + fourth = first + betweennodes.lft(nodepath,fourth.i,nodepath,first.i,3ahlength) ; + + for i = first.i, second.i, third.i, fourth.i : + draw node(i) ; + drawarrow fromto(0,i,i+1) ; + endfor +\stopMPcode +\stopplacefigure + +\startTEX +for i = first.i, second.i, third.i, fourth.i : + draw node(i) ; + drawarrow fromto(0,i,i+1) ; +endfor +\stopTEX + +This results in \in {Figure} [fig:relative]. The path is now defined as one +running through the position of all of the defined nodes, and is cyclic. + +Using this approach, that of defining but not drawing the nodes until a complete +set of equations defining their relative positions has been constructed, imposes +several limitations. First, the nodes are expected to be numbered from $0$ up to +$n$, continuously and without any gaps for each defined path. This is just an +implicit, heuristic convention of the path construction. Second, when finally +defining all the nodes and their positions, the path needs to be constructed. A +function, \type {makenodepath(p) ;} accomplishes this; it gets implicitly called +(once) upon the drawing of any \type {node()} or connecting \type {fromto}. Of +course, \type {makenodepath()} can always be called explicitly once the set of +equations determining the node positions is completely defined. + +\startparagraph [style=bold] +We once again stress that the writing of a solvable yet not over|-|determined set +of equations can be a common source of error for many \METAPOST\ users. +\startfootnote + The generous use of descriptive variables as we try to illustrate in the + examples here can help tremendously in keeping track of multiple equations. +\stopfootnote +\stopparagraph + +Another such example is the construction of a simple tree of descendance or +family tree. There are many ways to draw such a tree; in \in {figure} +[fig:descendance] we will show only three generations. + +\startplacefigure [location=here,reference=fig:descendance, + title={A tree of descendance}] +\startMPcode + save p ; % path p[], p[][] ; get automagically defined + save spacing ; spacing = 5pt ; + save d ; d = 4ahlength ; + + save mother, father ; pair mother, father ; + + mother = makenode(p,0,"\node{mother}") ; + father = makenode(p,1,"\node{father}") ; + + mother = origin ; + father = mother + betweennodes.rt(p,0,p,1,spacing) ; + + % first generation + save child, spouse ; pair child[], spouse[] ; + child = 0 ; spouse = 1 ; + + child1 = makenode(p0,child, "\node{child1}") ; + spouse1 = makenode(p0,spouse,"\node{spouse}") ; + child2 = makenode(p1,child, "\node{child2}") ; + spouse2 = makenode(p1,spouse,"\node{spouse}") ; + + .5[child1,child2] = mother + d*down ; + spouse1 = child1 + betweennodes.rt(p0,child, p0,spouse,spacing) ; + child2 = spouse1 + betweennodes.rt(p0,spouse,p1,child, whatever) ; + spouse2 = child2 + betweennodes.rt(p1,child, p1,spouse,spacing) ; + + % second generation + save grandchild, grandspouse ; pair grandchild[], grandspouse[] ; + grandchild1 = makenode(p0 0,child, "\node{grandchild1}") ; + grandspouse1 = makenode(p0 0,spouse,"\node{spouse}") ; + grandchild2 = makenode(p0 1,child, "\node{grandchild2}") ; + grandspouse2 = makenode(p0 1,spouse,"\node{spouse}") ; + grandchild3 = makenode(p1 0,child, "\node{grandchild3}") ; + grandspouse3 = makenode(p1 0,spouse,"\node{spouse}") ; + grandchild4 = makenode(p1 1,child, "\node{grandchild4}") ; + grandspouse4 = makenode(p1 1,spouse,"\node{spouse}") ; + + .5[grandchild1,grandchild2] = child1 + d*down ; + .5[grandchild3,grandchild4] = child2 + d*down ; + grandchild2 = grandchild1 + betweennodes.rt(p0 0,child,p0 1,child,spacing) ; + grandchild3 = grandchild2 + betweennodes.rt(p0 1,child,p1 0,child,spacing) ; + grandchild4 = grandchild3 + betweennodes.rt(p1 0,child,p1 1,child,spacing) ; + grandspouse1 = grandchild1 + nodeboundingpoint.bot(p0 0,child) + + nodeboundingpoint.lrt(p0 0,spouse) ; + grandspouse2 = grandchild2 + nodeboundingpoint.bot(p0 1,child) + + nodeboundingpoint.lrt(p0 1,spouse) ; + grandspouse3 = grandchild3 + nodeboundingpoint.bot(p1 0,child) + + nodeboundingpoint.lrt(p1 0,spouse) ; + grandspouse4 = grandchild4 + nodeboundingpoint.bot(p1 1,child) + + nodeboundingpoint.lrt(p1 1,spouse) ; + + draw node(p,0) ; + draw node(p,1) withcolor blue ; + + for i=0,1 : + draw node(p[i],child) ; + drawarrow fromtopaths(0,p,0,p[i],child) ; + draw node(p[i],spouse) withcolor blue ; + for j=0,1 : + draw node(p[i][j],child) ; + draw node(p[i][j],spouse) withcolor blue ; + endfor + drawarrow fromtopaths(0,p[i],child,p[i][0],child) ; + drawarrow fromtopaths(0,p[i],child,p[i][1],child) ; + endfor +\stopMPcode +\stopplacefigure + +We leave it as an exercise to the reader to come|-|up with the equations used to +determine this tree (one can look at source of this document, if necessary). + +The requisite set of equations could be hidden from the user wishing to construct +simple, pre|-|defined types of diagrams. However, such cases would involve a loss +of generality and flexibility. Nevertheless, the \ConTeXt-Nodes module \emph +{could} be extended in the future to provide a few simple models. One might be a +branching tree structure, although even the above example (as drawn) does not +easily fit into a simple, general model. + +\blank + +A user on the \CONTEXT\ mailing list asked if it is possible to make structure +trees for English sentences with categorical grammar, an example of which is +shown in \in {Figure} [fig:grammar]. + +\startbuffer +\startMPcode + save p ; path p[] ; + save n ; n = 0 ; + % rather than parsing a string, we can use "suffixes": + forsuffixes $=People,from,the,country,can,become,quite,lonely : + p[n] = makenode(p[n],0,"\node{\it" & (str $) & "}") + = (n,0) ; % we work first with unit paths. + n := n + 1 ; + endfor + save u ; u := MakeupWidth/n ; %(columns) TextWidth/n ; + + % build upward tree + + vardef makeparentnode(text t) = + save i, xsum, xaverage, ymax ; + i = xsum = 0 ; + forsuffixes $ = t : + clearxy ; z = point infinity of $ ; + xsum := xsum + x ; + if unknown ymax : ymax = y ; elseif y > ymax : ymax := y ; fi + i := i + 1 ; + endfor + xaverage = xsum / i ; + ymax := ymax + 1 ; + forsuffixes $ = t : + clearxy ; + z = point infinity of $ ; + $ := $ & z -- (x,ymax) if i>1 : -- (xaverage,ymax) fi ; + endfor + enddef ; + + makeparentnode(p2,p3) ; + makeparentnode(p4,p5) ; + makeparentnode(p6,p7) ; + makeparentnode(p1,p2) ; + makeparentnode(p0,p1) ; + makeparentnode(p4,p6) ; + makeparentnode(p0,p4) ; + makeparentnode(p0) ; + + % the paths are all defined but need to be scaled. + + for i=0 upto n-1 : + p[i] := p[i] xyscaled (u,.8u) ; + draw node(p[i],0) ; + endfor + + save followpath ; boolean followpath ; followpath = true ; + + draw fromtopaths(followpath,p0,0,p0,1,"\node{H:N}") ; + draw fromtopaths(followpath,p1,0,p1,1,"\node{Rel:Prep}") ; + draw fromtopaths(followpath,p2,0,p2,1,"\node{Dr:Dv}") ; + draw fromtopaths(followpath,p3,0,p3,1,"\node{H:N}") ; + draw fromtopaths(followpath,p4,0,p4,1,"\node{M:Aux}") ; + draw fromtopaths(followpath,p5,0,p5,1,"\node{H:Mv}") ; + draw fromtopaths(followpath,p6,0,p6,1,"\node{M:Adv}") ; + draw fromtopaths(followpath,p7,0,p7,1,"\node{H:Adj}") ; + + draw fromtopaths(followpath,p1,1,p1,2) ; + draw fromtopaths(followpath,p2,3,p2,4) ; + draw fromtopaths(followpath,p1,2,p1,3,"\node{M:PP}") ; + draw fromtopaths(followpath,p2,1,p2,2) ; + draw fromtopaths(followpath,p3,1,p3,2) ; + draw fromtopaths(followpath,p2,2,p2,3,"\node{Ax:NP}") ; + draw fromtopaths(followpath,p4,1,p4,2) ; + draw fromtopaths(followpath,p5,1,p5,2) ; + draw fromtopaths(followpath,p4,2,p4,3,"\node{P:VP}") ; + draw fromtopaths(followpath,p6,1,p6,2) ; + draw fromtopaths(followpath,p7,1,p7,2) ; + draw fromtopaths(followpath,p6,2,p6,3,"\node{PCs:AdjP}") ; + draw fromtopaths(followpath,p0,1,p0,2) ; + draw fromtopaths(followpath,p1,3,p1,4) ; + draw fromtopaths(followpath,p0,2,p0,3,"\node{S:NP}") ; + draw fromtopaths(followpath,p4,3,p4,4) ; + draw fromtopaths(followpath,p6,3,p6,4) ; + draw fromtopaths(followpath,p4,4,p4,5,"\node{Pred:PredP}") ; + draw node(p0,4.5,"\node{Cl}") ; + draw fromtopaths(followpath,p0,3,p0,4.5) ; + draw fromtopaths(followpath,p4,5,p4,6) ; +\stopMPcode +\stopbuffer + +\startplacefigure [reference=fig:grammar, + title={A categorical grammer structure tree}] + \getbuffer +\stopplacefigure + +Here, I chose to define a series of parallel paths, one per word, with one path +terminating whenever it joins another path (or paths) at a common parent. +Naturally, labeling each branch of the tree structure requires a knowledge of the +tree structure. The code is not short, but hopefully it is mostly clear. + +\typebuffer [option=TEX] + +Note that diagrams such as those constructed here will each be significantly +different, making the writing of a general mechanism rather complex. For example, +one might need to construct a tree branching up rather than down, or to the right +(or left), or even following an arbitrary path, such as a random walk. These can +all be achieved individually in \METAPOST\ without too much difficulty. + +\stopsubject + +\startsubject [title=A 3D projection] + +Although \METAPOST\ is a 2D drawing language, it can be easily extended to work +in 3D. Several attempts have been made in the past ranging from simple to +complicated. Here, we will take a simple approach. + +The \METAPOST\ language includes a triplet variable type, used to handle \type +{rgb} colors (it also has a quadruplet type used for \type {cmyk} colors). We +will use this \type {triplet} type to hold 3D coordinates. There is a separate +\CONTEXT\ module, entitled \type {three}, which creates a new \METAPOST\ instance +(also named \type {three}), which loads a set of macros that can be used to +manipulate these triplet coordinates. + +\usemodule [three] + +\startTEX +\usemodule [three] + +\startMPcode{three} + % code here +\stopMPcode +\stopTEX + +For our purposes here, only one function is really necessary: \type +{projection()} that maps a 3D coordinate to a 2D projection on the page. This +will not be a perspective projection having a viewpoint and a focus point, but +rather a very simple oblique projection, useful for, e.g., pseudo|-|3D schematic +drawings. The \type {Z} coordinate is taken to be \type {up} and the \type {Y} +coordinate taken to be \type {right}, both in the page of the paper. The third +coordinate \type {X} is an oblique projection in a right|-|hand coordinate +system. + +\page [yes] + +\startbuffer +\startMPcode{three} + save nodepath ; + path nodepath ; + nodepath = (projection Origin -- + projection (1,0,0) -- + projection (1,1,0) -- + projection (0,1,0) -- + projection (0,1,1) -- + projection (1,1,1) -- + projection (1,0,1) -- + projection (0,0,1) -- + cycle) scaled 5cm ; + + draw node(0,"\node{${\cal C}_{i\cal P}^{\mathrm{nt}}$}") ; + draw node(1,"\node{${\cal C}_{i\cal G}^{\mathrm{nt}}$}") ; + draw node(2,"\node{${\cal C}_{j\cal P}^{\mathrm{nt}}$}") ; + draw node(3,"\node{${\cal C}_{j\cal G}^{\mathrm{nt}}$}") ; + draw node(4,"\node{${\cal C}_{j\cal G}$}") ; + draw node(5,"\node{${\cal C}_{j\cal P}$}") ; + draw node(6,"\node{${\cal C}_{i\cal G}$}") ; + draw node(7,"\node{${\cal C}_{i\cal P}$}") ; + + interim crossingscale := 30 ; + drawdoublearrows fromto(0,0,1) ; + drawdoublearrows fromto(0,1,2) ; + drawdoublearrows fromto(0,2,3) ; + drawdoublearrows fromto(0,3,0) crossingunder fromto(0,2,5) ; + + drawdoublearrows fromto(0,7,6) ; + drawdoublearrows fromto(0,6,5) ; + drawdoublearrows fromto.ulft(0,5,4,"\node{$τ_j$~}") ; + drawdoublearrows fromto.top (0,7,4,"\node{$σ$}") ; + + drawdoublearrows fromto.lrt(0,0,7,"\node{$Ψ^{\mathrm{nt}}$}") + crossingunder fromto(0,6,5) ; + drawdoublearrows fromto(0,1,6) ; + drawdoublearrows fromto(0,2,5) ; + drawdoublearrows fromto(0,3,4) ; +\stopMPcode +\stopbuffer + +\startplacefigure [location=right, + reference=fig:cube] + \getbuffer +\stopplacefigure + +Intended for schematic drawings, there is no automatic hidden|-|line removal nor +effects like shading, and line crossings need to be handled manually (using \type +{crossingunder} introduced previously). In \in{Figure} [fig:cube] we draw a +simple cubical commutative diagram, with a node at each corner. + +\typebuffer [option=TEX] + +Note the use of \type {drawdoublearrows}, a new \METAFUN\ command that is +introduced here. + +\stopsubject + +\startsubject [title=Two final examples] + +\startbuffer[mp:tikz-cd] +\startMPcode + save nodepath ; save l ; l = 5ahlength ; + save X, Y, Z, XxY, T ; + pair X, Y, Z, XxY, T ; + XxY.i = 0 ; XxY = makenode(XxY.i,"\node{$X\times_Z Y$}") ; + X.i = 1 ; X = makenode(X.i, "\node{$X$}") ; + Z.i = 2 ; Z = makenode(Z.i, "\node{$Z$}") ; + Y.i = 3 ; Y = makenode(Y.i, "\node{$Y$}") ; + T.i = 4 ; T = makenode(T.i, "\node{$T$}") ; + XxY = origin ; + X = XxY + betweennodes.rt (nodepath,XxY.i,nodepath,X.i) + (l,0) ; + Z = X + betweennodes.bot(nodepath,X.i, nodepath,Z.i) + (0,-.8l); + Y = XxY + betweennodes.bot(nodepath,XxY.i,nodepath,Y.i) + (0,-.8l) ; + T = XxY + nodeboundingpoint.ulft(XxY.i) + + nodeboundingpoint.lft (T.i) + l*dir(135) ; + for i = XxY.i, X.i, Z.i, Y.i, T.i: + draw node(i) ; + endfor + drawarrow fromto.top(0, XxY.i,X.i, "\nodeSmall{$p$}") ; + drawarrow fromto.rt (0, X.i,Z.i, "\nodeSmall{$f$}") ; + drawarrow fromto.top(0, Y.i,Z.i, "\nodeSmall{$g$}") ; + drawarrow fromto.rt (0, XxY.i,Y.i, "\nodeSmall{$q$}") ; + drawarrow fromto.top( .13,T.i,X.i, "\nodeSmall{$x$}") ; + drawarrow fromto.urt(-.13,T.i,Y.i, "\nodeSmall{$y$}") ; + drawarrow fromto (0, T.i,XxY.i,"\nodeSmall{$(x,y)$}") + dashed withdots scaled .5 + withpen currentpen scaled 2 ; +\stopMPcode +\stopbuffer + +% Rather, let's do it similarly to TikZ. + +\startbuffer[mp:tikz-cd] +\startnodes [dx=2.5cm,dy=2cm,alternative=arrow] + \placenode [0, 0] {\node{$X\times_Z Y$}} + \placenode [1, 0] {\node{$X$}} + \placenode [1,-1] {\node{$Z$}} + \placenode [0,-1] {\node{$Y$}} + \placenode [-1,1] {\node{$T$}} + + \connectnodes [0,1] [position=top, label={\nodeSmall{$p$}}] + \connectnodes [1,2] [position=right, label={\nodeSmall{$f$}}] + \connectnodes [0,3] [position=right, label={\nodeSmall{$q$}}] + \connectnodes [3,2] [position=top, label={\nodeSmall{$g$}}] + \connectnodes [4,0] [option=dotted,rulethickness=1pt, + label={\nodeSmall{$(x,y)$}}] + \connectnodes [4,1] [offset=+.13,position=top, + label={\nodeSmall{$x$}}] + \connectnodes [4,3] [offset=-.13,position=topright, + label={\nodeSmall{$y$}}] +\stopnodes +\stopbuffer + +\startplacefigure [reference=fig:tikz-cd, + location={right,+3*hang}] + \getbuffer[mp:tikz-cd] +\stopplacefigure + +We end this manual with two examples of more advanced commutative diagrams. The +following example, shown in \in {Figure} [fig:tikz-cd], illustrates what in +category theory is called a \emph {pullback}. It is inspired from an example +given in the TikZ CD (commutative diagrams) package. + +The arrow labeled \quotation {$(x,y)$} is drawn \type {dashed withdots} and +illustrates how the line gets broken, implicitly \type {crossingunder} its +centered label. + +\typebuffer[mp:tikz-cd] [option=TEX] + +The previous diagram was drawn using the \CONTEXT\ interface. Our final example, +shown in \in {Figure} [fig:tikz-cd2], gives another \quotation {real|-|life} +example of a categorical pullback, also inspired by TikZ-CD, but this time drawn +through the \METAPOST\ interface and solving for positions. + +\startbuffer[mp:tikz-cd2] +\startMPcode + save nodepath ; save l ; l = 5ahlength ; + save A, B, C, D, E ; + pair A, B, C, D, E ; + A.i = 0 ; A = makenode(A.i,"\node{$\pi_1(U_1\cap U_2)$}") ; + B.i = 1 ; B = makenode(B.i, + "\node{$\pi_1(U_1)\ast_{\pi_1(U_1\cap U_2)}\pi_1(U_2)$}") ; + C.i = 2 ; C = makenode(C.i,"\node{$\pi_1(X)$}") ; + D.i = 3 ; D = makenode(D.i,"\node{$\pi_1(U_2)$}") ; + E.i = 4 ; E = makenode(E.i,"\node{$\pi_1(U_1)$}") ; + A = origin ; + B = A + betweennodes.rt(nodepath,A.i,nodepath,B.i) + ( l,0) ; + C = B + betweennodes.rt(nodepath,B.i,nodepath,C.i) + (.7l,0) ; + D = .5[A,B] + (0,-.9l) ; + E = .5[A,B] + (0, .9l) ; + + for i = A.i, B.i, C.i, D.i, E.i : + draw node(i) ; + endfor + drawarrow fromto.llft( 0,A.i,D.i,"\smallnode{$i_2$}") ; + drawarrow fromto.ulft( 0,A.i,E.i,"\smallnode{$i_1$}") ; + drawarrow fromto ( 0,D.i,B.i) ; + drawarrow fromto ( 0,E.i,B.i) ; + drawarrow fromto.urt( .1,E.i,C.i,"\smallnode{$j_1$}") ; + drawarrow fromto.lrt(-.1,D.i,C.i,"\smallnode{$j_2$}") ; + drawarrow fromto.top( 0,B.i,C.i) dashed evenly ; + draw textext.top("{\tfxx\strut$\simeq$}") + shifted point .4 of fromto(0,B.i,C.i) ; +\stopMPcode +\stopbuffer + +\startplacefigure [location=here,reference=fig:tikz-cd2] + \getbuffer[mp:tikz-cd2] +\stopplacefigure + +\typebuffer[mp:tikz-cd2] [option=TEX] + +\stopsubject + +\startsubject [title=Conclusions] + +There was initial consensus at the 2017 \CONTEXT\ Meeting in Maibach, Germany, +where a version of this package was presented, that there was little use of +developing a purely \CONTEXT\ interface. Rather, the \METAPOST\ package should be +sufficiently accessible. Since then, however, we decided that the development of +a derivative \CONTEXT\ interface implementing some basic functionality could +indeed be useful for many users, although it will necessarily remain somewhat +limited. Users are recommended to turn to the pure \METAPOST\ interface when more +sophisticated functionality is needed. + +\stopsubject + +\startsubject [title=Acknowledgements] + +This module was inspired by a request made by Idris Samawi Hamid to draw a +natural transformation diagram (\in{Figure} [fig:natural]). The \METAPOST\ macros +that were developed then benefited from improvements suggested by Hans Hagen as +well as inspiration provided by Taco Hoekwater. + +The cover artwork one can recognize as coming under the hand of Hans Hagen that +he produced when I mentioned that I wanted to do something along these lines. It +fits very well into the style of manual covers that we distribute with \CONTEXT. +This manual therefore has been co|-|written by Hans and Alan. + +\stopsubject + +\startsubject [title=References] + + \placelistofpublications + +\stopsubject + +\stoptitle + +\stoptext diff --git a/doc/context/sources/general/manuals/notnow/notnow-columns-and-notes.tex b/doc/context/sources/general/manuals/notnow/notnow-columns-and-notes.tex new file mode 100644 index 000000000..336c39480 --- /dev/null +++ b/doc/context/sources/general/manuals/notnow/notnow-columns-and-notes.tex @@ -0,0 +1,26 @@ +\usemodule[art-01] + +\starttext + + \samplefile{tufte} + \footnote{\samplefile{tufte}} + + \startitemize[packed,columns] + \startitem one \stopitem + \startitem two \stopitem + \startitem three \footnote{A note (three).} + \stopitem + \startitem four \stopitem + \startitem five \stopitem + \startitem six \stopitem + \startitem seven \stopitem + \startitem eight \stopitem + \stopitemize + + \dorecurse {10} { + \samplefile{ward} + \footnote{Another note #1!} + \par + } + +\stoptext diff --git a/doc/context/sources/general/manuals/notnow/notnow-sidefloats.tex b/doc/context/sources/general/manuals/notnow/notnow-sidefloats.tex new file mode 100644 index 000000000..4a8a1ba3b --- /dev/null +++ b/doc/context/sources/general/manuals/notnow/notnow-sidefloats.tex @@ -0,0 +1,59 @@ +\usemodule[art-01] + +\starttext + +\definefloat + [figure-column] + +\setupfloat + [figure-column] + [default={left,nonumber,none,high}, % high kills sidespacebefore + topoffset=\strutgap] + +\setupfloat + [sidespacebefore=, + sidespaceafter=] + +\enabletrackers[*float*] + +\starttext + +\input ward + +\placefloat + [figure-column][][]{} + {\externalfigure[t:/sources/cow.pdf][width=3cm,frame=on]} + +\input ward + +\placefloat + [figure-column][][]{} + {\externalfigure[t:/sources/cow.pdf][width=3cm,frame=on]} + +\input ward + +\placefloat + [figure-column][][]{} + {\externalfigure[t:/sources/cow.pdf][width=3cm,frame=on]} + +\flushsidefloats + +\input ward + +\page + +\setupfloat + [spacebeforeside=3*big, + spaceafterside=5*big] + +\input ward + +\placefloat + [figure-column][][]{} + {\externalfigure[t:/sources/cow.pdf][width=3cm,frame=on]} + +\flushsidefloats + +\input ward + +\stoptext diff --git a/doc/context/sources/general/manuals/notnow/notnow.tex b/doc/context/sources/general/manuals/notnow/notnow.tex new file mode 100644 index 000000000..e1768db41 --- /dev/null +++ b/doc/context/sources/general/manuals/notnow/notnow.tex @@ -0,0 +1,175 @@ +% language=uk + +\usemodule[typesetting] + +\defineexternalfigure + [typesetting] + [frame=on, + framecolor=darkblue, + rulethickness=1pt] + +\setupcombination + [twopages] + [style=bold, + color=darkblue] + +\setupbodyfont + [ebgaramond,14.4pt] + +\setuphead + [chapter] + [style=\bfc, + header=empty, + color=darkblue] + +\setuplist + [chapter] + [alternative=c, + width=1.5em] + +\setuplayout + [width=middle, + height=middle, + topspace=15mm, + backspace=15mm, + header=15mm, + footer=0mm] + +\setupwhitespace + [big] + +\setuptype + [color=darkblue] + +\setuptyping + [color=darkblue] + +\setuppagenumbering + [alternative=doublesided] + +% \showframe + +\startdocument[author=Hans Hagen] + +\definefont[NotNow][Serif*default @ 18pt]% +\definefont[NotNot][Serif*default @ 2.5pt]% + +\startpagemakeup[pagestate=stop] + \scale[width=\paperwidth,height=\paperheight] \bgroup + \bTABLE[strut=no,height=29.7pt,width=21pt,align={lohi,middle},foregroundcolor=white,framecolor=white,background=color] + \bTR + \bTD[backgroundcolor=darkblue] \NotNow W \eTD + \bTD[backgroundcolor=darkgray] \NotNow H \eTD + \bTD[backgroundcolor=darkblue] \NotNow Y \eTD + \eTR + \bTR + \bTD[backgroundcolor=darkgray] \NotNow N \eTD + \bTD[backgroundcolor=darkblue] \NotNow O \eTD + \bTD[backgroundcolor=darkgray] \NotNow T \eTD + \eTR + \bTR + \bTD[backgroundcolor=darkblue] \NotNow N \eTD + \bTD[backgroundcolor=darkgray] \NotNow O \eTD + \bTD[backgroundcolor=darkblue] \NotNow W \eTD + \eTR + \eTABLE + \egroup +\stoppagemakeup + +\starttitle[title=Contents] + + \placelist[chapter] + +\stoptitle + +\startchapter[title=Introduction] + +You can do a lot in \CONTEXT\ but for sure there are limitations too. There are +quite some sub|-|mechanisms and sometimes there are more solutions for one +problem. For instance, we have several table mechanisms and several +multi|-|column mechanisms. In this document we will collect information about +what doesn't work (well) and if possible indicate why. Feel free to submit more +items. We will also discuss features that do work in most cases but are somewhat +unreliable. + +Does that mean that we cannot make everything work? No, sometimes demands are too +conflicting. Yes, we can implement more, but it simply doesn't pay off to spend +time on writing code that is used seldom. Keep in mind that much of \CONTEXT\ is +written in spare time without any compensation. Publishers have demands but +seldom are willing to pay for it. Users have demands and no means to pay for it. +On the other hand, user demands often have challenging properties that trigger +development. Sometimes a project has as side effect that some mechanism become +better. + +The good news that one can often work around it. Not all typesetting has to be +fully automatic. And there are always reasonable typographic alternatives. The +examples shown here can be run on your machine. + +\stopchapter + +\startchapter[title=Columns and notes] + +Because \TEX\ doesn't really support columns we need to cook up some magic to +achieve them. Especially a mix between single and multi|-|columns is sort of +tricky. Because notes are inserts and inserts play a role in determining the +optimal breakpoints they can interfere badly, depending on the mechanism used. In +\CONTEXT\ we use mixed columns for multi|-|column itemizations and as these can +have footnotes you can end up in troubles. + +\typefile{notnow-columns-and-notes.tex} + +In such case the notes are postponed and flushed {\em after} the itemized list so +they can end up on a next page. If this happens depends on how much room there is +on the page. Solutions are possible (and the old \MKII\ column handler might +behave better in some cases) but it's not worth the trouble to complicate the +already complex code more than needed. Also, it will never be perfect anyway. + +\FirstPages{notnow-columns-and-notes} + +\stopchapter + +\startpagemakeup[pagestate=stop,page=left,doublesided=no] + \scale[width=\paperwidth,height=\paperheight] \bgroup + \bTABLE[strut=no,height=29.7pt,width=21pt,align={lohi,middle},foregroundcolor=white,framecolor=white,background=color] + \bTR + \bTD[backgroundcolor=darkblue] \eTD + \bTD[backgroundcolor=darkgray] \eTD + \bTD[backgroundcolor=darkblue] \eTD + \eTR + \bTR + \bTD[backgroundcolor=darkgray] \eTD + \bTD[backgroundcolor=darkblue] \eTD + \bTD[backgroundcolor=darkgray] \eTD + \eTR + \bTR + \bTD[backgroundcolor=darkblue] \eTD + \bTD[backgroundcolor=darkgray] \eTD + \bTD[backgroundcolor=darkblue,foregroundstyle=\NotNot] + Hans Hagen \vfilll PRAGMA ADE \vfilll Hasselt NL + \eTD + \eTR + \eTABLE + \egroup +\stoppagemakeup + +\startchapter[title=Sidefloats] + +Support for side floats is non|-|trivial and no solution will serve all intended +usage. Over the years we have improved on border cases but it is still not +perfect. For that reason the implementation is (apart from solving bugs, mostly) frozen. +Here is an example of a use case that we ran into. We manipulate the spacing with +an offset parameter. + +\typefile{notnow-sidefloats.tex} + +You can best play with these parameters and see what they do. If you use this +mechanism in a long term project, use a frozen instance of \CONTEXT ! + +\TwoPages{notnow-sidefloats} + +The second pages has preceding and trailing whitespace outside the sidefloat +flow. + +\stopchapter + +\stopdocument diff --git a/doc/context/sources/general/manuals/onandon/m-fonts-plugins-timings-luajittex.lua b/doc/context/sources/general/manuals/onandon/m-fonts-plugins-timings-luajittex.lua new file mode 100644 index 000000000..2bc4e0371 --- /dev/null +++ b/doc/context/sources/general/manuals/onandon/m-fonts-plugins-timings-luajittex.lua @@ -0,0 +1,90 @@ +return { + ["engine"]="luajittex", + ["timings"]={ + ["arabic"]={ + ["list"]={ "arabtype", "husayni" }, + ["results"]={ + ["arabtype"]={ + ["context base"]=0.32, + ["context node"]=7.167, + ["context none"]=0.322, + ["harfbuzz native"]=4.631, + ["harfbuzz uniscribe"]=4.67, + }, + ["husayni"]={ + ["context base"]=0.35, + ["context node"]=12.251, + ["context none"]=0.351, + ["harfbuzz native"]=15.279, + ["harfbuzz uniscribe"]=15.253, + }, + }, + }, + ["latin"]={ + ["list"]={ "modern", "pagella", "dejavu", "cambria", "ebgaramond", "lucidaot" }, + ["results"]={ + ["cambria"]={ + ["context base"]=0.384, + ["context node"]=1.17, + ["context none"]=0.366, + ["harfbuzz native"]=2.907, + ["harfbuzz uniscribe"]=2.863, + }, + ["dejavu"]={ + ["context base"]=0.399, + ["context node"]=0.985, + ["context none"]=0.364, + ["harfbuzz native"]=3.02, + ["harfbuzz uniscribe"]=2.968, + }, + ["ebgaramond"]={ + ["context base"]=0.43, + ["context node"]=1.323, + ["context none"]=0.383, + ["harfbuzz native"]=2.999, + ["harfbuzz uniscribe"]=2.983, + }, + ["lucidaot"]={ + ["context base"]=0.414, + ["context node"]=0.626, + ["context none"]=0.422, + ["harfbuzz native"]=2.606, + ["harfbuzz uniscribe"]=2.594, + }, + ["modern"]={ + ["context base"]=0.418, + ["context node"]=0.773, + ["context none"]=0.383, + ["harfbuzz native"]=3.074, + ["harfbuzz uniscribe"]=3.049, + }, + ["pagella"]={ + ["context base"]=0.436, + ["context node"]=0.803, + ["context none"]=0.416, + ["harfbuzz native"]=3.024, + ["harfbuzz uniscribe"]=3.006, + }, + }, + }, + ["mixed"]={ + ["list"]={ "arabtype", "husayni" }, + ["results"]={ + ["arabtype"]={ + ["context base"]=0.572, + ["context node"]=4.039, + ["context none"]=0.602, + ["harfbuzz native"]=3.69, + ["harfbuzz uniscribe"]=3.686, + }, + ["husayni"]={ + ["context base"]=0.617, + ["context node"]=5.943, + ["context none"]=0.575, + ["harfbuzz native"]=7.193, + ["harfbuzz uniscribe"]=7.109, + }, + }, + }, + }, +}
\ No newline at end of file diff --git a/doc/context/sources/general/manuals/onandon/m-fonts-plugins-timings-luatex.lua b/doc/context/sources/general/manuals/onandon/m-fonts-plugins-timings-luatex.lua new file mode 100644 index 000000000..59606554d --- /dev/null +++ b/doc/context/sources/general/manuals/onandon/m-fonts-plugins-timings-luatex.lua @@ -0,0 +1,90 @@ +return { + ["engine"]="luatex", + ["timings"]={ + ["arabic"]={ + ["list"]={ "arabtype", "husayni" }, + ["results"]={ + ["arabtype"]={ + ["context base"]=0.416, + ["context node"]=15.168, + ["context none"]=0.412, + ["harfbuzz native"]=7.144, + ["harfbuzz uniscribe"]=7.679, + }, + ["husayni"]={ + ["context base"]=0.449, + ["context node"]=26.076, + ["context none"]=0.459, + ["harfbuzz native"]=10.498, + ["harfbuzz uniscribe"]=18.958, + }, + }, + }, + ["latin"]={ + ["list"]={ "modern", "pagella", "dejavu", "cambria", "ebgaramond", "lucidaot" }, + ["results"]={ + ["cambria"]={ + ["context base"]=0.444, + ["context node"]=2.114, + ["context none"]=0.426, + ["harfbuzz native"]=4.587, + ["harfbuzz uniscribe"]=5.026, + }, + ["dejavu"]={ + ["context base"]=0.464, + ["context node"]=1.676, + ["context none"]=0.426, + ["harfbuzz native"]=4.495, + ["harfbuzz uniscribe"]=4.792, + }, + ["ebgaramond"]={ + ["context base"]=0.497, + ["context node"]=2.356, + ["context none"]=0.433, + ["harfbuzz native"]=4.957, + ["harfbuzz uniscribe"]=5.169, + }, + ["lucidaot"]={ + ["context base"]=0.481, + ["context node"]=0.926, + ["context none"]=0.474, + ["harfbuzz native"]=4.28, + ["harfbuzz uniscribe"]=4.685, + }, + ["modern"]={ + ["context base"]=0.477, + ["context node"]=1.227, + ["context none"]=0.439, + ["harfbuzz native"]=5.057, + ["harfbuzz uniscribe"]=5.243, + }, + ["pagella"]={ + ["context base"]=0.502, + ["context node"]=1.273, + ["context none"]=0.469, + ["harfbuzz native"]=4.958, + ["harfbuzz uniscribe"]=5.489, + }, + }, + }, + ["mixed"]={ + ["list"]={ "arabtype", "husayni" }, + ["results"]={ + ["arabtype"]={ + ["context base"]=0.678, + ["context node"]=7.854, + ["context none"]=0.687, + ["harfbuzz native"]=5.822, + ["harfbuzz uniscribe"]=6.214, + }, + ["husayni"]={ + ["context base"]=0.724, + ["context node"]=11.922, + ["context none"]=0.674, + ["harfbuzz native"]=6.929, + ["harfbuzz uniscribe"]=9.851, + }, + }, + }, + }, +}
\ No newline at end of file diff --git a/doc/context/sources/general/manuals/onandon/onandon-decade.tex b/doc/context/sources/general/manuals/onandon/onandon-decade.tex new file mode 100644 index 000000000..890668a5c --- /dev/null +++ b/doc/context/sources/general/manuals/onandon/onandon-decade.tex @@ -0,0 +1,90 @@ +% language=uk + +\startcomponent onandon-decade + +\environment onandon-environment + +\startchapter[title=The first decade] + +When writing this it's hard to believe that we're already a decade working on +\LUATEX\ and about the same time on \MKIV. The question is, did we achieve the +objectives? The answer can easily be \quotation {yes} because we didn't start +with objectives, just with some experiments with a \LUA\ extension interface. +However, it quickly became clear that this was the way to go. Already in an early +stage we took a stand in what direction we had to move. + +How did we end up with \LUA\ and not one of the other popular scripting +languages? The \CONTEXT\ macro package always came with a runner. Not only did +the runner manage the (often) multiple runs, it also took care of sorting the +index and other inter|-|job activities. Additional helpers were written for +installing fonts, managing (and converting) images, job control, etc. First they +were binaries (written in \MODULA\ 2), but successive implementations used \PERL\ +and \RUBY. When I found out that the \SCITE\ editor I switched to had an +extension mechanism using \LUA, I immediately liked that language. It's clean, +not bloated, relatively stable, evolves in an academic environment and is not +driven by commerce and|/|or short term success, and above all, the syntax makes +the code look good. So, it was the most natural candidate for extending \TEX. + +Already for along time, \TEX\ is a stable program and whatever we do with it, we +should not break it. There has been frontend extensions, like \ETEX, and backend +extensions, like \PDFTEX, and experiments like \OMEGA\ and \ALEPH\ and we could +start from there. So, basically we took \PDFTEX, after all, that was what we used +for the first experiments, and merged some \ALEPH\ directional code in it. A +tremendous effort was undertaken (thanks to funding by the Oriental \TEX\ +project) to convert the code base from \PASCAL\ to~\CCODE. + +It is hard to get an agreement over what needs to be added and it's a real waste +of time to enter that route by endless discussions: every \TEX\ user has +different demands and macro packages differ in philosophy . So, in the spirit of +the extension language \LUA\ we stuck to concept of \quotation {If you want it +better, write it in \LUA}. As a consequence we had to provide access to the +internals with efficient and convenient methods, something that happened +stepwise. We did extend the engine with a few features that make live easier but +tried to limit ourselves. On the other hand, due to developments with fonts and +languages we generalized these concepts so that extending and controlling them is +easier. And, due to developments in math font technology we also added +alternative code paths to the math renderer. + +All these matters have been presented and discussed at meetings, in user group +journals and in documents that are part of the \CONTEXT\ suite. And during this +decade the \CONTEXT\ users have been patient testers of whatever we threw at them +in the \MKIV\ version of this macro package. + +It's kind of interesting to note that in the \TEX\ community it takes a while +before version 1 of programs becomes available. Some programs never (seem to) +reach that state. However, for us version 1.0 marks the moment that we consider +the interfaces to be stable. Of course we move on so a version 2.0 can divert and +provide more or even less interfaces, provide new functionality or drop obsolete +features. The intermediate versions (up to version one) were always quite useable +in production. In 2005 the first prototype of \LUATEX\ was demonstrated at the +\TUG\ conference, and in 2007 at the \TUG\ conference we had a whole day on +\LUATEX. At that time \CONTEXT\ \MKIV\ evolved fast and we already had decent +\OPENTYPE\ support as part of the oriental \TEX\ project. It was in those years +that the major reorganization of the code base took place but in successive years +many subsystems were opened and cleaned up. There were some occasions where an +interface was changed for the better but adapting was not that hard. It might +have helped that much of \CONTEXT\ \MKIV\ is written in \LUA. What also helped is +that most \CONTEXT\ users quickly switched to \MKIV, if only because \MKII\ was +frozen. And, thanks to those users, we were able to root out bugs and +bottlenecks. It was interesting to see that the approach of mixing \TEX, +\METAPOST\ and \LUA\ catched on quite well. + +By the end of September 2016, at the 10\high{th} \CONTEXT\ meeting we released +what we call the first long term stable version of \LUATEX. This version performs +quite well but we might still add a few things here and there and the code will be +further cleaned up and documented. In the meantime \LUATEX\ is also used in other +macro packages. It will not replace \PDFTEX\ (at least not soon) because that +engine does the job for most of the publications done in \TEX: articles. As they +are mostly in English and use traditional fonts, there is no need to switch to +the more flexible but somewhat slower \LUATEX. In a similar fashion \XETEX\ +serves those who want the benefits of \PDFTEX, hard|-|coded font support and +token juggling at the \TEX\ level. We will support those engines with \MKII\ but +as mentioned, we will not develop new code for. We strongly advice \CONTEXT\ users +to use \LUATEX\ but there the advertisements stop. Personally I haven't used +\PDFTEX\ (which made \TEX\ survive in the evolving world of electronic documents) +for a decade and I never really used \XETEX\ (which opened up the \TEX\ world to +modern fonts). At least for the coming decade I hope that \LUATEX\ can serve us well. + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/onandon/onandon-editing.tex b/doc/context/sources/general/manuals/onandon/onandon-editing.tex new file mode 100644 index 000000000..c8482397e --- /dev/null +++ b/doc/context/sources/general/manuals/onandon/onandon-editing.tex @@ -0,0 +1,393 @@ +% language=uk + +\startcomponent onandon-editing + +\environment onandon-environment + +\startchapter[title=Editing] + +\startsection[title=Introduction] + +% This introduction is similar to the workflows chapter. + +Some users like the synctex feature that is built in the \TEX\ engines. +Personally I never use it because it doesn't work well with the kind of documents +I maintain. If you have one document source, and don't shuffle around (reuse) +text too much it probably works out okay but that is not our practice. Here I +will describe how you can enable a more \CONTEXT\ specific synctex support so +that aware \PDF\ viewers can bring you back to the source. + +\stopsection + +\startsection[title={The premise}] + +Most of the time we provide our customers with an authoring workflow consisting +of: + +\startitemize[packed] + \startitem the typesetting engine \CONTEXT \stopitem + \startitem the styles to generate the desired \PDF\ files \stopitem + \startitem the text editor \SCITE \stopitem + \startitem the \SUMATRAPDF\ viewer \stopitem +\stopitemize + +For the \MATHML\ we advice the \MATHTYPE\ editor and we provide them with a +customized \MATHML\ translator for the copy & paste actions. When \ASCIIMATH\ is +used to code math no special tools are needed. + +What people operate this workflow? Sometimes it's an author, but most of the time +they are editors with a background in copy|-|editing. We call them \XML\ editors, +because they are maintaining the large (sets of) \XML\ documents and edit +directly in the \XML\ sources. + +Maybe you'll ask yourself \quotation {Can they do that? Can they edit directly in +the \XML\ resource?} The answer is yes, because after they have hit the +processing key they are rewarded with a publishable \PDF\ document in a demanding +layout. + +The \XML\ sources have a dual purpose. They form the basis for: + +\startitemize[packed] + \startitem + all folio products that are generated in \XML\ to \PDF\ workflow(s) + \stopitem + \startitem + the digital web product(s) + \stopitem +\stopitemize + +The \XML\ editors do their proofing chapter|-|wise. Sometimes a chapter is one +big \XML\ file (10.000 lines is no exception when the chapter contains hundreds +of bloated \MATHML\ snippets). In other projects they have to deal with chapters +that are made up of hundreds (100 upto 500) of smaller \XML\ files. + +\stopsection + +\startsection[title={The problem}] + +Let's keep it simple: there's a typo. Here's what an \XML\ editor will do: + +\startitemize[packed] + \startitem + start \SCITE + \stopitem + \startitem + open a file + \stopitem + \startitem + correct the typo + \stopitem + \startitem + generate the \PDF + \stopitem + \startitem + proof the \PDF\ and see if his alteration has some undesired side + effects like text flow of image floating + \stopitem +\stopitemize + +So far so good. When the editor dealing with one big \XML\ file there's no +problem. Hopefully the filename will indicate the specific chapter. He or she +opens the file and searches for the typo. And then correction happens. But what +if there are hundreds of small \XML\ files. How does the editor know in which +file the typo can be found? + +First, let's give a few statistics based on two projects that are in a revision +stage. + +\starttabulate[|c|c|c|c|] +\HL +\NC + project \NC + chapters \NC + \# of files \NC + average \# of lines \NC \NR +\HL +\NC + A \NC + 16 \NC + 16 \NC + 11000 \NC \NR +\NC + B \NC + 132 \NC + 16000\footnote{132 chapters consisting of $\pm 120$ files.} \NC + 100 \NC \NR +\HL +\stoptabulate + +The \XML\ resource passes three stages: a raw, a semi final and a final version. +The raw \XML\ version originates from a web authoring tool that is used by the +author. Then the \PDF\ is proofread and the \XML\ editor goes to work. + +\starttabulate[|l|c|c|] +\HL +\NC + workflow \NC + \# edit locations and adaptations \NC + \# runs\footnote {Maybe you can now see why we put quite some effort in + keeping \CONTEXT\ working at a comfortable speed.} \NC \NR +\HL +\NC + raw to semifinal \NC + 75 \NC + 105 \NC \NR +\NC + semifinal to final \NC + 35 \NC + 55 \NC \NR +\HL +\stoptabulate + +Keep in mind that altering text may cause text to flow and images to float in a +way that an \XML\ editor will have to finetune and needs multiple runs for one +correction. + +Just to give an idea of the work involved. A typical semi final needs some 50 +runs where each run takes 20 seconds (assuming 3 runs to get all cross +referencing right). The numbers of explicit pagebreaks is about 5, and (related +to formulas) explicit linebreaks around 8. It takes some 2 hours to get +everything right, which includes checking in detail, fixing some things and if +needed moving content a bit around. + +Now we broaden the earlier question into: how can we make the work of an \XML\ +editor as easy and efficient as possible? + +\stopsection + +\startsection[title={Enhancing efficiency}] + +Since it is easier to proof content for folio and web via PDF documents we +generate proof \PDF\ files in which the complete content is shown. The proof can +be a massive document. A normal 40 page chapter can explode to 140 pages +visualizing all the content that is coded in the \XML\ file(s). + +The content in the proof is shown in an effective way and a functional order. +Let's give a few examples of how we enhance the \XML\ editors effectiveness: + +\startitemize[packed] + +\startitem + By default the proof \PDF\ file is interactive which serves testing the tocs + and the register. +\stopitem +\startitem + The web hyperlinks are active so their destinatation can be tested. +\stopitem +\startitem + The questions and their answers are displayed in eachothers proximity. This + sounds logical but in folio they are two seperate products (theory and + answer books). +\stopitem +\startitem + Medium specific content (web or folio) is typographically highligthed. For + example by colored backgrounds. +\stopitem +\startitem + When spelling mode is on the \XML\ editor can easily pick out the colored + misspelled words. +\stopitem +\startitem + Images can be active areas although this is of no interest to \XML\ editors. + Clicking the image results in opening the image file in its corresponding + application for maintenance. +\stopitem +\startitem + For practical reasons the filenames and paths of the \XML\ files are + displayed. The filenames are active links and clicking them results in + opening the destination \XML\ file in \SCITE. +\stopitem +\stopitemize + +Okay. The last option is a nice feature. However, the destination file is opened +at the top of the file and you still have to find the typo or whatever +incorrect issue you are looking for. + +So a further enhancement in efficiency would be to jump to the typo's +corresponding line in the \XML\ source. This is where \SYNCTEX\ comes into view. +This feature, present in the \TEX\ engines, provides a way to go from \PDF\ to +source by using a secondary file with positions. Unfortunately that mechanism is +hardly useable for \CONTEXT\ because it assumes a page and file handling model +different from what we use. However, as \CONTEXT\ uses \LUATEX, it can also +provide it's own alternative. + +\stopsection + +% The rest is similar to the workflows chapter. + +\startsection[title=What we want] + +The \SYNCTEX\ method roughly works as follows. Internally \TEX\ constricts linked +lists of glyphs, kerns, glue, boxes, rules etc. These elements are called nodes. +Some nodes carry information about the file and line where they were created. In +the backend this information gets somehow translated in a (sort of) verbose tree +that describes the makeup in terms of boxes, glue and kerns. From that +information the \SYNCTEX\ parser library, hooked into a \PDF\ viewer, can go back +from a position on the screen to a line in a file. One would expect this to be a +relative simple rectangle based model, but as far as I can see it's way more +complex than that. There are some comments that \CONTEXT\ is not supported well +because it has a layered page model, which indicates that there are some +assumptions about how macro packages are supposed to work. Also the used +heuristics not only involve some specific spot (location) but also involve the +corners and edges. It is therefore not so much a (simple) generic system but a +mechanism geared for a macro package like \LATEX. + +Because we have a couple of users who need to edit complex sets of documents, +coded in \TEX\ or \XML, I decided to come up with a variant that doesn't use the +\SYNCTEX\ machinery but manipulates the few \SYNCTEX\ fields directly \footnote {This +is something that in my opinion should have been possible right from the start +but it's too late now to change the system and it would not be used beyond +\CONTEXT\ anyway.} and eventually outputs a straightforward file for the editor. +Of course we need to follow some rules so that the editor can deal with it. It +took a bit of trial and error to get the right information in the support file +needed by the viewer but we got there. + +The prerequisites of a decent \CONTEXT\ \quotation {click on preview and goto +editor} are the following: + +\startitemize + +\startitem + It only makes sense to click on text in the text flow. Headers and footers + are often generated from structure, and special typographic elements can + originate in macros hooked into commands instead of in the source. +\stopitem + +\startitem + Users should not be able to reach environments (styles) and other files + loaded from the (normally read|-|only) \TEX\ tree, like modules. We don't + want accidental changes in such files. +\stopitem + +\startitem + We not only have \TEX\ files but also \XML\ files and these can normally + flush in rather arbitrary ways. Although the concept of lines is sort of + lost in such a file, there is still a relation between lines and the snippets + that make out the content of an \XML\ node. +\stopitem + +\startitem + In the case of \XML\ files the overhead related to preserving line + numbers should be minimal and have no impact on loading and memory when + these features are not used. +\stopitem + +\startitem + The overhead in terms of an auxiliary file size and complexity as well + as producing that file should be minimal. It should be easy to turn on and + off these features. (I'd never turn them on by default.) +\stopitem + +\stopitemize + +It is unavoidable that we get more run time but I assume that for the average user +that is no big deal. It pays off when you have a workflow when a book (or even a +chapter in a book) is generated from hundreds of small \XML\ files. There is no +overhead when \SYNCTEX\ is not used. + +In \CONTEXT\ we don't use the built|-|in \SYNCTEX\ features, that is: we let +filename and line numbers be set but often these are overloaded explicitly. The +output file is not compressed and constructed by \CONTEXT. There is no benefit in +compression and the files are probably smaller than default \SYNCTEX\ anyway. + +\stopsection + +\startsection[title=Commands] + +Although you can enable this mechanism with directives it makes sense to do it +using the following command. + +\starttyping +\setupsynctex[state=start] +\stoptyping + +The advantage of using an explicit command instead of some command line option is +that in an editor it's easier to disable this trickery. Commenting that line will +speed up processing when needed. This command can also be given in an environment +(style). On the command line you can say + +\starttyping +context --synctex somefile.tex +\stoptyping + +A third method is to put this at the top of your file: + +\starttyping +% synctex=yes +\stoptyping + +Often an \XML\ files is very structured and although probably the main body of +text is flushed as a stream, specific elements can be flushed out of order. In +educational documents flushing for instance answers to exercises can happen out of +order. In that case we still need to make sure that we go to the right spot in +the file. It will never be 100\% perfect but it's better than nothing. The +above command will also enable \XML\ support. + +If you don't want a file to be accessed, you can block it: + +\starttyping +\blocksynctexfile[foo.tex] +\stoptyping + +Of course you need to configure the viewer to respond to the request for +editing. In Sumatra combined with SciTE the magic command is: + +\starttyping +c:\data\system\scite\wscite\scite.exe "%f" "-goto:%l" +\stoptyping + +Such a command is independent of the macro package so you can just consult the +manual or help info that comes with a viewer, given that it supports this linking +back to the source at all. + +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. Use + +\starttyping +\setupsynctex[state=start,method=min] +\stoptyping + +to get words clickable and + +\starttyping +\setupsynctex[state=start,method=max] +\stoptyping + +if you want somewhat more efficient ranges. The overhead for \type {min} is about +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: + +\starttyping +\enabletrackers[system.synctex.visualize] +\enabletrackers[system.synctex.visualize=real] +\stoptyping + +The following tracker outputs some status information about \XML\ flushing. Such +trackers only make sense for developers. + +\starttyping +\enabletrackers[system.synctex.xml] +\stoptyping + +\stopsection + +\startsection[title=Warning] + +Don't turn on this feature when you don't need it. This is one of those mechanism +that hits performance badly. + +Depending on needs the functionality can be improved and|/|or extended. Of course +you can always use the traditional \SYNCTEX\ method but don't expect it to behave +as described here. + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/onandon/onandon-emoji.tex b/doc/context/sources/general/manuals/onandon/onandon-emoji.tex new file mode 100644 index 000000000..1f67cc528 --- /dev/null +++ b/doc/context/sources/general/manuals/onandon/onandon-emoji.tex @@ -0,0 +1,457 @@ +% language=uk + +\usemodule[fonts-emoji] + +\environment onandon-environment + +% \definefont[MyEmoji][emojionecolor-svginot*default,svg] +% \definefont[MyEmoji][seguiemj*seguiemj-bw] +% \definefont[MyEmoji][emojionemozilla*default,overlay] +% \definefont[MyEmoji][applecoloremoji*default,bitmap] + +\definefontfeature[seguiemj-cl][default][colr=yes,ccmp=yes,dist=yes] +\definefontfeature[seguiemj-bw][default][ccmp=yes,dist=yes] + +\definefont[MyEmoji] [seguiemj*seguiemj-cl] +\definefont[MyEmojiLarge][seguiemj*seguiemj-cl @ 100pt] + +\definefontsynonym[emoji][seguiemj*seguiemj-cl] + +\startcomponent onandon-emoji + +\startchapter[title=Emoji again] + +Because at the \CONTEXT\ 2016 meeting color fonts \footnote {For that occasion +the cowfont, a practical joke concerning Dutch \quote {koeieletters}, were turned +into a color font and presented at the meeting.} were on the agenda, some time +was spent on emoji (these colorful small picture glyphs). When possible I bring +kids to the Bacho\TEX\ conference so for the 2017 BachoTUG I decided to do +something with emoji that, after all, are mostly used by those younger than I am. +So, I had to take a look at the current state. Here are some observations. + +The \UNICODE\ standard defines a whole lot of emoji and if mankind manages to +survive for a while one can assume that a lot more will be added. After all, +icons as well as variants keep evolving. There are several ways to organize these +symbols in groups but I will not give grouping a try. Just visit \type +{emojipedia.org} and you get served well. For this story I only mention that: + +\startitemize + \startitem + There are quite some shapes and nearly all of them are in color. The + yellow ones, smilies and such, are quite prominently present but there + are many more. + \stopitem + \startitem + A special subset is fulled by persons: man, woman, girl, boy and recently + a baby. + \stopitem + \startitem + The grown ups can be combined in loving couples (either or not kissing) + and then can form families, but only upto 2 young kids or gender neutral + babies. + \stopitem + \startitem + All persons can be flagged with one of five skin tones so that not all + persons (or heads) look bright yellow. + \stopitem + \startitem + Interesting is that girls and boys are still fond of magenta (pinkish) + and cyan (blueish) cloths and ornaments. Also haircuts are rather + specific to the gender. + \stopitem +\stopitemize + +For rendering color emojis we have a few color related \OPENTYPE\ font properties +available: bitmaps, \SVG\, and stacked glyphs. Now, if you think of the +combinations that can be made with skin tones, you realize that fonts can become +pretty large if each combination results in a glyph. In the first half of 2017 +\MICROSOFT\ released an update for its emoji font and the company took the +challenge to provide not only mixed skin tone couples, but also supported skin +tones for the kids, including a baby. + +This recent addition already adds over 25.000 additional glyphs \footnote {That +is the amount I counted when I added all combinations runtime but the emojipedia +mentions twice that amount. Currently in \CONTEXT\ we resolve such combinations +when requested.} so imagine what will happen in the future. But, instead of +making a picture for each variant, a different solution has been chosen. For +coloring this seguiemj font uses the (very flexible) stacking technology: a color +shape is an overlay of colored symbols. The colors are organized in pallets and +it's no big deal to add additional pallets if needed. Instead of adding +pre|-|composed shapes (as is needed with bitmaps and \SVG) snippets are used to +build alternative glyphs and these can be combined into new shapes by +substitution and positioning (for that kerns, mark anchoring and distance +compensation is used). + +So, a family can be constructed of composed shapes (man, woman, etc) that each +are composed of snippets (skull, hair, mouth, eyes). So, effectively a family of +four is a bunch of maybe 25 small glyphs overlayed and colored. In \in {figure} +[fig:emojisnippets] we see how a shape is constructed out of separate glyphs. \in +{Figure} [fig:emojisnippetsoverlay] shows how they can be overlayed with colors +(we use a dedicated color set). + +\startplacefigure[title={Emoji snippets.},reference=fig:emojisnippets] + \scale[width=\textwidth]{\framed[frame=off,offset=overlay,align=normal]\bgroup + \forgetall + \MyEmoji + \ShowEmojiSnippets + [family man light skin tone + woman dark skin tone + girl medium skin tone + boy medium skin tone] + \egroup} +\stopplacefigure + +\startplacefigure[title={Emoji snippets overlayed.},reference=fig:emojisnippetsoverlay] + \scale[width=\textwidth]{\framed[frame=off,offset=overlay,align=normal]\bgroup + \forgetall + \MyEmoji + \ShowEmojiSnippetsOverlay + [family man light skin tone + woman dark skin tone + girl medium skin tone + boy medium skin tone] + \egroup} +\stopplacefigure + +When a font supports it, a sequence of emoji can be turned into a more compact +representation. In \in {figure} [fig:emojiskintones] we see how skin tones are +applied in such combinations. \in {Figure} [fig:emojiglyphs] shows the small +snippets. + +\startplacefigure[title={Emoji families and such with skin tones.},reference=fig:emojiskintones,location=page] + \startcombination[2*4] + {\ruledhbox{\MyEmojiLarge\resolvedemoji + {family man woman girl boy}}} + {family man woman girl boy} + {\ruledhbox{\MyEmojiLarge\resolvedemoji + {family woman girl boy}}} + {family woman girl boy} + {\ruledhbox{\MyEmojiLarge\resolvedemoji + {family woman woman girl boy}}} + {family woman woman girl boy} + {\ruledhbox{\MyEmojiLarge\resolvedemoji + {family man girl boy}}} + {family man girl boy} + {\ruledhbox{\MyEmojiLarge\resolvedemoji + {family + man dark skin tone + woman girl baby}}} + {family + man dark skin tone + woman girl baby} + {\ruledhbox{\MyEmojiLarge\resolvedemoji + {family + man light skin tone + woman light skin tone + girl dark skin tone}}} + {family + man light skin tone + woman light skin tone + girl dark skin tone} + {\ruledhbox{\MyEmojiLarge\resolvedemoji + {family woman girl boy}}} + {family woman girl boy} + {\ruledhbox{\MyEmojiLarge\resolvedemoji + {family + man light skin tone + woman dark skin tone + girl medium skin tone + boy medium skin tone}}} + {family + man light skin tone + woman dark skin tone + girl medium skin tone + boy medium skin tone} + \stopcombination +\stopplacefigure + +\startplacefigure[title={Emoji glyphs.},reference=fig:emojiglyphs] + \scale[width=\textwidth]{\framed[frame=off,offset=overlay,align=normal]\bgroup + \forgetall + \MyEmoji + \ShowEmojiGlyphs + [family man light skin tone + woman dark skin tone + girl medium skin tone + boy medium skin tone] + \egroup} +\stopplacefigure + +When we have to choose a font we need to take the following criteria into +account: + +\startitemize +\startitem + What is the quality of the shapes? For sure, outlines are best if you want to + scale too. +\stopitem +\startitem + How efficient is a shape constructed. In that respect a bitmap or \SVG\ image + is just one entity. +\stopitem +\startitem + How well can (semi) arbitrary combinations of emoji be provided. Here the + glyph approach wins. +\stopitem +\startitem + Are all skin colors for all human relates shapes supported? Actually it opens + the possibility for racist fonts. +\stopitem +\startitem + Are all reasonable combinations of persons supported? It looks like (depending + on time and version) kissing men or women can be missing, maybe because of + social political reasons. +\stopitem +\startitem + Are black and white shapes provided alongside color shapes. +\stopitem +\stopitemize + +Maybe an \SVG\ or bitmap image can have a lot of detail compared to a stacked +glyph but, when we're just using pictographic representations, the later is the +best choice. + +When I was playing a bit with the skin tone variants and other combinations that +should result in some composed shape, I used the \UNICODE\ test files but I got +the impression that there are some errors in the test suite, for instance with +respect to modifiers. Maybe the fonts are just doing the wrong thing or maybe +some implement these sequences a bit inconsistent. This will probably improve +over time but the question is if we should intercept issues. I'm not in favour of +this because it adds more and more fuzzy code that not only wastes cycles +(energy) but is also a conceptual horror. So, when testing, imperfection has to +be accepted for now. This is no big deal as until now no one ever asked for emoji +support in \CONTEXT. + +When no combined shape is provided, the original sequence shows up. A side effect +can be that zero|-|width|-| joiners and modifiers become visible. This depends on +the fonts. Users probably don't care that much about it. Now how do we suppose +that users enter these emoji (sequences) in a document source? One can imagine a +pop up in the editor but \TEX ies are often using commands for special cases. + +We already showed some combined shapes. The reader might appreciate the outcome +but getting there from the input takes a bit of work. For instance a two person +\typ {man light skin tone woman medium skin tone girl medium-light skin tone baby +medium-light skin tone} involves this: + +\blank +\start + \setupalign[verytolerant] + \showotfcomposition + {seguiemj*seguiemj-cl} + {1} + {\resolvedemoji{family + man light skin tone + woman medium skin tone + girl medium-light skin tone + baby medium-light skin tone}} +\stop +\blank + +A black and white example is the following \type {family woman girl}: + +\blank +\start + \setupalign[verytolerant] + \showotfcomposition + {seguiemj*seguiemj-bw} + {1} + {\resolvedemoji{family woman girl}} +\stop +\blank + +I will not show all emoji, just the subset that contains the word \type {woman} +in the description. As you can see the persons in the sequences are separated by +a zero|-|width|-|joiner. There are some curious ones, for instance a \typ {woman +wearing turban} which in terms of \UNICODE\ input is a female combine with a +turban wearing man becomes a beardless woman wearing a turban. Woman vampires and +zombies are not supported so these are male properties. + +\startpacked + \MyEmoji + \ShowEmoji[woman] +\stoppacked + +So what if you don't like these colors? Because we're dealing with \TEX\ you can +assume that if there is some way around the fixed color sets, then it will be +provided. So, when you use \CONTEXT, here is away to overload them: + +\startbuffer +\definecolor[emoji-red] [r=.4] +\definecolor[emoji-green] [g=.4] +\definecolor[emoji-blue] [b=.4] +\definecolor[emoji-yellow][r=.4,g=.4] +\definecolor[emoji-gray] [s=1,t=.5,a=1] + +\definefontcolorpalette + [emoji-s] + [black,emoji-gray] + +\definefontcolorpalette + [emoji-r] + [emoji-red,emoji-gray] + +\definefontcolorpalette + [emoji-g] + [emoji-green,emoji-gray] + +\definefontcolorpalette + [emoji-b] + [emoji-blue,emoji-gray] + +\definefontcolorpalette + [emoji-y] + [emoji-yellow,emoji-gray] + +\definefontfeature[seguiemj-s][ccmp=yes,dist=yes,colr=emoji-s] +\definefontfeature[seguiemj-r][ccmp=yes,dist=yes,colr=emoji-r] +\definefontfeature[seguiemj-g][ccmp=yes,dist=yes,colr=emoji-g] +\definefontfeature[seguiemj-b][ccmp=yes,dist=yes,colr=emoji-b] +\definefontfeature[seguiemj-y][ccmp=yes,dist=yes,colr=emoji-y] + +\definefont[MyEmojiS][seguiemj*seguiemj-s] +\definefont[MyEmojiR][seguiemj*seguiemj-r] +\definefont[MyEmojiG][seguiemj*seguiemj-g] +\definefont[MyEmojiB][seguiemj*seguiemj-b] +\definefont[MyEmojiY][seguiemj*seguiemj-y] +\stopbuffer + +\typebuffer \getbuffer + +\startplacefigure[title={Overloading colors by plugging in a sequence of alternate colors.},reference=fig:emojioverload,location=page] +\startcombination[4*6] + {\scale[height=.1\textheight]{\MyEmoji \resolvedemoji{triangular ruler}}} {} + {\scale[height=.1\textheight]{\MyEmoji \resolvedemoji{rabbit face}}} {} + {\scale[height=.1\textheight]{\MyEmoji \resolvedemoji{man}}} {} + {\scale[height=.1\textheight]{\MyEmoji \resolvedemoji{woman}}} {} + {\scale[height=.1\textheight]{\MyEmojiR\resolvedemoji{triangular ruler}}} {} + {\scale[height=.1\textheight]{\MyEmojiR\resolvedemoji{rabbit face}}} {} + {\scale[height=.1\textheight]{\MyEmojiR\resolvedemoji{man}}} {} + {\scale[height=.1\textheight]{\MyEmojiR\resolvedemoji{woman}}} {} + {\scale[height=.1\textheight]{\MyEmojiG\resolvedemoji{triangular ruler}}} {} + {\scale[height=.1\textheight]{\MyEmojiG\resolvedemoji{rabbit face}}} {} + {\scale[height=.1\textheight]{\MyEmojiG\resolvedemoji{man}}} {} + {\scale[height=.1\textheight]{\MyEmojiG\resolvedemoji{woman}}} {} + {\scale[height=.1\textheight]{\MyEmojiB\resolvedemoji{triangular ruler}}} {} + {\scale[height=.1\textheight]{\MyEmojiB\resolvedemoji{rabbit face}}} {} + {\scale[height=.1\textheight]{\MyEmojiB\resolvedemoji{man}}} {} + {\scale[height=.1\textheight]{\MyEmojiB\resolvedemoji{woman}}} {} + {\scale[height=.1\textheight]{\MyEmojiY\resolvedemoji{triangular ruler}}} {} + {\scale[height=.1\textheight]{\MyEmojiY\resolvedemoji{rabbit face}}} {} + {\scale[height=.1\textheight]{\MyEmojiY\resolvedemoji{man}}} {} + {\scale[height=.1\textheight]{\MyEmojiY\resolvedemoji{woman}}} {} + {\scale[height=.1\textheight]{\MyEmojiS\resolvedemoji{triangular ruler}}} {} + {\scale[height=.1\textheight]{\MyEmojiS\resolvedemoji{rabbit face}}} {} + {\scale[height=.1\textheight]{\MyEmojiS\resolvedemoji{man}}} {} + {\scale[height=.1\textheight]{\MyEmojiS\resolvedemoji{woman}}} {} +\stopcombination +\vskip2ex % looks nicer +\stopplacefigure + +In \in {figure} [fig:emojioverload] we see how this is applied. You can provide +as many colors as needed but when you don't provide enough the last one is used. +This way we get the overlayed transparent colors in the examples. By using +transparency we don't obscure shapes. + +The emojipedia mentions \quotation {Asked about the design, \MICROSOFT\ told +emojipedia that one of the reasons for the thick stroke was to allow each emoji +to be easily read on any background color.} The first glyph in the stack seems to +do the trick, so just make sure that it doesn't become white. And, before I read +that remark, while preparing a presentation with a colored background, I had +already noticed that using a background was no problem. This font definitely sets +the standard. + +How do we know what colors are used? The next table shows the first color palette +of seguiemj. There are quite some colors so defining your own definitely involved +some studying. + +{\MyEmoji\ShowEmojiPalettes[1]} + +Normally special symbols are accessed in \CONTEXT\ with the \type {symbol} +command where symbols are organized in symbol sets. This is a rather old +mechanism and dates from the time that fonts were limited in coverage and symbols +were collected in special fonts. The emoji are accessed by their own command: +\type {\emoji}. The font used has the font synonym \type {emoji} so you need to +set that one first: + +\starttyping +\definefontsynonym[emoji][seguiemj*seguiemj-cl] +\stoptyping + +Here is an example: + +\startbuffer +\emoji{woman light skin tone}\quad +\emoji{woman scientist}\quad +{\bfd bigger \emoji{man health worker}} +\stopbuffer + +\typebuffer + +or typeset: \getbuffer + +The emoji symbol scales with the normal running font. When you ask for a family +with skin toned members the lookup can result in another match (or no match) +because one never knows to what extend a font supports it. + +\starttabulate[|l|p|] +\NC \type{\expandedemoji} \NC the sequence constructed from the given string \NC \NR +\NC \type{\resolvedemoji} \NC a protected sequence constructed from the given string \NC \NR +\NC \type{\checkedemoji } \NC an typeset sequence with unresolved modifiers and joiners removed \NC \NR +\NC \type{\emoji} \NC a typeset resolved sequence using the \type {emoji} font synonym \NC \NR +\NC \type{\robustemoji} \NC a typeset checked sequence using the \type {emoji} font synonym \NC \NR +\stoptabulate + +In case you wonder how some of the details above were typeset, there is a module +\type {fonts-emoji} that provides some helpers for introspection. + +\starttabulate[|l|p|] +\NC \type {\ShowEmoji} \NC show all the emoji in the current font \NC \NR +\NC \type {\ShowEmojiSnippets} \NC show the snippets of a given emoji \NC \NR +\NC \type {\ShowEmojiSnippetsOverlay} \NC show the overlayed snippets of a given emoji \NC \NR +\NC \type {\ShowEmojiGlyphs} \NC show the snippets of a typeset emoji \NC \NR +\NC \type {\ShowEmojiPalettes} \NC show the color pallets in the current font \NC \NR +\stoptabulate + +Examples of usage are: + +\starttyping +\ShowEmojiSnippets[family man woman girl boy] +\ShowEmojiGlyphs [family man woman baby girl] +\ShowEmoji [^man] +\ShowEmoji +\ShowEmojiPalettes +\ShowEmojiPalettes[1] +\stoptyping + +A good source of information about emoji is the mentioned \type {emojipedia.org} +website. There you find not only details about all these symbols but also has +some history. It compares updates in fonts too. It mentions for instance that in +the creative update of Windows 10, some persons grew beards in the seguiemj font +and others lost an eye. Now, if you look at the snippets shown before, you can +wonder if that eye is really gone. Maybe the color is wrong or the order of +stacking is not right. I decided not to waste time looking into that. + +Another quote: \quotation {Support for color emoji presentation on \MSWINDOWS\ is +limited. Many applications on \MSWINDOWS\ display emojis with a black and white +text presentation instead of their color version.} Well, we can do better with +\TEX, but as usual not that many people really cares about that. But it's fun +anyway. + +We end with a warning. When you use \quote {ligatures} like this, you really need +to check the outcome. For instance, when \MICROSOFT\ updated the font end 2017, +same gender couples got different hair style for the individuals so that one can +still distinguish them. However, kissing couples and couples in love (indicated +by a heart) seem to be removed. Who knows how and when politics creep into fonts: +is public mixed couple kissing permitted, do we support families with any mix of +gender, is associating pink with girls okay or not, how do we distinguish male +and female anyway? In \in {figure} [fig:old-and-new] we see the same combination +twice, the early 2017 rendering versus the late 2017 rendering. Can you notice +the differences? + +\startplacefigure[title={Incompatible updates.},reference=fig:old-and-new] + \externalfigure[onandon-seguiemj.pdf][width=\textwidth] +\stopplacefigure + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/onandon/onandon-ffi.tex b/doc/context/sources/general/manuals/onandon/onandon-ffi.tex new file mode 100644 index 000000000..01c1bb4c5 --- /dev/null +++ b/doc/context/sources/general/manuals/onandon/onandon-ffi.tex @@ -0,0 +1,554 @@ +% language=uk + +\startcomponent onandon-ffi + +\environment onandon-environment + +\startchapter[title={Plug mode, an application of ffi}] + +A while ago, at an NTG meeting, Kai Eigner and Ivo Geradts demonstrated how to +use the Harfbuzz (hb) library for processing \OPENTYPE\ fonts. The main +motivation for them playing with that was that it provides a way to compare the +\LUA\ based font machinery with other methods. They also assumed that it would +give a better performance for complex fonts and|/|or scripts. + +One of the guiding principles of \LUATEX\ development is that we don't provide +hard coded solutions. For that reason we opened up the internals so that one can +provide solutions written in pure \LUA, but, of course, one can cooperate with +libraries via \LUA\ code as well. Hard coding solutions makes no sense as there +are often several solutions possible, depending on one's need. Although +development is closely related to \CONTEXT, the development of the \LUATEX\ +engine is generic. We try to be macro package agnostic. Already in an early stage +we made sure that the \CONTEXT\ font handler could be used in other packages as +well, but one can easily dream up light weight variants for specific purposes. +The standard \TEX\ font handling was kept and is called \type {base} mode in +\CONTEXT. The \LUA\ variant is tagged \type {node} mode because it operates on +the node list. Later we will refer to these modes. + +With the output of \XETEX\ for comparison, the first motive mentioned for looking +into support for such a library is not that strong. And when we want to test +against the standard, we can use MS-Word. A minimal \CONTEXT\ \MKIV\ installation +one only has the \LUATEX\ engine. Maintaining several renderers simultaneously +might give rise to unwanted dependencies. + +The second motive could be more valid for users because, for complex fonts, there +is|=|or at least was|=|a performance hit with the \LUA\ variant. Some fonts use +many lookup steps or are inefficient even in using their own features. It must be +said that till now I haven't heard \CONTEXT\ users complain about speed. In fact, +the font handling became many times faster the last few years, and probably no +one even noticed. Also, when using alternatives to the built in methods, in the +end, you will loose functionality and|/|or interactions with other mechanisms +that are built into the current font system. Any possible gain in speed is lost, +or even becomes negative, when a user wants to use additional functionality that +requires additional processing. \footnote {In general we try to stay away from +libraries. For instance, graphics can be manipulated with external programs, and +caching the result is much more efficient than recreating it. Apart from \SQL\ +support, where integration makes sense, I never felt the need for libraries. And +even \SQL\ can efficiently be dealt with via intermediate files.} + +Just kicking in some alternative machinery is not the whole story. We still need +to deal with the way \TEX\ sees text, and that, in practice, is as a sequence of +glyph nodes|=|mixed with discretionaries for languages that hyphenate, glue, +kern, boxes, math, and more. It's the discretionary part that makes it a bit +complex. In contextual analysis as well as positioning one needs to process up to +three additional cases: the pre, post and replace texts|=|either or not linked +backward and forward. And as applied features accumulate one ends up winding and +unwinding these snippets. In the process one also needs to keep an eye on spaces +as they can be involved in lookups. Also, when injecting or removing glyphs one +needs to deal with attributes associated with nodes. Of course something hard +codes in the engine might help a little, but then one ends up with the situation +where macro packages have different demands (and possible interactions) and no +solution is the right one. Using \LUA\ as glue is a way to avoid that problem. In +fact, once we go along that route, it starts making sense to come up with a +stripped down \LUATEX\ that might suit \CONTEXT\ better, but it's not a route we +are eager to follow right now. + +Kai and Ivo are plain \TEX\ users so they use a font definition and switching +environment that is quite different from \CONTEXT. In an average \CONTEXT\ run +the time spent on font processing is measurable but not the main bottleneck +because other time consuming things happen. Sometimes the load on the font +subsystem can be higher because we provide additional features normally not found +in \OPENTYPE. Add to that a more dynamic font model and it will be clear that +comparing performance between situations that use different macro packages is not +that trivial (or relevant). + +More reasons why we follow a \LUA\ route are that we: support (run time +generated) virtual fonts, are able to kick in additional features, can let the +font mechanism cooperate with other functionality, and so on. In the upcoming +years more trickery will be provided in the current mechanisms. Because we had to +figure out a lot of these \OPENTYPE\ things a decade ago when standards were +fuzzy quite some tracing and visualization is available. Below we will see some +timings, It's important to keep in mind that in \CONTEXT\ the \OPENTYPE\ font +handler can do a bit more if requested to do so, which comes with a bit of +overhead when the handler is used in \CONTEXT|=|something we can live with. + +Some time after Kai's presentation he produced an article, and that was the +moment I looked into the code and tried to replicate his experiments. Because +we're talking libraries, one can understand that this is not entirely trivial, +especially because I'm on another platform than he is|=|Windows instead of OSX. +The first thing that I did was rewrite the code that glues the library to \TEX\ +in a way that is more suitable for \CONTEXT. Mixing with existing modes (\type +{base} or \type {node} mode) makes no sense and is asking for unwanted +interferences, so instead a new \type {plug} mode was introduced. A sort of +general text filtering mechanism was derived from the original code so that we +can plug in whatever we want. After all, stability is not the strongest point of +today's software development, so when we depend on a library, we need to be +prepared for other (library based) solutions|=|for instance, if I understood +correctly, \XETEX\ switched a few times. + +After redoing the code the next step was to get the library running and I decided +that the \type {ffi} route made most sense. \footnote {One can think of a +intermediate layer but I'm pretty sure that I have different demands than others, +but \type {ffi} sort of frees us from endless discussions.} Due to some expected +functions not being supported, my efforts in using the library failed. At that +time I thought it was a matter of interfacing, but I could get around it by +piping into the command line tools that come with the library, and that was good +enough for testing. Of course it was dead slow, but the main objective was +comparison of rendering so it doesn't matter that much. After that I just quit +and moved on to something else. + +At some point Kai's article came close to publishing, and I tried the old code +again, and, surprise, after some messing around, the library worked. On my system +the one shipped with Inkscape is used, which is okay as it frees me from bothering +about installations. As already mentioned, we have no real reason in \CONTEXT\ +for using fonts libraries, but the interesting part was that it permitted me to +play with this so called \type {ffi}. At that moment it was only available in +\LUAJITTEX\. Because that creates a nasty dependency, after a while, Luigi +Scarso and I managed to get a similar library working in stock \LUATEX\, which is +of course the reference. So, I decided to give it a second try, and in the process +I rewrote the interfacing code. After all, there is no reason not to be nice for +libraries and optimize the interface where possible. + +Now, after a decade of writing \LUA\ code, I dare to claim that I know a bit +about how to write relatively fast code. I was surprised to see that where Kai +claimed that the library was faster than the \LUA\ code.I saw that it really +depends on the font. Sometimes the library approach is actually slower, which is +not what one expects. But remember that one argument for using a library is for +complex fonts and scripts. So what is meant with complex? + +Most Latin fonts are not complex|=|ligatures and kerns and maybe a little bit of +contextual analysis. Here the \LUA\ variant is the clear winner. It runs upto ten +times faster. For more complex Latin fonts, like EBgaramond, that resolves +ligatures in a different way, the library catches up, but still the \LUA\ handler +is faster. Keep in mind that we need to juggle discretionary nodes in any case. +One difference between both methods is that the \LUA\ handler runs over all the +lists (although it has to jump over fonts not being processed then), while the +library gets snippets. However, tests show that the overhead involved in that is +close to zero and can be neglected. Already long ago we saw that when we compared +\MKIV\ \LUATEX\ and \MKII\ \XETEX, the \LUA\ based font handler is not that slow +at all. This makes sense because the problem doesn't change, and maybe more +importantly because \LUA\ is a pretty fast language. If one or the other approach +is less that two times faster the gain will probably go unnoticed in real runs. +In my experience a few bad choices in macro or style writing is more harmful than +a bit slower font machinery. Kick in some additional node processing and it might +make comparison of a run even harder. By the way, one reason why font handling +has been sped up over the years is because our workflows sometimes have a high +load, and, for instance, processing a set of 5 documents remotely has to be fast. +Also, in an edit workflow you want the runtime to be a bit comfortable. + +Contrary to Latin, a pure Arabic text (normally) has no discretionary nodes, and +the library profits most of this. Some day I have to pick up the thread with +Idris about the potential use of discretionary nodes in Arabic typesetting. +Contrary to Arabic, Latin text has not many replacements and positioning, and, +therefore, the \LUA\ variant gets the advantage. Some of the additional features +that the \LUA\ variant provides can, of course, be provided for the library +variant by adding some pre- and postprocessing of the list, but then you quickly +loose any gain a library provides. So, Arabic has less complex node lists with no +branches into discretinaries, but it definitely has more replacements, +positioning and contextual lookups due to the many calls to helpers in the \LUA\ +code. Here the library should win because it can (I assume) use more optimized +datastructures. + +In Kai's prototype there are some cheats for right|-|to|-|left rendering and +special scripts like Devanagari. As these tweaks mostly involve discretionary +nodes; there is no real need for them. When we don't hyphenate no time is wasted +anyway. I didn't test Devanagari, but there is some preprocessing needed in the +\LUA\ variant (provided by Kai and Ivo) that I might rewrite from scratch once I +understand what happens there. But still, I expect the library to perform +somewhat better there but I didn't test it. Eventually I might add support for +some more scripts that demand special treatments, but so far there has not been +any request for it. + +So what is the processing speed of non|-|Latin scripts? An experiment with Arabic +using the frequently used Arabtype font showed that the library performs faster, +but when we use a mixed Latin and Arabic document the differences become less +significant. On pure Latin documents the \LUA\ variant will probably win. On pure +Arabic the library might be on top. On average there is little difference in +processing speed between the \LUA\ and library engines when processing mixed +documents. The main question is, does one want to loose functionality provided by +the \LUA\ variant? Of course one can depend on functionality provided by the +library but not by the \LUA\ variant. In the end the user decides. + +How did we measure? The baseline measurement is the so called \type {none} mode: +nothing is done there. It's fast but still takes a bit of time as it is triggered +by a general mode identifying pass. That pass determines what font processing +modes are needed for a list. \type {Base} mode only makes sense for Latin and has +some limitations. It's fast and, basically, its run time can be neglected. That's +why, for instance, \PDFTEX\ is faster than the other engines, but it doesn't do +\UNICODE\ well. \type {Node} mode is the fancy name for the \LUA\ font handler. +So, in order of increasing run time we have: \type {none}, \type {base} and \type +{node}. If we compare \type{node} mode with \type {plug} mode (in our case using +the hb library), we can subtract \type {none} mode. This gives a cleaner (more +distinctive) comparison but not a real honest one because the identifying pass +always happens. + +We also tested with and without hyphenation, but in practice that makes no sense. +Only verbatim is typeset that way, and normally we typeset that in \type {none} +mode anyway. On the other hand mixing fonts does happen. All the tests start with +forced garbage collection in order to get rid of that variance. We also pack into +horizontal boxes so that the par builder (with all kind of associated callbacks) +doesn't kick in, although the \type {node} mode should compensate that. + +Keep in mind that the tests are somewhat dumb. There is no overhead in handling +structure, building pages, adding color or whatever. I never process raw text. As +a reference it's no problem to let \CONTEXT\ process hundreds of pages per +second. In practice a moderate complex document like the metafun manual does some +20 pages per second. In other words, only a fraction of the time is spent on +fonts. The timings for \LUATEX\ are as follows: + +\usemodule[m-fonts-plugins] + +\startluacode + local process = moduledata.plugins.processlist + local data = table.load("m-fonts-plugins-timings-luatex.lua") + or table.load("t:/sources/m-fonts-plugins-timings-luatex.lua") + + context.testpage { 6 } + context.subsubject("luatex latin") + process(data.timings.latin) + context.testpage { 6 } + context.subsubject("luatex arabic") + process(data.timings.arabic) + context.testpage { 6 } + context.subsubject("luatex mixed") + process(data.timings.mixed) +\stopluacode + +The timings for \LUAJITTEX\ are, of course, overall better. This is because the +virtual machine is faster, but at the cost of some limitations. We seldom run +into these limitations, but fonts with large tables can't be cached unless we +rewrite some code and sacrifice clean solutions. Instead, we perform a runtime +conversion which is not that noticeable when it's just a few fonts. The numbers +below are not influenced by this as the test stays away from these rare cases. + +\startluacode + local process = moduledata.plugins.processlist + local data = table.load("m-fonts-plugins-timings-luajittex.lua") + or table.load("t:/sources/m-fonts-plugins-timings-luajittex.lua") + + context.testpage { 6 } + context.subsubject("luajittex latin") + process(data.timings.latin) + context.testpage { 6 } + context.subsubject("luajittex arabic") + process(data.timings.arabic) + context.testpage { 6 } + context.subsubject("luajittex mixed") + process(data.timings.mixed) +\stopluacode + +A few side notes. Since a library is an abstraction, one has to live with what +one gets. In my case that was a crash in \UTF-32 mode. I could get around it, but +one advantage of using \LUA\ is that it's hard to crash|=|if only because as a +scripting language it manages its memory well without user interference. My +policy with libraries is just to wait till things get fixed and not bother with +the why and how of the internals. + +Although \CONTEXT\ will officially support the \type {plug} model, it will not be +actively used by me, or in documentation, so for support users are on their own. +I didn't test the \type {plug} mode in real documents. Most documents that I +process are Latin (or a mix), and redefining feature sets or adapting styles for +testing makes no sense. So, can one just switch engines without looking at the +way a font is defined? The answer is|=|not really, because (even without the user +knowing about it) virtual fonts might be used, additional features kicked in and +other mechanisms can make assumptions about how fonts are dealt with too. + +The useability of \type {plug} mode probably depends on the workflow one has. We +use \CONTEXT\ in a few very specific workflows where, interestingly, we only use a +small subset of its functionality. Most of which is driven by users, and tweaking +fonts is popular and has resulted in all kind of mechanisms. So, for us it's +unlikely that we will use it. If you process (in bursts) many documents in +succession, each demanding a few runs, you don't want to sacrifice speed. + +Of course timing can (and likely will) be different for plain \TEX\ and \LATEX\ +usage. It depends on how mechanisms are hooked into the callbacks, what extra +work is done or not done compared to \CONTEXT. This means that my timings for +\CONTEXT\ for sure will differ from those of other packages. Timings are a +snapshot anyway. And as said, font processing is just one of the many things that +goes on. If you are not using \CONTEXT\ you probably will use Kai's version +because it is adapted to his use case and well tested. + +A fundamental difference between the two approaches is that|=|whereas the \LUA\ +variant operates on node lists only, the \type {plug} variant generates strings +that get passed to a library where, in the \CONTEXT\ variant of hb support, we +use \UTF-32 strings. Interesting, a couple of years ago I considered using a +similar method for \LUA\ but eventually decided against it, first of all for +performance reasons, but mostly because one still has to use some linked list +model. I might pick up that idea as a variant, but because all this \TEX\ related +development doesn't really pay off and costs a lot of free time it will probably +never happen. + +I finish with a few words on how to use the plug model. Because the library +initializes a default set of features,\footnote {Somehow passing features to the +library fails for Arabic. So when you don't get the desired result, just try with +the defaults.} all you need to do is load the plugin mechanism: + +\starttyping +\usemodule[fonts-plugins] +\stoptyping + +Next you define features that use this extension: + +\starttyping +\definefontfeature + [hb-native] + [mode=plug, + features=harfbuzz, + shaper=native] +\stoptyping + +After this you can use this feature set when you define fonts. Here is a complete +example: + +\starttyping +\usemodule[fonts-plugins] + +\starttext + + \definefontfeature + [hb-library] + [mode=plug, + features=harfbuzz, + shaper=native] + + \definedfont[Serif*hb-library] + + \input ward \par + + \definefontfeature + [hb-binary] + [mode=plug, + features=harfbuzz, + method=binary, + shaper=uniscribe] + + \definedfont[Serif*hb-binary] + + \input ward \par + +\stoptext +\stoptyping + +The second variant uses the \type {hb-shape} binary which is, of course, pretty +slow, but does the job and is okay for testing. + +There are a few trackers available too: + +\starttyping +\enabletrackers[fonts.plugins.hb.colors] +\enabletrackers[fonts.plugins.hb.details] +\stoptyping + +The first one colors replaced glyphs while the second gives lot of information +about what is going on. If you want to know what gets passed to the library you +can use the \type {text} plugin: + +\starttyping +\definefontfeature[test][mode=plug,features=text] +\start + \definedfont[Serif*test] + \input ward \par +\stop +\stoptyping + +This produces something: + +\starttyping[style=\ttx] +otf plugin > text > start run 3 +otf plugin > text > 001 : [-] The [+]-> U+00054 U+00068 U+00065 +otf plugin > text > 002 : [+] Earth, [+]-> U+00045 U+00061 U+00072 ... +otf plugin > text > 003 : [+] as [+]-> U+00061 U+00073 +otf plugin > text > 004 : [+] a [+]-> U+00061 +otf plugin > text > 005 : [+] habi- [-]-> U+00068 U+00061 U+00062 ... +otf plugin > text > 006 : [-] tat [+]-> U+00074 U+00061 U+00074 +otf plugin > text > 007 : [+] habitat [+]-> U+00068 U+00061 U+00062 ... +otf plugin > text > 008 : [+] for [+]-> U+00066 U+0006F U+00072 +otf plugin > text > 009 : [+] an- [-]-> U+00061 U+0006E U+0002D +\stoptyping + +You can see how hyphenation of \type {habi-tat} results in two snippets and a +whole word. The font engine can decide to turn this word +into a disc node with a pre, post and replace text. Of course the machinery will +try to retain as many hyphenation points as possible. Among the tricky parts of +this are lookups across and inside discretionary nodes resulting in (optional) +replacements and kerning. You can imagine that there is some trade off between +performance and quality here. The results are normally acceptable, especially +because \TEX\ is so clever in breaking paragraphs into lines. + +Using this mechanism (there might be variants in the future) permits the user to +cook up special solutions. After all, that is what \LUATEX\ is about|=|the +traditional core engine with the ability to plug in your own code using \LUA. +This is just an example of it. + +I'm not sure yet when the plugin mechanism will be in the \CONTEXT\ distribution, +but it might happen once the \type {ffi} library is supported in \LUATEX. At the +end of this document the basics of the test setup are shown, just in case you +wonder what the numbers apply to. + +Just to put things in perspective, the current (February 2017) \METAFUN\ manual +has 424 pages. It takes \LUATEX\ 18.3 seconds and \LUAJITTEX\ 14.4 seconds on my +Dell 7600 laptop with 3840QM mobile i7 processor. Of this 6.1 (4.5) seconds is +used for processing 2170 \METAPOST\ graphics. Loading the 15 fonts used takes +0.25 (0.3) seconds, which includes also loading the outline of some. Font +handling is part of the, so called, hlist processing and takes around 1 (0.5) +second, and attribute backend processing takes 0.7 (0.3) seconds. One problem in +these timings is that font processing often goes too fast for timing, especially +when we have lots of small snippets. For example, short runs like titles and such +take no time at all, and verbatim needs no font processing. The difference in +runtime between \LUATEX\ and \LUAJITTEX\ is significant so we can safely assume +that we spend some more time on fonts than reported. Even if we add a few +seconds, in this rather complete document, the time spent on fonts is still not +that impressive. A five fold increase in processing (we use mostly Pagella and +Dejavu) is a significant addition to the total run time, especially if you need a +few runs to get cross referencing etc.\ right. + +The test files are the familiar ones present in the distribution. The \type +{tufte} example is a good torture test for discretionary processing. We preload +the files so that we don't have the overhead of \type {\input}. + +\starttyping +\edef\tufte{\cldloadfile{tufte.tex}} +\edef\khatt{\cldloadfile{khatt-ar.tex}} +\stoptyping + +We use six buffers for the tests. The Latin test uses three fonts and also +has a paragraph with mixed font usage. Loading the fonts happens once before +the test, and the local (re)definition takes no time. Also, we compensate +for general overhead by subtracting the \type {none} timings. + +\starttyping +\startbuffer[latin-definitions] +\definefont[TestA][Serif*test] +\definefont[TestB][SerifItalic*test] +\definefont[TestC][SerifBold*test] +\stopbuffer + +\startbuffer[latin-text] +\TestA \tufte \par +\TestB \tufte \par +\TestC \tufte \par +\dorecurse {10} {% + \TestA Fluffy Test Font A + \TestB Fluffy Test Font B + \TestC Fluffy Test Font C +}\par +\stopbuffer +\stoptyping + +The Arabic tests are a bit simpler. Of course we do need to make sure that we go +from right to left. + +\starttyping +\startbuffer[arabic-definitions] +\definedfont[Arabic*test at 14pt] +\setupinterlinespace[line=18pt] +\setupalign[r2l] +\stopbuffer + +\startbuffer[arabic-text] +\dorecurse {10} { + \khatt\space + \khatt\space + \khatt\blank +} +\stopbuffer +\stoptyping + +The mixed case use a Latin and an Arabic font and also processes a mixed script +paragraph. + +\starttyping +\startbuffer[mixed-definitions] +\definefont[TestL][Serif*test] +\definefont[TestA][Arabic*test at 14pt] +\setupinterlinespace[line=18pt] +\setupalign[r2l] +\stopbuffer + +\startbuffer[mixed-text] +\dorecurse {2} { + {\TestA\khatt\space\khatt\space\khatt} + {\TestL\lefttoright\tufte} + \blank + \dorecurse{10}{% + {\TestA وَ قَرْمِطْ بَيْنَ الْحُرُوفِ؛ فَإِنَّ} + {\TestL\lefttoright A snippet text that makes no sense.} + } +} +\stopbuffer +\stoptyping + +The related font features are defined as follows: + +\starttyping +\definefontfeature + [test-none] + [mode=none] + +\definefontfeature + [test-base] + [mode=base, + liga=yes, + kern=yes] + +\definefontfeature + [test-node] + [mode=node, + script=auto, + autoscript=position, + autolanguage=position, + ccmp=yes,liga=yes,clig=yes, + kern=yes,mark=yes,mkmk=yes, + curs=yes] + +\definefontfeature + [test-text] + [mode=plug, + features=text] + +\definefontfeature + [test-native] + [mode=plug, + features=harfbuzz, + shaper=native] + +\definefontfeature + [arabic-node] + [arabic] + +\definefontfeature + [arabic-native] + [mode=plug, + features=harfbuzz, + script=arab,language=dflt, + shaper=native] +\stoptyping + +The timings are collected in \LUA\ tables and typeset afterwards, so there is no +interference there either. + +{\em The timings are as usual a snapshot and just indications. The relative times +can differ over time depending on how binaries are compiled, libraries are +improved and \LUA\ code evolves. In node mode we can have experimental trickery +that is not yet optimized. Also, especially with complex fonts like Husayni, not +all shapers give the same result, although node mode and Uniscribe should be the +same in most cases. A future (public) version of Husayni will play more safe and +use less complex sequences of features.} + +% And for the record: when I finished it, this 12 page documents processes in +% roughly 1~second with \LUATEX\ and 0.8 second with \LUAJITTEX\ which is okay for +% a edit|-|preview cycle. + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/onandon/onandon-performance.tex b/doc/context/sources/general/manuals/onandon/onandon-performance.tex new file mode 100644 index 000000000..279383a8c --- /dev/null +++ b/doc/context/sources/general/manuals/onandon/onandon-performance.tex @@ -0,0 +1,785 @@ +% language=uk + +% no zero timing compensation, just simple tests +% m4all book + +\startcomponent onandon-performance + +\environment onandon-environment + +\startchapter[title=Performance] + +\startsection[title=Introduction] + +This chapter is about performance. Although it concerns \LUATEX\ this text is +only meant for \CONTEXT\ users. This is not because they ever complain about +performance, on the contrary, I never received a complain from them. No, it's +because it gives them some ammunition against the occasionally occurring nagging +about the speed of \LUATEX\ (somewhere on the web or at some meeting). My +experience is that in most such cases those complaining have no clue what they're +talking about, so effectively we could just ignore them, but let's, for the sake +of our users, waste some words on the issue. + +\stopsection + +\startsection[title=What performance] + +So what exactly does performance refer to? If you use \CONTEXT\ there are +probably only two things that matter: + +\startitemize[packed] +\startitem How long does one run take. \stopitem +\startitem How many runs do I need. \stopitem +\stopitemize + +Processing speed is reported at the end of a run in terms of seconds spent on the +run, but also in pages per second. The runtime is made up out of three +components: + +\startitemize[packed] +\startitem start-up time \stopitem +\startitem processing pages \stopitem +\startitem finishing the document \stopitem +\stopitemize + +The startup time is rather constant. Let's take my 2013 Dell Precision with +i7-3840QM as reference. A simple + +\starttyping +\starttext +\stoptext +\stoptyping + +document reports 0.4 seconds but as we wrap the run in an \type {mtxrun} +management run we have an additional 0.3 overhead (auxiliary file handling, \PDF\ +viewer management, etc). This includes loading the Latin Modern font. With +\LUAJITTEX\ these times are below 0.3 and 0.2 seconds. It might look like much +overhead but in an edit|-|preview runs it feels snappy. One can try this: + +\starttyping +\stoptext +\stoptyping + +which bring down the time to about 0.2 seconds for both engines but as it doesn't +do anything useful that is is no practice. + +Finishing a document is not that demanding because most gets flushed as we go. +The more (large) fonts we use, the longer it takes to finish a document but on +the average that time is not worth noticing. The main runtime contribution comes +from processing the pages. + +Okay, this is not always true. For instance, if we process a 400 page book from +2500 small \XML\ files with multiple graphics per page, there is a little +overhead in loading the files and constructing the \XML\ tree as well as in +inserting the graphics but in such cases one expects a few seconds more runtime. The +\METAFUN\ manual has some 450 pages with over 2500 runtime generated \METAPOST\ +graphics. It has color, uses quite some fonts, has lots of font switches +(verbatim too) but still one run takes only 18 seconds in stock \LUATEX\ and less +that 15 seconds with \LUAJITTEX. Keep these numbers in mind if a non|-|\CONTEXT\ +users barks against the performance tree that his few page mediocre document +takes 10 seconds to compile: the content, styling, quality of macros and whatever +one can come up with all plays a role. Personally I find any rate between 10 and +30 pages per second acceptable, and if I get the lower rate then I normally know +pretty well that the job is demanding in all kind of aspects. + +Over time the \CONTEXT||\LUATEX\ combination, in spite of the fact that more +functionality has been added, has not become slower. In fact, some subsystems +have been sped up. For instance font handling is very sensitive for adding +functionality. However, each version so far performed a bit better. Whenever some +neat new trickery was added, at the same time improvements were made thanks to +more insight in the matter. In practice we're not talking of changes in speed by +large factors but more by small percentages. I'm pretty sure that most \CONTEXT\ +users never noticed. Recently a 15\endash30\% speed up (in font handling) was +realized (for more complex fonts) but only when you use such complex fonts and +pages full of text you will see a positive impact on the whole run. + +There is one important factor I didn't mention yet: the efficiency of the +console. You can best check that by making a format (\typ {context --make en}). +When that is done by piping the messages to a file, it takes 3.2 seconds on my +laptop and about the same when done from the editor (\SCITE), maybe because the +\LUATEX\ run and the log pane run on a different thread. When I use the standard +console it takes 3.8 seconds in Windows 10 Creative update (in older versions it +took 4.3 and slightly less when using a console wrapper). The powershell takes +3.2 seconds which is the same as piping to a file. Interesting is that in Bash on +Windows it takes 2.8 seconds and 2.6 seconds when piped to a file. Normal runs +are somewhat slower, but it looks like the 64 bit Linux binary is somewhat faster +than the 64 bit mingw version. \footnote {Long ago we found that \LUATEX\ is very +sensitive to for instance the \CPU\ cache so maybe there are some differences due +to optimization flags and|/|or the fact that bash runs in one thread and all file +\IO\ in the main windows instance. Who knows.} Anyway, it demonstrates that when +someone yells a number you need to ask what the conditions where. + +At a \CONTEXT\ meeting there has been a presentation about possible speed|-|up of +a run for instance by using a separate syntax checker to prevent a useless run. +However, the use case concerned a document that took a minute on the machine +used, while the same document took a few seconds on mine. At the same meeting we +also did a comparison of speed for a \LATEX\ run using \PDFTEX\ and the same +document migrated to \CONTEXT\ \MKIV\ using \LUATEX\ (Harald K\"onigs \XML\ +torture and compatibility test). Contrary to what one might expect, the +\CONTEXT\ run was significantly faster; the resulting document was a few +gigabytes in size. + +\stopsection + +\startsection[title=Bottlenecks] + +I will discuss a few potential bottlenecks next. A complex integrated system like +\CONTEXT\ has lots of components and some can be quite demanding. However, when +something is not used, it has no (or hardly any) impact on performance. Even when +we spend a lot of time in \LUA\ that is not the reason for a slow|-|down. +Sometimes using \LUA\ results in a speedup, sometimes it doesn't matter. Complex +mechanisms like natural tables for instance will not suddenly become less +complex. So, let's focus on the \quotation {aspects} that come up in those +complaints: fonts and \LUA. Because I only use \CONTEXT\ and occasionally test +with the plain \TEX\ version that we provide, I will not explore the potential +impact of using truckloads of packages, styles and such, which I'm sure of plays +a role, but one neglected in the discussion. + +\startsubsubject[title=Fonts] + +According to the principles of \LUATEX\ we process (\OPENTYPE) fonts using \LUA. +That way we have complete control over any aspect of font handling, and can, as +to be expected in \TEX\ systems, provide users what they need, now and in the +future. In fact, if we didn't had that freedom in \CONTEXT\ I'd probably already +quit using \TEX\ a decade ago and found myself some other (programming) niche. + +After a font is loaded, part of the data gets passed to the \TEX\ engine so that +it can do its work. For instance, in order to be able to typeset a paragraph, +\TEX\ needs to know the dimensions of glyphs. Once a font has been loaded +(that is, the binary blob) the next time it's fetched from a cache. Initial +loading (and preparation) takes some time, depending on the complexity or size of +the font. Loading from cache is close to instantaneous. After loading the +dimensions are passed to \TEX\ but all data remains accessible for any desired +usage. The \OPENTYPE\ feature processor for instance uses that data and \CONTEXT\ +for sure needs that data (fast accessible) for different purposes too. + +When a font is used in so called base mode, we let \TEX\ do the ligaturing and +kerning. This is possible with simple fonts and features. If you have a critical +workflow you might enable base mode, which can be done per font instance. +Processing in node mode takes some time but how much depends on the font and +script. Normally there is no difference between \CONTEXT\ and generic usage. In +\CONTEXT\ we also have dynamic features, and the impact on performance depends on +usage. In addition to base and node we also have plug mode but that is only used +for testing and therefore not advertised. + +Every \type {\hbox} and every paragraph goes through the font handler. Because +we support mixed modes, some analysis takes place, and because we do more in +\CONTEXT, the generic analyzer is more light weight, which again can mean that a +generic run is not slower than a similar \CONTEXT\ one. + +Interesting is that added functionality for variable and|/|or color fonts had no +impact on performance. Runtime added user features can have some impact but when +defined well it can be neglected. I bet that when you add additional node list +handling yourself, its impact on performance is larger. But in the end what +counts is that the job gets done and the more you demand the higher the price you +pay. + +\stopsubsubject + +\startsubsubject[title=\LUA] + +The second possible bottleneck when using \LUATEX\ can be in using \LUA\ code. +However, using that as argument for slow runs is laughable. For instance +\CONTEXT\ \MKIV\ can easily spend half its time in \LUA\ and that is not making +it any slower than \MKII\ using \PDFTEX\ doing equally complex things. For +instance the embedded \METAPOST\ library makes \MKIV\ way faster than \MKII, and +the built|-|in \XML\ processing capabilities in \MKIV\ can easily beat \MKII\ +\XML\ handling, apart from the fact that it can do more, like filtering by path +and expression. In fact, files that take, say, half a minute in \MKIV, could as +well have taken 15 minutes or more in \MKII\ (and imagine multiple runs then). + +So, for \CONTEXT\ using \LUA\ to achieve its objectives is mandate. The +combination of \TEX, \METAPOST\ and \LUA\ is pretty powerful! Each of these +components is really fast. If \TEX\ is your bottleneck, review your macros! When +\LUA\ seems to be the bad, go over your code and make it better. Much of the +\LUA\ code I see flying around doesn't look that efficient, which is okay because +the interpreter is really fast, but don't blame \LUA\ beforehand, blame your +coding (style) first. When \METAPOST\ is the bottleneck, well, sometimes not much +can be done about it, but when you know that language well enough you can often +make it perform better. + +For the record: every additional mechanism that kicks in, like character spacing +(the ugly one), case treatments, special word and line trickery, marginal stuff, +graphics, line numbering, underlining, referencing, and a few dozen more will add +a bit to the processing time. In that case, in \CONTEXT, the font related runtime +gets pretty well obscured by other things happening, just that you know. + +\stopsubsubject + +\stopsection + +\startsection[title=Some timing] + +Next I will show some timings related to fonts. For this I use stock \LUATEX\ +(second column) as well as \LUAJITTEX\ (last column) which of course performs +much better. The timings are given in 3 decimals but often (within a set of runs) +and as the system load is normally consistent in a set of test runs the last two +decimals only matter in relative comparison. So, for comparing runs over time +round to the first decimal. Let's start with loading a bodyfont. This happens +once per document and normally one has only one bodyfont active. Loading involves +definitions as well as setting up math so a couple of fonts are actually loaded, +even if they're not used later on. A setup normally involves a serif, sans, mono, +and math setup (in \CONTEXT). \footnote {The timing for Latin Modern is so low +because that font is loaded already.} + +\environment onandon-speed-000 + +\ShowSample{onandon-speed-000} % bodyfont + +There is a bit difference between the font sets but a safe average is 150 milli +seconds and this is rather constant over runs. + +An actual font switch can result in loading a font but this is a one time overhead. +Loading four variants (regular, bold, italic and bold italic) roughly takes the +following time: + +\ShowSample{onandon-speed-001} % four variants + +Using them again later on takes no time: + +\ShowSample{onandon-speed-002} % four variants + +Before we start timing the font handler, first a few baseline benchmarks are +shown. When no font is applied and nothing else is done with the node list we +get: + +\ShowSample{onandon-speed-009} + +A simple monospaced, no features applied, run takes a bit more: + +\ShowSample{onandon-speed-010} + +Now we show a one font typesetting run. As the two benchmarks before, we just +typeset a text in a \type {\hbox}, so no par builder interference happens. We use +the \type {sapolsky} sample text and typeset it 100 times 4 (either of not with +font switches). + +\ShowSample{onandon-speed-003} + +Much more runtime is needed when we typeset with four font switches. The garamond +is most demanding. Actually we're not doing 4 fonts there because it has no bold, +so the numbers are a bit lower than expected for this example. One reason for it +being demanding is that it has lots of (contextual) lookups. The only comment I +can make about that is that it also depends on the strategies of the font +designer. Combining lookups saves space and time so complexity of a font is not +always a good predictor for performance hits. + +% \ShowSample{onandon-speed-004} + +If we typeset paragraphs we get this: + +\ShowSample{onandon-speed-005} + +We're talking of some 275 pages here. + +\ShowSample{onandon-speed-006} + +There is of course overhead in handling paragraphs and pages: + +\ShowSample{onandon-speed-011} + +Before I discuss these numbers in more details two more benchmarks are +shown. The next table concerns a paragraph with only a few (bold) words. + +\ShowSample{onandon-speed-007} + +The following table has paragraphs with a few mono spaced words +typeset using \type{\type}. + +\ShowSample{onandon-speed-008} + +When a node list (hbox or paragraph) is processed, each glyph is looked at. One +important property of \LUATEX\ (compared to \PDFTEX) is that it hyphenates the +whole text, not only the most feasible spots. For the \type {sapolsky} snippet +this results in 200 potential breakpoints, registered in an equal number of +discretionary nodes. The snippet has 688 characters grouped into 125 words and +because it's an English quote we're not hampered with composed characters or +complex script handling. And, when we mention 100 runs then we actually mean +400 ones when font switching and bodyfonts are compared + +\startnarrower + \showglyphs \showfontkerns + \input sapolsky \wordright{Robert M. Sapolsky} +\stopnarrower + +In order to get substitutions and positioning right we need not only to consult +streams of glyphs but also combinations with preceding pre or replace, or +trailing post and replace texts. When a font has a bit more complex substitutions, +as ebgaramond has, multiple (sometimes hundreds of) passes over the list are made. +This is why the more complex a font is, the more runtime is involved. + +Another factor, one you could easily deduce from the benchmarks, is intermediate +font switches. Even a few such switches (in the last benchmarks) already result +in a runtime penalty. The four switch benchmarks show an impressive increase of +runtime, but it's good to know that such a situation seldom happens. It's also +important not to confuse for instance a verbatim snippet with a bold one. The +bold one is indeed leading to a pass over the list, but verbatim is normally +skipped because it uses a font that needs no processing. That verbatim or bold +have the same penalty is mainly due to the fact that verbatim itself is costly: +the text is picked up using a different catcode regime and travels through \TEX\ +and \LUA\ before it finally gets typeset. This relates to special treatments of +spacing and syntax highlighting and such. + +Also keep in mind that the page examples are quite unreal. We use a layout with +no margins, just text from edge to edge. + +\placefigure + {\SampleTitle{onandon-speed-005}} + {\externalfigure[onandon-speed-005][frame=on,orientation=90,width=.45\textheight]} + +\placefigure + {\SampleTitle{onandon-speed-006}} + {\externalfigure[onandon-speed-006][frame=on,orientation=90,maxwidth=.45\textheight,maxheight=\textwidth]} + +\placefigure + {\SampleTitle{onandon-speed-007}} + {\externalfigure[onandon-speed-007][frame=on,orientation=90,width=.45\textheight]} + +\placefigure + {\SampleTitle{onandon-speed-008}} + {\externalfigure[onandon-speed-008][frame=on,orientation=90,width=.45\textheight]} + +\placefigure + {\SampleTitle{onandon-speed-011}} + {\externalfigure[onandon-speed-011][frame=on,orientation=90,width=.45\textheight]} + +So what is a realistic example? That is hard to say. Unfortunately no one ever +asked us to typeset novels. They are rather brain dead products for a machinery +so they process fast. On the mentioned laptop 350 word pages in Dejavu fonts can +be processed at a rate of 75 pages per second with \LUATEX\ and over 100 pages +per second with \LUAJITTEX . On a more modern laptop or professional server +performance is of course better. And for automated flows batch mode is your +friend. The rate is not much worse for a document in a language with a bit more +complex character handling, take accents or ligatures. Of course \PDFTEX\ is +faster on such a dumb document but kick in some more functionality and the +advantage quickly disappears. So, if someone complains that \LUATEX\ needs 10 or +more seconds for a simple few page document \unknown\ you can bet that when the +fonts are seen as reason, that the setup is pretty bad. Personally I'd not waste +time on such a complaint. + +\stopsection + +\startsection[title=Valid questions] + +Here are some reasonable questions that you can ask when someone complains to you +about the slowness of \LUATEX: + +\startsubsubject[title={What engines do you compare?}] + +If you come from \PDFTEX\ you come from an 8~bit world: input and font handling +are based on bytes and hyphenation is integrated into the par builder. If you use +\UTF-8\ in \PDFTEX, the input is decoded by \TEX\ macros which carries a speed +penalty. Because in the wide engines macro names can also be \UTF\ sequences, +construction of macro names is less efficient too. + +When you try to use wide fonts, again there is a penalty. Now, if you use \XETEX\ +or \LUATEX\ your input is \UTF-8 which becomes something 32 bit internally. Fonts +are wide so more resources are needed, apart from these fonts being larger and in +need of more processing due to feature handling. Where \XETEX\ uses a library, +\LUATEX\ uses its own handler. Does that have a consequence for performance? Yes +and no. First of all it depends on how much time is spent on fonts at all, but +even then the difference is not that large. Sometimes \XETEX\ wins, sometimes +\LUATEX. One thing is clear: \LUATEX\ is more flexible as we can roll out our own +solutions and therefore do more advanced font magic. For \CONTEXT\ it doesn't +matter as we use \LUATEX\ exclusively and rely on the flexible font handler, also +for future extensions. If really needed you can kick in a library based handler +but it's (currently) not distributed as we loose other functionality which in +turn would result in complaints about that fact (apart from conflicting with the +strive for independence). + +There is no doubt that \PDFTEX\ is faster but for \CONTEXT\ it's an obsolete +engine. The hard coded solutions engine \XETEX\ is also not feasible for +\CONTEXT\ either. So, in practice \CONTEXT\ users have no choice: \LUATEX\ is +used, but users of other macro packages can use the alternatives if they are not +satisfied with performance. The fact that \CONTEXT\ users don't complain about +speed is a clear signal that this is no issue. And, if you want more speed you +can use \LUAJITTEX. \footnote {In plug mode we can actually test a library and +experiments have shown that performance on the average is much worse but it can +be a bit better for complex scripts, although a gain gets unnoticed in normal +documents. So, one can decide to use a library but at the cost of much other +functionality that \CONTEXT\ offers, so we don't support it.} In the last section +the different engines will be compared in more detail. + +Just that you know, when we do the four switches example in plain \TEX\ on my +laptop I get a rate of 40 pages per second, and for one font 180 pages per +second. There is of course a bit more going on in \CONTEXT\ in page building and +so, but the difference between plain and \CONTEXT\ is not that large. + +\stopsubsubject + +\startsubsubject[title={What macro package is used?}] + +If the answer is that when plain \TEX\ is used, a follow up question is: what +variant? The \CONTEXT\ distribution ships with \type {luatex-plain} and that is +our benchmark. If there really is a bottleneck it is worth exploring. But keep in +mind that in order to be plain, not that much can be done. The \LUATEX\ part is +just an example of an implementation. We already discussed \CONTEXT, and for +\LATEX\ I don't want to speculate where performance hits might come from. When +we're talking fonts, \CONTEXT\ can actually a bit slower than the generic (or +\LATEX) variant because we can kick in more functionality. Also, when you compare +macro packages, keep in mind that when node list processing code is added in that +package the impact depends on interaction with other functionality and depends on +the efficiency of the code. You can't compare mechanisms or draw general +conclusions when you don't know what else is done! + +\stopsubsubject + +\startsubsubject[title={What do you load?}] + +Most \CONTEXT\ modules are small and load fast. Of course there can be exceptions +when we rely on third party code; for instance loading tikz takes a a bit of +time. It makes no sense to look for ways to speed that system up because it is +maintained elsewhere. There can probably be gained a bit but again, no user +complained so far. + +If \CONTEXT\ is not used, one probably also uses a large \TEX\ installations. +File lookup in \CONTEXT\ is done differently and can can be faster. Even loading +can be more efficient in \CONTEXT, but it's hard to generalize that conclusion. +If one complains about loading fonts being an issue, just try to measure how much +time is spent on loading other code. + +\stopsubsubject + +\startsubsubject[title={Did you patch macros?}] + +Not everyone is a \TEX pert. So, coming up with macros that are expanded many +times and|/|or have inefficient user interfacing can have some impact. If someone +complains about one subsystem being slow, then honestly demands to complain about +other subsystems as well. You get what you ask for. + +\stopsubsubject + +\startsubsubject[title={How efficient is the code that you use?}] + +Writing super efficient code only makes sense when it's used frequently. In +\CONTEXT\ most code is reasonable efficient. It can be that in one document fonts +are responsible for most runtime, but in another document table construction can +be more demanding while yet another document puts some stress on interactive +features. When hz or protrusion is enabled then you run substantially slower +anyway so when you are willing to sacrifice 10\% or more runtime don't complain +about other components. The same is true for enabling \SYNCTEX: if you are +willing to add more than 10\% runtime for that, don't wither about the same +amount for font handling. \footnote {In \CONTEXT\ we use a \SYNCTEX\ alternative +that is somewhat faster but it remains a fact that enabling more and more +functionality will make the penalty of for instance font processing relatively +small.} + +\stopsubsubject + +\startsubsubject[title={How efficient is the styling that you use?}] + +Probably the most easily overseen optimization is in switching fonts and color. +Although in \CONTEXT\ font switching is fast, I have no clue about it in other +macro packages. But in a style you can decide to use inefficient (massive) font +switches. The effects can easily be tested by commenting bit and pieces. For +instance sometimes you need to do a full bodyfont switch when changing a style, +like assigning \type {\small\bf} to the \type {style} key in \type {\setuphead}, +but often using e.g.\ \type {\tfd} is much more efficient and works quite as +well. Just try it. + +\stopsubsubject + +\startsubsubject[title={Are fonts really the bottleneck?}] + +We already mentioned that one can look in the wrong direction. Maybe once someone +is convinced that fonts are the culprit, it gets hard to look at the real issue. +If a similar job in different macro packages has a significant different runtime +one can wonder what happens indeed. + +It is good to keep in mind that the amount of text is often not as large as you +think. It's easy to do a test with hundreds of paragraphs of text but in practice +we have whitespace, section titles, half empty pages, floats, itemize and similar +constructs, etc. Often we don't mix many fonts in the running text either. So, in +the end a real document is the best test. + +\stopsubsubject + +\startsubsubject[title={If you use \LUA, is that code any good?}] + +You can gain from the faster virtual machine of \LUAJITTEX. Don't expect wonders +from the jitting as that only pays of for long runs with the same code used over +and over again. If the gain is high you can even wonder how well written your +\LUA\ code is anyway. + +\stopsubsubject + +\startsubsubject[title={What if they don't believe you?}] + +So, say that someone finds \LUATEX\ slow, what can be done about it? Just advice +him or her to stick to tool used previously. Then, if arguments come that one +also wants to use \UTF-8, \OPENTYPE\ fonts, a bit of \METAPOST, and is looking +forward to using \LUA\ runtime, the only answer is: take it or leave it. You pay +a price for progress, but if you do your job well, the price is not that large. +Tell them to spend time on learning and maybe adapting and bark against their own +tree before barking against those who took that step a decade ago. Most \CONTEXT\ +users took that step and someone still using \LUATEX\ after a decade can't be +that stupid. It's always best to first wonder what one actually asks from \LUATEX, +and if the benefit of having \LUA\ on board has an advantage. If not, one can +just use another engine. + +Also think of this. When a job is slow, for me it's no problem to identify where +the problem is. The question then is: can something be done about it? Well, I +happily keep the answer for myself. After all, some people always need room to +complain, maybe if only to hide their ignorance or incompetence. Who knows. + +\stopsubsubject + +\stopsection + +\startsection[title={Comparing engines}] + +The next comparison is to be taken with a grain of salt and concerns the state of +affairs mid 2017. First of all, you cannot really compare \MKII\ with \MKIV: the +later has more functionality (or a more advanced implementation of +functionality). And as mentioned you can also not really compare \PDFTEX\ and the +wide engines. Anyway, here are some (useless) tests. First a bunch of loads. Keep +in mind that different engines also deal differently with reading files. For +instance \MKIV\ uses \LUATEX\ callbacks to normalize the input and has its own +readers. There is a bit more overhead in starting up a \LUATEX\ run and some +functionality is enabled that is not present in \MKII. The format is also larger, +if only because we preload a lot of useful font, character and script related +data. + +\starttyping +\starttext + \dorecurse {#1} { + \input knuth + \par + } +\stoptext +\stoptyping + +When looking at the numbers one should realize that the times include startup and +job management by the runner scripts. We also run in batchmode to avoid logging +to influence runtime. The average is calculated from 5 runs. + +% sample 1, number of runs: 5 + +\starttabulate[||r|r|r|] +\HL +\BC engine \BC 50 \BC 500 \BC 2500 \NC \NR +\HL +\BC pdftex \NC 0.43 \NC 0.77 \NC 2.33 \NC \NR +\BC xetex \NC 0.85 \NC 2.66 \NC 10.79 \NC \NR +\BC luatex \NC 0.94 \NC 2.50 \NC 9.44 \NC \NR +\BC luajittex \NC 0.68 \NC 1.69 \NC 6.34 \NC \NR +\HL +\stoptabulate + +The second example does a few switches in a paragraph: + +\starttyping +\starttext + \dorecurse {#1} { + \tf \input knuth + \bf \input knuth + \it \input knuth + \bs \input knuth + \par + } +\stoptext +\stoptyping + +% sample 2, number of runs: 5 + +\starttabulate[||r|r|r|] +\HL +\BC engine \BC 50 \BC 500 \BC 2500 \NC \NR +\HL +\BC pdftex \NC 0.58 \NC 2.10 \NC 8.97 \NC \NR +\BC xetex \NC 1.47 \NC 8.66 \NC 42.50 \NC \NR +\BC luatex \NC 1.59 \NC 8.26 \NC 38.11 \NC \NR +\BC luajittex \NC 1.12 \NC 5.57 \NC 25.48 \NC \NR +\HL +\stoptabulate + +The third examples does a few more, resulting in multiple subranges +per style: + +\starttyping +\starttext + \dorecurse {#1} { + \tf \input knuth \it knuth + \bf \input knuth \bs knuth + \it \input knuth \tf knuth + \bs \input knuth \bf knuth + \par + } +\stoptext +\stoptyping + +% sample 3, number of runs: 5 + +\starttabulate[||r|r|r|] +\HL +\BC engine \BC 50 \BC 500 \BC 2500 \NC \NR +\HL +\BC pdftex \NC 0.59 \NC 2.20 \NC 9.52 \NC \NR +\BC xetex \NC 1.49 \NC 8.88 \NC 43.85 \NC \NR +\BC luatex \NC 1.64 \NC 8.91 \NC 41.26 \NC \NR +\BC luajittex \NC 1.15 \NC 5.91 \NC 27.15 \NC \NR +\HL +\stoptabulate + +The last example adds some color. Enabling more functionality can have an impact +on performance. In fact, as \MKIV\ uses a lot of \LUA\ and is also more advanced +that \MKII, one can expect a performance hit but in practice the opposite +happens, which can also be due to some fundamental differences deep down at the +macro level. + +\starttyping +\setupcolors[state=start] % default in MkIV + +\starttext + \dorecurse {#1} { + {\red \tf \input knuth \green \it knuth} + {\red \bf \input knuth \green \bs knuth} + {\red \it \input knuth \green \tf knuth} + {\red \bs \input knuth \green \bf knuth} + \par + } +\stoptext +\stoptyping + +% sample 4, number of runs: 5 + +\starttabulate[||r|r|r|] +\HL +\BC engine \BC 50 \BC 500 \BC 2500 \NC \NR +\HL +\BC pdftex \NC 0.61 \NC 2.36 \NC 10.33 \NC \NR +\BC xetex \NC 1.53 \NC 9.25 \NC 45.59 \NC \NR +\BC luatex \NC 1.65 \NC 8.91 \NC 41.32 \NC \NR +\BC luajittex \NC 1.15 \NC 5.93 \NC 27.34 \NC \NR +\HL +\stoptabulate + +In these measurements the accuracy is a few decimals but a pattern is visible. As +expected \PDFTEX\ wins on simple documents but starts loosing when things get +more complex. For these tests I used 64 bit binaries. A 32 bit \XETEX\ with +\MKII\ performs the same as \LUAJITTEX\ with \MKIV, but a 64 bit \XETEX\ is +actually quite a bit slower. In that case the mingw cross compiled \LUATEX\ +version does pretty well. A 64 bit \PDFTEX\ is also slower (it looks) that a 32 +bit version. So in the end, there are more factors that play a role. Choosing +between \LUATEX\ and \LUAJITTEX\ depends on how well the memory limited +\LUAJITTEX\ variant can handle your documents and fonts. + +Because in most of our recent styles we use \OPENTYPE\ fonts and (structural) +features as well as recent \METAFUN\ extensions only present in \MKIV\ we cannot +compare engines using such documents. The mentioned performance of \LUATEX\ (or +\LUAJITTEX) and \MKIV\ on the \METAFUN\ manual illustrate that in most cases this +combination is a clear winner. + +\starttyping +\starttext + \dorecurse {#1} { + \null \page + } +\stoptext +\stoptyping + +This gives: + +% sample 5, number of runs: 5 + +\starttabulate[||r|r|r|] +\HL +\BC engine \BC 50 \BC 500 \BC 2500 \NC \NR +\HL +\BC pdftex \NC 0.46 \NC 1.05 \NC 3.72 \NC \NR +\BC xetex \NC 0.73 \NC 1.80 \NC 6.56 \NC \NR +\BC luatex \NC 0.84 \NC 1.44 \NC 4.07 \NC \NR +\BC luajittex \NC 0.61 \NC 1.10 \NC 3.33 \NC \NR +\HL +\stoptabulate + +That leaves the zero run: + +\starttyping +\starttext + \dorecurse {#1} { + % nothing + } +\stoptext +\stoptyping + +This gives the following numbers. In longer runs the difference in overhead is +neglectable. + +% sample 6, number of runs: 5 + +\starttabulate[||r|r|r|] +\HL +\BC engine \BC 50 \BC 500 \BC 2500 \NC \NR +\HL +\BC pdftex \NC 0.36 \NC 0.36 \NC 0.36 \NC \NR +\BC xetex \NC 0.57 \NC 0.57 \NC 0.59 \NC \NR +\BC luatex \NC 0.74 \NC 0.74 \NC 0.74 \NC \NR +\BC luajittex \NC 0.53 \NC 0.53 \NC 0.54 \NC \NR +\HL +\stoptabulate + +It will be clear that when we use different fonts the numbers will also be +different. And if you use a lot of runtime \METAPOST\ graphics (for instance for +backgrounds), the \MKIV\ runs end up at the top. And when we process \XML\ it +will be clear that going back to \MKII\ is no longer a realistic option. It must +be noted that I occasionally manage to improve performance but we've now reached +a state where there is not that much to gain. Some functionality is hard to +compare. For instance in \CONTEXT\ we don't use much of the \PDF\ backend +features because we implement them all in \LUA. In fact, even in \MKII\ already a +done in \TEX, so in the end the speed difference there is not large and often in +favour of \MKIV. + +For the record I mention that shipping out the about 1250 pages has some overhead +too: about 2 seconds. Here \LUAJITTEX\ is 20\% more efficient which is an +indication of quite some \LUA\ involvement. Loading the input files has an +overhead of about half a second. Starting up \LUATEX\ takes more time that +\PDFTEX\ and \XETEX, but that disadvantage disappears with more pages. So, in the +end there are quite some factors that blur the measurements. In practice what +matters is convenience: does the runtime feel reasonable and in most cases it +does. + +If I would replace my laptop with a reasonable comparable alternative that one +would be some 35\% faster (single threads on processors don't gain much per year). +I guess that this is about the same increase in performance that \CONTEXT\ +\MKIV\ got in that period. I don't expect such a gain in the coming years so +at some point we're stuck with what we have. + +\stopsection + +\startsection[title=Summary] + +So, how \quotation {slow} is \LUATEX\ really compared to the other engines? If we +go back in time to when the first wide engines showed up, \OMEGA\ was considered +to be slow, although I never tested that myself. Then, when \XETEX\ showed up, +there was not much talk about speed, just about the fact that we could use +\OPENTYPE\ fonts and native \UTF\ input. If you look at the numbers, for sure you +can say that it was much slower than \PDFTEX. So how come that some people +complain about \LUATEX\ being so slow, especially when we take into account that +it's not that much slower than \XETEX, and that \LUAJITTEX\ is often faster that +\XETEX. Also, computers have become faster. With the wide engines you get more +functionality and that comes at a price. This was accepted for \XETEX\ and is +also acceptable for \LUATEX. But the price is nto that high if you take into +account that hardware performs better: you just need to compare \LUATEX\ (and +\XETEX) runtime with \PDFTEX\ runtime 15 years ago. + +As a comparison, look at games and video. Resolution became much higher as did +color depth. Higher frame rates were in demand. Therefore the hardware had to +become faster and it did, and as a result the user experience kept up. No user +will say that a modern game is slower than an old one, because the old one does +500 frames per second compared to some 50 for the new game on the modern +hardware. In a similar fashion, the demands for typesetting became higher: +\UNICODE, \OPENTYPE, graphics, \XML, advanced \PDF, more complex (niche) +typesetting, etc. This happened more or less in parallel with computers becoming +more powerful. So, as with games, the user experience didn't degrade with +demands. Comparing \LUATEX\ with \PDFTEX\ is like comparing a low res, low frame +rate, low color game with a modern one. You need to have up to date hardware and +even then, the writer of such programs need to make sure it runs efficient, +simply because hardware no longer scales like it did decades ago. You need to +look at the larger picture. + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/onandon/onandon-seguiemj.pdf b/doc/context/sources/general/manuals/onandon/onandon-seguiemj.pdf Binary files differnew file mode 100644 index 000000000..02b2bd271 --- /dev/null +++ b/doc/context/sources/general/manuals/onandon/onandon-seguiemj.pdf diff --git a/doc/context/sources/general/manuals/onandon/onandon-seguiemj.tex b/doc/context/sources/general/manuals/onandon/onandon-seguiemj.tex new file mode 100644 index 000000000..eff8a6acb --- /dev/null +++ b/doc/context/sources/general/manuals/onandon/onandon-seguiemj.tex @@ -0,0 +1,54 @@ +% language=uk + +\environment onandon-environment + +\setuppagenumbering[alternative=singlesided] + +\definefontfeature[seguiemj-cl][default][colr=yes,ccmp=yes,dist=yes] + +\definefont[MyEmojiLargeOld][seguiemj-old*seguiemj-cl @ 100pt] +\definefont[MyEmojiLargeNew][seguiemj*seguiemj-cl @ 100pt] + +\def\ShowThem#1% + {\ruledhbox{\MyEmojiLargeOld\resolvedemoji{#1}}% + \quad + \ruledhbox{\MyEmojiLargeNew\resolvedemoji{#1}}} + +\def\ShowGone#1% + {\setbox\scratchbox\ruledhbox{\MyEmojiLargeOld\resolvedemoji{#1}}% + \copy\scratchbox + \quad + \ruledhbox to \wd\scratchbox + {\lower\dp\scratchbox\vbox to \htdp\scratchbox + {\vss + \hbox to \wd\scratchbox{\hss no longer supported\hss}% + \vss}}} + +\starttext + +\startTEXpage[offset=.5pt] +\startcombination[2*5] + {\ShowThem{family woman woman girl boy}}% + {family woman woman girl boy} + {\ShowThem{family woman woman boy boy}}% + {family woman woman boy boy} + {\ShowThem{family woman girl boy}} + {family woman girl boy} + {\ShowThem{family man dark skin tone woman girl baby}} + {family man dark skin tone woman girl baby} + {\ShowThem{family man light skin tone woman light skin tone girl dark skin tone}} + {family man light skin tone woman light skin tone girl dark skin tone} + {\ShowThem{family man girl boy}} + {family man girl boy} + {\ShowThem{family man man girl boy}}% + {family man man girl boy} + {\ShowThem{family man light skin tone woman dark skin tone girl medium skin tone boy medium skin tone}} + {family man light skin tone woman dark skin tone girl medium skin tone boy medium skin tone} + {\ShowGone{couple with heart man light skin tone man medium-dark skin tone}} + {couple with heart man light skin tone man medium-dark skin tone} + {\ShowGone{kiss man medium-light skin tone man dark skin tone}} + {kiss man medium-light skin tone man dark skin tone} +\stopcombination +\stopTEXpage + +\stoptext diff --git a/doc/context/sources/general/manuals/onandon/onandon-speed-000.tex b/doc/context/sources/general/manuals/onandon/onandon-speed-000.tex new file mode 100644 index 000000000..f48af866d --- /dev/null +++ b/doc/context/sources/general/manuals/onandon/onandon-speed-000.tex @@ -0,0 +1,116 @@ +% \startenvironment onandon-speed-000 + +% \dontcomplain + +\edef\sapolsky{\ignorespaces\cldloadfile{sapolsky}\removeunwantedspaces} + +\startluacode + + function document.ResetSample(title) + document.elapsed = { + title = title, + times = { }, + } + end + + function document.RegisterSample(bodyfont,elapsed) + table.insert(document.elapsed.times, { + bodyfont = bodyfont, + elapsed = elapsed + }) + end + + function document.SaveSample() + if LUATEXENGINE == "luajittex" then + table.save(tex.jobname.."-jit.lua",document.elapsed) + else + table.save(tex.jobname..".lua",document.elapsed) + end + end + + function document.ShowSample(filename) + -- context.typefile(filename..".tex") + local elapsed = table.load(file.nameonly(filename)..".lua") + local elapsedjit = table.load(file.nameonly(filename).."-jit.lua") + if elapsed and elapsedjit then + context.testpage { 6 } + context.starttabulate { "|l|l|lp|" } + context.HL() + context.NC() context.formatted.rlap("\\bf %s",elapsed.title) + context.NC() + context.NC() + context.NC() context.NR() + context.HL() + local times = elapsed.times + local timesjit = elapsedjit.times + for j=1,#times do + local t = times[j] + local tjit = timesjit[j] + context.NC() context(t.bodyfont) + context.NC() context(t.elapsed) + context.NC() context(tjit.elapsed) + context.NC() context.NR() + end + context.HL() + context.stoptabulate() + end + end + + function document.SampleTitle(filename) + local elapsed = table.load(filename..".lua") + if elapsed then + context(elapsed.title) + end + end +\stopluacode + +\appendtoks + \ctxlua{document.SaveSample()}% +\to \everystoptext + +\def\SampleCount{1000} +\def\SampleCount{100} + +\unexpanded\def\RegisterSample#1% + {\ctxlua{document.RegisterSample("#1","\elapsedtime")}} + +\unexpanded\def\ProcessSample#1% + {\page + \ctxlua{document.ResetSample("#1")}% + \resettimer \Sample {modern} \RegisterSample {modern} + \resettimer \Sample {pagella} \RegisterSample {pagella} + \resettimer \Sample {termes} \RegisterSample {termes} + \resettimer \Sample {cambria} \RegisterSample {cambria} + \resettimer \Sample {dejavu} \RegisterSample {dejavu} + \resettimer \Sample {ebgaramond} \RegisterSample {ebgaramond} + \resettimer \Sample {lucidaot} \RegisterSample {lucidaot} + \page } + +\unexpanded\def\ProcessBaselineSample#1% + {\page + \ctxlua{document.ResetSample("#1")}% + \resettimer \Sample {baseline} \RegisterSample {baseline} + \page } + +\unexpanded\def\Sample#1% + {\setupbodyfont[#1]} + +\unexpanded\def\ShowSample#1% + {\ctxlua{document.ShowSample("#1")}} + +\unexpanded\def\SampleTitle#1% + {\ctxlua{document.SampleTitle("#1.lua")}} + +\continueifinputfile{onandon-speed-000.tex} + +\starttext + +\ProcessSample{bodyfont} + +\setbox\scratchbox\vbox{\hsize1pt\tttf\sapolsky} \getnoflines{\htdp\scratchbox} + +\writestatus{!!!!!!}{noflines : \the\noflines} + +\stoptext + +% \stopenvironment diff --git a/doc/context/sources/general/manuals/onandon/onandon-speed-001.tex b/doc/context/sources/general/manuals/onandon/onandon-speed-001.tex new file mode 100644 index 000000000..b6c241752 --- /dev/null +++ b/doc/context/sources/general/manuals/onandon/onandon-speed-001.tex @@ -0,0 +1,15 @@ +\environment onandon-speed-000 + +\ProcessSample{bodyfont} \setupbodyfont[dejavu] + +\starttext + +\def\Sample#1% + {\start + \switchtobodyfont[#1] + \setbox\scratchbox\hbox{\tf\bf\it\bi}% + \stop} + +\ProcessSample{bodyfont switch and 4 style changes (first time)} + +\stoptext diff --git a/doc/context/sources/general/manuals/onandon/onandon-speed-002.tex b/doc/context/sources/general/manuals/onandon/onandon-speed-002.tex new file mode 100644 index 000000000..edd6dd0f7 --- /dev/null +++ b/doc/context/sources/general/manuals/onandon/onandon-speed-002.tex @@ -0,0 +1,16 @@ +\environment onandon-speed-000 + +\ProcessSample{bodyfont} \setupbodyfont[dejavu] + +\starttext + +\def\Sample#1% + {\start + \switchtobodyfont[#1] + \setbox\scratchbox\hbox{\tf\bf\it\bi}% + \stop} + +\ProcessSample{bodyfont switch and 4 style changes (first time)} +\ProcessSample{bodyfont switch and 4 style changes (follow up)} + +\stoptext diff --git a/doc/context/sources/general/manuals/onandon/onandon-speed-003.tex b/doc/context/sources/general/manuals/onandon/onandon-speed-003.tex new file mode 100644 index 000000000..4362ccb4f --- /dev/null +++ b/doc/context/sources/general/manuals/onandon/onandon-speed-003.tex @@ -0,0 +1,15 @@ +\environment onandon-speed-000 + +\ProcessSample{bodyfont} \setupbodyfont[dejavu] + +\starttext + +\def\Sample#1% + {\start + \switchtobodyfont[#1] + \dorecurse\SampleCount{\setbox\scratchbox\hbox{\sapolsky\space\sapolsky\space\sapolsky\space\sapolsky}}% + \stop} + +\ProcessSample{\SampleCount\space hboxes with 4 texts using one font} + +\stoptext diff --git a/doc/context/sources/general/manuals/onandon/onandon-speed-005.tex b/doc/context/sources/general/manuals/onandon/onandon-speed-005.tex new file mode 100644 index 000000000..7aeb53b4b --- /dev/null +++ b/doc/context/sources/general/manuals/onandon/onandon-speed-005.tex @@ -0,0 +1,17 @@ +\environment onandon-speed-000 + +\ProcessSample{bodyfont} \setupbodyfont[dejavu] + +\starttext + +\def\Sample#1% + {\start + \switchtobodyfont[#1] + \dorecurse\SampleCount{\sapolsky\space\sapolsky\space\sapolsky\space\sapolsky\par}% + \stop} + +\startlayout[page] + \ProcessSample{\SampleCount\space times 4 texts on pages} +\stoplayout + +\stoptext diff --git a/doc/context/sources/general/manuals/onandon/onandon-speed-006.tex b/doc/context/sources/general/manuals/onandon/onandon-speed-006.tex new file mode 100644 index 000000000..d15ef428e --- /dev/null +++ b/doc/context/sources/general/manuals/onandon/onandon-speed-006.tex @@ -0,0 +1,17 @@ +\environment onandon-speed-000 + +\ProcessSample{bodyfont} \setupbodyfont[dejavu] + +\starttext + +\def\Sample#1% + {\start + \switchtobodyfont[#1] + \dorecurse\SampleCount{\tf\sapolsky\space\bf\sapolsky\space\it\sapolsky\space\bi\sapolsky\space\par}% + \stop} + +\startlayout[page] + \ProcessSample{\SampleCount\space times 4 texts on pages using 4 styles} +\stoplayout + +\stoptext diff --git a/doc/context/sources/general/manuals/onandon/onandon-speed-007.tex b/doc/context/sources/general/manuals/onandon/onandon-speed-007.tex new file mode 100644 index 000000000..7a4eed497 --- /dev/null +++ b/doc/context/sources/general/manuals/onandon/onandon-speed-007.tex @@ -0,0 +1,31 @@ +\environment onandon-speed-000 + +\ProcessSample{bodyfont} \setupbodyfont[dejavu] + +\starttext + +\def\sapolsky{% + Agriculture is a fairly recent human invention, and in many ways it was one of + the great {\bf stupid} moves of all time. Hunter|-|gatherers have thousands of wild + sources of food to subsist on. Agriculture changed that all, generating an + overwhelming reliance on a few dozen domesticated food sources, making you + extremely vulnerable to the next famine, the next locust infestation, the next + potato blight. Agriculture allowed for stockpiling of surplus resources and thus, + {\bf inevitably}, the unequal stockpiling of them --- stratification of society and + the invention of classes. Thus, it allowed for the invention of poverty. I think + that the punch line of the primate|-|human difference is that when humans + invented poverty, they came up with a way of subjugating the low|-|ranking like + {\bf nothing ever seen before} in the primate world. +}% + +\def\Sample#1% + {\start + \switchtobodyfont[#1] + \dorecurse\SampleCount{\sapolsky\par}% + \stop} + +\startlayout[page] + \ProcessSample{\SampleCount\space texts on pages with [1,2,4] bold font switches} +\stoplayout + +\stoptext diff --git a/doc/context/sources/general/manuals/onandon/onandon-speed-008.tex b/doc/context/sources/general/manuals/onandon/onandon-speed-008.tex new file mode 100644 index 000000000..ae968bc10 --- /dev/null +++ b/doc/context/sources/general/manuals/onandon/onandon-speed-008.tex @@ -0,0 +1,32 @@ +\environment onandon-speed-000 + +\ProcessSample{bodyfont} \setupbodyfont[dejavu] + +\starttext + +\def\sapolsky{% + Agriculture is a fairly recent human invention, and in many ways it was one + of the great \type {stupid} moves of all time. Hunter|-|gatherers have + thousands of wild sources of food to subsist on. Agriculture changed that + all, generating an overwhelming reliance on a few dozen domesticated food + sources, making you extremely vulnerable to the next famine, the next locust + infestation, the next potato blight. Agriculture allowed for stockpiling of + surplus resources and thus, \type {inevitably}, the unequal stockpiling of + them --- stratification of society and the invention of classes. Thus, it + allowed for the invention of poverty. I think that the punch line of the + primate|-|human difference is that when humans invented poverty, they came up + with a way of subjugating the low|-|ranking like \type {nothing ever seen + before} in the primate world. +}% + +\def\Sample#1% + {\start + \switchtobodyfont[#1] + \dorecurse\SampleCount{\sapolsky\par}% + \stop} + +\startlayout[page] + \ProcessSample{\SampleCount\space texts on pages with [1,2,4] word verbatim switches} +\stoplayout + +\stoptext diff --git a/doc/context/sources/general/manuals/onandon/onandon-speed-009.tex b/doc/context/sources/general/manuals/onandon/onandon-speed-009.tex new file mode 100644 index 000000000..61116e652 --- /dev/null +++ b/doc/context/sources/general/manuals/onandon/onandon-speed-009.tex @@ -0,0 +1,15 @@ +\environment onandon-speed-000 + +\ProcessSample{bodyfont} \setupbodyfont[dejavu] + +\starttext + +\def\Sample#1% + {\start + \infofont + \dorecurse\SampleCount{\setbox\scratchbox\hpack{\sapolsky\space\sapolsky\space\sapolsky\space\sapolsky}}% + \stop} + +\ProcessBaselineSample{\SampleCount\space hboxes with 4 texts and no font handling} + +\stoptext diff --git a/doc/context/sources/general/manuals/onandon/onandon-speed-010.tex b/doc/context/sources/general/manuals/onandon/onandon-speed-010.tex new file mode 100644 index 000000000..673c2b1e5 --- /dev/null +++ b/doc/context/sources/general/manuals/onandon/onandon-speed-010.tex @@ -0,0 +1,15 @@ +\environment onandon-speed-000 + +\ProcessSample{bodyfont} \setupbodyfont[dejavu] + +\starttext + +\def\Sample#1% + {\start + \infofont + \dorecurse\SampleCount{\setbox\scratchbox\hbox{\sapolsky\space\sapolsky\space\sapolsky\space\sapolsky}}% + \stop} + +\ProcessBaselineSample{\SampleCount\space hboxes with 4 texts and no features} + +\stoptext diff --git a/doc/context/sources/general/manuals/onandon/onandon-speed-011.tex b/doc/context/sources/general/manuals/onandon/onandon-speed-011.tex new file mode 100644 index 000000000..90d924c00 --- /dev/null +++ b/doc/context/sources/general/manuals/onandon/onandon-speed-011.tex @@ -0,0 +1,20 @@ +\environment onandon-speed-000 + +\ProcessSample{bodyfont} \setupbodyfont[dejavu] + +\dontcomplain + +\starttext + +\def\Sample#1% + {\start + \tttf\tx + \dorecurse\SampleCount{\sapolsky\space\sapolsky\space\sapolsky\space\sapolsky\par}% + \stop} + +\startlayout[page] + \ProcessBaselineSample {\SampleCount\space paragraphs with 4 texts and no features} +\stoplayout + + +\stoptext diff --git a/doc/context/sources/general/manuals/onandon/onandon-speed-012.tex b/doc/context/sources/general/manuals/onandon/onandon-speed-012.tex new file mode 100644 index 000000000..e2d51e195 --- /dev/null +++ b/doc/context/sources/general/manuals/onandon/onandon-speed-012.tex @@ -0,0 +1,20 @@ +\environment onandon-speed-000 + +\ProcessSample{bodyfont} \setupbodyfont[dejavu] + +\dontcomplain + +\starttext + +\def\SampleCount{1000} + +\def\Sample#1% + {\start +% \switchtobodyfont[#1] + \dorecurse\SampleCount{\sapolsky\par} + \stop} + +% \ProcessSample{\SampleCount\space pages no features} +\ProcessBaselineSample{\SampleCount\space paragraphs text} + +\stoptext diff --git a/doc/context/sources/general/manuals/onandon/onandon-variable.tex b/doc/context/sources/general/manuals/onandon/onandon-variable.tex new file mode 100644 index 000000000..c73196cef --- /dev/null +++ b/doc/context/sources/general/manuals/onandon/onandon-variable.tex @@ -0,0 +1,557 @@ +% language=uk + +% todo: callback: stream, llx, lly, urx, ury, wd, lsb +% add glyphs runtime +% create whole cff so that we can go from mp + +\startcomponent onandon-variable + +\environment onandon-environment + +\startchapter[title=Variable fonts] + +\startsubject[title=Introduction] + +History shows the tendency to recycle ideas. Often quite some effort is made by +historians to figure out what really happened, not just long ago, when nothing +was written down and we have to do with stories or pictures at most, but also in +recent times. Descriptions can be conflicting, puzzling, incomplete, partially +lost, biased, \unknown + +Just as language was invented (or evolved) several times, so were scripts. The +same might be true for rendering scripts on a medium. Semaphores came and went +within decades and how many people know now that they existed and that encryption +was involved? Are the old printing presses truly the old ones, or are older +examples simply gone? One of the nice aspects of the internet is that one can now +more easily discover similar solutions for the same problem, but with a different +(and independent) origin. + +So, how about this \quotation {new big thing} in font technology: variable fonts. +In this case, history shows that it's not that new. For most \TEX\ users the +names \METAFONT\ and \METAPOST\ will ring bells. They have a very well documented +history so there is not much left to speculation. There are articles, books, +pictures, examples, sources, and more around for decades. So, the ability to +change the appearance of a glyph in a font depending on some parameters is not +new. What probably {\em is} new is that creating variable fonts is done in the +natural environment where fonts are designed: an interactive program. The +\METAFONT\ toolkit demands quite some insight in programming shapes in such a way +that one can change look and feel depending on parameters. There are not that +many meta fonts made and one reason is that making them requires a certain mind- +and skill set. On the other hand, faster computers, interactive programs, +evolving web technologies, where rea|l|-time rendering and therefore more or less +real-time tweaking of fonts is a realistic option, all play a role in acceptance. + +But do interactive font design programs make this easier? You still need to be +able to translate ideas into usable beautiful fonts. Taking the common shapes of +glyphs, defining extremes and letting a program calculate some interpolations +will not always bring good results. It's like morphing a picture of your baby's +face into yours of old age (or that of your grandparent): not all intermediate +results will look great. It's good to notice that variable fonts are a revival of +existing techniques and ideas used in, for instance, multiple master fonts. The +details might matter even more as they can now be exaggerated when some +transformation is applied. + +There is currently (March 2017) not much information about these fonts so what I +say next may be partially wrong or at least different from what is intended. The +perspective will be one from a \TEX\ user and coder. Whatever you think of them, +these fonts will be out there and for sure there will be nice examples +circulating soon. And so, when I ran into a few experimental fonts, with +\POSTSCRIPT\ and \TRUETYPE\ outlines, I decided to have a look at what is inside. +After all, because it's visual, it's also fun to play with. Let's stress that at +the moment of this writing I only have a few simple fonts available, fonts that +are designed for testing and not usage. Some recommended tables were missing and +no complex \OPENTYPE\ features are used in these fonts. + +\stopsubject + +\startsubject[title=The specification] + +I'm not that good at reading specifications, first of all because I quickly fall +asleep with such documents, but most of all because I prefer reading other stuff +(I do have lots of books waiting to be read). I'm also someone who has to play +with something in order to understand it: trial and error is my modus operandi. +Eventually it's my intended usage that drives the interface and that is when +everything comes together. + +Exploring this technology comes down to: locate a font, get the \OPENTYPE\ 1.8 +specification from the \MICROSOFT\ website, and try to figure out what is in the +font. When I had a rough idea the next step was to get to the shapes and see if I +could manipulate them. Of course it helped that in \CONTEXT\ we already can load +fonts and play with shapes (using \METAPOST). I didn't have to install and learn +other programs. Once I could render them, in this case by creating a virtual font +with inline \PDF\ literals, a next step was to apply variation. Then came the +first experiments with a possible user interface. Seeing more variation then +drove the exploration of additional properties needed for typesetting, like +features. + +The main extension to the data packaged in a font file concerns the (to be +discussed) axis along which variable fonts operate and deltas to be applied to +coordinates. The \type {gdef} table has been extended and contains information +that is used in \type {gpos} features. There are new \type {hvar}, \type {vvar} +and \type {mvar} tables that influence the horizontal, vertical and general font +dimensions. The \type {gvar} table is used for \TRUETYPE\ variants, while the +\type {cff2} table replaces the \type {cff} table for \OPENTYPE\ \POSTSCRIPT\ +outlines. The \type {avar} and \type {stat} tables contain some +meta|-|information about the axes of variations. + +It must be said that because this is new technology the information in the +standard is not always easy to understand. The fact that we have two rendering +techniques, \POSTSCRIPT\ \type {cff} and \TRUETYPE\ \type {ttf}, also means that +we have different information and perspectives. But this situation is not much +different from \OPENTYPE\ standards a few years ago: it takes time but in the end +I will get there. And, after all, users also complain about the lack of +documentation for \CONTEXT, so who am I to complain? In fact, it will be those +\CONTEXT\ users who will provide feedback and make the implementation better in +the~end. + +\stopsubject + +\startsubject[title=Loading] + +Before we discuss some details, it will be useful to summarize what the font +loader does when a user requests a font at a certain size and with specific +features enabled. When a font is used the first time, its binary format is +converted into a form that makes it suitable for use within \CONTEXT\ and +therefore \LUATEX. This conversion involves collecting properties of the font as +a whole (official names, general dimensions like x-height and em-width, etc.), of +glyphs (dimensions, \UNICODE\ properties, optional math properties), and all +kinds of information that relates to (contextual) replacements of glyphs (small +caps, oldstyle, scripts like Arabic) and positioning (kerning, anchoring marks, +etc.). In the \CONTEXT\ font loader this conversion is done in \LUA. + +The result is stored in a condensed format in a cache and the next time the font +is needed it loads in an instant. In the cached version the dimensions are +untouched, so a font at different sizes has just one copy in the cache. Often a +font is needed at several sizes and for each size we create a copy with scaled +glyph dimensions. The feature-related dimensions (kerning, anchoring, etc.)\ are +shared and scaled when needed. This happens when sequences of characters in the +node list get converted into sequences of glyphs. We could do the same with glyph +dimensions but one reason for having a scaled copy is that this copy can also +contain virtual glyphs and these have to be scaled beforehand. In practice there +are several layers of caching in order to keep the memory footprint within +reasonable bounds. \footnote {In retrospect one can wonder if that makes sense; +just look at how much memory a browser uses when it has been open for some time. +In the beginning of \LUATEX\ users wondered about caching fonts, but again, just +look at what amounts browsers cache: it gets pretty close to the average amount +of writes that a \SSD\ can handle per day within its guarantee.} + +When the font is actually used, interaction between characters is resolved using +the feature|-|related information. When for instance two characters need to be +kerned, a lookup results in the injection of a kern, scaled from general +dimensions to the current size of the font. + +When the outlines of glyphs are needed in \METAFUN\ the font is also converted +from its binary form to something in \LUA, but this time we filter the shapes. +For a \type {cff} this comes down to interpreting the \type {charstrings} and +reducing the complexity to \type {moveto}, \type {lineto} and \type {curveto} +operators. In the process subroutines are inlined. The result is something that +\METAPOST\ is happy with but that also can be turned into a piece of a \PDF. + +We now come to what a variable font actually is: a basic design which is +transformed along one or more axes. A simple example is wider shapes: + +\startlinecorrection +\startMPcode +for i=1 upto 4 : + fill fullsquare xyscaled (i*.5cm,1cm) shifted (i*2.5*cm,0) withcolor "darkgray"; + fill fullcircle xyscaled (2.5mm,2.5mm) shifted (i*2.5*cm,0) withcolor "lightgray" ; +endfor ; +\stopMPcode +\stoplinecorrection + +We can also go taller and retain the width: + +\startlinecorrection +\startMPcode +for i=1 upto 4 : + fill fullsquare xyscaled (1cm,i*.5cm) shifted (i*2.5*cm,0) withcolor "darkgray"; + fill fullcircle xyscaled (2.5mm,2.5mm) shifted (i*2.5*cm,0) withcolor "lightgray" ; +endfor ; +\stopMPcode +\stoplinecorrection + +Here we have a linear scaling but glyphs are not normally done that way. There +are font collections out there with lots of intermediate variants (say from light +to heavy) and it's more profitable to sell each variant independently. However, +there is often some logic behind it, probably supported by programs that +designers use, so why not build that logic into the font and have one file that +represents many intermediate forms. In fact, once we have multiple axes, even +when the designer has clear ideas of the intended usage, nothing will prevent +users from tinkering with the axis properties in ways that will fulfil their +demands but hurt the designers eyes. We will not discuss that dilemma here. + +When a variable font follows the route described above, we face a problem. When +you load a \TRUETYPE\ font it will just work. The glyphs are packaged in the same +format as static fonts. However, a variable font has axes and on each axis a +value can be set. Each axis has a minimum, maximum and default. It can be that +the default instance also assumes some transformations are applied. The standard +recommends adding tables to describe these things but the fonts that I played +with each lacked such tables. So that leaves some guesswork. But still, just +loading a \TRUETYPE\ font gives some sort of outcome, although the dimensions +(widths) might be weird due to lack of a (default) axis being applied. + +An \OPENTYPE\ font with \POSTSCRIPT\ outlines is different: the internal \type +{cff} format has been upgraded to \type {cff2} which on the one hand is less +complicated but on the other hand has a few new operators \emdash\ which results +in programs that have not been adapted complaining or simply quitting on them. + +One could argue that a font is just a resource and that one only has to pass it +along but that's not what works well in practice. Take \LUATEX. We can of course +load the font and apply axis vales so that we can process the document as we +normally do. But at some point we have to create a \PDF. We can simply embed the +\TRUETYPE\ files but no axis values are applied. This is because, even if we add +the relevant information, there is no way in current \PDF\ formats to deal with +it. For that, we should be able to pass all relevant axis|-|related information +as well as specify what values to use along these axes. And for \TRUETYPE\ fonts +this information is not part of the shape description so then we in fact need to +filter and pass more. An \OPENTYPE\ \POSTSCRIPT\ font is much cleaner because +there we have the information needed to transform the shape mostly in the glyph +description. There we only need to carry some extra information on how to apply +these so|-|called blend values. The region|/|axis model used there only demands +passing a relatively simple table (stripped down to what we need). But, as said +above, \type {cff2} is not backward-compatible so a viewer will (currently) +simply not show anything. + +Recalling how we load fonts, how does that translate with variable changes? If we +have two characters with glyphs that get transformed and that have a kern between +them, the kern may or may not transform. So, when we choose values on an axis, +then not only glyph properties change but also relations. We no longer can share +positional information and scale afterwards because each instance can have +different values to start with. We could carry all that information around and +apply it at runtime but because we're typesetting documents with a static design +it's more convenient to just apply it once and create an instance. We can use the +same caching as mentioned before but each chosen instance (provided by the font +or made up by user specifications) is kept in the cache. As a consequence, using +a variable font has no overhead, apart from initial caching. + +So, having dealt with that, how do we proceed? Processing a font is not different +from what we already had. However, I would not be surprised if users are not +always satisfied with, for instance, kerning, because in such fonts a lot of care +has to be given to this by the designer. Of course I can imagine that programs +used to create fonts deal with this, but even then, there is a visual aspect to +it too. The good news is that in \CONTEXT\ we can manipulate features so in +theory one can create a so|-|called font goodie file for a specific instance. + +\stopsubject + +\startsubject[title=Shapes] + +For \OPENTYPE\ \POSTSCRIPT\ shapes we always have to do a dummy rendering in +order to get the right bounding box information. For \TRUETYPE\ this information +is already present but not when we use a variable instance, so I had to do a bit +of coding for that. Here we face a problem. For \TEX\ we need the width, height +and depth of a glyph. Consider the following case: + +\startlinecorrection +\startMPcode +path p ; p := fullcircle xysized (3cm,2cm) ; +fill p + withcolor "lightgray" ; +draw boundingbox currentpicture + withpen pencircle scaled .5mm + withcolor "darkgray" ; +setbounds currentpicture to p ; +draw boundingbox currentpicture + leftenlarged 2mm rightenlarged 5mm ; +\stopMPcode +\stoplinecorrection + +The shape has a bounding box that fits the shape. However, its left corner is not +at the origin. So, when we calculate a tight bounding box, we cannot use it for +actually positioning the glyph. We do use it (for horizontal scripts) to get the +height and depth but for the width we depend on an explicit value. In \OPENTYPE\ +\POSTSCRIPT\ we have the width available and how the shape is positioned relative +to the origin doesn't much matter. In a \TRUETYPE\ shape a bounding box is part +of the specification, as is the width, but for a variable font one has to use +so-called phantom points to recalculate the width and the test fonts I had were +not suitable for investigating this. + +At any rate, once I could generate documents with typeset text using variable +fonts it became time to start thinking about a user interface. A variable font +can have predefined instances but of course a user also wants to mess with axis +values. Take one of the test fonts: Adobe Variable Font Prototype. It has several +instances: + +\unexpanded\def\SampleFont#1#2#3% + {\NC #2 + \NC \definedfont[name:#1#3*default]It looks like this! + \normalexpanded{\noexpand\NC\currentfontinstancespec} + \NC \NR} + +\starttabulate[|||T|] +\SampleFont {adobevariablefontprototype} {extralight} {extralight} +\SampleFont {adobevariablefontprototype} {light} {light} +\SampleFont {adobevariablefontprototype} {regular} {regular} +\SampleFont {adobevariablefontprototype} {semibold} {semibold} +\SampleFont {adobevariablefontprototype} {bold} {bold} +\SampleFont {adobevariablefontprototype} {black high contrast} {blackhighcontrast} +\SampleFont {adobevariablefontprototype} {black medium contrast} {blackmediumcontrast} +\SampleFont {adobevariablefontprototype} {black} {black} +\stoptabulate + +Such an instance is accessed with: + +\starttyping +\definefont + [MyLightFont] + [name:adobevariablefontprototypelight*default] +\stoptyping + +The Avenir Next variable demo font (currently) provides: + +\starttabulate[|||T|] +\SampleFont {avenirnextvariable} {regular} {regular} +\SampleFont {avenirnextvariable} {medium} {medium} +\SampleFont {avenirnextvariable} {bold} {bold} +\SampleFont {avenirnextvariable} {heavy} {heavy} +\SampleFont {avenirnextvariable} {condensed} {condensed} +\SampleFont {avenirnextvariable} {medium condensed} {mediumcondensed} +\SampleFont {avenirnextvariable} {bold condensed} {boldcondensed} +\SampleFont {avenirnextvariable} {heavy condensed} {heavycondensed} +\stoptabulate + +Before we continue I will show a few examples of variable shapes. Here we use some +\METAFUN\ magic. Just take these definitions for granted. + +\startbuffer[a] +\startMPcode + draw outlinetext.b + ("\definedfont[name:adobevariablefontprototypeextralight]foo@bar") + (withcolor "gray") + (withcolor red withpen pencircle scaled 1/10) + xsized .45TextWidth ; +\stopMPcode +\stopbuffer + +\startbuffer[b] +\startMPcode + draw outlinetext.b + ("\definedfont[name:adobevariablefontprototypelight]foo@bar") + (withcolor "gray") + (withcolor red withpen pencircle scaled 1/10) + xsized .45TextWidth ; +\stopMPcode +\stopbuffer + +\startbuffer[c] +\startMPcode + draw outlinetext.b + ("\definedfont[name:adobevariablefontprototypebold]foo@bar") + (withcolor "gray") + (withcolor red withpen pencircle scaled 1/10) + xsized .45TextWidth ; +\stopMPcode +\stopbuffer + +\startbuffer[d] +\startMPcode + draw outlinetext.b + ("\definefontfeature[whatever][axis={weight:350}]% + \definedfont[name:adobevariablefontprototype*whatever]foo@bar") + (withcolor "gray") + (withcolor red withpen pencircle scaled 1/10) + xsized .45TextWidth ; +\stopMPcode +\stopbuffer + +\typebuffer[a,b,c,d] + +The results are shown in \in {figure} [fig:whatever:1]. What we see here is that +as long as we fill the shape everything will look as expected but using an +outline only won't. The crucial (control) points are moved to different locations +and as a result they can end up inside the shape. Giving up outlines is the price +we evidently need to pay. Of course this is not unique for variable fonts +although in practice static fonts behave better. To some extent we're back to +where we were with \METAFONT\ and (for instance) Computer Modern: because these +originate in bitmaps (and probably use similar design logic) we also can have +overlap and bits and pieces pasted together and no one will notice that. The +first outline variants of Computer Modern also had such artifacts while in the +static Latin Modern successors, outlines were cleaned up. + +\startplacefigure[title=Four variants,reference=fig:whatever:1] + \startcombination[2*2] + {\getbuffer[a]} {a} + {\getbuffer[b]} {b} + {\getbuffer[c]} {d} + {\getbuffer[d]} {c} + \stopcombination +\stopplacefigure + +The fact that we need to preprocess an instance but only know how to do that when +we have gotten the information about axis values from the font means that the +font handler has to be adapted to keep caching correct. Another definition is: + +\starttyping +\definefontfeature + [lightdefault] + [default] + [axis={weight:230,contrast:50}] + +\definefont + [MyLightFont] + [name:adobevariablefontprototype*lightdefault] +\stoptyping + +Here the complication is that where normally features are dealt with after +loading, the axis feature is part of the preparation (and caching). If you want +the virtual font solution you can do this: + +\starttyping +\definefontfeature + [inlinelightdefault] + [default] + [axis={weight:230,contrast:50}, + variableshapes=yes] + +\definefont + [MyLightFont] + [name:adobevariablefontprototype*inlinelightdefault] +\stoptyping + +When playing with these fonts it was hard to see if loading was done right. For +instance not all values make sense. It is beyond the scope of this article, but +axes like weight, width, contrast and italic values get applied differently to +so|-|called regions (subspaces). So say that we have an $x$ coordinate with value +$50$. This value can be adapted in, for instance, four subspaces (regions), so we +actually get: + +\startformula + x^\prime = x + + s_1 \times x_1 + + s_2 \times x_2 + + s_3 \times x_3 + + s_4 \times x_4 +\stopformula + +The (here) four scale factors $s_n$ are determined by the axis value. Each axis +has some rules about how to map the values $230$ for weight and $50$ for contrast +to such a factor. And each region has its own translation from axis values to +these factors. The deltas $x_1,\dots,x_4$ are provided by the font. For a +\POSTSCRIPT|-|based font we find sequences like: + +\starttyping +1 <setvstore> +120 [10 -30 40 -60] 1 <blend> ... <operator> +100 120 [10 -30 40 -60] [30 -10 -30 20] 2 <blend> .. <operator> +\stoptyping + +A store refers to a region specification. From there the factors are calculated +using the chosen values on the axis. The deltas are part of the glyphs +specification. Officially there can be multiple region specifications, but how +likely it is that they will be used in real fonts is an open question. + +For \TRUETYPE\ fonts the deltas are not in the glyph specification but in a +dedicated \type {gvar} table. + +\starttyping +apply x deltas [10 -30 40 -60] to x 120 +apply y deltas [30 -10 -30 20] to y 100 +\stoptyping + +Here the deltas come from tables outside the glyph specification and their +application is triggered by a combination of axis values and regions. + +The following two examples use Avenir Next Variable and demonstrate that kerning +is adapted to the variant. + +\startbuffer +\definefontfeature + [default:shaped] + [default] + [axis={width:10}] + +\definefont + [SomeFont] + [file:avenirnextvariable*default:shaped] +\stopbuffer + +\typebuffer \getbuffer + +\start \showglyphs \showfontkerns \SomeFont \input zapf \wordright{Hermann Zapf}\par \stop + +\startbuffer +\definefontfeature + [default:shaped] + [default] + [axis={width:100}] + +\definefont + [SomeFont] + [file:avenirnextvariable*default:shaped] +\stopbuffer + +\typebuffer \getbuffer + +\start \showglyphs \showfontkerns \SomeFont \input zapf \wordright{Hermann Zapf}\par \stop + +\stopsubject + +\startsubject[title=Embedding] + +Once we're done typesetting and a \PDF\ file has to be created there are three +possible routes: + +\startitemize + \startitem + We can embed the shapes as \PDF\ images (inline literal) using virtual + font technology. We cannot use so|-|called xforms here because we want to + support color selectively in text. + \stopitem + \startitem + We can wait till the \PDF\ format supports such fonts, which might happen + but even then we might be stuck for years with viewers getting there. Also + documents need to get printed, and when printer support might + arrive is another unknown. + \stopitem + \startitem + We can embed a regular font with shapes that match the chosen values on the + axis. This solution is way more efficient than the first. + \stopitem +\stopitemize + +Once I could interpret the right information in the font, the first route was the +way to go. A side effect of having a converter for both outline types meant that +it was trivial to create a virtual font at runtime. This option will stay in +\CONTEXT\ as pseudo|-|feature \type {variableshapes}. + +When trying to support variable fonts I tried to limit the impact on the backend +code. Also, processing features and such was not touched. The inclusion of the +right shapes is done via a callback that requests the blob to be injected in the +\type {cff} or \type {glyf} table. When implementing this I actually found out +that the \LUATEX\ backend also does some juggling of charstrings, to serve the +purpose of inlining subroutines. In retrospect I could have learned a few tricks +faster by looking at that code but I never realized that it was there. Looking at +the code again, it strikes me that the whole inclusion could be done with \LUA\ +code and some day I will give that a try. + +\stopsubject + +\startsubject[title=Conclusion] + +When I first heard about variable fonts I was confident that when they showed up +they could be supported. Of course a specimen was needed to prove this. A first +implementation demonstrates that indeed it's no big deal to let \CONTEXT\ with +\LUATEX\ handle such fonts. Of course we need to fill in some gaps which can be +done once we have complete fonts. And then of course users will demand more +control. In the meantime the helper script that deals with identifying fonts by +name has been extended and the relevant code has been added to the distribution. +At some point the \CONTEXT\ Garden will provide the \LUATEX\ binary that has the +callback. + +I end with a warning. On the one hand this technology looks promising but on the +other hand one can easily get lost. Probably most such fonts operate over a +well|-|defined domain of values but even then one should be aware of complex +interactions with features like positioning or replacements. Not all combinations +can be tested. It's probably best to stick to fonts that have all the relevant +tables and don't depend on properties of a specific rendering technology. + +Although support is now present in the core of \CONTEXT\ the official release +will happen at the \CONTEXT\ meeting in 2017. By then I hope to have tested more +fonts. Maybe the interface has also been extended by then because after all, +\TEX\ is about control. + +\stopsubject + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/onandon/onandon.tex b/doc/context/sources/general/manuals/onandon/onandon.tex new file mode 100644 index 000000000..60b626a5e --- /dev/null +++ b/doc/context/sources/general/manuals/onandon/onandon.tex @@ -0,0 +1,56 @@ +% 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 have been published in TugBoat, the NTG Maps, the ConTeXt Group +% journal or otherwise. Thanks to the editors for corrections. + +% Timestamp: I started this document in the week https://www.youtube.com/watch?v=PFWz_6hnAEI +% showed up --- and there's more of this bbc performance --- it's this kind of the stuff that +% keeps me going 'on and on' .. Jacob C, Cory H, Snarky P, Jules B with orchestra ... it can't +% get any better I guess (although .. what would happen if we add Gavin H to that equation). +% And when looking at https://www.youtube.com/watch?v=c5FqpddnJmc ... it's the kind of innovation +% in music that reminds me of first hearing Kate Bush (equally young when she showed up). + +\environment onandon-environment + +\startproduct onandon + +\component onandon-titlepage + +\startfrontmatter + \component onandon-contents + \component onandon-introduction +\stopfrontmatter + +\startbodymatter + \component onandon-decade + \component onandon-ffi + % \startchapter[title=Variable fonts] First published in user group magazines. \stopchapter + \component onandon-variable + \component onandon-emoji + \startchapter[title={Children of \TEX}] First published in user group magazines. \stopchapter + % \component onandon-children + \component onandon-performance + \component onandon-editing + \startchapter[title={Advertising \TEX}] First published in user group magazines. \stopchapter + % \component onandon-perception + \startchapter[title={Tricky fences}] First published in user group magazines. \stopchapter + % \component onandon-fences + % \component onandon-media + \startchapter[title={From 5.2 to 5.3}] Maybe first published in user group magazines. \stopchapter + % \component onandon-53 + \startchapter[title={Executing \TEX}] Maybe first published in user group magazines. \stopchapter + % \component onandon-execute +\stopbodymatter + +\stopproduct diff --git a/doc/context/sources/general/manuals/pagecolumns/pagecolumns-000.tex b/doc/context/sources/general/manuals/pagecolumns/pagecolumns-000.tex new file mode 100644 index 000000000..418595aa1 --- /dev/null +++ b/doc/context/sources/general/manuals/pagecolumns/pagecolumns-000.tex @@ -0,0 +1,72 @@ +% content=tex +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\startenvironment pagecolumns-000 + +\usemodule[visual,simulate] + +\dontcomplain + +\useMPlibrary[dum] + +\setupbodyfont + [palatino] + +\setuplayout + [grid=yes] + +\setuplayout + [backspace=20mm, + cutspace=15mm, + width=middle, + height=middle] + +\setupsystem + [random=1234] + +\setuppagenumbering + [alternative=doublesided, + location=] + +\setupheadertexts + [pagenumber][right] + [left][pagenumber] + +\setupfootertexts + [\inputfilename] + +\setupfooter + [color=black, + style=\tttf] + +\setupheader + [color=black, + style=\tttf] + +\setuptolerance + [verytolerant,stretch] + +\definecolor[color-3][.5(red,black)] +\definecolor[color-2][.5(green,black)] +\definecolor[color-1][.5(blue,black)] +\definecolor[color-4][.5(white,black)] +\definecolor[color-5][.5(white,color-4)] + +\definecolor[fakerulecolor][white] + +\setupcolors + [textcolor=white] + +\startuniqueMPgraphic{frame} + fill OverlayBox withcolor \MPcolor{color-1} ; +\stopuniqueMPgraphic + +\startuniqueMPgraphic{contrast} + fill OverlayBox withcolor \MPcolor{color-3} ; +\stopuniqueMPgraphic + +\defineoverlay[frame] [\uniqueMPgraphic{frame}] +\defineoverlay[contrast][\uniqueMPgraphic{contrast}] + +\stopenvironment diff --git a/doc/context/sources/general/manuals/pagecolumns/pagecolumns-001.tex b/doc/context/sources/general/manuals/pagecolumns/pagecolumns-001.tex new file mode 100644 index 000000000..afdca49aa --- /dev/null +++ b/doc/context/sources/general/manuals/pagecolumns/pagecolumns-001.tex @@ -0,0 +1,24 @@ +% content=tex +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\environment pagecolumns-000 + +\definepagecolumns + [example] + [n=2] + +\setupbackgrounds + [text] + [background=color, + backgroundcolor=color-1] + +\starttext + +\startpagecolumns[example] + + \dorecurse{20}{\fakewords{100}{200}\par} + +\stoppagecolumns + +\stoptext diff --git a/doc/context/sources/general/manuals/pagecolumns/pagecolumns-002.tex b/doc/context/sources/general/manuals/pagecolumns/pagecolumns-002.tex new file mode 100644 index 000000000..d425d3b82 --- /dev/null +++ b/doc/context/sources/general/manuals/pagecolumns/pagecolumns-002.tex @@ -0,0 +1,79 @@ +% content=tex +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\environment pagecolumns-000 + +\definepagecolumns + [example] + [n=3, + distance=\emwidth] + +\setupbackgrounds + [text] + [background=color, + backgroundcolor=color-1] + +\starttext + +\startpagecolumns[example] + +\dorecurse {7} { + \startplacefigure[location={here,none}] + \framed + [width=\columnwidth, + height=1cm, + frame=off, + background=color, + backgroundcolor=color-2] + {Here: A.#1} + \stopplacefigure + \samplefile{tufte} + \startplacefigure[location={here,none}] + \framed + [width=\columnwidth, + height=1cm, + frame=off, + background=color, + backgroundcolor=color-2] + {Here: B.#1} + \stopplacefigure + \samplefile{tufte} + \startplacefigure[location={here,none}] + \framed + [width=\textwidth, + height=1cm, + frame=off, + background=color, + backgroundcolor=color-2] + {Here: C.#1} + \stopplacefigure + \startplacefigure[location={here,none}] + \framed + [width=\measure{twocolumns}, + height=1cm, + frame=off, + background=color, + backgroundcolor=color-2] + {Here: D.#1} + \stopplacefigure + \samplefile{tufte} + \startplacefigure[location={force,none}] + \framed + [width=\columnwidth, + height=1cm, + frame=off, + background=color, + backgroundcolor=color-2] + {Force: E.#1} + \stopplacefigure +} + +\dorecurse {7} { + \samplefile{tufte} + \par +} + +\stoppagecolumns + +\stoptext diff --git a/doc/context/sources/general/manuals/pagecolumns/pagecolumns-003.tex b/doc/context/sources/general/manuals/pagecolumns/pagecolumns-003.tex new file mode 100644 index 000000000..544458b34 --- /dev/null +++ b/doc/context/sources/general/manuals/pagecolumns/pagecolumns-003.tex @@ -0,0 +1,53 @@ +% content=tex +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\environment pagecolumns-000 + +\definepagecolumns + [example] + [n=3, + distance=\emwidth] + +\setupbackgrounds + [text] + [background=color, + backgroundcolor=color-1] + +\starttext + +\startpagecolumns[example] + +\dorecurse {7} { + \startplacefigure[location={top,none}] + \framed + [width=\textwidth, + height=1cm, + frame=off, + background=color, + backgroundcolor=color-2] + {A.#1} + \stopplacefigure + \startplacefigure[location={top,none}] + \framed + [width=\measure{twocolumns}, + height=1cm, + frame=off, + background=color, + backgroundcolor=color-3] + {B.#1} + \stopplacefigure + \samplefile{tufte} + \par +} + +\dorecurse {7} { + \samplefile{tufte} + \par +} + +\stoppagecolumns + +\stoptext + + diff --git a/doc/context/sources/general/manuals/pagecolumns/pagecolumns-004.tex b/doc/context/sources/general/manuals/pagecolumns/pagecolumns-004.tex new file mode 100644 index 000000000..2144d399b --- /dev/null +++ b/doc/context/sources/general/manuals/pagecolumns/pagecolumns-004.tex @@ -0,0 +1,54 @@ +% content=tex +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\environment pagecolumns-000 + +\definepagecolumns + [example] + [n=3, + distance=\emwidth] + +\setupbackgrounds + [text] + [background=color, + backgroundcolor=color-1] + +\starttext + +\startpagecolumns[example] + +\dorecurse {7} { + + \startplacefigure[location={top,none}] + \framed + [width=1cm, + height=1cm, + frame=off, + background=color, + backgroundcolor=color-2] + {A.#1} + \stopplacefigure + + \startplacefigure[location={left,none}] + \framed + [width=1cm, + height=1cm, + frame=off, + background=color, + backgroundcolor=color-2] + {A.#1} + \stopplacefigure + + \samplefile{tufte} + \footnote{foo #1.1} + \footnote{foo #1.2} + + \par +} + +\stoppagecolumns + +\stoptext + + diff --git a/doc/context/sources/general/manuals/pagecolumns/pagecolumns-005.tex b/doc/context/sources/general/manuals/pagecolumns/pagecolumns-005.tex new file mode 100644 index 000000000..c714879fd --- /dev/null +++ b/doc/context/sources/general/manuals/pagecolumns/pagecolumns-005.tex @@ -0,0 +1,52 @@ +% content=tex +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\environment pagecolumns-000 + +\definepagecolumns + [example] + [n=3, + distance=\emwidth] + +\setupbackgrounds + [text] + [background=color, + backgroundcolor=color-1] + +\starttext + +\startpagecolumns[example] + +\dorecurse {7} { + + \startplacefigure[location={top,none}] + \framed + [width=1cm, + height=1cm, + frame=off, + background=color, + backgroundcolor=color-2] + {A.#1} + \stopplacefigure + + \startplacefigure[location={left,none}] + \framed + [width=1cm, + height=6cm, + frame=off, + background=color, + backgroundcolor=color-2] + {B.#1} + \stopplacefigure + + \samplefile{klein}\par + \samplefile{klein}\par + +} + +\stoppagecolumns + +\stoptext + + diff --git a/doc/context/sources/general/manuals/pagecolumns/pagecolumns-006.tex b/doc/context/sources/general/manuals/pagecolumns/pagecolumns-006.tex new file mode 100644 index 000000000..b56470bbc --- /dev/null +++ b/doc/context/sources/general/manuals/pagecolumns/pagecolumns-006.tex @@ -0,0 +1,45 @@ +% content=tex +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\environment pagecolumns-000 + +\definepagecolumns + [example] + [n=3, + distance=\emwidth] + +\setupbackgrounds + [text] + [background=color, + backgroundcolor=color-1] + +\starttext + +\startpagecolumns[example] + +\dorecurse {20} { + HERE #1.1 + \samplefile{klein}\column + \samplefile{klein}\page +} + +\page[right] + +RIGHT PAGE + +\page[left] + +LEFT PAGE + +\dorecurse {20} { + HERE #1.2 + \samplefile{klein}\column + \samplefile{klein}\page +} + +\stoppagecolumns + +\stoptext + + diff --git a/doc/context/sources/general/manuals/pagecolumns/pagecolumns-007.tex b/doc/context/sources/general/manuals/pagecolumns/pagecolumns-007.tex new file mode 100644 index 000000000..aefa62588 --- /dev/null +++ b/doc/context/sources/general/manuals/pagecolumns/pagecolumns-007.tex @@ -0,0 +1,70 @@ +% content=tex +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\environment pagecolumns-000 + +\definepagecolumns[example][n=2,distance=\emwidth] + +\setupbackgrounds[text][background=color,backgroundcolor=color-1] + +\useMPlibrary[dum] + +\starttext + +\startbuffer[small] + \framed + [width=3cm, + height=2cm, + frame=off, + background=color, + backgroundcolor=color-2] + {Small} +\stopbuffer + +\startbuffer[large] + \framed + [width=12cm, + height=6cm, + frame=off, + background=color, + backgroundcolor=color-2] + {Large} +\stopbuffer + +\startpagecolumns[example] + \samplefile{tufte}\par + \startplacefigure[location=here,title=Test] + \getbuffer[small] + \stopplacefigure + \startplacefigure[location=here,title=Test] + \getbuffer[small] + \stopplacefigure + \samplefile{tufte}\par +\stoppagecolumns + +\startpagecolumns[example] + \samplefile{tufte}\par + \startplacefigure[location=here,title=Test] + \getbuffer[small] + \stopplacefigure + \startplacefigure[location=here,title=Test] + \getbuffer[large] + \stopplacefigure + \samplefile{tufte}\par +\stoppagecolumns + +\startpagecolumns[example] + \samplefile{tufte}\par + \startplacefigure[location=here,title=Test] + \getbuffer[large] + \stopplacefigure + \startplacefigure[location=here,title=Test] + \getbuffer[large] + \stopplacefigure + \samplefile{tufte}\par +\stoppagecolumns + +\stoptext + + diff --git a/doc/context/sources/general/manuals/pagecolumns/pagecolumns.tex b/doc/context/sources/general/manuals/pagecolumns/pagecolumns.tex new file mode 100644 index 000000000..40a396e1b --- /dev/null +++ b/doc/context/sources/general/manuals/pagecolumns/pagecolumns.tex @@ -0,0 +1,395 @@ +% macros=mkvi language=uk + +\definemeasure[onecolumn] [\columnwidth] +\definemeasure[twocolumns] [\dimexpr\plustwo \columnwidth+ \columndistance\relax] +\definemeasure[threecolumns][\dimexpr\plusthree\columnwidth+\plustwo \columndistance\relax] +\definemeasure[fourcolumns] [\dimexpr\plusfour \columnwidth+\plusthree\columndistance\relax] + +\usemodule[abr-04] + +\setupbodyfont + [dejavu,11pt] + +\definefont[QuiteLarge][SansBold sa 2.50] +\definefont[NotSoLarge][SansBold sa 1.25] + +\setuplayout + [backspace=.1\paperwidth, + topspace=.025\paperheight, + header=0.025\paperheight, + footer=0.025\paperheight, + headerdistance=0.025\paperheight, + footerdistance=0.025\paperheight, + width=middle, + height=middle] + +\setuppagenumbering + [alternative=doublesided, + location=] + +\setupwhitespace + [line] + +\setupblank + [line] + +\setuptyping + [blank=halfline] + +\startsetups [pagenumber] + \hbox to .2\paperwidth { + \hss + Page \pagenumber + \hss + } +\stopsetups + +\setupfooter [before=\vfill,after=\vfill,style=\bf,color=color-4] +\setupheader [before=\vfill,after=\vfill,style=\bf,color=color-4] + +\setupfootertexts [] [\setups{pagenumber}] +\setupheadertexts [] [\setups{chapterhead}] + +\startsetups [chapterhead] + \hbox to .2\paperwidth { + \hss + \getmarking[chapter] + \hss + } +\stopsetups + +\setuphead + [chapter] + [header=empty] + +\definecolor[color-3][.5(red,black)] +\definecolor[color-2][.5(green,black)] +\definecolor[color-1][.5(blue,black)] +\definecolor[color-4][.5(white,black)] +\definecolor[color-5][.5(white,color-4)] +\definecolor[color-6][.2(white,color-4)] + +\definecolor[fakerulecolor][white] + +\usemodule[typesetting] + +\setupcombination + [style=mono] + +\startuseMPgraphic{page} +StartPage ; + path p ; + numeric n; n := PageNumber ; + numeric w; w := bbwidth(Page) ; + numeric h; h := bbheight(Page) ; + def DrawBit (expr bit, dx, dy) = + path p ; p := unitsquare xyscaled(w/5,h/40) shifted (dx*w/10,dy*(h-h/40)) ; + if n div bit > 0 : + n := n - (n div bit)*bit ; + fill p withcolor \MPcolor{color-1} ; + else : + fill p withcolor \MPcolor{color-2} ; + fi ; + enddef ; + DrawBit(32,7,1) ; + DrawBit(16,4,1) ; + DrawBit( 8,1,1) ; + DrawBit( 4,7,0) ; + DrawBit( 2,4,0) ; + DrawBit( 1,1,0) ; +StopPage ; +\stopuseMPgraphic + +\startuniqueMPgraphic{frame} + fill OverlayBox withcolor \MPcolor{color-5} ; +\stopuniqueMPgraphic + +\startuniqueMPgraphic{contrast} + fill OverlayBox withcolor \MPcolor{color-4} ; +\stopuniqueMPgraphic + +\defineoverlay[page] [\useMPgraphic{page}] +\defineoverlay[frame] [\useMPgraphic{frame}] +\defineoverlay[contrast][\useMPgraphic{contrast}] + +\setuphead + [chapter] + [style=\QuiteLarge, + color=color-3, + number=no] + +\setuplist + [chapter] + [command=\MyListCommand, + alternative=command] + +\starttexdefinition unexpanded MyListCommand #1#2#3 + \snaptogrid + [line,-line]\vbox { + \tfb + \setstrut + \strut#2 + \quad#3 + } +\stoptexdefinition + +\setupmargindata + [style=\tttf, + color=color-3] + +\starttexdefinition unexpanded ShowFile #1 + \margintext + {\cldcontext{string.match("#1","\letterpercent d+")}} + \typefile + [range={environment}] + {#1} +\stoptexdefinition + +% \typefile[range=4] {...} +% \typefile[range={=}]{...} % start after comment lines + +\starttexdefinition unexpanded ShowEnvironmentFile #1 + \margintext + {\cldcontext{string.match("#1","\letterpercent d+")}} + \typefile + [range={=startenvironment}] + {#1} +\stoptexdefinition + +\startdocument + +\startMPpage +StartPage ; + path p ; numeric w, h, d ; picture q ; + if true : + q := image(draw textext.urt("\ssbf PAGES") withcolor \MPcolor{color-6}) ; + else : + q := image(draw textext.urt("\ssbf PAGECOLUMNS") withcolor \MPcolor{color-6}) ; + fi ; + w := bbwidth(Page) ; + h := bbheight(Page) ; + d := h/100 ; + fill Page withcolor \MPcolor{color-1} ; + p := Page xysized (w,d) ; + for i := 5d step 2d until h-5d : + fill p shifted (0,i) withcolor \MPcolor{color-2} ; + endfor + p := Page xysized(w/10,h) ; + for i = 0, .3, .6, .9 : + fill p shifted (i*w,0) withcolor \MPcolor{color-1} withtransparency(1,.75) ; + endfor ; + def do_it(expr sz, sh) = + p := Page xysized sz ; + fill p shifted sh withcolor \MPcolor{color-3} withtransparency(1,.5) ; + draw q xysized (bbwidth(p),bbheight(p)) shifted sh ; + enddef ; + do_it ((8w/10,13d),(.1w,81d)) ; + do_it ((5w/10,13d),(.4w,67d)) ; + do_it ((2w/10,17d),(.1w,20d)) ; + do_it ((2w/10,15d),(.1w,56d)) ; + do_it ((1w/10,10d),(.4w,40d)) ; + do_it ((2w/10,13d),(.7w,27d)) ; + draw textext.urt("\ssbf Hans Hagen") + xysized (5w/10,5d) + shifted (.4w,6d) + withcolor \MPcolor{color-5} ; +StopPage ; +\stopMPpage + +\page[empty] \setuppagenumber[number=1] + +\setupbackgrounds + [page] + [background=page] + +\starttitle[title=Contents] + + \placelist[chapter] + +\stoptitle + +\startchapter[title=Introduction] + +{\em This manual as well as the mechanism it describes is under construction. Don't +use page columns in production. Experimenting is of course fine.} + +The \TEX\ engine is a progressive typesetter: it takes input and does something +with it and can do that for quite a while. It can process massive input and +produce massive output. In that process it never looks back. Now, it is of course +possible to collect content and delay some aspects of the rendering but to what +extent that content can be manipulated is limited. In \LUATEX\ one can do a bit +more but even then the basic typesetting process is mostly linear. + +When a text gets typeset there are several properties that play a role: + +\startitemize +\startitem + the width of the lines in a paragraph which is the main unit of processing +\stopitem +\startitem + the target height of what gets output, normally this is the height of the + text area, excluding headers and footers +\stopitem +\startitem + the parameters that determine when the so called output routine gets called, + for instance successive broken lines, widow and club penalties +\stopitem +\startitem + the presence of so called inserts, for instance footnotes or floating bodies +\stopitem +\startitem + the space between lines and paragraphs +\stopitem +\startitem + explicitly entered elements or spacing or injected by macros hooked into for + instance \type {\everypar} +\stopitem +\stopitemize + +It is important to realize that \TEX\ has no concept of what a page is. It takes +input and occasionally hand over the intermediate result to the output routine. +There decisions are made to flush out a page, either of not with ornaments like +headers, footers, content left over from previous encounters, footnotes as well +as maybe specific trickery liked by the backend that targets at some viewer. + +That said, so called multi|-|column layouts are {\em not} part of the concepts +present in \TEX. As far as the engine is concerned there is only one column. +Among the reasons for not having a native mechanism for columns is that it is +very hard to come up with a mechanism for splitting them in ways that suits +everybody. In fact, the amount of control needed would make such a mechanism very +complex and still limited. You can compare this to math typesetting. That +subspace has some fixed characteristics if only because otherwise mathematicians +could not communicate. However, there is some control over spacing and one can to +some extend intervene. In \LUATEX\ some of the hard coded properties are made +configureable but still one gets pretty much what the engine considers right. +Such an approach would not work with columns. In fact, it doesn't even work well +with tables, for which \TEX\ provides the alignment mechanism: different kind of +tables demand different solutions, which is why in \CONTEXT\ we have old +fashioned tables, tabulated tables (that span pages and can contain paragraphs), +natural as well as extreme tables that resemble \HTML\ tables, line tables and +framed tables. + +So, when we want to support columns we need to write something in \TEX\ lingua +and for that the \type {\vsplit} operation can be of help. So far we have in +\CONTEXT\ four mechanisms: + +\startitemize[n] +\startitem + the original \MKII\ mechanism that permits mixed single and multi|-|column + text flows, with limited support for floating bodies +\stopitem +\startitem + a reimplementation of mixed columns in a mix of \TEX\ and \LUA, a bit better + with balancing and penalties for keeping section heads with the text, but + with very limited support for floating bodies; it works ok with grids +\stopitem +\startitem + a reimplementation of \MKII\ columnsets, a mechanism that is meant for + magazine like layouts where floats can span columns and positioned at will: + this one assumes relative simple text flows but as a bonus provides spreads; + this one is strongly grid based +\stopitem +\startitem + page based columns, where we use the normal (single column) page builder to + collect columns that then get combined into a page: this one is quite robust + but one has to keep an eye on floats as we don't span across columns + otherwise than in top or bottom floats but, on the other hand, one can use so + called side floats; this one is still experimental +\stopitem +\stopitemize + +Given specific demands one can come up with alternatives but it's very hard to +combine all demands into one mechanismn simply because anything can be part of +the text flow. Because it is not much fun to write such mechanisms and because +no project ever pays for fundamental development, one just has to accept what +\CONTEXT\ provides, be it with limitations. + +The first mechanism is more or less obsolete and replaced by the second. For +instance, we now use the second one when we have an itemize that demands columns. +I must admit that I don't like columns and never use them. I was involved in +projects where the designer wanted columns but in the end the complexity of the +content didn't work well with that that decision: inconsistent whitespace (due to +many small sections, lots of images, many tables, math formulas, etc) as well as +the result having more pages that the single column variant with side and margin +floats. Occasionally I use columned itemize or columned tables of contents and of +course registers are often in columns. + +One can wonder why columns are supported anyway. It's mostly useful for +newspapers that have wide pages or journals that have small print. For magazines +and special layout it's fine too although it can look bad when columns are narrow +and fancy layout tricks are used. I guess that at some point their use will +disappear. A document on a phone or tablet is one narrow columns. An internet +page is one long column. A printed book, given that there will be such items in +the future is normally typeset in one column. And journals as well as newspapers +more and more get replaced by media that better serve their purpose. So, apart +from an intellectual challenge, implementing extensive multi|-|column support is +a waste of energy. Which is why we can accept limitations. + +\stopchapter + +\startchapter[title=Just text] + +As with the other mechanism you can define a column instance and use that later. +You can also directly pass the settings with the \type {\startpagecolumns} command +but best is to define an instance. + +\FourPages{pagecolumns-001} + +\ShowFile{pagecolumns-001} + +We always start at a new page and end on a new one. Footnotes and such don't span +columns and we don't balance. When the number of columns equals one you get the +normal routine but with the requested settings. + +\stopchapter + +\startchapter[title=Floats] + +You can have floating bodies in columns. When a float doesn't fit it will be +flushed at the top of the next page. + +\FourPages{pagecolumns-002} + +\ShowFile{pagecolumns-002} + +\SixPages{pagecolumns-007} + +\ShowFile{pagecolumns-007} + +Side floats are also supported but we don't treat them special so you get the +same behaviour as with single column layouts. + +\FourPages{pagecolumns-005} + +\ShowFile{pagecolumns-005} + +\FourPages{pagecolumns-003} + +\ShowFile{pagecolumns-003} + + +\stopchapter + +\startchapter[title=Footnotes] + +Footnotes are supported but we assume sane usage. You can always revert to +endnotes if needed. + +\FourPages{pagecolumns-004} + +\ShowFile{pagecolumns-004} + +\stopchapter + +\startchapter[title=Pages] + +Going to a new page happens with \type {\page} and progressing to the next column +with \type {\column}. + +\FourSpread{pagecolumns-006} + +\ShowFile{pagecolumns-006} + +\stopchapter + +\stopdocument diff --git a/doc/context/sources/general/manuals/publications/122176.pdf b/doc/context/sources/general/manuals/publications/122176.pdf Binary files differnew file mode 100644 index 000000000..f8db03c1c --- /dev/null +++ b/doc/context/sources/general/manuals/publications/122176.pdf diff --git a/doc/context/sources/general/manuals/publications/124484.mol b/doc/context/sources/general/manuals/publications/124484.mol new file mode 100644 index 000000000..24800c395 --- /dev/null +++ b/doc/context/sources/general/manuals/publications/124484.mol @@ -0,0 +1,62 @@ +141125 + Marvin 01010811133D + + 13 13 0 0 0 0 999 V2000 + -0.1283 -2.5422 -0.0043 O 0 0 0 0 0 0 0 0 0 0 0 0 + 1.1658 -0.6138 0.0065 C 0 0 0 0 0 0 0 0 0 0 0 0 + -0.1195 -1.3196 -0.0021 C 0 0 0 0 0 0 0 0 0 0 0 0 + 1.0475 0.8443 -0.0012 C 0 0 0 0 0 0 0 0 0 0 0 0 + -1.2986 -0.6295 -0.0041 C 0 0 0 0 0 0 0 0 0 0 0 0 + -0.1554 1.4497 -0.0042 C 0 0 0 0 0 0 0 0 0 0 0 0 + -1.3072 0.7176 -0.0039 C 0 0 0 0 0 0 0 0 0 0 0 0 + 1.7474 -0.9159 -0.8684 H 0 0 0 0 0 0 0 0 0 0 0 0 + 1.7236 -0.9042 0.9004 H 0 0 0 0 0 0 0 0 0 0 0 0 + 1.8754 1.3949 -0.0035 H 0 0 0 0 0 0 0 0 0 0 0 0 + -2.1653 -1.1196 -0.0049 H 0 0 0 0 0 0 0 0 0 0 0 0 + -0.2061 2.4425 -0.0066 H 0 0 0 0 0 0 0 0 0 0 0 0 + -2.1794 1.1959 -0.0037 H 0 0 0 0 0 0 0 0 0 0 0 0 + 1 3 2 0 0 0 0 + 2 3 1 0 0 0 0 + 2 4 1 0 0 0 0 + 2 8 1 0 0 0 0 + 2 9 1 0 0 0 0 + 3 5 1 0 0 0 0 + 4 6 2 0 0 0 0 + 4 10 1 0 0 0 0 + 5 7 2 0 0 0 0 + 5 11 1 0 0 0 0 + 6 7 1 0 0 0 0 + 6 12 1 0 0 0 0 + 7 13 1 0 0 0 0 +M END + +> <PUBCHEM_BONDANNOTATIONS> +2 3 8 +2 4 8 +3 5 8 +4 6 8 +5 7 8 +6 7 8 + +> <StdInChI> +InChI=1S/C6H6O/c7-6-4-2-1-3-5-6/h1-4H,5H2 + +> <StdInChIKey> +WQPDQJCBHQPNCZ-UHFFFAOYSA-N + +> <AuxInfo> +1/0/N:6,7,4,5,2,3,1/rA:13nOCCCCCCHHHHHH/rB:;d1s2;s2;s3;d4;d5s6;s2;s2;s4;s5;s6;s7;/rC:-.1283,-2.5422,-.0043;1.1658,-.6138,.0065;-.1195,-1.3196,-.0021;1.0475,.8443,-.0012;-1.2986,-.6295,-.0041;-.1554,1.4497,-.0042;-1.3072,.7176,-.0039;1.7474,-.9159,-.8684;1.7236,-.9042,.9004;1.8754,1.3949,-.0035;-2.1653,-1.1196,-.0049;-.2061,2.4425,-.0066;-2.1794,1.1959,-.0037; + +> <Formula> +C6 H6 O + +> <Mw> +94.11124 + +> <SMILES> +O=C1C([H])=C([H])C([H])=C([H])C1([H])[H] + +> <CSID> +124484 + +$$$$ diff --git a/doc/context/sources/general/manuals/publications/124484.pdf b/doc/context/sources/general/manuals/publications/124484.pdf Binary files differnew file mode 100644 index 000000000..227a35b29 --- /dev/null +++ b/doc/context/sources/general/manuals/publications/124484.pdf diff --git a/doc/context/sources/general/manuals/publications/4953942.mol b/doc/context/sources/general/manuals/publications/4953942.mol new file mode 100644 index 000000000..9addc2281 --- /dev/null +++ b/doc/context/sources/general/manuals/publications/4953942.mol @@ -0,0 +1,54 @@ +6451477 + Marvin 12300719113D + + 13 13 0 0 0 0 999 V2000 + 0.0758 1.5048 0.6075 O 0 0 0 0 0 0 0 0 0 0 0 0 + -0.7275 -1.1065 -0.4102 C 0 0 0 0 0 0 0 0 0 0 0 0 + 0.6148 -1.1430 -0.4871 C 0 0 0 0 0 0 0 0 0 0 0 0 + -1.5117 -0.0902 0.0316 C 0 0 0 0 0 0 0 0 0 0 0 0 + 1.4983 -0.1720 -0.1409 C 0 0 0 0 0 0 0 0 0 0 0 0 + -1.0967 1.1007 0.4952 C 0 0 0 0 0 0 0 0 0 0 0 0 + 1.2041 1.0381 0.3634 C 0 0 0 0 0 0 0 0 0 0 0 0 + -1.2084 -1.9253 -0.7143 H 0 0 0 0 0 0 0 0 0 0 0 0 + 1.0128 -1.9857 -0.8416 H 0 0 0 0 0 0 0 0 0 0 0 0 + -2.4964 -0.2417 0.0106 H 0 0 0 0 0 0 0 0 0 0 0 0 + 2.4645 -0.3767 -0.2737 H 0 0 0 0 0 0 0 0 0 0 0 0 + -1.7903 1.7498 0.7873 H 0 0 0 0 0 0 0 0 0 0 0 0 + 1.9607 1.6477 0.5723 H 0 0 0 0 0 0 0 0 0 0 0 0 + 1 6 1 0 0 0 0 + 1 7 1 0 0 0 0 + 2 3 2 0 0 0 0 + 2 4 1 0 0 0 0 + 2 8 1 0 0 0 0 + 3 5 1 0 0 0 0 + 3 9 1 0 0 0 0 + 4 6 2 0 0 0 0 + 4 10 1 0 0 0 0 + 5 7 2 0 0 0 0 + 5 11 1 0 0 0 0 + 6 12 1 0 0 0 0 + 7 13 1 0 0 0 0 +M END + +> <StdInChI> +InChI=1S/C6H6O/c1-2-4-6-7-5-3-1/h1-6H + +> <StdInChIKey> +ATYBXHSAIOKLMG-UHFFFAOYSA-N + +> <AuxInfo> +1/0/N:2,3,4,5,6,7,1/E:(1,2)(3,4)(5,6)/rA:13nOCCCCCCHHHHHH/rB:;d2;s2;s3;s1d4;s1d5;s2;s3;s4;s5;s6;s7;/rC:.0758,1.5048,.6075;-.7275,-1.1065,-.4102;.6148,-1.143,-.4871;-1.5117,-.0902,.0316;1.4983,-.172,-.1409;-1.0967,1.1007,.4952;1.2041,1.0381,.3634;-1.2084,-1.9253,-.7143;1.0128,-1.9857,-.8416;-2.4964,-.2417,.0106;2.4645,-.3767,-.2737;-1.7903,1.7498,.7873;1.9607,1.6477,.5723; + +> <Formula> +C6 H6 O + +> <Mw> +94.11124 + +> <SMILES> +O1C([H])=C([H])C([H])=C([H])C([H])=C1[H] + +> <CSID> +4953942 + +$$$$ diff --git a/doc/context/sources/general/manuals/publications/4953942.pdf b/doc/context/sources/general/manuals/publications/4953942.pdf Binary files differnew file mode 100644 index 000000000..02c6cc22a --- /dev/null +++ b/doc/context/sources/general/manuals/publications/4953942.pdf diff --git a/doc/context/sources/general/manuals/publications/971.mol b/doc/context/sources/general/manuals/publications/971.mol new file mode 100644 index 000000000..d27a673ba --- /dev/null +++ b/doc/context/sources/general/manuals/publications/971.mol @@ -0,0 +1,62 @@ +996 + Marvin 12300703363D + + 13 13 0 0 0 0 999 V2000 + -1.1709 -2.1086 -0.0000 O 0 0 0 0 0 0 0 0 0 0 0 0 + -0.5317 -1.0277 -0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0 + 0.8788 -1.0328 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0 + -1.2264 0.1986 0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0 + 1.5888 0.1839 -0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0 + -0.5163 1.4138 -0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0 + 0.8912 1.4069 -0.0000 C 0 0 0 0 0 0 0 0 0 0 0 0 + 1.3960 -1.9155 0.0000 H 0 0 0 0 0 0 0 0 0 0 0 0 + -2.2490 0.2143 0.0000 H 0 0 0 0 0 0 0 0 0 0 0 0 + 2.6112 0.1810 -0.0000 H 0 0 0 0 0 0 0 0 0 0 0 0 + -1.0246 2.3005 -0.0000 H 0 0 0 0 0 0 0 0 0 0 0 0 + 1.4055 2.2902 0.0000 H 0 0 0 0 0 0 0 0 0 0 0 0 + -2.0526 -2.1045 0.0000 H 0 0 0 0 0 0 0 0 0 0 0 0 + 1 2 1 0 0 0 0 + 1 13 1 0 0 0 0 + 2 3 2 0 0 0 0 + 2 4 1 0 0 0 0 + 3 5 1 0 0 0 0 + 3 8 1 0 0 0 0 + 4 6 2 0 0 0 0 + 4 9 1 0 0 0 0 + 5 7 2 0 0 0 0 + 5 10 1 0 0 0 0 + 6 7 1 0 0 0 0 + 6 11 1 0 0 0 0 + 7 12 1 0 0 0 0 +M END + +> <PUBCHEM_BONDANNOTATIONS> +2 3 8 +2 4 8 +3 5 8 +4 6 8 +5 7 8 +6 7 8 + +> <StdInChI> +InChI=1S/C6H6O/c7-6-4-2-1-3-5-6/h1-5,7H + +> <StdInChIKey> +ISWSIDIOOBJBQZ-UHFFFAOYSA-N + +> <AuxInfo> +1/0/N:7,5,6,3,4,2,1/E:(2,3)(4,5)/rA:13nOCCCCCCHHHHHH/rB:s1;d2;s2;s3;d4;d5s6;s3;s4;s5;s6;s7;s1;/rC:-1.1709,-2.1086,0;-.5317,-1.0277,0;.8788,-1.0328,0;-1.2264,.1986,0;1.5888,.1839,0;-.5163,1.4138,0;.8912,1.4069,0;1.396,-1.9155,0;-2.249,.2143,0;2.6112,.181,0;-1.0246,2.3005,0;1.4055,2.2902,0;-2.0526,-2.1045,0; + +> <Formula> +C6 H6 O + +> <Mw> +94.11124 + +> <SMILES> +O([H])C1C([H])=C([H])C([H])=C([H])C=1[H] + +> <CSID> +971 + +$$$$ diff --git a/doc/context/sources/general/manuals/publications/971.pdf b/doc/context/sources/general/manuals/publications/971.pdf Binary files differnew file mode 100644 index 000000000..a2fbc32c7 --- /dev/null +++ b/doc/context/sources/general/manuals/publications/971.pdf diff --git a/doc/context/sources/general/manuals/publications/C6H6O.bib b/doc/context/sources/general/manuals/publications/C6H6O.bib new file mode 100644 index 000000000..4e37e3d19 --- /dev/null +++ b/doc/context/sources/general/manuals/publications/C6H6O.bib @@ -0,0 +1,105 @@ +@chemical{108-95-2, + cas = {108-95-2}, + formula = {C_6H_6O}, + chemspider = {971}, + pubchem = {996}, + mw = {94.113}, + mass = {94.042}, + IUPAC = {phenol}, + name = {phenol}, + name:en = {phenol}, + name:nl = {fenol}, + name:pl = {fenol}, + name:it = {fenolo}, + name:fr = {phénol}, + name:de = {phenole}, + synonyms = {carbolic acid; hydroxybenzene; monohydroxybenzene; phenic acid; + phenyl alcohol; benzophenol; carbolicum acidum; phenic alcohol; + phenyl hydroxide; phenylic acid; carbolic oil; carbolsaeure;}, + molarvolume = {87.9 cm³}, + mp = {42°C}, + bp = {181°C}, + density = {1.071 g/ml}, + ionization = {8.5 eV}, + vaporpressure = {0.4 mmHg}, + refractiveindex = {1.553}, + surfacetension = {41.0 dyne/cm}, + appearance = {Colorless to light-pink, crystalline solid with a sweet, acrid odor}, + chemical = {SIX,ROT,B,EB135,+SR1,RZ1=OH}, + InChI={1S/C6H6O/c7-6-4-2-1-3-5-6/h1-5,7H}, + SMILES={C1=CC=C(C=C1)O}, + jmol = {971.mol}, + rendered = {971.pdf}, +} + +@chemical{24599-57-3, + cas = {24599-57-3}, + formula = {C_6H_6O}, + chemspider = {124484}, + pubchem = {141125}, + mw = {94.113}, + mass = {94.042}, + IUPAC = {cyclohexa-2,4-dien-1-one}, + name = {cyclohexadienone}, + name:en = {2,4-cyclohexadien-1-one}, + name:fr = {2,4-cyclohexadién-1-one}, + name:de = {2,4-cyclohexadien-1-on}, + density = {1.1 g/ml}, + bp = {182.4°C}, + refractiveindex = {1.515}, + surfacetension = {37.2 dyne/cm}, + molarvolume = {89.5 cm³}, + chemical = {SIX,ROT,B,EB35,+DR1,RZ1=O}, + InChI={1S/C6H6O/c7-6-4-2-1-3-5-6/h1-4H,5H2}, + SMILES = {C1C=CC=CC1=O}, + jmol = {124484.mol}, + rendered = {124484.pdf}, +} + +@chemical{566-33-5, + cas = {566-33-5}, + formula = {C_6H_6O}, + pubchem = {138558}, + chemspider = {122176}, + mw = {94.113}, + mass = {94.042}, + IUPAC = {cyclohexa-2,5-dien-1-one}, + name = {2,5-cyclohexadienone}, + name:en = {2,5-cyclohexadien-1-one}, + name:fr = {2,5-cyclohexadién-1-one}, + name:de = {2,5-cyclohexadien-1-on}, + density = {1.1 g/ml}, + bp = {173°C}, + refractiveindex = {1.515}, + surfacetension = {37.2 dyne/cm}, + molarvolume = {89.5 cm³}, + chemical = {SIX,ROT,B,EB25,+DR1,RZ1=O}, + InChI = {1S/C6H6O/c7-6-4-2-1-3-5-6/h2-5H,1H2}, + SMILES = {C1C=CC(=O)C=C1}, + jmol = {122176.mol}, + rendered = {122176.pdf}, +} + +@chemical{291-70-3, + cas = {291-70-3}, + chemspider = {4953942}, + pubchem = {6451477}, + formula = {C_6H_6O}, + mw = {94.113}, + mass = {94.042}, + IUPAC = {oxepine}, + name = {oxepin}, + name:en = {Oxacycloheptatriene}, + name:fr = {oxépine}, + name:de = {oxepin}, + density = {1.0 g/ml}, + bp = {183.1°C}, + refractiveindex = {1.502}, + surfacetension = {39.9 dyne/cm}, + molarvolume = {95.1 cm³}, + chemical = {SEVEN,ROT,+SB7,-SB1,B2..6,EB246,Z1=O}, + InChI={1S/C6H6O/c1-2-4-6-7-5-3-1/h1-6H}, + SMILES = {C1=CC=COC=C1}, + jmol = {4953942.mol}, + rendered = {4953942.pdf}, +} diff --git a/doc/context/sources/general/manuals/publications/boekplan.bib b/doc/context/sources/general/manuals/publications/boekplan.bib new file mode 100644 index 000000000..5089388ed --- /dev/null +++ b/doc/context/sources/general/manuals/publications/boekplan.bib @@ -0,0 +1,93 @@ +@Book{Hagen2010metafun, + Title = {MetaFun}, + + Address = {Hassalt, NL}, + Author = {Hans Hagen}, + Edition = {2nd}, + Month = {October}, + Organization = {PRAGMA ADE}, + Year = {2010}, + + Abstract = {If you like graphics, you may like MetaFun, a collection of MetaPost macros. The manual covers most of MetaPost, as well as the interface between this graphical environment and ConTeXt. There are numerous examples, that give you an impression about the power of this graphical system as well as the strength of the combination with TeX. + +This is the second version of the MetaFun book. This version is adapted to ConTeXt MkIV that uses LuaTeX with MPlib. Although the book targets at ConTeXt users, much of the content concerns general usage of MetaPost, a small and fast system for making graphics.}, + Day = {8}, + File = {metafun-p.pdf}, + ISBN = {978-94-90688-02-8}, + Keywords = {MetaPost; ConTeXt; MkIV. LuaTeX}, + Language = {english}, + TotalPages = {375}, + Publisher = {Boekplan}, + Url = {http://www.h2o-books.com/catalog/context/metafun} +} + +@Book{Hagen2010mkii-mkiv, + Title = {MKII - MKIV, the history of LuaTeX}, + Author = {Hans Hagen}, + Publisher = {Boekplan}, + Year = {2010}, + + Address = {Hassalt, NL}, + Month = {October}, + + Abstract = {The objective of the LuaTeX project by Taco Hoekwater, Hartmut Henkel and Hans Hagen is to provide a versatile successor to TeX. During the development the team keeps track of ideas and experiments. In parallel ConTeXt MkIV is developed. This book describes the development of both systems and shows what impact the project has. The book start at version zero and ends with version 0.50, the first formal release.}, + Day = {30}, + Keywords = {ConTeXt; MkII; MkIV; LuaTeX}, + Language = {english}, + TotalPages = {328}, + Url = {http://www.h2o-books.com/catalog/context/mkii-mkiv} +} + +@Manual{Hagen2014bibliographies, + Title = {Bibliographies}, + + Address = {Hassalt, NL}, + Author = {Hans Hagen and Alan Braslau}, + Note = {still incomplete}, + Organization = {PRAGMA ADE \& \CONTEXT\ Development Team}, + Year = {2015}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + File = {mkiv-publications.pdf}, + Keywords = {manual}, + Language = {english}, + Review = {Review...}, + Subtitle = {The \CONTEXT\ way} +} + +@Book{Hoekwater2011fonts, + Title = {Fonts in ConTeXt}, + + Address = {Hassalt, NL}, + Author = {Taco Hoekwater and Hans Hagen}, + Month = {February}, + Year = {2011}, + + Abstract = {This booklet describes how to define and use fonts in ConTeXt. It demonstrates how to use individual fonts and provides examples of more complex setups for related font styles. Although ConTeXt comes with many fonts set up, this manual is a must-read for those who want to roll out their own setups.}, + Day = {18}, + ISBN = {978-94-90688-03-5}, + Keywords = {fonts; ConTeXt; MkIV; LuaTeX}, + Language = {english}, + TotalPages = {128}, + Publisher = {Boekplan}, + Url = {http://www.h2o-books.com/catalog/context/fonts} +} + +@Book{Hoekwater2011layouts, + Title = {Layouts in ConTeXt}, + + Address = {Hassalt, NL}, + Author = {Taco Hoekwater and Hans Hagen and Willi Egger}, + Month = {July}, + Year = {2011}, + + Abstract = {One of the principles behind ConTeXt is that you can create your own styles. Often defining a style starts with setting up the page layout. This booklet tells in detail how to do that. It also contains information on how to prepare your documents for professional printing, including page imposition.}, + Day = {11}, + ISBN = {978-94-90688-00-4}, + Keywords = {ConTeXt; MkIV; LuaTeX}, + Language = {english}, + TotalPages = {142}, + Publisher = {Boekplan}, + Url = {http://www.h2o-books.com/catalog/context/layouts} +} diff --git a/doc/context/sources/general/manuals/publications/duane.bib b/doc/context/sources/general/manuals/publications/duane.bib new file mode 100644 index 000000000..bc31a26e1 --- /dev/null +++ b/doc/context/sources/general/manuals/publications/duane.bib @@ -0,0 +1,116 @@ +@IMAGE {tug2014, + title = "TUG 2014", + url = "http://tug.org/tug2014/", + url_image = "http://tug.org/art/tug2014-color.jpg", + url_thumb = "http://tug.org/tug2014/t2014-thumb.jpg", + description = "Official drawing of the TUG 2014 conference", + author = "Duane Bibby", + year = 2014, +} + +@IMAGE {tug2013, + title = "TUG 2013", + url = "http://tug.org/tug2013/", + url_image = "http://tug.org/tug2013/tug2013-color-300.jpg", + url_thumb = "http://tug.org/tug2013/t2013-thumb.jpg", + description = "Official drawing of the TUG 2013 conference", + author = "Duane Bibby", + year = 2013, +} + +@IMAGE {tug2012, + title = "TUG 2012", + url = "http://tug.org/tug2012/", + url_image = "http://www.tug.org/art/tug2012-color.jpg", + url_thumb = "http://www.tug.org/tug2012/t2012-thumb.jpg", + description = "Official drawing of the TUG 2012 conference", + author = "Duane Bibby", + year = 2012, +} + +@IMAGE {tug2011, + title = "TUG 2011: TeX in the eBook era", + url = "http://tug.org/tug2011/", + url_image = "http://www.tug.org/art/tug2011-boatrace.jpg", + url_thumb = "http://www.tug.org/tug2011/art/t2011-thumb.jpg", + description = "Official drawing of the TUG 2011 conference", + author = "Duane Bibby", + year = 2011, +} + +@IMAGE {tug2010, + title = "TUG 2010: TeX's $2^5$ anniversary", + url = "http://tug.org/tug2010/", + url_image = "http://www.tug.org/art/tug2010-color.jpg", + url_thumb = "http://www.tug.org/tug2010/t2010-thumb.jpg", + description = "Official drawing of the TUG 2010 conference", + author = "Duane Bibby", + year = 2010, +} + +@IMAGE {tug2009, + title = "TUG 2009", + url = "http://tug.org/tug2009/", + url_image = "http://www.tug.org/art/tug2009.jpg", + url_thumb = "http://www.tug.org/tug2009/t2009-thumb.jpg", + description = "Official drawing of the TUG 2009 conference", + author = "Duane Bibby", + year = 2009, +} + +@IMAGE {tug2008, + title = "TUG 2008", + url = "http://www.ucc.ie/archive/tug2008/", + url_image = "http://www.tug.org/art/tug2008.jpg", + url_thumb = "", + description = "Official drawing of the TUG 2008 conference", + author = "Duane Bibby", + year = 2008, +} + +@IMAGE {tug2007, + title = "TUG 2007", + url = "http://tug.org/tug2007/", + url_image = "http://www.tug.org/tug2007/t2007.jpg", + url_thumb = "http://www.tug.org/tug2007/t2007-thumb.jpg", + description = "Official drawing of the TUG 2007 conference", + author = "Duane Bibby", + year = 2007, +} + +% URL not working +@IMAGE {tug2006, + title = "TUG 2006", + url = "http://tug.org/tug2006/", + url_image = "http://www.tug.org/art/tug2006-color.jpg", + url_thumb = "", + description = "Official drawing of the TUG 2006 conference", + author = "Duane Bibby", + year = 2006, +} + +@IMAGE {tug2006bw, + title = "TUG 2006 b&w", + url = "http://tug.org/tug2006/", + url_image = "http://www.tug.org/art/tug2006-bw.jpg", + url_thumb = "", + colorspace = "gray", + description = "Official drawing of the TUG 2006 conference (black and white version)", + author = "Duane Bibby", + year = 2006, +} + + +@IMAGE {tug2005, + title = "TUG 2005", + url = "http://tug.org/tug2005/", + url_image = "http://www.tug.org/art/tug2005.jpg", + url_thumb = "", + description = "Official drawing of the TUG 200 conference", + author = "Duane Bibby", + year = 2005, +} + +% http://www.tug.org/art/ +% https://tug.org/meetings.html +% http://www.tug.org/tug2001/bulletin/bulletin.jpg diff --git a/doc/context/sources/general/manuals/publications/manuals.bib b/doc/context/sources/general/manuals/publications/manuals.bib new file mode 100644 index 000000000..00f5d9136 --- /dev/null +++ b/doc/context/sources/general/manuals/publications/manuals.bib @@ -0,0 +1,47 @@ +@BOOK {h2o:layouts-in-context, + title = "Layouts in ConTeXt", + author = "Taco Hoekwater and Hans Hagen and Willi Egger", + year = 2011, + month = 07, + day = 11, + url = "http://www.h2o-books.com/node/12", + url_image = "http://www.h2o-books.com/sites/default/files/imagecache/product_full/layout-cover.png", + url_thumb = "http://www.h2o-books.com/sites/default/files/imagecache/product/layout-cover.png", + price = 24, +} + +@BOOK {h2o:fonts-in-context, + title = "Fonts in ConTeXt", + author = "Taco Hoekwater and Hans Hagen", + year = 2011, + month = 02, + day = 18, + url = "http://www.h2o-books.com/node/11", + url_image = "http://www.h2o-books.com/sites/default/files/imagecache/product_full/fonts-cover.png", + url_thumb = "http://www.h2o-books.com/sites/default/files/imagecache/product/fonts-cover.png", + price = 19, +} + +@BOOK {h2o:mkii-mkiv, + title = "MKII - MKIV, the history of LuaTeX", + author = "Hans Hagen", + year = 2010, + month = 10, + day = 30, + url = "http://www.h2o-books.com/node/10", + url_image = "http://www.h2o-books.com/sites/default/files/imagecache/product_full/mk-thumb.png", + url_thumb = "http://www.h2o-books.com/sites/default/files/imagecache/product/mk-thumb.png", + price = 49, +} + +@BOOK {h2o:metafun-manual, + title = "MetaFun manual", + author = "Hans Hagen", + year = 2010, + month = 10, + day = 10, + url = "http://www.h2o-books.com/node/9", + url_image = "http://www.h2o-books.com/sites/default/files/imagecache/product_full/metafun-thumb_0.png", + url_thumb = "http://www.h2o-books.com/sites/default/files/imagecache/product/metafun-thumb_0.png", + price = 49, +} diff --git a/doc/context/sources/general/manuals/publications/mkiv-publications.bib b/doc/context/sources/general/manuals/publications/mkiv-publications.bib new file mode 100644 index 000000000..15086e5b0 --- /dev/null +++ b/doc/context/sources/general/manuals/publications/mkiv-publications.bib @@ -0,0 +1,680 @@ +@Comment{Start example} +@Article{article, + Title = {Article title}, + Title:fr = {Titre de l'article}, + Author = {First Last} + # { and First Middle Last} + # { and Last, First-Combined} + # { and First van Last} + # { and van Last, First Middle} + # { and Last, Junior, First Middle} + # { and van Last, Junior III, First Middle} + # { and De La, Last, Junior III, First Middle}, + Journal = {Journal name}, + Year = {YYYY}, + + Note = {note...}, + Number = {number}, + Pages = {ff--tt}, + Subtitle = {Subtitle}, + Type = {Special Issue}, + Volume = {volume}, + + Month = {MM-ignored!}, + Day = {DD-ignored!}, + Abstract = {Abstract...}, + Warning = {Notice that Comment= also exists}, + Comment = {Comment...}, + XCrossref = {crossref}, + Doi = {doi-specification}, + Keywords = {keyword1; keyword2; keyword3}, + Language = {english}, + Review = {Review...}, + Url = {url} +} +@Comment{Stop example} +@Article{article, + Title = {Article title}, + Title:fr = {Titre de l'article}, + Author = {First Last} + # { and First Middle Last} + # { and Last, First-Combined} + # { and First van Last} + # { and van Last, First Middle} + # { and Last, Junior, First Middle} + # { and van Last, Junior III, First Middle} + # { and De La, Last, Junior III, First Middle}, + Journal = {Journal name}, + Year = {YYYY}, + + Note = {note...}, + Number = {number}, + Pages = {ff--tt}, + Subtitle = {Subtitle}, + Type = {Special Issue}, + Volume = {volume}, + + Month = {MM-ignored!}, + Day = {DD-ignored!}, + Abstract = {Abstract...}, + Warning = {Notice that Comment= also exists}, + Comment = {Comment...}, + XCrossref = {crossref}, + Doi = {doi-specification}, + Keywords = {keyword1; keyword2; keyword3}, + Language = {english}, + Review = {Review...}, + Url = {url} +} + +@Comment{We define a few other instances of Article to test some realistic contingencies.} + +@Article{advancedonline, + Message = {This is an example of an advanced online publication.}, + Title = {Advanced article title}, + Author = {LastnameA, FirstnameA + and LastnameB, FirstnameB + and LastnameC, FirstnameC + and LastnameD, FirstnameD + and LastnameE, FirstnameE + and LastnameF, FirstnameF + and LastnameG, FirstnameG}, + Journal = {Journal name}, + + Language = {english}, + Url = {url}, +} + +@Magazine{magazine, + Message = {This is a magazine article.}, + Title = {Magazine article title}, + Author = {MagazineLastname, Firstname}, + Journal = {Magazine name}, + Year = {YYYY}, + + Month = {Month}, + Day = {DD}, + Note = {note...}, + Number = {number}, + Pages = {ff--tt}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Keywords = {magazine}, + Language = {english}, + Review = {Review...}, + Url = {url} +} + +@Newspaper{newspaper, + Message = {This is a newspaper article.}, + Title = {Article title}, + Author = {NewspaperLastname, Firstname}, + Journal = {Newspaper name}, + Year = {YYYY}, + + Month = {Month}, + Day = {DD}, + Note = {note...}, + Number = {number}, + Pages = {ff--tt}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Keywords = {newspaper}, + Language = {english}, + Review = {Review...}, + Url = {url} +} + +@Newspaper{editorial, + Message = {This is a newspaper editorial.}, + Editor = {EditorLastname, Firstname}, + Title = {Editorial title}, + Journal = {Newspaper name}, + Year = {YYYY}, + + Month = {Month}, + Day = {DD}, + Note = {note...}, + Number = {number}, + Pages = {ff--tt}, + Type = {Editorial}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Keywords = {editorial}, + Language = {english}, + Review = {Review...}, + Url = {url} +} + +@Book{book, + Title = {Book title}, + Title = {Title2}, + Author = {BookAuthorLastnameA, Firstname + and BookAuthorLastnameB, Firstname Middle + and BookAuthorLastnameC, Firstname-Combined}, + Editor = {EditorLastname, Firstname}, + Editor = {EditorLastname2, Firstname}, + Publisher = {Publisher}, + Year = {YYYY}, + + Address = {Address}, + Edition = {edition}, + Month = {Month}, + Note = {note...}, + Number = {number}, + Series = {series}, + Type = {Translated title, for example}, + Volume = {volume}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Doi = {doi-specification}, + Keywords = {book}, + Language = {english}, + Review = {Review...}, + Url = {url} +} + +@Book{selfpublished, + Title = {Book title}, + Author = {BookAuthorLastname, Firstname}, + Author = {BookAuthorLastname2, Firstname}, + Year = {YYYY}, + + Address = {Address}, + + Comment = {A self-published book}, + Language = {english}, +} + +@Book{editedbook, + Editor = {EditorLastnameA, Firstname + and EditorLastnameB, Firstname}, + Publisher = {Publisher}, + Title = {Book title}, + Year = {YYYY}, + + Address = {Address}, + + Comment = {Editors as authors}, + Language = {english}, +} + +@Book{noauthor, + Title = {Book title}, + Publisher = {Publisher}, + Year = {YYYY}, + + Address = {Address}, + + Comment = {Publisher as author}, + Language = {english}, +} + +@Booklet{booklet, + Title = {Booklet title}, + + Address = {Address}, + Author = {BookletAuthorLastname, Firstname}, + HowPublished = {howpublished}, + Month = {Month}, + Note = {note...}, + Year = {YYYY}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Doi = {doi-specification}, + Keywords = {booklet}, + Language = {english}, + Review = {Review...}, + Url = {url} +} + +@Conference{conference, + Title = {Conference title}, + Author = {ConferenceAuthorLastname, Firstname}, + Booktitle = {Booktitle}, + Year = {YYYY}, + + Address = {Address}, + Editor = {EditorLastname, Firstname}, + Month = {Month}, + Note = {note...}, + Number = {number}, + Organization = {<Symposium conducted at the meeting of> Organization}, + Pages = {ff--tt}, + Publisher = {publisher}, + Series = {series}, + Volume = {volume}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Doi = {doi-specification}, + Keywords = {conference}, + Language = {english}, + Review = {Review...}, + Url = {url} +} + +@Electronic{electronic, + Title = {Electronic title}, + + Address = {Address}, + Author = {ElectronicAuthorLastname, Firstname}, + HowPublished = {howpublished}, + Language = {english}, + Month = {Month}, + Note = {note...}, + Organization = {Organization}, + Url = {url}, + Year = {YYYY}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Doi = {doi-specification}, + Keywords = {electronic}, + Review = {Review...}, +} + +@Film{film, + Title = {Film title}, + + Director = {DirectorLastname, Firstname}, + Producer = {ProducerLastName, Firstname}, + Publisher = {studio}, + Address = {address}, + Note = {note...}, + Year = {YYYY}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Keywords = {misc}, + Language = {english}, + Review = {Review...}, + Url = {url} +} + +@InBook{inbook, + Title = {InBook title}, + Author = {InBookAuthorLastname, Firstname}, + Chapter = {Chapter title}, + Editor = {EditorLastname, Firstname}, + Pages = {ff--tt}, + Publisher = {publisher}, + Year = {YYYY}, + + Address = {Address}, + Edition = {edition}, + Month = {Month}, + Note = {note...}, + Number = {number}, + Series = {series}, + Type = {type}, + Volume = {volume}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Doi = {doi-specification}, + Keywords = {inbook}, + Language = {english}, + Review = {Review...}, + Url = {url} +} + +@InCollection{incollection, + Title = {InCollection title}, + Author = {InCollectionAuthorLastname, Firstname}, + Booktitle = {Booktitle}, + Publisher = {publisher}, + Year = {YYYY}, + + Address = {Address}, + Chapter = {Chaptertitle}, + Edition = {edition}, + Editor = {EditorLastname, Firstname}, + Month = {Month}, + Note = {note...}, + Number = {number}, + Pages = {ff--tt}, + Series = {series}, + Type = {type}, + Volume = {volume}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Doi = {doi-specification}, + Keywords = {incollection}, + Language = {english}, + Review = {Review...}, + Url = {url} +} + +@InProceedings{inproceedings, + Title = {InProceedings title}, + Author = {InProceedingsAuthorLastname, Firstname}, + Booktitle = {Booktitle}, + Year = {YYYY}, + + Address = {Address}, + Editor = {EditorLastname, Firstname}, + Month = {Month}, + Note = {note...}, + Number = {number}, + Organization = {<Symposium conducted at the meeting of> Organization}, + Pages = {ff--tt}, + Publisher = {publisher}, + Series = {series}, + Volume = {volume}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Doi = {doi-specification}, + Keywords = {inproceedings}, + Language = {english}, + Review = {Review...}, + Url = {url} +} + +@Manual{manual, + Title = {Manual title}, + + Address = {Address}, + Author = {ManualLastname, Firstname}, + Edition = {Edition}, + Month = {Month}, + Note = {note...}, + Organization = {Organization}, + Year = {YYYY}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + Doi = {doi-specification}, + Keywords = {manual}, + Review = {Review...}, + Url = {url} +} + +@MastersThesis{mastersthesis, + Title = {MastersThesis title}, + Author = {MastersThesisAuthorLastname, Firstname}, + School = {school}, + Year = {YYYY}, + + Address = {Address}, + Month = {Month}, + Note = {note...}, + Type = {type}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Doi = {doi-specification}, + Keywords = {mastersthesis}, + Language = {english}, + Review = {Review...}, + Url = {url} +} + +@Thesis{thesis, + Title = {Thesis title}, + Author = {ThesisAuthorLastname, Firstname}, + School = {school}, + Year = {YYYY}, + + Address = {Address}, + Month = {Month}, + Note = {note...}, + Type = {type of thesis}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Doi = {doi-specification}, + Keywords = {mastersthesis}, + Language = {english}, + Review = {Review...}, + Url = {url} +} + +@Misc{misc, + Title = {Misc title}, + + Author = {MiscAuthorLastname, Firstname}, + HowPublished = {howpublished}, + Month = {Month}, + Note = {note...}, + Year = {YYYY}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Doi = {doi-specification}, + Keywords = {misc}, + Language = {english}, + Review = {Review...}, + Url = {url} +} + +@Music{music, + Title = {Music title}, + Album = {Album title}, + + Artist = {ArtistLastname, Firstname}, + Composer = {ComposerLastName, Firstname}, + Publisher = {label}, + Address = {address}, + Note = {note...}, + Year = {YYYY}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Keywords = {misc}, + Language = {english}, + Review = {Review...}, + Url = {url} +} + +@Other{other, + Title = {Other title}, + Abstract = {Abstract...}, + Author = {OtherAuthorLastname, Firstname}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Doi = {doi-specification}, + Keywords = {other}, + Language = {english}, + Note = {note...}, + Review = {Review...}, + Url = {url}, + Year = {YYYY} +} + +@Patent{patent, + Title = {Patent title}, + Nationality = {nationality}, + Number = {number}, + Year = {YYYY}, + Yearfiled = {YYYYfiled}, + Author = {PatentAuthorLastname, Firstname}, + Language = {english}, + Note = {note...}, + Url = {url}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Doi = {doi-specification}, + Keywords = {patent}, + Review = {Review...}, +} + +@Periodical{periodical, + Title = {Periodical title}, + + Editor = {EditorLastname, Firstname}, + Language = {english}, + Month = {Month}, + Note = {note...}, + Number = {number}, + Organization = {Organization}, + Series = {series}, + Url = {url}, + Volume = {volume}, + Year = {YYYY}, + + Abstract = {Abstract...}, + Author = {PeriodicalAuthorLastname, Firstname}, + Journal = {Periodical Journal}, + Comment = {Complete issue of a periodical, such as + a special issue of a journal}, + PercentCrossref = {crossref}, + Day = {DD}, + Keywords = {periodical}, + Review = {Review...}, +} + +@PhdThesis{phdthesis, + Title = {PhDThesis title}, + Author = {PhDThesisAuthorLastname, Firstname}, + School = {school}, + Year = {YYYY}, + Note = {note...}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Doi = {doi-specification}, + Keywords = {phdthesis}, + Language = {english}, + Review = {Review...}, + Url = {url} +} + +@Proceedings{proceedings, + Title = {Proceedings title}, + Year = {YYYY}, + + Address = {Address}, + Editor = {EditorLastname, Firstname}, + Month = {Month}, + Note = {note...}, + Number = {number}, + Organization = {<Symposium conducted at the meeting of> Organization}, + Publisher = {Publisher}, + Series = {series}, + Volume = {volume}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Doi = {doi-specification}, + Keywords = {proceedings}, + Review = {Review...}, + Url = {url} +} + +@Proceedings{proceedings-organization, + Title = {Proceedings title}, + Year = {YYYY}, + + Address = {Address}, + Month = {Month}, + Day = {DD}, + Note = {note...}, + Number = {number}, + Organization = {Organization}, + Publisher = {Publisher}, + Series = {series}, + Volume = {volume}, + + Abstract = {Abstract...}, + Comment = {Conference preceedings with no identified editor(s)}, + PercentCrossref = {crossref}, + Doi = {doi-specification}, + Keywords = {proceedings}, + Review = {Review...}, + Url = {url} +} + +@Standard{standard, + Title = {Standard title}, + Institution = {institution}, + Organization = {Organization}, + Author = {StandardAuthorLastname, Firstname}, + Language = {english}, + Note = {note...}, + Url = {url}, + Year = {YYYY}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Doi = {doi-specification}, + Keywords = {standard}, + Review = {Review...}, +} + +@TechReport{techreport, + Title = {TechReport title}, + Author = {TechReportAuthorLastname, Firstname}, + Institution = {institution}, + Year = {YYYY}, + + Address = {Address}, + Month = {Month}, + Note = {note...}, + Number = {number}, + Type = {type}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Doi = {doi-specification}, + Keywords = {techreport}, + Language = {english}, + Review = {Review...}, + Url = {url} +} + +@Unpublished{unpublished, + Title = {Unpublished title}, + Author = {UnpublishedAuthorLastname, Firstname}, + Note = {note...}, + + Month = {Month}, + Year = {YYYY}, + + Abstract = {Abstract...}, + Comment = {Comment...}, + PercentCrossref = {crossref}, + Doi = {doi-specification}, + Keywords = {unpublished}, + Language = {english}, + Review = {Review...}, + Url = {url} +} + +@Literal{literal, + Key = {ZZZZ-end}, + Text = {Copied literally to the bibliography}, +} + +@Book{selfpublished2, + Crossref = selfpublished, + Author = {BookAuthorLastname2, Firstname}, +} diff --git a/doc/context/sources/general/manuals/publications/mkiv-publications.lua b/doc/context/sources/general/manuals/publications/mkiv-publications.lua new file mode 100644 index 000000000..f6a980f3e --- /dev/null +++ b/doc/context/sources/general/manuals/publications/mkiv-publications.lua @@ -0,0 +1,30 @@ +return { + ["GH0001"] = { + category = "book", + title = "Rhythmic Illusions", + subtitle = "for drums", + author = "Gavin Harrison", + publisher = "Warner", + isbn = "1576236870", + year = "1996", + comment = "plus cd", + }, + ["GH0002"] = { -- no reference in brittisch library + category = "book", + title = "Rhythmic Perspectives", + subtitle = "a multidimensional study of rhythmic composition", + author = "Gavin Harrison", + publisher = "Alfred Publishing Co., Inc", + year = "1999", + comment = "plus cd", + }, + ["GH0003"] = { + category = "book", + title = "Rhythmic Designs", + subtitle = "a study of practical creativity", + author = "Gavin Harrison and Terry Branham", + publisher = "Hudson", + year = "2010", + comment = "plus dvd", + }, +} diff --git a/doc/context/sources/general/manuals/publications/mkiv-publications.tex b/doc/context/sources/general/manuals/publications/mkiv-publications.tex new file mode 100644 index 000000000..9612221ac --- /dev/null +++ b/doc/context/sources/general/manuals/publications/mkiv-publications.tex @@ -0,0 +1,63 @@ +% language=en % uk - Is behaviour really better than behavior, defence than defense? + +% todo : index key in chapters + +% \enabletrackers[publications*] +% \enabletrackers[publications.match] +% \enabletrackers[publications.setups] +% \enabletrackers[publications.authorhash] + +% We use the following bib files: +% +% tugboat.bib +% template2.bib +% +% boekplan.bib +% duane.bib +% manuals.bib +% +% mkiv-publications.bib +% mkiv-publications.lua + +\environment publications-style + +\startdocument + [title={Bibliographies}, + subtitle={The \CONTEXT\ way}, + author={Hans Hagen and Alan Braslau}] + +\component publications-titlepage + +\startfrontmatter + \component publications-contents + \component publications-introduction +\stopfrontmatter + +\startbodymatter + \component publications-quick + \component publications-database + \component publications-datasets + \component publications-rendering + \component publications-citations + \component publications-customize + \component publications-exporting + \component publications-lua + \component publications-xml + \component publications-extensions + % \component publications-journals + \component publications-otheruse + \component publications-tracing +\stopbodymatter + +\startappendices + \component publications-fields + \component publications-completeness + \component publications-transition + \component publications-performance +\stopappendices + +\startbackmatter + \component publications-overviews +\stopbackmatter + +\stopdocument diff --git a/doc/context/sources/general/manuals/publications/publications-citations.tex b/doc/context/sources/general/manuals/publications/publications-citations.tex new file mode 100644 index 000000000..aabdd5328 --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-citations.tex @@ -0,0 +1,881 @@ +\environment publications-style + +\startcomponent publications-citations + +\startchapter + [title=Citations, + reference=ch:cite] + +The \index {style+APA}APA Style Guide as well as good practice demand that +\emphasis {all} references appearing in the bibliography be cited at least once +in the text (and, of course, all citations must have a corresponding +bibliographical reference). Other publishing styles, textbooks in particular, +might additionally include lists of general references for \quote {further +reading} (and these lists might sometimes be split into sections according to +subject). An author may, in contrast, choose not to interrupt a text with many +citations, nevertheless, including a list of references. Furthermore, one might +refer in the text to certain works that need not necessarily be accompanied by a +full bibliography listing (for example, \Name {Darwin} {C.}'s \emph {Origin}). +\startfootnote \textcite[entry] [default::Darwin1859] \stopfootnote Thus, a +system providing tools to handle bibliographies needs to be flexible. + +A good, general reference on bibliography practice (in the English language), +independent of any particular specification, can be found in \cite [title] +[default::vanLeunen1992] \cite [default::vanLeunen1992]. Note that rules and +traditions may differ slightly in other languages and cultures. + +The examples of bibliography listings of the previous chapter were simplified by +the fact that the entire bibliographical dataset was rendered. In practice, the +same dataset source(s) could be used over many documents, and the dataset might +contain many more references than are used in any one document. That is, the data +source might be more complete than the final rendered bibliography list or lists. +The mechanism of citation allows you to select references from the dataset(s) to +build the list rendering as well as to place a indicator of the reference (or +not) in the text of the document corresponding to a list entry (a publication). +These citation renderings can be of many forms. + +A citation is normally pretty short as its main purpose is to refer uniquely to a +more detailed description. But, there are several ways to refer, which is why the +citation subsystem is configurable and extensible. Just look at the following +commands: + +\cindex{cite} +\tindex{::} + +\starttabulate +\NC \TEXcode{\cite[num][article]} \NC \cite[num] [article] \NC \NR +\NC \TEXcode{\cite[textnum][article]} \NC \cite[textnum] [article] \NC \NR +\NC \TEXcode{\cite[authornum][article]} \NC \cite[authornum] [article] \NC \NR +\NC \TEXcode{\cite[authoryear][article]} \NC \cite[authoryear] [article] \NC \NR +\NC \TEXcode{\cite[authoryears][article]} \NC \cite[authoryears][article] \NC \NR +\NC \TEXcode{\cite[short][article]} \NC \cite[short] [article] \NC \NR +\NC \TEXcode{\cite[tag][article]} \NC \cite[tag] [article] \NC \NR +\NC \TEXcode{\cite[index][article]} \NC \cite[index] [article] \NC \NR +\NC \TEXcode{\cite[category][article]} \NC \cite[category] [article] \NC \NR +\NC \TEXcode{\cite[author][article]} \NC \cite[author] [article] \NC \NR +\NC \TEXcode{\cite[year][article]} \NC \cite[year] [article] \NC \NR +\NC \TEXcode{\cite[title][article]} \NC \cite[title] [article] \NC \NR +\NC \TEXcode{\cite[keywords][article]} \NC \cite[keywords] [article] \NC \NR +\NC \TEXcode{\cite[none][article]} \NC \cite[none] [article] \NC \NR +\NC \TEXcode{\cite[X]} \NC \cite[X] \NC \NR +\NC \TEXcode{\cite[]} \NC \cite[] \NC \NR +\NC \TEXcode{\cite[template::Chen:1988:IPP]} \NC \cite[template::Chen:1988:IPP] \NC \NR +\NC \TEXcode{\cite[entry][article]} \NC \cite[entry] [article] \NC \NR +\stoptabulate + +The first argument is optional and if omitted, the default citation rendering +(for example, \TEXcode {num} or \TEXcode {authoryear}, depending on the +specification) will be selected. + +\startbuffer +\cite[article] +\stopbuffer +\cindex{cite} + +\typeTEXbuffer \getbuffer + +\startaside +The default citation alternative is defined via \cindex {setupbtx} + +\startTEX +\setupbtx[alternative=num] +\stopTEX + +However, this is not used as it is overridden by the specification, even the +\TEXcode {default} specification: + +\startTEX +\setupbtx[default:cite][alternative=num] +\setupbtx [apa:cite][alternative=authoryear] +\stopTEX + +These examples introduce the concept of \Index {namespace}s that is extensively +used in the bibliography subsystem. The \TEXcode {cite} namespace will inherit +from the root namespace; similarly, the \TEXcode {default} specification will +inherit elements from the \TEXcode {cite} namespace, but will be distinct from +the \TEXcode {apa} specification's \TEXcode {cite} namespace, and so forth. +Normally, we need not to worry about this as it is handled through the loading of +the specification. +\stopaside + +\cindex {cite} +\showsetup[cite] + +The \Cindex{citation} command is synonymous to \Cindex{cite}. + +\cindex {citation} +\showsetup[citation] +%\showsetup[citation:userdata] +\showsetup[citation:alternative] +\showsetup[citation:direct] + +\startaside +Note that the \MKII\ module based on \Tindex {bibtex} allowed the use of curly +brackets enclosing the \Index {tag} (for reasons of backward compatibility with +traditional \LATEX\ practice). A side|-|effect made this a bit picky about spaces +between its arguments, the first of which is optional. We have chosen to remove +this restriction through the use of standard \CONTEXT\ syntax using square +brackets (reserving curly brackets to usually be used to enclose text that is to +be typeset). + +The system will tolerate the \Index {depreciated} syntax \cindex {cite}\TEXcode +{\cite{tag}}, but this practice is to be strongly discouraged and cannot be mixed +with any other options. +\stopaside + +The most commonly used citation variants (or alternatives) are \TEXcode {num} and +\TEXcode {authoryear} introduced above. The first is typically employed in +conjunction with a numbered bibliography list, usually sorted in the citation +order in the text; the second is typically used in conjunction with a +bibliography list sorted by author and year of publication. + +Other citation variants may be quite useful, even when used in the context of the +above standard schemes. One such example would be \Cindex {cite}\TEXcode +{[title][tag]} that can be used to include the title of the work in the running +text (as can be seen earlier in \in {section} [sec:styles]; another one is +\cindex {cite}\TEXcode {\cite[year][tag]} that can be used to include the +publication date and \cindex {cite}\TEXcode {\cite[author][tag]} can be used to +extract the authors' names. These are examples of a general rule where \cindex +{cite}\TEXcode {\cite[field][tag]} will return the contents of the given field +for an entry, if the entry contains such a field. + +The variants \TEXcode {textnum} and \TEXcode {authoryears} are intended to be +used in the running text when the reference becomes part of the syntax of the +sentence: typically, they will not be set|-|off by parenthesis, for example. + +\startaside +The name \TEXcode {authoryears} (with an \quote{s}) is a shorthand that was used +in \MKII. Whereas its name is not immediately obvious at first view, in practice +it is a quite convenient variant of \TEXcode {authoryear} that differs only in +the style of punctuation, thus its place in a sentence structure. +\stopaside + +Notice that in the example \TEXcode{\cite[template::Chen:1988:IPP]} shown above, +the \TEXcode {tag} was prefixed with an alternate dataset name (\tindex +{::}\TEXcode {template::}) rather than to the default \TEXcode {dataset=example} +that was specified in the \Cindex {setupbtx} command earlier. The reason behind +the double|-|colon syntax should be made obvious here (where the \Index {tag} +itself uses single colons). + +In the last of the examples shown above, \TEXcode{\cite[entry][article]}, the +full rendered bibliographic entry gets placed. + +Unless the placed rendering uses \TEXcode {method=dataset}, only publications +that are explicitly cited will end up in the lists. You can force a citation into +a list using \Cindex {usecitation}, for example: + +\cindex{usecitation} + +\startTEX +\usecitation[patent] +\stopTEX + +This command has two synonyms: \Cindex {nocite} and \Cindex {nocitation} so you +can choose whatever fits you best. + +\cindex {nocite} +\showsetup[nocite] + +\cindex {nocitation} +\showsetup[nocitation] + +\cindex {usecitation} +\showsetup[usecitation] + +The purpose and utility of these commands (and their synonyms) is not only to +draw a citation from the dataset for inclusion in the bibliography, but also to +mark the place in the text where the citation is relevant. Normally, one might +claim that this should be done through one of the forms of the \Cindex {cite} (or +\Cindex {citation}) command, as all references appearing in the bibliography are +to be cited at least once in the text. However, even if one does not disagree +with this statement, one might still wish attach the citation to the reference in +the text of a \Index {floating object} such as a table or a figure, thus +establishing a proper order in the numbering since the explicit citation +rendering might occur within the table or the figure caption that might get +placed on a much later page. Consider the following schematic illustration: + +\cindex{nocite} +\cindex{cite} + +\startTEX +(see \nocite [MyReference]\in {table} [tab:mytable]). + +\startplacetable[reference=tab:mytable] + \unknown\ \cite[MyReference] +\stopplacetable +\stopTEX + +The citation rendering and the bibliographic list rendering are intimately +coupled reciprocally and cannot be dissociated. This coupling can be through the +reference number for example, but unnumbered reference lists also contain +interacting hyperlinks. A failure to take into account this interdependence can +lead to fundamental misunderstandings in use. + +\startaside +Both the citation and the list must be rendered. For example, a common error +would be to omit (or comment|-|out) the list rendering during the writing stage +of a document. Such an error will cause the citations to fail to render properly. + +Whereas this might seem to be an unnecessary limitation, it results from a +specific design choice and from the possibility of placing multiple renderings +freely, anywhere in a document. It is preferable not to render citations at all +than to render these citations possibly incorrectly. +\stopaside + +\startsection[title=Combining citations] + +\startbuffer +\cite[num][article,book,booklet] +\stopbuffer + +A single citation might refer to several sources, obtained through the use of a +comma separated list of \Index{tag}s, for example: \getbuffer + +\cindex{cite} + +\typeTEXbuffer + +A comma separated list of three (or more) consecutive numbers will get collapsed +or compressed into a range of numbers (if possible). + +\cindex {cite} The order in which the citation \Index {tag}s appear in the list +may or may not be important, depending upon the citation variant and on the style +specification. Consider the following examples: + +\startbuffer +\cite[num] [article,book] +\cite[textnum] [article,book] +\cite[authoryear] [article,book] +\cite[authoryears][article,book] +\cite[short] [article,book] +\cite[author] [article,book] +\cite[year] [article,book] +\cite[title] [article,book] +\stopbuffer + +\typeTEXbuffer + +This gives: + +\cindex{cite} +\startlines \getbuffer \stoplines + +Now we swap the order: + +\startbuffer +\cite[num] [book,article] +\cite[textnum] [book,article] +\cite[authoryear] [book,article] +\cite[authoryears][book,article] +\cite[short] [book,article] +\cite[author] [book,article] +\cite[year] [book,article] +\cite[title] [book,article] +\stopbuffer + +\typeTEXbuffer + +and get: + +\startlines \getbuffer \stoplines + +Note that the numbered citation reference is always rendered in numerical order, +where the numbers correspond to the order in which the entries appear in the +bibliography list. This order depends on the \Index {sorting} of the list +rendering (this sorting may be, in some styles, in the order in which the +references are cited) and is controlled by the \TEXcode {[list]} \TEXcode +{sorttype} parameter. In the \index {style+APA}APA style, presently active, the +citations are always sorted according to author and year. Thus, \quotation +{BookAuthorLastname} appears before \quotation {Last} in our example here, +regardless of the order in which the references appear in the \Cindex {cite} +command (i.e. either \TEXcode {\cite[article,book]} or \TEXcode +{\cite[book,article]}). + +The user can control the state of sorting of the \cindex{cite}\TEXcode {cite} +variants through the parameter \TEXcode {sorttype=normal}; other choices are +\TEXcode {reverse} and \TEXcode {none}: + +\startTEX +\setupbtx[aps:cite:num][sorttype=none] +\stopTEX + +\startsubsubject [title=Single list item containing multiple publication entries] + +Some bibliography styles admit the combination of several bibliographical sources +into a single list item having a unique reference number. The combination of +multiple bibliographic entries into as single bibliography list item is more +compact and this practice is often encountered in short \quote {letter}|-|type +journal articles. (Note, however, that entries combined as such do not make any +sense in an authoryear scheme such as \index {style+APA}APA.) + +One can combine \Index {tag}s using the addition operator symbol (\TEXcode {+}), +best illustrated though an example: + +\startbuffer +\METAFUN\ began as an expression of love and appreciation for \METAPOST. +\citation [num] [tugboat::Berdnikov:TB21-2-129+Hobby:TB21-2-131] + +\definebtxrendering[tugboat][aps][dataset=tugboat,group=examples] +\placebtxrendering [tugboat][criterium=section] +\stopbuffer + +\cindex{citation} +\cindex{definebtxrendering} +\cindex{placebtxrendering} +\tindex{::} + +\typeTEXbuffer + +\getbuffer + +Combined entries are joined using a separator that can be specified, as in: + +\startbuffer +\setupbtxrendering[tugboat][separator={\break}] +\stopbuffer + +\cindex{setupbtxrendering} +\tindex{separator} + +\typeTEXbuffer + +or suppressed (using \tindex {separator}\TEXcode {separator=,}); By default, +\cindex {removepunctuation}\TEXcode {separator={\removepunctuation;\space}}. + +Dataset entries that are combined cannot also appear apart (nor does this really +make any logical sense). All of the following: + +\startbuffer +\cite[num][tugboat::Berdnikov:TB21-2-129] +\cite[num][tugboat::Berdnikov:TB21-2-129,Hobby:TB21-2-131] +\cite[num][tugboat::Hobby:TB21-2-131] +\stopbuffer +\cindex{cite} +\tindex{::} + +\typeTEXbuffer \getbuffer + +will point to the combined reference (as they should). However, beware that +attempting to include any of these references in a \emphasis {different} combined +list item is undefined, meaning unsupported. + +Combining list entries is another instance showing that citations and the +rendered bibliography list interact and cannot be separated. + +\stopsubsubject + +\stopsection + +\startsection[title=Additional text] + +\startsubsubject [title=Additional text in a citation reference] + +Sometimes one would like to include additional text in a citation, for example +a specific commentary or page number reference. + +\startbuffer +\cite[righttext={ p.\nbsp xx}][article] +\stopbuffer + +\cindex{cite} + +\typeTEXbuffer + +yielding: + +\getbuffer + +The additional text can be either before (\TEXcode {lefttext=}) or after +(\TEXcode {righttext=}) \startfootnote The \MKII\ bib module used the keyword +\TEXcode {extra=} in the place of \TEXcode {righttext=}. We chose not to support +this as a synonym as the name is ambiguous. Furthermore, we seek to limit the +number of keywords used in \CONTEXT. \stopfootnote each citation entry and are +not to be confused with the delimiters \TEXcode {left={(},} and \TEXcode +{right={)},} used to surround the entire citation. The difference becomes +important when referencing multiple citations. + +The following examples further illustrate the syntax: + +\startbuffer +\cite[lefttext={See },righttext={ p.\nbsp yy}][book] +\stopbuffer + +\typeTEXbuffer \getbuffer + +\startbuffer +\cite[alternative=authoryears,righttext={ p.\nbsp xx}][article] + +\cite[alternative=authornum,righttext={ p.\nbsp xx}][article] +\stopbuffer + +\typeTEXbuffer \getbuffer + +\startbuffer +\cite[alternative=num,righttext={{ p.\nbsp xx},{ p.\nbsp yy}}] + [article,book,booklet] +\stopbuffer + +\cindex{cite} + +\typeTEXbuffer \getbuffer + +\startbuffer +\cite[lefttext={In the article: },righttext={.}][article] +\stopbuffer + +\cindex{cite} + +\typeTEXbuffer \getbuffer + +\startbuffer +\cite[lefttext={{In the article: },{in the book: }},alternative=title] + [article,book] +\stopbuffer + +\cindex{cite} + +\typeTEXbuffer \getbuffer + +\startbuffer +\cite[righttext={{ p.\nbsp xx},}][article,book] +\stopbuffer + +\cindex{cite} \typeTEXbuffer \getbuffer + +Because \CONTEXT\ does not allow mixing key|-|value pair lists with single value +keys, the keyword \TEXcode {alternative=} must be used, if needed, as shown in +the examples above. + +Note that a double curly|-|bracket (\TEXcode {{{}}}) also needs to be used when +the text is to contain a comma. + +\stopsubsubject + +\startsubsubject [title=Additional text in a list entry] + +Additional text such as notes and page numbers can also get placed with the entry +in the bibliography list. Of course, the bibliography data entry can contain a +\TEXcode {note=} field that may or may not get rendered, but often is, according +to the style specification. + +It is also possible to specify notes or page references to be rendered \TEXcode +{before} or \TEXcode {after} a bibliography entry through the citation call. + +\startbuffer +\cite + [alternative=num, + before={{Introducing MetaPost: },}, + after={,{ See, also, the references therein, p.\nbsp 58.}}] + [tugboat::Hobby:TB10-4-505,Hobby:TB22-1-46] +\blank +\placebtxrendering [tugboat][criterium=section] +\stopbuffer + +\cindex{cite} +\cindex{placebtxrendering} +\tindex{::} + +\typeTEXbuffer \getbuffer + +Clearly, such additional text can be added to each entry only once, so the first +such \Cindex {cite} call wins. + +\stopsubsubject + +\stopsection + +\startsection[title=Placing a single citation] + +Sometimes, one would like to place a single citation somewhere in the text +without necessarily adding it to a bibliography list. Take, for example, + +\startbuffer +\placecitation[tugboat::Mahajan:TB31-1-88] +\stopbuffer + +\getbuffer + +obtained by using + +\cindex{placecitation} +\tindex{::} + +\typeTEXbuffer + +Note that \Cindex {placecitation}\TEXcode {[tag]} is a synonym for \Cindex +{citation}\TEXcode {[entry][tag]} (that was seen earlier). + +\showsetup[placecitation] + +As for other citation reference, this will fail if a bibliography list rendering +is not placed somewhere in the document so let's do that here: + +\startbuffer +\placebtxrendering[tugboat][criterium=section] +\stopbuffer + +\cindex{placebtxrendering} + +\typeTEXbuffer \getbuffer + +Whereas this might seem redundant above (placing the citation entry as well as +its list rendering), this will only exceptionally be the case (as in this highly +artificial example of this manual); Indeed, all cited work (such as \cite +[textnum] [tugboat::Mahajan:TB31-1-88], above) will logically always be placed in +a list of references. + +The placement of a single citation brings to light a subtle point: The \TEXcode +{specification} that is used by citations is that set in the root namespace +(through \Cindex {setupbtx}\TEXcode {[specification=apa]} or possibly through +\Cindex {usebtxdefinitions}\TEXcode {[apa]}. This is \emphasis {not} necessarily +the same as that of the rendering (if a different rendering specification is +declared). Note that the named rendering used above (\TEXcode {[tugboat]}) was +not declared a child of the rendering named \TEXcode {[aps]}, though the \TEXcode +{specification=apa} is active. Thus, the style of the citations can be made to +differ from the style of their bibliography list, as here, but this is not really +a very good practice. + +\stopsection + +\startsection[title=Placing citations as footnotes] + +A \Cindex {placecitation} command can occur inside a footnote or other \Index +{floating object} such as a figure or table caption. No specification or style +that places its bibliography list renderings as footnotes has been implemented +yet. + +% bibliographies as endnotes intercalated with footnotes... + +\stopsection + +\startsection[title=Searching] + +Finding the right \Index {tag} in a database can be a pain. In particular, +datasets having their origin in multiple source files may contain conflicting +\Index {tag}s, though duplicate \Index {tag}s get suffixed automatically so this +should not be a real problem. + +On the other hand, asking for a \Index {wildcard} also makes no sense. +\startfootnote Note that \cindex {nocite}\TEXcode {\nocite{*}} is a valid +\LATEX/\BIBTEX\ practice that is used to include all entries of a \Tindex {.bib} +file in the final bibliography. This result can be obtained in \CONTEXT\ through +the \TEXcode {method=dataset} list rendering parameter. Alternately, one can use +the syntax \cindex {cite}\TEXcode {\cite[match(*:*)]} which is a shorthand to +match all values of all fields. \stopfootnote Nevertheless, we provide a powerful +mechanism for matching a query. Keep in mind that a \Index {tag} is used as a +quick look|-|up in a hashed table whereas a search will look through the entire +dataset. If processing speed is critical, one should use the cite \Index {tag} +lookup; in practice, even on a big book project employing a very large dataset, +the search is not a penalty. + +Let's look in more detail at the \Cindex {cite} command. In order to distinguish +efficiently between a normal reference and a more clever one, we use the \TEXcode +{match()} function: + +\tindex{::} +\startTEX +match(query) +dataset::match(query) +dataset :: match ( query ) +\stopTEX + +The handler is rather tolerant for spaces (as well as capitalization) which is +handy if you have long queries that wrap around in the source code. Of course the +\tindex {::}\TEXcode {dataset::} prefix is optional in which case the current +dataset is taken. Such match queries can be mixed in a multiple reference +citation indifferently with hashed cite \Index {tag}s so the system is really +flexible. + +\blank + +To demonstrate the use a search query, we load a small bibliographic database: + +\startbuffer +\usebtxdataset[boekplan][boekplan.bib] +\stopbuffer + +\cindex{usebtxdataset} + +\typeTEXbuffer + +\getbuffer + +We could switch to this base using: + +\cindex{setupbtx} +\startTEX +\setupbtx[dataset=boekplan] +\stopTEX + +but instead we shall use a prefix as seen previously. Consider the following: + +\startbuffer +everything that you might want to know about layouts +\cite[boekplan::match(author:Egger)] +\stopbuffer + +\cindex{cite} +\tindex{::} + +\typeTEXbuffer + +We will get: \quotation {\inlinebuffer}. Of course this assumes that we also +typeset a list of references somewhere in our document, so let's do that here: + +\startbuffer +\definebtxrendering[boekplan][apa][dataset=boekplan,group=examples] +\placebtxrendering [boekplan][criterium=chapter] +\stopbuffer + +\cindex{definebtxrendering} +\cindex{placebtxrendering} + +\typeTEXbuffer \getbuffer + +\startbuffer +\cite[authoryears][ match(title:Lua)]\\ +\cite[authoryears][default:: match(title:Lua)]\\ +\cite[authoryears][boekplan::match(title:Lua)] +\stopbuffer + +\cindex{cite} +\tindex{::} + +\typeTEXbuffer \getbuffer + +Notice that no match is found in the \quote {current} dataset (\TEXcode {example}). + +A query eventually becomes a \LUA\ expression so you can use helpers to achieve +your goal. As a convenience there are some shortcuts to access fields. The +following examples demonstrate this: + +\startbuffer +\cite + [authoryears] + [boekplan::match(author:hagen and year:2010-2011)]\\ +\cite + [authoryears] + [boekplan::match(author:{Willi Egger})]\\ +\cite + [authoryears] + [boekplan::match(author:Hans and (tonumber(field:year) or 0) > 2011)] +\stopbuffer + +\cindex{cite} +\tindex{::} + +\typeTEXbuffer \getbuffer + +You can use grouping braces when spaces are involved. Ranges (of numbers) are +recognized. Of course, you can use other characters that the basic alphabet. + +\startbuffer +\cite[authoryears][tugboat::match(author:{Bogusław Jackowski})]\\ +\stopbuffer + +\cindex{cite} +\tindex{::} + +\typeTEXbuffer \getbuffer + +This demonstrates further the interest in converting classical \TEX\ accent +sequences into proper \UTF\ characters. The citations found above \bold{must} +correspond to some bibliography list entries, so we will place this list here: + +\startbuffer +\placebtxrendering [tugboat][criterium=section] +\stopbuffer + +\cindex{placebtxrendering} + +\typeTEXbuffer \getbuffer + +String lookups are partial and case insensitive. + +\startbuffer +\cite [boekplan::match(author:e)]\\ +\cite [boekplan::match(author:h)] +\stopbuffer + +\cindex{cite} +\tindex{::} + +\typeTEXbuffer + +so one must take care in formulating cite queries as both lookups above will +get all five entries: \inlinebuffer, whereas + +\startbuffer +\cite [boekplan::match(author:eg)]\\ +\cite [boekplan::match(author:e*r)] +\stopbuffer + +\cindex{cite} +\tindex{::} + +\typeTEXbuffer + +finds \inlinebuffer. As the match compares the entire author string, and not +just each author, it also finds [Hag]en & Br[aslau] as well as [Ho]ekwater[ & +Hagen]. + +% To Hans: It is curious that match(author:e*r) finds [Hag]en and Br[aslau]. +% To Alan: We match the whole (original) string. +% +% Response: Yes, but this is not what one might naively expect. +% It would be useful to match author by author, rather than the entire author +% string, at least that is how one might want to use it. Oh well... +% the mechanism is predictable and the above example explicitly explains this +% point. Would it be easy to add match(lastname:h*), for example? I suppose that +% this would have to yield hits in ALL author-type fields (author, editor, ...). + +Note also that the order of the match criteria is not significant. + +\startaside +The search mechanism is very powerful. However, a \bold {major \Index{pitfall}} +or risk comes from the possibility to easily under|-|specify the match criteria. +For example, \TEXcode {match(author:Hagen and author:Hoekwater)} will find \cite +[title] [boekplan::match(title:Fonts)], but it will also find \cite [title] +[boekplan::match(title:Layouts)]; Nor would adding the criterium \TEXcode {and +year:2011} be of any help. The solution is + +\startbuffer +\cite + [authoryear] + [boekplan::match(author:Hagen and author:Hoekwater and title:fonts)] +\stopbuffer + +\cindex{cite} +\tindex{::} + +\typeTEXbuffer \getbuffer + +Note that using \TEXcode {match(title:fonts)} alone would also work, that is +until another reference work containing the word \quote {fonts} in its title gets +added to the dataset! \startfootnote Multiple hits would have occurred in the +examples above containing \TEXcode {title:lua} had only one dataset been used in +the typesetting of the present manual. \stopfootnote Thus, whereas it might +appear that the match mechanism be a more robust way of identifying dataset +entries then short cite \Index {tag}s, incomplete search queries might return +unwanted, excess matches. + +It is quite common in real bibliography databases for some author or authors to +appear in many different references published in the same year, perhaps buried in +a longer list of authors, so some care has to be taken to uniquely identify the +desired work. Of course, this feature can also be a good shorthand as well to +select several different matching works when that is the desired result. +\stopaside + +% This only begins to touch on the search mechanism. +% This section needs to be expanded. + +\stopsection + +\startsection[title={Page index, interaction, and registers},reference=sec:index] + +Each citation in the text not only marks the dataset entry for inclusion in the +bibliography list but also records the page number on which the citation occurs. +Each named list rendering can be instructed to include these pages just like an +index. + +\startbuffer +\setupbtxrendering + [default] + [pagestate=start] +\stopbuffer + +\cindex{setupbtxrendering} + +\typeTEXbuffer + +The result can be observed in the \about [ch:biblio] on \at {page} [ch:biblio]. +If interaction is active (\cindex {setupinteraction}\TEXcode +{\setupinteraction[state=start]}), then these page numbers will be \Index +{hyperlink}s back to the citations. If \TEXcode {numbering=yes}, then the +numbered bibliography entries will also contain \Index {hyperlink}s back to the +first occurrence in the text where the entry is cited (which is the same as the +first page indexed). + +Some styles, such as \index {style+APA}\TEXcode {apa}, will have other \Index +{hyperlink}s. The author list including the year will be active just like the +numbers above (an \TEXcode {authoryear} list is usually not numbered). +Furthermore, any doi or url that is included in the entry will be a \Index +{hyperlink} to the external resource. Finally, all titles will contain \Index +{hyperlink}s to the local downloaded file of the cited work if this exists and +was specified (using the data field \TEXcode {file={},}). + +In addition to the index of pages of citations in the text associated with each +entry in the bibliography list, one has the possibility of adding bibliography +items to any standard index list. This can be illustrated through the creation of +a list of authors or names: + +\startbuffer +\defineregister + [indexofauthors] + +\definebtxregister + [authors] + [field=author, + register=indexofauthors, + method=always, + dataset=default, + alternative=invertedshort] +\stopbuffer + +\cindex{defineregister} +\cindex{definebtxregister} + +\typeTEXbuffer + +placed in the preamble of the document and to be followed later, typically +towards the end of the document, by + +\cindex{placeregister} + +\startTEX +\startchapter[title=Index of Names] + \placeregister[indexofauthors][compress=yes] +\stopchapter +\stopTEX + +as can be see in the present manual on \at {page} [ch:indexofauthors]. + +\cindex {definebtxregister} +\showsetup[definebtxregister] + +\cindex {setupbtxregister} +\showsetup[setupbtxregister] + +Any field can be indexed, as desired, for example \TEXcode {field=title}. One +particularly useful field is \TEXcode {keywords={}}: a semi|-|colon separated +list of keywords will be split into individual index entries for each cited work. + +The handling of fields to be interpreted as names (as in \TEXcode {author}) or as +keywords (split into fields separated by semi|-|colons), etc. depends on the +specification and is declared in a lua file associated with the specification +definition file. This will be described in the next chapter. + +\stopsection + +\startsection [title=Summary and explanation of the \TEXcode {\cite} mechanism] + +As the list of cited references is being built in memory, each used dataset entry +is flagged. As the list gets placed, either partially or fully, eventual conflits +in \TEXcode {short} and in \TEXcode {authoryear} tags are resolved through an +assignment of suffixes. These are then fed|-|back to the citation references. + +A dataset can have multiple renderings and multiple datasets and renderings can +be grouped. The many citation variants can be freely used together and this may +or may not make coherent sense. For example, an \TEXcode {authoryear} sorted list +is assigned numbers that are available for use as numbered citation references, +but these numbers will follow the order of the list and not the order of +citations. Conversely, a list that is sorted in the order of citations will still +have \TEXcode {authoryear} and \TEXcode {short} citation tags, but these will be +of less use for the reader in this case than the \TEXcode {authornum} variant. +With such flexibility comes complication. + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/publications/publications-completeness.tex b/doc/context/sources/general/manuals/publications/publications-completeness.tex new file mode 100644 index 000000000..5642ea312 --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-completeness.tex @@ -0,0 +1,23 @@ +\environment publications-style + +\startcomponent publications-completeness + +\startchapter + [reference=ch:datasetcompleteness, + title={Dataset completeness}] + +\startbuffer +\showbtxdatasetcompleteness[example] +\stopbuffer + +\typeTEXbuffer + +\cindex {showbtxdatasetcompleteness}The listing can be rather long \unknown\ The +header for each entry gives the \TEXcode {index}, \TEXcode {category} and +\TEXcode {tag}. + +\getbuffer + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/publications/publications-contents.tex b/doc/context/sources/general/manuals/publications/publications-contents.tex new file mode 100644 index 000000000..3e5acaa03 --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-contents.tex @@ -0,0 +1,18 @@ +\environment publications-style + +\startcomponent publications-contents + +\starttitle[title=Contents] + + \setuplist + [chapter] + [before=, + after=] + + \placelist + [chapter] + [color=black] + +\stoptitle + +\stopcomponent diff --git a/doc/context/sources/general/manuals/publications/publications-customize.tex b/doc/context/sources/general/manuals/publications/publications-customize.tex new file mode 100644 index 000000000..1a2ab7040 --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-customize.tex @@ -0,0 +1,659 @@ +\environment publications-style + +\startcomponent publications-customize + +\startchapter[title=Custom renderings,reference=ch:custom] + +\startsection[title=Introduction] + +The rendering of citations and bibliography lists is highly configurable and +custom rendering schemes can be added. The details can get quite complicated so +we will begin with a description of how citation variations can be used in the +running text, followed by a description on how to control the rending of the +associated bibliography list. + +\startaside +Loading the specification file defines a \Index {namespace}, say \TEXcode {apa}, +containing subspaces \TEXcode {apa:list} and \TEXcode {apa:cite} as well as +variants, for example \TEXcode {apa:cite:authoryear}, allowing \emphasis +{parameters} to be tuned independently for each form. This insures independence +but can get somewhat confusing. Most users will not encounter any problems as all +of this setup work is taken care of in the specification file; only those needing +to fine|-|tune specific settings need to better understand the underlying +mechanism. + +The rendering of the variants can be adjusted through \Cindex {setupbtx} in the +appropriate \Index {namespace}, for example modifying (or suppressing) +parenthesis or activating or deactivating interaction \Index {hyperlink}s. Beyond +the settings of parameters in the appropriate \Index {namespace}, +\emphasis{setups} are used to perform the actual renderings of citations as well +as of lists. One must be aware of \Index {namespace} \Index {isolation} and +\Index {inheritance} as well as fall|-|back when attempting to make changes. + +When small modifications on one of the pre|-|defined specifications are desired, +we suggest loading the specification and then adjusting certain parameters and +overloading the appropriate setups. Eventually, a new specification might be +necessary. +\stopaside + +A common setup will enable or disable interaction: + +\startbuffer +\setupbtx [interaction=start] +\stopbuffer + +\cindex{setupbtx} + +\typeTEXbuffer + +Notice that this is applied to the root \Index {namespace}. + +Other root|-|\Index {namespace} parameters that have been used are \TEXcode +{specification}, \TEXcode {dataset} and \TEXcode {numbering}. + +Associated with \TEXcode {specification} is an additional parameter \TEXcode +{default=} that defines a fall|-|back specification to be used to complete a +derived specification. \startfootnote For example, a variant on a specification +can be defined by only addressing specific differences, for example \index +{style+RMP}\TEXcode {specification=rmp} would be associated with \index +{style+APS}\TEXcode {default=aps}, as this describes a style used by the journal: +The Review of Modern Physics, mostly based on the style of the American Physical +Society. \stopfootnote + +Further \quote {low|-|level} formatting parameters, mostly dealing with the +formatting of names, are also defined by default in the root namespace. These are +listed in \in {table} [tab:setupbtx]. Some might eventually be redefined by the +specification in other namespaces, and may with good reason differ by context: +between the \TEXcode {[cite]} and \TEXcode {[list]} namespaces, for example. + +In order to insure the independence of specifications, each one defines its own +root namespace, for example \TEXcode {[default]}, \TEXcode {[apa]} or \TEXcode +{[aps]}, inheriting its settings from root, upon which are built the other +namespaces. + +\startplacetable + [reference=tab:setupbtx, + list={\TEXcode {\setupbtx} low|-|level formatting parameters}, + title={\Cindex {setupbtx} low|-|level formatting parameters. Some may be + redefined differently in the \TEXcode {cite} and \TEXcode {list} namespaces.}] +\starttabulate [|Tr|Tl|p|] + \NC specification \NC default \NC default style \NC \NR + \NC default \NC <null> \NC fall|-|back style \NC \NR + \NC interaction \NC start \NC active hyperlinks \NC \NR + \NC separator \NC \Cindex{btxsemicolon} \NC between multiple references \NC \NR + \NC separator:firstnames \NC \Cindex{btxspace} \NC between first names \NC \NR + \NC separator:juniors \NC \Cindex{btxspace} \NC before \quote{juniors} \NC \NR + \NC separator:vons \NC \Cindex{btxspace} \NC before \quote{vons} \NC \NR + \NC separator:initials \NC \Cindex{btxspace} \NC between initials \NC \NR + \NC stopper:initials \NC . \NC initialization truncation symbol \NC \NR + \NC separator:invertedinitials \NC \Cindex{btxcomma} \NC before initials, inverted form \NC \NR + \NC separator:invertedfirstnames \NC \Cindex{btxcomma} \NC before first names, inverted form \NC \NR + \NC authorconversion \NC normal \NC normal, normalshort, inverted, invertedshort, name (see \in{table}[tab:authorconversion]) \NC \NR + \NC monthconversion \NC number \NC month, month:mnen (see \TEXcode {\convertnumber}) \NC \NR + \NC journalconversion \NC normal \NC normal, abbreviated(short?) \NC \NR + \NC etallimit \NC 3 \NC length of author list \NC \NR + \NC etaldisplay \NC 3 \NC length of truncated author list \NC \NR + \NC \tindex{others}otherstext \NC et al. \NC author list truncation text \NC \NR + \NC separator:names:2 \NC \Cindex{btxcomma} \NC separates multiple names \NC \NR + \NC separator:names:3 \NC \Cindex{btxcomma} \NC before last name in a list \NC \NR + \NC separator:names:4 \NC \Cindex{btxcomma} \NC between only two names \NC \NR + \NC separator:2 \NC \Cindex{btxsemicolon} \NC separates multiple objects \NC \NR + \NC separator:3 \NC \Cindex{btxsemicolon} \NC before last object in a list \NC \NR + \NC separator:4 \NC \Cindex{btxsemicolon} \NC between only two objects \NC \NR +\stoptabulate +\stopplacetable + +\cindex {setupbtx} +\showsetup[setupbtx] + +\stopsection + +\startsection + [reference=sec:customcite, + title=Custom citation renderings] + +\startsubsubject [title=Parameters] + +Citation variants are mostly controlled though adjustment of their parameters +within the appropriate \Index {namespace}. For example, the cite variant \cindex +{cite}\TEXcode {\cite[num]} would be addressed through + + +\cindex {setupbtx} + +\startTEX +\setupbtx[default:cite:num] +\stopTEX + +for the \TEXcode {default} specification, or alternately, through + +\cindex {setupbtx} + +\startTEX +\setupbtx[apa:cite:num] +\stopTEX + +for the \index {style+APA}\TEXcode {apa} specification. For example, superscript +numbered citations in the \index {style+APS}\TEXcode {aps} specification could be +obtained through + +\cindex{setupbtx} + +\startTEX +\setupbtx[aps:cite:num][command=\high] +\stopTEX + +Typical parameters (in addition to those listed in \in {table} [tab:setupbtx]) +are presented in \in {table} [tab:setupbtxcite]. + +\startplacetable + [reference=tab:setupbtxcite, + location=force, + list= {\TEXcode{\setupbtx [cite]} parameters}, + title={\cindex{setupbtx}\TEXcode{\setupbtx[cite]} parameters}] +\starttabulate [|Tr|l|l|] +\NC alternative \NC num \NC default cite form \NC \NR +\NC left \NC \NC opening string \NC \NR +\NC right \NC \NC closing string \NC \NR +\NC inbetween \NC \Cindex{btxspace} \NC \NC \NR +\NC range \NC \TEXcode{\endash} \NC \NC \NR +\NC command \NC \NC \NC \NR +\NC style \NC \NC \NC \NR +\NC sorttype \NC normal \NC \NC \NR +\NC compress \NC yes \NC \NC \NR +\stoptabulate +\stopplacetable + +A demonstration of how these parameters can be manipulated in an individual +\TEXcode {\cite} call is shown in \in{table} [tab:authorconversion], which also +illustrates the different ways of formatting names. + +\startplacetable + [title={\TEXcode{authorconversion}}, + reference=tab:authorconversion] +\starttabulate [|Tl|p|] +\NC ac \NC \TEXcode{\cite[alternative=author,etallimit=,authorconversion=ac][article]} \NC \NR +\HL +\NC name \NC \cite[alternative=author,etallimit=,authorconversion=name] [article] \NC \NR +\NC normal \NC \cite[alternative=author,etallimit=,authorconversion=normal] [article] \NC \NR +\NC normalshort \NC \cite[alternative=author,etallimit=,authorconversion=normalshort] [article] \NC \NR +\NC inverted \NC \cite[alternative=author,etallimit=,authorconversion=inverted] [article] \NC \NR +\NC invertedshort \NC \cite[alternative=author,etallimit=,authorconversion=invertedshort][article] \NC \NR +\stoptabulate +\stopplacetable + +\stopsubsubject + +\startsubsubject [title=Setups] + +The next step in the customization of citation variants is through the overlaying +of setups that handle the actual rendering of the citation. These rarely will +need to be changed as most tuning can be done through the adjustment of +parameters such as those given above. \startfootnote An exception is for special +features, such as in the \index {style+APA}\TEXcode {apa} specification where a +missing date is replaced by the notation \quotation {n..d.}. \stopfootnote + +It is to be pointed|-|out that original citation variants can be easily added. As +an example, imagine that one might like to access the field \TEXcode {abstract} +that is normally not rendered (like many other unused dataset fields). One would +start by defining a parameter \Index {namespace} inheriting from the \TEXcode +{cite} \Index {namespace}, followed by a simple setup (remember that the \TEXcode +{apa} specification is currently active): + +\startbuffer +\definebtx[apa:cite:abstract][apa:cite] +\startsetups btx:apa:cite:abstract + \btxcitereference + \btxflush{abstract} +\stopsetups + +\startparagraph [style=slanted] +\cite[abstract][boekplan::Hagen2010metafun] +\stopparagraph +\stopbuffer + +\cindex{definebtx} +\cindex{btxcitereference} +\cindex{btxflush} +\cindex{cite} +\cindex{startsetups} +\cindex{stopsetups} +\tindex{::} + +\typeTEXbuffer + +\getbuffer + +If no special manipulation is known, the field with the same name (if found) will +be simply flushed. This will only work, however, if the field is identified as +either required or optional, that is not flagged as ignored in \in {table} +[tab:fields] (see also \in {Appendix} [ch:datasetfields]). For the sake of the +present manual, the field \BTXcode{abstract} has been defined as optional for the +\BTXcode{book} entry in the specification's lua file. + +But don't expect too much support for such low|-|level rendering control. + +\stopsubsubject + +\stopsection + +\startsection[title=Custom list renderings,reference=sec:list] + +The rendering of lists is much more flexible and configurable than the rendering +of citation markers. This is because the nature of data to be rendered requires +many tools and helpers to deal with all of the eventual contingencies inherent in +describing bibliographical references. + +The same \quote {low|-|level} formatting parameters used for citations also apply +for \TEXcode {list} \Index {namespace}s, although their settings may differ from +those of the citations. Consider the \index {style+APA}\TEXcode {apa} style that +specifies the use of \tindex {others} \quotation {et al.} in citations but +\quotation {\textellipsis} in the bibliography list, \quotation {and} in +citations but \quotation {\textampersand} in lists, last names only in \TEXcode +{authoryear} citations, etc. + +\startsubsubject[title=Bibliographies as lists] + +At another level of detail, the bibliography list is rendered in a standard +\CONTEXT\ list environment that can be setup using the command \Cindex +{setupbtxlist} (which is only \Cindex {setuplist} working in the protected +bibliography environment: \TEXcode {btx}). The root settings, appropriate for a +numbered bibliography list, are: + +\cindex{setuplist} + +\startTEX +\setuplist + [btx] + [prefixstopper=:, + state=start, + alternative=a, + before=\blank, + after=\blank] +\stopTEX + +whereas an unnumbered, author|-|year sorted list might have: + +\cindex{setupbtxlist} + +\startTEX +\setupbtxlist + [apa] + [alternative=paragraph, + margin=3\emwidth] +\stopTEX + +as already seen in \in {Chapter} [ch:renderings]. The above demonstrate that +\cindex {setupbtxlist}\TEXcode {\setupbtxlist[name]} is just a synonym for +\cindex {setuplist}\TEXcode {\setuplist[btx:name]}. + +\cindex {setupbtxlist} +\showsetup[setupbtxlist] + +\cindex {setuplist} +\showsetup[setuplist] % too big for the page! + +Each specification will have its own list \Index {namespace} (\TEXcode +{btx:specification}) that inherits from the root \TEXcode {btx} \Index +{namespace}. This model of inheritance holds true for the citation and list +details as described earlier. + +\stopsubsubject + +\startsubsubject[title=Setups] + +The layout of the information presented in the list is entirely controlled +through setups, with the help of some underlying \LUA\ code organizing the data +stored in the dataset. These setups rely on further setups as well as some +convenient helpers or defined special commands. To understand this, consider as +an illustration the setups defined for the \TEXcode {default} specification +(taken from the source file \type {publ-imp-default.mkvi}): + +\cindex{startsetups} +\cindex{stopsetups} +\cindex{texdefinition} +\cindex{btxperiod} + +\startTEX +\startsetups btx:default:list:book + \texdefinition{btx:default:author} + \texdefinition{btx:default:title} + \texdefinition{btx:default:editionset} + \texdefinition{btx:default:publisher} + \texdefinition{btx:default:year} + \btxperiod +\stopsetups +\stopTEX + +\cindex{startsetups} +\cindex{stopsetups} +\cindex{texdefinition} +\cindex{btxperiod} + +\startTEX +\startsetups btx:default:list:article + \texdefinition{btx:default:author} + \texdefinition{btx:default:title} + \texdefinition{btx:default:journal} + \texdefinition{btx:default:year} + \btxperiod +\stopsetups +\stopTEX + +This specification could be extended to handle publication categories other than +\TEXcode {book} and \TEXcode {article} simply by defining an additional setup, +\emphasis {almost} (see the following). + +\stopsubsubject + +\startsubsubject[title=\LUA\ tables] + +The qualification above is to bring attention to an important \LUA\ component +that is defined in a companion source file: \TEXcode {publ-imp-default.lua}. This +file defines a hierarchical \LUA\ table containing an element \TEXcode +{categories} that itself contains the entries \TEXcode {book}, \TEXcode +{article}, etc. The entries for each \Index {category} themselves contain the +entries \index {field+required}\TEXcode {required} and \index +{field+optional}\TEXcode {optional} listing the dataset fields that are to be +used. Any field that is not declared either \index {field+required}required or +\index {field+optional}optional will be \index {field+ignored}\emphasis +{ignored}. \startfootnote The difference between \index {field+required}\quote +{required} and \index {field+optional}\quote {optional} is only a question of +diagnostics as described in the Appendices. Their functional meaning is rather +\quote {handled} in contrast to \index {field+ignored}\quote {ignored}. +\stopfootnote Note that if a category is \emphasis {not} declared in this \LUA\ +table, than \emphasis {all} of its fields will be considered \index +{field+optional}\quote {optional}. Thus, ignoring this level of control and +simply defining additional setups might be sufficient for most use. + +The advantage of the \LUA\ table is a great simplification of the logic of the +helper setups. Fields that might be irrelevant for one category yet used in +another can be tested; if the field is to be \index {field+ignored}\quote +{ignored}, than a fetch will return nothing. Indeed, the above two setups could +be replaced by a single setup as \TEXcode {journal} is irrelevant and thus +ignored for the \Index {category} \TEXcode {book} but not for the \Index +{category} \TEXcode {journal}. However, an oversimplification such as just +described would be rather confusing and would not extend well to a more complete +specification (such as \index {style+APA}\TEXcode {apa}) handling many different +categories. + +Note, as well, that fields \index {field+ignored}\quote {ignored} for certain +\index {category}categories in the bibliography list will also be ignored in +citations. For example, choosing to ignore \TEXcode {title} in some \Index +{category}, say \TEXcode {article}, will cause \TEXcode {\cite[title]} to fail +(return nothing) when referring to an entry of that category. In the example +shown in \in {section} [sec:customcite], the abstract field would not return +anything if it did not appear in the \LUA\ table. + +This \LUA\ table also defines (as \index {type}\quote {types}, outside of \index +{category}\quote {categories}) what fields are to be interpreted as names, what +fields are to eventually be interpreted as a number or range of numbers, and what +fields are to be interpreted specially as a (semi|-|colon) separated list (for +example, \TEXcode {keywords}). + +A more subtle feature of the \LUA\ level is the notion of \index {set}\quote +{sets}. Related fields can be grouped into sets, for example. + +\startLUA +book = { + sets = { + author = { "author", "editor", }, + editionset = { "edition", "volume", "number" }, + }, +}, +\stopLUA + +A fetch of the set \text {author} (i.e. \cindex {btxflush}\TEXcode +{\btxflush{author}}, to be described below) will return the \text {author} field +if this is present, otherwise it will return the \TEXcode {editor} field, for an +edited book, for example. Testing for the presence of a set in a data entry is +equivalent to a logical \emphasis{or} in testing for the presence of each element +of the set. This mechanism can appear confusing yet it has served to greatly +simplify the logic of the various setups. \startfootnote Sometimes a \Index {set} +will be defined using the same name as its first element, sometimes it can be +given a unique name (typically ending in \quote {set}). \stopfootnote + +The \TEXcode {author} set is a bit special given its use in the \TEXcode +{authoryear(s)}, \TEXcode {authornum}, and \TEXcode {short} citation variants. +This \Index {set} determines what fields are to enter into the citation \Index +{tag}s, a generalization of the notion of author. For example, in the \index +{style+APA}APA style, this set would include the author, editor, or title fields +or an article and the author, editor, publisher, or title fields for a book and +still other sequences of fields for other categories of publications. + +\stopsubsubject + +\startsubsubject[title=Defined helpers] + +Fetching data from the dataset is performed using the command encountered above: +\TEXcode {\btxflush}. If the field (or no elements of the set) is not found, then +this command will return nothing. + +\cindex {btxflush} +\showsetup[btxflush] + +Alternately, one might need to explicitly test for the presence or absence of the +field, in order to conditionally include punctuation or not to trigger +separators, for example. Three test macros have been defined: + +\startplacetable [title=Conditional macros] +\cindex{btxdoifelse} +\cindex{btxdoif} +\cindex{btxdoifnot} +\startTEX +\btxdoifelse{fieldname}{action when found}{action when not found} +\btxdoif {fieldname}{action when found} +\btxdoifnot {fieldname} {action when not found} +\stopTEX +\stopplacetable + +In many cases, the readability can be improved by using further setups, for +instance: + +\cindex{btxdoifelse} +\cindex{fastsetup} + +\startTEX +\btxdoifelse {author} { + \fastsetup{btx:apa:author:yes} +} { + \fastsetup{btx:apa:author:nop} +} +\stopTEX + +Note that the choice between using setups (defined through \Cindex {startsetups} +\unknown\ \Cindex {stopsetups} and recalled through \Cindex {fastsetup}) versus +textdefinitions without arguments (defined through \Cindex {starttexdefinition} +\unknown\ \Cindex {stoptexdefinition} and recalled through \Cindex +{texdefinition}) is a question of taste and opportunity. One should keep in mind +not get carried away abusing setups and texdefinitions for simple code fragments +that are to be used uniquely. + +An extra conditional is available for testing interactivity: + +\cindex{btxdoifelseinteraction} + +\startTEX +\btxdoifelseinteraction{action when true}{action when false} +\stopTEX + +There is also a conditional \Cindex {btxinteractive} which is more efficient, +although in practice efficiency is not so important here. + +\blank + +In addition to \Index {set}s, there are derived or special fields such as +\TEXcode {num} (for the reference number), \TEXcode {suffix} (to be appended in +some cases to \TEXcode {year}), \TEXcode {short} (for names), etc. These all can +be retrieved using \Cindex {btxflush}. Sometimes one might want to force access +to a particular data field (such as \TEXcode {author}) rather than eventually an +element of a \Index {set} having the same name. There are three basic commands to +flush data and a few others to flush associated information: + +\startplacetable [title=Field access macros] +\starttabulate[|l|l|] +\NC \Cindex{btxflush} \NC fetch a derived or explicit field \NC \NR +\NC \Cindex{btxdetail} \NC fetch a derived field (e.g.\ \TEXcode {short}) \NC \NR +\NC \Cindex{btxfield} \NC fetch a explicit field (e.g.\ \TEXcode {year}) \NC \NR +\NR +\NC \Cindex{btxfieldname} \NC fetch the field name \NC \NR +\NC \Cindex{btxfieldtype} \NC fetch the field type (e.g.\ \TEXcode{author}, \TEXcode{range}, \unknown \NC \NR +\NC \Cindex{btxfoundname} \NC fetch the field name of a set (or field) \NC \NR +\NC \Cindex{btxfoundtype} \NC fetch the field type of a set (or field) \NC \NR +\stoptabulate +\stopplacetable + +A few helpers are provided to inject symbols but also take care of leading and +trailing spaces: \startfootnote These make use of the \CONTEXT\ command \Cindex +{removeunwantedspaces}. There is also a \quote {secret} command \TEXcode +{\removepunctuation} that can be quite useful, but also lead to undesired +consequences when wielded blindly! \stopfootnote + +\startplacetable [title=Punctuation macros] +\starttabulate[|||] +\NC \Cindex{btxspace} \NC before \btxspace after \NC \NR +\NC \Cindex{btxnbsp} \NC before \btxnbsp after \NC \NR +\NC \Cindex{btxnobreakspace} \NC before \btxnobreakspace after (same as \Cindex {btxnbsp}) \NC \NR +\NC \Cindex{btxperiod} \NC before \btxperiod after \NC \NR +\NC \Cindex{btxcomma} \NC before \btxcomma after \NC \NR +\NC \Cindex{btxcommabreak} \NC before \btxcommabreak after (allows a line break) \NC \NR +\NC \Cindex{btxleftparenthesis} \NC before \btxleftparenthesis after \NC \NR +\NC \Cindex{btxrightparenthesis} \NC before \btxrightparenthesis after \NC \NR +\NC \Cindex{btxrightparenthesiscomma} \NC before \btxrightparenthesiscomma after \NC \NR +\NC \Cindex{btxrightparenthesisperiod} \NC before \btxrightparenthesisperiod after \NC \NR +\NC \Cindex{btxleftbracket} \NC before \btxleftbracket after \NC \NR +\NC \Cindex{btxrightbracket} \NC before \btxrightbracket after \NC \NR +\NC \Cindex{btxrightbracketcomma} \NC before \btxrightbracketcomma after \NC \NR +\NC \Cindex{btxrightbracketperiod} \NC before \btxrightbracketperiod after \NC \NR +\stoptabulate +\stopplacetable + +\stopsubsubject + +\starthiding + +Normally you can use \TEXcode {\btxfield} or \TEXcode {\btxflush} as derived +fields just like analyzed author fields are flushed in a special way. There is +experimental support for so called manipulators. You can for instance say this: + +\starttyping +\btxflush{lowercase->title} +\stoptyping + +A sequence of manipulators is applied to fetched field, where a sequence is one +or more manipulators: + +\starttyping +\btxflush{stripperiod->uppercase->title} +\stoptyping + +Some actions are recognized (built|-|in) but you can also use actions from other +namespaces, like in: + +\starttyping +\btxflush{converters.Word -> title} +\stoptyping + +Watch how we can use spaces around the \TEXcode {->} which is nicer for wrapped +around usage. Eventually, we might put some more function in the default +namespace. + +So, the previous example setup can be rewritten as: + +\starttyping +\btxdoif {title} { + \bold{\btxfield{title}} + \btxcomma +} +\stoptyping + +There is a special command for rendering a (combination) of authors: + +\starttyping +\btxflushauthor{author} +\btxflushauthor{editor} +\btxflushauthor[inverted]{editor} +\stoptyping + +Instead of the last one you can also use: + +\starttyping +\btxflushauthorinverted{editor} +\stoptyping + +You can use a (configurable) default or pass directives: Valid directives are + +\starttabulate +\NC \bf conversion \NC \bf rendering \NC \NR +\HL +\NC \TEXcode{inverted} \NC the Frog jr, Kermit \NC \NR +\NC \TEXcode{invertedshort} \NC the Frog jr, K \NC \NR +\NC \TEXcode{normal} \NC Kermit, the Frog, jr \NC \NR +\NC \TEXcode{normalshort} \NC K, the Frog, jr \NC \NR +\stoptabulate + +The list itself is not a list in the sense of a regular \CONTEXT\ structure +related list. We do use the list mechanism to keep track of used entries but that +is mostly because we can then reuse filtering mechanisms. The actual rendering of +a reference and entry runs on top of so called constructions (other examples of +constructions are descriptions, enumerations and notes). + +\showsetup[setupbtxlist] + +You need to be aware what command is used to achieve the desired result. For +instance, in order to put parentheses around a number reference you say: + +\starttyping +\setupbtxlistvariant + [num] + [left=(, + right=)] +\stoptyping + +If you want automated width calculations, the following does the trick: + +\starttyping +\setupbtxrendering + [default] + [width=auto] +\stoptyping + +but if you want to control it yourself you say something: + +\starttyping +\setupbtxrendering + [width=none] + +\setupbtxlist + [default] + [width=3cm, + distance=\emwidth, + color=red, + headcolor=blue, + headalign=flushright] +\stoptyping + +In most cases the defaults will work out fine. + +Normally the references are numbered using one counter for the whole document. If +you want each list to have its own number, then you can set the \TEXcode +{continue} parameter: + +\starttyping +\setupbtxrendering[continue=no] +\stoptyping + +In a similar fashion you can influence if references are included only once of in +each list: + +\starttyping +\setupbtxrendering[repeat=yes] +\stoptyping + +\stophiding + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/publications/publications-database.tex b/doc/context/sources/general/manuals/publications/publications-database.tex new file mode 100644 index 000000000..656ace56d --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-database.tex @@ -0,0 +1,553 @@ +\environment publications-style + +\startcomponent publications-database + +\startchapter[title=The database] + +The bibliography subsystem uses a database (or a set of databases) to construct a +list of citations to be used in a scholarly work. However, it will be shown later +that the database system can be used (and abused) to many ends having little or +nothing at all to do with citations and bibliographies. Nevertheless, at first we +shall remain focused on the use of bibliography databases. + +The data to be used must have a source and a structure. In the next sections we +describe the possible input. + +\startsection[title=\BibTeX] + +The \BIBTEX\ format is rather popular in the \TEX\ community and even with its +shortcomings it will stay around for a while. Many publication websites can +export and many tools are available to work with this database format. It is +rather simple and looks a bit like \index [LUA table] {\LUA\ table}\LUA\ tables. +Indeed, it is said that the \BIBTEX\ format was one of the inspirations for the +constructor syntax in \LUA\ \cite [alternative=num, +righttext={\btxcomma Chapter\nbsp 12.}] [default::Ierusalimschy2006]. + +Unfortunately the content can be (and usually is) polluted with +non|-|standardized \TEX\ commands which complicates pre- or post|-|processing +outside \TEX. In that sense a \BIBTEX\ database is often not coded neutrally. +Some limitations, like the use of commands to encode accented characters root in +the \ASCII\ world and can be bypassed by using \index [UTF] {\UTF}\UTF\ instead +(as handled somewhat in \LATEX\ through extensions such as \Tindex {bibtex8}). + +The normal way to deal with a bibliography is to refer to entries using a unique +\Index {tag} or key. When a text containing a list of entries is typeset, this +reference can be used for linking purposes. The list can be processed and sorted +using the \Tindex {bibtex} program that converts the database into something more +\TEX\ friendly (a \Tindex {.bbl} file). + +In \CONTEXT\ we no longer use the (external) \goto {\Tindex {bibtex} program} +[url(https://www.ctan.org/pkg/bibtex)] at all: we simply parse the database files +in \LUA\ and deal with the necessary manipulations directly in \CONTEXT. One or +more such databases can be used and combined with additional entries defined +within the document. We can have several such datasets active at the same time. + +\startaside +\emphasis {On the name \Tindex {btx}:} many of the \CONTEXT\ commands that will be +used in the following contain the label \TEXcode {btx} in their name. This +identifier was retained despite the fact that \CONTEXT\ \MKIV\ is now completely +independent of \BIBTEX; it reflects the role still played by \BIBTEX\ data as a +preferred source format and serves as a handy, unique identifier, both internally +in the programming as well as for the user. This three|-|letter label is +systematically used in commands that otherwise attempt to avoid cryptic|-|styled +names. +\stopaside + +A \BIBTEX\ file entry looks like this: + +\startBTX +@Article {sometag, + author = "An Author and Another One", + title = "A hopefully meaningful title", + journal = maps, + volume = "25", + number = "2", + pages = "5--9", + month = mar, + year = "2013", + ISSN = "1234-5678", +} +\stopBTX + +Entries are of the form: \index {category}\BTXcode {@category{...}} + +Anything outside of a valid \BTXcode {@category{...}} construction is ignored and +is taken to be a comment. Within an entry, there are to be no comments but one +can prefix field names, for example, to have them ignored. + +There is a special entry type named \index {@comment}\BTXcode {@comment{...}}. +The main use of such an entry type is to comment a large part of the bibliography +easily, since anything outside an entry is already a comment, and commenting out +one entry may be achieved by just removing its initial~\BTXcode {@}. — The \index +{@comment}\BTXcode {@comment{...}} entry is perhaps of some use, although this is +not very elegant! As one can input multiple bibliography data files, as will be +seen below, it is much better practice to split datafiles for optional loading. + +Many \BIBTEX\ data management tools such as \Tindex {jabref} (see below) will +ignore and then throw|-|away all such handily|-|crafted comments and data entries +turned into comments. So one must beware! + +The field names are all cast to lowercase so capitalization is irrelevant; +Spacing is not important and should be used advantageously for readability. The +leading \Index {tag} (\BTXcode {sometag} in the example above) cannot contain +spaces and \emphasis {must} be followed by a comma. + +The entry \Index {tag} (\BTXcode {@category{sometag,...}}) is not to be confused +with the optional field \BTXcode {key=sortkey,} that may also be present. + +Normally a value is given between quotes (or curly brackets) but single words are +also valid (as there is no real benefit in not using quotes or curly brackets, we +advise to always use them, contrary to our example above). The order of the +fields in an entry is inconsequential and there can be many more fields than +those shown above. Instead of string values one can also use predefined +shortcuts. The title for example might quite often contain \TEX\ macros, and some +fields, like \BTXcode {pages} have funny characters such as the endash (typically +entered as \BTXcode {--}) so we have a mixture of data and typesetting +directives. Furthermore, if you are covering non||English references, you often +need characters that are not in the \ASCII\ subset. Note that \CONTEXT\ is quite +happy with \UTF, but if your database file uses old|-|fashioned \TEX\ accent +combinations then these will be internally converted automatically to \UTF. + +Commands (macros) found in a database file are converted to an indirect call, +which is quite robust. The use of commands in the database file will be described +in \in {section} [sec:Commands]. + +The \Tindex {author} (and \Tindex {editor}) fields are parsed separating multiple +authors identified by the conjunction \quote {and}. Each name is assumed to be in +the form: + +\definetyping + [NameSyntax] + [margin=1em] + +\startNameSyntax +Firstname(s) Lastname +\stopNameSyntax + +\seeindex {vons} {particule} + +where \type {Lastname} is a single word but may include an optional (nobility) +\Index {particule}: lower|-|case word(s) such as \quotation {von}, \quotation +{de}, \quotation {de la}, etc.) \emphasis {unless} specifically in the two- or +three|-|token form: + +\index {suffix} + +\startNameSyntax +Lastname(s), Firstname(s) +Lastnames(s), Suffix(es), Firstname(s) +\stopNameSyntax + +separated explicitly using comma(s) thus allowing multi|-|word \type {Lastnames}. + +\startaside +An \BTXcode {author} field is sometimes abused in traditional \BIBTEX\ usage to +hold not a name but rather an entity. Other fields, such as \BTXcode +{organization} or \BTXcode {collaboration}, for example, should be used in such +cases. +\stopaside + +\BIBTEX\ also (obscurely) supports the syntax: + +\seeindex {juniors}{suffix} +\index {suffix} + +\startNameSyntax +Firstname(s) \{Lastname(s), Suffix(es)\} +\stopNameSyntax + +we may (or may not) support this in the future, so don't use this! + +We extend \BIBTEX\ by optionally parsing each name in terms of four or five +tokens: + +\index {particule} \index {suffix} \index {initial} + +\startNameSyntax +Particule(s), Lastname(s), Suffix(es), Firstname(s) +Particule(s), Lastname(s), Suffix(es), Firstname(s), Initial(s) +\stopNameSyntax + +in order to allow a free form for the particules, irrespective of capitalization, +thus avoiding the need to resort to any sort of \TEX\ trickery \cite [num] +[default::Patashnik1988,Markey2009]. In fact, an optional sixth token is parsed +whose meaning is presently reserved for future directives describing how the name +is to be interpreted: + +\index {particule} \index {suffix} \index {initial} + +\startNameSyntax +Particule(s), Lastname(s), Suffix(es), Firstname(s), Initial(s), directives +\stopNameSyntax + +\BIBTEX\ additionally accepts the special token \Tindex {others} to be used +(sparingly) to indicate an incomplete author list. Note that most style +specifications will handle the truncation of long author lists in a systematic +fashion. The \index [others] {\tt and others}\BTXcode {and others} construction +finds its use when the complete author list is not well known or ill|-|defined. + +Sometimes, or even often, the database might contain variants of an author's +name that we would like to identify as a single, unique author. Indeed, certain +bibliographic styles (as will be seen later) as well as an index of authors, for +example, will depend on this identification. A command \Cindex {btxremapauthor} +allows establishing this identity: + +\startbuffer +\btxremapauthor [Donald Knuth] [Donald E. Knuth] +\btxremapauthor [Don Knuth] [Donald E. Knuth] +\stopbuffer +\getbuffer + +\cindex {btxremapauthor} +\typebuffer [option=TEX] + +Fields other than \Tindex {author} and \Tindex {editor}, for example \Tindex +{artist} or \Tindex {director} if one desires, can be declared to be of type +\quote {author} and thus interpreted as names, but this is a subject for +specialists. + +The \BTXcode {keywords} field can also be split into tokens separated by +semicolons (keyword; keyword; \unknown). This can be useful, as will be seen +later, in the creation of keyword indexes, for example. + +Other string values such as \BTXcode {title} are kept literally (except for an +internal automatic conversion to \UTF\ of certain \TEX\ strings such as accent +combinations, endash, quotations, etc.). Note that the bibliography rendering +style (see below) might specify a capitalization of the title (using the +\CONTEXT\ commands \TEXcode {\Word} or \TEXcode {\Words}, for example). +Capitalized Names and acronyms are respected removing a need for the \BIBTEX\ +practice of \quote {protecting} such words or letters with surrounding curly +brackets (which here are simply stripped off). (Furthermore, since \CONTEXT\ uses +\UTF, it does not suffer from all of the complicated \Index {sorting} issues that +plague \BIBTEX|/|\LATEX.) As some styles might not specify the capitalization of +words in the title whereas other styles might, it is recommended that strings be +written in lower case except where upper case is explicitly required so as to be +compatible with all such capitalization styles. + +\startaside +Some bibliographic database sources can be quite sloppy and return strings +(titles and even authors) in all capitals, for example. We have made the design +choice \emphasis {not} to follow the \BIBTEX\ practice/feature of explicitly +formatting all string values, as we did not want to require the protection +through enclosing curly brackets that would have been a necessary consequence. +Thus, some cleaning of these database files might be needed. Furthermore, we +attempt to use all the power of \CONTEXT\ and \LUA, thus making unnecessary much +(most?) of the \TEX-like encoding of the data. We encourage users to clean|-|up +their \Tindex {.bib} database files as much as possible so that they contain only +the necessary data, with a minimum of explicit formatting directives. +\stopaside + +String values, as described above, can be enclosed indifferently between matching +curly brackets: \BTXcode {{}} or pairs of quotation marks: \BTXcode {""}. +Multiple string values can be \index {string concatenation}concatenated using the +operator \BTXcode {\#}, as will be illustrated in \in {table} +[tab:mkiv-publications.bib]. + +Everything outside of a valid entry is ignored and treated as a \Index {comment}. +Syntactic errors (such as a missing comma or some unbalanced quotes or +parenthesis) are also skipped over, i.e. ignored. This is to attempt to continue +on to valid data but may lead to unexpected results. It is therefore the user's +responsibility to insure the correctness of the data files. Whereas some checks +and warnings are issued, the system is purposefully not too verbose. + +Data is handled on a \quote {first come, first served} basis: duplicate \index +{duplicate+fields}\emphasis {fields} in an entry are ignored \startfootnote Note +that some \BIBTEX\ practice allows for the concatenation of duplicate name \index +{duplicate+fields}fields (i.e. \BTXcode {author} and \BTXcode {editor}) through +\BTXcode {and}, but (silently) ignores duplicate other fields. We choose to have +a consistant behavior and disallow duplicate field occurrences. \stopfootnote +though duplicate \index {duplicate+entries}\emphasis {entries} (having the same +\index {duplicate+tags}tag) are retained, but the subsequent identical \Index +{tag}s will be modified by adding a suffix $-n$ for the $n$\high {th} duplicate. +The presence of duplicate \index {duplicate+fields}fields or \index +{duplicate+tags}tags will be flagged as such with warnings in the log file. +Duplicate \index {duplicate+entries}entries using different \Index {tag}s will +not be treated as duplicates. + +A special provision has been made to declare author \Index {synonyms}, that is +names that might occur with a variation of spellings or aliases. This shall be +discussed later. + +We have attempted to remain compatible with the \BIBTEX\ format, and any new +bibliography extensions that we introduce here were designed in a way to remain +compatible with \BIBTEX, being simply ignored rather than potentially generating +a \BIBTEX\ error. + +The \BIBTEX\ files are loaded in memory as \LUA\ table but can be converted to +\XML\ so that we can access them in a more flexible way, but that is another +subject for specialists. + +\stopsection + +\startsection [reference=sec:Commands,title=Commands in entries] + +One unfortunate aspect commonly found in \BIBTEX\ files is that they may contain +\TEX\ commands. Even worse is that there is no standard on what these commands +can be and what they mean, at least not formally, as \BIBTEX\ is a program +intended to be used with many variants of \TEX\ style: plain, \LATEX, and others. +This means that we need to define our use of these typesetting commands. (In +particular, one might need to redefine those that are too \LATEX|-|centric.) +However, in most cases, they are just abbreviations or font switches and these +are often well known. Therefore, \CONTEXT\ will try to resolve them before +reporting an issue. The log file will announce the commands that have been seen +in the loaded databases. For instance, loading \Tindex {tugboat.bib} (distributed +with \TEXLIVE) gives a long list of commands of which we show a small set of the +five most frequently encountered ones here: + +\startbuffer +\definebtxdataset[tugboat] +\usebtxdataset[tugboat][tugboat.bib] +\stopbuffer + +\getbuffer + +\starttyping +publications > tugboat tt 134 known +publications > tugboat Dash 136 unknown +publications > tugboat acro 137 known +publications > tugboat LaTeX 209 known +publications > tugboat TeX 856 known +\stoptyping + +Some are flagged as known and others as unknown. You can define unknown commands, +or overload existing definitions in the standard way (\emphasis {e.g.} \TEXcode +{\def\Dash{—}}), the \CONTEXT\ way (\TEXcode {\define\Dash{—}}) or, +alternatively, in the following way: + +\cindex {definebtxcommand} + +\startTEX +\definebtxcommand\TUB {TUGboat} +\definebtxcommand\MP {METAPOST} +\definebtxcommand\sltt{\tt} +\definebtxcommand\<#1>{\type{#1}} +\stopTEX + +\definebtxcommand\MP {METAPOST} % to be used silently below + +Custom commands created using \Cindex {definebtxcommand} have the advantage of +using a separate name space thus allowing \Index {isolation} from other \CONTEXT\ +commands. (The \Index {isolation} of \Cindex {btxcommand} allows the \Tindex +{.bib} files to safely contain \TEX\ and \LATEX\ idiosyncrasies that might +conflict with proper \CONTEXT\ syntax.) Unknown commands do not stall processing, +but their names are then typeset in a mono|-|spaced font so they probably stand +out for proofreading. You can access the commands using \index +{btxcommand}\TEXcode {\btxcommand{...}} (or \Cindex {btxcmd}), as in: + +\startbuffer +commands like \btxcommand{MySpecialCommand} are handled in an indirect way +\stopbuffer + +\cindex {btxcommand} + +\typeTEXbuffer + +As this is an undefined command we get: \quotation {\inlinebuffer}. + +Often, these embedded \TEX\ commands are present in \Tindex {.bib} files in order +to trick \BIBTEX\ into certain behavior. Since this will generally not be +necessary here, we strongly encourage users to clean|-|up such unnecessary +extras. Indeed, the idea is to keep the data clean, using styles and parameter +settings instead to handle rendering issues. Indeed, we don't see it as challenge +nor as a duty to support all kinds of messy definitions. Of course, we try to be +somewhat tolerant, but you will be sure to get better results if you use nicely +setup, consistent databases. + +Finally, the \BIBTEX\ entry \tindex {@string}\BTXcode {@String{}} is preprocessed +as expected. + +\tindex {@string} + +\startTEX +@String{j-TUGboat = "TUGboat"} +\stopTEX + +\startaside +Notice that \Tindex {tugboat.bib} also contains: \tindex {@preamble} +\startBTX +@Preamble{"\input tugboat.def"} +@Preamble{"\input path.sty"} +\stopBTX +These are silently ignored as many such commands are most likely not to be +compatible with \CONTEXT. Indeed, the examples shown here are not! +\stopaside + +\stopsection + +\startsection[title=\MKII\ definitions] + +In the old \MKII\ setup we have two kinds of entries: the ones that come from the +\BIBTEX\ run and additional user|-|supplied ones. We no longer rely on \BIBTEX\ +output but we do still support the user supplied definitions. These were in fact +prepared in a way that suits the processing of the \BIBTEX\ generated entries; +The next variant reflects the \CONTEXT\ recoding of the old \BIBTEX\ output. For +this reason, some users refer to this as \Tindex {.bbl} format. + +\cindex {startpublication} +\cindex {stoppublication} + +\startTEX +\startpublication[k=Hagen:Second,t=article,a={Hans Hagen},y=2013,s=HH01] + \artauthor[] {Hans}[H.]{}{Hagen} + \arttitle {Who knows more?} + \journal {MyJournal} + \pubyear {2013} + \month {8} + \volume {1} + \issue {3} + \issn {1234-5678} + \pages {123--126} +\stoppublication +\stopTEX + +The split \TEXcode {\artauthor} fields will be collapsed into a single \TEXcode +{author} field as we handle the splitting later when it gets parsed in \LUA. The +\TEXcode {\artauthor} syntax is only kept around for backward compatibility with +the previous use of \BIBTEX. + +In the new setup we support these variants: + +\cindex {startpublication} +\cindex {stoppublication} + +\startTEX +\startpublication[k=Hagen:Third,t=article] + \author{Hans Hagen} + \title {Who knows who?} + ... +\stoppublication +\stopTEX + +as well as + +\cindex {startpublication} +\cindex {stoppublication} + +\startTEX +\startpublication[tag=Hagen:Third,category=article] + \author{Hans Hagen} + \title {Who knows who?} + ... +\stoppublication +\stopTEX + +and + +\cindex {startpublication} +\cindex {stoppublication} + +\startTEX +\startpublication + \tag {Hagen:Third} + \category{article} + \author {Hans Hagen} + \title {Who knows who?} + ... +\stoppublication +\stopTEX + +The use of this format will be illustrated later a means to export the database +which may be of great use in converting collections of \MKII\ bibliography files. + +\showsetup[startpublication] + +\stopsection + +\startsection[title=\LUA\ tables] + +Because internally the entries are \index [LUA table] {\LUA\ table}\LUA\ tables, +we also support the loading of \LUA\ based definitions: + +\startLUA +return { + ["Hagen:First"] = { + author = "Hans Hagen", + category = "article", + issn = "1234-5678", + issue = "3", + journal = "MyJournal", + month = "8", + pages = "123--126", + tag = "Hagen:First", + title = "Who knows nothing?", + volume = "1", + year = "2013", + }, +} +\stopLUA + +Notice that the \Index {tag} is redundantly specified; it is \quote {pushed} into +the table so that one can access it without having to know the \Index {tag} of the +original table. + +\stopsection + +\startsection[title=\XML] + +The following \index [XML] {\XML}\XML\ input is rather close in structure, and is +also accepted as input. + +\startXML +<?xml version="2.0" standalone="yes" ?> +<bibtex> + <entry tag="Hagen:First" category="article"> + <field name="author">Hans Hagen</field> + <field name="category">article</field> + <field name="issn">1234-5678</field> + <field name="issue">3</field> + <field name="journal">MyJournal</field> + <field name="month">8</field> + <field name="pages">123--126</field> + <field name="tag">Hagen:First</field> + <field name="title">Who knows nothing?</field> + <field name="volume">1</field> + <field name="year">2013</field> + </entry> +</bibtex> +\stopXML + +We shall focus on the use of \BIBTEX\ \Tindex {.bib} files as the input data +format of reference. Keep in mind, however, that the \index [LUA table] {\LUA\ +table}\LUA\ table format and the \index [XML] {\XML}\XML\ format might prove to +be more flexible for future expansion of functionality. + +\stopsection + +\startsection[title=Other formats] + +Various other bibliographic data file formats are in common use, such as: + +\starttabulate [|Tl|p|] +\NC savedrecs.txt \NC Institute of Scientific Information (ISI) tagged format + (e.g. Thomson Reuters™ Web of Science™), \NC \NR +\NC filename.enw \NC Thomson Reuters™ Endnote™ export format + (there is also an Endnote \type {.xml} export), \NC \NR +\NC filename.ris \NC Research Information Systems, Incorporated, now + Thomson Reuters™ Reference Manager™, and \NC \NR +\NC pubmed_result.txt \NC The National Library of Medicine® (NLM®) + MEDLINE®|/|PubMed® data format \NC \NR +\stoptabulate + +just to name a few (amongst many more). Filters can be easily written in \LUA\ to +read these and other bibliography data formats, although no such filters are +provided. This is because the user has a choice of a certain number of +bibliography database management programs that can easily convert from these to +the \BIBTEX\ format. (Notable, open source examples are \index {jabref} \goto +{jabref} [url(http://jabref.sourceforge.net)] and \index {zotero} \goto {zotero} +[url(http://www.zotero.org)].) Indeed, it is not the vocation of the present +\CONTEXT\ bibliography subsystem to fully manage the bibliography data sources, +only to be able to use such data in the production of documents. + +\startaside +\emphasis {A note on database management programs:} these are very valuable tools +for the manipulation of bibliography database information, which is why the +\BIBTEX\ format has so much importance for us here. However, one must be aware +that these programs are not standards and many of them may introduce invalid +extensions that might not even be handled correctly by \BIBTEX\ itself. +\stopaside + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/publications/publications-datasets.tex b/doc/context/sources/general/manuals/publications/publications-datasets.tex new file mode 100644 index 000000000..d612b72e0 --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-datasets.tex @@ -0,0 +1,337 @@ +\environment publications-style + +\startcomponent publications-datasets + +\startchapter[title=Datasets] + +Normally in a document you will use only one bibliographic database, whether or +not its source is distributed over multiple files. Nevertheless, we support +multiple database formats as well which is why we talk of datasets instead. The +use of multiple datasets allows the isolation of different bibliographies (a +single bibliography can nevertheless be rendered by structure element: section, +chapter, part, etc. as we shall see later). A good example of the use of multiple +datasets would be for a proper bibliography itself in addition to a reference +catalog (of equipment, suppliers, software, patents, legal jurisprudence, music, +\unknown). Indeed, datasets can be used to hold both bibliographic and +non|-|bibliographic information. + +A dataset is initiated with the \Cindex {definebtxdataset} command. + +\cindex {definebtxdataset} + +\startTEX +\definebtxdataset[default] +\stopTEX + +\startaside +A default database, \TEXcode {default}, is predefined, yet we recommend defining +it explicitly because in the future we may provide more options. +\stopaside + +Like other commands in \CONTEXT, the dataset options can be setup using the +command \Cindex {setupbtxdataset}. + +\cindex {definebtxdataset} +\showsetup[definebtxdataset] + +\cindex {setupbtxdataset} +\showsetup[setupbtxdataset] + +A dataset is loaded from some source through the use of the +\Cindex {usebtxdataset} command. + +Here are some examples: + +\cindex {usebtxdataset} +\tindex {.bib} +\tindex {.xml} +\tindex {.lua} +\tindex {.bbl} + +\startTEX +\usebtxdataset[tugboat][tugboat.bib] +\usebtxdataset[default][mtx-bibtex-output.xml] +\usebtxdataset[default][test-001-btx-standard.lua] +\usebtxdataset[default][mkii-publications.bbl] +\usebtxdataset[default][named.buffer] +\stopTEX + +\cindex {usebtxdataset} +\showsetup[usebtxdataset] + +The four suffixes illustrated in the example above are understood by the loader. +Here the dataset (other than the first) has the name \TEXcode {default} and the +four database files are merged. The last example shows that a \TEXcode {named} +\Index {buffer} can also be employed to add dataset entries (in \BIBTEX\ format). +This may be useful for small additions or examples, but it is generally a better +idea (for convenience of management of data) to place them in files separate from +the document source code. + +Definitions in the document source (coded in \TEX\ speak) are also added, and +they are saved for successive runs. This means that if you load and define +entries, they will be known at a next run beforehand, so that references to them +are independent of where in the document source loading and definitions take +place. This is convenient to eventually break|-|up the dataset loading calls to +relevant sections of the document structure. + +In this document we use some example databases, so let's load one of them now: +\startfootnote This code snippet demonstrates that \TEXcode {\usebtxdataset} will +implicitly declare an undefined dataset name, although this practice is to be +discouraged. Similarly, omitting to specify the dataset name \TEXcode {[default]} +in the examples given earlier would fall|-|back correctly, but this, too, is to +be discouraged as being potentially error|-|prone. \stopfootnote + +\startbuffer +\usebtxdataset[example][mkiv-publications.bib] +\stopbuffer + +\cindex {definebtxdataset} +\cindex {usebtxdataset} + +\typeTEXbuffer + +\getbuffer + +The beginning of the file \type {mkiv-publications.bib} is shown below in \in +{table} [tab:mkiv-publications.bib]. This bibliography database test file +contains one entry of each standard type or category, with the \Index {tag} set +to the entry type name. This entry shown here illustrates many features that will +be explained elsewhere in the text. + +\startsection[title=Dataset coverage] + +You can load much more data than you actually need. Usually only those entries +that are referred to explicitly will be shown in lists, and commands used to +select these dataset entries will described in \in {chapter} [ch:cite]. + +A single bibliography list can span groups of datasets; also multiple datasets +can loaded from the same source, for example, one per chapter, in order to +achieve a complete \Index {isolation} of bibliographies with respect to numbering +and references. + +As this concept is not obvious but can be quite useful, we will repeat this last +point: multiple datasets can be loaded using the same source file, i.e.\ +containing the same data, to be used in parallel, independently. There is little +penalty in keeping even very large datasets as multiple copies in memory. + +The current active dataset to be used by default can be set with + +\startbuffer +\setupbtx[dataset=example] +\stopbuffer + +\cindex {setupbtx} + +\typeTEXbuffer + +\getbuffer + +However, most publication|-|related commands accept optional arguments that +denote the dataset and references to entries can always be prefixed with a +dataset identifier. More about that later. + +\showsetup[setupbtx] + +\stopsection + +\startsection [title=Specification] + +The content of a dataset can really be anything: entries of type (or categories) +of all sorts, each containing arbitrary fields. The use to be made of this data +can vary greatly since the system is not limited to the production of +bibliography lists, in particular. The intended use is reflected through a set of +specifications, specific to each bibliography (or non|-|bibliography) style. +These specifications affect the interpretation of dataset categories and fields +as well as their rendering. They will also affect the rendering of citations or +the reference or invocation of individual data entries. + +The \TEXcode {default} bibliography specification is very simple: only the +categories \TEXcode {book} and \TEXcode {article} are explicitly defined. These +were shown along with their default rendering in the quick|-|start example on \at +{page} [ch:quick]. We purposely limited this \TEXcode {default} specification as +a minimal example for a bibliography. + +The notion of categories and the fields that they might contain and their +interpretation depend on a particular specification, although the dataset +\emphasis {content} is independent of all eventual rendering specifications that +may be applied. + +An alternative set of specifications can be selected using, for example + +\startbuffer +\usebtxdefinitions[apa] +\stopbuffer + +\cindex {usebtxdefinitions} +\index {style+APA} +\seeindex {specification}{style} + +\typeTEXbuffer + +\getbuffer + +Alternately, the set of specifications can be loaded and (later) activated using + +\cindex {loadbtxdefinitionfile} +\cindex {setupbtx} +\index {style+APA} + +\startTEX +\loadbtxdefinitionfile[apa] +... +\setupbtx[specification=apa] +\stopTEX + +but it is safer to use the \TEXcode {\use} rather than \TEXcode {\load} form, in +particular with specifications that may themselves have several variants. Also, +it is way too easy to later forget to set the \TEXcode {specification} parameter +and then wonder why the loaded specification was not applied. + +\startaside +We wish to clarify that each specification defines the categories of entries and +the interpretation or use of the fields that they contain, but does not alter the +data itself, only how this data is used. It also defines \emphasis {setups} that +control the rendering of lists as well as citations (to be described below). +Additionally, it creates a namespace with settings for particular \emphasis +{parameters} controlling the formatting of names, for example, punctuation as +well as other stylistic features. The user can tune or overload these settings as +needed. +\stopaside + +A specification need not be activated before loading a dataset; indeed the +contents of a dataset are stored independent of the specification, and multiple +specifications can be applied to the same dataset (although this will not usually +be the case). Furthermore, multiple specification files can be loaded +simultaneously as they reside in separate namespaces, but only one specification +can be selected at a time. We introduce these commands here in the context of +datasets as the labeling of categories and of field use can change depending on +the specification. Indeed, some specifications might ignore certain fields +present in the dataset that may be used with other specifications. The details of +how this is programmed will be explained in \in {Chapter} [ch:custom]. + +So a specification is both a definition of how a dataset is to be interpreted as +well as stylistic tuning of how it is to be rendered. + +\cindex {loadbtxdefinitionfile} +\showsetup[loadbtxdefinitionfile] + +\cindex {usebtxdefinitions} +\showsetup[usebtxdefinitions] + +\stopsection + +\startsection [title=Dataset diagnostics] + +You can ask for an overview of entries present in a dataset with: + +\startbuffer +\showbtxdatasetfields[example] +\stopbuffer + +\cindex {showbtxdatasetfields} + +\typeTEXbuffer + +The listing that this produces is shown in \in {Appendix} [ch:datasetfields]. + +\cindex {showbtxdatasetfields} +\showsetup[showbtxdatasetfields] +\showsetup[showbtxdatasetfields:argument] + +Sometimes you might want to check a database, listing all of its entries in +detail. This can be particularly useful when in doubt concerning the correctness +or the completeness of the data source, remembering that invalid entries and some +syntax errors are simply skipped over. One way of examining the loaded dataset in +detail is the following: + +\startbuffer +\showbtxdatasetcompleteness[example] +\stopbuffer + +\cindex {showbtxdatasetcompleteness} + +\typeTEXbuffer + +The diagnostic listing (which can be rather long) is shown in \in {Appendix} +[ch:datasetcompleteness]. + +\cindex {showbtxdatasetcompleteness} +\showsetup[showbtxdatasetcompleteness] +\showsetup[showbtxdatasetcompleteness:argument] + +The dataset contains many entries and each entry is assigned to a \Index +{category}. It must be stressed, so we repeat ourselves here, that these \quote +{categories} can be of any sort whatsoever, the meaning of which resides in the +rendering style that is chosen. The entries contain fields, and these too can be +of any sort; their use also depends on the rendering style and the \Index +{category} in which they belong. \BibTeX\ has conventionally defined a number of +standard categories, each making use of a number of fields considered either +\index {field+required}required, \index {field+optional}optional or \index +{field+ignored}ignored. However, different traditional \BIBTEX\ rendering styles +can make inconsistant use of these standard categories and fields. To make +matters worse, different \Tindex {.bib} database handling programs might use (and +impose) differing \quote {standards} as well, as mentioned above. \startfootnote +For example, \Tindex {jabref}, in addition to discarding all comments contained +in the database file, will convert all unrecognized, preciously named categories +to \tindex {@other}\BTXcode {@Other}! Of course, \Tindex {jabref} is flexible +enough to be configured with new categories and additional fields, so users of +\Tindex {jabref} with \CONTEXT\ will probably want to use an extended, custom +configuration. \stopfootnote This situation arises from the complexity of +handling bibliographic data of all sorts. + +You can see all (currently known) \index {category}categories and \index +{field}fields with: + +\cindex {showbtxfields} + +\startTEX +\showbtxfields[rotation=...] +\stopTEX + +The result is shown \in {table} [tab:fields], below. + +\cindex {showbtxfields} +\showsetup[showbtxfields] +\showsetup[showbtxfields:argument] + +Note that other, possibly non|-|bibliographic use of the present dataset system +might define entirely different categories and field types, possibly having +nothing at all to do with the names shown here. An example of such use is given +in \in {chapter} [ch:duane]. + +Just as a database can be much larger than needed for a document, the same is +true for the fields that make up an entry; not all entry fields will be +necessarily used. This idea will be developed in the next section describing the +rendering of bibliography lists. + +\stopsection + +\startplacetable + [reference=tab:mkiv-publications.bib, + title={mkiv-publications.bib\\ + This test file was constructed to illustrate various features of the + \BIBTEX\ format and contains some fields that might at first glance + appear somewhat curious.}]. + \typeBTXfile + [range={@Comment{Start example},@Comment{Stop example}}] + {mkiv-publications.bib} +\stopplacetable + +\startplacetable + [reference=tab:fields, + list={\TEXcode {\showbtxfields[rotation=90]}}, + title={\cindex {showbtxfields}\TEXcode {\showbtxfields[rotation=90]} The entry + \Index {category} and \Index {field} names (and how they are used) are + defined by both the rendering style as well as by the contents of the + dataset. \index {field+required}\quote {Required} fields are indicated + in green. All unmarked fields are normally \index + {field+ignored}ignored in the rendering.}] + \small + \showbtxfields[rotation=90] +\stopplacetable + +\placefloats + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/publications/publications-exporting.tex b/doc/context/sources/general/manuals/publications/publications-exporting.tex new file mode 100644 index 000000000..b459ce118 --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-exporting.tex @@ -0,0 +1,33 @@ +\environment publications-style + +\startcomponent publications-exporting + +\startchapter[title=Exporting datasets] + +A dataset can be much more complete than necessary. Furthermore, it may be +desirable to isolate bibliography data by chapter, for example, or by any other +structural element such as part. To achieve this, it is possible to export the +entries of a dataset following certain criteria. + +\cindex{savebtxdataset} + +Take as an example, the bibliography of the present manual that was entered in +the source as buffers for convenience. The entries can be saved to a legitimate +\BIBTEX\ format file using: + +\startTEX +\savebtxdataset + [default] + [mkvi-publications.bib] + [alternative=bib, + criterium=all] +\stopTEX + +This can also be used to convert older bibliography source files (for example, +kept in the \tindex {.bbl}\MKII\ format) into the \tindex {.bib}\type {bib}, +\tindex {.lua}\type {lua} or even \tindex {.xml}\type {xml} format that could be +more convenient for future manipulation. + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/publications/publications-extensions.tex b/doc/context/sources/general/manuals/publications/publications-extensions.tex new file mode 100644 index 000000000..262d5eb3c --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-extensions.tex @@ -0,0 +1,119 @@ +\environment publications-style + +\startcomponent publications-extensions + +\startchapter[title=Extensions] + +As \TEX\ and \LUA\ are both open and accessible in \CONTEXT\ it is possible to +extend the functionality of the bibliography related code. For instance, you +could add extra loaders, sketched as follows: + +\startTEX +\startluacode +function publications.loaders.myformat(dataset,filename) + local t = { } + -- Load data from 'filename' and convert it to a Lua table 't' with + -- the key as hash entry and fields conforming the luadata table + -- format. + loaders.lua(dataset,t) +end +\stopluacode +\stopTEX + +This would then permit the loading a database (into a dataset) with the command: + +\cindex{usebtxdataset} + +\startTEX +\usebtxdataset[default][myfile.myformat] +\stopTEX + +The \type {myformat} suffix is recognized automatically. If you want to use another +suffix, you can do this: + +\cindex{usebtxdataset} + +\startTEX +\usebtxdataset[default][myformat::myfile.txt] +\stopTEX + +%% NO SETUP BTX:APA:LEFTTEXT SO THE FOLLOWING DOES NOT WORK: +%% +%% If you want to add information to an entry at runtime you can pass so called user +%% variables with the \type {\cite} command. The following example demonstrates +%% this. First we define a dataset: +%% +%% \startbuffer +%% \startbuffer [knuth] +%% @Book{knuth-texbook, +%% title = {The TeXbook}, +%% author = {Knuth, Donald Ervin}, +%% isbn = {0-201-13447-0}, +%% series = {Computers {\&} Typesetting}, +%% volume = {A}, +%% year = {1986}, +%% publisher = {Addison Wesley}, +%% address = {Reading, MA}, +%% } +%% \stopbuffer +%% +%% \definebtxdataset[knuth] +%% \usebtxdataset [knuth] [knuth.buffer] +%% \definebtxrendering[knuth][dataset=knuth] +%% \stopbuffer +%% +%% \typeTEXbuffer +%% \getbuffer +%% +%% \startbuffer[setup] +%% \startsetups btx:apa:lefttext +%% \currentbtxlefttext +%% \btxspace +%% \btxdoifelseuservariable {notabene} { +%% {\bs \currentbtxuservariable{notabene}} +%% } { +%% % nothing +%% } +%% \btxspace +%% \stopsetups +%% \stopbuffer +%% +%% \getbuffer[setup] +%% +%% \startbuffer +%% We all know the \TeX book by Don Knuth \citation [reference=knuth::knuth-texbook, +%% lefttext={\bf >}] [notabene=Well known to \TEX\ users:]. +%% \stopbuffer +%% +%% We use this example where we use \type {\citation} instead of \type {\cite} because +%% it is more tolerant with spaces. Because we pass user variables as second argument +%% the first argument also has to be a key|/|value set. +%% +%% \typeTEXbuffer +%% +%% \getbuffer +%% +%% The list is typeset using: +%% +%% \startbuffer +%% \placelistofpublications [knuth] [criterium=all] +%% \stopbuffer +%% +%% \typeTEXbuffer +%% +%% and looks like this: +%% +%% \getbuffer +%% +%% The injection of the user variables is up to you. Here we hooked it into an +%% existing setup that we overload: +%% +%% \typeTEXbuffer [setup] +%% +%% The \type {lefttext} and \type {righttext} variables are also kept with the +%% entry but these are checked for automatically. In this case it means that +%% when no \type {lefttext} is specified, the \type {notabene} doesn't show up. + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/publications/publications-fields.tex b/doc/context/sources/general/manuals/publications/publications-fields.tex new file mode 100644 index 000000000..adbdb373b --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-fields.tex @@ -0,0 +1,38 @@ +\environment publications-style + +\startcomponent publications-fields + +\startchapter + [title={Dataset fields}, + reference=ch:datasetfields] + +\setupbtx + [specification=apa] + +\usebtxdataset + [example] + [mkiv-publications.bib] + +\startbuffer +\showbtxdatasetfields[example] +\stopbuffer + +\typeTEXbuffer + +\cindex {showbtxdatasetfields}The field names for each entry \Index {category} +are colored according to their status with respect to the bibliography rendering +style. The \index {field+required}\quote {required} field names are colored in +green, where required means that if this field is missing, one is probably not +using the correct entry type or category. Some fields are \index +{field+optional}\quote {optional} (and some \index {field+required}\quote +{required} fields can become conditionally optional, see below). Fields that +normally would be \index {field+ignored}ignored (defined as neither required, nor +optional) are colored in dark yellow. Some fields are treated as \index +{field+special}\quote {special}, that is are used internally, not necessarily +directly rendered, and are colored here in blue. + +\getbuffer + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/publications/publications-introduction.tex b/doc/context/sources/general/manuals/publications/publications-introduction.tex new file mode 100644 index 000000000..53abf5d83 --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-introduction.tex @@ -0,0 +1,109 @@ +\environment publications-style + +\startcomponent publications-introduction + +\startchapter[title=Introduction] + +\startsubject[title=How Hans got involved] + +This manual is dedicated to Taco \Name{Hoekwater}{T.} who in a previous century +implemented the first \BIBTEX\ module and saw it morph into a \TEX||\LUA\ hybrid +in this century. The fact that there was support for bibliographies made it +possible for users to use \CONTEXT\ in an academic environment, dominated by +bibliographic databases encoded in the \BIBTEX\ format. + +This manual describes how \MKIV\ now handles bibliographies. Support in \CONTEXT\ +started in \MKII\ for \BIBTEX, as mentioned above, using a module written by Taco +\Name {Hoekwater} {T.}. Later his code was adapted to \MKIV, but because users +demanded more, I decided that reimplementing made more sense than patching. In +particular, through the use of \LUA, the \BIBTEX\ data files can be easily +directly parsed, thus liberating \CONTEXT\ from the dependency on an external +\BIBTEX\ executable. The \Index{CritEd project} (by Thomas \Name {Schmitz} {T.}, +Alan \Name {Braslau} {A.}, Luigi \Name {Scarso} {L.} and \name {Hagen} +{H.}myself) was a good reason to undertake this rewrite. As part that project +users were invited to come up with ideas about extensions. Not all of them are +(yet) honored, but the rewrite makes more functionality possible. + +The subsystem described here is one of the most complex and messy of all +\CONTEXT\ subsystems. This has to do with the fact that it combines (multiple) +lists and (multiple) forward and backward references, all kind of rendering of +the citation as well as the entry in the list, rather complex interactivity, +multiple databases, datasets and renderings and of course combinations of this. +The implementation uses a mix of \TEX\ and \LUA\ code with so called setups as +rendering specifications. At the cost of complexity (and some runtime penalty) +this provides a lot of freedom and flexibility. + +% \startlines +% Hans \Name {Hagen} {H.} +% PRAGMA ADE +% Hasselt NL +% \stoplines + +\stopsubject + +\startsubject[title=How Alan got involved] + +Bibliographies and citations are of utmost importance in any scholarly work. +Nevertheless, the production of bibliography lists and the insertion of +citations, just like the production of an index, is a task that is often +postponed to a later stage in the writing of an article, a book, or a manual. +Perhaps this is because it can be more important to create than to refer, but +maybe the necessary tools are found to be insufficient or unnatural. + +A computerized typesetting system should help an author produce a text, not +impose any preset format or unnecessary constraint. In a referenced work, a +bibliography system should be flexible enough to adapt to very different styles +and practices. Creating such a system is quite a challenge. + +\CONTEXT\ \MKII\ implemented a system that was based on a use of \BIBTEX, an +external program that built upon basic bibliographic macros introduced in \LATEX. +\CONTEXT\ \MKIV\ moved away from this dependency, opening up many possibilities +for new functionality and, we hoped, providing more natural and flexible tools +for authors. For my own use, the most important of which is a very powerful +search and match mechanism that has been made possible though the use of \LUA. + +I had started by asking simple questions on details of the workings of this new +system and making \quotation{wouldn't it be nice to} requests for functionality +that I knew was somehow buried in the inner workings of \CONTEXT. As a result of +these inquiries, I got drawn into the project to make this new system a reality. + +% \startlines +% Alan \Name{Braslau}{A.} +% Paris, France +% \stoplines + +\stopsubject + +\startsubject[title=How you can be involved] + +Bibliography management is indeed one of the most complex subsystems in \CONTEXT, +and many, many design decisions had to be made during its development. +Experimental features were added, some of which were later abandoned as being +inappropriate or else superseded by some better mechanism. The effort (and time) +that we spent in reimplementing the treatment of bibliographies was much greater +than any of us had anticipated when we undertook this project. Hopefully, now the +system is stable enough to be more widely used and this manual is an attempt to +make it accessible to all users. + +There are \CONTEXT\ users who will just use whatever the bibliograpy modules +provide by default. For many, the \APA\ style is good enough; others may have +specific needs. This manual should provide insight on how to adapt the system to +new styles. But sometimes users will ask questions on the mailing list that are +not answered here. Feel free to come up with additional examples that can be +added to the test suite, or when we consider them to be of general use, to this +manual. + +\stopsubject + +\startsubject[title=Hyperlinks] + +Please note \startfootnote Footnotes are placed at the end of each chapter. +\stopfootnote that this document contains hyperlinks that are not highlighted for +aesthetic reasons. In addition to standard interaction (table of contents, index, +and cross|-|references, some external web sources are selectable. + +\stopsubject + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/publications/publications-journals.tex b/doc/context/sources/general/manuals/publications/publications-journals.tex new file mode 100644 index 000000000..0dd8a872f --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-journals.tex @@ -0,0 +1,88 @@ +% \endinput + +\environment publications-style + +\startcomponent publications-journals + +\startchapter[title=Journals] + +An experimental feature is the ability to load a list of mapping from complete +journal names to abbreviated forms. + +\startbuffer +\btxloadjournallist[journals.txt] % the jabref list + +\btxexpandedjournal {Z. Ökol. Nat.schutz} or +\btxabbreviatedjournal{Z. Ökol. Nat.schutz} or +\btxabbreviatedjournal{Z. Ökol. Nat. schutz} +\stopbuffer + +\typeTEXbuffer \getbuffer + +In this case the text file looks like: + +\starttyping +Zeitschrift für Ökologie und Naturschutz = Z. Ökol. Nat..schutz +.... +\stoptyping + +Instead you can have a \LUA\ file that looks like: + +\startLUA +return { + ["Zeitschrift für Ökologie und Naturschutz"] = "Z. Ökol. Nat.schutz", + ... +} +\stopLUA + +or + +\startLUA +return { + { "Zeitschrift für Ökologie und Naturschutz", "Z. Ökol. Nat.schutz" }, + ... +} +\stopLUA + +A file can be saved with: + +\startTEX +\btxsavejournallist[journals.lua] +\stopTEX + +and then loaded again in a second run. For small lists it makes not much sense +to cache the lists but if you have tens thousands of journals it can be +considered. Normally loading is can be neglected compared to the run. Anyhow, +such a list looks like this: + +\startLUA +return { + ["abbreviations"]={ + ["zeitschriftfürökologieundnaturschutz"] = "Z. Ökol. Nat.schutz", + }, + ["expansions"]={ + ["zökolnatschutz"] = "Zeitschrift für Ökologie und Naturschutz", + }, +} +\stopLUA + +In the future \type {mtx-bibtex} might be able to generate such lists (once we know +what users come up with). + +You can add additional entries with: + +\startTEX +\btxaddjournal + [Zeitschrift für Ökologie und Naturschutz] + [Z. Ökol. Nat.schutz] +\stopTEX + +As usual with such mechanisms, internally spaces, punctuation and case are +ignored with a lookup. + +There are also two manipulators for journals: \type {expandedjournal} and +\type {abbreviatedjournal}. + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/publications/publications-lua.tex b/doc/context/sources/general/manuals/publications/publications-lua.tex new file mode 100644 index 000000000..3a148dca4 --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-lua.tex @@ -0,0 +1,224 @@ +\environment publications-style + +\startcomponent publications-lua + +\startchapter[title=The \LUA\ view] + +The following is reserved for \LUA\ programmers. + +Because we manage data at the \LUA\ end it is tempting to access it there for +other purposes. This is fine as long as you keep in mind that aspects of the +implementation may change over time, although this is unlikely once the modules +become stable. + +The entries are collected in datasets and each set has a unique name. In this +document we have the set named \type {example}. A dataset table has several +fields, and probably the one of most interest is the \type {luadata} field. Each +entry in this table describes a publication. Take, for example \type +{publications.datasets.example.luadata["article"]}: + +\startluacode + context.tocontext(publications.datasets.example.luadata["article"]) +\stopluacode + +There is a companion entry in the parallel \type {details} table,\\ +\type {publications.datasets.example.details["article"]}: + +\startluacode + context.tocontext(publications.datasets.example.details["article"]) +\stopluacode + +tracking further information derived from the publication entry and its use. + +You can loop over the entries using regular \LUA\ code combined with \MKIV\ +helpers: + +\startbuffer +local dataset = publications.datasets.example + +context.starttabulate { "|l|l|l|" } +context.NC() context("tag") +context.NC() context("short") +context.NC() context("title") +context.NC() context.NR() +context.HL() +for tag, entry in table.sortedhash(dataset.luadata) do + local detail = dataset.details[tag] or { } + context.NC() context.type(tag) + context.NC() context(detail.shorthash) + context.NC() context(entry.title) + context.NC() context.NR() +end +context.stoptabulate() +\stopbuffer + +\typeLUAbuffer + +This results in: + +\ctxluabuffer + +Notice that the years in this example dataset given as \type {YYYY} are +interpreted as if they were \index {9999}\type {9999}. + +You can manipulate a dataset after loading. Of course this assumes that you know +what kind of content you have and what you need for rendering. As example we load +a small dataset. + +\startbuffer +\definebtxdataset[drumming] +\usebtxdataset[drumming][mkiv-publications.lua] +\stopbuffer + +\cindex{definebtxdataset} +\cindex{usebtxdataset} + +\typeTEXbuffer + +\getbuffer + +Because we're going to do some \LUA, we could have loaded this dataset using: + +\startTEX +\startluacode +publications.load("drumming","mkiv-publications.lua","lua") +\stopluacode +\stopTEX + +The dataset has three entries:% +\startfootnote +Gavin Harrison is in my (Hans) opinion one of the most creative, diverse and +interesting drummers of our time. It's also fascinating to watch him play and a +welcome distraction from writing code and manuals. +\stopfootnote + +\typeLUAfile{mkiv-publications.lua} + +As you can see, we can have a subtitle. As an exercise, we will combine the +title and subtitle into one: + +\startbuffer +\startluacode +local luadata = publications.datasets.drumming.luadata + +for tag, entry in next, luadata do + if entry.subtitle then + if entry.title then + entry.title = entry.title .. ", " .. entry.subtitle + else + entry.title = entry.subtitle + end + entry.subtitle = nil + logs.report("btx", + "combining title and subtitle of entry tagged %a into %a", + tag,entry.title) + end +end +\stopluacode +\stopbuffer + +\typeTEXbuffer \getbuffer + +As a hash comes in a different order each run (something that demands a lot of +care in multi|-|pass workflows that save data in between), so it is probably +better to use this instead: + +\startTEX +\startluacode +local ordered = publications.datasets.drumming.ordered + +for i=1,#ordered do + local entry = ordered[i] + if entry.subtitle then + if entry.title then + entry.title = entry.title .. ", " .. entry.subtitle + else + entry.title = entry.subtitle + end + entry.subtitle = nil + logs.report("btx", + "combining title and subtitle of entry tagged %a into %a", + entry.tag,entry.title) + end +end +\stopluacode +\stopTEX + +This loops processes in the order of definition. Alternately, one can sort by +\Index{tag}: + +\startTEX +\startluacode +local luadata = publications.datasets.drumming.luadata + +for tag, entry in table.sortedhash(luadata) do + if entry.subtitle then + if entry.title then + entry.title = entry.title .. ", " .. entry.subtitle + else + entry.title = entry.subtitle + end + entry.subtitle = nil + logs.report("btx", + "combining title and subtitle of entry tagged %a into %a", + entry.tag,entry.title) + end +end +\stopluacode +\stopTEX + +The original data is stored in a \LUA\ table, hashed by tag. Starting with \LUA\ 5.2 +each run of \LUA\ gets a different ordering of such a hash. In older versions, when you +looped over a hash, the order was undefined, but the same as long as you used the same +binary. This had the advantage that successive runs, something we often have in document +processing gave consistent results. In today's \LUA\ we need to do much more sorting of +hashes before we loop, especially when we save multi||pass data. It is for this reason +that the \XML\ tree is sorted by hash key by default. That way lookups (especially +the first of a set) give consistent outcomes. + +We can now simply typeset the entries with: + +\cindex{definebtxrendering} +\cindex{placebtxrendering} + +\startbuffer +\definebtxrendering[drumming][group=examples,dataset=drumming] +\placebtxrendering[drumming][method=dataset] +\stopbuffer + +\typeTEXbuffer \getbuffer + +Because we just want to show the entries, and have no citations that force them +to be shown, we have to set the \type {method} to \type {dataset}. + +Of course, none of these manipulations in \LUA\ are really necessary, as the +rendering could be setup as: + +\cindex {btxfetch} +\cindex {btxdoif} +\cindex {btxcomma} +\cindex {starttexdefinition} +\cindex {stoptexdefinition} + +\startTEX +\starttexdefinition btx:default:title + \btxfetch{author} + \btxdoif{subtitle} { + \btxcomma + \btxfetch{subtitle} + } +\stoptexdefinition +\stopTEX + +which is indeed the case in many of the styles (the \type {default} style uses +\Cindex {btxcolon}). \startfootnote The specifications could be modified to use a +parameter \type {inbetween={, }} for titles:subtitles that the user can easily +setup as needed. But as such style questions are, in general, well defined in the +specifications, this was not deemed necessary. \stopfootnote + +It is always a question of how much should be done in \LUA\ and how much should +be done in \TEX. In the end, it is often a question of taste. + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/publications/publications-otheruse.tex b/doc/context/sources/general/manuals/publications/publications-otheruse.tex new file mode 100644 index 000000000..43b21d9a5 --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-otheruse.tex @@ -0,0 +1,328 @@ +\environment publications-style + +\startcomponent publications-otheruse + +\startchapter + [reference=ch:duane, + title=Other use of datasets] + +Because a bibliography is just a kind of database, you can use the publications +mechanism for other purposes as well. + +\startsection + [title=Images] + +During the re|-|implementation \name {Miklavec}{M.}Mojca came up with the +following definitions: + +\startbuffer +\startbuffer[duane] +@IMAGE {tug2013, + title = "TUG 2013", + url = "http://tug.org/tug2013/", + url_image = "http://tug.org/tug2013/tug2013-color-300.jpg", + url_thumb = "http://tug.org/tug2013/t2013-thumb.jpg", + description = "Official drawing of the TUG 2013 conference", + author = "Duane Bibby", + year = 2013, + copyright = "TUG", +} + +@IMAGE {tug2014, + title = "TUG 2014", + url = "http://tug.org/tug2014/", + url_image = "http://tug.org/art/tug2014-color.jpg", + url_thumb = "http://tug.org/tug2014/t2014-thumb.jpg", + description = "Official drawing of the TUG 2014 conference", + author = "Duane Bibby", + year = 2014, + copyright = "TUG", +} +\stopbuffer +\stopbuffer + +\typeBTXbuffer \name{Bibby}{D.}\getbuffer + +For documentation purposes we can have a definition in a buffer so that we can +show it verbatim but also load it. The following code defines a dataset, loads +the buffer and sets up a rendering. + +\startbuffer +\definebtxdataset + [duane] + +\usebtxdataset + [duane] + [duane.buffer] + +\definebtx + [duane] + [default=, + specification=duane, + authorconversion=normal] + +\definebtx + [duane:list] + [duane] + +\definebtx + [duane:list:author] + [duane:list] + +\definebtx + [duane:list:image] + [duane:list] + +\definebtxrendering + [duane] + [specification=duane, + group=duane, % so not: group=default, + dataset=duane, + method=dataset, + numbering=no, + criterium=all] + +\stopbuffer + +\cindex{definebtxdataset} +\cindex{usebtxdataset} +\cindex{definebtx} +\cindex{definebtxrendering} + +\typeTEXbuffer \getbuffer + +Instead of for instance \TEXcode {apa} we create a specification named \TEXcode +{duane}. Because categories are rendered with a setup, we can define the +following: + +\startbuffer +\startsetups btx:duane:list:image + \tbox \bgroup + \bTABLE[offset=1ex] + \bTR + \bTD[ny=4] + \dontleavehmode + \externalfigure[\btxflush{url_thumb}][width=3cm] + \eTD + \bTD \btxflush{title} \eTD + \eTR + \bTR + \bTD \btxflush{author} \eTD + \eTR + \bTR + \bTD \btxflush{description} \eTD + \eTR + \bTR + \bTD + \goto{high res variant}[url(\btxflush{url_image})] + \eTD + \eTR + \eTABLE + \egroup +\stopsetups + +\placebtxrendering[duane][criterium=all] +\stopbuffer + +\cindex{startsetups} +\cindex{stopsetups} +\cindex{placebtxrendering} +\cindex{btxflush} + +\typeTEXbuffer \getbuffer + +An alternative rendering is: + +\startbuffer +\startsetups btx:duane:list:image + \bgroup + \bTABLE[offset=1ex] + \bTR + \bTD + \dontleavehmode + \goto{\externalfigure[\btxflush{url_thumb}][width=3cm]} + [url(\btxflush{url_image})] + \eTD + \bTD + \bold{\btxflush{title}} + \blank + \btxflush{description} + \blank [3*line] + \btxflush{author} + \eTD + \eTR + \eTABLE + \egroup +\stopsetups + +\placebtxrendering[duane] +\stopbuffer + +\cindex{startsetups} +\cindex{stopsetups} +\cindex{placebtxrendering} +\cindex{btxflush} + +\typeTEXbuffer \getbuffer + +We only get the second rendering because we specified \TEXcode {criterium} as +\TEXcode {all}. Future version of \CONTEXT\ will probably provide \Index{sorting} +options and ways to plug in additional functionality. + +\stopsection + +\startsection + [title=Chemistry] + +To give further ideas on how the \quote {publications} database system can be +effectively used in a document, consider any object such as an image (as seen +above), an equation, a chemical compound, or other entity having various +properties and that might be used repeatedly. Here we will give an almost +realistic example of a dataset containing various chemical compounds. + +Like above, we shall define a named dataset and load it with definitions having +nothing to do with publications, rather a number of chemical compounds of +formula \chemical {C_6H_6O} (there are some 57 such molecules). + +\startbuffer +\definebtxdataset + [chemistry] + +\usebtxdataset + [chemistry] + [C6H6O.bib] +\stopbuffer + +\cindex{definebtxdataset} +\cindex{usebtxdataset} +\typebuffer [option=TEX] +\getbuffer + +We can visualize the contents of the dataset using, for example: + +\startbuffer +\showbtxdatasetcompleteness + [dataset=chemistry, + specification=chemistry] +\stopbuffer + +\cindex{showbtxdatasetcompleteness} +\typebuffer [option=TEX] + +Note that the specification \quote {chemistry} is undefined (as yet) so the log file shows: + +\starttyping +publications > no data definition file 'publ-imp-chemistry.lua' for 'chemistry' +\stoptyping + +This is harmless as a missing (lua) definition file makes \emphasis {all} data categories and fields +\quote {optional}, allowing their access and use. + +The dataset (containing just 4 of the 57 entries) is: + +\startparagraph [style=small] +\getbuffer +\stopparagraph + +The next step is to activate the specification and dataset and to define a list rendering, as +follows: + +\startbuffer +\setupbtx + [specification=chemistry, + dataset=chemistry] + +\definebtxrendering + [chemistry] + [specification=chemistry, + group=chemistry, + dataset=chemistry] +\stopbuffer + +\cindex{setupbtx} +\cindex{definebtxrendering} +\typebuffer [option=TEX] +\getbuffer + +This list rendering can then be placed, but first one needs to create a setup +describing how to handle the entry (or category) \type {@chemical{}} contained +in the file \type {C6H6O.bib}. As in the earlier example, we shall use a table +structure for the list text: + +\startbuffer +\startsetups btx:chemistry:list:chemical + \startframed [frame=off,location=middle] + \bTABLE [frame=off] + \bTR + \bTD [width=.2\textwidth,ny=2] + \goto + {\startchemical [scale=small] + \chemical [\btxflush{chemical}] + \stopchemical} [program(\btxflush{rendered})] + \eTD + \bTD [width=.2\textwidth] \chemical{\btxflush{formula}} \eTD + \bTD [width=.4\textwidth] \btxflush{iupac} \eTD + \eTR + \bTR + \bTD \btxflush{mw}~g/mole \eTD + \bTD \btxflush{cas} \eTD + \eTR + \eTABLE + \stopframed +\stopsetups + +\placebtxrendering [method=dataset] +\stopbuffer + +\cindex{startsetups} +\cindex{stopsetups} +\typebuffer [option=TEX] + +Note that not all fields of the dataset are used. + +\getbuffer + +The real usefulness of the dataset is the possibility of referring to entries +and the ability to extract data fields. Setups can be defined for those fields +requiring any formatting beyond a simple flushing, for example those requiring +the \Cindex {chemical} command. + +\startbuffer +\startsetups btx:chemistry:cite:formula + \chemical {\currentbtxfirst} +\stopsetups + +\startsetups btx:chemistry:cite:chemical + \startchemical [scale=600] + \chemical [\currentbtxfirst] + \stopchemical +\stopsetups + +\cite [name] [108-95-2] |<|or|>| +\cite [formula] [108-95-2] |<|or|>| +\cite [chemical] [108-95-2] |<|or|>| +\cite [molarvolume] [108-95-2] +\stopbuffer + +\cindex{startsetups} +\cindex{stopsetups} +\cindex{cite} +\typebuffer [option=TEX] +\getbuffer + +\startbuffer +\cite [name] [566-33-5] |<|or|>| +\cite [formula] [566-33-5] |<|or|>| +\cite [chemical] [566-33-5] |<|or|>| +\cite [molarvolume] [566-33-5] +\stopbuffer + +\cindex{cite} +\typebuffer [option=TEX] +\getbuffer + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/publications/publications-overviews.tex b/doc/context/sources/general/manuals/publications/publications-overviews.tex new file mode 100644 index 000000000..27ec420db --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-overviews.tex @@ -0,0 +1,42 @@ +\environment publications-style + +\startcomponent publications-overviews + +\startchapter[title=Bibliography,reference=ch:biblio] + +\setupbtx + [interaction=all] + +\setupbtxrendering + [default] + [pagestate=start, + before=, + after=] + +\placelistofpublications + +\stopchapter + +\startchapter[reference=ch:listoftables,title=List of tables] + \placelistoftables [criterium=all] +\stopchapter + +\startchapter[reference=ch:indexofauthors,title=Index of names] + \placeregister[indexofauthors] [criterium=all,compress=yes] +\stopchapter + +\startchapter[reference=ch:index,title=Index of subjects] + \placeindex [criterium=all,compress=yes] +\stopchapter + +\startchapter[title=Hashed authors] + +\start + \small + \small + \showbtxhashedauthors +\stop + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/publications/publications-performance.tex b/doc/context/sources/general/manuals/publications/publications-performance.tex new file mode 100644 index 000000000..ec358dfc9 --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-performance.tex @@ -0,0 +1,46 @@ +\environment publications-style + +\startcomponent publications-performance + +\startchapter[title=Performance] + +The move from external \BIBTEX\ processing to internal processing has the +advantage that we stay within the same run. In the traditional approach we had +roughly the following steps: + +\startitemize[packed] +\startitem + In the first \CONTEXT\ run information is collected and written to file. +\stopitem +\startitem + fter the first run the \BIBTEX\ program converts that file to another + one, a so called \type {bbl} file with \TEX\ commands. +\stopitem +\startitem + Successive runs use that file for typesetting references and producing + lists of publications that are reffered to. +\stopitem +\stopitemize + +In the \MKIV\ approach the bibliographic database is loaded in memory each run +and processing also happens each run. On paper this looks less efficient but as +\LUA\ is quite fast, in practice performance is much better. + +Probably most demanding is the treatment of authors as we have to analyze names, +split multiple authors and reassemble firstnames, vons, surnames and juniors. +When we sort by author sorting vectors have to be made which also has a penalty. +However, in practice the user will not notice a performance degradation. We did +some tests with a list of 500.000 authors, sorted them and typeset them as list +(producing some 5400 dense pages in a small font and with small margins). This is +typical one of these cases where using \LUAJITTEX\ saves quite time. On my +machine it took just over 100 seconds to get this done. Unfortunately not all +operating systems performed equally well: 32 bit versions worked fine, but 64 bit +\LINUX\ either crashed (stalled) the machine or ran out of memory rather fast, +while \MACOSX\ and \WINDOWS\ performed fine. In practice you will never run into +this, unless you produce massive amounts of bibliographic entries. \LUAJIT\ has +some benefits but also some drawbacks. In practice you will not run into these +problems. + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/publications/publications-quick-example.tex b/doc/context/sources/general/manuals/publications/publications-quick-example.tex new file mode 100644 index 000000000..14f70960f --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-quick-example.tex @@ -0,0 +1,16 @@ +\usebtxdataset[mkiv-publications.bib] + +\starttext + +\startbodymatter +a citation: \cite[article,book] +\stopbodymatter + +\startbackmatter + \startchapter[title=Bibliography] + \placelistofpublications + \stopchapter +\stopbackmatter + +\stoptext + diff --git a/doc/context/sources/general/manuals/publications/publications-quick.tex b/doc/context/sources/general/manuals/publications/publications-quick.tex new file mode 100644 index 000000000..930203a38 --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-quick.tex @@ -0,0 +1,44 @@ +\environment publications-style + +\startcomponent publications-quick + +\startchapter + [reference=ch:quick, + list={Quick start}, + title={\Index{Quick start}, for the impatient}] + +\cindex{usebtxdataset} +\cindex{cite} +\cindex{placelistofpublications} + +Without \emphasis {any} explanation: + +\typeTEXfile + {publications-quick-example.tex} + +\startcombination[c=2,r=1,distance=\emwidth] + \startcontent + \typesetfile + [publications-quick-example.tex] + [width=.5\dimexpr\textwidth-\emwidth\relax,frame=on,page=1] + \stopcontent + \startcaption + bodymatter + \stopcaption + \startcontent + \typesetfile + [publications-quick-example.tex] + [width=.5\dimexpr\textwidth-\emwidth\relax,frame=on,page=2] + \stopcontent + \startcaption + backmatter + \stopcaption +\stopcombination + +This example demonstrates that the basic usage in the production of bibliography +citations and lists is rather simple. However, once the user starts asking for +particular customizations, then things can get quite complicated rather quickly. + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/publications/publications-rendering.tex b/doc/context/sources/general/manuals/publications/publications-rendering.tex new file mode 100644 index 000000000..caa1f61d7 --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-rendering.tex @@ -0,0 +1,541 @@ +\environment publications-style + +\startcomponent publications-rendering + +\startchapter[title=Renderings,reference=ch:renderings] + +\startsection + [reference=sec:styles, + title={Generating lists of publications}] + +A list of publications can be rendered at any place in the document, and multiple +renderings can appear under certain limitations (according to \Index {scope}). +The specification introduced previously defines the style of the rendering as +well as what data it will contain. + +If you want to see what publications are in the database, the easiest way is to +ask for a complete list: + +\startbuffer +\usebtxdataset % illustrated again here + [example] % although already loaded + [mkiv-publications.bib] % in the previous chapter + +\definebtxrendering + [example] % named rendering + [apa] % parent namespace + [dataset=example, + group=examples] % group will be presented later + +\placelistofpublications % aka \placebtxrendering + [example] % rendering defined above + [method=dataset] % i.e. all entries +\stopbuffer + +\cindex{definebtxrendering} +\cindex{placelistofpublications} +\cindex{placebtxrendering} + +\typeTEXbuffer + +The commands \Cindex {placelistofpublications} (that is just a synonym for +\Cindex {placebtxrendering}) refer to a named rendering and accept a list of +options (inherited from \Cindex {setupbtxrendering}). When applied to a named +dataset (other than \TEXcode {default}), a named rendering needs to be associated +through \Cindex {definebtxrendering} as is done here. + +Note that the define shown above explicitly inherits from a rendering named +\TEXcode {apa} that was itself defined when loading the specification file. +\startfootnote The rendering parent \index {style+APA}\TEXcode {[apa]} sets the +parameters: \TEXcode {specification=apa,} \TEXcode {sorttype=authoryear,} and +\TEXcode {numbering=no,} described below. It also sets various list parameters in +a protected \TEXcode {apa} namespace to produce a \quote {hanging} bibliography +list. \stopfootnote Had this inheritance not been specified, the new rendering +would inherit default, minimal settings. This notion of inheritance will be +further illustrated later. + +The bibliography list rendering of our example dataset, following the \index +{style+APA}APA style, is: + +\getbuffer + +The rendering is a list whose appearance can be tuned, as any list in \CONTEXT. +It is somewhat more complex to manage, though, because we can have not only many +different standards but also many fields that can be set up. This means that +there are several commands involved. As we saw demonstrated above, a rendering is +defined and setup using the commands: + +\cindex{definebtxrendering} + +\showsetup{definebtxrendering} + +\cindex{setupbtxrendering} + +\showsetup{setupbtxrendering} + +A rendering is then placed using \Cindex {placebtxrendering}, a \CONTEXT\ command +that accepts the same arguments as for its setup. Using \TEXcode +{method=dataset}, as above, one renders the entire contents of the dataset. +Normally, however, one would not use this \TEXcode {method} and place only a +selection of entries that are to be used in the document, whereas the dataset may +very well contain many other, unused references. The \TEXcode {method=global} or +\TEXcode {method=local} option can be used to specify if this use is to be global +for the entire document or else local to a structure element such as a part or a +chapter. + +\cindex{placebtxrendering} + +\showsetup{placebtxrendering} + +\cindex{placelistofpublications} + +\showsetup{placelistofpublications} + +The rendering is a \TEXcode {list} and this reference list is numbered. These +numbers can be displayed, or not, depending on the bibliography style +specification through the use of the \index {numbering}\TEXcode {numbering=yes} +or \TEXcode {no} parameter values. The \index {style+APA}APA style, illustrated +above, normally does not number the bibliography list. + +The reference list is also \index {sorting}sorted, controlled by the parameter +\TEXcode {sorttype}; here \TEXcode {sorttype=authoryear}, appropriate for the +\index {style+APA}APA style, \Index {sorting} first by author list, then by +publication year, then by title, finally by page. One can sort the list in many +ways: for example \TEXcode {sorttype=index} will render the list in the order in +which it was loaded into the dataset (see \in {table} [tab:sorttype] for an +explanation of list sorting schemes). + +\startplacetable [location=force, + title={\TEXcode {sorttype=}}, + reference=tab:sorttype] +\index{sorting} +\starttabulate [|Tp(5.5em)|p(.75\textwidth)|] +\HL +\NC default\\none\\cite\\list +\NC render the list in the order in which it was built, + that is, in the order that references were selected from the dataset for + inclusion in the list. \NC \NR +\HL +\NC dataset\\index +\NC sort the list according to the dataset index, that is, in the order in that + references were added to the dataset. \NC \NR +\HL +\NC reference +\NC sort the list in alphabetical order of the citation \Index{tag}s of the + dataset. Note that all entries missing tags get assigned the dataset index as + their tag. \NC \NR +\HL +\NC key +\NC sort the list in alphabetical order of the entry field \TEXcode {key} + (traditionally used in \BIBTEX\ as an alternate sorting key). Falls back on + the dataset index if no such field is present. \NC \NR +\HL +\NC short +\NC sort the list in alphabetical order of the short tag (first three letters + of the author name or first letter of the first three authors followed by + the last two digits of the year). \NC \NR +\HL +\NC authoryear +\NC sort the list in alphabetical order of the authors (or editors or publisher), + then by publication year, then by title (or by journal and volume) and + finally by page. \NC \NR +\stoptabulate +\stopplacetable + +As a concrete example, the rendering named \TEXcode {example} above inherits from +the rendering instance named \TEXcode {apa} that is defined in the specification +file as: + +\cindex{definebtxrendering} + +\startTEX +\definebtxrendering + [apa] + [specification=apa, + sorttype=authoryear, + numbering=no] +\stopTEX + +\startaside +A more subtle characteristic of renderings is that one generally would not want a +bibliography list to appear redundantly in a document as that would be confusing, +unless of course it is desired that elements of the list reappear in later lists, +for example when placing partial bibliographies at the end of each chapter and a +complete bibliography list at the end of a book. One must specify \TEXcode +{repeat=yes} in order to get multiple renderings of a bibliography list; +otherwise, as they appear, entries get marked as placed and will be inhibited +from being placed again elsewhere. +\stopaside + +All renderings of bibliography lists such as the one shown earlier in this +section also depend on a set of general list parameters that apply to each +individual entry (a cited publication), as for any list item in \CONTEXT. These +can be adjusted through the command \Cindex {setupbtxlist} (further described in +\in {section} [sec:list], below). As an example, the \TEXcode {apa} specification +file includes: + +\cindex{setupbtxlist} + +\startTEX +\setupbtxlist + [apa] + [alternative=paragraph, + width=fit, + distance=.5em, + margin=3em] +\stopTEX + +Such settings (yielding a hanging list that would be inappropriate with a +numbered bibliography list) get inherited from the \TEXcode {apa} namespace in +the rendering that we named \TEXcode {example} above. + +Let's try a new example (using a file taken from the \index {TUG bibliography +archive}\goto {TUG bibliography archive} +[url(http://ftp.math.utah.edu/pub/tex/bib/index.html)]): \startfootnote \index +{template.bib} The file \TEXcode {template-clean.bib} is simply a copy of \TEXcode +{template.bib} that has been cleaned|-|up to remove the empty entries. +\stopfootnote + +\startbuffer +\definebtxdataset[template] +\usebtxdataset [template][template-clean.bib] + +\loadbtxdefinitionfile[aps] +\definebtxrendering + [template] + [aps] + [dataset=template, + group=examples] + +\placelistofpublications + [template] + [method=dataset] +\stopbuffer + +\cindex{definebtxdataset} +\cindex{usebtxdataset} +\cindex{loadbtxdefinitionfile} +\cindex{definebtxrendering} +\cindex{placelistofpublications} + +\typeTEXbuffer + +Here, the new rendering is defined to inherit explicitly from a rendering named +\index {style+APS}\TEXcode {aps} (whose specification is loaded but not activated +here). Notice, in particular, compared to the previous rendering example, that +the list is numbered and that there is no hanging margin (it uses the standard +list \TEXcode {alternative=b}): + +\getbuffer + +The \Index {numbering} of the references are unique and pick|-|up from where the +previous numbering stops (the first example contains 33 references, although this +numbering is not displayed). This behavior can be \TEXcode {method=global} for +the entire document, or else \TEXcode {method=local}, limited to a structural +element such as a chapter or a part. Furthermore, one can associate renderings +into particular number groups, effectively isolating them from any other +renderings. For example, as seen above in the rendering definitions, the present +manual uses: + +\cindex{setupbtxrendering} + +\startTEX +\setupbtxrendering[example] [group=examples] +\setupbtxrendering[template][group=examples] +\stopTEX + +thus setting the numbering of the group \TEXcode {examples} apart from the +numbering of the dataset \TEXcode {default} and its named rendering (which contains +this manual's own bibliography, to be placed later, on \at {page} [ch:biblio]). + +\stopsection + +\startsection + [reference=sec:styles, + title={Rendering styles, or more on specifications}] + +The default rendering style implemented in the \MKII\ module was loosely based on +the \index {style+APA}APA standard. In contrast, we made a design choice in the +present \MKIV\ system to provide a very minimal \TEXcode {default} style, and one +should not expect much from this default: in fact, it only recognizes \type +{article} and \type {book} entries (see the bibliography on \at {page} +[ch:biblio]). A user requiring a more complete rendering will want to explicitly +load and activate another style file. One such complete specification, +illustrated above and appropriately named \index {style+APA}\TEXcode {apa}, is +described in the \cite [title] [default::APA2010]. \cite [num] +[default::APA2010] + +\startaside +\emphasis {A note on the \index {style+APA}APA style:} We get the strong +impression that the APA bibliography style standard was made with the implicit +assumption that manual intervention would be involved in the editing and +production process; It has been an arduous task to create a system capable of +fully conforming to these specifications. + +Furthermore, we note that it has sometimes been argued that a numbered citation +system and bibliography list is supposedly superior to the author|-|year scheme +as is employed in the \index {style+APA}APA style (amongst others); indeed, +handling numbered citations is certainly much easier from the point of view of +the programmer of an automated typesetting system such as \TEX. Yet many find +that the longer author|-|year citations can be of great use to the reader (as +well as the writer) so we take no stand in this debate and provide both +possibilities. + +We have made (and continue to make) a great effort to scrupulously respect the +\index {style+APA}APA style in the so|-|named rendering. Yet be warned that very +few editors and publishers in fact follow this style exactly so some +customization will always be required. +\stopaside + +In addition to the APA specification, there are many prescribed styles to render +bibliographic descriptions that can be programmed as standards. Alternatives to +\index {style+APA}\TEXcode {specification=apa} might be \index +{style+MLA}\TEXcode {mla}, \index {style+Chicago}\TEXcode {chicago}, \index +{style+Harvard}\TEXcode {harvard}, \index {style+IEEE}\TEXcode {ieee}, \index +{style+APS}\TEXcode {aps} (commonly used in the physical sciences), \index +{style+Vancouver}\TEXcode {vancouver} (used in the biological sciences), or many +others. At this time, we only provide two description files, with \index +{style+APS}\TEXcode {aps} being an example\startfootnote The \index +{style+APS}APS style attempts to be very compact, providing complete yet minimal +information, in contrast to the \index {style+APA}APA style which is rather +verbose. \stopfootnote of a number|-|based rather than an authoryear|-|based +scheme; more style schemes may be added in the future and the customization of a +rendering style will be described in a later chapter. + +The rendering style usually also implies a particular bibliography list \Index +{sorting} scheme as well as the use of a particular citation style. Indeed, the +rendering of bibliography lists and references to it are intimately coupled. This +question will be explained a bit later. The \index {style+APA}APA style, for +example, specifies that the bibliography list be sorted by author and then by +year, then by title. The list is not numbered (references are cited by author and +year). Note, however, as can be seen from the two examples shown above that the +references were indeed assigned numbers even though they are not displayed in the +\index {style+APA}\TEXcode {apa} rendering (the user can easily choose to display +these numbers, if desired). + +\stopsection + +\startsection + [list={Bibliography list scope}, + title={Bibliography list \Index{scope}}] + +A single dataset can by used with multiple renderings. Although these renderings +may illustrate different styles (as here for the purpose of demonstration in a +manual on bibliographies), this would not be a coherent choice for a document +that would normally employ a single bibliography style. + +The most obvious use of multiple renderings (employing a single specification) is +the placement of bibliography lists localized by structure elements: parts, +chapters in a book, sections, etc. through the option \TEXcode +{criterium=chapter}, for example. This can be setup using: + +\cindex{setupbtxrendering} + +\startTEX +\setupbtxrendering + [default] + [repeat=yes, + continue=yes, + method=global] +\stopTEX + +followed at the end of each chapter by + +\cindex{placelistofpublications} + +\startTEX +\placelistofpublications + [criterium=chapter] +\stopTEX + +The numbering might alternately be made local through the option \TEXcode +{method=local}. If desired, the reference numbers can also get prefixed: + +\cindex{setupbtxlist} + +\startTEX +\setupbtxlist + [default] + [prefix=yes, + width=1cm] +\stopTEX + +A bibliography list rendering placed at a single location, at the end of a book, +for example, can also be easily split into structural parts. The following code +(given without any explanation) illustrates this idea nicely: + +\cindex{placelistofpublications} + +\startTEX +\startbackmatter + \startchapter [title=Bibliography,number=no,incrementnumber=no] + \startsubject [title=Introduction] + \placelistofpublications + [criterium=reference,reference=introduction] + \stopsubject + \dorecurse{12} { + \startsubject [title={Chapter #1}] + \placelistofpublications + [criterium=bodypart:chapter,reference=#1] + \stopsubject + } + \stopchapter +\stopbackmatter +\stopTEX + +Note, as the above demonstrates, that the list of bibliography citations for +\emphasis {any} referenced structural element can be placed \emphasis {anywhere} +in the document, not simply within the structural element itself. + +\stopsection + +\startsection[title=Language] + +Bibliography lists (and citations in the text, see below) are rendered in the +language of the document (\Cindex {mainlanguage}). However, a bibliography entry +can contain a \TEXcode {language=} field and this can be used (if present), +depending on the specification, in the rendering and hyphenation of the \TEXcode +{title}, for example. + +One might choose to override this behavior and impose a single language for all +bibliography entries (as well as for all other \CONTEXT\ constructs) using +\Cindex {setupdelimitedtext} \TEXcode {[language=global]}. + +Since this directive is general for all delimited text in \CONTEXT\ and is not +specific to bibliographies, one can apply it to force a particular language +within a unique section, as in: + +\cindex{setupdelimitedtext} +\cindex{placelistofpublications} + +\startTEX +\startsection[title=Bibliografía] + \setupdelimitedtext[language=es] + \placelistofpublications +\stopsection +\stopTEX + +% to Hans: This currently does not work! +% to Alan: I need an example! + +The language setting also influences the sorting of \UTF\ strings, in particular +authors and titles. + +\cindex {setupdelimitedtext} +\showsetup[setupdelimitedtext] + +\startplacetable [title={\cindex{setupdelimitedtext}\TEXcode{\setupdelimitedtext[language=…]}}] + \starttabulate [|Tl|p(.7\textwidth)|] + \NC language= \NC \NC \NR + \HL + \NC {\it<blank>} \NC (the default) use the current active language; \NC \NR + \NC local \NC respect local language directives (such as the + entry's \TEXcode {language={…},} field, if present + and managed by the rendering specification) \NC \NR + \NC global \NC impose the main document language; \NC \NR + \NC en, de, nl, + \unknown \NC impose the specified language. \NC \NR + \HL + \stoptabulate +\stopplacetable + +\startsubsubject[title=Translated titles] + +Going beyond this handling of punctuation, labels and sorting, we have also +introduced an entirely new feature, allowing for dataset entries to contain +fields describing translated titles, for example. This is particularly useful +when including citations to references published in languages other than the +document language. + +Below is an example including \emphasis{three} languages: \startfootnote In this +reference, the \TEXcode {title} and the \TEXcode {booktitle} are in different +languages and the \TEXcode {language = {french},} field refers to the cited text. +Both titles would have been rendered using French hyphenation rules had this not +been overridden by including the switch \TEXcode {\de} that otherwise should be +avoided in a database. The solution used here is sloppy, but fortunately, a +complicated situation such as this is not very common. +\stopfootnote + +% We could have +% booktitle:de = {Die ...}, +% +% but what simple logic could be used to indicate choosing this title? +% The present case could, perhaps should, have language = {german}, but this +% would simply switch the problem to title = {\fr Principes ...}, + +\startbuffer +\startbuffer[leibniz] +@INCOLLECTION{Leibniz1885, + author = {Leibniz, G. W.}, + title = {Principes de la nature et de la grâce fondés en raison, 1714}, + title:en = {Principles of Nature and Grace Founded in Reason}, + booktitle = {\de Die Philosophischen Schriften von Gottfried Wilhelm Leibniz}, + booktitle:en = {The Philosophical Writings of Gottfried Wilhelm Leibniz}, + editor = {Gerhardt, C. G.}, + publisher = {Weidmann}, + year = {1885}, + volume = {6}, + chapter = {8}, + pages = {598–606}, + address = {Berlin}, + language = {french}, +} +\stopbuffer +\stopbuffer + +\typeTEXbuffer \getbuffer + +\startbuffer +\usebtxdataset [leibniz][leibniz.buffer] +\definebtxrendering[leibniz][apa][group=examples,dataset=leibniz] +\placebtxrendering [leibniz][method=dataset] +\stopbuffer + +with + +\typeTEXbuffer + +that gets rendered as: + +\getbuffer + +In the \index {style+APA}APA bibliography style, the original reference title is +listed followed by the translated title (within square brackets), the translation +chosen being that of the \Cindex {mainlanguage} of the document (if present in +the entry, of course). In other bibliography styles, this feature might not be +implemented or may be ignored. + +\stopsubsubject + +\startsubsubject + [title=Multilingual bibliographies] + +The present handling of languages is only the beginning, and these features will +be developed further in the future: multilingual typesetting being one of the +great strengths behind \CONTEXT. + +\stopsubsubject + +\stopsection + +\startsection + [title=Page index] + +The list renderings can also include a page index of citations to each entry. +This can be enabled using the parameter \TEXcode {pagestate}: + +\cindex{setupbtxrendering} + +\startTEX +\setupbtxrendering [pagestate=start] +\stopTEX + +As this is more of a subject related to the citation mechanism, it will be +described in the following chapter (see \in {section} [sec:index], \at {p.} +[sec:index]). + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/publications/publications-style.tex b/doc/context/sources/general/manuals/publications/publications-style.tex new file mode 100644 index 000000000..2e0937887 --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-style.tex @@ -0,0 +1,359 @@ +\startenvironment publications-style + +\startmode[atpragma] + \usemodule[scite] % gives the default lexing +\stopmode + +\dontcomplain + +\setupbodyfont + [dejavu,10pt] + +\definecolor[fore:one] [darkmagenta] +\definecolor[fore:two] [darkcyan] +\definecolor[fore:three][darkyellow] + +% \definecolor[back:one][.85(darkblue,white)] +% \definecolor[back:two][.85(darkcyan,white)] +\definecolor[back:one] [.90(darkyellow,white)] +\definecolor[back:two] [.90(darkyellow,white)] +\definecolor[back:three][.90(darkblue,white)] + +\setuphead + [chapter] + [header=high, + style=\bfc] + +\setuphead + [section,subject] + [style=\bfb] + +\setuphead + [subsection,subsubject] + [style=\bfa] + +\setuphead + [chapter,section,subject,subsection,subsubject] + [color=fore:one] + +\setupheader + [color=fore:one] + +\setuplayout + [topspace=1.5cm, + bottomspace=1cm, + width=middle, + height=middle] + +\setupfootertexts + [pagenumber] + +\setupheadertexts + [chapter] + +\setupnotes + [location=none] + +\setupnotation + [way=bychapter] + +\startsetups chapter:after + \ifcase\rawcountervalue[footnote]\relax + \or + \startsubject[title=Footnote] + \placefootnotes + \stopsubject + \else + \startsubject[title=Footnotes] + \placefootnotes + \stopsubject + \fi +\stopsetups + +\setuphead + [chapter] + [aftersection=\setups{chapter:after}] + +\setupwhitespace + [big] + +% All this syntax highlighting doesn't look good but Alan likes it, so: + +\ifdefined\scitebuffer + + \definetype [BTXcode] [option=bibtex] + \definetype [XMLcode] [option=xml] + \definetype [TEXcode] [option=tex] + \definetype [LUAcode] [option=lua] + \definetype [MPcode] [option=mps] + + \definetyping[BTX] [option=bibtex] + +\else + + \definetype [BTXcode] [option=,color=fore:two] + \definetype [XMLcode] [option=,color=fore:two] + \definetype [TEXcode] [option=,color=fore:two] + \definetype [LUAcode] [option=,color=fore:two] + \definetype [MPcode] [option=,color=fore:two] + + \definetyping[BTX] [option=,color=fore:two] + + \setuptyping [BTX] [option=,color=fore:one] + \setuptyping [XML] [option=,color=fore:one] + \setuptyping [TEX] [option=,color=fore:one] + \setuptyping [LUA] [option=,color=fore:one] + \setuptyping [MP] [option=,color=fore:one] + +\fi + +\setuptype + [option=, + color=fore:two] + +\setuptyping + [option=, + color=fore:one] + +\setuptyping + [keeptogether=yes] + +% \setupinteraction +% [state=start, +% style=bold, +% color=fore:two, +% contrastcolor=fore:two] + +\setupinteraction + [state=start, + style=, + color=, + contrastcolor=] + +\setupalign + [verytolerant] + +\definehighlight + [emphasis] + [style=italic] + +% This bit of MP magic keeps the text aligned and puts the left frame in the margin. + +\startuseMPgraphic{mpos:region:aside} + for i=1 upto nofmultipars : + multipars[i] := multipars[i] leftenlarged ExHeight ; + endfor ; + draw_multi_pars ; + draw_multi_side ; +\stopuseMPgraphic + +\definetextbackground + [framedbg] + [location=paragraph, + before=\blank, + after=\blank, + mp=mpos:region:aside, + topoffset=.5ex, + leftoffset=0pt, + rightoffset=1ex, + bottomoffset=.5ex, + frame=off, + leftframe=on, + frameoffset=1ex, + rulethickness=2pt, + framecolor=fore:two, + background=color, + backgroundcolor=back:two] + +\definetextbackground + [aside] + [framedbg] + [framecolor=fore:one, + backgroundcolor=back:one] + +\setupbtxrendering + [before={\startframedbg\blank[disable]}, + after={\blank[back]\stopframedbg}] + +% HH: low level, no high level switch (yet): + +\setnewconstant\kindofpagetextareas 1 + +\defineregister + [indexofauthors] + +\definebtxregister + [authors] + [field=author, + register=indexofauthors, + method=always, + dataset={default,tugboat,boekplan}, + alternative=invertedshort] + +% the \textbackslash variant doesn't always work out well with inline verbatim as \tt is +% something else .. also, following that by some arguments in \type is messy +% +% bad: \cindex {cite}\TEXcode{\cite[field][tag]} + +\define [1] \Index {\index {#1}#1} +\define [1] \tindex{\index [#1]{\tt#1}} +\define [1] \Tindex{\tindex{#1}{\tt#1}} +\define [1] \cindex{\expanded{\index [#1]{\TEXcode{\expandafter\string\csname#1\endcsname}}}} % bah +\define [1] \Cindex{\expanded{\cindex{#1}{\TEXcode{\expandafter\string\csname#1\endcsname}}}} % bah + +% hm + +\define [2] \name {\btxregisterauthor{#1 #2}\indexofauthors{#1, #2}} +\define [2] \Name {\name{#1}{#2}#1} + +\setupnote + [footnote] + [next={ }] % Why should this be necessary? + +\setupfloat + [table] + [default={here,force}] + +\setupcaption + [table] + [location=top] + +\setuplist + [table] + [interaction=all, + alternative=c] + +\usemodule[abr-02] +\usemodule[set-11] + +\logo [BibTeX] {Bib\TeX} + +\startmode[export] + + \setupbackend + [export=yes]%, + + % \setupexport + % [hyphen=yes, + % width=60em] + + \setuptagging + [state=start] + + % HH: bah: + + \setupinteraction [option=bookmark] + \setupinteractionscreen [option=bookmark] + \placebookmarks [chapter,title,section,subsection] + +\stopmode + +\setupinteraction + [title={\documentvariable{title}}, + subtitle={\documentvariable{subtitle}}, + author={\documentvariable{author}}] + +\usemodule[setups-basics] + +\loadsetups[i-context] + +% \setupframedtext +% [setuptext] +% [rulethickness=2pt, +% framecolor=fore:three, +% leftframe=on, +% frame=off, +% width=\dimexpr\hsize\relax, +% background=color, +% backgroundcolor=back:three] + +\definetextbackground + [mysetuptext] + [framedbg] + [framecolor=fore:three, + topoffset=1ex, + bottomoffset=1ex, + backgroundcolor=back:three] + +\startsetups xml:setups:start + \starttextbackground[mysetuptext] +\stopsetups + +\startsetups xml:setups:stop + \stoptextbackground +\stopsetups + +% Since this is a manual about bibliographies, let us use citations... + +\startbuffer [bibliography] +@Book{Ierusalimschy2006, + author = {Ierusalimschy, R.}, + title = {Programming in Lua}, + year = {2006}, + publisher = {Lua.org}, + isbn = {8590379817}, + url = {http://www.lua.org/pil/contents.html}, +} + +@Book{APA2010, + title = {Publication Manual of the American Psychological Association}, + year = {2010}, + edition = {Sixth}, + address = {Washington, DC}, + publisher = {American Psychological Association}, + note = {291 pages}, + ISBN = {1-4338-0559-6 (hardcover)}, + url = {http://www.apa.org/books/}, +} + +@Article{Patashnik1988, + title = {Bib\TEX ing}, + author = {Patashnik, Oren}, + year = {1988}, + month = {February}, + day = {8}, + url = {https://www.ctan.org/tex-archive/biblio/bibtex/base/btxdoc..pdf}, +} + +@Article{Markey2009, + title = {Tame the BeaST}, + subtitle = {The B to X of Bib\TEX}, + author = {Markey, Nicolas}, + year = {2009}, + month = {October}, + day = {11}, + url = {http://tug.ctan.org/info/bibtex/tamethebeast/ttb_en.pdf}, +} + +@Book{vanLeunen1992, + title = {A Handbook for Scholars}, + author = {van Leunen, Mary-Claire}, + year = {1992}, + edition = {revised}, + publisher = {Oxford University Press}, + address = {New York}, +} + +@BOOK{Darwin1859, + author = {Darwin, C.}, + year = {1859}, + title = {On the Origin of Species by Means of Natural Selection, or The Preservation + of Favoured Races in the Struggle for Life}, + publisher = {John Murray}, + address = {London} +} +\stopbuffer + +\usebtxdataset + [bibliography.buffer] + +% also used: + +%\definebtxdataset +% [tugboat] + +%\usebtxdataset +% [tugboat] +% [tugboat.bib] + +\stopenvironment diff --git a/doc/context/sources/general/manuals/publications/publications-titlepage.tex b/doc/context/sources/general/manuals/publications/publications-titlepage.tex new file mode 100644 index 000000000..dfc53419a --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-titlepage.tex @@ -0,0 +1,39 @@ +\environment publications-style + +\startcomponent publications-titlepage + +\startMPpage + + StartPage ; + + picture pic ; pic := image ( + path pth ; pth := ((0,0) for i=1 step 2 until 20 : -- (i,1) -- (i+1,0) endfor) ; + for i=0 upto 9 : draw pth shifted (0,2*i) ; endfor ; + ) ; + + picture btx ; btx := textext("\ssbf\WORDS{\getvariable{document}{title}}") ; + picture ctx ; ctx := textext("\ssbf\WORDS{\getvariable{document}{subtitle}}") ; + picture dtx ; dtx := textext("\ssbf \getvariable{document}{author}") ; + + pic := pic shifted - llcorner pic ; + btx := btx shifted - llcorner btx ; + ctx := ctx shifted - llcorner ctx ; + dtx := dtx shifted - llcorner dtx ; + + pic := pic xysized (PaperWidth,PaperHeight) ; + btx := btx xsized (2PaperWidth/3) shifted (.25PaperWidth,.225PaperHeight) ; + ctx := ctx xsized (2PaperWidth/3) shifted (.25PaperWidth,.150PaperHeight) ; + dtx := dtx xsized (2PaperWidth/3) shifted (.25PaperWidth,.075PaperHeight) ; + + fill Page withcolor \MPcolor{fore:two} ; + + draw pic withcolor \MPcolor{fore:one} ; + draw btx withcolor \MPcolor{lightgray} ; + draw ctx withcolor \MPcolor{lightgray} ; + draw dtx withcolor \MPcolor{lightgray} ; + + StopPage ; + +\stopMPpage + +\stopcomponent diff --git a/doc/context/sources/general/manuals/publications/publications-tracing.tex b/doc/context/sources/general/manuals/publications/publications-tracing.tex new file mode 100644 index 000000000..1c97c715d --- /dev/null +++ b/doc/context/sources/general/manuals/publications/publications-tracing.tex @@ -0,0 +1,108 @@ +\environment publications-style + +\startcomponent publications-tracing + +\startchapter + [title=Tracing] + +There are several tracing options. If you want to see where a citations refers to +and where a list entry point back to, you can say: + +\startTEX +\enabletrackers[publications.crosslinks] +\stopTEX + +This injects markers in both places. One list entry can point to multiple +citations. The other tracers a more for debugging and can generate lots of +messages. + +\startTEX +publications +publications.authorhash +publications.cite +publications.cite.missing +publications.cite.references +publications.detail +publications.duplicates +publications.match +publications.setups +publications.sorters +publications.suffixes +\stopTEX + +You can also trace the databases. Take this one: + +\startbuffer +\startbuffer[phony] +@comment { warning : + Hello Allan! + How are you doing today? +} + +@CoMMeNT { message : + Hello Allan! + How are you doing today? +} + +@comment { + all kind of crap +} + +@Article{Myarticle, + Title = {My title}, + Author = {Myself, Me}, + Journal = {My favorite journal}, + Year = {2014}, + Pages = {1}, +} + +@Foo{foo, + Goo = goo, +} +\stopbuffer +\stopbuffer + +\typeBTXbuffer \getbuffer + +\startbuffer +\usebtxdataset [phony] [phony.buffer] +\stopbuffer + +When we load this database (buffer) with: + +\typeTEXbuffer \getbuffer + +We get this on the console and in the log + +\starttyping +publications > adding bib data to set 'phony' from source 'phony' +publications > phony > warning : Hello Allan! +publications > phony > warning : How are you doing today? +publications > phony > message : Hello Allan! +publications > phony > message : How are you doing today? +\stoptyping + +You can use this feature to add warnings to your database for entries that you +need to check. + +You can also use comment to hide entries: + +\startBTX +@comment { + + @article{Hobby1999, + author = {Hobby, John D.}, + year = {1999}, + title = {Introduction to MetaPost}, + journal = {Eutupon}, + volume = {2}, + month = {April}, + pages = {39-53}, + } + +} +\stopBTX + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/publications/template-clean.bib b/doc/context/sources/general/manuals/publications/template-clean.bib new file mode 100644 index 000000000..7537362e6 --- /dev/null +++ b/doc/context/sources/general/manuals/publications/template-clean.bib @@ -0,0 +1,419 @@ +%%% ==================================================================== +%%% BibTeX-file{ +%%% author = "BibNet", +%%% version = "1.01", +%%% date = "06 April 1995", +%%% time = "10:40:31 MST", +%%% filename = "template.bib", +%%% address = "Center for Scientific Computing +%%% Department of Mathematics +%%% University of Utah +%%% Salt Lake City, UT 84112 +%%% USA +%%% and +%%% Utah Supercomputing Institute +%%% University of Utah +%%% Salt Lake City, UT 84112 +%%% USA", +%%% telephone = "+1 801 581 5254", +%%% FAX = "+1 801 581 4148", +%%% checksum = "50833 419 1409 11712", +%%% email = "bibnet at math.utah.edu (Internet)", +%%% codetable = "ISO/ASCII", +%%% keywords = "BibTeX, template", +%%% supported = "yes", +%%% docstring = "This file contains empty sample BibTeX entry +%%% templates, and one filled-in example of each. +%%% +%%% The checksum field above contains a CRC-16 +%%% checksum as the first value, followed by the +%%% equivalent of the standard UNIX wc (word +%%% count) utility output of lines, words, and +%%% characters. This is produced by Robert +%%% Solovay's checksum utility.", +%%% } +%%% ==================================================================== + +% @Article{, +% author = "", +% title = "", +% journal = "", +% year = "", +% OPTvolume = "", +% OPTnumber = "", +% OPTpages = "", +% OPTmonth = "", +% OPTnote = "", +% bibdate = "Thu Feb 10 16:53:42 1994", +% } +% +% @Booklet{, +% title = "", +% OPTauthor = "", +% OPThowpublished = "", +% OPTaddress = "", +% OPTmonth = "", +% OPTyear = "", +% OPTnote = "", +% bibdate = "Thu Feb 10 16:53:33 1994", +% } +% +% @Book{, +% author = "", +% title = "", +% publisher = "", +% year = "", +% ISBN = "", +% LCCN = "", +% OPTeditor = "", +% OPTvolume = "", +% OPTnumber = "", +% OPTseries = "", +% OPTaddress = "", +% OPTedition = "", +% OPTmonth = "", +% OPTnote = "", +% OPTpages = "", +% OPTprice = "", +% OPTacknowledgement = "", +% bibdate = "Thu Feb 10 16:53:36 1994", +% } +% +% @InBook{, +% author = "", +% title = "", +% chapter = "", +% publisher = "", +% year = "", +% ISBN = "", +% LCCN = "", +% OPTeditor = "", +% OPTvolume = "", +% OPTnumber = "", +% OPTseries = "", +% OPTaddress = "", +% OPTedition = "", +% OPTmonth = "", +% OPTtype = "", +% OPTnote = "", +% OPTpages = "", +% OPTprice = "", +% OPTacknowledgement = "", +% bibdate = "Thu Feb 10 16:52:57 1994", +% } +% +% @InCollection{, +% author = "", +% title = "", +% booktitle = "", +% publisher = "", +% year = "", +% ISBN = "", +% LCCN = "", +% OPTeditor = "", +% OPTvolume = "", +% OPTnumber = "", +% OPTseries = "", +% OPTtype = "", +% OPTchapter = "", +% OPTaddress = "", +% OPTedition = "", +% OPTmonth = "", +% OPTnote = "", +% OPTpages = "", +% OPTprice = "", +% OPTacknowledgement = "", +% bibdate = "Thu Feb 10 16:52:36 1994", +% } +% +% @InProceedings{, +% author = "", +% title = "", +% booktitle = "", +% year = "", +% ISBN = "", +% ISBN = "", +% OPTeditor = "", +% OPTvolume = "", +% OPTnumber = "", +% OPTseries = "", +% OPTorganization = "", +% OPTpublisher = "", +% OPTaddress = "", +% OPTmonth = "", +% OPTnote = "", +% OPTpages = "", +% OPTprice = "", +% bibdate = "Thu Feb 10 16:53:46 1994", +% } +% +% @Manual{, +% title = "", +% OPTauthor = "", +% OPTorganization = "", +% OPTaddress = "", +% OPTedition = "", +% OPTyear = "", +% OPTmonth = "", +% OPTnote = "", +% bibdate = "Thu Feb 10 16:53:17 1994", +% } +% +% @MastersThesis{, +% author = "", +% title = "", +% school = "", +% year = "", +% OPTaddress = "", +% OPTmonth = "", +% OPTnote = "", +% OPTtype = "", +% bibdate = "Thu Feb 10 16:53:30 1994", +% } +% +% @Misc{, +% OPTauthor = "", +% OPTtitle = "", +% OPThowpublished = "", +% OPTyear = "", +% OPTmonth = "", +% OPTnote = "", +% bibdate = "Thu Feb 10 16:52:31 1994", +% } +% +% @Periodical{, +% key = "", +% title = "", +% OPTeditor = "", +% OPTorganization = "", +% OPTvolume = "", +% OPTnumber = "", +% OPTpages = "", +% OPTmonth = "", +% OPTyear = "", +% OPTISSN = "", +% OPTpublisher = "", +% OPTaddress = "", +% OPThowpublished = "", +% OPTnote = "", +% OPTkeywords = "", +% bibdate = "Thu Feb 10 16:52:20 1994", +% } +% +% @PhdThesis{, +% author = "", +% title = "", +% school = "", +% year = "", +% OPTaddress = "", +% OPTmonth = "", +% OPTtype = "", +% OPTnote = "", +% bibdate = "Thu Feb 10 16:53:28 1994", +% } +% +% @Proceedings{, +% title = "", +% year = "", +% ISBN = "", +% OPTeditor = "", +% OPTvolume = "", +% OPTnumber = "", +% OPTseries = "", +% OPTpublisher = "", +% OPTorganization = "", +% OPTaddress = "", +% OPTmonth = "", +% OPTnote = "", +% OPTpages = "", +% OPTacknowledgement = "", +% bibdate = "Thu Feb 10 16:53:13 1994", +% } +% +% @TechReport{, +% author = "", +% title = "", +% institution = "", +% year = "", +% OPTtype = "", +% OPTnumber = "", +% OPTaddress = "", +% OPTmonth = "", +% OPTnote = "", +% bibdate = "Thu Feb 10 16:53:24 1994", +% } +% +% @Unpublished{, +% author = "", +% title = "", +% note = "", +% OPTyear = "", +% OPTmonth = "", +% bibdate = "Thu Feb 10 16:52:27 1994", +% } + +%%====================================================================== +@String{inst-mit = "Massachusetts Institute of Technology"} + +@String{j-SPE = "Soft{\-}ware\emdash Prac{\-}tice and Experience"} + +@String{pub-ADOBE = "{Adobe Systems Incorporated}"} +@String{pub-ADOBE:adr = "1585 Charleston Road, P.~O. Box 7900, Mountain + View, CA 94039-7900, USA, Tel: (415) 961-4400"} +@String{pub-CUP = "Cambridge University Press"} +@String{pub-CUP:adr = "New York"} +@String{pub-CURSCI = "Current Science"} +@String{pub-CURSCI:adr = "34--42 Cleveland Street, London, UK"} + +@String{pub-PH = "Pren{\-}tice-Hall"} +@String{pub-PH:adr = "Englewood Cliffs, NJ 07632, USA"} + +@Article{Chen:1988:IPP, + author = "Pehong Chen and Michael A. Harrison", + title = "Index Preparation and Processing", + journal = j-SPE, + year = "1988", + volume = "19", + number = "9", + pages = "897--915", + month = sep, + note = "The {\LaTeX} text of this paper is included in the + {\tt makeindex} software distribution.", +} + +@Book{Kahaner:1989:NMS, + author = "David Kahaner and Cleve Moler and Stephen Nash", + title = "Numerical Methods and Software", + publisher = pub-PH, + address = pub-PH:adr, + year = "1989", + ISBN = "0-13-627258-4", + LCCN = "TA345 .K341 1989", + pages = "xii + 495", + bibdate = "Wed Dec 15 10:35:43 1993", +} + +@InBook{Fletcher:1987:PMO, + author = "R. Fletcher", + title = "Practical Methods of Optimization", + chapter = "8.7~: {P}olynomial time algorithms", + pages = "183--188", + publisher = "John Wiley~\&~Sons", + address = "New York", + edition = "second", + year = "1987", +} + +@InCollection{Johnson:1987:LDT, + author = "Steven C. Johnson and Michael E. Lesk", + title = "Language Development Tools", + booktitle = "{UNIX} System Readings and Applications", + publisher = pub-PH, + address = pub-PH:adr, + year = "1987", + pages = "245--265", + note = "Reprinted from {T}he {B}ell {S}ystem {T}echnical + {J}ournal, 1978", +} + +@InProceedings{Gray:1988:GLA, + author = "Robert W. Gray", + title = "$\gamma$-{GLA}\emdash A Generator for Lexical + Analyzers that Programmers Can Use", + booktitle = "Summer USENIX '88", + year = "1988", + pages = "147--160", + month = jun # " 20--24", +} + +@Manual{Adobe:1990:ATF, + author = pub-ADOBE, + title = "Adobe Type 1 Font Format", + organization = pub-ADOBE, + address = pub-ADOBE:adr, + year = "1990", + month = mar, + partnumber = "LPS0064", +} + +@Mastersthesis{Adams:1986:DFL, + title = "A Dialogue of Forms: Letters and Digital Font Design", + author = "Debra Anne Adams", + year = "1986", + month = sep, + school = inst-mit, + address = "MIT Microreproduction Lab, 77 Massachusetts Avenue, + room 014-0551, Cambridge, MA 02139. \$46.35", + comments = "Deriving other characters from the control characters + in a typeface. Her work continues at Xerox.", +} + +@Misc{Abraxas:1987:P, + author = "{Abraxas Software, Inc.}", + title = "{PCYACC} 2.0", + note = "7033 SW Macadam Ave., Portland, OR 97219.", + year = "1987", +} + +@Periodical{CurSci:1987:A, + key = "C01AIDS", + title = "{AIDS}", + year = "1987--date{}", + publisher = pub-CURSCI, + address = pub-CURSCI:adr, + acknowledgement = ack-ga-gt, + note = "Current Science publishes more than 80 medical + periodicals using an in-house markup language for + which {\TeX} is the back-end typesetting system. All + submitted articles (whether on paper or on magnetic + media) are rekeyed by clerical staff into the markup + system.", +} + +@Phdthesis{Naiman:1991:UGI, + author = "Avi Naiman", + title = "The Use of Grayscale for Improved Character + Presentation", + school = "University of Toronto", + year = "1991", + address = "ATTN: Technical Reports, + Computer Systems Research Institute, + University of Toronto, + 6 King's College Road, + Toronto, Ontario M5S 1A1, + CANADA, + Tel: (416) 978-8751. + The cost is CDN\$16 if inside Canada, US\$16 if outside. + Avi's e-mail address is \path|avi@cvs.rochester.edu|.", + note = "Technical report CSRI-253", + acknowledgement = ack-kb, +} + +@Proceedings{Andre:1989:RID, + title = "Raster Imaging and Digital Topography", + year = "1989", + editor = "Jacques Andr{\'e} and Roger Hersch", + publisher = pub-CUP, + ISBN = "0-521-37490-1", +} + +@TechReport{Chen:1987:AIP, + author = "Pehong Chen and Michael A. Harrison", + title = "Automating Index Preparation", + institution = "Computer Science Division, University of California", + year = "1987", + type = "Technical Report", + number = "87/347", + address = "Berkeley, CA, USA", + month = mar, + note = "This is an expanded version of + \cite{Chen:SPE-19-9-897}.", +} + +@Unpublished{English:1987:UMO, + title = "Using {METAFONT} for Original Font Design", + author = "Paul M. English", + month = aug, + year = "1987", + institution = "University of Massachusetts at Boston", +} diff --git a/doc/context/sources/general/manuals/rules/rules-mkiv.tex b/doc/context/sources/general/manuals/rules/rules-mkiv.tex index 536a37aea..00ab49c25 100644 --- a/doc/context/sources/general/manuals/rules/rules-mkiv.tex +++ b/doc/context/sources/general/manuals/rules/rules-mkiv.tex @@ -627,7 +627,7 @@ primitive here, so we follow the \TEX\ conventions of keywords. \hskip-100mm \darkred \frule width 100mm height 10mm depth 8mm radius 2mm line 2pt\relax \hskip-100mm - \hbox to 100mm{\white \bold \hfill some handy word with frames\hfill} + \hbox to 100mm{\white \bold \hfill some handy word with frames\hfill}% \egroup \stopbuffer diff --git a/doc/context/sources/general/manuals/spacing/spacing-linecorrection.tex b/doc/context/sources/general/manuals/spacing/spacing-linecorrection.tex index c16afbf0a..525dd7490 100644 --- a/doc/context/sources/general/manuals/spacing/spacing-linecorrection.tex +++ b/doc/context/sources/general/manuals/spacing/spacing-linecorrection.tex @@ -6,6 +6,8 @@ \startchapter[title=Line correction] +\startsection[title=Wrapping content] + \startbuffer[linecorrection] \typebuffer \blank @@ -103,6 +105,8 @@ Because in this document we have set the whitespace this also gets added around the box. So, in case your spacing around some special content looks bad, consider using these commands. +\stopsection + \stopchapter \stopcomponent diff --git a/doc/context/sources/general/manuals/spacing/spacing-mkiv.tex b/doc/context/sources/general/manuals/spacing/spacing-mkiv.tex index 375f4e2a8..0f32e4d30 100644 --- a/doc/context/sources/general/manuals/spacing/spacing-mkiv.tex +++ b/doc/context/sources/general/manuals/spacing/spacing-mkiv.tex @@ -28,6 +28,8 @@ \startbodymatter \component spacing-linecorrection + \component spacing-spaces + \component spacing-periods \stopbodymatter \stopdocument diff --git a/doc/context/sources/general/manuals/spacing/spacing-periods.tex b/doc/context/sources/general/manuals/spacing/spacing-periods.tex new file mode 100644 index 000000000..8d493b9a9 --- /dev/null +++ b/doc/context/sources/general/manuals/spacing/spacing-periods.tex @@ -0,0 +1,79 @@ +% language=uk + +\environment spacing-style + +\startcomponent spacing-periods + +\startchapter[title=Periods in abbreviations] + +% \enabletrackers[typesetters.periodkerns] + +When you use so called non french spacing you get more spacing after punctuation +(as determined by the \type {sfcode} of the punctuation character) . However, +when you use periods as delimiters for abbreviations, that period is not the end +of a sentence and you want normal interword spacing instead. One way to achieve +this is to add a backslash after the period but in an automated workflow where +the source is not coming from \TEX\ but for instance in \XML\ format, you can't +do that. The \type {\setupspacing} command can be used to set one of: + +\starttabulate[|T|p|] +\NC fixed \NC \showglyphs \frenchspacing bla bla e.g. some more \NC \NR +\NC packed \NC \showglyphs \newfrenchspacing bla bla e.g. some more \NC \NR +\NC broad \NC \showglyphs \nonfrenchspacing bla bla e.g. some more \NC \NR +\stoptabulate + +The \type {packed} case is similar to \type {fixed} but has slightly larger (some +5\percent) spacing after punctuation which (at least historically) avoids some +side effects with hyphenation and dashes. We default to \type {broad} anyway. + +The next examples demonstrate what the \type {\setperiodkerning} does when it gets +an option passed. Its counterpart is \type {\resetperiodkerning}. + +\starttabulate[|T|Tr|p|] + \HL + \NC \NC \NC \showglyphs \nonfrenchspacing \resetperiodkerning bla bla e.g. some more \NC \NR + \NC \NC \NC \showglyphs \nonfrenchspacing \resetperiodkerning bla bla e.g. Some more \NC \NR + \HL + \NC zerospaceperiods \NC 0 \NC \showglyphs \nonfrenchspacing \setperiodkerning [zerospaceperiods]bla bla e.g. some more \NC \NR + \NC \NC \NC \showglyphs \nonfrenchspacing \setperiodkerning [zerospaceperiods]bla bla e.g. Some more \NC \NR + \HL + \NC smallspaceperiods \NC .25\NC \showglyphs \nonfrenchspacing \setperiodkerning [smallspaceperiods]bla bla e.g. some more \NC \NR + \NC \NC \NC \showglyphs \nonfrenchspacing \setperiodkerning [smallspaceperiods]bla bla e.g. Some more \NC \NR + \HL + \NC halfspaceperiods \NC .50 \NC \showglyphs \nonfrenchspacing \setperiodkerning [halfspaceperiods]bla bla e.g. some more \NC \NR + \NC \NC \NC \showglyphs \nonfrenchspacing \setperiodkerning [halfspaceperiods]bla bla e.g. Some more \NC \NR + \HL +\stoptabulate + +Next we enlarge the affected bit of text so that you can see that the last two +options also affects the space after the periods that bind the characters. + +\startlinecorrection +\startcombination[4*2] + {\scale[scale=3500]{\ruledhbox{\showglyphs \nonfrenchspacing \resetperiodkerning e.g. s}}} {} + {\scale[scale=3500]{\ruledhbox{\showglyphs \nonfrenchspacing \setperiodkerning [zerospaceperiods]e.g. s}}} {} + {\scale[scale=3500]{\ruledhbox{\showglyphs \nonfrenchspacing \setperiodkerning [smallspaceperiods]e.g. s}}} {} + {\scale[scale=3500]{\ruledhbox{\showglyphs \nonfrenchspacing \setperiodkerning [halfspaceperiods]e.g. s}}} {} + {\scale[scale=3500]{\ruledhbox{\showglyphs \nonfrenchspacing \resetperiodkerning e.g. S}}} {} + {\scale[scale=3500]{\ruledhbox{\showglyphs \nonfrenchspacing \setperiodkerning [zerospaceperiods]e.g. S}}} {\ttxx zerospaceperiods} + {\scale[scale=3500]{\ruledhbox{\showglyphs \nonfrenchspacing \setperiodkerning [smallspaceperiods]e.g. S}}} {\ttxx smallspaceperiods} + {\scale[scale=3500]{\ruledhbox{\showglyphs \nonfrenchspacing \setperiodkerning [halfspaceperiods]e.g. S}}} {\ttxx halfspaceperiods} +\stopcombination +\stoplinecorrection + +Defining more options is easy, we only specify the factor that determines mid +periods. When \type {factor} is zero, only the final period is looked at. + +\starttyping +\defineperiodkerning [zerospaceperiods] [factor=0] +\defineperiodkerning [smallspaceperiods] [factor=.25] +\defineperiodkerning [halfspaceperiods] [factor=.5] +\stoptyping + +This mechanism has been present for a while but I forgot about it. When cleaning +up code it was decided to add it to the core. Maybe more options and features are +needed but so far there has never been demand for this so \unknown + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/spacing/spacing-spaces.tex b/doc/context/sources/general/manuals/spacing/spacing-spaces.tex new file mode 100644 index 000000000..0d7f64379 --- /dev/null +++ b/doc/context/sources/general/manuals/spacing/spacing-spaces.tex @@ -0,0 +1,276 @@ +% language=uk + +\environment spacing-style + +\startcomponent spacing-periods + +\startchapter[title=Spacing] + +\startsection[title=Spaces] + +When \TEX\ reads its input and transforms content it into a node list spaces are +turned into glue nodes of subtype \quote {spaceskip} or \quote {xspaceskip}. In +pseudo code, this is what happens: + +\starttyping +if spacefactor >= 2000 and xspaceskip ~= 0 then + space = xspaceskip_space + stretch = xspaceskip_stretch + shrink = xspaceskip_shrink + subtype = xspaceskip +else + if spaceskip == 0 then + space = font_space + stretch = font_stretch + shrink = font_shrink + else + space = spaceskip_space + stretch = spaceskip_stretch + shrink = spaceskip_shrink + end + if space_factor >= 2000 + space = space + font_extraspace + end + stretch = stretch * space_factor + shrink = shrink * space_factor + subtype = spaceskip +end +insert_glue(space,stretch,shrink,subtype) +\stoptyping + +We demonstrate the effects in a few examples. You can use \typ {\showmakeup [space]} to +visualize spaces. + +\def\ShowSpaces#1#2#3% + {\blank + \start + \startsubsubsubject[title={case #1: \type{#2} and \type {#3}}] + \dontleavehmode + #2\relax + #3\relax + \showmakeup[space]% + % \definedfont[Serif*default]% + \nonfrenchspacing + \strut x\space x.\space x\crlf + \frenchspacing + \strut x\space x.\space x\par + \stop + \stopsubsubject + \blank} + +\ShowSpaces{1}{\spacefactor2000}{\xspaceskip100pt} + +\starttabulate[|l|l|] +\HL +\NC \type {\spacefactor} \NC $\geq 2000$ \NC \NR +\NC \type {\xspaceskip} \NC $\neq 0$ \NC \NR +\HL +\NC space \NC xspaceskip_space \NC \NR +\NC stretch \NC xspaceskip_stretch \NC \NR +\NC shrink \NC xspaceskip_shrink \NC \NR +\NC subtype \NC xspaceskip \NC \NR +\HL +\stoptabulate + +\ShowSpaces{2}{\spacefactor1000}{\spaceskip0pt} + +\starttabulate[|l|l|] +\HL +\NC \type {\spacefactor} \NC $\lt 2000$ \NC \NR +\NC \type {\spaceskip} \NC $\eq 0$ \NC \NR +\HL +\NC space \NC font_space \NC \NR +\NC stretch \NC font_stretch \NC \NR +\NC shrink \NC font_shrink \NC \NR +\NC subtype \NC spaceskip \NC \NR +\HL +\stoptabulate + +\ShowSpaces{3}{\spacefactor2000}{\spaceskip0pt} + +\starttabulate[|l|l|] +\HL +\NC \type {\spacefactor} \NC $\geq 2000$ \NC \NR +\NC \type {\spaceskip} \NC $\eq 0$ \NC \NR +\HL +\NC space \NC font_space $+$ extraspace_font \NC \NR +\NC stretch \NC font_stretch \NC \NR +\NC shrink \NC font_shrink \NC \NR +\NC subtype \NC spaceskip \NC \NR +\HL +\stoptabulate + +\ShowSpaces{4}{\spacefactor1000}{\spaceskip100pt} + +\starttabulate[|l|l|] +\HL +\NC \type {\spacefactor} \NC $\lt 2000$ \NC \NR +\NC \type {\spaceskip} \NC $\neq 0$ \NC \NR +\HL +\NC space \NC font_space \NC \NR +\NC stretch \NC font_stretch $\times$ space_factor \NC \NR +\NC shrink \NC font_shrink $\times$ space_factor \NC \NR +\NC subtype \NC spaceskip \NC \NR +\HL +\stoptabulate + +\ShowSpaces{5}{\spacefactor2000}{\spaceskip100pt} + +\starttabulate[|l|l|] +\HL +\NC \type {\spacefactor} \NC $\geq 2000$ \NC \NR +\NC \type {\spaceskip} \NC $\neq 0$ \NC \NR +\HL +\NC space \NC font_space $+$ extraspace_font \NC \NR +\NC stretch \NC font_stretch $\times$ space_factor \NC \NR +\NC shrink \NC font_shrink $\times$ space_factor \NC \NR +\NC subtype \NC spaceskip \NC \NR +\HL +\stoptabulate + +The width of a space relates to the design of a font and therefore the t width of +the space, its stretch and its shrink are taken from the font and scaled +accordingly. Normally we take the space character in the font as reference. +Traditional \TEX\ fonts don't have that character but \OPENTYPE\ fonts have. When +there is no space character, in the case of a monospaced font we take the +emwidth, otherwise we take half the emwidth. As a last resort we can take the +average width of characters. And of even that fails we take half of the font +units. But, as mentioned, modern fonts have a space. + +In the \CONTEXT\ font loader we use a stretch that is 1/2 of the width of a space +and the shrink is 1/3 the width of a space. These values are familiar for those +who come from traditional \TEX. + +As with many variables, you can overload these values when a font is loaded by +setting the \type {spacing} feature. Here is how this is done: + +\startbuffer +\definefontfeature + [morespace] + [spacing=0.50 plus 0.50 minus 0.250] +\definefontfeature + [lessspace] + [spacing=0.25 plus 0.25 minus 0.125] +\definefontfeature + [extramorespace] + [spacing=0.50 plus 0.50 minus 0.250 extra 2.00] +\definefontfeature + [extralessspace] + [spacing=0.25 plus 0.25 minus 0.125 extra 2.00] + +\definedfont[Serif*default] + \inleft{\infofont default} + \samplefile{klein}\par + \blank +\definedfont[Serif*default,morespace] + \inleft{\infofont morespace} + \samplefile{klein}\par + \blank +\definedfont[Serif*default,extramorespace] + \inleft{\infofont extramorespace} + \samplefile{klein}\par + \blank +\definedfont[Serif*default,lessspace] + \inleft{\infofont lessspace} + \samplefile{klein}\par + \blank +\definedfont[Serif*default,extralessspace] + \inleft{\infofont extralessspace} + \samplefile{klein}\par + \blank +\stopbuffer + +\typebuffer + +For demonstration purposes we use a somewhat excessive \type {extra} +specification. By default the extra space is equal to the shrink. + +\blank \start + \showmakeup[space] + \getbuffer +\stop \blank + +\stopsection + +\startsection[title=Expansion] + +Spaces become glue that can shrink or stretch. In the worst case words will come +too close, or the gap will be large. Even worse is that this can lead to +successive lines in a paragraph looking different with respect to spacing. A solution +for this is to use font expansion, although the benefits are often less than +some users want (you) to believe. + +This mechanism is enabled with \type {\setupalign}. There are two variants (\type +{hz} and \type {fullhz}) and a reset (\type {nohz}). In \in {figure} [fig:expansion] +we use the following font definition: + +\startbuffer +\definefont[testfont][Normal*default,quality @ 9pt] +\stopbuffer + +\typebuffer \getbuffer + +We use \type {\showfontexpansion} to view the effective expansion factors of each +glyph. When \type {fullhz} is used fontkerns also can get expanded. Zero values +are not shown. The font kern factors are shown below the character factors. They +can be neglected and one can even wonder if they need a treatment especially +because kerns are also used for relative positioning, accent anchoring and +cursive attachments. + +\startplacefigure[reference=fig:expansion,title={The two expansion methods in action.}] + \startcombination[nx=3,ny=2,location=top] + {\framed[foregroundstyle=\testfont,width=.3\textwidth,align={normal,tolerant,nohz}] {\showfontexpansion\samplefile{ward}}} {} + {\framed[foregroundstyle=\testfont,width=.3\textwidth,align={normal,tolerant,fullhz}]{\showfontexpansion\samplefile{ward}}} {} + {\framed[foregroundstyle=\testfont,width=.3\textwidth,align={normal,tolerant,hz}] {\showfontexpansion\samplefile{ward}}} {} + {\scale[width=.3\textwidth]{\clip[nx=2,ny=4,x=2,y=3]{\framed[foregroundstyle=\testfont,width=.3\textwidth,align={normal,tolerant,nohz}] {\showfontexpansion\samplefile{ward}}}}} {\tttf{nohz}} + {\scale[width=.3\textwidth]{\clip[nx=2,ny=4,x=2,y=3]{\framed[foregroundstyle=\testfont,width=.3\textwidth,align={normal,tolerant,fullhz}]{\showfontexpansion\samplefile{ward}}}}} {\tttf{fullhz}} + {\scale[width=.3\textwidth]{\clip[nx=2,ny=4,x=2,y=3]{\framed[foregroundstyle=\testfont,width=.3\textwidth,align={normal,tolerant,hz}] {\showfontexpansion\samplefile{ward}}}}} {\tttf{hz}} + \stopcombination +\stopplacefigure + +\stopsection + +\startsection[title=Looseness] + +The \type {\looseness} parameter can be used to let the par builder add more +lines, but that condition is only met when the demand is reasonable. So we need +stretch and often also tolerance to achieve it. + +\starttyping +\looseness=1 ... text ... \par +\stoptyping + +This setting is reset afterwards. Because \type {framed} does some grouping deep down, +we need either to use it in there like this: + +\starttyping +\framed + [align={normal,verytolerant,stretch},strut=no] + {\looseness1 ... \par} +\stoptyping + +which is somewhat clumsy, or we can do: + +\starttyping +\framed + [align={normal,verytolerant,stretch,2*more}] + {...} +\stoptyping + +This is demonstrated in \in {figure} [fig:looseness]. + +\startplacefigure[reference=fig:looseness,title={Looseness in action.}] + \dontcomplain + \startcombination[location=top,nx=3,ny=1] + {\framed[foregroundstyle=small,align={normal,verytolerant,stretch}, width=.3\textwidth]{\samplefile{sapolsky}\unskip}} {} + {\framed[foregroundstyle=small,align={normal,verytolerant,stretch,1*more},width=.3\textwidth]{\samplefile{sapolsky}\unskip}} {\type {1*more}} + {\framed[foregroundstyle=small,align={normal,verytolerant,stretch,2*more},width=.3\textwidth]{\samplefile{sapolsky}\unskip}} {\type {2*more}} + \stopcombination +\stopplacefigure + +\stopsection + +\stopchapter + +\stopcomponent + diff --git a/doc/context/sources/general/manuals/spacing/spacing-style.tex b/doc/context/sources/general/manuals/spacing/spacing-style.tex index cf0bae7bf..5514df729 100644 --- a/doc/context/sources/general/manuals/spacing/spacing-style.tex +++ b/doc/context/sources/general/manuals/spacing/spacing-style.tex @@ -1,5 +1,7 @@ \startenvironment spacing-style +\usemodule[abbreviations-words,typesetting] + \setupbodyfont [pagella] @@ -52,4 +54,11 @@ [style=\bfc, color=maincolor] +\setuphead + [subsubsection] + [style=bold, + color=maincolor, + before=\blank, + after=\blank] + \stopenvironment diff --git a/doc/context/sources/general/manuals/sql/sql-mkiv.tex b/doc/context/sources/general/manuals/sql/sql-mkiv.tex index dabb0a34f..4d2ecbc6e 100644 --- a/doc/context/sources/general/manuals/sql/sql-mkiv.tex +++ b/doc/context/sources/general/manuals/sql/sql-mkiv.tex @@ -527,7 +527,6 @@ loggers.save(db, { -- variant 2: flat table message = "whatever b" } ) - local result = loggers.collect(db, { start = { day = 1, @@ -576,7 +575,6 @@ In this example we typeset the (small) table): \ctxluabuffer - \stopsection \startsection[title=Colofon] diff --git a/doc/context/sources/general/manuals/start/en/ma-cb-en-heads.tex b/doc/context/sources/general/manuals/start/en/ma-cb-en-heads.tex index aa7e7b161..4eddcb9fd 100644 --- a/doc/context/sources/general/manuals/start/en/ma-cb-en-heads.tex +++ b/doc/context/sources/general/manuals/start/en/ma-cb-en-heads.tex @@ -33,12 +33,12 @@ These titles are created with the commands shown in \in{table}[tab:headers]: \HL \stoptable} -\shortsetup{chapter} -\shortsetup{section} -\shortsetup{subsection} -\shortsetup{title} -\shortsetup{subject} -\shortsetup{subsubject} +\shortsetup{startsection:instance:chapter} +\shortsetup{startsection:instance:section} +\shortsetup{startsection:instance:subsection} +\shortsetup{startsection:instance:title} +\shortsetup{startsection:instance:subject} +\shortsetup{startsection:instance:subsubject} These commands will produce a numbered or unnumbered title in a predefined fontsize and fonttype with some vertical spacing before and after the header. diff --git a/doc/context/sources/general/manuals/start/en/ma-cb-en.pdf b/doc/context/sources/general/manuals/start/en/ma-cb-en.pdf Binary files differindex 6ad164eb0..497cecfe0 100644 --- a/doc/context/sources/general/manuals/start/en/ma-cb-en.pdf +++ b/doc/context/sources/general/manuals/start/en/ma-cb-en.pdf diff --git a/doc/context/sources/general/manuals/start/en/ma-cb-en.tex b/doc/context/sources/general/manuals/start/en/ma-cb-en.tex index 2e0b283af..2e7f7eac4 100644 --- a/doc/context/sources/general/manuals/start/en/ma-cb-en.tex +++ b/doc/context/sources/general/manuals/start/en/ma-cb-en.tex @@ -6,13 +6,10 @@ \project ma-cb -% \disabledirectives[otf.kernruns] -% \disabledirectives[otf.discruns] -% \disabledirectives[otf.compruns] - \startdocument - [title={\ConTeXt\ Mark IV\crlf an excursion}, - subtitle={English\crlf version}, + [title={\ConTeXt\ Mark IV}, + subtitle={an excursion}, + version={English}, author={Ton Otten\crlf PRAGMA ADE}] \startfrontmatter diff --git a/doc/context/sources/general/manuals/start/ma-cb-style.tex b/doc/context/sources/general/manuals/start/ma-cb-style.tex index 294e4a5cc..d4f7d7c5f 100644 --- a/doc/context/sources/general/manuals/start/ma-cb-style.tex +++ b/doc/context/sources/general/manuals/start/ma-cb-style.tex @@ -11,7 +11,9 @@ % Setups are kind of special. -\loadsetups[cont-\currentmainlanguage.xml] +% \loadsetups[cont-\currentmainlanguage.xml] + +\loadsetups[i-context] \setupsetup [\c!criterium=\v!used] @@ -254,59 +256,26 @@ \newbox\CoverBackgroundBox % reuse saves .8 sec, could be an object! +\definebodyfontenvironment[1.9pt] + +\defineframed + [CoverFramed] + [%\c!foregroundstyle=\CoverFont, + \c!background=basic-shape-dark, + \c!backgroundoffset=1pt, + \c!rulethickness=2pt, + \c!frame=\v!off] + \starttexdefinition unexpanded ShowSetupOnCover #n #tag #xmlroot \dontleavehmode - \framed [ - \c!background=basic-shape-light, - \c!backgroundoffset=5pt, - \c!rulethickness=2pt, - \c!frame=\v!off - ] { - \xmlsetup{#xmlroot}{xml:setups:assemblename} - \tttf - \texescape\currentSETUPfullname + \CoverFramed { + \tttf\showsetupnameonly{#1}{#2}{#3} } - \hskip1.25em plus 1em minus 1em\relax + \kern\zeropoint + \hskip1em plus 1em minus .25em\relax \stoptexdefinition -% \startsetups coverbackground -% -% \ifvoid\CoverBackgroundBox -% -% \global\setbox\CoverBackgroundBox=\vbox to \paperheight \bgroup -% \hsize\paperwidth -% \emergencystretch3em -% \parfillskip0pt -% \switchtobodyfont -% [6pt] -% \baselineskip 0pt plus 1pt minus 1pt -% \setupsorting -% [texcommand] -% [\c!command=\ShowSetupOnCover, -% \c!criterium=\v!all] -% \beginofshapebox -% \leftskip3pt -% \rightskip3pt -% \placelistofsorts -% [texcommand] -% \endofshapebox -% \doreshapebox -% {\box\shapebox} -% {\penalty\shapepenalty} -% {\kern\shapekern} -% {\vfil} -% \kern3pt -% \vfilneg -% \flushshapebox -% \vfilneg -% \kern3pt -% \egroup -% -% \fi -% -% \copy\CoverBackgroundBox -% -% \stopsetups +\definecolor[CoverTransparency][a=1,t=.5] \startsetups coverbackground @@ -316,14 +285,18 @@ \startnicelyfilledbox [\c!width=\paperwidth, \c!height=\paperheight, - \c!offset=\exheight, +% \c!offset=\exheight, +% \c!offset=\emwidth, + \c!offset=\zeropoint, \c!strut=\v!no] \switchtobodyfont - [6pt] + [1.9pt] + \starttransparent[CoverTransparency] \placelistofsorts [texcommand] [\c!command=\ShowSetupOnCover, - \c!criterium=\v!all] + \c!criterium=\v!all]% used + \stoptransparent \stopnicelyfilledbox \fi @@ -362,14 +335,16 @@ \hbox to \hsize \bgroup \hss - \definedfont[SansBold*default at 40pt] + %\definedfont[SansBold*default at 40pt] + \definedfont[Bold*default at 40pt] \framed [\c!background=basic-shape-dark, \c!frame=\v!off, - \c!rulethickness=15pt, + \c!rulethickness=30pt, \c!align=\v!middle, \c!offset=40pt] - {\documentvariable{title}} + {\dontleavehmode\hbox{\documentvariable{title}}\par + \dontleavehmode\hbox{\documentvariable{subtitle}}} \egroup \vfill @@ -377,14 +352,15 @@ \doifsomething {\documentvariable{subtitle}} { \hbox to \hsize \bgroup - \definedfont[SansBold*default at 14pt] + %\definedfont[SansBold*default at 20pt] + \definedfont[Bold*default at 20pt] \framed [\c!background=basic-shape-dark, \c!frame=\v!off, - \c!rulethickness=10pt, + \c!rulethickness=15pt, \c!align=\v!middle, \c!offset=20pt] - {\documentvariable{subtitle}} + {\documentvariable{version}} \hss \egroup @@ -392,11 +368,12 @@ \hbox to \hsize \bgroup \hss - \definedfont[SansBold*default at 20pt] + %\definedfont[SansBold*default at 24pt] + \definedfont[Bold*default at 24pt] \framed [\c!background=basic-shape-dark, \c!frame=\v!off, - \c!rulethickness=12.5pt, + \c!rulethickness=18pt, \c!align=\v!middle, \c!offset=35pt] {\documentvariable{author}} @@ -547,9 +524,16 @@ \switchtobodyfont[8pt] - \startmixedcolumns[documentcolumns] + % somehow \blank doesn't work here + + \setupframedtexts + [setuptext] + [\c!before={\vskip6pt}, + \c!after={\vskip6pt}] + + % \startmixedcolumns[documentcolumns] \placelistofsorts[texcommand] - \stopmixedcolumns + % \stopmixedcolumns \stop @@ -671,7 +655,7 @@ \setupregister [Command] [\c!indicator=\v!off, - c!before={\blank[\v!line]}] + \c!before={\blank[\v!line]}] \protect diff --git a/doc/context/sources/general/manuals/workflows/workflows-mkiv.tex b/doc/context/sources/general/manuals/workflows/workflows-mkiv.tex index c742b94e1..52070c49e 100644 --- a/doc/context/sources/general/manuals/workflows/workflows-mkiv.tex +++ b/doc/context/sources/general/manuals/workflows/workflows-mkiv.tex @@ -38,12 +38,14 @@ \stopfrontmatter \startbodymatter + \component workflows-running \component workflows-resources \component workflows-graphics \component workflows-suspects \component workflows-injectors \component workflows-xml \component workflows-setups + \component workflows-synctex \stopbodymatter \stopdocument diff --git a/doc/context/sources/general/manuals/workflows/workflows-running.tex b/doc/context/sources/general/manuals/workflows/workflows-running.tex new file mode 100644 index 000000000..6d3e9f5c4 --- /dev/null +++ b/doc/context/sources/general/manuals/workflows/workflows-running.tex @@ -0,0 +1,72 @@ +% language=uk + +\environment workflows-style + +\startcomponent workflows-running + +\startchapter[title={Running}] + +\startsection[title={Errors}] + +A \CONTEXT\ runs normally spits out quite some information to the console. In +fact, even more information can go to the log file. It makes sense to have a look +at the end of the log file occasionally because there you can find information +about the (file) structure loaded, modules, issues with references and|/|or +fonts, etc. + +One problem with the terminal is that you can miss an issue easily, but there is +a way out of this: + +\starttyping +\enabledirectives[logs.errors] +\stoptyping + +The command line argument \type {--errors} has the same consequence. If you want +to quit in an error, you can say for instance: + +\starttyping +\enabledirectives[logs.errors=missing characters] +\stoptyping + +If you run \CONTEXT\ with \type {--trackers} or \type {--directives} you get some +information about the possible extra tracing. It might be illustrative to run a +file with: + +\starttyping +\enabletrackers[*] +\stoptyping + +There are all kind of trackers and directives and you can get a list with: + +\starttyping +context --trackers --directives +\stoptyping + +An example is: + +\starttyping +\enabletrackers[fonts.missing=replace] +\stoptyping + +or just: + +\starttyping +\enabletrackers[fonts.missing] +\stoptyping + + +\stopsection + +\startsection[title={Silent}] + +The \type {--silent} options blocks most message. You can also pass a list (or +pattern) of categories to silence. The \type {--noconsole} option only disables +logging to the console. The error reporting mentioned in the previous section +will never be silenced. + +\stopsection + +\stopchapter + +\stopcomponent + diff --git a/doc/context/sources/general/manuals/workflows/workflows-synctex.tex b/doc/context/sources/general/manuals/workflows/workflows-synctex.tex new file mode 100644 index 000000000..8f1fac632 --- /dev/null +++ b/doc/context/sources/general/manuals/workflows/workflows-synctex.tex @@ -0,0 +1,207 @@ +% language=uk + +\environment workflows-style + +\startcomponent workflows-xml + +\startchapter[title=\SYNCTEX] + +\startsection[title=Introduction] + +Some users like the \SYNCTEX\ feature that is built in the \TEX\ engines. +Personally I never use it because it doesn't work well with the kind of documents +I maintain. If you have one document source, and don't shuffle around (reuse) +text too much it probably works out okay but that is not our practice. Here I +will describe how you can enable a more \CONTEXT\ specific \SYNCTEX\ support so +that aware \PDF\ viewers can bring you back to the source. + +\stopsection + +\startsection[title=What we want] + +The \SYNCTEX\ method roughly works as follows. Internally \TEX\ constricts linked +lists of glyphs, kerns, glue, boxes, rules etc. These elements are called nodes. +Some nodes carry information about the file and line where they were created. In +the backend this information gets somehow translated in a (sort of) verbose tree +that describes the makeup in terms of boxes, glue and kerns. From that +information the \SYNCTEX\ parser library, hooked into a \PDF\ viewer, can go back +from a position on the screen to a line in a file. One would expect this to be a +relative simple rectangle based model, but as far as I can see it's way more +complex than that. There are some comments that \CONTEXT\ is not supported well +because it has a layered page model, which indicates that there are some +assumptions about how macro packages are supposed to work. Also the used +heuristics not only involve some specific spot (location) but also involve the +corners and edges. It is therefore not so much a (simple) generic system but a +mechanism geared for a macro package like \LATEX. + +Because we have a couple of users who need to edit complex sets of documents, +coded in \TEX\ or \XML, I decided to come up with a variant that doesn't use the +\SYNCTEX\ machinery but manipulates the few \SYNCTEX\ fields directly \footnote {This +is something that in my opinion should have been possible right from the start +but it's too late now to change the system and it would not be used beyond +\CONTEXT\ anyway.} and eventually outputs a straightforward file for the editor. +Of course we need to follow some rules so that the editor can deal with it. It +took a bit of trial and error to get the right information in the support file +needed by the viewer but we got there. + +The prerequisites of a decent \CONTEXT\ \quotation {click on preview and goto +editor} are the following: + +\startitemize + +\startitem + It only makes sense to click on text in the text flow. Headers and footers + are often generated from structure, and special typographic elements can + originate in macros hooked into commands instead of in the source. +\stopitem + +\startitem + Users should not be able to reach environments (styles) and other files + loaded from the (normally read|-|only) \TEX\ tree, like modules. We don't + want accidental changes in such files. +\stopitem + +\startitem + We not only have \TEX\ files but also \XML\ files and these can normally + flush in rather arbitrary ways. Although the concept of lines is sort of + lost in such a file, there is still a relation between lines and the snippets + that make out the content of an \XML\ node. +\stopitem + +\startitem + In the case of \XML\ files the overhead related to preserving line + numbers should be minimal and have no impact on loading and memory when + these features are not used. +\stopitem + +\startitem + The overhead in terms of an auxiliary file size and complexity as well + as producing that file should be minimal. It should be easy to turn on and + off these features. (I'd never turn them on by default.) +\stopitem + +\stopitemize + +It is unavoidable that we get more run time but I assume that for the average user +that is no big deal. It pays off when you have a workflow when a book (or even a +chapter in a book) is generated from hundreds of small \XML\ files. There is no +overhead when \SYNCTEX\ is not used. + +In \CONTEXT\ we don't use the built|-|in \SYNCTEX\ features, that is: we let +filename and line numbers be set but often these are overloaded explicitly. The +output file is not compressed and constructed by \CONTEXT. There is no benefit in +compression and the files are probably smaller than default \SYNCTEX\ anyway. + +\stopsection + +\startsection[title=Commands] + +Although you can enable this mechanism with directives it makes sense to do it +using the following command. + +\starttyping +\setupsynctex[state=start] +\stoptyping + +The advantage of using an explicit command instead of some command line option is +that in an editor it's easier to disable this trickery. Commenting that line will +speed up processing when needed. This command can also be given in an environment +(style). On the command line you can say + +\starttyping +context --synctex somefile.tex +\stoptyping + +A third method is to put this at the top of your file: + +\starttyping +% synctex=yes +\stoptyping + +Often an \XML\ files is very structured and although probably the main body of +text is flushed as a stream, specific elements can be flushed out of order. In +educational documents flushing for instance answers to exercises can happen out of +order. In that case we still need to make sure that we go to the right spot in +the file. It will never be 100\% perfect but it's better than nothing. The +above command will also enable \XML\ support. + +If you don't want a file to be accessed, you can block it: + +\starttyping +\blocksynctexfile[foo.tex] +\stoptyping + +Of course you need to configure the viewer to respond to the request for +editing. In Sumatra combined with SciTE the magic command is: + +\starttyping +c:\data\system\scite\wscite\scite.exe "%f" "-goto:%l" +\stoptyping + +Such a command is independent of the macro package so you can just consult the +manual or help info that comes with a viewer, given that it supports this linking +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: + +\starttyping +\enabletrackers[system.synctex.visualize] +\enabletrackers[system.synctex.visualize=real] +\stoptyping + +The following tracker outputs some status information about \XML\ flushing. Such +trackers only make sense for developers. + +\starttyping +\enabletrackers[system.synctex.xml] +\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 + +\startsection[title=Warning] + +Don't turn on this feature when you don't need it. This is one of those mechanism +that hits performance badly. + +Depending on needs the functionality can be improved and|/|or extended. Of course +you can always use the traditional \SYNCTEX\ method but don't expect it to behave +as described here. + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/xml/xml-mkiv.tex b/doc/context/sources/general/manuals/xml/xml-mkiv.tex index 80d51532f..0f9c74662 100644 --- a/doc/context/sources/general/manuals/xml/xml-mkiv.tex +++ b/doc/context/sources/general/manuals/xml/xml-mkiv.tex @@ -288,7 +288,6 @@ code can be used as starting point: \starttyping \startxmlsetups xml:demo:base - \xmlsetsetup{#1}{*}{-} \xmlsetsetup{#1}{document|section|p}{xml:demo:*} \stopxmlsetups @@ -1275,6 +1274,15 @@ The following commands return strings. Normally these are used in tests. returns the last attribute found (this avoids a lookup) \stopxmlcmd +\startxmlcmd {\cmdbasicsetup{xmlsetatt}} + set the value of attribute \cmdinternal {cd:name} +\stopxmlcmd + +\startxmlcmd {\cmdbasicsetup{xmlsetattribute}} + set the value of attribute \cmdinternal {cd:name} for each match of \cmdinternal + {cd:lpath} +\stopxmlcmd + \stopsection \startsection[title={manipulation}] @@ -1610,6 +1618,80 @@ mechanism for other purposes as well. \stopsection +\startsection[title={Parameters}] + +\startbuffer[test] +<something whatever="alpha"> + <what> + beta + </what> +</something> +\stopbuffer + +\startbuffer +\startxmlsetups xml:mysetups + \xmlsetsetup{\xmldocument}{*}{xml:*} +\stopxmlsetups + +\xmlregistersetup{xml:mysetups} + +\startxmlsetups xml:something + parameter : \xmlpar {#1}{whatever}\par + attribute : \xmlatt {#1}{whatever}\par + text : \xmlfirst {#1}{what} \par + \xmlsetpar{#1}{whatever}{gamma} + parameter : \xmlpar {#1}{whatever}\par + \xmlflush{#1} +\stopxmlsetups + +\startxmlsetups xml:what + what: \xmlflush{#1}\par + parameter : \xmlparam{#1}{..}{whatever}\par +\stopxmlsetups + +\xmlprocessbuffer{main}{test}{} +\stopbuffer + +Say that we have this \XML\ blob: + +\typebuffer[test] + +With: + +\typebuffer + +we get: + +\getbuffer + +Parameters are stored with a node. + +\startxmlcmd {\cmdbasicsetup{xmlpar}} + returns the value of parameter \cmdinternal {cd:name} or empty if no such + parameter exists +\stopxmlcmd + +\startxmlcmd {\cmdbasicsetup{xmlparam}} + finds a first match for \cmdinternal {cd:lpath} at \cmdinternal {cd:node} and + returns the value of parameter \cmdinternal {cd:name} or empty if no such + parameter exists +\stopxmlcmd + +\startxmlcmd {\cmdbasicsetup{xmllastpar}} + returns the last parameter found (this avoids a lookup) +\stopxmlcmd + +\startxmlcmd {\cmdbasicsetup{xmlsetpar}} + set the value of parameter \cmdinternal {cd:name} +\stopxmlcmd + +\startxmlcmd {\cmdbasicsetup{xmlsetparam}} + set the value of parameter \cmdinternal {cd:name} for each match of \cmdinternal + {cd:lpath} +\stopxmlcmd + +\stopsection + \stopchapter \startchapter[title={Expressions and filters}] @@ -1779,7 +1861,6 @@ In addition, \type {=} equals \type {==} and \type {!=} is the same as \type \stopsection - \startsection[title={css selectors}] \startbuffer[selector-001] @@ -1838,7 +1919,7 @@ supported too. In fact, you can combine both methods. Depending on what you select, the \CSS\ one can be a little bit faster too. It has the advantage that one can select more in one go but at the same time looks a bit less attractive. This method was added just to show that it can be done but might be useful too. A -selector is gogen between curly braces (after all \CSS\ uses them and they have no +selector is given between curly braces (after all \CSS\ uses them and they have no function yet in the parser. \starttyping diff --git a/doc/context/sources/general/manuals/xtables/xtables-mkiv.tex b/doc/context/sources/general/manuals/xtables/xtables-mkiv.tex index d4316b479..827ad3fcc 100644 --- a/doc/context/sources/general/manuals/xtables/xtables-mkiv.tex +++ b/doc/context/sources/general/manuals/xtables/xtables-mkiv.tex @@ -1013,14 +1013,240 @@ similar. \stopsection -\startsection[title={Colofon}] +\startsection[title={Alignment}] -\starttabulate[|B|p|] -\NC author \NC \getvariable{document}{author}, \getvariable{document}{affiliation}, \getvariable{document}{location} \NC \NR -\NC version \NC \currentdate \NC \NR -\NC website \NC \getvariable{document}{website} \endash\ \getvariable{document}{support} \NC \NR -\NC copyright \NC \symbol[cc][cc-by-sa-nc] \NC \NR -\stoptabulate +\enabletrackers[typesetters.characteralign] + +There is limited support for aligning numbers in columns. When you flush right +and have a fixed number of digits it's not a problem, but otherwise it might come +in handy. In any case, you might want to use the following as part of your style: + +\starttyping +\addfeature[tabularnumbers] +\stoptyping + +\start \addfeature[tabularnumbers] + +The basic alignment mechanism can be demonstrated with the following examples: + +\startbuffer +\startcharacteralign[,] % or [character={,}] + \checkcharacteralign{123.456,78} \par + \checkcharacteralign {456} \par + \checkcharacteralign {23.456} \par + \checkcharacteralign {78,9} \par + \checkcharacteralign {78} \par +\stopcharacteralign +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\startcharacteralign[leftsample=123.456,rightsample=00,character={,}] + \checkcharacteralign{123.456,78} \par + \checkcharacteralign {456} \par + \checkcharacteralign {23.456} \par + \checkcharacteralign {78,9} \par + \checkcharacteralign {78} \par +\stopcharacteralign +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\startcharacteralign[leftwidth=100pt,rightwidth=30pt] + \checkcharacteralign{123.456,78} \par + \checkcharacteralign {456} \par + \checkcharacteralign {23.456} \par + \checkcharacteralign {78,9} \par + \checkcharacteralign {78} \par +\stopcharacteralign +\stopbuffer + +\typebuffer \getbuffer + +Samples win over width settings. When no sample or width is given a two pass +analyzer kicks in. This is not the case in the following examples. + +\startbuffer +\startxtable + [align={flushright,lohi}, + aligncharacter=yes, + alignmentleftsample=100, + alignmentrightsample=00, + alignmentcharacter={.}] + \startxrow \startxcell 1 \stopxcell \stopxrow + \startxrow \startxcell 1.1 \stopxcell \stopxrow + \startxrow \startxcell 11.11 \stopxcell \stopxrow +\stopxtable +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\startxtable + [align={flushright,lohi}, + aligncharacter=yes, + alignmentleftsample=000.000, + alignmentrightsample=00, + alignmentcharacter={,}] + \startxrow \startxcell 123.456,78 x \stopxcell \stopxrow + \startxrow \startxcell 456 x \stopxcell \stopxrow + \startxrow \startxcell 23.456 x \stopxcell \stopxrow + \startxrow \startxcell 78,9 x \stopxcell \stopxrow + \startxrow \startxcell 78 x \stopxcell \stopxrow +\stopxtable +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\startxtable[align={flushright,lohi}] + \startxrow + \startxcell + [aligncharacter=yes, + alignmentcharacter={,}, + alignmentleftsample=000.000, + alignmentrightsample=00] + 123.456,78 + \stopxcell + \stopxrow + \startxrow + \startxcell + [aligncharacter=yes] + 456 + \stopxcell + \stopxrow + \startxrow + \startxcell + [aligncharacter=yes] + 23.456 + \stopxcell + \stopxrow + \startxrow + \startxcell + [aligncharacter=yes] + 78,9 + \stopxcell + \stopxrow + \startxrow + \startxcell + [aligncharacter=yes] + 78 + \stopxcell + \stopxrow +\stopxtable +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\setupxtable + [aligned] + [aligncharacter=yes, + alignmentleftsample=000.000, + alignmentrightsample=00, + alignmentcharacter={,}] + +\startxtable[align={flushright,lohi}] + \startxrow \startxcell[aligned] 123.456,78 \stopxcell \stopxrow + \startxrow \startxcell[aligned] 456 \stopxcell \stopxrow + \startxrow \startxcell[aligned] 23.456 \stopxcell \stopxrow + \startxrow \startxcell[aligned] 78,9 \stopxcell \stopxrow + \startxrow \startxcell[aligned] 78 \stopxcell \stopxrow +\stopxtable +\stopbuffer + +\typebuffer \getbuffer + +\stop + +\disabletrackers[typesetters.characteralign] + +\stopsection + +\startsection[title={Depth}] + +Take the following example. Here we have some text that, when typeset narrow, +will have a last line with no (or, depending on the font, hardly) depth. + +\startbuffer +\startxtable[frame=on] + + \startxrow + \startxcell[width=3cm] + here filled with some words to force a rather long line + \stopxcell + \stopxrow + + \startxrow + \startxcell + here filled with some words to force a rather long line + \stopxcell + \stopxrow + + \startxrow + \startxcell + here filled with some words to force a rather long line + + \stopxcell + \stopxrow + +\stopxtable +\stopbuffer + +\typebuffer + +The problem is that \TEX\ doesn't add depth that that last line and adding it +automatically can be done in grid mode but one doesn't always want that. Some mechanisms +add so called struts automatically. As the table cells are framed boxes indeed that +happens here, unless you add an empty line (as in the last row). When you embed + +\startlinecorrection[blank] {\showstruts \showboxes \getbuffer} \stoplinecorrection + +\startbuffer +\startxtable[frame=on] + + \startxrow + \startxcell[width=3cm] + \startitemize[packed] + \startitem + here filled with some words to force a rather long line + \stopitem + \stopitemize + \stopxcell + \stopxrow + + \startxrow + \startxcell + \startitemize[packed] + \startitem + here filled with some words to force a rather long line + \stopitem + \stopitemize + \stopxcell + \stopxrow + + \startxrow + \startxcell + \startitemize[packed] + \startitem + here filled with some words to force a rather long line + + \stopitem + \stopitemize + \stopxcell + \stopxrow + +\stopxtable +\stopbuffer + +\typebuffer + +Don't count on all mechanisms used inside a cell to provide this but with itemize +you're lucky. + +\startlinecorrection[blank] {\showstruts \showboxes \getbuffer} \stoplinecorrection \stopsection @@ -1234,6 +1460,78 @@ in the distribution. \typebuffer[tight] \start \getbuffer[tight,demo] \stop \typebuffer[normal] \start \getbuffer[normal,demo] \stop +\page + +\startbuffer +\startxtable[align={middle,lohi}] + \startxrow + \startxcell[ny=3] (1,3) \stopxcell + \startxcell (1,1) \stopxcell + \startxcell (1,1) \stopxcell + \stopxrow + \startxrow + \startxcell (1,1) \stopxcell + \startxcell (1,1) \stopxcell + \stopxrow + \startxrow + \startxcell[nx=2] (2,1) \stopxcell + \stopxrow +\stopxtable +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\startxtable[align={middle,lohi}] + \startxrow + \startxcell[ny=2] (1,2) \stopxcell + \startxcell (1,1) \stopxcell + \startxcell (1,1) \stopxcell + \stopxrow + \startxrow + \startxcell (1,1) \stopxcell + \startxcell (1,1) \stopxcell + \stopxrow + \startxrow + \startxcell[nx=2] (2,1) \stopxcell + \stopxrow +\stopxtable +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\startxtable[align={middle,lohi}] + \startxrow + \startxcell[ny=2] (1,2) \stopxcell + \startxcell (1,1) \stopxcell + \startxcell (1,1) \stopxcell + \startxcell (1,1) \stopxcell + \stopxrow + \startxrow + \startxcell[nx=3] (3,1) \stopxcell + \stopxrow + \startxrow + \startxcell[nx=4] (4,1) \stopxcell + \stopxrow +\stopxtable +\stopbuffer + +\typebuffer \getbuffer + +\page + % \ruledhbox{\getbuffer[normal,demo]} +\startsection[title={Colofon}] + +\starttabulate[|B|p|] +\NC author \NC \getvariable{document}{author}, \getvariable{document}{affiliation}, \getvariable{document}{location} \NC \NR +\NC version \NC \currentdate \NC \NR +\NC website \NC \getvariable{document}{website} \endash\ \getvariable{document}{support} \NC \NR +\NC copyright \NC \symbol[cc][cc-by-sa-nc] \NC \NR +\stoptabulate + +\stopsection + \stopdocument |
