diff options
Diffstat (limited to 'doc/context/sources/general/manuals/swiglib/swiglib-mkiv.tex')
| -rw-r--r-- | doc/context/sources/general/manuals/swiglib/swiglib-mkiv.tex | 335 |
1 files changed, 335 insertions, 0 deletions
diff --git a/doc/context/sources/general/manuals/swiglib/swiglib-mkiv.tex b/doc/context/sources/general/manuals/swiglib/swiglib-mkiv.tex new file mode 100644 index 000000000..fc7a269bb --- /dev/null +++ b/doc/context/sources/general/manuals/swiglib/swiglib-mkiv.tex @@ -0,0 +1,335 @@ +% language=uk + +% author : Hans Hagen, PRAGMA ADE, NL +% license : Creative Commons, Attribution-NonCommercial-ShareAlike 3.0 Unported + +\usemodule[art-01,abr-02] + +\definecolor + [maincolor] + [r=.4] + +\definecolor + [extracolor] + [g=.4] + +\setupbodyfont + [11pt] + +\setuptype + [color=maincolor] + +\setuptyping + [color=maincolor] + +\definefontsynonym + [TitlePageMono] + [file:lmmonoproplt10-bold*default] + +\setuphead + [color=maincolor] + +\usesymbols + [cc] + +\setupinteraction + [hidden] + +\loadfontgoodies[lm] + +\startdocument + [metadata:author=Hans Hagen, + metadata:title=SwigLib basics, + author=Hans Hagen, + affiliation=PRAGMA ADE, + location=Hasselt NL, + title=SwigLib basics, + support=www.contextgarden.net, + website=www.pragma-ade.nl] + +\startluasetups[swiglib] + for i=1,640 do + context.definedfont { string.formatters["TitlePageMono at %p"](65536*(10+math.random(5))) } + context("SwigLib ") + end + context.removeunwantedspaces() +\stopluasetups + +\startMPpage + +StartPage ; + + fill Page enlarged 1cm withcolor \MPcolor{extracolor} ; + + draw textext("\framed[loffset=2pt,roffset=2pt,frame=off,width=\paperwidth,align={normal,paragraph,verytolerant,stretch}]{\luasetup{swiglib}}") + xysized (PaperWidth,PaperHeight) + shifted center Page + withcolor .8white ; + + draw textext.ulft("\definedfont[TitlePageMono]basics") + xsized .75PaperWidth + shifted lrcorner Page + shifted (-1cm,2cm) + withcolor \MPcolor{maincolor} ; + +% draw textext.ulft("\definedfont[TitlePageMono]in context mkiv") +% xsized .6PaperWidth +% shifted lrcorner Page +% shifted (-1cm,6cm) +% withcolor \MPcolor{maincolor} ; + +StopPage ; + +\stopMPpage + +\dontcomplain + +\startsubject[title=Contents] + +\placelist[section][alternative=a] + +\stopsubject + +\startsection[title=Introduction] + +The \SWIGLIB\ project is related to \LUATEX\ and aims as adding portable library +support to this \TEX\ engine without too much fixed binding. The project does not +provide \LUA\ code, unless really needed, because it assumes that macro packages +have different demands. It also fits in the spirit of \TEX\ and \LUA\ to minimize +the core components. + +The technical setup is by Luigi Scarso and documentation about how to build the +libraries is part of the \SWIGLIB\ repository. Testing happens with help of the +\CONTEXT\ (garden) infrastructure. This short document only deals with usage in +\CONTEXT\ but also covers rather plain usage. + +\blank \start \em todo: reference to Luigi's manual \stop \blank + +\stopsection + +\startsection[title=Inside \CONTEXT] + +The recommended way to load a library in \CONTEXT\ is by using the +\type {swiglib} function. This function lives in the global namespace. + +\starttyping +local gm = swiglib("gmwand.core") +\stoptyping + +After this call you have the functionality available in the \type {gm} +namespace. This way of loading makes \CONTEXT\ aware that such a library +has been loading and it will report the loaded libraries as part of the +statistics. + +If you want, you can use the more ignorant \type {require} instead but in +that case you need to be more explicit. + +\starttyping +local gm = require("swiglib.gmwand.core") +\stoptyping + +Here is an example of using such a library (by Luigi): + +\startbuffer +\startluacode +local gm = swiglib("gmwand.core") +local findfile = resolvers.findfile + +gm.InitializeMagick(".") + +local magick_wand = gm.NewMagickWand() +local drawing_wand = gm.NewDrawingWand() +local pixel_wand = gm.NewPixelWand(); + +gm.MagickSetSize(magick_wand,800,600) +gm.MagickReadImage(magick_wand,"xc:gray") + +gm.DrawPushGraphicContext(drawing_wand) + +gm.DrawSetFillColor(drawing_wand,pixel_wand) + +gm.DrawSetFont(drawing_wand,findfile("dejavuserifbold.ttf")) +gm.DrawSetFontSize(drawing_wand,96) +gm.DrawAnnotation(drawing_wand,200,200,"ConTeXt 1") + +gm.DrawSetFont(drawing_wand,findfile("texgyreschola-bold.otf")) +gm.DrawSetFontSize(drawing_wand,78) +gm.DrawAnnotation(drawing_wand,250,300,"ConTeXt 2") + +gm.DrawSetFont(drawing_wand,findfile("lmroman10-bold.otf")) +gm.DrawSetFontSize(drawing_wand,48) +gm.DrawAnnotation(drawing_wand,300,400,"ConTeXt 3") + +gm.DrawPopGraphicContext(drawing_wand) + +gm.MagickDrawImage(magick_wand,drawing_wand) + +gm.MagickWriteImages(magick_wand,"./swiglib-mkiv-gm-1.png",1) +gm.MagickWriteImages(magick_wand,"./swiglib-mkiv-gm-1.jpg",1) +gm.MagickWriteImages(magick_wand,"./swiglib-mkiv-gm-1.pdf",1) + +gm.DestroyDrawingWand(drawing_wand) +gm.DestroyPixelWand(pixel_wand) +gm.DestroyMagickWand(magick_wand) +\stopluacode +\stopbuffer + +\typebuffer \getbuffer + +In practice you will probably stay away from manipulating text this way, but it +illustrates that you can use the regular \CONTEXT\ helpers to locate files. + +\startlinecorrection[big] + \startcombination[3*1] + {\externalfigure[swiglib-mkiv-gm-1.png][width=.3\textwidth]} {png} + {\externalfigure[swiglib-mkiv-gm-1.pdf][width=.3\textwidth]} {pdf} + {\externalfigure[swiglib-mkiv-gm-1.jpg][width=.3\textwidth]} {jpg} + \stopcombination +\stoplinecorrection + +You'd better make sure to use unique filenames for such graphics. Of course a more +clever mechanism would only run time consuming tasks once for each iteration of a +document. + +\stopsection + +\startsection[title=Outside \CONTEXT] + +In the \CONTEXT\ distribution we ship some generic macros and code for usage in +plain \TEX\ but there is no reason why they shouldn't work in other macro packages +as well. A rather plain example is this: + +\starttyping +\input luatex-swiglib.tex + +\directlua { + dofile("luatex-swiglib-test.lua") +} + +\pdfximage {luatex-swiglib-test.jpg} \pdfrefximage\pdflastximage + +\end +\stoptyping + +Assuming that you made the \type {luatex-plain} format, such a file can be processed using: + +\starttyping +luatex --fmt=luatex=plain luatex-swiglib-test.tex +\stoptyping + +The loaded \LUA\ file \type {luatex-swiglib-test.lua} liike like this: + +\starttyping +local gm = swiglib("gmwand.core") + +gm.InitializeMagick(".") + +local magick_wand = gm.NewMagickWand() +local drawing_wand = gm.NewDrawingWand() + +gm.MagickSetSize(magick_wand,800,600) +gm.MagickReadImage(magick_wand,"xc:red") +gm.DrawPushGraphicContext(drawing_wand) +gm.DrawSetFillColor(drawing_wand,gm.NewPixelWand()) +gm.DrawPopGraphicContext(drawing_wand) +gm.MagickDrawImage(magick_wand,drawing_wand) +gm.MagickWriteImages(magick_wand,"./luatex-swiglib-test.jpg",1) + +gm.DestroyDrawingWand(drawing_wand) +gm.DestroyMagickWand(magick_wand) +\stoptyping + +Instead of loading a library with the \type {swiglib} function, you can also +use \type {require}: + +\starttyping +local gm = require("swiglib.gmwand.core") +\stoptyping + +Watch the explicit \type {swiglib} reference. Both methods are equivalent. + +\stopsection + +\startsection[title={The libraries}] + +Most libraries are small but some can be rather large and have additional files. +This is why we keep them separated. On my system they are collected in the +platform binary tree: + +\starttyping +e:/tex-context/tex/texmf-mswin/bin/lib/luatex/lua/swiglib/gmwand +e:/tex-context/tex/texmf-mswin/bin/lib/luatex/lua/swiglib/mysql +e:/tex-context/tex/texmf-mswin/bin/lib/luatex/lua/swiglib/.... +\stoptyping + +One can modulate on this: + +\starttyping +...tex/texmf-mswin/bin/lib/luatex/lua/swiglib/mysql/core.dll +...tex/texmf-mswin/bin/lib/luajittex/lua/swiglib/mysql/core.dll +...tex/texmf-mswin/bin/lib/luatex/context/lua/swiglib/mysql/core.dll +\stoptyping + +are all valid. When versions are used you can provide an additional argument to the +\type {swiglib} loader: + +\starttyping +tex/texmf-mswin/bin/lib/luatex/lua/swiglib/mysql/5.6/core.dll +\stoptyping + +This works with: + +\starttyping +local mysql = swiglib("mysql.core","5.6") +\stoptyping + +as well as: + +\starttyping +local mysql = swiglib("mysql.core") +\stoptyping + +It is hard to predict how operating systems look up libraries and especially +nested loads, but as long as the root of the \type {swiglib} path is known to the +file search routine. We've kept the main conditions for success simple: the core +library is called \type {core.dll} or \type {core.so}. Each library has an +(automatically called) initialize function named \type {luaopen_core}. There is no +reason why (sym)links from the \type {swiglib} path to someplace else shouldn't +work. + +In \type {texmfcnf.lua} you will find an entry like: + +\starttyping +CLUAINPUTS = ".;$SELFAUTOLOC/lib/{$engine/context,$engine}/lua//" +\stoptyping + +Which in practice boils down to a search for \type {luatex} or \type {luajittex} +specific libraries. When both binaries are compatible and there are no \type +{luajittex} binaries, the regular \type {luatex} libraries will be used. + +The \type {swiglib} loader function mentioned in previous sections load libraries +in a special way: it changes dir to the specific path and then loads the library +in the usual way. After that it returns to the path where it started out. After +this, when the library needs additional libraries (and for instance graphicmagick +needs a lot of them) it will first look on its own path (which is remembered). + +The \MKIV\ lookups are somewhat more robust in the sense that they first check +for matches on engine specific paths. This comes in handy when the search +patterns are too generic and one can match on for instance \type {luajittex} +whilc \type {luatex} is used. + +\stopsection + +\startsection[title=Colofon] + +\starttabulate[|B|p|] +\NC author \NC \getvariable{document}{author}, \getvariable{document}{affiliation}, \getvariable{document}{location} \NC \NR +\NC version \NC \currentdate \NC \NR +\NC website \NC \getvariable{document}{website} \endash\ \getvariable{document}{support} \NC \NR +\NC copyright \NC \symbol[cc][cc-by-sa-nc] \NC \NR +\NC comment \NC the swiglib infrastructure is implemented by Luigi Scarso \NC \NR +\stoptabulate + +\stopsection + +\stopdocument |