diff options
Diffstat (limited to 'doc/context/sources/general')
21 files changed, 4637 insertions, 0 deletions
diff --git a/doc/context/sources/general/manuals/epub/epub-mkiv-demo.tex b/doc/context/sources/general/manuals/epub/epub-mkiv-demo.tex new file mode 100644 index 000000000..b4b979874 --- /dev/null +++ b/doc/context/sources/general/manuals/epub/epub-mkiv-demo.tex @@ -0,0 +1,43 @@ + +% \usemodule[luacalls] + +\usemodule[mathml] + +\setupexternalfigures + [location=default] + +\setupbackend + [export=yes] + +\setupexport + [svgstyle=mathtest-style, + hyphen=yes, + width=60em] + +\setupbodyfont[pagella] + +\definefloat[graphic][graphics][figure] + +% \environment [mathtest-style] + +\starttext + + \startsection[title=First] + + \startitemize + \startitem one \stopitem + \startitem two \stopitem + \stopitemize + + \startplacefigure[title=First] + \externalfigure[cow.pdf] + \stopplacefigure + + \startplacegraphic[title=Second] + \externalfigure[cow.pdf] + \stopplacegraphic + + some math: \m{e=mc^2} + + \stopsection +\stoptext diff --git a/doc/context/sources/general/manuals/epub/epub-mkiv.tex b/doc/context/sources/general/manuals/epub/epub-mkiv.tex new file mode 100644 index 000000000..6fc4ed9d4 --- /dev/null +++ b/doc/context/sources/general/manuals/epub/epub-mkiv.tex @@ -0,0 +1,466 @@ +% language=uk + +% todo: +% +% metadata +% properties +% \dontleavehmode before hbox +% cover page +% +% http://www.cnet.com/news/google-subtracts-mathml-from-chrome-and-anger-multiplies/ + +% \usemodule[luacalls] + +\usemodule[art-01,abr-02] + +\definehighlight[notabene][style=bold] + +\definecolor[darkorange] [.70(green,red)] +\definecolor[lightorange][.45(orange,white)] +\definecolor[lesswhite] [.90(white)] + +\setuptyping[color=darkorange] +\setuptype [color=darkorange] + +\starttext + +\startMPpage + +numeric w ; w := 21cm ; +numeric h ; h := 29.7cm ; +numeric ww ; ww := 9w/10 ; +numeric oo ; oo := (w-ww) / 2 ; +numeric hh ; hh := h/5.5 ; +path p ; p := unitsquare xysized(w,h) ; + +color orange ; orange := \MPcolor{darkorange} ; % .7[green,red] ; + +fill p enlarged 2mm withcolor orange ; + +draw image ( + draw anchored.top( + textext("\ttbf\setupinterlinespace[line=1.7ex]\framed[frame=off,align=middle,offset=0mm]{\smash{<div/>}\\\smash{<div >}\\\smash{</div>}}") + xsized w, + center topboundary p shifted (0,-12mm)) withcolor \MPcolor{lightorange} ; % 0.45[white,orange] ; + draw anchored.bot( + textext("\ssbf\setupinterlinespace[line=2.2ex]\framed[frame=off,align=middle]{exporting\\xml and epub\\from context}") + xsized w, + center bottomboundary p shifted (0,4mm)) withcolor \MPcolor {lesswhite} ; % 0.90white ; +) ; + +setbounds currentpicture to p ; + +\stopMPpage + +\startsection[title=Introduction] + +There is a pretty long tradition of typesetting math with \TEX\ and it looks like +this program will dominate for many more years. Even if we move to the web, the +simple fact that support for \MATHML\ in some browsers is suboptimal will drive +those who want a quality document to use \PDF\ instead. + +I'm writing this in 2014, at a time when \XML\ is widespread. The idea of \XML\ is +that you code your data in a very structured way, so that it can be manipulated and +(if needed) validated. Text has always been a target for \XML\ which is a follow|-|up +to \SGML\ that was in use by publishers. Because \HTML\ is less structured (and also +quite tolerant with respect to end tags) we prefer to use \XHTML\ but unfortunately +support for that is less widespread. + +Interestingly, documents are probably among the more complex targets of the +\XML\ format. The reason is that unless the author restricts him|/|herself or +gets restricted by the publisher, tag abuse can happen. At \PRAGMA\ we mostly +deal with education|-|related \XML\ and it's not always easy to come up with +something that suits the specific needs of the educational concept behind a +school method. Even if we start out nice and clean, eventually we end up with a +polluted source, often with additional structure needed to satisfy the tools used +for conversion. + +We have been supporting \XML\ from the day it showed up and most of our projects +involve \XML\ in one way or the other. That doesn't mean that we don't use \TEX\ +for coding documents. This manual is for instance a regular \TEX\ document. In +many ways a structured \TEX\ document is much more convenient to edit, especially +if one wants to add a personal touch and do some local page make|-|up. On the other hand, +diverting from standard structure commands makes the document less suitable for +output other than \PDF. There is simply no final solution for coding a document, +it's mostly a matter of taste. + +So we have a dilemma: if we want to have multiple output, frozen \PDF\ as well as +less-controlled \HTML\ output, we can best code in \XML, but when we want to code +comfortably we'd like to use \TEX. There are other ways, like Markdown, that can +be converted to intermediate formats like \TEX, but that is only suitable for +simple documents: the more advanced documents get, the more one has to escape +from the boundaries of (any) document encoding, and then often \TEX\ is not a bad +choice. There is a good reason why \TEX\ survived for so long. + +It is for this reason that in \CONTEXT\ \MKIV\ we can export the content in a +reasonable structured way to \XML. Of course we assume a structured document. It +started out as an experiment because it was relatively easy to implement, and it +is now an integral component. + +\stopsection + +\startsection[title=The output] + +The regular output is an \XML\ file but as we have some more related data it gets +organized in a tree. We also export a few variants. An example is given below: + +\starttyping +./test-export +./test-export/images +./test-export/images/... +./test-export/styles +./test-export/styles/test-defaults.css +./test-export/styles/test-images.css +./test-export/styles/test-styles.css +./test-export/styles/test-templates.css +./test-export/test-raw.xml +./test-export/test-raw.lua +./test-export/test-tag.xhtml +./test-export/test-div.xhtml +\stoptyping + +Say that we have this input: + +\starttyping +\setupbackend + [export=yes] + +\starttext + \startsection[title=First] + \startitemize + \startitem one \stopitem + \startitem two \stopitem + \stopitemize + \stopsection +\stoptext +\stoptyping + +The main export ends up in the \type {test-raw.xml} export file and looks like +the following (we leave out the preamble and style references): + +\starttyping +<document> <!-- with some attributes --> + <section detail="section" chain="section" level="3"> + <sectionnumber>1</sectionnumber> + <sectiontitle>First</sectiontitle> + <sectioncontent> + <itemgroup detail="itemize" chain="itemize" symbol="1" level="1"> + <item> + <itemtag><m:math ..><m:mo>•</m:mo></m:math></itemtag> + <itemcontent>one</itemcontent> + </item> + <item> + <itemtag><m:math ..><m:mo>•</m:mo></m:math></itemtag> + <itemcontent>two</itemcontent> + </item> + </itemgroup> + </sectioncontent> + </section> +</document> +\stoptyping + +This file refers to the stylesheets and therefore renders quite well in a browser +like Firefox that can handle \XHTML\ with arbitrary tags. + +The \type {detail} attribute tells us what instance of the element is used. +Normally the \type {chain} attribute is the same but it can have more values. +For instance, if we have: + +\starttyping +\definefloat[graphic][graphics][figure] + +..... + +\startplacefigure[title=First] + \externalfigure[cow.pdf] +\stopplacefigure + +..... + +\startplacegraphic[title=Second] + \externalfigure[cow.pdf] +\stopplacegraphic +\stoptyping + +we get this: + +\starttyping +<float detail="figure" chain="figure"> + <floatcontent>...</floatcontent> + <floatcaption>...</floatcaption> +</float> +<float detail="graphic" chain="figure graphic"> + <floatcontent>...</floatcontent> + <floatcaption>...</floatcaption> +</float> +\stoptyping + +This makes it possible to style specific categories of floats by using a +(combination of) \type {detail} and|/|or \type {chain} as filters. + +The body of the \type {test-tag.xhtml} file looks similar but it is slightly more +tuned for viewing. For instance, hyperlinks are converted to a way that \CSS\ and +browsers like more. Keep in mind that the raw file can be the base for conversion +to other formats, so that one stays closest to the original structure. + +The \type {test-div.xhtml} file is even more tuned for viewing in browsers as it +completely does away with specific tags. We explicitly don't map onto native +\HTML\ elements because that would make everything look messy and horrible, if only +because there seldom is a relation between those elements and the original. One +can always transform one of the export formats to pure \HTML\ tags if needed. + +\starttyping +<body> + <div class="document"> + <div class="section" id="aut-1"> + <div class="sectionnumber">1</div> + <div class="sectiontitle">First</div> + <div class="sectioncontent"> + <div class="itemgroup itemize symbol-1"> + <div class="item"> + <div class="itemtag"><m:math ...><m:mo>•</m:mo></m:math></div> + <div class="itemcontent">one</div> + </div> + <div class="item"> + <div class="itemtag"><m:math ...><m:mo>•</m:mo></m:math></div> + <div class="itemcontent">two</div> + </div> + </div> + <div class="float figure"> + <div class="floatcontent">...</div></div> + <div class="floatcaption">...></div> + </div> + <div class="float figure graphic"> + <div class="floatcontent">...</div></div> + <div class="floatcaption">...></div> + </div> + </div> + </div> +</body> +\stoptyping + +The default \CSS\ file can deal with tags as well as classes. The file +of additional styles contains definitions of so|-|called highlights. In the \CONTEXT\ source +one is better off using explicit named highlights instead of local font and color +switches because these properties are then exported to the \CSS. The images style +defines all images used. The templates file lists all the elements used and can +be used as a starting point for additional \CSS\ styling. + +Keep in mind that the export is \notabene{not} meant as a one|-|to|-|one visual +representation. It represents structure so that it can be converted to whatever +you like. + +In order to get an export you must start your document with: + +\starttyping +\setupbackend + [export=yes] +\stoptyping + +So, we trigger a specific (extra) backend. In addition you can set up the export: + +\starttyping +\setupexport + [svgstyle=test-basic-style.tex, + cssfile=test-extras.css, + hyphen=yes, + width=60em] +\stoptyping + +The \type {hyphen} option will also export hyphenation information so that the +text can be nicely justified. The \type {svgstyle} option can be used to specify +a file where math is set up; normally this would only contain a \type{bodyfont} setup, +and this option is only needed if you want to create an \EPUB\ file afterwards which +has math represented as \SVG. + +The value of \type {cssfile} ends up as a style reference in the exported files. +You can also pass a comma|-|separated list of names (between curly braces). These +entries come after those of the automatically generated \CSS\ files so you need +to be aware of default properties. + +\stopsection + +\startsection[title=Images] + +Inclusion of images is done in an indirect way. Each image gets an entry in a +special image related stylesheet and then gets referred to by \type {id}. Some +extra information is written to a status file so that the script that creates +\EPUB\ files can deal with the right conversion, for instance from \PDF\ to \SVG. +Because we can refer to specific pages in a \PDF\ file, this subsystem deals with +that too. Images are expected to be in an \type {images} subdirectory and because in \CSS\ +the references are relative to the path where the stylesheet resides, we use +\type {../images} instead. If you do some postprocessing on the files or relocate +them you need to keep in mind that you might have to change these paths in the +image|-|related \CSS\ file. + +\stopsection + +\startsection[title=Epub files] + +At the end of a run with exporting enabled you will get a message to the console that +tells you how to generate an \EPUB\ file. For instance: + +\starttyping +mtxrun --script epub --make --purge test +\stoptyping + +This will create a tree with the following organization: + +\starttyping +./test-epub +./test-epub/META-INF +./test-epub/META-INF/container.xml +./test-epub/OEBPS +./test-epub/OEBPS/content.opf +./test-epub/OEBPS/toc.ncx +./test-epub/OEBPS/nav.xhtml +./test-epub/OEBPS/cover.xhtml +./test-epub/OEBPS/test-div.xhtml +./test-epub/OEBPS/images +./test-epub/OEBPS/images/... +./test-epub/styles +./test-epub/styles/test-defaults.css +./test-epub/styles/test-images.css +./test-epub/styles/test-styles.css +./test-epub/mimetype +\stoptyping + +Images will be moved to this tree as well and if needed they will be converted, +for instance into \SVG. Converted \PDF\ files can have a \typ {page-<number>} in +their name when a specific page has been used. + +You can pass the option \type {--svgmath} in which case math will be converted to +\SVG. The main reason for this feature is that we found out that \MATHML\ support +in browsers is not currently as widespread as might be expected. The best bet is Firefox which +natively supports it. The Chrome browser had it for a while but it got dropped +and math is now delegated to \JAVASCRIPT\ and friends. In Internet Explorer +\MATHML\ should work (but I need to test that again). + +This conversion mechanism is +kind of interesting: one enters \TEX\ math, then gets \MATHML\ in the export, and +that gets rendered by \TEX\ again, but now as a standalone snippet that then gets +converted to \SVG\ and embedded in the result. + +\stopsection + +\startsection[title=Styles] + +One can argue that we should use native \HTML\ elements but since we don't have a nice +guaranteed|-|consistent mapping onto that, it makes no sense to do so. Instead, we +rely on either explicit tags with details and chains or divisions with classes +that combine the tag, detail and chain. The tagged variant has some more +attributes and those that use a fixed set of values become classes in the +division variant. Also, once we start going the (for instance) \type {H1}, \type +{H2}, etc.\ route we're lost when we have more levels than that or use a +different structure. If an \type {H3} can reflect several levels it makes no +sense to use it. The same is true for other tags: if a list is not really a list +than tagging it with \type {LI} is counterproductive. We're often dealing with +very complex documents so basic \HTML\ tagging becomes rather meaningless. + +If you look at the division variant (this is used for \EPUB\ too) you will notice +that there are no empty elements but \type {div} blocks with a comment as content. +This is needed because otherwise they get ignored, which for instance makes table +cells invisible. + +The relation between \type {detail} and \type {chain} (reflected in \type {class}) +can best be seen from the next example. + +\starttyping +\definefloat[myfloata] +\definefloat[myfloatb][myfloatbs][figure] +\definefloat[myfloatc][myfloatcs][myfloatb] +\stoptyping + +This creates two new float instances. The first inherits from the main float +settings, but can have its own properties. The second example inherits from +the \type {figure} so in fact it is part of a chain. The third one has a longer +chain. + +\starttyping +<float detail="myfloata">...</float> +<float detail="myfloatb" chain="figure">...</float> +<float detail="myfloatc" chain="figure myfloatb">...</float> +\stoptyping + +In a \CSS\ style you can now configure tags, details, and chains as well as +classes (we show only a few possibilities). Here, the \CSS\ element on the +first line of each pair is invoked by the \CSS\ selector on the second line. + +\starttyping +div.float.myfloata { } float[detail='myfloata'] { } +div.float.myfloatb { } float[detail='myfloatb'] { } +div.float.figure { } float[detail='figure'] { } +div.float.figure.myfloatb { } float[chain~='figure'][detail='myfloata'] { } +div.myfloata { } *[detail='myfloata'] { } +div.myfloatb { } *[detail='myfloatb'] { } +div.figure { } *[chain~='figure'] { } +div.figure.myfloatb { } *[chain~='figure'][detail='myfloatb'] { } +\stoptyping + +The default styles cover some basics but if you're serious about the export +or want to use \EPUB\ then it makes sense to overload some of it and|/|or +provide additional styling. You can find plenty about \CSS\ and its options +on the Internet. + +\stopsection + +\startsection[title=Coding] + +The default output reflects the structure present in the document. If that is not +enough you can add your own structure, as in: + +\starttyping +\startelement[question] +Is this right? +\stopelement +\stoptyping + +You can also pass attributes: + +\starttyping +\startelement[question][level=difficult] +Is this right? +\stopelement +\stoptyping + +But these will be exported only when you also say: + +\starttyping +\setupexport + [properties=yes] +\stoptyping + +You can create a namespace. The following will generate attributes +like \type {my-level}. + +\starttyping +\setupexport + [properties=my-] +\stoptyping + +In most cases it makes more sense to use highlights: + +\starttyping +\definehighlight + [important] + [style=bold] +\stoptyping + +This has the advantage that the style and color are exported to a special +\CSS\ file. + +Headers, footers, and other content that is part of the page builder are not +exported. If your document has cover pages you might want to hide them too. The +same is true when you create special chapter title rendering with a side +effect that content ends up in the page stream. If something shows up that you +don't want, you can wrap it in an \type {ignore} element: + +\starttyping +\startelement[ignore] +Don't export this. +\stopelement +\stoptyping + +\stopsection + +\stoptext diff --git a/doc/context/sources/general/manuals/mcommon.tex b/doc/context/sources/general/manuals/mcommon.tex new file mode 100644 index 000000000..b6b6026e9 --- /dev/null +++ b/doc/context/sources/general/manuals/mcommon.tex @@ -0,0 +1,210 @@ +% content=tex +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\startenvironment mcommon + +% modules + +\usemodule[abr-02] + +% layout + +% \startmode[screen] +% \setuppapersize[S6][S6] +% \setupinteractionscreen[options=max] +% \stopmode + +\setuplayout + [topspace=15mm, + header=15mm, + headerdistance=0mm, + footer=0cm, + width=middle, + height=middle] + +\setupinteraction + [state=start, + color=, + contrastcolor=, + style=] + +% fonts + +\definetypeface [mainface] [rm] [serif] [pagella] [default] +\definetypeface [mainface] [ss] [sans] [heros] [default] % [rscale=1.1] +\definetypeface [mainface] [tt] [mono] [heros] [default] % [rscale=1.1] +\definetypeface [mainface] [mm] [math] [pagella] [default] + +\setupbodyfont[mainface,12pt] + +\definefont [BigFont] [SansBold*default at 60pt] +\definefont [MedFont] [SansBold*default at 30pt] + +% colors (historically) + +\definecolor [NopColor] [r=.6,g=.4,b=.5] +\definecolor [AltColor] [r=.4,g=.6,b=.5] +\definecolor [TheColor] [r=.4,g=.5,b=.6] +\definecolor [TmpColor] [r=.6,g=.5,b=.4] + +\definecolor [NopColor] [r=.40,g=.20,b=.20] +\definecolor [AltColor] [r=.20,g=.40,b=.20] +\definecolor [TheColor] [r=.20,g=.20,b=.40] +\definecolor [TmpColor] [r=.40,g=.40,b=.20] + +\definecolor [red] [NopColor] +\definecolor [green] [AltColor] +\definecolor [blue] [TheColor] +\definecolor [yellow][TmpColor] + +% spacing + +\setupwhitespace + [big] + +\setuptolerance + [verytolerant,stretch] + +% verbatim + +\setuptype + [color=AltColor] + +\setuptyping + [color=AltColor] + +% structure + +\setupitemize + [each] + [color=TheColor] + +\definedescription + [switch] + [headstyle=type, + headcolor=TheColor, + location=serried, + width=broad] + +\defineenumeration + [topic] + [location=serried, + width=broad, + headstyle=, + headcolor=TheColor, + text=, + left={[}, + right={]}] + +\setuphead + [section] + [style=\bfb, + color=TheColor] + +\setuplist + [section] + [alternative=c, + color=TheColor, + textcolor=black, + pagecolor=black] + +% whatever + +\setupsystem + [random=medium] + +\setupfloats + [ntop=100] + +\setupinteraction + [style=, + color=NopColor, + contrastcolor=NopColor] + +% tables and frames + +\setuptabulate + [rulethickness=.5pt, + rulecolor=AltColor] + +\setuptables + [rulethickness=.5pt, + rulecolor=AltColor] + +\setupframedtexts + [rulethickness=.5pt, + framecolor=TheColor, + width=\textwidth] + +% quick reference things + +\usemodule[set-11] \loadsetups + +\setupframedtexts + [setuptext] + [rulethickness=.5pt, + framecolor=AltColor] + +% titlepage + +\startsetups titlepage + \defineoverlay + [logo] + [\useMPgraphic{titlepage}{width=\overlaywidth,height=\overlayheight}] + \setupbackgrounds + [page] + [background=logo] + \startstandardmakeup + \dontcomplain + \BigFont + \setupinterlinespace + \vfill + \setupalign[left] + \let\\=\par + \dontleavehmode + \rotate + [rotation=90] + {\color + [lightgray] + {\getvariable{document}{title}}} + \par + \stopstandardmakeup + \setupbackgrounds + [page] + [background=] +\stopsetups + +\startsetups colofon + \blank[2*big] + \testpage[3] + \startpacked + \getvariable{document}{author}\par + \getvariable{document}{affiliation}\par + \getvariable{document}{location}\par + \stoppacked +\stopsetups + +\setupdocument + [title=No Title, + before=\setups{titlepage}, + after=\setups{colofon}] + +% urls + +\useurl[gpl-simple] [http://creativecommons.org/licenses/GPL/2.0/] +\useurl[gpl-legal] [http://creativecommons.org/licenses/GPL/2.0/legalcode] +\useurl[byncsa-simple][http://creativecommons.org/licenses/by-nc-sa/2.5/] +\useurl[byncsa-legal] [http://creativecommons.org/licenses/by-nc-sa/2.5/legalcode] + +\useurl[garden] [http://contextgarden.net] +\useurl[install] [http://wiki.contextgarden.net/ConTeXt_Standalone] +\useurl[texlive] [http://www.tug.org/texlive/] +\useurl[group] [http://group.contextgarden.net] +\useurl[list] [http://www.ntg.nl/mailman/listinfo/ntg-context] +\useurl[development] [http://www.ntg.nl/mailman/listinfo/dev-context] +\useurl[announce] [http://www.ntg.nl/mailman/listinfo/ann-context] +\useurl[collector] [http://tracker.luatex.org] +\useurl[pragma] [http://www.pragma-ade.com] + +\stopenvironment diff --git a/doc/context/sources/general/manuals/readme/mreadme.tex b/doc/context/sources/general/manuals/readme/mreadme.tex new file mode 100644 index 000000000..b2af11bc4 --- /dev/null +++ b/doc/context/sources/general/manuals/readme/mreadme.tex @@ -0,0 +1,372 @@ +% interface=en engine=luatex language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\environment mcommon + +% copied from cont-log: readme_logo + +\startuseMPgraphic{titlepage}{width,height} + numeric width ; width = \MPvar{width} ; + numeric height ; height = \MPvar{height} ; + numeric delta ; delta := width/10 ; + numeric circle ; circle := 2.5delta ; + color c ; c := (.2,.4,.6) ; + path p, q, r ; + p := unitsquare xscaled width yscaled height ; + z1 = (delta,height-2delta) ; + z2 = (width-delta,height-delta) ; + z3 = (width/2-delta,2delta+circle) ; + z4 = (x3,delta+circle/2) ; + q := z1 { dir -15 } .. z2 & z2 { dir -105 } .. z3 & z3 { dir 135 } .. z1 & cycle ; + r := fullcircle xscaled circle yscaled (.85circle) rotated 15 shifted z4 ; + pickup pencircle scaled (delta/1.5) ; + fill p withcolor .50c ; + fill q withcolor .75c ; + fill r withcolor .75c ; + draw p withcolor c ; + draw q withcolor c ; + pickup pencircle scaled (delta/2) ; + draw r withcolor c ; + setbounds currentpicture to p ; +\stopuseMPgraphic + +\startdocument + [title={Read Me First}, + author={Hans Hagen}, + affiliation={PRAGMA ADE}, + location={Hasselt NL}] + +\startsubject[title={Introduction}] + +What licence suits best for a \TEX\ like system is a matter of taste. Personally +we dislike any licence that needs more than a few pages of dense legal code to +get the message across. A \TEX\ related system like \CONTEXT\ is a hybrid of +programs, scripts and|/|or macro code as well as documentation and sample code, +including graphics. \TEX\ related systems also have a long standing tradition of +providing support structures for users. In order to make support feasible, a +\TEX\ based system like \CONTEXT\ assumes a certain logic and structure in the +way the related files are named and organized in a tree structure. Even a small +change in one of the elements may let such a system behave differently than +manuals suggest. Swap a font, change some style defaults, leave out some pieces, +and users may end up in confusion. A licence does not give a user any guarantees! + +In order to satisfy those responsible for distributing \CONTEXT, we need to +choose a licence that makes them feel comfortable. Unfortunately we don't feel +that comfortable with a licence that does not provide the guarantees that a +system will not be adapted in such ways that the advertised behaviour changes. On +the other hand, it is the responsibility of those distributing and extending the +system to make sure that this does not happen. However, users should not +automatically assume that what they get shipped is the same as the original, +which is why we stress that support (from our side) will only be given on +unaltered systems. + +First of all, what is \CONTEXT ? It's just a bunch of macros, written in \TEX\ +and \METAPOST, meant for typesetting documents. The macros are accompanied by +some scripts, written in \PERL\ (mainly the older scripts) \RUBY\ (also older +ones) and \LUA\ (the current fashion). The \CONTEXT\ distribution comes with a +few fonts, files that help manage resources (e.g.\ map files needed for \MKII), +as well as patterns (based on official ones, so this is a derived work). + +The \CONTEXT\ distribution is packaged in a zip file organized in the \TDS\ +structure. + +\starttabulate[|lT|p|] +\NC \type {cont-tmf.zip} \NC the main distribution that has all relevant files \NC \NR +\NC \type {cont-tst.7z} \NC a bunch of test files that can also serve as examples \NC \NR +\NC \type {cont-mpd.zip} \NC a \METAPOST\ to \PDF\ converter (not needed in \CONTEXT) \NC \NR +\NC \type {cont-ppc.zip} \NC a macro package for typesetting chemistry (not needed in \CONTEXT) \NC \NR +\NC \type {cont-sci.zip} \NC configuration files for using \CONTEXT\ in the \SCITE\ editor \NC \NR +\stoptabulate + +There are two flavours of \CONTEXT: \MKII\ and \MKIV. The first one is frozen and +will not be extended. It runs on top of \PDFTEX\ or \XETEX. The \MKIV\ version is +actively developed and runs on top of \LUATEX\ (an engine that is developed +alongside \CONTEXT\ but that can also be used for other macro packages). + +The documentation can be downloaded from our website or the Wiki. Some manuals +ship with source code. We might ship more source code but only when the source is +stable and clean and can serve as an example. + +That said, what licence does apply? We need to distinguish between things that +resemble a program on the one hand and documentation on the other hand. We +(currently) use a different licence for either of them. + +\stopsubject + +\startsubject[title={The Code}] + +The program code (i.e. anything not under the \type {/doc} subtree) is +distributed under the + +\startnarrower +\goto{Creative Commons GNU GPL}[url(gpl-simple)] +\stopnarrower + +For practical purposes distributers may also choose the \LATEX\ project licence, +which is considered to be a bit more \TEX\ friendly. (BSD alike licences, the +Ruby Licence and the Apache are all licences that apply well for \CONTEXT.) + +In practice, users may forget about the legal part, if only because I haven't +even read (and understood) it completely myself, so let's stick to what Creative +Commons makes of it: + +\startcolor[blue] +The GNU General Public License is a Free Software license. Like any Free Software +license, it grants to you the four following freedoms: + +\startitemize + \startitem + The freedom to run the program for any purpose. + \stopitem + \startitem + The freedom to study how the program works and adapt it to your needs. + \stopitem + \startitem + The freedom to redistribute copies so you can help your neighbour. + \stopitem + \startitem + The freedom to improve the program and release your improvements to the + public, so that the whole community benefits. + \stopitem +\stopitemize + +You may exercise the freedoms specified here provided that you comply with the +express conditions of this license. The principal conditions are: + +You must conspicuously and appropriately publish on each copy distributed an +appropriate copyright notice and disclaimer of warranty and keep intact all the +notices that refer to this License and to the absence of any warranty; and give +any other recipients of the Program a copy of the GNU General Public License +along with the Program. Any translation of the GNU General Public License must be +accompanied by the GNU General Public License. + +If you modify your copy or copies of the program or any portion of it, or develop +a program based upon it, you may distribute the resulting work provided you do so +under the GNU General Public License. Any translation of the GNU General Public +License must be accompanied by the GNU General Public License. + +If you copy or distribute the program, you must accompany it with the complete +corresponding machine-readable source code or with a written offer, valid for at +least three years, to furnish the complete corresponding machine-readable source +code. + +Any of these conditions can be waived if you get permission from the copyright +holder. + +Your fair use and other rights are in no way affected by the above. +\stopcolor + +\stopsubject + +\startsubject[title={Recommendations}] + +Here are a few recommendations in case you want to distribute, extend of embed +\CONTEXT\ in applications: + +\startitemize + +\startitem + You can best leave the code base untouched. Most of \CONTEXT\ provides hooks + and it's relatively easy to overload code. Leave the lower level system code + untouched: changes may backfire when you update. Asking for more hooks is the + best way to go. +\stopitem + +\startitem + Put your own code in the right subpaths, i.e.\ modules approved by the + development team under \type {.../third}, and styles and whatever else under + \type {.../user}. This way your code will not interfere with existing code + and updating will give less problems. Keep in mind that \TEX\ systems have + their own way and order in locating files, and the load order often matters. +\stopitem + +\startitem + Don't copy styles and change a few lines, but load the base one and + built|/|patch on top of that. In the end you may benefit from improvements to + the base style. +\stopitem + +\startitem + Be original. The whole idea behind \CONTEXT\ is that you can write your own + styles. On the \CONTEXT\ mailing list as well as on the Wiki there are enough + advanced users to help you make a start. +\stopitem + +\startitem + Don't hesitate to submit bugs reports and ask for extensions. It may even be + that what you want is already present but yet undocumented. +\stopitem + +\startitem + If things don't work as expected, check to what extend your system matches + the (more or less) standard. We provide so called minimal \CONTEXT\ trees + that can serve as a reference. Because \CONTEXT\ evolves, make sure your + system is up to date. The \CONTEXT\ garden provides ways to install and + update the standard distribution. +\stopitem + +\startitem + The scripts can best be called using \type {mtxrun}. This lessens dependencies + on the location in the tree and ensures upward compatibility. It also prevents + clashes with similar scripts. +\stopitem + +\startitem + Some scripts depend on each other. Don't mess around with the existing + functionality and names of the scripts and then feed them back into the + standard distributions. +\stopitem + +\stopitemize + +\stopsubject + +\startsubject[title={Documents}] + +The documentation is provided under another Creative Commons licence + +\startnarrower + \goto{Attribution NonCommercial ShareAlike}[url(byncsa-simple)] +\stopnarrower + +This one says: + +\startcolor[blue] +You are free: + +\startitemize + \startitem to copy, distribute, display, and perform the work \stopitem + \startitem to make derivative works \stopitem +\stopitemize + +{\sc Attribution:} You must attribute the work in the manner specified by the +author or licensor. + +{\sc NonCommercial:} You may not use this work for commercial purposes. + +{\sc Share Alike:} If you alter, transform, or build upon this work, you may +distribute the resulting work only under a license identical to this one. + +\startitemize + \startitem + For any reuse or distribution, you must make clear to others the license + terms of this work. + \stopitem + \startitem + Any of these conditions can be waived if you get permission from the + copyright holder. + \stopitem +\stopitemize + +Your fair use and other rights are in no way affected by the above. +\stopcolor + +The non||commercial part is mostly a safeguard. We don't mind if user groups +distribute printed copies, publish (parts of) manuals and|/|or if authors use +example code in manuals and books about \CONTEXT. + +If you distribute \CONTEXT\ and related software on electronic media as part of +\TEX\ distributions (either or not for money), you may also distribute the +manuals and their sources in electronic form, preferable as provided by the +maintainers of \CONTEXT. + +Keep in mind that logos and cover designs are not meant to be copied. We provide +the source code for some manuals, but we don't always provide all graphics and +other resources. For instance, in some manuals we use commercial fonts and you +have to buy those yourself. + +We provide the typeset manuals at our website. Those are the official ones. We +appreciate it if you do not to distribute manuals compiled on your own system as +substitutes. The manuals are a showcase for what \CONTEXT\ provides. Help us to +assure the quality. + +\stopsubject + +\startsubject[title={More information}] + +We're not going to fill \mathematics{n}~pages with legal stuff, so if you want to +know more, you have to consult the web for the legalities mentioned. Here are a +few starting points: + +\startlines +\goto{\url[gpl-simple]}[url(gpl-simple)] +\goto{\url[gpl-legal]}[url(gpl-legal)] +\stoplines + +\startlines +\goto{\url[byncsa-simple]}[url(byncsa-simple)] +\goto{\url[byncsa-legal]}[url(byncsa-legal)] +\stoplines + +\CONTEXT\ itself can be fetched from the main site or the garden: + +\startlines +\goto{\url[pragma]}[url(pragma)] +\goto{\url[install]}[url(install)] +\stoplines + +These always ship the latest versions. Alternatively you can install the whole +\TEX\ distribution, which is a yearly snapshot: + +\startlines +\goto{\url[texlive]}[url(texlive)] +\stoplines + +A starting point for support can be found at: + +\startlines +\goto{\url[list]}[url(list)] +\goto{\url[garden]}[url(garden)] +\stoplines + +And of course there is the \CONTEXT\ group: + +\startlines +\goto{\url[group]}[url(group)] +\stoplines + +Bugs and feature requests can be registered at the collector: + +\startlines +\goto{\url[collector]}[url(collector)] +\stoplines + +Releases are announced at: + +\startlines +\goto{\url[announce]}[url(announce)] +\stoplines + +The developers can be met at: + +\startlines +\goto{\url[development]}[url(development)] +\stoplines + +\stopsubject + +\startsubject[title={Disclaimer}] + +To play safe we include a disclaimer here, taken from the BSD style licence. For +some reason such a text is always in unreadable capitals, so \unknown + +\start \txx \blue +THIS SOFTWARE IS PROVIDED BY THE AUTHOR \quotation {AS IS} AND ANY EXPRESS OR +IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF +THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +\stop + +\unknown\ and don't bother discussing licence issues and related things with us +for the mere sake of discussing licence stuff. + +\stopsubject + +\stopdocument 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 diff --git a/doc/context/sources/general/manuals/tiptrick/tiptrick.tex b/doc/context/sources/general/manuals/tiptrick/tiptrick.tex new file mode 100644 index 000000000..54a785134 --- /dev/null +++ b/doc/context/sources/general/manuals/tiptrick/tiptrick.tex @@ -0,0 +1,117 @@ +% interface=en +% +% author: Hans Hagen - Pragma ADE - www.pragma-ade.com + +\setupbodyfont + [dejavu] + +\setuppapersize + [HD-] + +\setuplayout + [location=middle, + header=0pt, + footer=0pt, + backspace=2.25cm, + topspace=2.25cm, + width=middle, + height=middle] + +\setupcolors + [state=start] + +\startreusableMPgraphic{page} + StartPage ; + picture p ; path s ; + fill Page withcolor .5red ; + draw Page withpen pensquare scaled 2cm withcolor .75[.5red,white] ; + s := (Field[Text][Text] enlarged .5cm) squeezed (.1cm,.15cm) ; + fill s withcolor .75[.5red,white] ; + if false : + p := image (graphictext "\ss TIP" withfillcolor .2white ;) ; + else : + p := textext.raw("\ss TIP") ; + setbounds p to (boundingbox p rightenlarged -0.025bbwidth(p)) ; + fi ; + p := p xysized(PaperWidth-1cm,PaperHeight-1cm) ; + p := p shifted .5(bbwidth(Page)-bbwidth(p),bbheight(Page)-bbheight(p)) ; + draw p withcolor .2white ; + clip p to s ; + draw p withcolor .875[.5red,white] ; ; + StopPage ; +\stopreusableMPgraphic + +\defineoverlay + [page] + [\reuseMPgraphic{page}] + +\setupbackgrounds + [page] + [background=page, + state=repeat] + +\definecolor[red][r=.5] + +\setuphead + [chapter] + [style=\tfb, + before=, + after={\blank[line]}] + +\setupblank + [halfline] + +% xml interface + +\startxmlsetups xml:tips + \xmlflush{#1} +\stopxmlsetups + +\startxmlsetups xml:tip + \startstandardmakeup + \startnamedsection[title][title=\xmlfirst{#1}{/title}] + \xmlall{#1}{/(remark|command)} + \vfill + \stopnamedsection + \stopstandardmakeup +\stopxmlsetups + +\startxmlsetups xml:remark + \blank + \xmlflush{#1} + \blank +\stopxmlsetups + +\definehighlight + [command] + [style=mono, + color=red, + command=no] + +\startxmlsetups xml:command + \blank + \starthighlight[command] + \xmlflush{#1} + \stophighlight + \blank +\stopxmlsetups + +\startxmlsetups xml:reference + \vfill + \hfill\strut see:\space + \xmlflush{#1} +\stopxmlsetups + +\startxmlsetups xml:initialize + \xmlsetsetup {#1} { + tips|tip|remark|command|reference + } {xml:*} +\stopxmlsetups + +\xmlregisterdocumentsetup{main}{xml:initialize} + +\starttext + + \xmlprocessfile{main}{tiptrick.xml}{} + +\stoptext diff --git a/doc/context/sources/general/manuals/tiptrick/tiptrick.xml b/doc/context/sources/general/manuals/tiptrick/tiptrick.xml new file mode 100644 index 000000000..8b4a30011 --- /dev/null +++ b/doc/context/sources/general/manuals/tiptrick/tiptrick.xml @@ -0,0 +1,53 @@ +<?xml version='1.0'?> + +<!-- author: Hans Hagen - Pragma ADE - www.pragma-ade.com --> + +<!-- feel free to submit more tips --> + +<tips xmlns="www.pragma-ade.com/schemas/tip.rng"> + + <tip> + <title>Generating Formats</title> + <remark>for all languages:</remark> + <command>context --make --all</command> + <remark>only english interface:</remark> + <command>context --make en</command> + <remark>for plain tex:</remark> + <command>mtxrun --script plain --make</command> + <!-- reference>mtexexec.pdf</reference --> + </tip> + + <tip> + <title>Updating</title> + <remark>when installed from the wiki:</remark> + <command>..../first-setup(.cmd)</command> + <remark>when downloaded from the website:</remark> + <command>cd ..../tex/texmf-context</command> + <command>wget http://www.pragma-ade.com/context/current/cont-tmf.zip</command> + <command>unzip cont-tmf.zip</command> + <command>mtxrun --generate</command> + <!-- reference>minstall.pdf</reference --> + </tip> + + <tip> + <title>Generating Command Lists</title> + <remark>quick reference document of english and dutch commands:</remark> + <command>context --interface=nl --global --result=setup-nl x-set-12.mkiv</command> + <command>context --interface=en --global --result=setup-en x-set-12.mkiv</command> + </tip> + + <tip> + <title>Module Documentation</title> + <remark>pretty printed, annotated module documentation:</remark> + <command>mtxrun --script modules syst-aux.mkiv</command> + </tip> + + <tip> + <title>Listings</title> + <remark>verbatim listings of (ascii) files:</remark> + <command>context --extra=listing --bodyfont=8pt --scite somefile.tex</command> + <command>context --extra=listing --bodyfont=8pt --scite somefile.lua</command> + <command>context --extra=listing --bodyfont=8pt --scite somefile.xml</command> + </tip> + +</tips> diff --git a/doc/context/sources/general/manuals/tools/tools-mkiv.tex b/doc/context/sources/general/manuals/tools/tools-mkiv.tex new file mode 100644 index 000000000..5f20e6985 --- /dev/null +++ b/doc/context/sources/general/manuals/tools/tools-mkiv.tex @@ -0,0 +1,501 @@ +% language=uk + +% author : Hans Hagen, PRAGMA ADE, NL +% license : Creative Commons, Attribution-NonCommercial-ShareAlike 3.0 Unported + +\usemodule[abr-02] + +\setuplayout + [width=middle, + height=middle, + backspace=2cm, + topspace=1cm, + footer=0pt, + bottomspace=2cm] + +\definecolor + [DocumentColor] + [r=.5] + +\setuptype + [color=DocumentColor] + +\setuptyping + [color=DocumentColor] + +\usetypescript + [iwona] + +\setupbodyfont + [iwona] + +\setuphead + [chapter] + [style=\bfc, + color=DocumentColor] + +\setuphead + [section] + [style=\bfb, + color=DocumentColor] + +\setupinteraction + [hidden] + +\setupwhitespace + [big] + +\setupheadertexts + [] + +\setupheadertexts + [] + [{\DocumentColor \type {luatools mtxrun context}\quad\pagenumber}] + +\usesymbols[cc] + +\def\sTEXMFSTART{\type{texmfstart}} +\def\sLUATOOLS {\type{luatools}} +\def\sMTXRUN {\type{mtxrun}} +\def\sCONTEXT {\type{context}} +\def\sKPSEWHICH {\type{kpsewhich}} +\def\sMKTEXLSR {\type{mktexlsr}} +\def\sXSLTPROC {\type{xsltproc}} + +\usemodule[narrowtt] + +\startdocument + [metadata:author=Hans Hagen, + metadata:title={Tools: luatools, mtxrun, context}, + author=Hans Hagen, + affiliation=PRAGMA ADE, + location=Hasselt NL, + title=Tools, + extra-1=luatools, + extra-2=mtxrun, + extra-3=context, + support=www.contextgarden.net, + website=www.pragma-ade.nl] + +\startMPpage + StartPage ; + picture p ; p := image ( + for i=1 upto 21 : + for j=1 upto 30 : + drawarrow (fullcircle rotated uniformdeviate 360) scaled 10 shifted (i*15,j*15) ; + endfor ; + endfor ; + ) ; + p := p ysized (bbheight(Page)-4mm) ; + fill Page enlarged 2mm withcolor \MPcolor{DocumentColor} ; + draw p shifted (center Page - center p) withpen pencircle scaled 2 withcolor .5white ; + numeric dx ; dx := bbwidth(Page)/21 ; + numeric dy ; dy := bbheight(Page)/30 ; + p := textext("\tt\bf\white\getvariable{document}{extra-1}") xsized(14*dx) ; + p := p shifted (-lrcorner p) shifted lrcorner Page shifted (-1dx,8dy) ; + draw p ; + p := textext("\tt\bf\white\getvariable{document}{extra-2}") xsized(14*dx) ; + p := p shifted (-lrcorner p) shifted lrcorner Page shifted (-1dx,5dy) ; + draw p ; + p := textext("\tt\bf\white\getvariable{document}{extra-3}") xsized(14*dx) ; + p := p shifted (-lrcorner p) shifted lrcorner Page shifted (-1dx,2dy) ; + draw p ; + setbounds currentpicture to Page ; + StopPage +\stopMPpage + +\startsubject[title=Contents] + +\placelist[section][alternative=a] + +\stopsubject + +\startsection[title={Remark}] + +This manual is work in progress. Feel free to submit additions or corrections. +Before you start reading, it is good to know that in order to get starting with +\CONTEXT, the easiest way to do that is to download the standalone distribution +from \type {contextgarden.net}. After that you only need to make sure that \type +{luatex} is in your path. The main command you use is then \type {context} and +normally it does all the magic it needs itself. + +\stopsection + +\startsection[title={Introduction}] + +Right from the start \CONTEXT\ came with programs that managed the process of +\TEX-ing. Although you can perfectly well run \TEX\ directly, it is a fact that +often multiple runs are needed as well as that registers need to be sorted. +Therefore managing a job makes sense. + +First we had \TEXEXEC\ and \TEXUTIL, and both were written in \MODULA, and as +this language was not supported on all platforms the programs were rewritten in +\PERL. Following that a few more tools were shipped with \CONTEXT. + +When we moved on to \RUBY\ all the \PERL\ scripts were rewritten and when +\CONTEXT\ \MKIV\ showed up, \LUA\ replaced \RUBY. As we use \LUATEX\ this means +that currently the tools and the main program share the same language. For \MKII\ +scripts like \TEXEXEC\ will stay around but the idea is that there will be \LUA\ +alternatives for them as well. + +Because we shipped many scripts, and because the de facto standard \TEX\ +directory structure expects scripts to be in certain locations we not only ship +tools but also some more generic scripts that locate and run these tools. + +\stopsection + +\startsection[title={The location}] + +Normally you don't need to know so many details about where the scripts +are located but here they are: + +\starttyping +<texroot>/scripts/context/perl +<texroot>/scripts/context/ruby +<texroot>/scripts/context/lua +<texroot>/scripts/context/stubs +\stoptyping + +This hierarchy was actually introduced because \CONTEXT\ was shipped with a bunch +of tools. As mentioned, we nowadays focus on \LUA\ but we keep a few of the older +scripts around in the \PERL\ and \RUBY\ paths.Now, if you're only using \CONTEXT\ +\MKIV, and this is highly recommended, you can forget about all but the \LUA\ +scripts. + +\stopsection + +\startsection[title={The traditional finder}] + +When you run scripts multiple times, and in the case of \CONTEXT\ they are even +run inside other scripts, you want to minimize the startup time. Unfortunately +the traditional way to locate a script, using \sKPSEWHICH, is not that fast, +especially in a setup with many large trees Also, because not all tasks can be +done with the traditional scripts (take format generation) we provided a runner +that could deal with this: \sTEXMFSTART. As this script was also used in more +complex workflows, it had several tasks: + +\startitemize[packed] +\item locate scripts in the distribution and run them using the right + interpreter +\item do this selectively, for instance identify the need for a run using + checksums for potentially changed files (handy for image conversion) +\item pass information to child processes so that lookups are avoided +\item choose a distribution among several installed versions (set the root + of the \TEX\ tree) +\item change the working directory before running the script +\item resolve paths and names on demand and launch programs with arguments + where names are expanded controlled by prefixes (handy for + \TEX-unware programs) +\item locate and open documentation, mostly as part the help systems in + editors, but also handy for seeing what configuration file is used +\item act as a \KPSEWHICH\ server cq.\ client (only used in special cases, + and using its own database) +\stopitemize + +Of course there were the usual more obscure and undocumented features as +well. The idea was to use this runner as follows: + +\starttyping +texmfstart texexec <further arguments> +texmfstart --tree <rootoftree> texexec <further arguments> +\stoptyping + +These are just two ways of calling this program. As \sTEXMFSTART\ can initialize +the environment as well, it is basically the only script that has to be present +in the binary path. This is quite comfortable as this avoids conflicts in names +between the called scripts and other installed programs. + +Of course calls like above can be wrapped in a shell script or batch file without +penalty as long as \sTEXMFSTART\ itself is not wrapped in a caller script that +applies other inefficient lookups. If you use the \CONTEXT\ minimals you can be +sure that the most efficient method is chosen, but we've seen quite inefficient +call chains elsewhere. + +In the \CONTEXT\ minimals this script has been replaced by the one we will +discuss in the next section: \sMTXRUN\ but a stub is still provided. + +\stopsection + +\startsection[title={The current finder}] + +In \MKIV\ we went a step further and completely abandoned the traditional lookup +methods and do everything in \LUA. As we want a clear separation between +functionality we have two main controlling scripts: \sMTXRUN\ and \sLUATOOLS. The +last name may look somewhat confusing but the name is just one on in a series. +\footnote {We have \type {ctxtools}, \type {exatools}, \type {mpstools}, \type +{mtxtools}, \type {pdftools}, \type {rlxtools}, \type {runtools}, \type +{textools}, \type {tmftools} and \type {xmltools}. Most if their funtionality is +already reimplemented.} + +In \MKIV\ the \sLUATOOLS\ program is nowadays seldom used. It's just a drop in +for \sKPSEWHICH\ plus a bit more. In that respect it's rather dumb in that it +does not use the database, but clever at the same time because it can make one +based on the little information available when it runs. It can also be used to +generate format files either or not using \LUA\ stubs but in practice this is not +needed at all. + +For \CONTEXT\ users, the main invocation of this tool is when the \TEX\ tree is +updated. For instance, after adding a font to the tree or after updating +\CONTEXT, you need to run: + +\starttyping +mtxrun --generate +\stoptyping + +After that all tools will know where to find stuff and how to behave well within +the tree. This is because they share the same code, mostly because they are +started using \sMTXRUN. For instance, you process a file with: + +\starttyping +mtxrun --script context <somefile> +\stoptyping + +Because this happens often, there's also a shortcut: + +\starttyping +context <somefile> +\stoptyping + +But this does use \sMTXRUN\ as well. The help information of \sMTXRUN\ is rather +minimalistic and if you have no clue what an option does, you probably never +needed it anyway. Here we discuss a few options. We already saw that we can +explicitly ask for a script: + +\starttyping +mtxrun --script context <somefile> +\stoptyping + +but + +\starttyping +mtxrun context <somefile> +\stoptyping + +also works. However, by using \type {--script} you limit te lookup to the valid +\CONTEXT\ \MKIV\ scripts. In the \TEX\ tree these have names prefixed by \type +{mtx-} and a lookup look for a plural as well. So, the next two lookups are +equivalent: + +\starttyping +mtxrun --script font +mtxrun --script fonts +\stoptyping + +Both will run \type {mtx-fonts.lua}. Actually, this is one of the scripts that +you might need when your font database is somehow outdated and not updated +automatically: + +\starttyping +mtxrun --script fonts --reload --force +\stoptyping + +Normally \sMTXRUN\ is all you need in order to run a script. However, there are a +few more options: + +\ctxlua{os.execute("mtxrun > tools-mkiv-help.tmp")} + +\typefile[ntyping]{tools-mkiv-help.tmp} + +Don't worry,you only need those obscure features when you integrate \CONTEXT\ in +for instance a web service or when you run large projects where runs and paths +take special care. + +\stopsection + +\startsection[title={Updating}] + +There are two ways to update \CONTEXT\ \MKIV. When you manage your +trees yourself or when you use for instance \TEXLIVE, you act as +follows: + +\startitemize[packed] +\item download the file cont-tmf.zip from \type {www.pragma-ade.com} or elsewhere +\item unzip this file in a subtree, for instance \type {tex/texmf-local} +\item run \type {mtxrun --generate} +\item run \type {mtxrun --script font --reload} +\item run \type {mtxrun --script context --make} +\stopitemize + +Or shorter: + +\startitemize[packed] +\item run \type {mtxrun --generate} +\item run \type {mtxrun font --reload} +\item run \type {context --make} +\stopitemize + +Normally these commands are not even needed, but they are a nice test if your +tree is still okay. To some extend \sCONTEXT\ is clever enough to decide if the +databases need to be regenerated and|/|or a format needs to be remade and|/|or if +a new font database is needed. + +Now, if you also want to run \MKII, you need to add: + +\startitemize[packed] +\item run \type {mktexlsr} +\item run \type {texexec --make} +\stopitemize + +The question is, how to act when \sLUATOOLS\ and \sMTXRUN\ have been updated +themselves? In that case, after unzipping the archive, you need to do the +following: + +\startitemize[packed] +\item run \type {luatools --selfupdate} +\item run \type {mtxrun --selfupdate} +\stopitemize + +For quite a while we shipped so called \CONTEXT\ minimals. These zip files +contained only the resources and programs that made sense for running \CONTEXT. +Nowadays the minimals are installed and synchronized via internet. \footnote +{This project was triggered by Mojca Miklavec who is also charge of this bit of +the \CONTEXT\ infrastructure. More information can be found at \type +{contextgarden.net}.} You can just run the installer again and no additional +commands are needed. In the console you will see several calls to \sMTXRUN\ and +\sLUATOOLS\ fly by. + +\stopsection + +\startsection[title={The tools}] + +We only mention the tools here. The most important ones are \sCONTEXT\ and \type +{fonts}. You can ask for a list of installed scripts with: + +\starttyping +mtxrun --script +\stoptyping + +On my machine this gives: + +\ctxlua{os.execute("mtxrun --script > tools-mkiv-help.tmp")} + +\typefile[ntyping]{tools-mkiv-help.tmp} + +The most important scripts are \type {mtx-fonts} and \type {mtx-context}. By +default fonts are looked up by filename (the \type {file:} prefix before font +names in \CONTEXT\ is default). But you can also lookup fonts by name (\type +{name:}) or by specification (\type {spec:}). If you want to use these two +methods, you need to generate a font database as mentioned in the previous +section. You can also use the font tool to get information about the fonts +installed on your system. + +\stopsection + +\startsection[title={Running \CONTEXT}] + +The \sCONTEXT\ tool is what you will use most as it manages your +run. + +\ctxlua{os.execute("context > tools-mkiv-help.tmp")} + +\typefile[ntyping]{tools-mkiv-help.tmp} + +There are few exert options too: + +\ctxlua{os.execute("context --expert > tools-mkiv-help.tmp")} + +\typefile[ntyping]{tools-mkiv-help.tmp} + +You might as well forget about these unless you are one of the +\CONTEXT\ developers. + +\stopsection + +\startsection[title={Prefixes}] + +A handy feature of \sMTXRUN\ (and as most features an inheritance of +\sTEXMFSTART) is that it will resolve prefixed arguments. This can be of help +when you run programs that are unaware of the \TEX\ tree but nevertheless need to +locate files in it. + +\ctxlua{os.execute("mtxrun --prefixes > tools-mkiv-help.tmp")} + +\typefile[ntyping]{tools-mkiv-help.tmp} + +An example is: + +\starttyping +mtxrun --execute xsltproc file:whatever.xsl file:whatever.xml +\stoptyping + +The call to \sXSLTPROC\ will get two arguments, being the complete path to the +files (given that it can be resolved). This permits you to organize the files in +a similar was as \TEX\ files. + +\stopsection + +\startsection[title={Stubs}] + +As the tools are written in the \LUA\ language we need a \LUA\ interpreter and or +course we use \LUATEX\ itself. On \UNIX\ we can copy \sLUATOOLS\ and \sMTXRUN\ to +files in the binary path with the same name but without suffix. Starting them in +another way is a waste of time, especially when \sKPSEWHICH\ is used to find +then, something which is useless in \MKIV\ anyway. Just use these scripts +directly as they are self contained. + +For \sCONTEXT\ and other scripts that we want convenient access to, stubs are +needed, like: + +\starttyping +#!/bin/sh +mtxrun --script context "$@" +\stoptyping + +This is also quite efficient as the \sCONTEXT\ script \type {mtx-context} is +loaded in \sMTXRUN\ and uses the same database. + +On \WINDOWS\ you can copy the scripts as|-|is and associate the suffix with +\LUATEX\ (or more precisely: \type {texlua}) but then all \LUA\ script will be +run that way which is not what you might want. + +In \TEXLIVE\ stubs for starting scripts were introduced by Fabrice Popineau. Such +a stub would start for instance \sTEXMFSTART, that is: it located the script +(\PERL\ or \RUBY) in the \TEX\ tree and launched it with the right interpreter. +Later we shipped pseudo binaries of \sTEXMFSTART: a \RUBY\ interpreter plus +scripts wrapped into a self contained binary. + +For \MKIV\ we don't need such methods and started with simple batch files, +similar to the \UNIX\ startup scripts. However, these have the disadvantage that +they cannot be used in other batch files without using the \type {start} command. +In \TEXLIVE\ this is taken care of by a small binary written bij T.M.\ Trzeciak +so on \TEXLIVE\ 2009 we saw a call chain from \type {exe} to \type {cmd} to \type +{lua} which is somewhat messy. + +This is why we now use an adapted and stripped down version of that program that +is tuned for \sMTXRUN, \sLUATOOLS\ and \sCONTEXT. So, we moved from the original +\type {cmd} based approach to an \type {exe} one. + +\starttyping +mtxrun.dll +mtxrun.exe +\stoptyping + +You can copy \type {mtxrun.exe} to for instance \type {context.exe} and it will +still use \sMTXRUN\ for locating the right script. It also takes care of mapping +\sTEXMFSTART\ to \sMTXRUN. So we've removed the intermediate \type {cmd} step, +can not run the script as any program, and most of all, we're as efficient as can +be. + +Of course this program is only meaningful for the \CONTEXT\ approach to tools. + +It may all sound more complex than it is but once it works users will not notice +those details. Als, in practice not that much has changed in running the tools +between \MKII\ and \MKIV\ as we've seen no reason to change the methods. + +\stopsection + +\startsubject[title={Colofon}] + +\starttabulate[|B|p|] + \NC author \NC \documentvariable{author}, + \documentvariable{affiliation}, + \documentvariable{location} \NC \NR + \NC version \NC \currentdate \NC \NR + \NC website \NC \documentvariable{website} \endash\ + \documentvariable{support} \NC \NR + \NC copyright \NC \symbol[cc][cc-by-sa-nc] \NC \NR +\stoptabulate + +\stopsubject + +\stopdocument diff --git a/doc/context/sources/general/manuals/units/units-mkiv.tex b/doc/context/sources/general/manuals/units/units-mkiv.tex new file mode 100644 index 000000000..0d91c67df --- /dev/null +++ b/doc/context/sources/general/manuals/units/units-mkiv.tex @@ -0,0 +1,538 @@ +% language=uk + +\usemodule[art-01,abr-02,physics-units] + +\definecolor[red] [darkred] +\definecolor[green] [darkgreen] +\definecolor[blue] [darkblue] +\definecolor[yellow] [darkyellow] +\definecolor[magenta][darkmagenta] +\definecolor[cyan] [darkcyan] + +\definecolor[maincolor] [darkcyan] +\definecolor[extracolor][darkmagenta] + +\setupbodyfont + [10pt] + +\setuptyping + [color=extracolor] + +\setuptype + [color=extracolor] % darkyellow + +% \setupnumbering +% [alternative=doublesided] + +\setupinteraction + [hidden] + +\setuphead + [section] + [color=maincolor] + +\usesymbols[cc] + +\startdocument + [metadata:author=Hans Hagen, + metadata:title=Units, + author=Hans Hagen, + affiliation=PRAGMA ADE, + location=Hasselt NL, + title=Units, + extra=ConTeXt MkIV, + support=www.contextgarden.net, + website=www.pragma-ade.nl] + +\unexpanded\def\UnitsHack#1#2% + {\setbox\scratchbox\hbox{\bf\strut#1#2/}% kerning and such + \hbox to \wd\scratchbox{\bf\strut#1\hss/\hss#2}} + +\startMPpage + + StartPage ; + fill Page enlarged 2mm withcolor \MPcolor{darkcyan} ; + pickup pencircle scaled 2mm ; + picture p, q, r ; + p := textext("\ssbf\WORD{\documentvariable{title}}") xsized (bbheight Page - 2cm) rotated 90 ; + q := textext("\ssbf\WORD{\documentvariable{author}}") ysized 1cm ; + r := textext("\ssbf\WORD{\documentvariable{extra}}") xsized bbwidth q ; + draw anchored.rt (p, center rightboundary Page shifted (-1cm, 0mm)) withcolor white ; + draw anchored.lft(q, ulcorner Page shifted ( 1cm, -84mm)) withcolor white ; % \MPcolor{darkred} ; + draw anchored.lft(r, ulcorner Page shifted ( 1cm,-108mm)) withcolor white ; % \MPcolor{darkred} ; + StopPage ; + +\stopMPpage + +% \page[empty] \setuppagenumber[start=1] + +\startsubject[title={Contents}] + +\placelist[section][criterium=all,interaction=all] + +\stopsubject + +\startsection[title={Introduction}] + +In \CONTEXT\ \MKII\ there is a module that implements consistent +typesetting of units (quantities and dimensions). In \MKIV\ this +functionality is now part of the physics core modules. This is +also one of the mechanisms that got a new user interface: instead +of using commands we now parse text. Thanks to those users who +provided input we're more complete now that in \MKII. You can browse +the mailing list archive to get some sense of history. + +\stopsection + +\startsection[title={The main command}] + +The core command is \type {\unit}. The argument to this command gets +parsed and converted into a properly typeset dimension. Normally there +will be a quantity in front. + +\starttabulate +\NC \type{10 meter} \NC \unit{10 meter} \NC \NR +\NC \type{10 meter per second} \NC \unit{10 meter per second} \NC \NR +\NC \type{10 square meter per second} \NC \unit{10 square meter per second} \NC \NR +\stoptabulate + +The parser knows about special cases, like synonyms: + +\starttabulate +\NC \type{10 degree celsius} \NC \unit{10 degree celsius} \NC \NR +\NC \type{10 degrees celsius} \NC \unit{10 degrees celsius} \NC \NR +\NC \type{10 celsius} \NC \unit{10 celsius} \NC \NR +\stoptabulate + +The units can be rather complex, for example: + +\startbuffer +\unit{30 kilo pascal square meter / second kelvin} +\stopbuffer + +\typebuffer + +This comes out as: \ignorespaces\getbuffer\removeunwantedspaces. Depending +on the unit at had, recognition is quite flexible. The following variants +all work out ok. + +\starttabulate +\NC \type{10 kilogram} \NC \unit{10 kilogram} \NC \NR +\NC \type{10 kilo gram} \NC \unit{10 kilo gram} \NC \NR +\NC \type{10 k gram} \NC \unit{10 k gram} \NC \NR +\NC \type{10 kilo g} \NC \unit{10 kilo g} \NC \NR +\NC \type{10 k g} \NC \unit{10 k g} \NC \NR +\NC \type{10 kg} \NC \unit{10 kg} \NC \NR +\NC \type{10 kilog} \NC \unit{10 kilog} \NC \NR +\NC \type{10 kgram} \NC \unit{10 kgram} \NC \NR +\stoptabulate + +Of course being consistent makes sense, so normally you will use +a consistent mix of short or long keywords. + +You can provide a qualifier that gets lowered and appended to +the preceding unit. + +\startbuffer +\unit{112 decibel (A)} +\stopbuffer + +\typebuffer + +This gives: \ignorespaces\getbuffer\removeunwantedspaces. Combinations +are also possible: + +\starttabulate +\NC \type{5 watt per meter celsius} \NC \unit{5 watt per meter celsius} \NC \NR +\NC \type{5 watt per meter degrees celsius} \NC \unit{5 watt per meter degrees celsius} \NC \NR +\NC \type{5 watt per meter kelvin} \NC \unit{5 watt per meter kelvin} \NC \NR +\NC \type{5 watt per meter per kelvin} \NC \unit{5 watt per meter per kelvin} \NC \NR +\NC \type{10 arcminute} \NC \unit{10 arcminute} \NC \NR +\NC \type{10 arcminute 20 arcsecond} \NC \unit{10 arcminute 20 arcsecond} \NC \NR +\stoptabulate + +\stopsection + +\startsection[title={Extra units}] + +To some extent units can be tuned. You can for instance +influence the spacing between a number and a unit: + +\startbuffer + \unit{35 kilogram per cubic meter} +\setupunit[space=normal] \unit{35 kilogram per cubic meter} +\setupunit[space=big] \unit{35 kilogram per cubic meter} +\setupunit[space=medium] \unit{35 kilogram per cubic meter} +\setupunit[space=small] \unit{35 kilogram per cubic meter} +\setupunit[space=none] \unit{35 kilogram per cubic meter} +\stopbuffer + +\typebuffer + +Of course no spacing looks rather bad: + +\startlines +\getbuffer +\stoplines + +Another parameter is \type {separator}. In order to demonstrate +this we define an extra unit command: + +\startbuffer +\defineunit[sunit][separator=small] +\defineunit[nunit][separator=none] +\stopbuffer + +\typebuffer \getbuffer + +We now have two more commands: + +\startbuffer +\unit {35 kilogram cubic meter} +\sunit{35 kilogram cubic meter} +\nunit{35 kilogram cubic meter} +\stopbuffer + +\typebuffer + +These three commands give different results: + +\startlines +\getbuffer +\stoplines + +Valid separators are \type {normal}, \type {big}, \type {medium}, +\type {small}, \type {none}. You can let units stand out by +applying color or a specific style. + +\startbuffer +\setupunit[style=\bi,color=maincolor] +\unit{10 square meter per second} +\stopbuffer + +\typebuffer + +Keep in mind that all defined units inherit from their parent +definition unless they are set up themselves. + +\start \blank \getbuffer \blank \stop + +To some extent you can control rendering in text and math mode. As +an example we define an extra instance. + +\startbuffer +\defineunit[textunit][alternative=text] +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +test \unit {10 cubic meter per second} test +test \textunit{10 cubic meter per second} test +test $\unit {10 cubic meter per second}$ test +test $\textunit{10 cubic meter per second}$ test +test 10 \unit {cubic meter per second} test +test 10 \textunit{cubic meter per second} test +test $10 \unit {cubic meter per second}$ test +test $10 \textunit{cubic meter per second}$ test +\stopbuffer + +\typebuffer + +\startlines +\getbuffer +\stoplines + +\stopsection + +\startsection[title={Labels}] + +The units, prefixes and operators are typeset using the label +mechanism which means that they can be made to adapt to a language +and|/|or adapted. Instead of language specific labels you can also +introduce mappings that don't relate to a language at all. As an +example we define some bogus mapping. + +\startbuffer +\setupunittext + [whatever] + [meter=retem, + second=dnoces] + +\setupprefixtext + [whatever] + [kilo=olik] + +\setupoperatortext + [whatever] + [solidus={ rep }] +\stopbuffer + +\typebuffer \getbuffer + +Such a mapping can be partial and the current language will +be the default fallback and itselfs falls back on the English +language mapping. + +\startbuffer +\unit{10 km/s} +\unit{10 Kilo Meter/s} +\unit{10 kilo Meter/s} +\unit{10 Kilo m/s} +\unit{10 k Meter/s} +\stopbuffer + +\typebuffer + +When we typeset this we get the normal rendering: + +\startlines +\getbuffer +\stoplines + +However, when we change the language parameter, we get +a different result: + +\startlines +\setupunit[language=whatever]\getbuffer +\stoplines + +The alternative rendering is set up as follows: + +\starttyping +\setupunit[language=whatever] +\stoptyping + +You can also decide to use a special instance of units: + +\starttyping +\defineunit[wunit][language=whatever] +\stoptyping + +This will define the \type {\wunit} command and leave the original +\type {\unit} command untouched. + +\stopsection + +\startsection[title={Digits}] + +In addition to units we have digits. These can be used independently +but the same functionality is also integrated in the unit commands. +The main purpose of this command is formatting in tables, of which +we give an example below. + +\starttabulate[|l|r|] +\NC \type{12,345.67 kilogram} \NC \unit{12,345.67 kilogram} \NR +\NC \type{__,__1.23 kilogram} \NC \unit{__,__1.23 kilogram} \NR +\NC \type{__,___.12 kilogram} \NC \unit{__,___.12 kilogram} \NR +\NC \type{__,__1.== kilogram} \NC \unit{__,__1.== kilogram} \NR +\NC \type{__,___:23 kilogram} \NC \unit{__,___:23 kilogram} \NR +\stoptabulate + +The \type {_} character serves as placeholders. There are some +assumptions to how numbers are constructed. In principe the input +assumes a comma to separate thousands and a period to separate the +fraction. + +\getbuffer + +You can swap periods and commas in the output. In fact there are a +few methods available. For instance we can separate the thousands +with a small space instead of a symbol. + +\startbuffer +\starttabulate[|c|r|r|] +\HL +\NC 0 \NC \setupunit[method=0]\unit{00,000.10 kilogram} + \NC \setupunit[method=0]\unit{@@,@@0.10 kilogram} \NC \NR +\NC 1 \NC \setupunit[method=1]\unit{00,000.10 kilogram} + \NC \setupunit[method=1]\unit{@@,@@0.10 kilogram} \NC \NR +\NC 2 \NC \setupunit[method=2]\unit{00,000.10 kilogram} + \NC \setupunit[method=2]\unit{@@,@@0.10 kilogram} \NC \NR +\NC 3 \NC \setupunit[method=3]\unit{00,000.10 kilogram} + \NC \setupunit[method=3]\unit{@@,@@0.10 kilogram} \NC \NR +\NC 4 \NC \setupunit[method=4]\unit{00,000.10 kilogram} + \NC \setupunit[method=4]\unit{@@,@@0.10 kilogram} \NC \NR +\NC 5 \NC \setupunit[method=5]\unit{00,000.10 kilogram} + \NC \setupunit[method=5]\unit{@@,@@0.10 kilogram} \NC \NR +\NC 6 \NC \setupunit[method=6]\unit{00,000.10 kilogram} + \NC \setupunit[method=6]\unit{@@,@@0.10 kilogram} \NC \NR +\HL +\stoptabulate +\stopbuffer + +\typebuffer % [bodyfont=9pt] + +\getbuffer + +The digit modes can be summarized as:: + +\startitemize[n,packed] +\item periods/comma +\item commas/period +\item thinmuskips/comma +\item thinmuskips/period +\item thickmuskips/comma +\item thickmuskips/period +\stopitemize + +You can reverse the order of commas and period in the input by +setting the parameter \type {order} to \type {reverse}. + +The digit parser handles a bunch of special characters as +well as different formats. We strongly suggest you to use +the grouped call. + +\starttabulate[|l|l|l|] +\NC \type{.} \NC , . \NC comma or period \NC \NR +\NC \type{,} \NC , . \NC comma or period \NC \NR +\NC \type{:} \NC \NC invisible period \NC \NR +\NC \type{;} \NC \NC invisible comma \NC \NR +\NC \type{_} \NC \NC invisible space \NC \NR +\NC \type{/} \NC \NC invisible sign \NC \NR +\NC \type{-} \NC $-$ \NC minus sign \NC \NR +\NC \type{+} \NC $+$ \NC plus sign \NC \NR +\NC \type{//} \NC \NC invisible high sign \NC \NR +\NC \type{--} \NC $\negative$ \NC high minus sign \NC \NR +\NC \type{++} \NC $\positive$ \NC high plus sign \NC \NR +\NC \type{=} \NC $\zeroamount$ \NC zero padding \NC \NR +\stoptabulate + +Let's give some examples: + +\starttabulate[|l|r|] +\NC \type{1} \NC \ruledhbox{\strut\digits{1}} \NC \NR +\NC \type{12} \NC \ruledhbox{\strut\digits{12}} \NC \NR +\NC \type{12.34} \NC \ruledhbox{\strut\digits{12.34}} \NC \NR +\NC \type{123,456} \NC \ruledhbox{\strut\digits{123,456}} \NC \NR +\NC \type{123,456.78} \NC \ruledhbox{\strut\digits{123,456.78}} \NC \NR +\NC \type{12,34} \NC \ruledhbox{\strut\digits{12,34}} \NC \NR +\NC \type{.1234} \NC \ruledhbox{\strut\digits{.1234}} \NC \NR +\NC \type{1234} \NC \ruledhbox{\strut\digits{1234}} \NC \NR +\NC \type{123,456.78^9} \NC \ruledhbox{\strut\digits{123,456.78^9}} \NC \NR +\NC \type{123,456.78e9} \NC \ruledhbox{\strut\digits{123,456.78e9}} \NC \NR +\NC \type{/123,456.78e-9} \NC \ruledhbox{\strut\digits{/123,456.78e-9}} \NC \NR +\NC \type{-123,456.78e-9} \NC \ruledhbox{\strut\digits{-123,456.78e-9}} \NC \NR +\NC \type{+123,456.78e-9} \NC \ruledhbox{\strut\digits{+123,456.78e-9}} \NC \NR +\NC \type{//123,456.78e-9} \NC \ruledhbox{\strut\digits{//123,456.78e-9}} \NC \NR +\NC \type{--123,456.78e-9} \NC \ruledhbox{\strut\digits{--123,456.78e-9}} \NC \NR +\NC \type{++123,456.78e-9} \NC \ruledhbox{\strut\digits{++123,456.78e-9}} \NC \NR +\NC \type{___,___,123,456,789.00} \NC \ruledhbox{\strut\digits{___,___,123,456,789.00}} \NC \NR +\NC \type{___,___,_12,345,678.==} \NC \ruledhbox{\strut\digits{___,___,_12,345,678.==}} \NC \NR +\stoptabulate + +\stopsection + +\startsection[title={Adding units}] + +It is possible to add extra snippets. This is a two step process: +first some snippet is defined, next a proper label is set up. In the +next example we define a couple of \TEX\ dimensions: + +\startbuffer +\registerunit + [unit] + [point=point, + basepoint=basepoint, + scaledpoint=scaledpoint, + didot=didot, + cicero=cicero] +\stopbuffer + +\typebuffer \getbuffer + +Possible categories are: \type {prefix}, \type {unit}, \type {operator}, +\type {suffix}, \type {symbol},\type {packaged}. Next we define labels: + +\startbuffer +\setupunittext + [point=pt, + basepoint=bp, + scaledpoint=sp, + didot=dd, + cicero=cc] +\stopbuffer + +\typebuffer \getbuffer + +Now we can use use these: + +\startbuffer +\unit{10 point / second} +\stopbuffer + +\typebuffer + +Of course you can wonder what this means. + +\blank \getbuffer \blank + +When no label is defined the long name is used: + +\startbuffer +\registerunit + [unit] + [page=page] +\stopbuffer + +\typebuffer \getbuffer + +This is used as: + +\startbuffer +\unit{10 point / page} +\stopbuffer + +\typebuffer + +Which gives: + +\blank \getbuffer \blank + +\stopsection + +\startsection[title={Built in keywords}] + +A given sequence of keywords is translated in an list of internal +keywords. For instance \type {m}, \type {Meter} and \type {meter} +all become \type {meter} and that one is used when resolving a +label. In the next tables the right column mentions the internal +keyword. The right column shows the Cased variant, but a lowercase +one is built|-|in as well. + +The following prefixes are built|-|in: + +\showunits[prefixes] + +The following units are supported, including some combinations: + +\showunits[units] + +The amount of operators is small: + +\showunits[operators] + +There is also a small set of (names) suffixes: + +\showunits[suffixes] + +Some symbols get a special treatment: + +\showunits[symbols] + +These are also special: + +\showunits[packaged] + +\startsection[title={Colofon}] + +\starttabulate[|B|p|] +\NC author \NC \getvariable{document}{author}, \getvariable{document}{affiliation}, \getvariable{document}{location} \NC \NR +\NC version \NC \currentdate \NC \NR +\NC website \NC \getvariable{document}{website} \endash\ \getvariable{document}{support} \NC \NR +\NC copyright \NC \symbol[cc][cc-by-sa-nc] \NC \NR +\stoptabulate + +\stopsection + +\stopdocument diff --git a/doc/context/sources/general/manuals/workflows/workflows-contents.tex b/doc/context/sources/general/manuals/workflows/workflows-contents.tex new file mode 100644 index 000000000..a32f4737d --- /dev/null +++ b/doc/context/sources/general/manuals/workflows/workflows-contents.tex @@ -0,0 +1,13 @@ +% language=uk + +\environment workflows-style + +\startcomponent workflows-contents + +\starttitle[title=Contents] + + \placelist[chapter] + +\stoptitle + +\stopcomponent diff --git a/doc/context/sources/general/manuals/workflows/workflows-graphics.tex b/doc/context/sources/general/manuals/workflows/workflows-graphics.tex new file mode 100644 index 000000000..55a8ad701 --- /dev/null +++ b/doc/context/sources/general/manuals/workflows/workflows-graphics.tex @@ -0,0 +1,157 @@ +% language=uk + +\environment workflows-style + +\startcomponent workflows-graphics + +\startchapter[title=Graphics] + +\startsection[title=Bad names] + +After many years of using \CONTEXT\ in workflows where large amounts of source files +as well as graphics were involved we can safely say that it's hard for publishers to +control the way these are named. This is probably due to the fact that in a +click|-|and|-|point based desktop publishing workflow names don't matter as one stays on +one machine, and names are only entered once (after that these names become abstractions and +get cut and pasted). Proper consistent resource managament is simply not part of the flow. + +This means that you get names like: + +\starttyping +foo_Bar_01_03-a.EPS +foo__Bar-01a_03.eps +foo__Bar-01a_03.eps +foo BarA 01-03.eps +\stoptyping + +Especially when a non proportional screen font is used multiple spaces can look +like one. In fancy screen fonts upper and lowercase usage might get obscured. It +really makes one wonder if copy|-|editing or adding labels to graphics isn't +suffering from the same problem. + +Anyhow, as in an automated rendering workflow the rendering is often the last step you +can imagine that when names get messed up it's that last step that gets blamed. It's not +that hard to sanitize names of files on disk as well as in the files that refer to them, +and we normally do that we have complete control. This is no option when all the resources +are synchronzied from elsewhere. In that case the only way out is signaling potential +issues. Say that in the source file there is a reference: + +\starttyping +foo_Bar_01_03-a.EPS +\stoptyping + +and that the graphic on disk has the same name, but for some reason after an update +has become: + +\starttyping +foo-Bar_01_03-a.EPS +\stoptyping + +The old image is probably still there so the update is not reflected in the final +product. This is not that uncommon when you deal with tens of thousands of files, +many editors and graphic designers, and no strict filename policy. + +For this we provide the following tracing option: + +\starttyping +\enabletrackers[graphics.lognames] +\stoptyping + +This will put information in the log file about included graphics, like: + +\starttyping +system > graphics > start names + +used graphic > asked : cow.pdf +used graphic > comment : not found +used graphic > asked : t:/sources/cow.pdf +used graphic > format : pdf +used graphic > found : t:/sources/cow.pdf +used graphic > used : t:/sources/cow.pdf + +system > graphics > stop names +\stoptyping + +You can also add information to the file itself: + +\starttyping +\usemodule[s-figures-names] +\stoptyping + +Of course that has to be done at the end of the document. Bad names are reported +and suitable action can be taken. + +\stopsection + +\startsection[title=Downsampling] + +You can plug in you rown converter, here is an example: + +\starttyping +\startluacode + +figures.converters.jpg = figures.converters.jpg or { } + +figures.converters.jpg["lowresjpg.pdf"] = + function(oldname,newname,resolution) + figures.programs.run ( + [[gm]], + [[convert -geometry %nx%x%ny% -compress JPEG "%old%" "%new%"]], + { + old = old, + new = new, + nx = resolution or 300, + ny = resolution or 300, + } + ) + end +\stopluacode +\stoptyping + +You can limit the search to a few types and set the resolution with: + +\starttyping +\setupexternalfigures + [order={pdf,jpg}, + resolution=100, + method=auto] +\stoptyping + +And use it like: + +\starttyping +\externalfigure[verybig.jpg][height=10cm] +\stoptyping + +The second string passed to the \type {run} helper contains the arguments to the +first one. The variables between percent signs get replaced by the variables in +the tables passed as third argument. + +\stopsection + +\startsection[title=Trackers] + +If you want a lot of info you can say: + +\starttyping +\enabletrackers[figures.*] +\stoptyping + +But you can be more specific. With \type {graphics.locating} you will get some +insight in where files are looked for. The \type {graphics.inclusion} tracker +gives some more info about actual inclusion. The \type {graphics.bases} is kind +of special and only makes sense when you use the graphic database options. The +\type {graphics.conversion} and related tracker \type {graphics.programs} show if +and how conversion of images takes place. + +The \type {graphics.lognames} will make sure that some extra information about +used graphics is saved in the log file, while \type {graphics.usage} will produce +a file \typ {<jobname>-figures-usage.lua} that contains information about found +(or not found) images and the way they are used. + +\stopsection + +\stopchapter + +\stopcomponent + diff --git a/doc/context/sources/general/manuals/workflows/workflows-injectors.tex b/doc/context/sources/general/manuals/workflows/workflows-injectors.tex new file mode 100644 index 000000000..d2f837d82 --- /dev/null +++ b/doc/context/sources/general/manuals/workflows/workflows-injectors.tex @@ -0,0 +1,86 @@ +% language=uk + +\environment workflows-style + +\startcomponent workflows-injectors + +\startchapter[title={Injectors}] + +When you have no control over the source but need to manually tweak some aspects +of the typesetting, like an occasional page break of column switch, you can use +the injector mechanism. This mechanism is part of list and register building but +can also be used elsewhere. + +\startbuffer[one] +\startmixedcolumns[balance=yes] + \dotestinjector{test}line 1 \par + \dotestinjector{test}line 2 \par + \dotestinjector{test}line 3 \par + \dotestinjector{test}line 4 \par + \dotestinjector{test}line 5 +\stopmixedcolumns +\stopbuffer + +\startbuffer[two] +\startmixedcolumns[balance=yes] + \dotestinjector{test}line 1 \par + \dotestinjector{test}line 2 \par + \dotestinjector{test}line 3 \par + \dotestinjector{test}line 4 \par + \dotestinjector{test}line 5 +\stopmixedcolumns +\stopbuffer + +We have two buffers: + +\typebuffer[one] + +and + +\typebuffer[two] + +When typeset these come out as: + +\blank \startpacked \bf \getbuffer[one] \stoppacked \blank + +and + +\blank \startpacked \bf \getbuffer[two] \stoppacked \blank + +We can enable (and show) the injectors with: + +\startbuffer +\doactivateinjector{test} \showinjector +\stopbuffer + +\typebuffer \getbuffer + +Now we get: + +\blank \startpacked \bf \getbuffer[one] \stoppacked \blank + +and + +\blank \startpacked \bf \getbuffer[two] \stoppacked \blank + +The small numbers are injector points. These will of course change when we add +more in|-|between. Let's add actions to some of the injection points: + +\startbuffer +\setinjector[test][13][{\column}] +\setinjector[test][17][{\column}] +\stopbuffer + +\typebuffer \getbuffer + +As expected we now get column breaks: + +\blank \startpacked \bf \getbuffer[one] \stoppacked \blank + +and + +\blank \startpacked \bf \getbuffer[two] \stoppacked \blank + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/workflows/workflows-introduction.tex b/doc/context/sources/general/manuals/workflows/workflows-introduction.tex new file mode 100644 index 000000000..a88640b27 --- /dev/null +++ b/doc/context/sources/general/manuals/workflows/workflows-introduction.tex @@ -0,0 +1,25 @@ +% language=uk + +\environment workflows-style + +\startcomponent workflows-introduction + +\startchapter[title=Introduction] + +This manual contains some information about features that can help you to manage +workflows or \CONTEXT\ related processes. Because we use \CONTEXT\ ourselves all +that we need ends up in the distribution. When you discover something workflow +related that is not yet covered here, you can tell me. I simply forget about all +there is, especially if it's made for projects. Don't expect this manual to be +complete or extensive, it's just a goodie. + +\startlines +\documentvariable{author}, +\documentvariable{affiliation} +\documentvariable{location} +\currentdate[month,year] +\stoplines + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/workflows/workflows-mkiv.tex b/doc/context/sources/general/manuals/workflows/workflows-mkiv.tex new file mode 100644 index 000000000..3820e04fa --- /dev/null +++ b/doc/context/sources/general/manuals/workflows/workflows-mkiv.tex @@ -0,0 +1,32 @@ +\setupbackend[export=yes] + +\environment workflows-style + +\startdocument + [metadata:author=Hans Hagen, + metadata:title=Workflow support in context, + author=Hans Hagen, + affiliation=PRAGMA ADE, + location=Hasselt NL, + title=workflow, + extra=support in context, + support=www.contextgarden.net, + website=www.pragma-ade.nl] + +\component workflows-titlepage + +\startfrontmatter + \component workflows-contents + \component workflows-introduction +\stopfrontmatter + +\startbodymatter + \component workflows-resources + \component workflows-graphics + \component workflows-suspects + \component workflows-injectors + \component workflows-xml + \component workflows-setups +\stopbodymatter + +\stopdocument diff --git a/doc/context/sources/general/manuals/workflows/workflows-resources.tex b/doc/context/sources/general/manuals/workflows/workflows-resources.tex new file mode 100644 index 000000000..cbed64864 --- /dev/null +++ b/doc/context/sources/general/manuals/workflows/workflows-resources.tex @@ -0,0 +1,156 @@ +% language=uk + +\environment workflows-style + +\startcomponent workflows-resources + +\startchapter[title=Accessing resources] + +One of the benefits of \TEX\ is that you can use it in automated workflows +where large quantities of data is involved. A document can consist of +several files and normally also includes images. Of course there are styles +involved too. At \PRAGMA\ normally put styles and fonts in: + +\starttyping +/data/site/context/tex/texmf-project/tex/context/user/<project>/... +/data/site/context/tex/texmf-fonts/data/<foundry>/<collection>/... +\stoptyping + +alongside + +\starttyping +/data/framework/... +\stoptyping + +where the job management services are put, while we put resources in: + +\starttyping +/data/resources/... +\stoptyping + +The processing happens in: + +\starttyping +/data/work/<uuid user space>/ +\stoptyping + +Putting styles (and resources like logos and common images) and fonts (if the +project has specific ones not present in the distribution) in the \TEX\ tree +makes sense because that is where such files are normally searched. Of course you +need to keep the distributions file database upto|-|date after adding files there. + +Processing has to happen isolated from other runs so there we use unique +locations. The services responsible for running also deal with regular cleanup +of these temporary files. + +Resources are somewhat special. They can be stable, i.e.\ change seldom, but more +often they are updated or extended periodically (or even daily). We're not +talking of a few files here but of thousands. In one project we have 20 thousand +resources, that can be combined into arbitrary books, and in another one, each +chapter alone is about 400 \XML\ and image files. That means we can have 5000 +files per book and as we have at least 20 books, we end up with 100K files. In +the first case accessing the resources is easy because there is a well defined +structure (under our control) so we know exactly where each file sits in the +resource tree. In the 100K case there is a deeper structure which is in itself +predictable but because many authors are involved the references to these files +are somewhat instable (and undefined). It is surprising to notice that publishers +don't care about filenames (read: cannot control all the parties involved) which +means that we have inconsist use of mixed case in filenames, and spaces, +underscores and dashes creeping in. Because typesetting for paper is always at +the end of the pipeline (which nowadays is mostly driven by (limitations) of web +products) we need to have a robust and flexible lookup mechanism. It's a side +effect of the click and point culture: if objects are associated (filename in +source file with file on the system) anything you key in will work, and +consistency completely depends on the user. And bad things then happen when files +are copied, renamed, etc. In that stadium we can better be tolerant than try to +get it fixed. \footnote {From what we normally receive we often conclude that +copy|-|editing and image production companies don't impose any discipline or +probably simply lack the tools and methods to control this. Some of our workflows +had checkers and fixers, so that when we got 5000 new resources while only a few +needed to be replaced we could filter the right ones. It was not uncommon to find +duplicates for thousands of pictures: similar or older variants.} + +\starttyping +foo.jpg +bar/foo.jpg +images/bar/foo.jpg +images/foo.jpg +\stoptyping + +The xml files have names like: + +\starttyping +b-c.xml +a/b-c.jpg +a/b/b-c.jpg +a/b/c/b-c.jpg +\stoptyping + +So it's sort of a mess, especially if you add arbitrary casing to this. Of course +one can argue that a wrong (relative) location is asking for problems, it's less +an issue here because each image has a unique name. We could flatten the resource +tree but having tens of thousands of files on one directory is asking for +problems when you want to manage them. + +The typesetting (and related services) run on virtual machines. The three +directories: + +\starttyping +/data/site +/data/resources +/data/work +\stoptyping + +are all mounted as nfs shares on a network storage. For the styles (and binaries) +this is no big deal as normally these files are cached, but the resources are +another story. Scanning the complete (mounted) resource tree each run is no +option so there we use a special mechanism in \CONTEXT\ for locating files. + +Already early in the development of \MKIV\ one of the locating mechanisms was +the following: + +\starttyping +tree:////data/resources/foo/**/drawing.jpg +tree:////data/resources/foo/**/Drawing.jpg +\stoptyping + +Here the tree is scanned once per run, which is normally quite okay when there +are not that many files and when the files reside on the machine itself. For a +more high performance approach using network shares we have a different +mechanism. This time it looks like this: + +\starttyping +dirlist:/data/resources/**/drawing.jpg +dirlist:/data/resources/**/Drawing.jpg +dirlist:/data/resources/**/just/some/place/drawing.jpg +dirlist:/data/resources/**/images/drawing.jpg +dirlist:/data/resources/**/images/drawing.jpg?option=fileonly +dirfile:/data/resources/**/images/drawing.jpg +\stoptyping + +The first two lookups are wildcard. If there is a file with that name, it will be +found. If there are more, the first hit is used. The second and third examples +are more selective. Here the part after the \type {**} has to match too. So here +we can deal with multiple files named \type {drawing.jpg}. The last two +equivalent examples are more tolerant. If no explicit match is found, a lookup +happens without being selective. The case of a name is ignored but when found, a +name with the right case is used. + +You can hook a path into the resolver for source files, for example: + +\starttyping +\usepath [dirfile://./resources/**] +\setupexternalfigures[directory=dirfile://./resources/**] +\stoptyping + +You need to make sure that file(name)s in that location don't override ones in +the regular \TEX\ tree. These extra paths are only used for source file lookups +so for instance font lookups are not affected. + +When you add, remove or move files the tree, you need to remove the \type +{dirlist.*} files in the root because these are used for locating files. A new +file will be generated automatically. Don't forget this! + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/workflows/workflows-setups.tex b/doc/context/sources/general/manuals/workflows/workflows-setups.tex new file mode 100644 index 000000000..e9d120f7b --- /dev/null +++ b/doc/context/sources/general/manuals/workflows/workflows-setups.tex @@ -0,0 +1,72 @@ +% language=uk + +\environment workflows-style + +\startcomponent workflows-setups + +\startchapter[title={Setups}] + +Setups are a powerful way to organize styles. They are basically macros but live +in their own namespace. One advantage is that spaces in a setup are ignored so +you can code without bothering about spurious spaces. Here is a trick that you +can use when one style contains directives for multiple products: + +\startbuffer +\startsetups tex:whatever + \fastsetup{tex:whatever:\documentvariable{stylevariant}} +\stopsetups + +\startsetups tex:whatever:foo + FOO +\stopsetups + +\startsetups tex:whatever:bar + BAR +\stopsetups +\stopbuffer + +\typebuffer \getbuffer + +Here we define a main setup \type {tex:whatever} that gets expanded in one of two +variants, controlled by a document variable. + +\startbuffer +\setups{tex:whatever} + +\setupdocument + [stylevariant=foo] + +\setups{tex:whatever} + +\setupdocument + [stylevariant=bar] + +\setups{tex:whatever} +\stopbuffer + +\typebuffer + +These lines result in: + +\getbuffer + +In a similar fashion you can define \XML\ setups that are used to render +elements: + +\starttyping +\startxmlsetups xml:whatever + \xmlsetup{#1}{xml:whatever:\documentvariable{stylevariant}} +\stopxmlsetups + +\startxmlsetups xml:whatever:foo + FOO: \xmlflush{#1} +\stopxmlsetups + +\startxmlsetups xml:whatever:bar + BAR: \xmlflush{#1} +\stopxmlsetups +\stoptyping + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/workflows/workflows-style.tex b/doc/context/sources/general/manuals/workflows/workflows-style.tex new file mode 100644 index 000000000..f29129fcd --- /dev/null +++ b/doc/context/sources/general/manuals/workflows/workflows-style.tex @@ -0,0 +1,49 @@ +\startenvironment workflows-style + +\usemodule + [abr-03] + +\setupbodyfont + [bookman,11pt] + +\definecolor + [maincolor] + [s=.35] + +\setuplayout + [height=middle, + width=middle, + footer=0pt] + +\setupwhitespace + [big] + +\setuphead + [chapter] + [style=\bfc, + color=maincolor, + header=high] + +\setuphead + [section] + [style=\bfb, + color=maincolor] + +\setuptyping + [color=maincolor] + +\setuptype + [color=maincolor] + +\setupdocument + [metadata:author=<author>, + metadata:title=<title>, + author=<author>, + affiliation=<affiliation>, + location=<location>, + title=<title>, + extra=<extra>, + support=<support>, + website=<website>] + +\stopenvironment diff --git a/doc/context/sources/general/manuals/workflows/workflows-suspects.tex b/doc/context/sources/general/manuals/workflows/workflows-suspects.tex new file mode 100644 index 000000000..621fd6f59 --- /dev/null +++ b/doc/context/sources/general/manuals/workflows/workflows-suspects.tex @@ -0,0 +1,54 @@ +% language=uk + +\environment workflows-style + +\startcomponent workflows-suspects + +\startchapter[title={Suspects}] + +When many authors and editors are involved there is the danger of inconsistent +spacing being applied. We're not only talking of the (often invisible in editing +programs) nobreak spaces, but also spacing inside or outside quotations and +before and after punctuation or around math. + +In \CONTEXT\ we have a built||in suspects checker that you can enable with the +following command: + +\starttyping +\enabletrackers[typesetters.suspects] +\stoptyping + +The next table shows some identified suspects. + +\starttexdefinition ShowSample #1 + \NC \type{#1} + \NC \enabletrackers[typesetters.suspects]#1\disabletrackers[typesetters.spacing] + \NC \NR +\stoptexdefinition + +\starttabulate[|||][before=,after=] + \ShowSample{foo$x$} + \ShowSample{$x$bar} + \ShowSample{foo$x$bar} + \ShowSample{$f+o+o$:} + \ShowSample{;$f+o+o$} + \ShowSample{; bar} + \ShowSample{foo:bar} + \ShowSample{\quote{ foo }} + \ShowSample{\quote{bar }} + \ShowSample{\quote{ bar}} + \ShowSample{(foo )} + \ShowSample{\{foo \}} + \ShowSample{foo{\bf gnu}bar} + \ShowSample{foo{\it gnu}bar} + \ShowSample{foo$x^2$bar} + \ShowSample{foo\nobreakspace bar} +\stoptabulate + +Of course this analysis is not perfect but we use it in final checking of complex +documents that are generated automatically from \XML. \footnote {Think of math +school books where each book is assembled from over a thousands files.} + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/workflows/workflows-titlepage.tex b/doc/context/sources/general/manuals/workflows/workflows-titlepage.tex new file mode 100644 index 000000000..f184152b3 --- /dev/null +++ b/doc/context/sources/general/manuals/workflows/workflows-titlepage.tex @@ -0,0 +1,37 @@ +% language=uk + +\environment workflows-style + +\startcomponent workflows-titlepage + +\definefontfeature[LatinModernMonoVariable][default][liga=no] +\definefont[LatinModernMonoVariable][LMTypewriterVarWd-Regular*LatinModernMonoVariable sa 1] + +\startMPpage + + fill fullsquare xysized(PaperWidth,PaperHeight) withcolor .4white ; + + draw image ( + fill arrowhead fullcircle scaled .5 rotated 0 scaled 10 withcolor white ; + fill arrowhead fullcircle scaled .5 rotated 120 scaled 10 withcolor white ; + fill arrowhead fullcircle scaled .5 rotated 240 scaled 10 withcolor white ; + fill arrowhead fullcircle scaled .5 rotated 60 scaled 10 withcolor white ; + fill arrowhead fullcircle scaled .5 rotated 180 scaled 10 withcolor white ; + fill arrowhead fullcircle scaled .5 rotated 300 scaled 10 withcolor white ; + ) xsized (.9PaperWidth) shifted (0,.2PaperWidth) ; + + draw image ( + fill arrowhead fullcircle scaled .5 rotated 0 scaled 10 withcolor .4red withtransparency (1,.5) ; + fill arrowhead fullcircle scaled .5 rotated 120 scaled 10 withcolor .4green withtransparency (1,.5) ; + fill arrowhead fullcircle scaled .5 rotated 240 scaled 10 withcolor .4blue withtransparency (1,.5) ; + fill arrowhead fullcircle scaled .5 rotated 60 scaled 10 withcolor .4cyan withtransparency (1,.5) ; + fill arrowhead fullcircle scaled .5 rotated 180 scaled 10 withcolor .4magenta withtransparency (1,.5) ; + fill arrowhead fullcircle scaled .5 rotated 300 scaled 10 withcolor .4yellow withtransparency (1,.5) ; + ) xsized (.9PaperWidth) shifted (0,.2PaperWidth) ; + + draw textext ("\LatinModernMonoVariable \documentvariable{title}") xsized (.9PaperWidth) shifted (0,-.425PaperWidth) withcolor white ; + draw textext ("\LatinModernMonoVariable \documentvariable{extra}") xsized (.9PaperWidth) shifted (0,-.575PaperWidth) withcolor white ; + +\stopMPpage + +\stopcomponent diff --git a/doc/context/sources/general/manuals/workflows/workflows-xml.tex b/doc/context/sources/general/manuals/workflows/workflows-xml.tex new file mode 100644 index 000000000..0f29f5f55 --- /dev/null +++ b/doc/context/sources/general/manuals/workflows/workflows-xml.tex @@ -0,0 +1,96 @@ +% language=uk + +\environment workflows-style + +\startcomponent workflows-xml + +\startluacode + for i=1,10 do + local filename = string.formatters["temp-%02i.xml"](i) + local filedata = string.formatters["<?xml version='1.0'?><p>snippet %i</p>"](i) + io.savedata(filename,filedata) + end +\stopluacode + +\startchapter[title={XML}] + +When you have an \XML\ project with many files involved, finding the right spot +of something that went wrong can be a pain. In one of our project the production of +some 50 books involves 60.000 \XML\ files and 20.000 images. Say that we have the +following file: + +\startbuffer[demo] +<?xml version='1.0'?> +<document> + <include name="temp-01.xml"/> <include name="temp-02.xml"/> + <include name="temp-03.xml"/> <include name="temp-04.xml"/> + <include name="temp-05.xml"/> <include name="temp-06.xml"/> + <include name="temp-07.xml"/> <include name="temp-08.xml"/> + <include name="temp-09.xml"/> <include name="temp-10.xml"/> +</document> +\stopbuffer + +\typebuffer[demo] + +Before we process this file we will merge the content of the files defined +as includes into it. When this happens the filename is automatically +registered so it can be accessed later. + +\startbuffer +\startxmlsetups xml:initialize + \xmlincludeoptions{#1}{include}{filename|name}{recurse,basename} + \xmlsetsetup{#1}{p|document}{xml:*} +\stopxmlsetups + +\startxmlsetups xml:document + \xmlflush{#1} +\stopxmlsetups + +\startxmlsetups xml:p + \inleftmargin{\infofont\xmlinclusion{#1}} + \xmlflush{#1} + \par +\stopxmlsetups + +\xmlregistersetup{xml:initialize} + +\xmlprocessbuffer{main}{demo}{} +\stopbuffer + +\typebuffer + +In this case we put the name of the file in the margin. Depending on when and how +elements are flushed other solutions, like overlays, can be used. + +\startpacked +\getbuffer +\stoppacked + +At any moment you can see what the current node contains. The whole (merged) +document is also available: + +\startbuffer +\xmlshow{main} +\stopbuffer + +\typebuffer + +A small font is used to typeset the (sub)tree: + +\blank \getbuffer \blank + +You can also save the tree: + +\startbuffer +\xmlsave{main}{temp.xml} +\stopbuffer + +\typebuffer \getbuffer + +This file looks like: + +\typefile{temp.xml} + +\stopchapter + +\stopcomponent diff --git a/doc/context/sources/general/manuals/xtables/xtables-mkiv.tex b/doc/context/sources/general/manuals/xtables/xtables-mkiv.tex new file mode 100644 index 000000000..302f2880c --- /dev/null +++ b/doc/context/sources/general/manuals/xtables/xtables-mkiv.tex @@ -0,0 +1,1225 @@ +% language=uk + +% author : Hans Hagen, PRAGMA ADE, NL +% license : Creative Commons, Attribution-NonCommercial-ShareAlike 3.0 Unported + +\usemodule[art-01,abr-02] + +\definecolor[red] [darkred] +\definecolor[green] [darkgreen] +\definecolor[blue] [darkblue] +\definecolor[yellow] [darkyellow] +\definecolor[magenta][darkmagenta] +\definecolor[cyan] [darkcyan] + +\setupexternalfigures + [location={local,default}] + +\setupbodyfont + [10pt] + +\setuptyping + [color=darkyellow] + +\setuptype + [color=darkcyan] + +% \setupnumbering +% [alternative=doublesided] + +\setuphead + [section] + [color=darkmagenta] + +\setupinteraction + [hidden] + +\startdocument + [metadata:author=Hans Hagen, + metadata:title=Extreme Tables, + author=Hans Hagen, + affiliation=PRAGMA ADE, + location=Hasselt NL, + title=Extreme Tables, + extra=ConTeXt MkIV, + support=www.contextgarden.net, + website=www.pragma-ade.nl] + +\startMPpage + + StartPage ; + fill Page enlarged 2mm withcolor magenta/4 ; + pickup pencircle scaled 2mm ; + numeric n ; n := bbheight Page ; + forever : + n := n / 1.5 ; + draw bottomboundary Page shifted (0, n) withcolor 2yellow/3 withtransparency (1,0.5) ; + draw topboundary Page shifted (0,-n) withcolor 2yellow/3 withtransparency (1,0.5) ; + exitif n < 2cm ; + endfor ; + numeric n ; n := bbheight Page ; + forever : + n := n / 1.5 ; + draw leftboundary Page shifted ( n,0) withcolor 2cyan/3 withtransparency (1,0.5) ; + draw rightboundary Page shifted (-n,0) withcolor 2cyan/3 withtransparency (1,0.5) ; + exitif n < 2cm ; + endfor ; + picture p, q, r ; + p := textext("\ssbf\WORD{\documentvariable{title}}") xsized (bbheight Page - 2cm) rotated 90 ; + q := textext("\ssbf\WORD{\documentvariable{author}}") ysized 1cm ; + r := textext("\ssbf\WORD{\documentvariable{extra}}") xsized bbwidth q ; + draw anchored.rt (p, center rightboundary Page shifted (-1cm,0cm)) withcolor white ; + draw anchored.bot(q, center bottomboundary Page shifted ( 1cm,4.4cm)) withcolor white ; + draw anchored.bot(r, center bottomboundary Page shifted ( 1cm,2.8cm)) withcolor white ; + StopPage ; + +\stopMPpage + +% \page[empty] \setuppagenumber[start=1] + +\startsubject[title={Contents}] + +\placelist[section][criterium=all,interaction=all] + +\stopsubject + +\startsection[title={Introduction}] + +This is a short introduction to yet another table mechanism built in \CONTEXT. It +is a variant of the so called natural tables but it has a different +configuration. Also, the implementation is completely different. The reason for +writing it is that in one of our projects we had to write styles for documents +that had tables spanning 30 or more pages and apart from memory constraints this +is quite a challenge for the other mechanisms, if only because splitting them +into successive floats is not possible due to limitations of \TEX. The extreme +table mechanism can handle pretty large tables and split them too. As each cell +is basically a \type {\framed} and as we need to do two passes over the table, +this mechanism is not the fastest but it is some two times faster than the +natural tables mechanism, and in most cases can be used instead. + +\stopsection + +\startsection[title={The structure}] + +The structure of the tables is summarized here. There can be the usual head, body +and foot specifications and we also support the optional header in following +pages. + +\starttyping +\definextable [tag] | [tag][parent] +\setupxtable [settings] | [tag][settings] + +\startxtable[tag|settings] + \startxtablehead|next|body|foot[tag|settings] + \startxrowgroup[tag|settings] + \startxrow[settings] + \startxcellgroup[tag|settings] + \startxcell[settings] ... \stopxcell + \stopxcellgroup + \stopxrow + \startxrowgroup + \stopxtablehead|next|body|foot +\stopxtable +\stoptyping + +Contrary to what you might expect, the definition command defines a new set of +command. You don't need to use this in order to set up a new settings +environment. Settings and definitions can inherit so you can build a chain of +parent|-|child settings. The grouping is nothing more than a switch to a new set +of settings. + +\stopsection + +\startsection[title={Direct control}] + +A simple table with just frames is defined as follows: + +\startbuffer +\startxtable + \startxrow + \startxcell one \stopxcell + \startxcell two \stopxcell + \stopxrow + \startxrow + \startxcell alpha \stopxcell + \startxcell beta \stopxcell + \stopxrow +\stopxtable +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] \getbuffer \stoplinecorrection + +You can pass parameters for tuning the table: + +\startbuffer +\startxtable[offset=1cm] + \startxrow + \startxcell one \stopxcell + \startxcell two \stopxcell + \stopxrow + \startxrow + \startxcell alpha \stopxcell + \startxcell beta \stopxcell + \stopxrow +\stopxtable +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] \getbuffer \stoplinecorrection + +You can (for as much as they make sense) use the same settings as the \type +{\framed} command, as long as you keep in mind that messing with the frame +related offsets can have side effects. + +\stopsection + +\startsection[title={Sets of settings}] + +Instead of directly passing settings you can use a predefined set. Of course you +can also combine these methods. + +\startbuffer +\definextable + [myxtable] + +\definextable + [myxtable:important] + [myxtable] + +\setupxtable + [myxtable] + [width=4cm, + foregroundcolor=red] + +\setupxtable + [myxtable:important] + [background=color, + backgroundcolor=red, + foregroundcolor=white] +\stopbuffer + +\typebuffer \getbuffer + +We can use these settings in table. Although it is not really needed to define a +set beforehand (i.e.\ you can just use the setup command) it is cleaner and more +efficient too. + +\startbuffer +\startxtable[myxtable] + \startxrow[foregroundcolor=green] + \startxcell one \stopxcell + \startxcell two \stopxcell + \startxcellgroup[foregroundcolor=blue] + \startxcell tree \stopxcell + \startxcell four \stopxcell + \stopxcellgroup + \stopxrow + \startxrow + \startxcell alpha \stopxcell + \startxcell beta \stopxcell + \startxcellgroup[myxtable:important] + \startxcell gamma \stopxcell + \startxcell delta \stopxcell + \stopxcellgroup + \stopxrow +\stopxtable +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] \getbuffer \stoplinecorrection + +The overhead of (chained) settings is quite acceptable and it helps to keep the +source of the table uncluttered from specific settings. + +\stopsection + +\startsection[title={Defining}] + +If needed you can define your own encapsulating commands. The following example +demonstrates this: + +\startbuffer +\definextable[mytable] +\stopbuffer + +\getbuffer \typebuffer + +We now can use the \type{mytable} wrapper: + +\startbuffer +\startmytable[height=4cm,width=8cm,align={middle,lohi}] + \startxrow + \startxcell test \stopxcell + \stopxrow +\stopmytable +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] \getbuffer \stoplinecorrection + +One drawback of using buffers is that they don't play well in macro definitions. +In that case you need to use the following wrapper: + +\startbuffer +\starttexdefinition MyTable #1#2#3#4 + \startembeddedxtable + \startxrow + \startxcell #1 \stopxcell + \startxcell #2 \stopxcell + \stopxrow + \startxrow + \startxcell #3 \stopxcell + \startxcell #4 \stopxcell + \stopxrow + \stopembeddedxtable +\stoptexdefinition +\stopbuffer + +\typebuffer \getbuffer + +This macro is used as any other macro with arguments: + +\startbuffer +\MyTable{one}{two}{three}{four} +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] \getbuffer \stoplinecorrection + +\stopsection + +\startsection[title={Stretching}] + +If you don't give the width of a cell, the widest natural size will be taken. +Otherwise the given width applies to the whole column. + +\startbuffer +\startxtable + \startxrow + \startxcell[width=1cm] one \stopxcell + \startxcell[width=2cm] two \stopxcell + \startxcell[width=3cm] tree \stopxcell + \startxcell[width=4cm] four \stopxcell + \stopxrow + \startxrow + \startxcell alpha \stopxcell + \startxcell beta \stopxcell + \startxcell gamma \stopxcell + \startxcell delta \stopxcell + \stopxrow +\stopxtable +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] \getbuffer \stoplinecorrection + +You can let the cells stretch so that the whole width of the text area is taken. + +\startbuffer[one] +\startxtable[option=stretch] + \startxrow + \startxcell[width=1cm] one \stopxcell + \startxcell[width=2cm] two \stopxcell + \startxcell[width=3cm] tree \stopxcell + \startxcell[width=4cm] four \stopxcell + \stopxrow + \startxrow + \startxcell alpha \stopxcell + \startxcell beta \stopxcell + \startxcell gamma \stopxcell + \startxcell delta \stopxcell + \stopxrow +\stopxtable +\stopbuffer + +\typebuffer[one] + +The available left over space is equally distributed among the cells. + +\startlinecorrection[blank] \getbuffer[one] \stoplinecorrection + +\startbuffer[two] +\startxtable[option={stretch,width}] + \startxrow + \startxcell[width=1cm] one \stopxcell + \startxcell[width=2cm] two \stopxcell + \startxcell[width=3cm] tree \stopxcell + \startxcell[width=4cm] four \stopxcell + \stopxrow + \startxrow + \startxcell alpha \stopxcell + \startxcell beta \stopxcell + \startxcell gamma \stopxcell + \startxcell delta \stopxcell + \stopxrow +\stopxtable +\stopbuffer + +An alternative is to distribute the space proportionally: + +\typebuffer[two] + +\startlinecorrection[blank] \getbuffer[two] \stoplinecorrection + +Just to stress the difference we show both alongside now: + +\startlinecorrection[blank] + \getbuffer[one] + \blank + \getbuffer[two] +\stoplinecorrection + +You can specify the width of a cell with each cell but need to keep into mind +that that value is then used for the whole column: + +\startbuffer +\startxtable + \startxrow + \startxcell[width=1em] one \stopxcell + \startxcell[width=2em] two \stopxcell + \startxcell[width=3em] tree \stopxcell + \startxcell[width=4em] four \stopxcell + \stopxrow + \startxrow + \startxcell alpha \stopxcell + \startxcell beta \stopxcell + \startxcell gamma \stopxcell + \startxcell delta \stopxcell + \stopxrow +\stopxtable +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] \getbuffer \stoplinecorrection + +You can enforce that larger columns win via the \type {option} parameter: + +\startbuffer +\startxtable[option=max] + \startxrow + \startxcell[width=1em] one \stopxcell + \startxcell[width=2em] two \stopxcell + \startxcell[width=3em] tree \stopxcell + \startxcell[width=4em] four \stopxcell + \stopxrow + \startxrow + \startxcell alpha \stopxcell + \startxcell beta \stopxcell + \startxcell gamma \stopxcell + \startxcell delta \stopxcell + \stopxrow +\stopxtable +\stopbuffer + +\typebuffer + +\startlinecorrection[blank] \getbuffer \stoplinecorrection + +\stopsection + +\startsection[title={Spacing}] + +It is possible to separate the cells by horizontal and/or vertical space. As an +example we create a setup. + +\startbuffer +\setupxtable + [myztable] + [option=stretch, + foregroundcolor=blue, + columndistance=10pt, + leftmargindistance=20pt, + rightmargindistance=30pt] +\stopbuffer + +\typebuffer \getbuffer + +You can use the \type {textwidth} parameter to set a specific maximum width. We +now apply the previous settings to an extreme table: + +\startbuffer +\startxtable[myztable] + \startxrow + \startxcell[width=1cm] one \stopxcell + \startxcell[width=2cm,distance=5pt] two \stopxcell + \startxcell[width=3cm] tree \stopxcell + \startxcell[width=4cm] four \stopxcell + \stopxrow + \startxrow + \startxcell[width=1cm] alpha \stopxcell + \startxcell[width=2cm] beta \stopxcell + \startxcell[width=3cm] gamma \stopxcell + \startxcell[width=4cm] delta \stopxcell + \stopxrow +\stopxtable +\stopbuffer + +\typebuffer + +As you can see here, we can still locally overload the settings but keep in mind +that these apply to the whole column then, not to the specific cell. + +\startlinecorrection[blank] \getbuffer \stoplinecorrection + +Vertical spacing is (currently) setup differently, i.e.\ as an argument to the +\type {\blank} command. + +\startbuffer +\startxtable[spaceinbetween=medium] + \startxrow + \startxcell one \stopxcell + \startxcell two \stopxcell + \startxcell tree \stopxcell + \startxcell four \stopxcell + \stopxrow + \startxrow + \startxcell alpha \stopxcell + \startxcell beta \stopxcell + \startxcell gamma \stopxcell + \startxcell delta \stopxcell + \stopxrow +\stopxtable +\stopbuffer + +\typebuffer + +Specifying spacing this way improves consistency with the rest of the document +spacing. + +\startlinecorrection[blank] \getbuffer \stoplinecorrection + +\stopsection + +\startsection[title={Spanning}] + +Of course we can span cells horizontally as well as vertically. Future versions +might provide more advanced options but the basics work okay. + +\startbuffer +\startxtable + \startxrow + \startxcell one \stopxcell + \startxcell[nx=2] two + three \stopxcell + \startxcell four \stopxcell + \startxcell five \stopxcell + \stopxrow + \startxrow + \startxcell[nx=3] alpha + beta + gamma \stopxcell + \startxcell[nx=2] delta + epsilon \stopxcell + \stopxrow +\stopxtable +\stopbuffer + +\typebuffer + +This spans a few cells horizontally: + +\startlinecorrection[blank] \getbuffer \stoplinecorrection + +The next example gives a span in two directions: + +\startbuffer +\startxtable + \startxrow + \startxcell alpha 1 \stopxcell + \startxcell beta 1 \stopxcell + \startxcell gamma 1 \stopxcell + \startxcell delta 1 \stopxcell + \stopxrow + \startxrow + \startxcell alpha 2 \stopxcell + \startxcell[nx=2,ny=2] whatever \stopxcell + \startxcell delta 2 \stopxcell + \stopxrow + \startxrow + \startxcell alpha 3 \stopxcell + \startxcell delta 3 \stopxcell + \stopxrow + \startxrow + \startxcell alpha 4 \stopxcell + \startxcell beta 4 \stopxcell + \startxcell gamma 4 \stopxcell + \startxcell delta 4 \stopxcell + \stopxrow +\stopxtable +\stopbuffer + +\typebuffer + +Of course, spanning is always a compromise but the best fit found by this +mechanism takes natural width, given width and available space into account. + +\startlinecorrection[blank] \getbuffer \stoplinecorrection + +\stopsection + +\startsection[title={Partitioning}] + +You can partition a table as follows: + +\startbuffer +\startxtable + \startxtablehead + \startxrow + \startxcell head one \stopxcell + \startxcell head two \stopxcell + \startxcell head tree \stopxcell + \startxcell head four \stopxcell + \stopxrow + \stopxtablehead + \startxtablenext + \startxrow + \startxcell next one \stopxcell + \startxcell next two \stopxcell + \startxcell next tree \stopxcell + \startxcell next four \stopxcell + \stopxrow + \stopxtablenext + \startxtablebody + \startxrow + \startxcell body one \stopxcell + \startxcell body two \stopxcell + \startxcell body tree \stopxcell + \startxcell body four \stopxcell + \stopxrow + \stopxtablebody + \startxtablefoot + \startxrow + \startxcell foot one \stopxcell + \startxcell foot two \stopxcell + \startxcell foot tree \stopxcell + \startxcell foot four \stopxcell + \stopxrow + \stopxtablefoot +\stopxtable +\stopbuffer + +\typebuffer + +There can be multiple such partitions and they are collected in head, next, body +and foot groups. Normally the header ends up at the beginning and the footer at +the end. When a table is split, the first page gets the header and the following +pages the next one. + +You can let headers and footers be repeated by setting the \type {header} +and|/|or \type {footer} parameters to \type {repeat}. + +\starttyping +\setupxtable + [split=yes, + header=repeat, + footer=repeat] +\stoptyping + +The table can be flushed in the running text but also in successive +floats. Given that the table is in a buffer: + +\starttyping +\placetable[here,split]{A big table.}{\getbuffer} +\stoptyping + +When you specify \type {split} as \type {yes} the caption is taken into account +when calculating the available space. + +There are actually three different split methods. The \type {yes} option works in +text mode as well as in floats, but in text mode no headers and footers get +repeated. If you want that feature in a text flush you have to set \type {split} +to \type {repeat} as well. + +You can keep rows together by passing a \type {samepage} directive. This +parameter can get the values \type {before}, \type {after} and \type {both}. + +\starttyping +\startxtable[split=yes] + \startxrow \startxcell \tttf .01. \stopxcell \stopxrow + \startxrow \startxcell \tttf .... \stopxcell \stopxrow + \startxrow \startxcell \tttf \red .21. \stopxcell \stopxrow + \startxrow[samepage=both] \startxcell \tttf \red .22. \stopxcell \stopxrow + \startxrow[samepage=both] \startxcell \tttf \red .23. \stopxcell \stopxrow + \startxrow \startxcell \tttf .... \stopxcell \stopxrow + \startxrow \startxcell \tttf .99. \stopxcell \stopxrow +\stopxtable +\stoptyping + +\stopsection + +\startsection[title={Options}] + +On the average a table will come out okay but you need to keep in mind that when +(complex) spans are used the results can be less that optimal. However, as +normally one pays attention to creating tables, the amount of control provided +often makes it possible to get what you want. + +In the following situations, the first cell width is determined by the span. It +is possible to make a more clever analyzer but we need to keep in mind that in +the same column there can be entries that span a different amount of columns. Not +only would that be inefficient but it would also be rather unpredictable unless +you know exactly what happens deep down. The following two examples demonstrate +default behaviour. + +\startbuffer +\startxtable + \startxrow + \startxcell[nx=3] + 1/2/3 + \stopxcell + \stopxrow + \startxrow + \startxcell 1 \stopxcell + \startxcell 2 \stopxcell + \startxcell 3 \stopxcell + \stopxrow +\stopxtable +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\startxtable + \startxrow + \startxcell[nx=3] + 1 / 2 / 3 + \stopxcell + \stopxrow + \startxrow + \startxcell 1 \stopxcell + \startxcell 2 \stopxcell + \startxcell 3 \stopxcell + \stopxrow +\stopxtable +\stopbuffer + +\typebuffer \getbuffer + +In practice you will set the width of the columns, as in: + +\startbuffer +\startxtable + \startxrow + \startxcell[nx=3] + 1/2/3 + \stopxcell + \stopxrow + \startxrow + \startxcell[width=\dimexpr\textwidth/3] 1 \stopxcell + \startxcell[width=\dimexpr\textwidth/3] 2 \stopxcell + \startxcell[width=\dimexpr\textwidth/3] 3 \stopxcell + \stopxrow +\stopxtable +\stopbuffer + +\typebuffer \getbuffer + +But, if you want you can control the enforced width by setting an option: + +\startbuffer +\startxtable + \startxrow + \startxcell[nx=3,option=tight] + 1/2/3 + \stopxcell + \stopxrow + \startxrow + \startxcell 1 \stopxcell + \startxcell 2 \stopxcell + \startxcell 3 \stopxcell + \stopxrow +\stopxtable +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\startxtable + \startxrow + \startxcell[nx=3,option=tight] + 1 / 2 / 3 + \stopxcell + \stopxrow + \startxrow + \startxcell 1 \stopxcell + \startxcell 2 \stopxcell + \startxcell 3 \stopxcell + \stopxrow +\stopxtable +\stopbuffer + +\typebuffer \getbuffer + +There is also a global setting: + +\startbuffer +\startxtable[option=tight] + \startxrow + \startxcell[nx=3] + 1/2/3 + \stopxcell + \stopxrow + \startxrow + \startxcell 1 \stopxcell + \startxcell 2 \stopxcell + \startxcell 3 \stopxcell + \stopxrow +\stopxtable +\stopbuffer + +\typebuffer \getbuffer + +\stopsection + +\startsection[title={Nesting}] + +Extreme tables can be nested but you need to keep an eye on inheritance here as +the inner table uses the settings from the encapsulating cell. The widths and +heights of the inner table default to \type {fit}. We could cook up a more +complex nesting model but this one is easy to follow. + +\startbuffer +\startxtable + \startxrow + \startxcell[offset=0pt] + \startxtable[background=color,backgroundcolor=green, + foregroundcolor=white,offset=1ex] + \startxrow + \startxcell[width=1cm] one \stopxcell + \startxcell[width=2cm] two \stopxcell + \stopxrow + \startxrow + \startxcell[width=3cm] alpha \stopxcell + \startxcell[width=4cm] beta \stopxcell + \stopxrow + \stopxtable + \stopxcell + \startxcell two \stopxcell + \stopxrow + \startxrow + \startxcell alpha \stopxcell + \startxcell + \startxtable[background=color,backgroundcolor=red, + foregroundcolor=white] + \startxrow + \startxcell one \stopxcell + \startxcell two \stopxcell + \stopxrow + \startxrow + \startxcell alpha \stopxcell + \startxcell beta \stopxcell + \stopxrow + \stopxtable + \stopxcell + \stopxrow +\stopxtable +\stopbuffer + +\typebuffer + +Here we just manipulate the offset a bit. + +\startlinecorrection[blank] \getbuffer \stoplinecorrection + +\stopsection + +\startsection[title={Buffers}] + +When you don't want to clutter your document source too much buffers can be if +help: + +\startbuffer +\startbuffer[test] +\startxtable + \startxrow + \startxcell[width=1cm] one \stopxcell + \startxcell[width=2cm] two \stopxcell + \stopxrow + \startxrow + \startxcell alpha \stopxcell + \startxcell beta \stopxcell + \stopxrow +\stopxtable +\stopbuffer +\stopbuffer + +\typebuffer \getbuffer + +One way of getting this table typeset is to say: + +\starttyping +\getbuffer[test] +\stoptyping + +Normally this is quite okay. However, internally extreme tables become also +buffers. If you don't like the overhead of this double buffering you can use the +following command: + +\starttyping +\processxtablebuffer[test] +\stoptyping + +This can save you some memory and runtime, but don't expect miracles. Also, this +way of processing does not support nested tables (unless \type {{}} is used). + +\stopsection + +\startsection[title={XML}] + +The following example demonstrates that we can use this mechanism in \XML\ too. +The example was provided by Thomas Schmitz. First we show how a table looks like +in \XML: + +\startbuffer[test] +<table> + <tablerow> + <tablecell> + One + </tablecell> + <tablecell> + Two + </tablecell> + </tablerow> + <tablerow> + <tablecell> + <b>Three</b> + </tablecell> + <tablecell> + Four + </tablecell> + </tablerow> +</table> +\stopbuffer + +\typebuffer[test] + +We need to map these elements to setups: + +\startbuffer +\startxmlsetups xml:testsetups + \xmlsetsetup{main}{b|table|tablerow|tablecell}{xml:*} +\stopxmlsetups + +\xmlregistersetup{xml:testsetups} +\stopbuffer + +\typebuffer \getbuffer + +The setups themselves are rather simple as we don't capture any attributes. + +\startbuffer +\startxmlsetups xml:b + \bold{\xmlflush{#1}} +\stopxmlsetups + +\startxmlsetups xml:table + \startembeddedxtable + \xmlflush{#1} + \stopembeddedxtable +\stopxmlsetups + +\startxmlsetups xml:tablerow + \startxrow + \xmlflush{#1} + \stopxrow +\stopxmlsetups + +\startxmlsetups xml:tablecell + \startxcell + \xmlflush{#1} + \stopxcell +\stopxmlsetups +\stopbuffer + +\typebuffer \getbuffer + +We now process the example. Of course it will also work for files. + +\startbuffer + \xmlprocessbuffer{main}{test}{} +\stopbuffer + +\typebuffer + +The result is: + +\startlinecorrection[blank] \getbuffer \stoplinecorrection + +\stopsection + +\startsection[title={Natural tables}] + +For the impatient a small additional module is provided that remaps the natural +table commands onto extreme tables: + +\startbuffer +\usemodule[ntb-to-xtb] +\stopbuffer + +\typebuffer \getbuffer + +After that: + +\startbuffer +\bTABLE + \bTR + \bTD[background=color,backgroundcolor=red] one \eTD + \bTD[width=2cm] two \eTD + \eTR + \bTR + \bTD[width=5cm] alpha \eTD + \bTD[background=color,backgroundcolor=yellow] beta \eTD + \eTR +\eTABLE +\stopbuffer +\stopbuffer + +\typebuffer + +Will come out as: + +\startlinecorrection[blank] +\getbuffer +\stoplinecorrection + +You can restore and remap the commands with the following helpers: + +\starttyping +\restoreTABLEfromxtable +\mapTABLEtoxtable +\stoptyping + +Of course not all functionality of the natural tables maps onto similar +functionality of extreme tables, but on the average the result will look rather +similar. + +\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 +\stoptabulate + +\stopsection + +\startsection[title={Examples}] + +On the following pages we show some examples of (experimental) features. For this +we will use the usual quotes from Ward, Tufte and Davis etc.\ that you can find +in the distribution. + +\page + +\startbuffer +\startxtable[bodyfont=6pt] + \startxrow + \startxcell \input ward \stopxcell + \startxcell \input tufte \stopxcell + \startxcell \input davis \stopxcell + \stopxrow +\stopxtable +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\startxtable[bodyfont=6pt,option=width] + \startxrow + \startxcell \input ward \stopxcell + \startxcell \input tufte \stopxcell + \startxcell \input davis \stopxcell + \stopxrow +\stopxtable +\stopbuffer + +\typebuffer \getbuffer + +\page + +\startbuffer +\startxtable[bodyfont=6pt] + \startxrow + \startxcell \externalfigure[cow.pdf][width=3cm] \stopxcell + \startxcell \input tufte \stopxcell + \startxcell \input davis \stopxcell + \stopxrow +\stopxtable +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\startxtable[bodyfont=6pt,option=width] + \startxrow + \startxcell \externalfigure[cow.pdf][width=3cm] \stopxcell + \startxcell \input tufte \stopxcell + \startxcell \input davis \stopxcell + \stopxrow +\stopxtable +\stopbuffer + +\typebuffer \getbuffer + +\page + +\startbuffer +\startxtable[option=stretch] + \startxrow + \startxcell bla \stopxcell + \startxcell bla bla \stopxcell + \startxcell bla bla bla \stopxcell + \stopxrow +\stopxtable +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\startxtable[option={stretch,width}] + \startxrow + \startxcell bla \stopxcell + \startxcell bla bla \stopxcell + \startxcell bla bla bla \stopxcell + \stopxrow +\stopxtable +\stopbuffer + +\typebuffer \getbuffer + +\page + +\startbuffer +\setupxtable[suffix][align=middle,foregroundcolor=red] +\setupxtable[blabla][foregroundstyle=slanted] +\setupxtable[crap] [foregroundcolor=blue] +\setupxtable[bold] [crap][foregroundstyle=bold] + +\startxtable % [frame=off] + \startxtablehead + \startxrow[bold] + \startxcell[suffix] head a \stopxcell + \startxcell[blabla] head b \stopxcell + \startxcell head c \stopxcell + \stopxrow + \stopxtablehead + \startxtablebody + \startxrow + \startxcell[suffix][ny=2] cell a 1 \stopxcell + \startxcell cell b 1 \stopxcell + \startxcell cell c 1 \stopxcell + \stopxrow + \startxrow + \startxcell cell b 2 \stopxcell + \startxcell cell c 2 \stopxcell + \stopxrow + \startxrow + \startxcell[suffix] cell a 3 \stopxcell + \startxcell cell b 3 \stopxcell + \startxcell cell c 3 \stopxcell + \stopxrow + \startxrow + \startxcell[suffix] cell a 4 \stopxcell + \startxcell cell b 4 \stopxcell + \startxcell cell c 4 \stopxcell + \stopxrow + \startxrow + \startxcell[suffix] cell a 5 \stopxcell + \startxcell cell b 5 \stopxcell + \startxcell cell c 5 \stopxcell + \stopxrow + \stopxtablebody +\stopxtable +\stopbuffer + +\typebuffer \start \getbuffer \stop + +\page + +\startbuffer +\startxtable[option=stretch] + \startxrow + \startxcell[option=fixed] first cell \stopxcell + \startxcell 101 \stopxcell + \startxcell 102 \stopxcell + \startxcell 103 \stopxcell + \stopxrow + \startxrow + \startxcell 2\high{nd} cell \stopxcell + \startxcell a \stopxcell + \startxcell b \stopxcell + \startxcell c \stopxcell + \stopxrow +\stopxtable +\stopbuffer + +\typebuffer \start \getbuffer \stop + +\page + +\startbuffer[demo] +\startxtable +\startxrow + \startxcell[demo][nx=4] 1 / 2 / 3 / 4 \stopxcell +\stopxrow +\startxrow + \startxcell[demo][nx=3] 1 / 2 / 3 \stopxcell + \startxcell 4 \stopxcell +\stopxrow +\startxrow + \startxcell 1 \stopxcell + \startxcell[demo][nx=3] 2 / 3 / 4 \stopxcell +\stopxrow +\startxrow + \startxcell[demo][nx=2] 1 / 2 \stopxcell + \startxcell 3 \stopxcell + \startxcell 4 \stopxcell +\stopxrow +\startxrow + \startxcell 1 \stopxcell + \startxcell[demo][nx=2] 2 / 3 \stopxcell + \startxcell 4 \stopxcell +\stopxrow +\startxrow + \startxcell 1 \stopxcell + \startxcell 2 \stopxcell + \startxcell[demo][nx=2] 3 / 4 \stopxcell +\stopxrow +\startxrow + \startxcell[demo][nx=2] 1 / 2 \stopxcell + \startxcell[demo][nx=2] 3 / 4 \stopxcell +\stopxrow +\startxrow + \startxcell 1 \stopxcell + \startxcell 2 \stopxcell + \startxcell 3 \stopxcell + \startxcell 4 \stopxcell +\stopxrow +\stopxtable +\stopbuffer + +\startbuffer[tight] +\setupxtable[demo][option=tight] +\stopbuffer + +\startbuffer[normal] +\setupxtable[demo][option=] +\stopbuffer + +\typebuffer[demo] + +\page + +\typebuffer[tight] \start \getbuffer[tight,demo] \stop +\typebuffer[normal] \start \getbuffer[normal,demo] \stop + +% \ruledhbox{\getbuffer[normal,demo]} + +\stopdocument |