diff options
Diffstat (limited to 'doc')
33 files changed, 3083 insertions, 2 deletions
diff --git a/doc/context/documents/general/fonts/fonts-mkiv.pdf b/doc/context/documents/general/fonts/fonts-mkiv.pdf Binary files differindex c96d8cda2..d388df3e9 100644 --- a/doc/context/documents/general/fonts/fonts-mkiv.pdf +++ b/doc/context/documents/general/fonts/fonts-mkiv.pdf diff --git a/doc/context/documents/general/manuals/colors-mkiv.pdf b/doc/context/documents/general/manuals/colors-mkiv.pdf Binary files differnew file mode 100644 index 000000000..f211288d9 --- /dev/null +++ b/doc/context/documents/general/manuals/colors-mkiv.pdf diff --git a/doc/context/documents/general/manuals/columnsets.pdf b/doc/context/documents/general/manuals/columnsets.pdf Binary files differindex 0d4e862f1..32a7f8b06 100644 --- a/doc/context/documents/general/manuals/columnsets.pdf +++ b/doc/context/documents/general/manuals/columnsets.pdf diff --git a/doc/context/documents/general/manuals/luatex.pdf b/doc/context/documents/general/manuals/luatex.pdf Binary files differindex 63f06d4ba..e06e1d873 100644 --- a/doc/context/documents/general/manuals/luatex.pdf +++ b/doc/context/documents/general/manuals/luatex.pdf diff --git a/doc/context/documents/general/manuals/rules-mkiv.pdf b/doc/context/documents/general/manuals/rules-mkiv.pdf Binary files differindex ff2155273..e3f061e24 100644 --- a/doc/context/documents/general/manuals/rules-mkiv.pdf +++ b/doc/context/documents/general/manuals/rules-mkiv.pdf diff --git a/doc/context/documents/general/manuals/spreadsheets-mkiv.pdf b/doc/context/documents/general/manuals/spreadsheets-mkiv.pdf Binary files differnew file mode 100644 index 000000000..d8709f169 --- /dev/null +++ b/doc/context/documents/general/manuals/spreadsheets-mkiv.pdf diff --git a/doc/context/documents/general/manuals/steps-mkiv.pdf b/doc/context/documents/general/manuals/steps-mkiv.pdf Binary files differindex fabdff6b2..f39b7be1b 100644 --- a/doc/context/documents/general/manuals/steps-mkiv.pdf +++ b/doc/context/documents/general/manuals/steps-mkiv.pdf diff --git a/doc/context/documents/general/manuals/workflows-mkiv.pdf b/doc/context/documents/general/manuals/workflows-mkiv.pdf Binary files differindex 95a8809a8..cbbec0a5a 100644 --- a/doc/context/documents/general/manuals/workflows-mkiv.pdf +++ b/doc/context/documents/general/manuals/workflows-mkiv.pdf diff --git a/doc/context/documents/general/qrcs/setup-cs.pdf b/doc/context/documents/general/qrcs/setup-cs.pdf Binary files differnew file mode 100644 index 000000000..164adb035 --- /dev/null +++ b/doc/context/documents/general/qrcs/setup-cs.pdf diff --git a/doc/context/documents/general/qrcs/setup-de.pdf b/doc/context/documents/general/qrcs/setup-de.pdf Binary files differnew file mode 100644 index 000000000..41365c799 --- /dev/null +++ b/doc/context/documents/general/qrcs/setup-de.pdf diff --git a/doc/context/documents/general/qrcs/setup-en.pdf b/doc/context/documents/general/qrcs/setup-en.pdf Binary files differnew file mode 100644 index 000000000..6caf60cc2 --- /dev/null +++ b/doc/context/documents/general/qrcs/setup-en.pdf diff --git a/doc/context/documents/general/qrcs/setup-fr.pdf b/doc/context/documents/general/qrcs/setup-fr.pdf Binary files differnew file mode 100644 index 000000000..01acd8a5a --- /dev/null +++ b/doc/context/documents/general/qrcs/setup-fr.pdf diff --git a/doc/context/documents/general/qrcs/setup-it.pdf b/doc/context/documents/general/qrcs/setup-it.pdf Binary files differnew file mode 100644 index 000000000..6210c3d63 --- /dev/null +++ b/doc/context/documents/general/qrcs/setup-it.pdf diff --git a/doc/context/documents/general/qrcs/setup-nl.pdf b/doc/context/documents/general/qrcs/setup-nl.pdf Binary files differnew file mode 100644 index 000000000..cb2f502b9 --- /dev/null +++ b/doc/context/documents/general/qrcs/setup-nl.pdf diff --git a/doc/context/documents/general/qrcs/setup-ro.pdf b/doc/context/documents/general/qrcs/setup-ro.pdf Binary files differnew file mode 100644 index 000000000..06b79b283 --- /dev/null +++ b/doc/context/documents/general/qrcs/setup-ro.pdf diff --git a/doc/context/general/qrcs/setup-cs.pdf b/doc/context/general/qrcs/setup-cs.pdf Binary files differdeleted file mode 100644 index 4349fe525..000000000 --- a/doc/context/general/qrcs/setup-cs.pdf +++ /dev/null diff --git a/doc/context/general/qrcs/setup-de.pdf b/doc/context/general/qrcs/setup-de.pdf Binary files differdeleted file mode 100644 index 082e3c2c9..000000000 --- a/doc/context/general/qrcs/setup-de.pdf +++ /dev/null diff --git a/doc/context/general/qrcs/setup-en.pdf b/doc/context/general/qrcs/setup-en.pdf Binary files differdeleted file mode 100644 index 34f77b0b3..000000000 --- a/doc/context/general/qrcs/setup-en.pdf +++ /dev/null diff --git a/doc/context/general/qrcs/setup-fr.pdf b/doc/context/general/qrcs/setup-fr.pdf Binary files differdeleted file mode 100644 index ad1c7d8aa..000000000 --- a/doc/context/general/qrcs/setup-fr.pdf +++ /dev/null diff --git a/doc/context/general/qrcs/setup-it.pdf b/doc/context/general/qrcs/setup-it.pdf Binary files differdeleted file mode 100644 index e0e0e71f9..000000000 --- a/doc/context/general/qrcs/setup-it.pdf +++ /dev/null diff --git a/doc/context/general/qrcs/setup-nl.pdf b/doc/context/general/qrcs/setup-nl.pdf Binary files differdeleted file mode 100644 index cd7df2807..000000000 --- a/doc/context/general/qrcs/setup-nl.pdf +++ /dev/null diff --git a/doc/context/general/qrcs/setup-ro.pdf b/doc/context/general/qrcs/setup-ro.pdf Binary files differdeleted file mode 100644 index 64bee894d..000000000 --- a/doc/context/general/qrcs/setup-ro.pdf +++ /dev/null diff --git a/doc/context/sources/general/fonts/fonts/fonts-extensions.tex b/doc/context/sources/general/fonts/fonts/fonts-extensions.tex index 2742b1ce0..89257f1f5 100644 --- a/doc/context/sources/general/fonts/fonts/fonts-extensions.tex +++ b/doc/context/sources/general/fonts/fonts/fonts-extensions.tex @@ -1233,6 +1233,44 @@ command: \stopsection +\startsection[title=Extra font kerns] + +Fonts are processed independent of each other. Sometimes that is unfortunate for +kerning, although in practice it won't happen that often. We can enable an +additional kerning mechanism to deal with these cases. The \type +{\setextrafontkerns} command takes one argument between square brackets. The +effect can be seen below: + +\startbuffer + VA {\smallcaps va} V{\smallcaps a} + VA {\bf VA} V{\bf A} {\bf V}A + V{\it A} +\stopbuffer + +\starttabulate[|Tl|l|p|] +\HL +\BC key \BC result \BC logic \NC \NR +\HL +\NC no kerns \NC \showfontkerns\setextrafontkerns[reset]\subff{f:kern}\inlinebuffer \NC no kerns at all \NC \NR +\NC kerns \NC \showfontkerns\setextrafontkerns[reset]\inlinebuffer \NC kerns within a font (feature) run \NC \NR +\HL +\NC none \NC \showfontkerns\setextrafontkerns [none]\inlinebuffer \NC only extra kerns within fonts \NC \NR +\NC min \NC \showfontkerns\setextrafontkerns [min]\inlinebuffer \NC minimal kerns within and across fonts \NC \NR +\NC max \NC \showfontkerns\setextrafontkerns [max]\inlinebuffer \NC maximum kerns within and across fonts \NC \NR +\NC mixed \NC \showfontkerns\setextrafontkerns[mixed]\inlinebuffer \NC averaged kerns within and across fonts \NC \NR +\HL +\stoptabulate + +The content is defined as: + +\typebuffer + +This mechanism obeys grouping so you have complete control over where and when +it gets applied. The \type {\showfontkerns} command can be used to trace the +injection of (font) kerns. + +\stopsection + \startsection[title=Ligatures] For some Latin fonts ligature building is quite advanced, take Unifraktur. I have no diff --git a/doc/context/sources/general/fonts/fonts/fonts-features.tex b/doc/context/sources/general/fonts/fonts/fonts-features.tex index 79085c236..4514f209a 100644 --- a/doc/context/sources/general/fonts/fonts/fonts-features.tex +++ b/doc/context/sources/general/fonts/fonts/fonts-features.tex @@ -891,7 +891,7 @@ one never knows what to expect. How do we know what faces add up to the ligature {\emoji\Man \zwj \Woman \zwj \Girl \zwj \Boy} and how are we supposed to know that there should {\darkgray -\type {zwj}} in between? When we input four faces seoarated by zero width +\type {zwj}} in between? When we input four faces separated by zero width joiners, we get a four face symbol instead. The reason for having the joiners in between is probably to avoid unexpected ligatures. The sequence \type {man}, \type {woman}, \type {boy}, \type {boy} gives \type {family}: @@ -2531,6 +2531,49 @@ unlikely to show up in future versions of the Latin Modern fonts. \stopsection +\startsection[title=Discretionaries] + +% speed test: +% +% \edef\tufte{\cldloadfile{tufte}} +% \enabledirectives[otf.alwaysdisc] +% \testfeatureonce{100}{\setbox0\hbox{\tufte \smallcaps \tufte}}\elapsedtime\par +% \disabledirectives[otf.alwaysdisc] +% \testfeatureonce{100}{\setbox0\hbox{\tufte \smallcaps \tufte}}\elapsedtime\par + +\startbuffer +\definedfont[cambria*default] +12\discretionary + {3} {4} {5}% +67\par +12{\oldstyle\discretionary + {3} {4} {5}}% +67\par +12\discretionary + {3{\oldstyle3}} {{\oldstyle4}4} {5{\oldstyle5}5}% +67\par +\stopbuffer + +The font handler has to do some magick to get features working with and across +discretionaries. To some extend you can use font switches inside discretionaries +but for sure border cases are not dealt with. This works: + +\startlinecorrection[blank] +\startcombination[nx=4,ny=1,location=top] + {\framed[align=normal]{\enabledirectives [otf.alwaysdisc]\setupwhitespace[line]\getbuffer}} {1} + {\framed[align=normal]{\enabledirectives [otf.alwaysdisc]\hsize1mm\getbuffer}} {2} + {\framed[align=normal]{\disabledirectives[otf.alwaysdisc]\setupwhitespace[line]\getbuffer}} {3} + {\framed[align=normal]{\disabledirectives[otf.alwaysdisc]\hsize1mm\getbuffer}} {4} +\stopcombination +\stoplinecorrection + +The first two examples have \type {otf.alwaysdisk} enabled, the last two have it +disabled. + +\typebuffer + +\stopsection + \startsection[title=Some remarks] If you talk about features and fonts it is not difficult to end up speaking diff --git a/doc/context/sources/general/manuals/colors/colors-basics.tex b/doc/context/sources/general/manuals/colors/colors-basics.tex new file mode 100644 index 000000000..4d7822bd0 --- /dev/null +++ b/doc/context/sources/general/manuals/colors/colors-basics.tex @@ -0,0 +1,1204 @@ +% language=uk + +\startcomponent colors-basics + +\environment colors-environment + +\usemodule[setups-basics] \loadsetups[i-color] + +\startchapter[title=Basics][color=darkred] + +\startsection[title=Color models] + +When you work with displays, and most of us do, the dominant color model is \RGB. +As far as I know \CMYK\ electrowetting displays are still not in production and +even there the \CMYK\ seems to have made place for \RGB\ (at least in promotion +movies). This is strange since where \RGB\ is used in cases where colors are +radiated, \CMYK\ shows up in reflective situations (and epub readers are just +that). But \RGB\ and \CMYK\ being complementary is not the only difference: +\CMYK\ has an explicit black channel, and as a consequence you cannot go from one +to the other color space without loss. + +In print \CMYK\ is dominant but in order to get real good colors you can go with +spot colors. The ink is not mixed with others but applied in more or less +quantity. A mixture of spot colors and \CMYK\ is used too. You can combine spot +colors into a so called multitone color. Often spot colors have names (for +instance refering to Pantone) but they always have a specification in another +color space in order to be shown on screen. Think of \quotation {gold} being a +valid ink, but hard to render on screen, so some yellowish replacement is used +there when documents get prepared on screen. + +In \CONTEXT\ all these models are supported, either or not at the same time. In \MKII\ +you had to turn on color support explicitly, if only because of the impact of the +overhead on performance, but in \MKIV\ color is on by default. You can disable it +with: + +\starttyping +\setupcolors + [state=stop] +\stoptyping + +The three mentioned models are controlled by keys, and by default we have set: + +\starttyping +\setupcolors + [rgb=yes, + cmyk=yes, + spot=yes] +\stoptyping + +Spot colors and their combinations in multitone colors are controlled by the same +parameter. You can define colors in the \HSV\ color space but in the end these +become and behave like \RGB. + +\stopsection + +\startsection[title=Using color] + +Normally you will use colors grouped. Most environments accept a \type {color} +parameter (some have \type {textcolor} or similar longer names too). In a running +text you can use: + +\starttyping +\color[red]{This will show up red.} +\stoptyping + +or: + +\starttyping +\startcolor[red] + This will show up red. +\stopcolor +\stoptyping + +In case you don't want the grouping you can use: + +\starttyping +\directcolor[red] +\stoptyping + +You can even use: + +\starttyping +\colored[r=0.5]{also red} +\stoptyping + +In which case an anonymous color is used. An ungrouped variant of this is: + +\starttyping +\directcolored[r=0.5] +\stoptyping + +You will seldom use these direct variants, but they might come in handy when you +write macros yourself where extra grouping starts interfering. In fact, it often +makes sense to use a bit more abstraction: + +\startbuffer +\definehighlight + [important] + [color=red] + +First \highlight[important]{or} second \important {or} third. +\stopbuffer + +\typebuffer + +This gives: \inlinebuffer . + +\stopsection + +\startsection[title=Using \CMYK\ or \RGB] + +When you compare colors in different color spaces, you need to be aware of the +fact that when a black component is used in \CMYK, conversion to \RGB\ might give +the same results but going back from that to \CMYK\ will look different from the +original. Also, \CMYK\ colors are often tuned for specific paper. + +\startbuffer +\definecolor[demo:rgb:1][r=1.0,g=1.0] +\definecolor[demo:rgb:2][r=1.0,g=1.0,b=0.5] +\definecolor[demo:rgb:3][r=1.0,g=1.0,b=0.6] +\definecolor[demo:cmy:1][y=1.0] +\definecolor[demo:cmy:2][y=0.5] +\definecolor[demo:cmy:3][y=0.4] +\stopbuffer + +\typebuffer \getbuffer + +In these definitions we have no black component. In \in {figure} +[color:rgb:cmyk:1] we see how these colors translate to the other color spaces. + +\startbuffer[compare] +\startbuffer +\definemeasure[demo][(\textwidth-2em)/3] +\startcombination[3*2] + {\blackrule[width=\measure{demo},height=1cm,depth=0cm,color=demo:rgb:1]}{\infofont\colorcomponents{demo:rgb:1}} + {\blackrule[width=\measure{demo},height=1cm,depth=0cm,color=demo:rgb:2]}{\infofont\colorcomponents{demo:rgb:2}} + {\blackrule[width=\measure{demo},height=1cm,depth=0cm,color=demo:rgb:3]}{\infofont\colorcomponents{demo:rgb:3}} + {\blackrule[width=\measure{demo},height=1cm,depth=0cm,color=demo:cmy:1]}{\infofont\colorcomponents{demo:cmy:1}} + {\blackrule[width=\measure{demo},height=1cm,depth=0cm,color=demo:cmy:2]}{\infofont\colorcomponents{demo:cmy:2}} + {\blackrule[width=\measure{demo},height=1cm,depth=0cm,color=demo:cmy:3]}{\infofont\colorcomponents{demo:cmy:3}} +\stopcombination +\stopbuffer + +\startcombination[1*4] + {\setupcolors[rgb=yes,cmyk=yes]\getbuffer} {Both \RGB\ and \CMYK\ enabled} + {\setupcolors [rgb=no,cmyk=yes]\getbuffer} {Only \CMYK\ enabled.} + {\setupcolors [rgb=yes,cmyk=no]\getbuffer} {Only \RGB\ enabled.} + {\setupcolors [rgb=no,cmyk=no]\getbuffer} {Both \RGB\ and \CMYK\ disabled.} +\stopcombination +\stopbuffer + +\startplacefigure[location=page,reference=color:rgb:cmyk:1,title={What happens when we disable color spaces.}] + \getbuffer[compare] +\stopplacefigure + +\startbuffer +\definecolor[demo:rgb:1][r=0.5,g=0.6,b=0.7] +\definecolor[demo:rgb:2][r=0.5,g=0.6,b=0.7] +\definecolor[demo:rgb:3][r=0.5,g=0.6,b=0.7] +\definecolor[demo:cmy:1][c=0.5,m=0.4,y=0.3] +\definecolor[demo:cmy:2][c=0.4,m=0.3,y=0.2,k=0.1] +\definecolor[demo:cmy:3][c=0.3,m=0.2,y=0.1,k=0.2] +\stopbuffer + +\typebuffer \getbuffer + +When we define the colors as above, you can see a difference between the \RGB\ +and \CMYK\ values, but also between a black component versus black distributed +over the colorants. This is seen best in \in {figure} [color:rgb:cmyk:2] when we +compare the first and third colors alongside. In \in {figure} [color:rgb:cmyk:3] +you see the whole repertoire. + +\startplacefigure[reference=color:rgb:cmyk:2,title={The impact of black on a \CMYK\ color.}] +\startMPcode + fill fullsquare xyscaled (TextWidth,25mm) withcolor \MPcolor{demo:cmy:3} ; + fill fullsquare xyscaled (TextWidth,20mm) withcolor \MPcolor{demo:cmy:1} ; + fill fullsquare xyscaled (TextWidth,10mm) withcolor \MPcolor{demo:cmy:3} ; + fill fullsquare xyscaled (TextWidth, 5mm) withcolor \MPcolor{demo:cmy:1} ; +\stopMPcode +\stopplacefigure + +\startplacefigure[reference=color:rgb:cmyk:3,title={What happens when we disable color spaces (black component).}] + \getbuffer[compare] +\stopplacefigure + +\stopsection + +\startsection[title=Conversion] + +A conversion to gray happens when \RGB\ and \CMYK\ are both disabled. The following +setting forces conversion. It disables both \RGB\ and \CMYK: + +\starttyping +\setupcolors + [conversion=always] +\stoptyping + +The default setting is \type {yes} which means that colors will be reduced to gray in +the backend. This is an optimization which can result in slightly smaller output: + +\starttabulate[|l|c|l|] +\NC \NC \bf \# \NC \bf \PDF\ sequence \NC \NR +\NC \bf cmyk \NC 23 \NC \tttf 0 0 0 0.5 k 0 0 0 0.5 K \NC \NR +\NC \bf rgb \NC 29 \NC \tttf 0.5 0.5 0.5 rg 0.5 0.5 0.5 RG \NC \NR +\NC \bf gray \NC 11 \NC \tttf 0.5 g 0.5 G \NC \NR +\stoptabulate + +The conversion to gray is controlled by: + +\starttyping +\setupcolors + [factor=yes] +\stoptyping + +Like \type {conversion} the \type {factor} is a global setting. You can play with the factor values. +The default (\type {yes}) uses the factors used by color television: + +\startformula + s = 0.30r + 0.59g + 0.11b +\stopformula + +In \in {figure} [color:demo:gray] we demonstrate what happens when you use different +values. Normally you won't change the defaults but for experimenting we do provide +the option: + +\starttyping +\setupcolors + [factor=0.20:0.40:0.40] +\stoptyping + +There is one pitfall. Colors are finalized per page and as this is a backend +feature the value current when a page is shipped out is used. An exception are +\METAPOST\ graphics, as they have local resources and are finalized immediately. +This is hardly a limitation because one will never set these numbers in the +middle of a document. + +\starttexdefinition color:demo:gray:do + \definecolor[demo:rgb:0][r=0.5,g=0.6,b=0.7] + % \blackrule[width=4cm,height=1cm,color=demo:rgb:0] + \lower.4\strutdp\hbox\bgroup + \startMPcode + fill unitsquare xyscaled (.5TextWidth,.9LineHeight) + withcolor "demo:rgb:0"; + \stopMPcode + \egroup +\stoptexdefinition + +\starttexdefinition color:demo:gray #1#2#3 + \NC \tttf #1 \NC \tttf #2 \NC \tttf #3 \NC + \setupcolors[factor={#1:#2:#3}] + \setupcolors[rgb=no,cmyk=no] + \texdefinition{color:demo:gray:do} + \setupcolors[factor=yes] + \NC \NR +\stoptexdefinition + +\startplacefigure[reference=color:demo:gray,title={Color to gray conversion using factors.}] +\starttabulate[|c|c|c|c|] +\NC \bf r \NC \bf g \NC \bf b \NC \bf gray \NC \NR +\NC \NC \NC \NC \texdefinition{color:demo:gray:do} \NC \NR +\texdefinition{color:demo:gray}{0.30}{0.59}{0.11} +\texdefinition{color:demo:gray}{0.30}{0.11}{0.59} +\texdefinition{color:demo:gray}{0.59}{0.30}{0.11} +\texdefinition{color:demo:gray}{0.11}{0.30}{0.59} +\texdefinition{color:demo:gray}{0.11}{0.59}{0.30} +\texdefinition{color:demo:gray}{0.59}{0.11}{0.30} +\texdefinition{color:demo:gray}{0.20}{0.40}{0.40} +\texdefinition{color:demo:gray}{0.30}{0.60}{0.10} +\texdefinition{color:demo:gray}{0.20}{0.30}{0.20} +\texdefinition{color:demo:gray}{0.40}{0.40}{0.40} +\stoptabulate +\stopplacefigure + +\stopsection + +% let's take a break and watch: https://www.youtube.com/watch?v=baLrrW3El-M + +\startsection[title=Definitions] + +The mostly used color definition command is \type {\definecolor}. Here we define the +primary colors: + +\startbuffer +\definecolor [red] [r=1] +\definecolor [green] [g=1] +\definecolor [blue] [b=1] +\definecolor [yellow] [y=1] +\definecolor [magenta] [m=1] +\definecolor [cyan] [c=1] +\stopbuffer + +\typebuffer \getbuffer + +These can be visualized as follows: + +\startbuffer +\showcolorcomponents[red,green,blue,yellow,magenta,cyan,black] +\stopbuffer + +\typebuffer \getbuffer + +Transparency is included in these tables but is, as already noted, in fact +independent. It can be defined with a color: + +\startbuffer +\definecolor [t:red] [r=1,a=1,t=.5] +\definecolor [t:green] [g=1,a=1,t=.5] +\definecolor [t:blue] [b=1,a=1,t=.5] +\stopbuffer + +\typebuffer \getbuffer + +This time the transparency values show up too: + +\showcolorcomponents[t:red,t:green,t:blue] + +Because transparency is separated from color, we can define transparent behaviour +as follows: + +\startbuffer +\definecolor[t:only] [a=1,t=.5] +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer + \dontleavehmode + \blackrule[width=4cm,height=1cm,color=darkgreen]% + \hskip-2cm + \color[t:only]{\blackrule[width=4cm,height=1cm,color=darkred]}% + \hskip-2cm + \color[t:only]{\blackrule[width=4cm,height=1cm]} +\stopbuffer + +\typebuffer + +We skip back to create an overlay, so we get: + +\startlinecorrection +\getbuffer +\stoplinecorrection + +In the section about transparency a bit more will be said about the relation between +color and transparencies and how to cheat. + +As soon as you need to typeset something for professional printing, spot colors +will show up so they are supported too. A spot color is not really a color but +related to the substance that gets put on the paper. This can be ink but also +something metallic, like silver, gold or some texture. In these cases we need +something to represent it when not printed on a suitable device so again we end +up with a color. This is reflected in the way spot colors are set up. + +\startbuffer +\definecolor [parentspot] [r=.5,g=.2,b=.8] +\definespotcolor [childspot-1] [parentspot] [p=.7,e=fancy] +\definespotcolor [childspot-2] [parentspot] [p=.4] +\stopbuffer + +\typebuffer \getbuffer + +The three colors, two of them are spot colors, show up as follows: + +\setupcolors[spot=yes] + +\showcolorcomponents[parentspot,childspot-1,childspot-2] + +The \type {p} is comparable to the \type {s} in gray scales. The \type {e} +parameter can be used to specify a name for the color. In the \PDF\ file that +name will become the separation name (a popular commercial naming scheme is +Pantone). + +A combination of spotcolor is called a multitone color. These are defined as +follows (we also define a few spotcolors and use transparency): + +\startbuffer +\definespotcolor [spotone] [darkred] [p=1] +\definespotcolor [spottwo] [darkgreen] [p=1] + +\definespotcolor [spotone-t] [darkred] [a=1,t=.5] +\definespotcolor [spottwo-t] [darkgreen] [a=1,t=.5] + +\definemultitonecolor + [whatever] + [spotone=.5,spottwo=.5] + [b=.5] + +\definemultitonecolor + [whatever-t] + [spotone=.5,spottwo=.5] + [b=.5] + [a=1,t=.5] +\stopbuffer + +\typebuffer \getbuffer + +\showcolorcomponents[spotone,spottwo,spotone-t,spottwo-t,whatever,whatever-t] + +Transparencies combine as follows: + +\startbuffer +\blackrule[width=3cm,height=1cm,color=spotone-t]\hskip-1.5cm +\blackrule[width=3cm,height=1cm,color=spotone-t] +\stopbuffer + +\typebuffer + +\startlinecorrection +\dontleavehmode\getbuffer +\stoplinecorrection + +In case you want to specify colors in the \HSV\ color space, you can do that too. +The hue parameter (\type {h}) is in degrees and runs from 0 upto 360 (larger +values get divided). The saturation (\type {s}) and value (\type {v}) parameters +run from 0 to 1. The \type {v} parameter is mandate. In \in {figure} [fig:hsv] we +show what the last two variables do. + +\starttyping +\definecolor[somecolor][h=125,s=0.5,v=0.8] +\stoptyping + +\startMPextensions + vardef hsvcircle(expr s, v) = + image ( save p ; path p ; p := fullcircle ; + save l ; numeric l ; l := length(p)/360 ; + for i=0 upto 360 : + fill origin -- subpath (i*l,(i+1)*l) of p -- cycle withcolor hsvtorgb(i,s,v) ; + endfor ; + ) + enddef; +\stopMPextensions + +\startplacefigure[reference=fig:hsv,title={Four hsv color circle running from 0 to 360 degrees, with zero at the right.}] + \startcombination[4*1] + {\startMPcode draw hsvcircle(0.6,0.6) scaled 3cm ; \stopMPcode} {\tttf s=0.6 v=0.6} + {\startMPcode draw hsvcircle(0.4,0.6) scaled 3cm ; \stopMPcode} {\tttf s=0.4 v=0.6} + {\startMPcode draw hsvcircle(0.6,0.4) scaled 3cm ; \stopMPcode} {\tttf s=0.6 v=0.4} + {\startMPcode draw hsvcircle(0.4,0.4) scaled 3cm ; \stopMPcode} {\tttf s=0.4 v=0.4} + \stopcombination +\stopplacefigure + +% \scratchdimen\dimexpr(\textwidth-118pt)/120\relax +% \dontleavehmode \dostepwiserecurse{0}{359}{1}{% +% \definecolor[tempcolor][h=#1,s=0.6,v=0.6]% +% \blackrule[color=tempcolor,width=\scratchdimen,height=1ex,depth=1ex]% +% \hskip1pt +% } + +If you need to use hexadecimal color specifications you can use these +definitions: + +\starttyping +\definecolor[mycolor][x=4477AA] +\definecolor[mycolor][h=4477AA] +\definecolor[mycolor][x=66] +\definecolor[mycolor][#4477AA] +\stoptyping + +The \type {#} is normally not accepted in \TEX\ source code but when you get the +specification from elsewhere (e.g.\ \XML) it can be convenient. + +\stopsection + +\startsection[title=Freezing colors] + +We can clone colors and thereby overload color dynamically. You can however +freeze colors via the setup option \type {expansion}. + +\startbuffer +\definecolor[green] [r=.5]{({\green green -> red})} +\definecolor[green] [g=.5]{({\green green -> green})} +\definecolor[green] [blue]{({\green green -> blue})} +\definecolor[blue] [red]{({\green green -> red})} +\setupcolors[expansion=yes]% +\definecolor[blue] [red]% +\definecolor[green] [blue]% +\definecolor[blue] [r=.5]{({\green green -> blue})} +\stopbuffer + +\typebuffer + +\start +\definecolor[red] [r=.5]% +\definecolor[green][g=.5]% +\definecolor[blue] [b=.5]% +\getbuffer +\stop + +\stopsection + +\startsection[title=Color groups] + +Nowadays we seldom use colorgroups but they are still supported. Groups are +collections of distinctive colors, something we needed in projects where many +graphics had to be made and consistency between text and image colors was +important. The groups can be translated into similar collections in drawing +programs used at that time. + +\startbuffer +\definecolorgroup + [redish] + [1.00:0.90:0.90, % 1 + 1.00:0.80:0.80, % 2 + 1.00:0.70:0.70, % 3 + 1.00:0.55:0.55, % 4 + 1.00:0.40:0.40, % 5 + 1.00:0.25:0.25, % 6 + 1.00:0.15:0.15, % 7 + 0.90:0.00:0.00] % 8 +\stopbuffer + +\typebuffer \getbuffer + +The redish color is called by number: + +\startbuffer +\blackrule[width=3cm,height=1cm,depth=0pt,color=redish:1]\quad +\blackrule[width=3cm,height=1cm,depth=0pt,color=redish:2]\quad +\blackrule[width=3cm,height=1cm,depth=0pt,color=redish:3] +\stopbuffer + +\typebuffer + +The number of elements is normally limited and eight is about what is useful and +still distinguishes good enough when printed in black and white. + +\startlinecorrection +\dontleavehmode\getbuffer +\stoplinecorrection + +\startlinecorrection +\setupcolors[rgb=no,cmyk=no]\dontleavehmode\getbuffer +\stoplinecorrection + +\stopsection + +\startsection[title=Palets] + +Color palets are handy when you want to use a set of (named) colors but +also want to switch efficiently between different definitions: + +\startbuffer +\definepalet + [standard] + [darkred=darkcyan, + darkgreen=darkmagenta, + darkblue=darkyellow] +\stopbuffer + +\typebuffer \getbuffer + +The \type {\setuppalet} commands switches to a palet. When a requested color is +not part of a palet, a regular lookup happens. This is used as: + +\startbuffer +\blackrule[width=15mm,height=10mm,depth=0mm,color=darkred]\quad +\blackrule[width=15mm,height=10mm,depth=0mm,color=darkgreen]\quad +\blackrule[width=15mm,height=10mm,depth=0mm,color=darkblue]\quad +\setuppalet[standard]% +\blackrule[width=15mm,height=10mm,depth=0mm,color=darkred]\quad +\blackrule[width=15mm,height=10mm,depth=0mm,color=darkgreen]\quad +\blackrule[width=15mm,height=10mm,depth=0mm,color=darkblue] +\stopbuffer + +\typebuffer + +\startlinecorrection +\dontleavehmode \getbuffer +\stoplinecorrection + +Here we use color names but often you end up with more symbolic names: + +\starttyping +\definepalet + [standard] + [important=darkred, + notabene=darkgreen, + warning=darkyellow] +\stoptyping + +As with the regular color commands, the palet mechanism is an old one but it is +well integrated. Instead of inheriting you can also use definitions: + +\starttyping +\definepalet + [standard] + [important={r=.5}, + notabene={g=.5}, + warning={r=.5,g=.5}] +\stoptyping + +\stopsection + +\startsection[title=Transparency] + +We already discussed transparency as part of colors. In most cases we will choose +type {normal} (or \type {1}) as transparency type, but there are more: + +\startluacode + local codes = table.swapped(attributes.transparencies.names) + + context.startcolumns { n = 4 } + context.starttabulate ( { "|B||" }, { keeptogether = "no" } ) + for i=0,#codes do + context.NC() + context(i) + context.NC() + context(codes[i]) + context.NC() + context.NR() + end + context.stoptabulate() + context.stopcolumns() +\stopluacode + +In \in {figure} [fig:transparency] we compare these variants. Not all are as +effective as their effect depends on several factors. You can read more about it +in the \PDF\ specification. + +\startMPextensions + vardef transdemo(expr b) = + image ( save p ; path p ; p := fullcircle ; + save l ; numeric l ; l := length(p)/16 ; + if (b = 1) or (b = 3) : + fill fullcircle scaled 1.00 withcolor yellow ; + fill fullcircle scaled 0.80 withcolor red ; + fill fullcircle scaled 0.60 withcolor black ; + fill fullcircle scaled 0.40 withcolor white ; + fill fullcircle scaled 0.20 withcolor .5white ; + fi ; + if (b = 2) or (b = 3) : + for i=0 upto 15 : + fill origin -- subpath (i*l,(i+1)*l) of p -- cycle + withcolor red + withtransparency (i,0.5) ; + draw textext("\ttbf " & decimal i) ysized .04 shifted (.45,0) rotated (i*360/16 + 360/32) ; + endfor ; + fi ; + ) + enddef; +\stopMPextensions + +\startplacefigure[reference=fig:transparency,title={The differences between the transparency options. The center is explicitly filled with white.}] + \startcombination[3*1] + {\startMPcode draw transdemo(1) scaled 4cm ; \stopMPcode} {\tttf backgrounds used} + {\startMPcode draw transdemo(2) scaled 4cm ; \stopMPcode} {\tttf transparencies used} + {\startMPcode draw transdemo(3) scaled 4cm ; \stopMPcode} {\tttf transparency overlayed} + \stopcombination +\stopplacefigure + +Colors and transparencies are coupled by definitions. We will explain this by +some examples. When we say: + +\startbuffer +\definecolor[clr1][r=.5] +\stopbuffer + +\typebuffer \getbuffer + +A non|-|transparent color is defined and when we say: + +\startbuffer +\definecolor[clr2][g=.5,a=1,t=.5] +\stopbuffer + +\typebuffer \getbuffer + +We defined a color with a transparency. However, color and transparency get separated +attributes. So when we nest them as in: + +\startbuffer +\color[clr1]{\bf RED \color[clr2] {GREEN}} +\color[clr2]{\bf GREEN \color[clr1] {RED} } +\stopbuffer + +\typebuffer + +we get: + +\startlines \getbuffer \stoplines + +The transparency of the outer color is also applied to the inner color. If you +don't want that, you explicitly need to set them: + +\startbuffer +\definecolor[clr3][b=.5,a=1,t=1] +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\color[clr1]{\bf RED \color[clr2] {GREEN} \color[clr3]{BLUE} } +\color[clr2]{\bf GREEN \color[clr1] {RED} \color[clr2]{GREEN}} +\color[clr3]{\bf BLUE \color[clr1] {RED} \color[clr2]{GREEN}} +\stopbuffer + +\typebuffer + +we get: + +\startlines \getbuffer \stoplines + +If you define a transparent|-|only color, you get transparent black: + +\startbuffer +\definecolor[clr4][a=1,t=.5] +\stopbuffer + +\typebuffer \getbuffer + +So: + +\startbuffer +\color[clr1]{\bf RED \color[clr4] {RED}} +\color[clr4]{\bf BLACK \color[clr1] {RED}} +\stopbuffer + +\typebuffer + +gives: + +\startlines \getbuffer \stoplines + +In addition to the already discussed definers and setters we also have a few +special ones. Personally I never needed them but they are the for completeness. + +\startbuffer +\definetransparency[tsp1][a=1,t=.5] +\stopbuffer + +\typebuffer \getbuffer + +We apply this to some text: + +\startbuffer +\color [clr1]{\bf RED \transparent[tsp1] {RED} } +\transparent[tsp1]{\bf BLACK \color [clr1] {RED} } +\transparent[tsp1]{\bf BLACK \transparent[reset]{BLACK} } +\stopbuffer + +\typebuffer + +and get: + +\startlines \getbuffer \stoplines + +We can also only switch color: + +\startbuffer +\color[clr1]{\bf RED \color [clr2] {GREEN}} +\color[clr1]{\bf RED \coloronly[clr2] {GREEN}} +\stopbuffer + +\typebuffer + +So the second line has no transparency: + +\startlines \getbuffer \stoplines + +The \typ {\starttransparent} and \type {\startcoloronly} commands are the +complements of \typ {\transparent} and \typ {\coloronly}. + +\stopsection + +\startsection[title=Interpolation] + +You can define intermediate colors in a way comparable with \METAPOST\ \type +{.5[red,green]} kind of specifications. Here are some examples: + +\startbuffer +\definecolor [mycolor1] [.5(red,green)] +\definecolor [mycolor2] [.8(red,green)] +\definecolor [mycolor3] [.4(red,white)] +\definecolor [mycolor4] [.4(white,red)] + +\showcolorcomponents[red,green,mycolor1,mycolor2,mycolor3,mycolor4] +\stopbuffer + +\typebuffer \getbuffer + +An older method, still available is: + +\starttyping +\defineintermediatecolor[mycolor5][0.5,red,green] +\stoptyping + +A variation on this are complementary colors: + +\startbuffer +\definecolor[mycolor1][.5(blue,red)] +\definecolor[mycolor2][-.5(blue,red)] +\definecolor[mycolor3][-(blue)] +\definecolor[mycolor4][-(red)] + +\showcolorcomponents[blue,red,mycolor1,mycolor2,mycolor3,mycolor4] +\stopbuffer + +\typebuffer \getbuffer + +\stopsection + +\startsection[title=PDF] + +Although it is not perfect, \PDF\ evolved in such a way that it will stay around +for a while. One reason is that it has become a standard, or more precisely a set +of standards. Depending on what variant you choose color support is limited. + +\startluacode + +local function state(v) + context.NC() + if v then + context("\\star") + end +end + +context.starttabulate { "|l|c|c|c|c|c|" } +context.NC() context.bold("format") +context.NC() context.bold("gray") +context.NC() context.bold("rgb") +context.NC() context.bold("cmyk") +context.NC() context.bold("spot") +-------.NC() context.bold("multi") +context.NC() context.bold("transparency") +context.NC() context.NR() +for name, data in table.sortedhash(lpdf.formats.data) do + context.NC() context.type(name) + state(data.gray_scale) + state(data.rgb_colors) + state(data.cmyk_colors) + state(data.spot_colors) + -- state(data.nchannel_colorspace) + -- state(data.calibrated_rgb_colors) + -- state(data.cielab_colors) + state(data.transparency) + -- state(data.include_intents) + -- state(data.internal_icc_profiles) + -- state(data.external_icc_profiles) + context.NR() +end +context.stoptabulate() + +\stopluacode + +When you have set the \type{format} with \type {\setupbackend} to one of the +known formats mentioned in the previous table, the color conversions will +automatically kick in. + +\stopsection + +\startsection[title=Unboxing] + +This paragraph is somewhat complex, so skip it when you don't feel comfortable +with the subject or when you've never seen low level \CONTEXT\ code. + +Colors are implemented using attributes. Attributes behave like fonts. This means +that they are kind of frozen once material is boxed. Consider that we define a +box as follows: + +\startbuffer +\setbox0\hbox{\bf default {\darkred red \darkgreen green} default} +\stopbuffer + +\typebuffer \getbuffer + +What do you expect to come out the next code? In \MKII\ the \quote {default} +inside the box will be colored yellow but the internal red and and green words +will keep their color. + +\startbuffer +\bf default {\darkyellow yellow {\box0} yellow} default +\stopbuffer + +\typebuffer + +This is what we get in \MKIV: \start \inlinebuffer \stop + +When we use fonts switches we don't expect the content of the +box to change. So, in the following the \quote {default} texts will +{\em not} become bold. + +\startbuffer +\setbox0\hbox{default {\sl slanted \bi bold italic} default} +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +default {\bf bold {\box0} bold} default +\stopbuffer + +\typebuffer + +Now we get: \inlinebuffer . + +Redoing a box with a new font is sort of tricky as by then all kind of +manipulations have been applied and the original inputs is long gone. But colors +are easier to deal with and therefore in \MKIV\ we have a trick to make sure the +outer color gets applied to the box: + +\startbuffer[enable] +\enabledirectives + [attributes.inheritance] +\stopbuffer + +\startbuffer +default {\bf \darkyellow yellow {\attributedbox0} yellow} default +\stopbuffer + +\typebuffer + +So, we get: \start\inlinebuffer[box]\inlinebuffer[enable]\space\inlinebuffer +\stop, but only after we have enabled this mechanisms explicitly: + +\typebuffer[enable] + +There is also an \type {\attributedcopy} macro. These macros signal the attribute +resolver that this box is to be treated special. + +In \MKII\ we have a similar situation which is why we had the option (only used +deep down in \CONTEXT) to encapsulate a bunch of code with + +\starttyping +\startregistercolor[foregroundcolor] +some macro code ... here foregroundcolor is applied ... more code +\stopregistercolor +\stoptyping + +This is for instance used in the \type {\framed} macro. First we package the +content, foregroundcolor is not yet applied because the injected specials of +literals can interfere badly, but by registering the colors the nested color +calls are tricked into thinking that preceding and following content is colored. +When packaged, we apply backgrounds, frames, and foregroundcolor to the whole +result. Because nested colors were aware of the foregroundcolor they have +properly reverted to this color when needed. + +In \MKIV\ the situation is reversed. Here we definitely need to set the +foregroundcolor because otherwise attributes are not set. This is no problem +because contrary to \MKII\ colors don't interfere (no extra nodes). We could have +flushed the framed content using \type {\attributedbox}, but we don't want to +enable inheritance by default because it comes with some overhead. + +\stopsection + +\startsection[title=Color intents] + +If we do this: + +\startbuffer +\startoverlay + {\blackrule[color=darkred, height=2cm,width=4cm]} + {\blackrule[color=darkblue,height=1cm,width=3cm]} +\stopoverlay +\stopbuffer + +\typebuffer + +we get: + +\startlinecorrection +\getbuffer +\stoplinecorrection + +The blue rectangle is drawn on top of the red one. In print, normally the +printing engine will make sure that there is no red below the blue. In case of +transparent colors this is somewhat tricky because then we definitely want to see +part of what lays below. + +You can control this process with the following commands: + +\starttyping +\setupcolors + [intent=...] +\stoptyping + +The default setting is \type {none} but you can set the intent to \type {overprint} or +\type {knockout} as well. In a running text you can use the following commands: + +\starttyping +\startcolorintent[overprint|knockout] + ... +\stopcolorintent + +\startoverprint + ... +\stopoverprint + +\startknockout + ... +\stopknockout +\stoptyping + +In practice you will probably seldom need to deal with this so best leave the defaults +as they are. + +\stopsection + +\startsection[title=Collections] + +Collections are predefined sets of colors. You find them in the files \type +{colo-imp-*.mkiv} and you can make such files yourself. When you define a color a +command is generated by default. When you load a collection, there is a danger +that you redefine commands unintended. For that reason most collections are +wrapped in: + +\starttyping +\startprotectedcolors + % definitions +\stopprotectedcolors +\stoptyping + +This prevents commands being defined and assumes that colors are accessed by +using the \type {color} parameter of setup commands or in the text with: + +\starttyping +\color[somecolor]{this gets colored} + +\startcolor[somecolor] + this gets colored +\stopcolorintent +\stoptyping + +The default set (\type {rgb}) is already preloaded with: + +\starttyping +\usecolors[rgb] % preloaded +\stoptyping + +You can get a list of colors with + +\startbuffer +\showcolor[rgb] +\stopbuffer + +\typebuffer + +This generates the list: + +\getbuffer + +These are the collections shipped with \CONTEXT. Some names are + +\starttabulate[|T||] +\NC crayola \NC crayon colors \NC \NR +\NC dem \NC a demo set of groups and palets \NC \NR +\NC ema \NC an old coming from an Emacs user \NC \NR +%NC pan \NC a bunch of Pantone colors \NC \NR % can't be distributed +%NC pra \NC colors used at \PRAGMA \NC \NR +\NC rainbow \NC a series of color groups by Alan \NC \NR +\NC ral \NC a set often used in industry (from Germany) \NC \NR +\NC rgb \NC a basic set of colors defined in the \RGB\ color space \NC \NR +%NC ros \NC the roscolux color set used in theater and cinema lighting \NC \NR % probably can't be distributed +\NC x11 \NC (most of the) standard X11 \RGB\ colors \NC \NR +\stoptabulate + +You can look in these files to see what gets defined. Even if you don't use them +they might be illustrative, + +\stopsection + +\startsection[title=Text color] + +Setting the color of the running text is done with: + +\starttyping +\setupcolors + [textcolor=darkgray] +\stoptyping + +If needed you can also set the \type {pagecolormodel} there but its default value +is \type {none} which means that it will obey the global settings. + +\stopsection + +\startsection[title=Tikz] + +In case you use the TikZ graphical subsystem you need to be aware of the the fact +that its color support is more geared towards \LATEX. There is glue code that +binds the \CONTEXT\ color system to its internal representation but there can +still be problems. For instance, not all color systems are supported so \CONTEXT\ +will try to remap, but only when it knows that it has to do so. You can best not +mix colorspaces when you use TikZ. If you really want (and there is no real +reason to do so) you can say: + +\starttyping +\enabledirectives[colors.pgf] +\stoptyping + +and then (at the cost of some extra overhead) define colors as: + +\starttyping +\definecolor[pgfcolora][blue!50!green] +\definecolor[pgfcolorb][red!50!blue] +\stoptyping + +\stopsection + +\startsection[title=Implementation details] + +The low level implementation of colors in \MKIV\ is fundamentally different from +\MKII. In \MKIV\ something like this happens: + +\starttyping +one \color[red]{two} three +\stoptyping + +becomes (with grouping): + +\starttyping +one {<start color: red>two<stop color>} three +\stoptyping + +the start and stop points are in fact injections in the input: a special (for +\DVI) or literals (for \PDF) is inserted that turns the color on and off, but +also information is carried along about the state of color, so that we can +properly nest as well as pick up the current color after a page break. We never +had real problems with this mechanism but one had to keep in mind that injections +like this could interfere with typesetting. This mechanism didn't rely on the +engine for housekeeping, all was done at the \TEX\ end using so called marks. + +In \MKIV\ we use attributes. This means that the sequence now looks like: + +\starttyping +one {<set color attribute to red>two} three +\stoptyping + +The actual handling of color happens when a page is shipped out and there is no +interference with typesetting. The work is mostly done in \LUA. + +Colorspaces (\RGB, \CMYK, spot) were already supported in \MKII\ and of course +still are in \MKIV. However, the colorspace is now a more independent property. +At some point in \MKII\ we also implemented transparency as a property of a +color. In \MKIV\ transparency is still defined with a color but handled +independently. This means that where in \MKII\ color is just one axis, in \MKIV\ +we have three: colorspace (model), color and transparency. This of course has a +bit of a performance and memory hit, but in practice a user won't notice it. + +\stopsection + +\startsection[title=Grouping] + +The \type {\color} and \type {\startcolor} command group their arguments. There might +be cases where this interferes with your intentions, for instance when you want to +set some variable and use its value later on. + +\startbuffer +1 \scratchcounter=1 +plus +1 \advance \scratchcounter by 1 +equals +\the\scratchcounter +\stopbuffer + +\typebuffer + +The summation works out okay: {\bf \inlinebuffer}. + +\startbuffer +\color[darkblue]{1 \scratchcounter=1} +plus +\color[darkblue]{1 \advance \scratchcounter by 1} +equals +\color[darkgreen]{\the\scratchcounter} +\stopbuffer + +\typebuffer + +Here the final result depends on the value of \type {\scratchcounter}: +{\scratchcounter 3 \bf \inlinebuffer}. + +\startbuffer +\start + \pushcolor[darkblue]1 \scratchcounter=1 \popcolor + plus + \pushcolor[darkblue]1 \advance \scratchcounter by 1 \popcolor + equals + \pushcolor[darkgreen]\the\scratchcounter \popcolor +\stop +\stopbuffer + +\typebuffer + +Here we get: {\bf \inlinebuffer}. The \typ {\pushcolor} and \typ {\popcolor} +commands can be used nested which give a bot of overhead. The \typ {\savecolor} +and \typ {\restorecolor} commands are variants that don't stack. They are a bit +more efficient but if you use them nested you probably also will use some +grouping. Where the push||pop pair needs to be matched, the save||restore pair +doesn't impose that restriction. + +\stopsection + +\startsection[title=Commands] + +There are quite some commands that relate to colors but you probably only need +\typ {\definecolor}, \type {\color} and \typ {\startcolor} \unknown \typ +{\stopcolor}. Here we show the complete list. Some commands are redundant, for +instance \typ {\definenamedcolor} is the same as \typ {\definecolor}. + +\placeallsetups + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/colors/colors-environment.tex b/doc/context/sources/general/manuals/colors/colors-environment.tex new file mode 100644 index 000000000..99f625854 --- /dev/null +++ b/doc/context/sources/general/manuals/colors/colors-environment.tex @@ -0,0 +1,7 @@ +\startenvironment colors-environment + + \environment manuals-explaining-environment + \environment manuals-explaining-cover + +\stopenvironment + diff --git a/doc/context/sources/general/manuals/colors/colors-graphics.tex b/doc/context/sources/general/manuals/colors/colors-graphics.tex new file mode 100644 index 000000000..4c8fb5270 --- /dev/null +++ b/doc/context/sources/general/manuals/colors/colors-graphics.tex @@ -0,0 +1,234 @@ +% language=uk + +\startcomponent colors-basics + +\environment colors-environment + +\startchapter[title=Graphics][color=darkblue] + +\startsection[title=Conversion] + +There is not that much to tell about graphics and color simply because from the +perspective of \TEX\ a graphic is just a blob with dimensions that travels +through the system and in the backend gets included as|-|is. This means that when +there is a problem with an image you have to go back to the source of that image +and fix it there. + +It can happen that you need to manipulate an image and in a fully automated +workflow that can be cumbersome. For that reason \CONTEXT\ has a mechanism for +converting graphics. + +\startluacode + context.starttabulate { "|BT|T|" } + context.NC() context.bold("original") + context.NC() context.bold("target") + context.NC() context.NR() + for k, v in table.sortedhash(figures.converters) do + context.NC() context(k) + context.NC() context("%{\\quad }t",table.sortedkeys(v)) + context.NC() context.NR() + end + context.stoptabulate() +\stopluacode + +Some of these converters are applied automatically. For instance if you include +an \type {eps} image, \CONTEXT\ will try to convert it into a \PDF\ file and only +do that once (unless the image changed). Of course it needs a conversion program, +but as long as you have GhostScript, GraphicMagick and InkScape on your machine +it should work out well. + +You can also define your own converters (we use a verbose variant): + +\starttyping +\startluacode + -- of course we need options + + local resolutions = { + [interfaces.variables.low] = "150x150", + [interfaces.variables.medium] = "300x300", + [interfaces.variables.high] = "600x600", + } + + figures.programs.lowrespng = { + command = "gm", + argument = [[convert -resample %resolution% "%oldname%" "%newname%"]], + } + + figures.converters["png"]["lowres.png"] = function(oldname,newname,resolution) + runprogram ( + figures.programs.lowrespng.command, + figures.programs.lowrespng.argument, + { + oldname = oldname, + newname = newname, + resolution = resolutions[resolution] or "150x150" + } + ) + end +\stopluacode +\stoptyping + +Usage is as follows: + +\starttyping +\externalfigure[mill.png][conversion=lowres.png] +\stoptyping + +\stopsection + +\startsection[title=Recoloring] + +You can think of more complex conversions, like converting a gray scale image to +a colored one. + +\startbuffer +\startluacode + figures.programs.recolor = { + command = "gm", + argument = [[convert -recolor "%color%" "%oldname%" "%newname%"]], + } + + figures.converters["png"]["recolor.png"] = + function(oldname,newname,resolution,arguments) + figures.programs.run ( + figures.programs.recolor.command, + figures.programs.recolor.argument, + { + oldname = oldname, + newname = newname, + color = arguments or ".5 0 0 .7 0 0 .9 0 0", + } + ) + end +\stopluacode +\stopbuffer + +\typebuffer % built in so no \getbuffer + +\startbuffer +\useexternalfigure[mill][mill.png][conversion=recolor.png] +\startcombination[3*2] + {\externalfigure[mill][arguments=.5 0 0 .7 0 0 .9 0 0]}{\figurefilearguments} + {\externalfigure[mill][arguments=.7 0 0 .9 0 0 .5 0 0]}{\figurefilearguments} + {\externalfigure[mill][arguments=.9 0 0 .5 0 0 .7 0 0]}{\figurefilearguments} + {\externalfigure[mill][arguments=.5 0 0 .9 0 0 .7 0 0]}{\figurefilearguments} + {\externalfigure[mill][arguments=.7 0 0 .5 0 0 .9 0 0]}{\figurefilearguments} + {\externalfigure[mill][arguments=.9 0 0 .7 0 0 .5 0 0]}{\figurefilearguments} +\stopcombination +\stopbuffer + +This can be applied as follows. The \type {resolution} and \type {color} +parameters get passed to the converter. This method is actually built +in already. + +\typebuffer + +The results are shown in \in {figure} [fig:recolor]. In this case we pass the +colors to be use in a kind of matrix notation that GraphicMagick needs. + +\startplacefigure[reference=fig:recolor,title={Recoloring bitmap images.}] + \getbuffer +\stopplacefigure + +Recoloring an image this way is actually not the best solution because +there is an internal mechanism that does the same. This trick (currently) +only works with spot colors. + +\startbuffer +\definecolor [my-blue] [c=1,m=.38,y=0,k=.64] % pms 2965 uncoated m +\definecolor [my-yellow] [c=0,m=.28,y=1,k=.06] % pms 124 uncoated m + +\definespotcolor [my-blue-100] [my-blue] [p=1] +\definespotcolor [my-yellow-100] [my-yellow] [p=1] +\definespotcolor [my-blue-50] [my-blue] [p=.5] +\definespotcolor [my-yellow-50] [my-yellow] [p=.5] + +\definemultitonecolor [my-mix] [my-blue=.12,my-yellow=.28] [c=.1,m=.1,y=.3,k=.1] +\stopbuffer + +\typebuffer \getbuffer + +These colors show up as: + +\starttabulate[|T||] +\NC my-blue \NC \blackrule[color=my-blue, width=.6\textwidth,height=5mm] \NC \NR +\NC my-blue-50 \NC \blackrule[color=my-blue-50, width=.6\textwidth,height=5mm] \NC \NR +\NC my-blue-100 \NC \blackrule[color=my-blue-100, width=.6\textwidth,height=5mm] \NC \NR +\NC my-yellow \NC \blackrule[color=my-yellow, width=.6\textwidth,height=5mm] \NC \NR +\NC my-yellow-50 \NC \blackrule[color=my-yellow-50, width=.6\textwidth,height=5mm] \NC \NR +\NC my-yellow-100 \NC \blackrule[color=my-yellow-100,width=.6\textwidth,height=5mm] \NC \NR +\NC my-mix \NC \blackrule[color=my-mix, width=.6\textwidth,height=5mm] \NC \NR +\stoptabulate + +\useexternalfigure[demofig][mill.png][object=no,width=.2\textwidth] + +\startbuffer +\startcombination[4*1] + {\externalfigure[demofig]} {no color} + {\externalfigure[demofig][color=my-mix]} {indexed duotone} + {\externalfigure[demofig][color=my-blue-100]} {spot color} + {\externalfigure[demofig][color=my-yellow-100]} {spot color} +\stopcombination +\stopbuffer + +\typebuffer + +This time we don't call an external program but we add an indexed color map to the +image. The result can be seen in \in {figure} [fig:reindexing]. + +\startplacefigure[reference=fig:reindexing,title={Reindexing bitmap images.}] + \getbuffer +\stopplacefigure + +\stopsection + +\startsection[title=Profiles] + +Color profiles are used to control the printing process. There is some (limited) +support for that built in. An example of a setup that we use in a project is the +following: + +\starttyping +\setupexternalfigures + [order={pdf,eps,png,jpg}, + conversion=cmyk.pdf, + method=auto] +\stoptyping + +So, we prefer \PDF\ vector images, if needed converted from \EPS. When there is +no vector image we check for a \PNG\ and as last resort for a \JPG. The +\type{method} is set to \type {auto} which means that we check if the image file +indeed is reflected in the suffix. This is needed because in a workflow with tens +of thousands of images there can be bad ones. + +The \type {conversion} parameter will make \CONTEXT\ check if there is a \type +{cmyk.pdf} converter defined and when that is the case, it's applied. That +specific converter will add a color profile to the image. You can set the +profiles with: + +\starttyping +\enabledirectives[graphics.conversion.rgbprofile=srgb.icc] +\enabledirectives[graphics.conversion.cmykprofile=isocoated_v2_eci.icc] +\stoptyping + +and these happens to be the defaults. You have to make sure that the files are +present, preferable in \type{t:/texmf/colors/icc/context}. If you add profiles +you need to make sure that \type {colorprofiles.lua} is updated accordingly. + +Just for completeness, in our situation, we also have set: + +\starttyping +\enabledirectives[graphics.conversion.eps.cleanup.ai] +\enabledirectives[graphics.extracheck] +\stoptyping + +The first directive will make sure that confusing sections (for instance meant to +the drawing program) are stripped from an \EPS\ file, and the second one forces +some extra checking on the image (just to make sure that the engine doesn't exit +on bad images). + +\stopsection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/colors/colors-introduction.tex b/doc/context/sources/general/manuals/colors/colors-introduction.tex new file mode 100644 index 000000000..ba1db9915 --- /dev/null +++ b/doc/context/sources/general/manuals/colors/colors-introduction.tex @@ -0,0 +1,49 @@ +% language=uk + +\startcomponent colors-introduction + +\environment colors-environment + +\startchapter[title=Introduction][color=darkgray] + +This manual fits in the series where we discus fundamental subsystems like fonts +and languages. Here we will collect the more technical backgrounds. This document +is not meant as a manual for users who start with \CONTEXT, for that we have +other manuals. + +Color has a rather long history in \CONTEXT\ because we supported it right from +the start. In the times that \DVI\ backend drivers were used, specials were the +way to force color in the result. However, each driver had different demands: +some expected specific color directives, others a sequence of for instance +\POSTSCRIPT\ commands. When \PDF\ showed up, resource management entered the +game. Because ot always used a backend driver model in \CONTEXT, it could easily +be adapted. All management, for instance of nested colors, was done in \TEX\ +code. If advanced color support hadn't been available right from the start, we'd +probably not be using \TEX\ now. + +In \MKIV\ color support was implemented from scratch but in a for the user +downward compatible way. In that respect this manual is not going to reveal +anything revolutionary. Much of the work is now delegated to \LUA\ and because of +that directives are no longer part of the (expanded) input stream. As a result +color is now more robust and less intrusive. + +Because \METAPOST\ support is well integrated, we also communicate colors to +\METAPOST. In \MKIV\ the communication between the two engines was upgraded and +hopefully evolved into an (even) more convenient interface. + +External graphics are in fact islands in the document flow: they manage their +resources like colors themselves. However, there are some ways to deal with the +demands of publishers and printers with respect to colors. These will be +discussed too. + +\getbuffer[underconstruction] + +\startlines +Hans Hagen +PRAGMA ADE, Hasselt NL +2016 +\stoplines + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/colors/colors-metafun.tex b/doc/context/sources/general/manuals/colors/colors-metafun.tex new file mode 100644 index 000000000..82514659b --- /dev/null +++ b/doc/context/sources/general/manuals/colors/colors-metafun.tex @@ -0,0 +1,695 @@ +% language=uk + +\startcomponent colors-basics + +\environment colors-environment + +\startchapter[title=Metafun][color=darkyellow] + +\startsection[title=Defining and using] + +In \METAPOST\ itself colors are defined as numbers or sets: + +\starttyping +color red ; red := (1,0,0) ; +cmykcolor cyan ; cyan := (1,0,0,0) ; +numeric gray ; gray := 0.5 ; +\stoptyping + +You don't need much fantasy to see that this fits well in the data model of +\METAPOST. In fact, transparency could be represented as a \type {pair}. The +disadvantage of having no generic color type is that you cannot mix them. In case +you need to manipulate them, you can check the type: + +\starttyping +if cmykcolor cyan : ... fi ; +\stoptyping + +because \METAFUN\ is tightly integrated in \CONTEXT\ you can refer to colors +known at the \TEX\ end by string. So, + +\starttyping +string mycolor ; mycolor := "red" ; +\stoptyping + +and then: + +\starttyping +fill fullcircle scaled 4cm withcolor mycolor ; +\stoptyping + +is quite okay. For completeness we also have \type {namedcolor} but it's not +really needed: + +\starttyping +fill fullcircle scaled 4cm withcolor namedcolor("red"); +\stoptyping + +You can define spot colors too but normally you will refer to colors +defined at the \TEX\ end. + +\startbuffer[spot] +\startMPcode + fill fullcircle scaled 3cm withcolor + .5 * spotcolor("whatever",(.3,.4,.5)) ; + fill fullcircle scaled 2cm withcolor + spotcolor("whatever",(.3,.4,.5)) ; + fill fullcircle scaled 1cm withcolor + spotcolor("whatever",(.3,.4,.5)/2) ; +\stopMPcode +\stopbuffer + +\startbuffer[multi] +\startMPcode + fill fullcircle scaled 3cm withcolor + .5 * multitonecolor("whatever",(.3,.4,.5),(.5,.3,.4)) ; + fill fullcircle scaled 2cm withcolor + multitonecolor("whatever",(.3,.4,.5),(.5,.3,.4)) ; + fill fullcircle scaled 1cm withcolor + multitonecolor("whatever",(.3,.4,.5)/2,(.5,.3,.4)/2) ; +\stopMPcode +\stopbuffer + +\typebuffer[spot] + +Multitones are defined as: + +\typebuffer[multi] + +Some \PDF\ renderers have problems with fractions of such colors and even display +the wrong colors. So, in these examples the third alternative in the sets of +three might be more robust than the first. The result is shown in \in {figure} +[fig:mpspot]. + +\startplacefigure[reference=fig:mpspot,title={Spot and multitones directly defined in \METAFUN.}] + \startcombination[2*1] + {\getbuffer[spot]} {} + {\getbuffer[multi]} {} + \stopcombination +\stopplacefigure + +\stopsection + +\startsection[title=Passing colors] + +Originally \TEX\ and \METAPOST\ were separated processes and even in \LUATEX\ +they still are. There can be many independent \METAPOST\ instances present, but +always there is \LUA\ as glue between them. In the early days of \LUATEX\ this +was a one way channel: the \METAPOST\ output is available at the \TEX\ end in +\LUA\ as a table and properties are used to communicate extensions. In today's +\LUATEX\ the \METAPOST\ library has access to \LUA\ itself so that gives us a +channel to \TEX, although with some limitations. + +Say that we have a color defined as follows: + +\startbuffer +\definecolor[MyColor][r=.25,g=.50,b=.75] +\stopbuffer + +\typebuffer \getbuffer + +We can apply this to a rule: + +\startbuffer +\blackrule[color=MyColor,width=3cm,height=1cm,depth=0cm] +\stopbuffer + +\typebuffer + +From this we get: + +\startlinecorrection +\getbuffer +\stoplinecorrection + +In \TEX\ (code) we can do this: + +\startbuffer +\startMPcode + fill unitsquare xyscaled (3cm,1cm) withcolor \MPcolor {MyColor} ; +\stopMPcode +\stopbuffer + +\typebuffer + +When the code is pushed to \METAPOST\ the color gets expanded, in this case to +\typ {(0.25, 0.50, 0.75)} because we specified an \RGB\ color but the other +colorspaces are supported too. + +\startlinecorrection +\getbuffer +\stoplinecorrection + +Equally valid code is: + +\starttyping +\startMPcode + fill unitsquare xyscaled (3cm,1cm) withcolor "MyColor" ; +\stopMPcode +\stoptyping + +This is very un-\METAPOST\ as naturally it can only deal with numerics for gray +scales, triplets for \RGB\ colors, and quadruplets for \CMYK\ colors. In +\METAFUN\ (as present in \CONTEXT\ MKIV) the \type {withcolor} operator also +accepts a string, which is resolved to a color specification. + +For the record we note that when you use transparent colors, a more complex +specification gets passed with \type {\MPcolor} or resolved (via the string). The +same is true for spot and multitone colors. It will be clear that when you want +to assign a color to a variable you have to make sure the type matches. A rather +safe way to define colors is: + +\starttyping +def MyColor = + \MPcolor{MyColor} +enddef ; +\stoptyping + +and because we can use strings, string variables are also an option. + +\stopsection + +\startsection[title=Grouping] + +The reason for discussing these details is that there is a rather fundamental +concept of grouping in \TEX\ which can lead to unexpected side effects. The +reason is that there is no grouping at the \LUA\ end, unless one uses a kind of +stack, and that in \METAPOST\ grouping is an explicit feature. + +\starttyping +\scratchcounter=123 +\bgroup + \scratchcounter=456 +\egroup +\stoptyping + +After this \TEX\ code is expanded the counter has value 123. In \METAPOST\ you +can do the following: + +\starttyping +scratchcounter := 123 ; +\begingroup + scratchcounter := 456 ; +\endgroup +\stoptyping + +but here the counter is 456 afterwards! You explicitly need to save a value: + +\starttyping +scratchcounter := 123 ; +\begingroup + save scratchcounter ; + numeric scratchcounter ; % variables are numeric by default anyway + scratchcounter := 456 ; +\endgroup +\stoptyping + +The difference perfectly makes sense if you think about the kind of applications +\TEX\ and \METAPOST\ are used for. In \LUA\ you can do this: + + +\starttyping +scratchcounter = 123 +do + local scratchcounter = 456 +end +\stoptyping + +and in fact, a \type {then}, \type {else}, \type {while}, \type {repeat}, \type +{do} and function body also behave this way. + +So, what is the impact on colors? Imagine that you do this: + +\startbuffer +\bgroup + \definecolor[MyColor][s=.5] + \startMPcode + pickup pencircle scaled 4mm ; + draw fullcircle scaled 30mm withcolor \MPcolor{MyColor} ; + draw fullcircle scaled 15mm withcolor "MyColor" ; + \stopMPcode +\egroup +\quad +\startMPcode + pickup pencircle scaled 4mm ; + draw fullcircle scaled 30mm withcolor \MPcolor{MyColor} ; + draw fullcircle scaled 15mm withcolor "MyColor" ; +\stopMPcode +\stopbuffer + +\typebuffer + +We get the following colors: + +\startlinecorrection +\hbox{\getbuffer} +\stoplinecorrection + +Because \type {\MPcolor} is a \TEX\ macro, its value gets expanded when the +graphic is calculated. After the group (first graphic) the color is restored. +But, in order to access the colors defined at the \TEX\ end in \METAPOST\ by name +(using \LUA) we need to make sure that a defined color is registered at that end. +Before we could use the string accessor in \METAPOST\ colors, this was never a +real issue. We kept the values in a (global) \LUA\ table which was good enough +for the cases where we wanted to access color specifications, for instance for +tracing. Such colors never changed in a document. But with the more dynamic +\METAPOST\ graphics we cannot do that: there is no way that \METAPOST\ (or \LUA) +later on can know that the color was defined inside a group as clone. For daily +usage it's enough to know that we have found a way around it in \CONTEXT\ at +neglectable overhead. In the rare case this mechanism fails, you can always +revert to the \type {\MPcolor} method. + +\startbuffer +\definecolor[DemoOne][red] +\definecolor[DemoTwo][s=.8,t=0.5,a=1] + +%definepalet[DemoPalet][NumberColor={g=1}] +\definepalet[DemoPalet][NumberColor=red,red=cyan] +\definepalet[DemoPalet][NumberColor=red] + +\setuppalet[DemoPalet] + +\bgroup + \definecolor[red] [b=.8] + \definecolor[DemoOne][yellow] + \startMPcode + fill fullcircle scaled 10 withcolor "NumberColor" ; + fill fullcircle scaled 7 withcolor "red" ; + fill fullcircle scaled 6 withcolor .5\MPcolor{red} ; + fill fullcircle scaled 4 shifted (-4,0) withcolor \MPcolor{DemoTwo} ; + fill fullcircle scaled 4 shifted ( 4,0) withcolor "DemoTwo" ; + fill fullcircle scaled 2 withcolor "DemoOne" ; + fill fullcircle scaled 1 withcolor \MPcolor{NumberColor} ; + currentpicture := currentpicture xysized(5cm,3cm) ; + \stopMPcode +\egroup +\hskip1cm +\startMPcode + fill fullcircle scaled 10 withcolor "NumberColor" ; + fill fullcircle scaled 7 withcolor "red" ; + fill fullcircle scaled 6 withcolor .5\MPcolor{red} ; + fill fullcircle scaled 4 shifted (-4,0) withcolor \MPcolor{DemoTwo} ; + fill fullcircle scaled 4 shifted ( 4,0) withcolor "DemoTwo" ; + fill fullcircle scaled 2 withcolor "DemoOne" ; + fill fullcircle scaled 1 withcolor \MPcolor{NumberColor} ; + currentpicture := currentpicture xysized(5cm,3cm) ; +\stopMPcode +\stopbuffer + +The following example was used when developing the string based color resolver. +The complication was in getting the color palets resolved right without too much +overhead. Again we demonstrate this because border cases might occur that are not +catched (yet). + +\startlinecorrection + \hbox {\getbuffer} +\stoplinecorrection + +\stopsection + +\startsection[title=Transparency] + +Transparency is supported at the \TEX\ end: either or not bound to colors. We +already saw how to use colors, here's how to apply transparency: + +\startbuffer +\startMPcode + fill fullsquare xyscaled (4cm,2cm) randomized 5mm + withcolor "darkred" ; + fill fullsquare xyscaled (2cm,4cm) randomized 5mm + withcolor "darkblue" withtransparency ("normal",0.5) ; + + fill fullsquare xyscaled (4cm,2cm) randomized 5mm shifted (45mm,0) + withcolor "darkred" withtransparency ("normal",0.5) ; + fill fullsquare xyscaled (2cm,4cm) randomized 5mm shifted (45mm,0) + withcolor "darkblue" withtransparency ("normal",0.5) ; + + fill fullsquare xyscaled (4cm,2cm) randomized 5mm shifted (90mm,0) + withcolor "darkred" withtransparency ("normal",0.5) ; + fill fullsquare xyscaled (2cm,4cm) randomized 5mm shifted (90mm,0) + withcolor "darkblue" ; +\stopMPcode +\stopbuffer + +\typebuffer + +We get a mixture of normal and transparent colors. Instead of \type {normal} +you can also pass a number (with \type {1} being \type {normal}). + +\startlinecorrection + \getbuffer +\stoplinecorrection + +\stopsection + +\startsection[title=Shading] + +Shading is available too. This mechanism is a bit more complex deep down because +it needs resources as well as shading vectors that adapt themselves to the current +scale. We will not go into detail about the shading properties here. + +\startbuffer +\startMPcode + comment("two shades with mp colors"); + fill fullcircle scaled 5cm + withshademethod "circular" + withshadevector (2cm,1cm) + withshadecenter (.1,.5) + withshadedomain (.2,.6) + withshadefactor 1.2 + withshadecolors (red,white) + ; + fill fullcircle scaled 5cm shifted (6cm,0) + withshademethod "circular" + withcolor "red" shadedinto "blue" + ; +\stopMPcode +\stopbuffer + +\typebuffer + +You can use normal \METAPOST\ colors as well as named colors. + +\startlinecorrection + \getbuffer +\stoplinecorrection + +\startbuffer +\startMPcode + comment("two shades with named colors"); + fill fullcircle scaled 5cm + withshademethod "circular" + withshadecolors ((1,0,0),(0,0,1,0)) + ; + fill fullcircle scaled 5cm shifted (6cm,0) + withshademethod "circular" + withcolor (1,0,0,0) shadedinto "blue" + ; +\stopMPcode +\stopbuffer + +The color space of the first color determines if the second one needs +to be converted, so this is valid: + +\typebuffer + +The first circle is in \RGB\ colors and the second in \CMYK. + +\startlinecorrection + \getbuffer +\stoplinecorrection + +You cannot use spot colors but you can use transparency, so with: + +\startbuffer +\startMPcode + comment("three transparent shades"); + fill fullcircle scaled 5cm + withshademethod "circular" + withshadecolors ("red","green") + withtransparency ("normal",0.5) + ; + fill fullcircle scaled 5cm shifted (30mm,0) + withshademethod "circular" + withshadecolors ("green","blue") + withtransparency ("normal",0.5) + ; + fill fullcircle scaled 5cm shifted (60mm,0) + withshademethod "circular" + withshadecolors ("blue","yellow") + withtransparency ("normal",0.5) + ; +\stopMPcode +\stopbuffer + +\typebuffer + +we get: + +\startlinecorrection + \getbuffer +\stoplinecorrection + +You can define a shade and use it later on, for example: + +\startbuffer +\startMPcode + defineshade myshade + withshademethod "circular" + withshadefactor 1 + withshadedomain (0,1) + withshadecolors (black,white) + withtransparency (1,.5) + ; + + fill fullcircle xyscaled(.75TextWidth,4cm) + shaded myshade ; + fill fullcircle xyscaled(.75TextWidth,4cm) shifted (.125TextWidth,0) + shaded myshade ; + fill fullcircle xyscaled(.75TextWidth,4cm) shifted (.25TextWidth,0) + shaded myshade ; +\stopMPcode +\stopbuffer + +\typebuffer + +This gives three transparent shaded shapes: + +\startlinecorrection + \getbuffer +\stoplinecorrection + +A very special shade is the following: + +\startbuffer +\startMPcode + fill fullsquare yscaled 5ExHeight xscaled TextWidth + 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) + ) + ; +\stopMPcode +\stopbuffer + +\typebuffer + +The result is a colorful band: + +\startlinecorrection + \getbuffer +\stoplinecorrection + +\stopsection + +\startsection[title=Text] + +The text typeset with \type {textext} is processed in \TEX\ using the +current settings. A text can of course have color directives embedded. + +\startbuffer +\startMPcode +numeric u ; u := 8mm ; +draw thetextext("RED", (0,0u)) withcolor darkred ; +draw thetextext("\darkgreen GREEN", (0,1u)) ; +draw thetextext("\darkblue BLUE", (0,2u)) withcolor darkred ; +draw thetextext("BLACK {\darkgreen GREEN}",(0,3u)) ; +draw thetextext("RED {\darkblue BLUE}",(0,4u)) withcolor darkred ; +\stopMPcode +\stopbuffer + +\typebuffer + +In this example we demonstrate that you can also apply a color to the +resulting picture. + +\startlinecorrection +\tttfd \getbuffer +\stoplinecorrection + +\stopsection + +\startsection[title=Helpers] + +\stopsection + +There are several color related macros in \METAFUN\ and these are discussed +in the \METAFUN\ manual, so we only mention a few here. + +\startbuffer +\startMPcode + fill fullsquare xyscaled(TextWidth,4cm) + withcolor darkred ; + fill fullsquare xyscaled(TextWidth,3cm) + withcolor complementary darkred ; + fill fullsquare xyscaled(TextWidth,2cm) + withcolor complemented darkred ; + fill fullsquare xyscaled(TextWidth,1cm) + withcolor grayed darkred ; +\stopMPcode +\stopbuffer + +\typebuffer + +This example code is shown in \in {figure} [fig:complemen-1]. The \type +{complementary} operator subtracts the given color from white, the \type +{complemented} operator calculates its values from opposites (so a zero becomes a +one). In \in {figure} [fig:complemen-2] a more extensive example is shown. + +\startplacefigure + [reference=fig:complemen-1, + title={The \type {complementary}, \type {complemented} and \type + {grayed} methodscompared.}] + \getbuffer +\stopplacefigure + +\startMPdefinitions + % This is an old example I had laying around since 2005. The original was just + % a framed text with the graphic as background but here I use textext instead. + def MyCompare (text method) = + + picture p ; p := textext("\quad \bf + I don't understand about complementary colors\quad + And what they say\quad + Side by side they both get bright\quad + Together they both get gray\quad" + ) ; + + numeric w ; w := bbwidth p ; + numeric h ; h := bbheight p ; + + for i = 1 upto 10 : + fill fullsquare + xscaled (w/10) + yscaled 5h + shifted (-w/2-w/20+i*w/10,-3h/2) + withcolor (i*red/10) + withtransparency(1,.5) ; + fill fullsquare + xscaled (w/10) + yscaled 5h + shifted (-w/2-w/20+i*w/10,3h/2) + withcolor method (i*red/10) + withtransparency(1,.5) ; + endfor ; + addbackground withcolor .75white ; + + draw p withcolor white ; + + currentpicture := currentpicture xsized TextWidth ; + enddef ; +\stopMPdefinitions + +\startplacefigure[reference=fig:complemen-2,title={Two methods to complement colors compared (text: Fiona Apple).}] + \startcombination[1*2] + {\startMPcode MyCompare(complemented) ; \stopMPcode} {complemented} + {\startMPcode MyCompare(complementary) ; \stopMPcode} {complementary} + \stopcombination +\stopplacefigure + +As we discussed before, the different color models in \METAPOST\ cannot be mixed +in expressions. We therefore have two macros that expand into white or black +in the right colorspace. + +\typebuffer + +\startbuffer +\startMPcode + fill fullsquare xyscaled(TextWidth,4cm) + withcolor .5[(.5,0,0), whitecolor (.5,0,0)] ; + fill fullsquare xyscaled(TextWidth,3cm) + withcolor .5[(.5,0,0), blackcolor (.5,0,0)] ; + fill fullsquare xyscaled(TextWidth,2cm) + withcolor .5[(.5,0,0,0), whitecolor (.5,0,0,0)] ; + fill fullsquare xyscaled(TextWidth,1cm) + withcolor .5[(.5,0,0,0), blackcolor (.5,0,0,0)] ; +\stopMPcode +\stopbuffer + +\typebuffer + +\startlinecorrection +\getbuffer +\stoplinecorrection + +There are two macros that can be used to resolve string to colors: \type +{resolvedcolor} and \type {namedcolor}. A resolved color is expanded via \LUA\ +while a named color is handled in the backend, when the result is converted to +\PDF. The resolved approach is more recent and is the same as a string color +specification. + +\startbuffer +\startMPcode + fill fullcircle scaled 4cm withcolor .5 resolvedcolor "darkred" ; + fill fullcircle scaled 3cm withcolor .5 resolvedcolor "gray" ; + fill fullcircle scaled 2cm withcolor .5 namedcolor "darkblue" ; + fill fullcircle scaled 1cm withcolor .5 namedcolor "gray" ; +\stopMPcode +\stopbuffer + +\typebuffer + +\startlinecorrection +\getbuffer +\stoplinecorrection + +There is a \type {drawoptions} macro that can be used to define properties in one go. + +\startbuffer +\startMPcode + drawoptions(withcolor "darkgreen"); + fill fullcircle scaled 4cm ; + fill fullcircle scaled 3cm withcolor white ; + fill fullcircle scaled 2cm ; +\stopMPcode +\stopbuffer + +\typebuffer + +We get: + +\startlinecorrection +\getbuffer +\stoplinecorrection + +The drawback of this approach is that, because we use so called pre- and +postscripts for achieving special effects (like spotcolors and shading) +successive \type {withcolor} calls can interfere in a way that unexpected results +turn up. A way out is to use properties: + +\startbuffer +\startMPcode + property p[] ; + p1 = properties(withcolor "darkred") ; + p2 = properties(withcolor "white") ; + fill fullcircle scaled 4cm withproperties p1 ; + fill fullcircle scaled 3cm withproperties p2 ; + fill fullcircle scaled 2cm withproperties p1 ; +\stopMPcode +\stopbuffer + +\typebuffer + +This results in: + +\startlinecorrection +\getbuffer +\stoplinecorrection + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/colors/colors-mkiv.tex b/doc/context/sources/general/manuals/colors/colors-mkiv.tex new file mode 100644 index 000000000..064758ba3 --- /dev/null +++ b/doc/context/sources/general/manuals/colors/colors-mkiv.tex @@ -0,0 +1,54 @@ +% 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. + +% \nopdfcompression + +\enablemode[simple] % ,oversized + +\startbuffer[abstract] + + This book is about colors and how to use them in \CONTEXT\ \MKIV, including + \METAFUN. Although the basics are not that complex, a bit of insight in how + they are implemented and what can be done might help in creating more + interesting looking documents. + +\stopbuffer + +\environment colors-environment + +\startdocument + [author=Hans Hagen, + title=Coloring \ConTeXt, + subtitle=explaining luatex and mkiv, + affiliation=PRAGMA ADE, + comment=work in progress, + cover:color:1=darkgreen, + cover:color:2=darkyellow, + cover:color:3=darkblue, + cover:color:4=darkmagenta, + cover:color:5=darkgray] + + \startfrontmatter + \component manuals-explaining-contents + \component colors-introduction + \stopfrontmatter + + \startbodymatter + \component colors-basics + \component colors-metafun + \component colors-graphics + \stopbodymatter + +\stopdocument diff --git a/doc/context/sources/general/manuals/luatex/luatex.tex b/doc/context/sources/general/manuals/luatex/luatex.tex index f571515ae..90484aa7e 100644 --- a/doc/context/sources/general/manuals/luatex/luatex.tex +++ b/doc/context/sources/general/manuals/luatex/luatex.tex @@ -13,7 +13,7 @@ \startdocument [%status=release, - version=1.0.0] + version=1.0.1] \component luatex-titlepage diff --git a/doc/context/sources/general/manuals/math/math-mkiv.tex b/doc/context/sources/general/manuals/math/math-mkiv.tex index d9785c8a8..291a99c9e 100644 --- a/doc/context/sources/general/manuals/math/math-mkiv.tex +++ b/doc/context/sources/general/manuals/math/math-mkiv.tex @@ -32,6 +32,7 @@ \component math-numbering \component math-combining \component math-features + \component math-tricks \stopbodymatter \stopdocument diff --git a/doc/context/sources/general/manuals/spreadsheets/spreadsheets-mkiv.tex b/doc/context/sources/general/manuals/spreadsheets/spreadsheets-mkiv.tex new file mode 100644 index 000000000..4dfd133ad --- /dev/null +++ b/doc/context/sources/general/manuals/spreadsheets/spreadsheets-mkiv.tex @@ -0,0 +1,756 @@ +% 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. + +\usemodule[spreadsheet] +\usemodule[art-01,abr-02] + +\definecolor[darkred] [r=.4] +\definecolor[darkgreen][g=.4] +\definecolor[darkblue] [b=.4] + +\definecolor[maincolor] [darkred] +\definecolor[extracolor][darkblue] + +\setuptyping + [color=extracolor] + +\setuptype + [color=extracolor] + +\setuphead + [section] + [color=maincolor] + +\setupbodyfont + [10pt] + +\setupinteraction + [hidden] + +% \setupnumbering +% [alternative=doublesided] + +\startdocument + [metadata:author=Hans Hagen, + metadata:title=Simple Spreadsheets, + author=Hans Hagen, + affiliation=PRAGMA ADE, + location=Hasselt NL, + title=Simple Spreadsheets, + extra=ConTeXt MkIV, + support=www.contextgarden.net, + website=www.pragma-ade.nl] + +\startMPpage + + StartPage; + + numeric n, m ; n := 3 * 4 ; m := 4 * 4 ; + numeric w, h ; w := PaperWidth/n ; h := PaperHeight/m ; + + for i=1 upto n : + for j=1 upto m : + fill + unitsquare + xysized (w,h) + shifted ((i-1)*w,(j-1)*h) + withcolor .5[i*red/n,j*blue/m] + ; + endfor ; + endfor ; + + for i=1 upto n : + for j=1 upto m : + draw + textext("\tt" & char(64+i) & if j < 10 : "0" else : "" fi & decimal j) + xysized (.7*w,.7*h) + shifted (i*w-.5w,(m+1-j)*h-.5h) + withcolor .5[(n+1-i)*green/n,(m+1-j)*yellow/m] + ; + endfor ; + endfor ; + + draw + textext.llft("\ssbf{\documentvariable{title}}") + xsized (PaperHeight-h) + rotated 90 + shifted (PaperWidth-1.75w,PaperHeight-h/2) + withcolor white + ; + + draw + textext.llft("\ssbf{\documentvariable{extra}}") + ysized (h/2) + shifted (PaperWidth-2.5w,3.75h) + withcolor white + ; + + + draw + textext.llft("\ssbf{\documentvariable{author}}") + ysized (h/2) + shifted (PaperWidth-2.5w,2.75h) + withcolor white + ; + + draw + textext.llft("\ssbf \currentdate") + ysized (h/2) + shifted (PaperWidth-2.5w,1.75h) + withcolor white + ; + + StopPage; + +\stopMPpage + +% \page[empty] \setuppagenumber[start=1] + +\startsubject[title={Contents}] + +\placelist[section][criterium=all,interaction=all] + +\stopsubject + +\startsection [title={Introduction}] + +Occasionally a question pops up on the \CONTEXT\ mailing list and answering it +becomes a nice distraction from a boring task at hand. The spreadsheet module is +the result of such a diversion. As with more support code in \CONTEXT, this is +not a replacement for \quote {the real thing} but just a nice feature for simple +cases. The module is loaded with + +\starttyping +\usemodule[spreadsheet] +\stoptyping + +So this is (at least currently) not one of the core functionalities but an +add||on. Of course some useful extensions might appear in the future. + +\stopsection + +\startsection [title={Spreadsheet tables}] + +We can use \LUA\ in each cell, because under the hood it is all \LUA. There is +some basic parsing applied so that we can use the usual \type {A..Z} variables to +access cells. + +\startbuffer[demo] +\startspreadsheettable[test] + \startrow + \startcell 1.1 \stopcell + \startcell 2.1 \stopcell + \startcell A[1] + B[1] \stopcell + \stoprow + \startrow + \startcell 2.1 \stopcell + \startcell 2.2 \stopcell + \startcell A[2] + B[2] \stopcell + \stoprow + \startrow + \startcell A[1] + B[1] \stopcell + \startcell A[2] + B[2] \stopcell + \startcell A[3] + B[3] \stopcell + \stoprow +\stopspreadsheettable +\stopbuffer + +\typebuffer[demo] + +The rendering is shown in \in {figure} [spreadsheet:1]. Keep in mind that in +\LUA\ all calculations are done using floats, at least in \LUA\ versions with +version numbers preceding 5.3. + +\placefigure + [here] + [spreadsheet:1] + {A simple spreadsheet.} + {\getbuffer[demo]} + +The last cell can also look like this: + +\starttyping +\startcell +function() + local s = 0 + for i=1,2 do + for j=1,2 do + s = s + dat[i][j] + end + end + return s +end +\stopcell +\stoptyping + +The content of a cell is either a number or a function. In this example +we just loop over the (already set) cells and calculate their sum. The +\type {dat} variable accesses the grid of cells. + +\starttyping +\startcell +function() + local s = 0 + for i=1,2 do + for j=1,2 do + s = s + dat[i][j] + end + end + tmp.total = s +end +\stopcell +\stoptyping + +In this variant we store the sum in the table \type {tmp} which is local to the +current sheet. Another table is \type {fnc} where we can store functions. This +table is shared between all sheets. There are two predefined functions: + +\starttyping +sum(columnname,firstrow,lastrow) +fmt(specification,n) +\stoptyping + +The \type {sum} function works top||down in columns, and roughly looks like +this: + +\starttyping +function sum(currentcolumn,firstrow,lastrow) + local r = 0 + for i = firstrow, lastrow do + r = r + cells[currentcolumn][i] + end + return r +end +\stoptyping + +The last two arguments are optional: + +\starttyping +sum(columnname,lastrow) +\stoptyping + +This is equivalent to: + +\starttyping +function sum(currentcolumn,lastrow) + local r = 0 + for i = 1, lastrow do + r = r + cells[currentcolumn][i] + end + return r +end +\stoptyping + +While: + +\starttyping +sum(columnname) +\stoptyping + +boils down to: + +\starttyping +function sum(currentcolumn) + local r = 0 + for i = 1, currentrow do + r = r + cells[currentcolumn][i] + end + return r +end +\stoptyping + +Empty cells or cells that have no numbers are skipped. Let's now see these +functions in action: + +\startbuffer[demo] +\startspreadsheettable[test] + \startrow + \startcell 1.1 \stopcell \startcell 2.1 \stopcell + \stoprow + \startrow + \startcell 2.1 \stopcell \startcell 2.2 \stopcell + \stoprow + \startrow + \startcell + function() + local s = 0 + for i=1,2 do + for j=1,2 do + s = s + dat[i][j] + end + end + context.bold(s) + end + \stopcell + \startcell + function() + local s = 1 + for i=1,2 do + for j=1,2 do + s = s * dat[i][j] + end + end + context.bold(fmt("@.1f",s)) + end + \stopcell + \stoprow +\stopspreadsheettable +\stopbuffer + +\typebuffer[demo] + +The result is shown in \in {figure} [spreadsheet:2]. Watch the \type {fmt} call: +we use an at sign instead of a percent to please \TEX. + +\placefigure + [here] + [spreadsheet:2] + {Cells can be (complex) functions.} + {\getbuffer[demo]} + +Keep in mind that we're typesetting and that doing complex calculations is not +our main objective. A typical application of this module is in making bills, for +which you can combine it with the correspondence modules. We leave that as an +exercise for the reader and stick to a simple example. + +\startbuffer[demo] +\startspreadsheettable[test] + \startrow + \startcell[align=flushleft,width=8cm] "item one" \stopcell + \startcell[align=flushright,width=3cm] @ "0.2f EUR" 3.50 \stopcell + \stoprow + \startrow + \startcell[align=flushleft] "item two" \stopcell + \startcell[align=flushright] @ "0.2f EUR" 8.45 \stopcell + \stoprow + \startrow + \startcell[align=flushleft] "tax 19\percent" \stopcell + \startcell[align=flushright] @ "0.2f EUR" 0.19 * (B[1]+B[2]) \stopcell + \stoprow + \startrow + \startcell[align=flushleft] "total 1" \stopcell + \startcell[align=flushright] @ "0.2f EUR" sum(B,1,3) \stopcell + \stoprow + \startrow + \startcell[align=flushleft] "total 2" \stopcell + \startcell[align=flushright] @ "0.2f EUR" B[1] + B[2] + B[3] \stopcell + \stoprow + \startrow + \startcell[align=flushleft] "total 3" \stopcell + \startcell[align=flushright] @ "0.2f EUR" sum(B) \stopcell + \stoprow +\stopspreadsheettable +\stopbuffer + +\typebuffer[demo] + +Here (and in \in {figure} [spreadsheet:8]) you see a quick and more +readable way to format cell content. The \type {@} in the template is +optional, but needed in cases like this: + +\starttyping +@ "(@0.2f) EUR" 8.45 +\stoptyping + +A \type {@} is only prepended when no \type {@} is given in the template. + +\placefigure + [here] + [spreadsheet:8] + {Cells can be formatted by using \type {@} directives.} + {\getbuffer[demo]} + +In practice this table we can be less specific and let \type {\sum} behave more +automatical. That way the coding can be simplified (see \in {figure} +[spreadsheet:7]) and also look nicer. + +\startbuffer[demo] +\startspreadsheettable[test][frame=off] + \startrow + \startcell[align=flushleft,width=8cm] "The first item" \stopcell + \startcell[align=flushright,width=3cm] @ "0.2f EUR" 3.50 \stopcell + \stoprow + \startrow + \startcell[align=flushleft] "The second item" \stopcell + \startcell[align=flushright] @ "0.2f EUR" 8.45 \stopcell + \stoprow + \startrow + \startcell[align=flushleft] "The third item" \stopcell + \startcell[align=flushright] @ "0.2f EUR" 5.90 \stopcell + \stoprow + \startrow[topframe=on] + \startcell[align=flushleft] "VAT 19\percent" \stopcell + \startcell[align=flushright] @ "0.2f EUR" 0.19 * sum(B) \stopcell + \stoprow + \startrow[topframe=on] + \startcell[align=flushleft] "\bf Grand total" \stopcell + \startcell[align=flushright] @ "0.2f EUR" sum(B) \stopcell + \stoprow +\stopspreadsheettable +\stopbuffer + +\typebuffer[demo] + +\placefigure + [here] + [spreadsheet:7] + {The \type {sum} function accumulates stepwise.} + {\getbuffer[demo]} + +There are a few more special start characters. This is demonstrated in \in +{figure} [spreadsheet:9]. An \type {=} character is ignored. \footnote {Taco +suggested to support this because some spreadsheet programs use that character to +flush a value.} When we start with an \type {!}, the content is not typeset. +Strings can be surrounded by single or double quotes and are not really +processed. + +\startbuffer[demo] +\startspreadsheettable[test][offset=1ex] + \startrow + \startcell[align=flushleft] "first" \stopcell + \startcell[align=flushleft] '\type{@ "[@i]" 1}' \stopcell + \startcell[align=flushright,width=3cm] @ "[@i]" 1 \stopcell + \stoprow + \startrow + \startcell[align=flushleft] "second" \stopcell + \startcell[align=flushleft] '\type{= 2}' \stopcell + \startcell[align=flushright] = 2 \stopcell + \stoprow + \startrow + \startcell[align=flushleft] "third" \stopcell + \startcell[align=flushleft] '\type{! 3}' \stopcell + \startcell[align=flushright] ! 3 \stopcell + \stoprow + \startrow + \startcell[align=flushleft] "fourth" \stopcell + \startcell[align=flushleft] '\type{4}' \stopcell + \startcell[align=flushright] 4 \stopcell + \stoprow + \startrow + \startcell[align=flushleft] "\bf total one" \stopcell + \startcell[align=flushleft] '\type{sum(C)}' \stopcell + \startcell[align=flushright] sum(C) \stopcell + \stoprow + \startrow + \startcell[align=flushleft] "\bf total two" \stopcell + \startcell[align=flushleft] '\type{= sum(C)}' \stopcell + \startcell[align=flushright] = sum(C) \stopcell + \stoprow +\stopspreadsheettable +\stopbuffer + +\typebuffer[demo] + +The \type {sum} function is clever enough not to include itself in the +summation. Only preceding cells are taken into account, given that they +represent a number. + +\placefigure + [here] + [spreadsheet:9] + {Cells can be hidden by \type {!} and can contain strings only.} + {\getbuffer[demo]} + +\stopsection + +\startsection [title={Normal tables}] + +In the previous examples we used \TEX\ commands for structuring the sheet but +the content of cells is \LUA\ code. It is also possible to stick to a regular +table and use specific commands to set and get cell data. + +\startbuffer[demo] +\bTABLE[align=middle] + \bTR + \bTD \getspr{100} \eTD \bTD test \setspr{30} \eTD + \eTR + \bTR + \bTD \getspr{20} \eTD \bTD \getspr{4+3} \eTD + \eTR + \bTR + \bTD \getspr{A[1] + A[2]} \eTD + \bTD \getspr{B1 + B2} \eTD + \eTR + \bTR + \bTD[nx=2] \bf \getspr{(A[3] + B[3]) /100} \eTD + \eTR + \bTR + \bTD[nx=2] \bf \getspr{fmt("@0.3f",(A[3] + B[3]) /100)} \eTD + \eTR + \bTR + \bTD[nx=2] \bf \getspr{fmt("@0.3f",(sum(A,1,2)) / 10)} \eTD + \eTR +\eTABLE +\stopbuffer + +\typebuffer[demo] + +The method to use depends on the complexity of the table. If there is +more text than data then this method is probably more comfortable. + +\placefigure + [here] + [spreadsheet:3] + {A sheet can be filled and accessed from regular tables.} + {\getbuffer[demo]} + +% \setupspreadsheet[mysheet] +% +% \startspreadsheet[mysheet] +% +% \bTABLE[align=middle] +% \bTR +% \bTD \getspr{100} \eTD \bTD test \setspr{30} \eTD +% \eTR +% \bTR +% \bTD \getspr{20} \eTD \bTD \getspr{4+3.5} \eTD +% \eTR +% \bTR +% \bTD \getspr{A[1] + A[2]} \eTD +% \bTD \getspr{B[1] + B[2]} \eTD +% \eTR +% \bTR +% \bTD[nx=2] \bf \getspr{A[3] + B[3]} \eTD +% \eTR +% \eTABLE +% +% \stopspreadsheet + +\stopsection + +\startsection[title={A few settings}] + +It's possible to influence the rendering. The following example demonstrates +this. We don't use any formatting directives. + +\startbuffer[demo] +\startspreadsheettable[test] + \startrow + \startcell 123456.78 \stopcell + \stoprow + \startrow + \startcell 1234567.89 \stopcell + \stoprow + \startrow + \startcell A[1] + A[2] \stopcell + \stoprow +\stopspreadsheettable +\stopbuffer + +\typebuffer[demo] + +\placefigure + [here] + [spreadsheet:4] + {Formatting (large) numbers.} + {\getbuffer[demo]} + +\in {Figure} [spreadsheet:4] demonstrates how this gets rendered by +default. However, often you want numbers to be split in parts separated by +periods and commas. This can be done as follows: + +\startbuffer[setup] +\definehighlight[BoldAndRed] [style=bold,color=darkred] +\definehighlight[BoldAndGreen][style=bold,color=darkgreen] + +\setupspreadsheet + [test] + [period={\BoldAndRed{.}}, + comma={\BoldAndGreen{,}}, + split=yes] +\stopbuffer + +\typebuffer[setup] \getbuffer[setup] + +\placefigure + [here] + [spreadsheet:5] + {Formatting (large) numbers with style and color.} + {\getbuffer[setup,demo]} + +\stopsection + +\startsection[title={The \LUA\ end}] + +You can also use spreadsheets from within \LUA. The following example is +rather straightforward: + +\startbuffer[demo-a] +\startluacode +context.startspreadsheettable { "test" } + context.startrow() + context.startcell() context("123456.78") context.stopcell() + context.stoprow() + context.startrow() + context.startcell() context("1234567.89") context.stopcell() + context.stoprow() + context.startrow() + context.startcell() context("A[1] + A[2]") context.stopcell() + context.stoprow() +context.stopspreadsheettable() +\stopluacode +\stopbuffer + +\typebuffer[demo-a] + +However, even more \LUA|-|ish is the next variant: + +\startbuffer[demo-b] +\startluacode + local set = moduledata.spreadsheets.set + local get = moduledata.spreadsheets.get + + moduledata.spreadsheets.start("test") + set("test",1,1,"123456.78") + set("test",2,1,"1234567.89") + set("test",3,1,"A[1] + A[2]") + moduledata.spreadsheets.stop() + + context.bTABLE() + context.bTR() + context.bTD() context(get("test",1,1)) context.eTD() + context.eTR() + context.bTR() + context.bTD() context(get("test",2,1)) context.eTD() + context.eTR() + context.bTR() + context.bTD() context(get("test",3,1)) context.eTD() + context.eTR() + context.eTABLE() +\stopluacode +\stopbuffer + +\typebuffer[demo-b] + +Of course the second variant does not make much sense as we can do this way +more efficient by not using a spreadsheet at all: + +\startbuffer[demo-c] +\startluacode + local A1, A2 = 123456.78, 1234567.89 + context.bTABLE() + context.bTR() + context.bTD() context(A1) context.eTD() + context.eTR() + context.bTR() + context.bTD() context(A2) context.eTD() + context.eTR() + context.bTR() + context.bTD() context(A1+A2) context.eTD() + context.eTR() + context.eTABLE() +\stopluacode +\stopbuffer + +\typebuffer[demo-c] + +You can of course use format explicitly. Here we use the normal percent +directives because we're in \LUA, and not in \TEX, where percentage +signs are a bit of an issue. + +\startbuffer[demo-d] +\startluacode + local A1, A2 = 123456.78, 1234567.89 + local options = { align = "flushright" } + context.bTABLE() + context.bTR() + context.bTD(options) + context("%0.2f",A1) + context.eTD() + context.eTR() + context.bTR() + context.bTD(options) + context("%0.2f",A2) + context.eTD() + context.eTR() + context.bTR() + context.bTD(options) + context("%0.2f",A1+A2) + context.eTD() + context.eTR() + context.eTABLE() +\stopluacode +\stopbuffer + +\typebuffer[demo-d] + +As expected and shown in \in {figure} [spreadsheet:6], only the first and last +variant gets the numbers typeset nicely. + +\placefigure + [here] + [spreadsheet:6] + {Spreadsheets purely done as \CONTEXT\ \LUA\ Document.} + {\startcombination[4*1] + {\getbuffer[demo-a]} {} + {\getbuffer[demo-b]} {} + {\getbuffer[demo-c]} {} + {\getbuffer[demo-d]} {} + \stopcombination} + +\stopsection + +\startsection[title={Helper macros}] + +There are two helper macros that you can use to see what is stored in a +spreadsheet: + +\starttyping +\inspectspreadsheet[test] +\showspreadsheet [test] +\stoptyping + +The first command reports the content of \type {test} to the console, and +the second one typesets it in the running text: + +\blank +\showspreadsheet[test] +\blank + +Another helper function is \type {\doifelsespreadsheetcell}, You can use this +one to check if a cell is set. + +\startbuffer[demo] +(1,1): \doifelsespreadsheetcell[test]{1}{1}{set}{unset} +(2,2): \doifelsespreadsheetcell[test]{2}{2}{set}{unset} +(9,9): \doifelsespreadsheetcell[test]{9}{9}{set}{unset} +\stopbuffer + +\typebuffer[demo] + +This gives: + +\startlines +\getbuffer[demo] +\stoplines + +There is not much more to say about this module, apart from that it is a +nice example of a \TEX\ and \LUA\ mix. Maybe some more (basic) functionality +will be added in the future but it all depends on usage. + +\stopsection + +\startsubject[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 + +\stopsubject + +\stopdocument |