diff options
Diffstat (limited to 'doc')
17 files changed, 2178 insertions, 0 deletions
diff --git a/doc/context/documents/general/magazines/mag-0000-mkiv.pdf b/doc/context/documents/general/magazines/mag-0000-mkiv.pdf Binary files differnew file mode 100644 index 000000000..c904eb0f5 --- /dev/null +++ b/doc/context/documents/general/magazines/mag-0000-mkiv.pdf diff --git a/doc/context/documents/general/magazines/mag-0002-mkiv.pdf b/doc/context/documents/general/magazines/mag-0002-mkiv.pdf Binary files differnew file mode 100644 index 000000000..5b88e63bb --- /dev/null +++ b/doc/context/documents/general/magazines/mag-0002-mkiv.pdf diff --git a/doc/context/documents/general/magazines/mag-0006-mkiv.pdf b/doc/context/documents/general/magazines/mag-0006-mkiv.pdf Binary files differnew file mode 100644 index 000000000..a556dc75b --- /dev/null +++ b/doc/context/documents/general/magazines/mag-0006-mkiv.pdf diff --git a/doc/context/documents/general/magazines/mag-0007-mkiv.pdf b/doc/context/documents/general/magazines/mag-0007-mkiv.pdf Binary files differnew file mode 100644 index 000000000..987ddbf7b --- /dev/null +++ b/doc/context/documents/general/magazines/mag-0007-mkiv.pdf diff --git a/doc/context/documents/general/magazines/mag-0010-mkiv.pdf b/doc/context/documents/general/magazines/mag-0010-mkiv.pdf Binary files differnew file mode 100644 index 000000000..41e82974f --- /dev/null +++ b/doc/context/documents/general/magazines/mag-0010-mkiv.pdf diff --git a/doc/context/documents/general/magazines/mag-1101-mkiv.pdf b/doc/context/documents/general/magazines/mag-1101-mkiv.pdf Binary files differnew file mode 100644 index 000000000..6b7c19fc6 --- /dev/null +++ b/doc/context/documents/general/magazines/mag-1101-mkiv.pdf diff --git a/doc/context/documents/general/magazines/mag-1102-mkiv.pdf b/doc/context/documents/general/magazines/mag-1102-mkiv.pdf Binary files differnew file mode 100644 index 000000000..47c00b05b --- /dev/null +++ b/doc/context/documents/general/magazines/mag-1102-mkiv.pdf diff --git a/doc/context/documents/general/magazines/mag-1103-mkiv.pdf b/doc/context/documents/general/magazines/mag-1103-mkiv.pdf Binary files differnew file mode 100644 index 000000000..6cfe20113 --- /dev/null +++ b/doc/context/documents/general/magazines/mag-1103-mkiv.pdf diff --git a/doc/context/documents/general/manuals/charts-mkiv.pdf b/doc/context/documents/general/manuals/charts-mkiv.pdf Binary files differindex 14ad492a1..1a0289aa5 100644 --- a/doc/context/documents/general/manuals/charts-mkiv.pdf +++ b/doc/context/documents/general/manuals/charts-mkiv.pdf diff --git a/doc/context/sources/general/magazines/magazines/mag-0000-mkiv.tex b/doc/context/sources/general/magazines/magazines/mag-0000-mkiv.tex new file mode 100644 index 000000000..7702bfbbc --- /dev/null +++ b/doc/context/sources/general/magazines/magazines/mag-0000-mkiv.tex @@ -0,0 +1,46 @@ +% language=uk + +% author : Hans Hagen +% copyright : PRAGMA ADE & ConTeXt Development Team +% license : Creative Commons Attribution ShareAlike 4.0 International +% reference : pragma-ade.nl | contextgarden.net | texlive (related) distributions +% origin : the ConTeXt distribution +% +% comment : Because this manual is distributed with TeX distributions it comes with a rather +% liberal license. We try to adapt these documents to upgrades in the (sub)systems +% that they describe. Using parts of the content otherwise can therefore conflict +% with existing functionality and we cannot be held responsible for that. Many of +% the manuals contain characteristic graphics and personal notes or examples that +% make no sense when used out-of-context. + +\usemodule[mag-01] + +\startbuffer[abstract] + This is the zero issue of a semi periodical. The associated style can be used + by \CONTEXT\ users to typeset and publish their own issues. +\stopbuffer + +\startdocument + [title={Introduction}, + subtitle={Welcome}, + author={Hans Hagen}, + affiliation=PRAGMA ADE, + date=Januari 2003, + number=0 \MKIV] + +This is the zero issue of a range of \CONTEXT\ related publications, in most +cases short introductions to new functionality. The style may be used by users +for providing similar documents, but preferably not for other purposes, since it +may confuse readers in their expectations. + +We've chosen a layout which is more functional than beautiful. This layout +provides several text areas: headers and footers, margins and edges as well as a +main text area. The surrounding (gray or color) makes the main page (which is +slightly smaller than A4) stand out and is suitable for viewing in spread mode. + +The documents produced at \PRAGMA\ are called {\bf This Way}, user documents gets +the title {\bf My Way}. The \PRAGMA\ issues are numbered. We strongly advise you +not to use the \type {mag-} prefix for your issues, since this may lead to +clashes with files distributed by \PRAGMA. + +\stopdocument diff --git a/doc/context/sources/general/magazines/magazines/mag-0002-mkiv.tex b/doc/context/sources/general/magazines/magazines/mag-0002-mkiv.tex new file mode 100644 index 000000000..45ca4c6c6 --- /dev/null +++ b/doc/context/sources/general/magazines/magazines/mag-0002-mkiv.tex @@ -0,0 +1,102 @@ +% language=uk + +% author : Hans Hagen +% copyright : PRAGMA ADE & ConTeXt Development Team +% license : Creative Commons Attribution ShareAlike 4.0 International +% reference : pragma-ade.nl | contextgarden.net | texlive (related) distributions +% origin : the ConTeXt distribution +% +% comment : Because this manual is distributed with TeX distributions it comes with a rather +% liberal license. We try to adapt these documents to upgrades in the (sub)systems +% that they describe. Using parts of the content otherwise can therefore conflict +% with existing functionality and we cannot be held responsible for that. Many of +% the manuals contain characteristic graphics and personal notes or examples that +% make no sense when used out-of-context. + +\usemodule[mag-01] + +\startbuffer[abstract] + Subpage numbers can save you some messing around with page references. Here + we show some basics. +\stopbuffer + +\startdocument + [title={Page Ranges}, + author=Hans Hagen, + affiliation=PRAGMA ADE, + date=Februari 2003, + number=2 \MKIV] + +This is a simple example of using subpage numbers. Subpage numbers are not +automatically kept track of, so you first need to activate them: + +\startbuffer +\setupsubpagenumber + [way=bychapter, + state=start] +\stopbuffer + +\typebuffer \getbuffer + +After activating this mechanism, you can access the numbers as follows. The +numbers are synchronized in during page building, which means that they are +correct when constructing headers and footers. + +\startbuffer +\setupheadertexts + [\firstsubpage--\lastsubpage] + +\setupfootertexts + [\pagenumber] +\stopbuffer + +\typebuffer \getbuffer + +There are several ways to access those numbers: + +\starttabulate +\NC \type{\firstsubpage} \NC first real pagenumber in range \NC\NR +\NC \type{\prevsubpage} \NC previous real pagenumber in range \NC\NR +\NC \type{\nextsubpage} \NC next real pagenumber in range \NC\NR +\NC \type{\lastsubpage} \NC last real pagenumber in range \NC\NR +\stoptabulate + +\startsetups [sub check] + + \vfill + + \setupbodyfont[8pt] + + \startcolor[MyBlue] + + \starttabulate[|l|r|] + \NC \type{\firstsubpage} \NC \firstsubpage \NC\NR + \NC \type{\prevsubpage} \NC \prevsubpage \NC\NR + \NC \type{\nextsubpage} \NC \nextsubpage \NC\NR + \NC \type{\lastsubpage} \NC \lastsubpage \NC\NR + \NC \type{\nofsubpages} \NC \nofsubpages \NC\NR + \TB + \NC \type{\lastpage} \NC \lastpage \NC\NR + \TB + \NC \type{\subpageno} \NC \number \subpageno \NC\NR + \NC \type{\pageno} \NC \number \pageno \NC\NR + \NC \type{\realpageno} \NC \number \realpageno \NC\NR + \stoptabulate + + \stopcolor + + \vfill \vfill + +\stopsetups + +We will now generate a bunch of fake chapters to illustrate this feature. + +\setuptexttexts + [margin] + [] [\vbox to \textheight{\setups[sub check]}] + +\chapter{Tufte} \dorecurse{15}{\input tufte } +\chapter{Zapf} \dorecurse{10}{\input zapf } +\chapter{Knuth} \dorecurse{20}{\input knuth } + +\stopdocument diff --git a/doc/context/sources/general/magazines/magazines/mag-0006-mkiv.tex b/doc/context/sources/general/magazines/magazines/mag-0006-mkiv.tex new file mode 100644 index 000000000..080127ac1 --- /dev/null +++ b/doc/context/sources/general/magazines/magazines/mag-0006-mkiv.tex @@ -0,0 +1,306 @@ +% language=uk + +% author : Hans Hagen +% copyright : PRAGMA ADE & ConTeXt Development Team +% license : Creative Commons Attribution ShareAlike 4.0 International +% reference : pragma-ade.nl | contextgarden.net | texlive (related) distributions +% origin : the ConTeXt distribution +% +% comment : Because this manual is distributed with TeX distributions it comes with a rather +% liberal license. We try to adapt these documents to upgrades in the (sub)systems +% that they describe. Using parts of the content otherwise can therefore conflict +% with existing functionality and we cannot be held responsible for that. Many of +% the manuals contain characteristic graphics and personal notes or examples that +% make no sense when used out-of-context. + +\usemodule[mag-01,abr-02] + +\setupcolors[rgb=no,cmyk=yes] + +\definecolor[red] [c=.25,m=.75,y=.75,k=.25] +\definecolor[green] [c=.75,m=.25,y=.75,k=.25] +\definecolor[blue] [c=.75,m=.75,y=.25,k=.25] + +\definecolor[tred] [c=.25,m=.75,y=.75,k=.25,t=.5,a=1] +\definecolor[tgreen] [c=.75,m=.25,y=.75,k=.25,t=.5,a=1] +\definecolor[tblue] [c=.75,m=.75,y=.25,k=.25,t=.5,a=1] +\definecolor[tblack] [s=0,t=.75,a=1] + +\definecolor[ocyan] [c=.75] +\definecolor[omagenta] [m=.75] +\definecolor[oyellow] [y=.75] +\definecolor[ogray] [s=.5] + +\startbuffer[abstract] + Occasionally we experiment a bit with (\PDF) features that are useful but at + the same time dangerous when applied uncontrolled. In the process of cleaning + up some files in my source tree and triggered by a discussion about overprint + I decided to move some of that code into the kernel. You are warned! +\stopbuffer + + +\startdocument + [title={A Few Dangerous Features}, + author=Hans Hagen, + affiliation=PRAGMA ADE, + date=June 2004, + number=6 \MKIV] + +\subject{Remark} + +The features discussed here have a so called global character, i.e. all settings +are global by nature. Future releases may introduce (and by default change to) +local behaviour. So, don't make your documents depending on local/global +behaviour. In most cases you will probably not notice the difference. + +\subject{Being negative} + +The \CONTEXT\ page imposition machinery provides negation because sometimes +raster image processors need that feature. In that case negation is applied to +the whole page. Within the document stream inverted colors are normally (and +best) realized with defining an appropriate color. For special purposes we also +provide negation + +\startbuffer +\startcolor[red]\ignorespaces + \input ward + \startnegative\ignorespaces + \input ward + \startpositive\ignorespaces + \input ward + \removeunwantedspaces\stoppositive + \input ward + \removeunwantedspaces\stopnegative + \input ward +\removeunwantedspaces\stopcolor +\stopbuffer + +\typebuffer \getbuffer + +We can also apply negation to graphic, but the result may not be what we expect. +While writing this document \in {figure} [fig:negated] negates well when view in +\GHOSTSCRIPT\ but \ACROBAT~6 shows a strange vertical line pattern. + +\startbuffer +\startcombination + {\startpositive + \externalfigure[hacker.jpg][width=4cm]% + \stoppositive} + {normal} + {\startnegative + \externalfigure[hacker.jpg][width=4cm]% + \stopnegative} + {negative} +\stopcombination +\stopbuffer + +\typebuffer + +\placefigure + [here] [fig:negated] + {Negation of graphics.} + {\getbuffer} + +\subject{Font effects} + +Another bag of tricks concerns font effects. As with negation and the to be +discussed overprint these are implemented using the \CONTEXT\ (still +experimental) feature handler, but this time we don't provide direct commands. +Instead we use arguments to control the effects. + +\startbuffer +In this paragraph we have \starteffect[hidden]hidden a piece of +text\stopeffect. How useful this feature is depends on the kind +of documents you make. An alternative is to put the text in a +viewer layer (\starteffect[hidden]as provided by \PDF\stopeffect) +that is hidden, but since that feature is not widely available +the effects approach is safer. +\stopbuffer + +\typebuffer \getbuffer + +More interesting is changing the way a font is rendered. An outline version is +rendered with the \type {outer} effect. + +\startbuffer +\bf \starteffect[outer]\input ward \stopeffect \par +\stopbuffer + +\typebuffer \start \getbuffer \stop + +The \type {inner} effect is the normal one so there is no reason to show it here. +The \type {both} option combines the two resulting in an extra bold version. + +\startbuffer +\bf \starteffect[both]\input ward \stopeffect \par +\stopbuffer + +\typebuffer \start \getbuffer \stop + +You can influence the linewidth as is demonstrated in the following example: + +\startbuffer +\setupeffect[outer][rulethickness=.8pt] +\bfd \starteffect[outer]Bigger is Beautiful\stopeffect +\stopbuffer + +\typebuffer \start \getbuffer \stop + +Speaking of 2004, in \CONTEXT\ (read: \TEX) intercharacter spacing can only be +achieved by macro processing. The next method works well, but you need to +manipulate the \type {\hsize} yourself, since the typesetting engine is unaware +of this backend manipulation. + +\startbuffer +\setupeffect[both][stretch=2] +\setupalign[right] +\dontleavehmode \hsize=.6\hsize +\bf \starteffect[both]\input ward \stopeffect \par +\stopbuffer + +\typebuffer \start \getbuffer \stop + +The \type {normal} (or \type {inner}) alternative looks as follows: + +\startbuffer +\setupeffect[normal][stretch=2] +\setupalign[right] +\dontleavehmode \hsize=.6\hsize +\bf \starteffect[normal]\input ward \stopeffect \par +\stopbuffer + +\typebuffer \start \getbuffer \stop + +\subject{Overprint and knockout} + +Another feature that should be used with care is overprint. Normally a raster +image processor will knock out colored areas under colored text or areas on top. +This works well when the printing engine (or press) is able to precisely align +the color plates. If not, you will get artifacts that show up as follows (often +such effects occur in newspapers and cheap magazines): + +\definelayer[fake][width=6cm,height=4cm] + +\setlayerframed + [fake] + [preset=lefttop] + [frame=off,width=8cm,height=4cm, + background=color,backgroundcolor=blue,foregroundcolor=white] + {\definedfont[SerifBold at 6\bodyfontsize]cheap} + +\setlayerframed + [fake] + [preset=lefttop,offset=1pt] + [frame=off,width=8cm,height=4cm, + foregroundcolor=tblack] + {\definedfont[SerifBold at 6\bodyfontsize]cheap} + +\startbaselinecorrection +\tightlayer[fake] +\stopbaselinecorrection + +On the one hand we get white spots and depending on how well the ink covers, we +can get darker spots as well. In such cases it's best to overprint the +background, which of course only works as expected when the top color is a well +covering black. Otherwise we probably may have to compensate the color, which in +turn depends on the kind of paper used. + +At the document level, you can set the overprint with: + +\starttyping +\setupcolors[overprint=yes] +\stoptyping + +We show a few examples of local usage: a simple application first (\in {figure} +{a} [fig:overprint]): + +\startbuffer[a] +\framed + [background=color,backgroundcolor=ocyan, + frame=off,offset=.25cm,strut=no] + {\bfb\setstrut + \startoverprint + \framed + [background=color,backgroundcolor=omagenta, + foregroundcolor=oyellow,align={lohi,middle}, + frame=off,width=2.5cm,height=2cm] + {overprint\\\startknockout knockout \stopknockout}% + \stopoverprint + \framed + [background=color,backgroundcolor=omagenta, + foregroundcolor=oyellow,align={lohi,middle}, + frame=off,width=2.5cm,height=2cm] + {knockout\\\startoverprint overprint\stopoverprint}}% +\stopbuffer + +\typebuffer[a] + +We can nest overprint and turn it off as well (\in {figure} {b} [fig:overprint]): + +\startbuffer[b] +\startoverprint +\framed + [background=color,backgroundcolor=ocyan, + frame=off,offset=.25cm,strut=no] + {\bfb\setstrut + \framed + [background=color,backgroundcolor=omagenta, + foregroundcolor=oyellow,align={lohi,middle}, + frame=off,width=2.5cm,height=2cm] + {overprint\\\startknockout knockout\stopknockout}% + \startknockout + \framed + [background=color,backgroundcolor=omagenta, + foregroundcolor=oyellow,align={lohi,middle}, + frame=off,width=2.5cm,height=2cm] + {knockout\\\startoverprint overprint\stopoverprint}% + \stopknockout}% +\stopoverprint +\stopbuffer + +\typebuffer[b] + +Sometimes the overprint preview in \ACROBAT\ works better when we apply a gray +background (\in {figure} {c} [fig:overprint]). We use rather ugly pure \CMYK\ +colors, otherwise the effect is not visible in overprint preview mode. + +\startbuffer[c] +\framed + [background=color,backgroundcolor=ogray,backgroundoffset=.25em, + frame=off,offset=overlay] + {\getbuffer[a]} +\stopbuffer + +\typebuffer[c] + +and (\in {figure} {d} [fig:overprint]): + +\startbuffer[d] +\framed + [background=color,backgroundcolor=ogray,backgroundoffset=.25em, + frame=off,offset=overlay] + {\getbuffer[b]} +\stopbuffer + +\typebuffer[d] + +\startbuffer +\startcombination[2*2] + {\getbuffer[a]} {a} + {\getbuffer[c]} {c} + {\getbuffer[b]} {b} + {\getbuffer[d]} {d} +\stopcombination +\stopbuffer + +\placefigure + [here] [fig:overprint] + {Preview overprint and knockout.} + {\getbuffer} + +If we look at examples~b and~d of \in {figure} [fig:overprint]) in \ACROBAT\ +overprint preview mode, we will see that the effect depends on where we apply the +overprint settings. As said, these are tricky features and should be used with +care and understanding. + +\stopdocument diff --git a/doc/context/sources/general/magazines/magazines/mag-0007-mkiv.tex b/doc/context/sources/general/magazines/magazines/mag-0007-mkiv.tex new file mode 100644 index 000000000..bf2fbb826 --- /dev/null +++ b/doc/context/sources/general/magazines/magazines/mag-0007-mkiv.tex @@ -0,0 +1,202 @@ +% language=uk + +% author : Hans Hagen +% copyright : PRAGMA ADE & ConTeXt Development Team +% license : Creative Commons Attribution ShareAlike 4.0 International +% reference : pragma-ade.nl | contextgarden.net | texlive (related) distributions +% origin : the ConTeXt distribution +% +% comment : Because this manual is distributed with TeX distributions it comes with a rather +% liberal license. We try to adapt these documents to upgrades in the (sub)systems +% that they describe. Using parts of the content otherwise can therefore conflict +% with existing functionality and we cannot be held responsible for that. Many of +% the manuals contain characteristic graphics and personal notes or examples that +% make no sense when used out-of-context. + +\usemodule[mag-01,abr-02,visual] + +\startbuffer[abstract] + The \type {m-visual} module is used in some manuals that come with \CONTEXT\ + to generate random text. This is sometimes less confusing that nice quotes + because the reader can then distinguish the explanation from the example. + This module is not extensive (but may grow) and is just an addition to + already built in visualization tools. +\stopbuffer + +\startdocument + [title={Faking Text and More}, + author=Hans Hagen, + affiliation=PRAGMA ADE, + date=August 2004, + number=7 \MKIV] + +\setupindenting[medium] \indenting[always] \setupwhitespace[none] + +\subject{Remark} + +When again a user asked me for the macros that I use to generate fake text, I +took a while to document them. Most macros use the built in random number +generator. In manuals you may want to control the randomization a bit. You can do +that by setting the seed: + +\starttyping +\setupystem[random=12345] +\stoptyping + +% Some more visualization tricks are discussed in the visual debugger modules \type +% {supp-vis.tex} and \type {core-vis.tex}. If you have special wishes, let me know. +% If they make sense (or more important: if they can be implemented in a decent +% way) they may be honored in the future. + +In \MKIV\ there is a lot of visualization available like showing all boxes, glue, +characters etc.\ (try \type {\showmakeup}) . Many mechanism have dedicated +trackers that visualize matters with color. Here we just mention a few +possibilities of a module with helpers. This module is loaded with: + +\starttyping +\usemodule[visual] +\stoptyping + +\subject{Faking words} + +We don't need much words to demonstrate the macros. Here we fake a single work +with \type {\fakeword}: \fakeword. You can fake a whole bunch with: + +\startbuffer +\fakewords{100}{200} \par +\fakewords {30} {80} \par +\fakewords{200}{200} +\stopbuffer + +\typebuffer \getbuffer + +In addition to \type {\fakewords} we have \type {\fakenwords}. This time we don't +specify a range, but a number and a random seed. + +\startbuffer +\fakenwords{100}{2} % words seed +\stopbuffer + +\typebuffer \getbuffer + +Drop caps can be faked as follows: + +\startbuffer +\fakedroppedcaps{3} +\fakewords{100}{200} \par +\fakewords{100}{200} +\stopbuffer + +\typebuffer \getbuffer + +You can visualize the indentation by adding another faker: + +\startbuffer +\fakeparindent \fakewords{100}{200} +\stopbuffer + +\typebuffer \getbuffer + +You can suppress indentation with: + +\startbuffer +\onlyfakewords{100}{200} +\stopbuffer + +\typebuffer \getbuffer + +You can influence the color by redefining one or more of the folowing fake +colors: + +\startbuffer +\definecolor[fakerulecolor] [black] +\definecolor[fakebaselinecolor] [green] +\definecolor[fakeparindentcolor][blue] +\stopbuffer + +\typebuffer \getbuffer + +In case you wonder if fake words hyphenate, they kind of do, as is shown here: +\bgroup \showfakewords \onlyfakewords{100}{200} \egroup + +\subject{Faking lines} + +Lines can be faked with: + +\startbuffer +\fakelines{3}{5} +\fakelines{4}{8} +\stopbuffer + +\typebuffer \getbuffer + +This is (of course) more efficient than faking words. + +\subject{Faking figures} + +Faking figures does not make that much sense. + +\startbuffer +\fakefigure + [left][] + {10em}{12em} + {3\lineheight}{5\lineheight} + +\fakewords{100}{200} +\stopbuffer + +\typebuffer \getbuffer + +In this case the width will vary between \type {10em} and \type {12em}, while the +height end up somewhere between 3 and~5 times the lineheight. + +If you want nice placeholders you can better use the \METAPOST\ \type {dum} +library. This one hooks into the external figure placement macros and will +produce a random graphic (with more or less random colors). + +\startbuffer +\useMPlibrary[dum] +\placefigure + [left][] + {\fakewords{3}{6}} + {\externalfigure[ForTheMomentFaked][width=3cm,height=2cm]} + +\fakewords{100}{200} +\stopbuffer + +\typebuffer \getbuffer + +\subject{Faking formulas} + +Another probably seldom used placeholder is \type {\fakeformula}: + +\startbuffer +\startformula \fakeformula \stopformula +\stopbuffer + +\typebuffer \getbuffer + +An alternative, showing baselines, is: + +\startbuffer +\startformula \fakespacingformula \stopformula +\stopbuffer + +\typebuffer \getbuffer + +You can trigger drawing of baseline yourself too: + +\startbuffer +\showbaselines +\fakewords{100}{200} \par +\fakewords {30} {80} \par +\fakewords{200}{200} +\stopbuffer + +\typebuffer \bgroup \getbuffer \egroup + +In this case you will notice that this document is not typeset on a grid, and +therefore, since the blank space is set to big the baseline visualization shows +this distance when applicable. + +\stopdocument diff --git a/doc/context/sources/general/magazines/magazines/mag-0010-mkiv.tex b/doc/context/sources/general/magazines/magazines/mag-0010-mkiv.tex new file mode 100644 index 000000000..eb5e2638b --- /dev/null +++ b/doc/context/sources/general/magazines/magazines/mag-0010-mkiv.tex @@ -0,0 +1,527 @@ +% language=uk + +% author : Hans Hagen +% copyright : PRAGMA ADE & ConTeXt Development Team +% license : Creative Commons Attribution ShareAlike 4.0 International +% reference : pragma-ade.nl | contextgarden.net | texlive (related) distributions +% origin : the ConTeXt distribution +% +% comment : Because this manual is distributed with TeX distributions it comes with a rather +% liberal license. We try to adapt these documents to upgrades in the (sub)systems +% that they describe. Using parts of the content otherwise can therefore conflict +% with existing functionality and we cannot be held responsible for that. Many of +% the manuals contain characteristic graphics and personal notes or examples that +% make no sense when used out-of-context. + +\usemodule[mag-01,abr-02] + +\startbuffer[abstract] + The content of tenth magazine was written while listening to Tori Amos' + latest album, The Beekeeper. In the (nice) booklet the text flows in shapes + and here I will demonstrate that \TEX\ can do something similar. It's also a + nice example of applying \HZ\ optimization. +\stopbuffer + +\startdocument + [title={Good looking shapes}, + author=Hans Hagen, + affiliation=PRAGMA ADE, + date=March 2005, + number=10 \MKIV] + +Just as it takes while to get an understanding what \TEX\ is about, it takes a +couple of listening loops to get a general picture about Tori Amos' Beekeeper. +While browsing the rather nicely designed booklet I got puzzled |<|as usual when +seeing such nice book(let)s|>| why everything looked okay except the text. High +end design combined with rather low end typography. Don't get me wrong, apart +from the typesetting it's a pretty good product! Tori being one of my favourite +artists, you can imagine that I wrote quite some \CONTEXT\ code listening to her +music. + +Now I will not argue that \TEX\ (or \CONTEXT) is the proper system for making +\CD\ covers, but since most of such a booklet is a matter of pasting graphics +components together, I can imagine that one should ask someone to typeset the +text snippets using a proper engine. Anyway, most buyers (fans) won't notice it, +but anyone familiar with \TEX\ will immediate get distracted by the strange +intercharacter and interline spacing. + +Typesetting in a fixed shape is non||trivial. First of all lines should break in +a pleasing way. If possible, hyphenation should be avoided. The gaps between +characters must not become to large and the last line should not be too short. +Doing this in \TEX\ is non trivial either, not so much because \TEX\ cannot do +such things, but because one needs to control several mechanisms at once. On the +other hand, one should know what one's dealing with anyway. + +Because the size of the shape is fixed, we can manipulate the number of lines +and/or the line length and scale afterwards to the desired size. The font size is +not fixed. This permits us to implement a semi||automated solution. The +difference between the first version of the solution and current one is that we +take into account an odd|/|even number of lines. Also, finding the best exit +condition took some experiments. The final solution is not that complex and also +shows a couple of tricks. + +\startbuffer +\definecolor[BeeColorA][r=.4,g=.5,b=.6] +\definecolor[BeeColorB][r=.5,g=.6,b=.4] +\definecolor[BeeColorC][r=.6,g=.4,b=.5] + +\definecolor[BeeColor] [BeeColorA] + +\defineoverlay + [beecell] + [\uniqueMPgraphic{beecell}{offset=3mm,color=BeeColor}] + +\startuniqueMPgraphic{beecell}{offset,color} + fill + for i = 1 upto 6 : (0,OverlayHeight/2) + rotatedaround (center OverlayBox,i*60) -- + endfor cycle + withpen pencircle scaled \MPvar{offset} + withcolor \MPvar{color} ; +\stopuniqueMPgraphic +\stopbuffer + +\getbuffer + +The shape we are dealing with looks as follows: + +\startlinecorrection +\startMPcode + fill + for i = 1 upto 6 : (5cm,0) + rotatedaround(origin,i*60) -- + endfor cycle + withpen pencircle scaled 2mm + withcolor \MPcolor{BeeColorC} ; + currentpicture := currentpicture xsized(5cm) ; +\stopMPcode +\stoplinecorrection + +We will will later put such a shape behind the text for which we define an +overlay: + +\typebuffer + +Normally one will not put a shape behind the text, but in our case it illustrates +the idea. We use an offset in order to get a more pleasing look. + +We will use the following two sample texts. The original linebreaks are visible +in the source: + +\startbuffer +\startbuffer[parasol] +\title {PARASOL} when I come to +terms to terms with this when +I come to terms with this when I +come to terms to terms with this my +world will change for me I haven't moved +since the call came since the call came I +haven't moved I stare at the wall knowing on the +other side the storm that waits for me then the +Seated Woman with a Parasol may be the only one you +can't Betray if I'm the Seated Women with a Parasol I will +be safe in my frame I have no need for a sea view for a sea +view I have no need I have my little pleasures this wall +being one of these when I come to terms to terms +with this when I come to terms with this when I +come to terms with this whip lash of Silk on +wool embroidery then the Seated Woman +with a Parasol may be the only one you +can't betray if I'm the Seated Woman +with a Parasol I will be safe in my +frame I will be safe in my frame +in your House in your frame +\stopbuffer + +\startbuffer[beekeeper] +\title {THE BEEKEEPER} Flaxen hair +blowing in the breeze It is time +for the geese to head south I have +come with my mustard seed I cannot +accept that she will be taken from me +``Do you know who I am'' she said ``I'm the +one who taps you on the shoulder when it's +your time Don't be afraid I promise that she +will awake Tomorrow Somewhere Tomorrow +Somewhere'' --- wrap yourself around the Tree of +Life and the Dance of the Infinity of the Hive --- take +this message to Michael I will comb myself into chains In +between the tap dance clan and your ballerina gang I have +come for the Beekeeper I know you want my You want +my Queen --- Anything but this Can you use me instead? +In your gown with your breathing mask Plugged into +a heart machine As if you ever needed one I must +see the Beekeeper I must see if she'll keep her +alive Call Engine 49 I have come with my +mustard seed Maybe I'm passing you by +On my way On my way I'm just passing +you by But don't be confused +One day I'll be coming for you \unknown\space +I must see the Beekeeper +I must see the Beekeeper +\stopbuffer +\stopbuffer + +\typebuffer \getbuffer + +We will call these buffers indirectly (using setups is a convenient way to +collect commands and definitions). + +\startbuffer +\startsetups [beetext] + \getbuffer[parasol] +\stopsetups +\stopbuffer + +\typebuffer \getbuffer + +Now comes the dirty code. We assume that you know a bit of \CONTEXT. First of all +we choose a font, in our case a Termes for the running text. We will use +Hermann Zapf optimization, which is way more acceptable that intercharacter +spacing and gives quite good results here. + +\startbuffer +\definefontfeature[hzdefault][default][hz=quality] +\definefont[BeeFont][file:texgyre-termes*hzdefault] +\stopbuffer + +\typebuffer \getbuffer + +The core of the code is a loop wherein we try to figure out what the best width +is. In principle this method can be used for similar shapes. Beforehand we define +a few variables. + +\startbuffer +\cldcontext{math.cosd(60)} +\cldcontext{math.sind(60)} + +\newdimen\BeeEdge +\newdimen\BeeLine +\newdimen\BeeSize + +\newbox \BeeBox + +\def\BeeLines{17} % choose optimum odd/even +\def\BeeStart{2cm} % set automatically +\def\BeeStep {.5mm} % accurate enough +\stopbuffer + +\typebuffer \getbuffer + +The loop starts with a rather small width and with increasing steps tries to find +the solution where the number of used lines equals the asked number of lines. We +could have used low level \TEX\ primitives, but using a few \CONTEXT\ wrappers +makes more sense because that way struts and alike are set as well. In the end we +stretch the interline spacing to match the height of the cell. + +\startbuffer + +\startsetups beeloop + +\def\title##1% + {{\ss\bf\kerncharacters[0.25]##1}% + \hskip.5em plus .5em minus .25em\relax + \ignorespaces} + +\setbox\scratchbox=\hbox{\setups[beetext]} + +\edef\BeeStart + {\the\dimexpr.5\wd\scratchbox/\BeeLines\relax} + +\def\BeeMax + {10000} + +\def\BeeShapeA + {\scratchdimen\numexpr\recurselevel-1\relax + \dimexpr\BeeEdge/\BeeLast\relax + \appendetoks + \the\dimexpr\BeeEdge- \scratchdimen\relax\space + \the\dimexpr\hsize +2\scratchdimen\relax\space + \to\scratchtoks} + +\def\BeeShapeB + {\appendetoks + \zeropoint\space + \the\dimexpr\hsize+2\BeeEdge\relax\space + \to\scratchtoks} + +\doloop + {\bgroup + \forgetall + \dontcomplain + \edef\BeeLast + {\the\numexpr(\BeeLines\ifodd\BeeLines-1\fi)/2\relax}% + \hsize\dimexpr\BeeStart+\recurselevel\dimexpr\BeeStep\relax\relax + \BeeEdge=\cldcontext{math.cosd(60)}\hsize + \BeeSize=\cldcontext{math.sind(60)}\hsize + \BeeLine=\dimexpr2\BeeSize/\numexpr2*\BeeLast+1\relax\relax + \setupinterlinespace[line=\BeeLine,stretch=.5]% + \setuptolerance[verytolerant]% + \setupalign[hz]% + \parfillskip\zeropoint + \scratchtoks\emptytoks + \ifodd\BeeLines + \dostepwiserecurse{1}{\BeeLast}{+1}{\BeeShapeA}% + \BeeShapeB + \dostepwiserecurse{\BeeLast}{1}{-1}{\BeeShapeA}% + \rightskip\zeropoint + \else + % we want to stay inside the shape, so we need + % to compensate the right side + \advance\hsize +\dimexpr\BeeEdge/\BeeLast\relax + \dostepwiserecurse{1}{\BeeLast}{+1}{\BeeShapeA}% + \dostepwiserecurse{\BeeLast}{1}{-1}{\BeeShapeA}% + \advance\hsize -\dimexpr\BeeEdge/\BeeLast\relax + \rightskip\dimexpr\BeeEdge/\BeeLast\relax + \fi + \setbox\scratchbox\vbox \bgroup + % we set it like this in case grid is turned on + \baselineskip=1\baselineskip plus 20pt minus 20pt + \parshape\numexpr\BeeLines\relax\the\scratchtoks + \begstrut + \ignorespaces\setups[beetext]\removeunwantedspaces + \endstrut + \endgraf + \xdef\BeeTotal{\number\prevgraf}% + \xdef\BeeRate {\number\badness }% + \egroup + \writestatus + {beestate} + { run: \recurselevel\space + target: \BeeLines \space + lines: \BeeTotal \space + badness: \BeeRate}% + \CheckBeeLines % sets 'done' + \ifdone + \vbox to 2\BeeSize + {\unvbox\ifvoid\BeeBox\scratchbox\else\BeeBox\fi}% + \egroup + \exitloop + \else + \egroup + \fi} + +\stopsetups +\stopbuffer + +\getbuffer \typebuffer + +The end criterium is determined by: + +\startbuffer +\def\CheckBeeLines + {\ifnum\BeeTotal>\BeeLines\relax + \donefalse + \else + \donetrue + \fi} +\stopbuffer + +\getbuffer \typebuffer + +This solution is rather safe and, at the cost of the ugly saving of the number of +lines as registered in \type {\prevgraf}, works better than measuring the height +of the box. + +We could build the loop out of more isolated pieces of code like this but the +reason why we do it for the checker is that we now can redefine it. At the cost +of a few more tests, the following checker is better, because it goes on for a +while and keeps looking for better solutions. If you have no idea what badness +is, just skip the following code snippet. + +\startbuffer +\def\CheckBeeLines + {\ifnum\BeeTotal>\BeeLines\relax + \donefalse + \else\ifnum\BeeTotal=\BeeLines\relax + \ifnum\BeeRate=\zerocount + \global\setbox\BeeBox=\box\scratchbox + \donetrue + \else\ifnum\BeeRate<\BeeMax\relax + \global\let\BeeMax\BeeRate + \global\setbox\BeeBox=\box\scratchbox + \donefalse + \else + \donefalse + \fi\fi + \else + \donetrue + \fi\fi} +\stopbuffer + +\getbuffer \typebuffer + +Well, this is not the kind of code you want a designer to enter, but providing it +as feature in a desk top publishing application is also non||trivial because each +case differs and turning many knobs to get things done is not easy either, so +basically it comes down to manual work (neglectable to the total amount of work +involved in getting such a musical product done). Of course one can ask someone +to typeset the text in \TEX\ and provide it as image, but that would make +coordination the production more complex. + +The criterium (here \BeeStep) can be made smaller when you encounter problems. If +we set it to 1mm, we get one case where the amount of lines jumps~2 and the loop +is exit unexpected. Of course one can catch such cases but it does not make much +sense in such a one||shot macro. + +The previous setup is applied as follows: + +\startbuffer +\startsetups beeloner + \framed + [offset=overlay, + frame=off, + background=beecell, + foregroundstyle=\BeeFont] + {\setups[beeloop]} +\stopsetups +\stopbuffer + +\getbuffer \typebuffer + +We will now put several variants alongside. For this we use a layer: + +\startbuffer +\startsetups beesample + +\definelayer + [beekeeper] + [width=13cm, + height=9cm] + +\setlayer + [beekeeper] + [preset=lefttop] + {\scale[width=5cm]{\def\BeeLines{16}\setups[beeloner]}} + +\setlayer + [beekeeper] + [preset=leftbottom] + {\scale[width=5cm]{\def\BeeLines{17}\setups[beeloner]}} + +\setlayer + [beekeeper] + [preset=righttop] + {\scale[width=5cm]{\def\BeeLines{18}\setups[beeloner]}} + +\setlayer + [beekeeper] + [preset=rightbottom] + {\scale[width=5cm]{\def\BeeLines{19}\setups[beeloner]}} + +\setlayer + [beekeeper] + [preset=middle] + {\scale[width=5cm]{\def\BeeLines{20}\setups[beeloner]}} + +\tightlayer[beekeeper] + +\stopsetups +\stopbuffer + +\getbuffer \typebuffer + +\startbuffer[a] +\startsetups [beetext] + \getbuffer[parasol] +\stopsetups + +\definecolor[BeeColor][BeeColorA] \setups[beesample] +\stopbuffer + +\startbuffer[b] +\startsetups [beetext] + \getbuffer[beekeeper] +\stopsetups + +\definecolor[BeeColor][BeeColorB] \setups[beesample] +\stopbuffer + +\startpostponing + +\placefigure + [here] + [fig:parasol] + {Parasol} + {\getbuffer[a]} + +\placefigure + [here] + [fig:beekeeper] + {The Beekeeper} + {\getbuffer[b]} + +\page + +\stoppostponing + +The first samples, shown in \in {figure} [fig:parasol], will be typeset using: + +\typebuffer[a] + +The second example, shown in \in {figure} [fig:beekeeper], is done in a similar +way. We redefine the \type {beetext} setup. + +\typebuffer[b] + +You can zoom in on cells using your viewer. An enlarged example is shown in \in +{figure} [fig:big]. + +\startbuffer +\definecolor[BeeColor][BeeColorC]% +\startcombination + {\scale + [width=.475\textwidth] + {\startsetups[beetext]\getbuffer[parasol]\stopsetups + \def\BeeLines{17}\setups[beeloner]}} + {Parasol} + {\scale + [width=.475\textwidth] + {\startsetups[beetext]\getbuffer[beekeeper]\stopsetups + \def\BeeLines{20}\setups[beeloner]}} + {The Beekeeper} +\stopcombination +\stopbuffer + +\typebuffer + +Choosing the best alternative is a matter of taste. If you ever get a change to +see the \CD\ (a good buy anyway) you will note the difference. It is possible to +improve the spacing at the top and bottom but we leave this as an exercise. + +\placefigure + [here] + [fig:big] + {An few enlarged examples.} + {\getbuffer} + +The downside of this exercise was that in the process my laptop suddenly made +some funny noises and made me end up with a cracked \CD. So in the end the +message may be not to bother too much about badly typeset paragraphs in \CD\ +booklets. + +\vbox to \vsize \bgroup + + \vfil + + \hbox to \hsize \bgroup \hss + \scale + [height=.45\textheight] + {\startsetups[beetext]\getbuffer[parasol]\stopsetups + \defineoverlay[beecell][]\def\BeeLines{17}\setups[beeloner]}% + \hss \egroup + + \vfil \vfil + + \hbox to \hsize \bgroup \hss + \scale + [height=.45\textheight] + {\startsetups[beetext]\getbuffer[beekeeper]\stopsetups + \defineoverlay[beecell][]\def\BeeLines{20}\setups[beeloner]}% + \hss \egroup + + \vfil + +\egroup + +\stopdocument diff --git a/doc/context/sources/general/magazines/magazines/mag-1101-mkiv.tex b/doc/context/sources/general/magazines/magazines/mag-1101-mkiv.tex new file mode 100644 index 000000000..c6baa7617 --- /dev/null +++ b/doc/context/sources/general/magazines/magazines/mag-1101-mkiv.tex @@ -0,0 +1,250 @@ +% language=uk + +% author : Hans Hagen +% copyright : PRAGMA ADE & ConTeXt Development Team +% license : Creative Commons Attribution ShareAlike 4.0 International +% reference : pragma-ade.nl | contextgarden.net | texlive (related) distributions +% origin : the ConTeXt distribution +% +% comment : Because this manual is distributed with TeX distributions it comes with a rather +% liberal license. We try to adapt these documents to upgrades in the (sub)systems +% that they describe. Using parts of the content otherwise can therefore conflict +% with existing functionality and we cannot be held responsible for that. Many of +% the manuals contain characteristic graphics and personal notes or examples that +% make no sense when used out-of-context. + +\usemodule[mag-01,abr-02,job-01] + +\startbuffer[abstract] + For a long time already \CONTEXT\ provides a way to organize your document(s) + in a structure that permits processing of components. This mechanism has been + upgraded a bit in \MKIV\ and here we will summarize the status quo. +\stopbuffer + +\startdocument + [title={Project Structure}, + author=Hans Hagen, + affiliation=PRAGMA ADE, + date=July 2011, + number=1101 \MKIV] + +A regular document has a simple structure. When we talk about structure here, we +only refer to the overall document structure. + +\startscite[tex] +% style specification + +\starttext + % the document content +\stoptext +\stopscite + +For practical reasons we delay initial font loading till the first \type +{\starttext} so that one can overload the defaults. This means that when no +bodyfont is specified, and {\starttext} is not given, there will be hardly any +visible output. + +An example of a more elaborate structure is the following: + +% \enabletrackers[context.trace] + +\startscite[tex] +\environment environment-1 +\environment environment-2 + +\startproduct product-1 + + \component component-1.tex + \component component-2.mkiv + \component component-3.cld + + \component component-1 + \component component-2 + +\stopproduct +\stopscite + +Here we have a specific product, made up out of components and using a few +environment files that specify the style. By default we assume tex files, but you +can be specific and use known suffixes. A less abstract example is the following: + +\startscite[tex] +\environment my-fonts +\environment my-style +\environment my-abbreviations +\environment my-urls + +\startproduct manual + + \component titlepage + \component contents + + \component chapter-1 + \component chapter-2 + \component chapter-3 + + \component index + +\stopproduct +\stopscite + +You can process components and products independently but be aware that you won't +get cross document (or chapter) references then. + +There is one more level: projects. + +\startscite[tex] +\environment my-fonts +\environment my-style +\environment my-abbreviations +\environment my-urls + +\startproject documentation + + \product manual + \product faqs + +\stopproject +\stopscite + +This means that we can also define the manual as follows: + +\startscite[tex] +\project documentation + +\startproduct manual + + \component titlepage + \component contents + + \component chapter-1 + \component chapter-2 + \component chapter-3 + + \component index + +\stopproduct +\stopscite + +Environments are only loaded once and when you run a component or product that +refers to environments or when environments are picked up from an encapsulating +structure you need to be aware of the order of loading. + +The names given after the start command are not that important but the names +after the simple commands refer to filenames, so in the next case there need to +be a file called \type {index.tex}: + +\startscite[tex] +\component index +\stopscite + +Equally valid is: + +\startscite[tex] +\component[index] +\stopscite + +Subpaths are also permitted: + +\startscite[tex] +\component manual/index +\stopscite + +The meaning of the mentioned commands is not frozen but adapts itself to the +current situation. A file can be processed many times, only once or never. The +following table shows what will happen when: + +\ctxlua{moduledata.jobs.showprocessors()} + +When you load an environment or component, you can specify it to be a \LUA\ file +by using the \type {lua} or \type {cld} suffix. In that case the file will be +loaded in the right way. From the table you can deduce that the following is also +valid: + +\startscite[tex] +\environment mystyle + +\starttext + % the content +\stoptext +\stopscite + +combined with: + +\startscite[tex] +\startenvironment mystyle + % the definitions +\stopenvironment +\stopscite + +This is about the simplest structure that you can use that still gives a bit of +abstraction. + +In addition to files in a project structure, you can load predefined modules. + +\startscite[tex] +\usemodule[mathml] +\stopscite + +or more specific: + +\startscite[tex] +\usemodule[x][mathml] +\stopscite + +Which limits the lookup to the \type {x} namespace. The first match quits the +search and the order of lookups is: \type {mkvi}, \type {mkiv}, \type {tex}, +\type {cld}, \type {lua}. It follows that modules can be \LUA\ files. + +When you use structure in the files you will find an overview in the log file. +This looks as follows: + +\starttyping +system > structure > start used structure + +used structure > text: product-1 +used structure > environment: environment-1 +used structure > environment: environment-2 +used structure > product: product-1 +used structure > component: component-1 +used structure > component: component-2 +used structure > component: component-1 +used structure > component: component-2 + +system > structure > stop used structure +\stoptyping + +Some basic logging on the console can be enabled with: + +\startscite[tex] +\enabletrackers[system.jobfiles] +\stopscite + +A new command pair is the following: + +\starttyping +\startdocument[settings] + structured content +\stopdocument +\stoptyping + +The settings are key|/|value pairs and the values can be retrieved using: + +\starttyping +\documentvariable{key} +\stoptyping + +You can set \type {before} and \type {after} parameters and by default these are +set up as follows: + +\starttyping +\setvariables + [document] + [before=\directsetup{document:start}, + after=\directsetup{document:stop}] +\stoptyping + +You can for instance define these setups to generate a title page (using document +variables) and a colophon page. In the future more functionality might be added. + +\stopdocument diff --git a/doc/context/sources/general/magazines/magazines/mag-1102-mkiv.tex b/doc/context/sources/general/magazines/magazines/mag-1102-mkiv.tex new file mode 100644 index 000000000..a63aca94c --- /dev/null +++ b/doc/context/sources/general/magazines/magazines/mag-1102-mkiv.tex @@ -0,0 +1,429 @@ +% language=uk + +% author : Hans Hagen +% copyright : PRAGMA ADE & ConTeXt Development Team +% license : Creative Commons Attribution ShareAlike 4.0 International +% reference : pragma-ade.nl | contextgarden.net | texlive (related) distributions +% origin : the ConTeXt distribution +% +% comment : Because this manual is distributed with TeX distributions it comes with a rather +% liberal license. We try to adapt these documents to upgrades in the (sub)systems +% that they describe. Using parts of the content otherwise can therefore conflict +% with existing functionality and we cannot be held responsible for that. Many of +% the manuals contain characteristic graphics and personal notes or examples that +% make no sense when used out-of-context. + +\usemodule[mag-01,abr-02] + +\startbuffer[abstract] + A not so widely known feature of the verbatim handler in \CONTEXT\ is the + ability to add comments in another style and \MKIV\ even offers a bit more. + Here some examples are shown. +\stopbuffer + +\startdocument + [title={Annotated Verbatim}, + author=Hans Hagen, + affiliation=PRAGMA ADE, + date=July 2011, + number=1102 \MKIV] + +\definetextbackground + [example] + [frame=on, + framecolor=darkblue, + location=paragraph, + leftoffset=1ex, + topoffset=1ex, + bottomoffset=1ex] + +Annotating verbatim content is done using a mechanism called escaping. For such +special cases it's often best to define a specific instance. + +\startbuffer[define] +\definetyping + [annotatedtyping] + [escape=/, + color=darkblue, + before=, + after=] +\stopbuffer + +\startbuffer[example] +\startannotatedtyping +bla = test /bgroup /sl oeps /egroup + /bgroup /bf some more /egroup + | another test + | somethingverylong /bgroup /it oeps /egroup +\stopannotatedtyping +\stopbuffer + +\typebuffer[define,example][option=TEX] \getbuffer[define] + +\starttextbackground[example] + \getbuffer[example] +\stoptextbackground + +In this example the \type {/} now serves as an escape character. Of course you +can also use the normal backslash but then you need to use a command to specify +it. + +\startbuffer[setup] +\setuptyping + [annotatedtyping] + [escape=\letterbackslash] +\stopbuffer + +\typebuffer[setup][option=TEX] \getbuffer[setup] + +Now we can say: + +\startbuffer[example] +\startannotatedtyping +bla = test \bgroup \sl oeps \egroup + \bgroup \bf some more \egroup + | another test + | somethingverylong \bgroup \it oeps \egroup +\stopannotatedtyping +\stopbuffer + +\typebuffer[example][option=TEX] + +and get: + +\starttextbackground[example] + \getbuffer[example] +\stoptextbackground + +You can also define an end symbol: + +\startbuffer[setup] +\setuptyping + [annotatedtyping] + [escape={//,*}, + color=darkblue] + +\definestartstop + [cmt] + [style=\rm\bf] +\stopbuffer + +\typebuffer[setup][option=TEX] \getbuffer[setup] + +Here the \type {//} starts the annotation and \type {*} ends it. + +\startbuffer[example] +\startannotatedtyping +bla = test // \black // \cmt{oeps} * + // \black // \cmt{some more} * + | another test + | somethingverylong // \black // \cmt{oeps} * +\stopannotatedtyping +\stopbuffer + +\typebuffer[example][option=TEX] + +Contrary to the first example, all text in the annotation is treated as \TEX\ +input: + +\starttextbackground[example] + \getbuffer[example] +\stoptextbackground + +You can consider using more balanced tagging, as in: + +\startbuffer[setup] +\setuptyping + [annotatedtyping] + [escape={<<,>>}, + color=darkblue] +\stopbuffer + +\typebuffer[example][option=TEX] + +Watch how we limit the annotation to part of the text: + +\startbuffer[example] +\startannotatedtyping +bla = test << \rm\bf first >> test + << \rm\bf second >> test + | test + | somethingverylong << \rm\bf fourth >> test +\stopannotatedtyping +\stopbuffer + +\typebuffer[example][option=TEX] + +The \type {test} a the end of the lines is verbatim again. + +\starttextbackground[example] + \getbuffer[example] +\stoptextbackground + +If no end symbol is given, the end of the line is used instead: + +\startbuffer[setup] +\setuptyping + [annotatedtyping] + [escape={//,}, + color=darkblue] +\stopbuffer + +\typebuffer[setup][option=TEX] \getbuffer[setup] + +Watch out: here we use \type {{//,}} and not just \type {//} (which would trigger +the escaped variant). + +\definestartstop[cmt][style=\rm\bf] + +\startbuffer[example] +\startannotatedtyping +bla = test // \black // \cmt{oeps} + // \black // \cmt{some more} + | test + | somethingverylong // \black // \cmt{oeps} +\stopannotatedtyping +\stopbuffer + +\typebuffer[example][option=TEX] + +The result is: + +\starttextbackground[example] + \getbuffer[example] +\stoptextbackground + +This can also be done easier by abusing the \type {style} option of \type {cmt}: + +\startbuffer[setup] +\definestartstop + [cmt] + [color=black, + style=\black //\rm\bf\space] +\stopbuffer + +\typebuffer[setup][option=TEX] \getbuffer[setup] + +When we give: + +\startbuffer[example] +\startannotatedtyping +bla = test // \cmt{oeps} + // \cmt{some more} + | test + | somethingverylong // \cmt{oeps} +\stopannotatedtyping +\stopbuffer + +\typebuffer[example][option=TEX] + +We get: + +\starttextbackground[example] + \getbuffer[example] +\stoptextbackground + +For cases like this, where we want to specify a somewhat detailed way to deal +with a situation, we can use processors: \footnote {More mechanisms in \CONTEXT\ +\MKIV\ will use that feature.} + +\startbuffer[setup] +\defineprocessor + [escape] + [style=bold, + color=black, + left=(,right=)] +\stopbuffer + +\typebuffer[setup][option=TEX] \getbuffer[setup] + +The previous definition of the annotation now becomes: + +\startbuffer[setup] +\setuptyping + [annotatedtyping] + [escape=escape->{//,}, + color=darkblue] +\stopbuffer + +\typebuffer[setup][option=TEX] \getbuffer[setup] + +This time no commands are needed in the annotation: + +\startbuffer[example] +\startannotatedtyping +bla = test // first + // second + | test + | somethingverylong // fourth +\stopannotatedtyping +\stopbuffer + +\typebuffer[example][option=TEX] + +The processor is applied to all text following the \type {//}. Spaces before the +text are stripped. + +\starttextbackground[example] + \getbuffer[example] +\stoptextbackground + +As some characters are special to \TEX, sometimes you need to escape the boundary +sequence: + +\startbuffer[setup] +\defineprocessor + [myescape] + [style=\rm\tf, + color=black] + +\setuptyping + [annotatedtyping] + [escape=myescape->{\letterhash\letterhash,}, + color=darkgreen] +\stopbuffer + +\typebuffer[setup][option=TEX] \getbuffer[setup] + +All text between the double hashes and the end of the line is now treated as +annotation: + +\startbuffer[example] +\startannotatedtyping +bla = test ## first \bf test + ## second \sl test + | test + | somethingverylong ## third \it test +\stopannotatedtyping +\stopbuffer + +\typebuffer[example][option=TEX] + +So we get: + +\starttextbackground[example] + \getbuffer[example] +\stoptextbackground + +We can beautify \TEX\ commenting as follows: + +\startbuffer[setup] +\defineprocessor + [comment] + [style=\rm, + color=black, + left={\tttf\letterpercent\space}] + +\setuptyping + [annotatedtyping] + [escape=comment->{\letterpercent\letterpercent,}, + color=darkblue] +\stopbuffer + +\typebuffer[setup][option=TEX] \getbuffer[setup] + +Here the double comments are turned into a single one and the text after it is +typeset in a regular font: + +\startbuffer[example] +\startannotatedtyping +bla = test %% first \bf test + %% second \sl test + | test + | somethingverylong %% third \it test +\stopannotatedtyping +\stopbuffer + +\typebuffer[example][option=TEX] + +This gives: + +\starttextbackground[example] + \getbuffer[example] +\stoptextbackground + +It is possible to define several escapes. Let's start with the delimited variant: + +\startbuffer[setup] +\defineprocessor + [escape_a] + [style=bold, + color=darkred, + left=(, + right=)] + +\defineprocessor + [escape_b] + [style=bold, + color=darkgreen, + left=(, + right=)] + +\setuptyping + [annotatedtyping] + [escape={escape_a->{[[,]]},escape_b->{[(,)]}}, + color=darkblue] +\stopbuffer + +\typebuffer[setup][option=TEX] \getbuffer[setup] + +We can now alternate comments: + +\startbuffer[example] +\startannotatedtyping +bla = test [[ first ]] test [( first )] + [[ second ]] test [( second )] + | test + | somethingverylong [[ fourth ]] test [( fourth )] +\stopannotatedtyping +\stopbuffer + +\typebuffer[example][option=TEX] + +When typeset this looks as follows: + +\starttextbackground[example] + \getbuffer[example] +\stoptextbackground + +The line terminated variant can also have multiple escapes. + +\startbuffer[setup] +\defineprocessor + [annotated_bf] + [style=\rm\bf, + color=darkred] + +\defineprocessor + [annotated_bs] + [style=\rm\bs, + color=darkyellow] + +\setuptyping + [annotatedtyping] + [escape={annotated_bf->{!bf,},annotated_bs->{!bs,}}, + color=darkblue] +\stopbuffer + +\typebuffer[setup][option=TEX] \getbuffer[setup] + +So this time we have two ways to enter regular \TEX\ mode: + +\startbuffer[example] +\startannotatedtyping +bla = test !bf one {\em again} + !bs two {\em again} + | test + | somethingverylong !bf three {\em again} +\stopannotatedtyping +\stopbuffer + +\typebuffer[example][option=TEX] + +These somewhat meaningful tags result in: + +\starttextbackground[example] + \getbuffer[example] +\stoptextbackground + +\stopdocument diff --git a/doc/context/sources/general/magazines/magazines/mag-1103-mkiv.tex b/doc/context/sources/general/magazines/magazines/mag-1103-mkiv.tex new file mode 100644 index 000000000..868535081 --- /dev/null +++ b/doc/context/sources/general/magazines/magazines/mag-1103-mkiv.tex @@ -0,0 +1,316 @@ +% language=uk + +% author : Hans Hagen +% copyright : PRAGMA ADE & ConTeXt Development Team +% license : Creative Commons Attribution ShareAlike 4.0 International +% reference : pragma-ade.nl | contextgarden.net | texlive (related) distributions +% origin : the ConTeXt distribution +% +% comment : Because this manual is distributed with TeX distributions it comes with a rather +% liberal license. We try to adapt these documents to upgrades in the (sub)systems +% that they describe. Using parts of the content otherwise can therefore conflict +% with existing functionality and we cannot be held responsible for that. Many of +% the manuals contain characteristic graphics and personal notes or examples that +% make no sense when used out-of-context. + +\usemodule[mag-01,abr-02] + +\startbuffer[abstract] + The (cross) reference mechanism in \CONTEXT\ is rather complex (in terms of + code) and provides a lot of functionality. Of course one can ask for page + numbers, section numbers, titles, or arbitrary text, but also control the + viewer, go to locations and have chains of actions. In this document we only + discuss some aspects of cross document referencing. This is not a complete + manual. +\stopbuffer + +\startdocument + [title={Cross document referencing}, + author=Hans Hagen, + affiliation=PRAGMA ADE, + date=September 2011, + number=1103 \MKIV] + +\subject{Other documents} + +A straightforward way to refer to something in an other document is by prefixing +the reference by a document tag. Take for instance: + +\startscite[tex] +\in{chapter}[other::whatever] +\stopscite + +Here, \type {other} is either a tag or a filename. In the case if a tag, you also +need a definition like: + +\startscite[tex] +\useexternalfile[other][somefilename] +\stopscite + +Because we load the references of the other file (when present), you can also ask +for titles of chapters. In fact, all the following work: + +\startscite[tex] +\at {page}[other::whatever] +\in {chapter}[other::whatever] +\about [other::whatever] +\goto{location}[other::whatever] +\stopscite + +given of course that in the other file we have set a reference: + +\startscite[tex] +\startchapter[reference=whatever,title={Who cares}] + ... +\stopchapter +\stopscite + +In \MKIV\ this mechanisms has been extended to deal with products and components. +In order not to get clashes between references in multiple chapters, you can do +something like this: + +\startscite[tex] +\setuphead[chapter][referenceprefix=whatever] +\stopscite + +This will create a namespace for this chapter. A more automated alternative is: + +\startscite[tex] +\setuphead[chapter][referenceprefix=+] +\stopscite + +Here the given reference (\type {whatever}) will automatically become the +namespace for that chapter. + +\subject{Products and components} + +This is however somewhat cumbersome when we deal with a project structure. There +we have the complication that we can process components within a product and +although one will only do this for proofing it makes sense at least to deal with +references in other components. + +In the test suite there are four files demonstrating what is possible. They can +be recognized by the name \type {cross-*.tex}. The product file \type {cross-100} +includes two components: + +\startscite[tex] +\startproduct cross-100 + + \component cross-001 + \component cross-002 + +\stopproduct +\stopscite + +In these components there are references to the other component. The cross +reference mechanism will automatically use the component's name as namespace but +only when you say: + +\startscite[tex] +\setupreferencing[autofile=yes] +\stopscite + +A component looks as follows: + +\startscite[tex] +\setupreferencing[autofile=yes] +\setupinteraction[state=start] + +\startcomponent cross-001 + +\product cross-100 + +\startchapter[title=One,reference=one] + ... +\stopchapter + +\stopcomponent +\stopscite + +When a component is processed, the references of the product are also loaded. +Actually, some more information fetched so that for instance the chapter number +gets set as well as the page number. + +Of course this will not guarantee that all referencing turns out right, but it's +better than nothing. There are now several ways to refer to something, and as we +have quite some fallback heuristics in place all the following will work out +well. However, keep in mind that when multiple \type {one}'s are uses you might +end up with the wrong one when no prefix is given. + +\startscite[tex] +\at {page}[one] +\in {chapter}[one] +\about [one] +\goto{location}[one] + +\at {page}[cross-001:one] +\in {chapter}[cross-001:one] +\about [cross-001:one] +\goto{location}[cross-001:one] + +\at {page}[cross-001::one] +\in {chapter}[cross-001::one] +\about [cross-001::one] +\goto{location}[cross-001::one] + +\at {page}[cross-001:::one] +\in {chapter}[cross-001:::one] +\about [cross-001:::one] +\goto{location}[cross-001:::one] +\stopscite + +So what do the (subtle) differences in colons mean? The \type {cross-001:} prefix +is just a prefix. Such a prefix is not always related to a document but it +happens that when no other match is found, an extra check takes place to see if +it is a component namespace. This is new per September 2011. + +The \type {cross-001::} prefix is the official way to refer to another document +and this is no news. However, the \type {cross-001:::} prefix is new and +depending on how the document is run, is either a regular namespace prefix (one +colon) or an external reference (two colons). When you use the project structure +this might be the best way to go. The reason is that order of looking (and +fallbacks) is better defined this way. + +So, given that you have a proper usage of product and components, the following +method is to be preferred: + +\startscite[tex] +\at {page}[other:::one] in \from[other] +\in chapter}[other:::one] of \from[other] (\about[other:::one]) +\goto{details}[other:::one] +\stopscite + +Keep in mind that in most cases a combination of components and extra prefixes +(that is, explicitly set prefixes) work ok. The prefixing mechanism is controlled +with: + +\startscite[tex] +\setupreferencing[prefix=blabla] +\stopscite + +but you will seldom need this command. In order to prevent clashes you can best +use some redundancy: + +\startscite[tex] +\placefigure[here][fig:foo]{}{}{} +\placetable [here][tab:foo]{}{}{} +\stopscite + +works out quite well. + +\subject{Reference commands} + +In \MKII\ the main reference mechanism handled not only user references but also +stored section numbers, section titles, captions and all that made sense to refer +to. In \MKIV\ we carry around way more information and references are stored in +and retrieved from several data structures. Although we keep much more +information in memory and store more information in the auxiliary file, we save +some too because now (for instance) section titles are stored only once. + +The following two commands store an explicit reference, unrelated to a structural +component. However, with the page number we also store information about the +current section so that we can add a prefix any time we want. + +\startscite[tex] +\textreference[sometag]{some text} +\pagereference[sometag] +\stopscite + +Keep in mind that these commands insert a so called node so they can best be +attached to some content in order not to dangle around and interfere with +spacing. The following works okay: + +\startscite[tex] +\dontleavehmode\textreference[ward]{Quoting Ward}\input ward +\stopscite + +A rather low level (not interactive) fetching can be done as follows: + +\startscite[tex] +\ref[text][sometag] +\ref[page][sometag] +\stopscite + +We already saw some more advanced commands to retrieve reference data: + +\startscite[tex] +\at {page}[one] +\in {chapter}[one] +\about [one] +\goto{location}[one] +\stopscite + +These commands will create a hyperlink when interactivity is turned on. + +The \type {\at} command typesets the page number and the \type {\in} command +typesets a number. The \type {\about} command deals with the title. In the case +of a regular reference the last two commands do a similar thing but the last one +adds quotes (by default). The \type {\goto} command only has a meaning in +interactive documents. It does not add anything to the text. + +In interactive mode all these commands will apply a so called contrast color in +case the reference refers to the page itself. + +There are two commands that relate to current location: + +\startscite[tex] +\somewere{before}{current}{after}[one] +\atpage[one] +\stopscite + +The first command typesets one of the three texts, which one depends of the +typeset and referred \type {one} being on the same page. The second command +generates a text automatically. + +Although not related to the kind of references we discuss here, you can define +symbolic references with: + +\startscite[tex] +\definereference[symbolic name][real reference] +\resetreference[symbolic name] +\stopscite + +Using this only makes sense in interactive documents where we can have special +operations with arguments and combinations of such references. + +\subject{Reference formats} + +You can control the formatting of references in detail using the setup command. +For instance you can tweak the way sections numbers are prefixed but as this +relates to numbering this will not be discussed here. Reference formats are +another way to control the rendering + +\startscite[tex] +\definereferenceformat[informula] [left=(,right=),text=formula] +\definereferenceformat[informulas] [left=(,right=),text=formulas] +\definereferenceformat[andformula] [left=(,right=),text=and] +\definereferenceformat[andformulas][left=(,right=),text=and] + +\informula [b] and \informula [for:c] +the \informula {formulas}[b] \informula {and} [for:c] +the \informulas {formulas}[b] \informula {and} [for:c] +the \informulas [b] \informula {en} [for:c] +the \informulas [b] \andformula [for:c] +\stopscite + +Instead of a text, one can specify a label, which should be defined with \type +{\setuplabeltext}. + +\subject{User references} + +You can create user references too. This is done with the following command: + +\startscite[tex] +\setreference[myref][key-1=value-1,key-2=value-2] +\stopscite + +You can then ask for keys using: + +\startscite[tex] +\getreference[myref][key-2] +\stopscite + +In principle you can add filters and rendering variants as well using \LUA\ code +but that is rather specialized and often not needed. + +\stopdocument |