\enableregime      % probably not needed here, but it's a strong habit
	[utf-8]
\usemodule         % My Way
	[mag-01]

% remove this: why doesn't \defaultencoding switch to EC automatically?
\usetypescript
	[palatino][ec] % \defaultencoding
\setupbodyfont
	[palatino,10pt]

\setuptyping       % all the \type-ing will be done in TeX
	[file]
	[option=TEX]
\setuptype
	[option=TEX]

\setupitemize
	[packed]
\setupframedtexts
	[frame=off,
	 background=screen,
	 width=\textwidth]

% In my opinion this should be the default
\chardef\TeXtextcolormode\zerocount
\runMPgraphicstrue
\runMPTEXgraphicstrue

\definecolor[HighlightColor][black]

% TODO (the way I imagine that the My Way module should work):
% - put title= into PDF title
% - put author= into PDF author
% - put My Way into PDF subject
\setvariables
  [magazine]
  [title={\color[HighlightColor]{\textbackslash sometxt}: \color[HighlightColor]{some} nice techniques\crlf for placing \color[HighlightColor]{text} labels on graphics},
   author={Mojca Miklavec},
   date=\currentdate,
  ]
% well, since the above is not implemented yet, we'll do it manually
\setupinteraction
	[author=Mojca Miklavec,
	 title={sometxt: some nice techniques for placing text on graphics},
	 subject={My Way},
	 keyword={},
	]

\def\dangerous{\color[red]{$\dagger$}}
\def\getexample
	{\placefigure[force]{none}{\getbuffer}}

% Other TODO's
% - fix colors in the \type+\bug+

% FIXME: temporary turn the shading off, otherwise it takes too long for GV to display the file
%\startuseMPgraphic{paper}
%  sh := define_circular_shade(a,a,0,bbheight(OverlayBox),
%   \MPcolor{InnerColor},\MPcolor{OuterColor}) ;
%  fill OverlayBox withshade sh ;
%  fill OverlayBox withcolor .5white ;
%\stopuseMPgraphic
\setupinmargin
	[style=italic]

% Bug in \type needs some workaround to show the content at least partially OK
\startbuffer[abstract]
This will be the abstract - but this is still a DRAFT version of the document. Neither content nor the design has been finished/polished out. Please report any bugs/typos/comments/suggestions.
\stopbuffer

\starttext \setups[titlepage] \setups[title]

%\setupheadertexts[Simple Alignment]

%\section{Motivation}

%\section{About this documentation and dangerous sections (\dangerous)}

%\CONTEXT\ tries to remain as backward compatible as possible. However, this is only true for the user interface --- low-level interface might (and does) change. It's highly probable that hacking and changing undocummented low-level commands might prevent the commands from working properly in the future.

%Some of the tricks described here might be on the border of what is considered user-interface and low-lever interface, so I've put a \dangerous\ sign next to them. For everyday usage these tricks are not needed anyway, but if you want to use them --- please use with some care.

\section{Hello world!}

\setuptype[option=MP]
In \METAPOST, the standard way of placing text on graphics is to use the \type+btex ... etex+ construct as in the following example:

\setuptyping[file][option=MP]
\startbuffer
beginfig(1);
   draw fullcircle xyscaled (3cm,2cm);
   label(btex Hello world! etex, origin);
endfig;
end.
\stopbuffer
\typebuffer
\setuptyping[file][option=TEX]

In \CONTEXT\ you would now do the same with::

\startbuffer
\startMPcode
   draw fullcircle xyscaled (3cm,2cm);
   label(\sometxt{Hello world!}, origin);
\stopMPcode
\stopbuffer
\typebuffer

Both approaches should yield equivalent result in this case:

\getexample

However, the \type+btex ... etex+ syntax has so many drawbacks (in both efficiency and flexibility) that it's use is {\bf strongly discouraged}.

There exists yet another possibility to place labels, namely \type+textext("...")+\footnote{documented in the \METAFUN\ manual} with the same hello-world example below.

\startbuffer
\startMPcode
   draw fullcircle xyscaled (3cm,2cm);
   label(textext("Hello world!"), origin);
\stopMPcode
\stopbuffer
\typebuffer

\setuptype[option=TEX]
Before Spring 2006 it was so buggy that it was hardly working anywhere and very soon after Hans \& Taco fixed most bugs, a much more efficient \type+\sometxt+ has been introduced to replace it. But despite its inefficiency, \type{textext} cannot be replaced trivially by \type+\sometxt+ in all the cases. For auto-generated strings, loops and macros it's still useful.

For an average user there's really not much left to say about \type{\sometxt}, apart from asking them to use it instead of any other alternative if possible. The rest of the document is devoted to the curious ones.

\section{Some Pitfalls}

{\it(I don't like the section name)}

Normally this should be the very last section in the manual, but {\bf some default settings need to be changed} if you experience problems (or even before you do).

\subsection{\textbackslash runMPgraphicstrue, \textbackslash runMPTEXgraphicstrue}

To be able to use \type{\sometxt} properly, you need to have \type{runMPgraphics} set to \type{true}.\footnote{This might be a bug, but without it you'll get wrong scaling when using more than one text label in a picture.}

In order to be able to use \type{textext} at all you also need to set \type+\runMPTEXgraphicstrue+.

You'll find the two settings in \type{tex/context/user/cont-sys.rme} in your {\tt\sl TEXMF} tree. If you want to change these values, uncomment the corresponding two lines and save the file as \type{cont-sys.tex}. That way your settings won't get lost next time when you update \CONTEXT.

{\it TODO: I have to check if one really has to enable write18 in order to be able to use \type{\runMPTEXgraphicstrue}. Because that would mean that one can only use \type{\sometxt} with \type{write18} enabled. That would be a pitty.}

\page
\subsection{Color stacks}

% Because of limited suport for nested colors, \type+\TeXtextcolormode+ switch has been introduced. By default it's value is set to {\sl one} (and might change to {\sl two} in future), but
If you want to use \type+withcolor+, you need\footnote{This document has been typeset with \type+\chardef\TeXtextcolormode\zerocount+ as well.}
\startbuffer
\chardef\TeXtextcolormode\zerocount
\stopbuffer
\typebuffer

The value of \type+\TeXtextcolormode+ means:
\startitemize[packed] % change itemize into something more suitable: description or ...
	\item {\bf 0}: nothing, withcolor works ok, but nested colors fail
	\item {\bf 1}: local color stack ok
	\item {\bf 2}: obey color stack (not yet supported)
\stopitemize

To see the difference, take a look at the following examples:

\startbuffer
\startuseMPgraphic{text color mode}
	draw \sometxt{this is \color[red]{red} and blue} withcolor blue;
	draw \sometxt{this is \color[red]{red} and black} shifted (4cm,0);
\stopuseMPgraphic

% default
\chardef\TeXtextcolormode\plusone
\useMPgraphic{text color mode}
\color[green]{\useMPgraphic{text color mode}}

\chardef\TeXtextcolormode\zerocount
\useMPgraphic{text color mode}
\color[green]{\useMPgraphic{text color mode}}
\stopbuffer
\typebuffer
\getexample

% recover from the example above
% \chardef\TeXtextcolormode\zerocount

\page
\section{textext("not to be thrown away yet")}

Most commercials or even manuals tell you only what the product they're selling is good for.
Here we'll make an exception and start with something where \type{\sometxt} is not good at all,
so we'll be forced to use the old \type{textext} macro for it.

On the first figure there is circle drawn first, followed by a loop which places twelve tics and numbers\footnote{Placement of numbers is visually bad, but placing them properly would require longer code and wouldn't bring anything to understanding of the example.} next to them, each one rotated for $i\cdot30^{\circ}$ in the clockwise (negative) direction.

\startbuffer
\startMPcode
	numeric r; r = 1.5cm;
	draw fullcircle scaled 2r;
	for i=1 upto 12:
		draw (origin--down) scaled 4pt shifted (0,r) rotated -30i;
		label(textext(decimal i), up scaled .75r rotated -30i);
	endfor;
\stopMPcode
\stopbuffer
\typebuffer
\getexample

\type{decimal} converts numerical value of the counter $i$ into string, which is then passed to \type{textext()} as an argument.

Passing values to both \type{btex ... etex} and \type{\sometxt} in such a way is not possible, that's why more tricky approaches are needed to achieve the same result. Or, we can always call \type{btex 1 etex}, \type{textext("1")} or \type+\sometxt{1}+ twelve times of course, with different argument each time.

\page

The second example shows us how strings can be concatenated together, so that the counter now takes the role of an index inside a math expression. Also, the calculated length of the perimeter can be written. That last thing would be the least trivial to get with \type{\sometxt}. It's probably not impossible to do it\footnote{If you like challenges, this might be a nice one. If you find a solution, please share it with the \CONTEXT\ community.}, but this article won't cover it.

\startbuffer
\startMPcode
	numeric r; r = 1cm;
	pair v[];
	path p;

	for i=1 upto 5:
		% define the five vertices
		v[i] = up scaled r rotated -72i;
		% draw labels: $v_1$, $v_2$, ... $v_5$
		label(textext("$v_" & decimal i & "$"), v[i] scaled 1.2);
	endfor;

	% define and draw the pentagon
	p = for i=1 upto 5: v[i]-- endfor cycle;
	draw p;
	% write out the calculated perimeter
	draw textext("length: " & decimal (arclength p/1cm) & " cm") shifted (4cm,0);
\stopMPcode
\stopbuffer
\typebuffer
\getexample

\page

If you want to use \type+textext+ inside your own macros (which possibly reside in an external file), you should also use \type+\forceMPTEXcheck{your_macro_name}+. This command triggers a more exhaustive scan of the contents, to assure an additional \TEX\ run to typeset the label when needed. {\it (I have no idea how to formulate this sentence.)}

{\sl my\_macros.mp:}
\startbuffer
vardef label_for_vertex(expr n) =
	textext("$v_" & decimal n & "$")
enddef
\stopbuffer
\setuptyping[file][option=MP]
\typebuffer
\setuptyping[file][option=TEX]

{\sl\TEX\ file:}
\startbuffer
\forceMPTEXcheck{label_for_vertex}

\startMPcode
input my_macros ;
for i=1 upto 6:
	draw label_for_vertex(i) shifted ((1cm,0) rotated 60i);
endfor;
\stopMPcode
\stopbuffer
\typebuffer

\startbuffer
\forceMPTEXcheck{label_for_vertex}

\startMPcode
vardef label_for_vertex(expr n) =
	textext("$v_" & decimal n & "$")
enddef;

for i=1 upto 6:
	draw label_for_vertex(i) shifted ((1cm,0) rotated 60i);
endfor;
\stopMPcode
\stopbuffer
\getexample

%{\sl (For a more detailed documentation about \METAPOST\ and/or \METAFUN\ please refer to the two manuals.)}

\page
\section{\textbackslash sometxt\{Some really nice features\}}
%\startitemize[packed]
%\item It's highly inefficient: needs a separate \TEX\ run to be processed.
%\item Consequently labels are processed in an isolated environment: tricky constructs don't work and you can't borrow definitions from the document. You have to define the proper font and additional macros separately.
%\item You can't use it in loops to generate text automatically.
%\stopitemize

%The power of \type{\sometxt} lies mostly in its efficiency and ??? the ability to use document-wide macro definitions???. The last issue, loops, is still not as user-friendly as it could be and in some situations not possible at all.

%\type+\sometxt{...}+ has been introduced in Spring 2006. Before that, \type{textext("...")} was a recommended way to place labels on \METAFUN\ graphics. In contrast to \type{\sometxt} it can handle \METAPOST-generated strings (in loops for example), but is still almost as inefficient as \type{btex ... etex}.


\subsection{Why is \textbackslash sometxt so much better than textext?}

{\sl (you may skip this if you want; it's not finished yet anyway)}

\startitemize
\head There is one obvious reason: {\bf speed}.

Processing each graphic needs a separate \METAPOST\ run and processing text inside a graphic needs a separate \CONTEXT\ run. Usually the document is processed twice, which means additional four \CONTEXT\ runs plus some conversions just to get those two simple(TODO: use better word!) graphics in the previous section. And all that appears to be extremely slow.

But there are more reasons than just the efficiency.

\head document-wide definitions are seen

The fact that \type{textext} triggers a new \CONTEXT\ run doesn't only affect efficiency, but also the scope of your definitions. Inside of \type{textext} you can only use standard \CONTEXT\ macros since the content is compiled in an isolated environment.

Well, there are some exceptions to the rule, but most of them are just calling for troubles. There is
\startbuffer
\startMPenvironment % with an optional argument [global]
 ... place for your settings \& definitions ...
\stopMPenvironment
\stopbuffer
\getbuffer
but even such simple things as definitions with arguments will fail to work. You can \type{\input} a file with definitions however, which might be slightly more reliable.

TODO: EXAMPLE!

\head problems with expansion

TODO: I don't know how to explain it, but as far as I remember math expressions (fractions perhaps) never worked as they were supposed to

\head less characters to escape

TODO: Assign a problem to write a double quote into textext

\stopitemize

\page
\subsection{Shortcuts}

If you need to use the same command inside \type+\sometxt+ multiple times, you can define a shortcut for it with \type+\definetextext[name]{\command}+. This will make \type+\sometxt[name]{whatever}+ equal to \type+\sometxt{\command{whatever}}+.

\startbuffer
\def\ForThoseWhoReallyHateLongCommands#1%
    {\framed[framecolor=blue]{\strut\bs #1}}
\definetextext[xs]{\ForThoseWhoReallyHateLongCommands}

\startMPcode
picture p; p = \sometxt[xs]{Framed title with eXtra Small overhelm};
fill bbox p withcolor .7white;
draw p;
draw \sometxt[xs]{\dots\ and another one} shifted (6cm,-4.5mm);
\stopMPcode
\stopbuffer
\typebuffer
\getexample

\subsection{Baseline placement}

By default texts are placed on the baseline {\it(which is OK: I guess that this sectio is not needed)}.

\startbuffer
\startMPcode
vardef place(expr p) =
	image(draw p;
	      draw (xpart llcorner p,0)--(xpart lrcorner p,0);)
enddef;

draw place(\sometxt[d]{depth: baseline on $y=0$}) shifted (-5cm,0);
draw place(\sometxt[n]{no depth: lower bound on $y=0$});

\stopMPcode
\stopbuffer
\typebuffer
\getexample

\page
\subsection{Accessing text labels from metapost}

\type+\sometxt+ can be used inside inline graphics (for example inside \type+\startMPcode+, \type+\startuseMPgraphic+ etc.), but not in plain .mp files or in some more complex cases. The following example shows how to define text labels and how to access them from metapost.

\startbuffer
\startTeXtexts
	\TeXtext{3}{Hello}
	\TeXtext{202}{world!}
\stopTeXtexts

\startMPcode
	% this could be written in an external metapost file
	draw sometxt(3) withcolor red;
	draw sometxt(202) shifted (1cm,0) withcolor blue;
\stopMPcode
\stopbuffer
\typebuffer
\getexample

Watch out. \type+\sometxt+ replaces what has previously been defined with \type+\TeXtext+, so the following example is not really a bug. If you want to prevent clashes, use higher numbers in arguments.

\startbuffer
\startTeXtexts
	\TeXtext{2}{Hello}
	\TeXtext{1}{world!}
\stopTeXtexts

\startMPcode
	% this could be written in an external metapost file
	draw sometxt(2) withcolor red;
	draw sometxt(1) shifted (1cm,0) withcolor blue;
	draw \sometxt{bug!} shifted (3cm,0);
\stopMPcode
\stopbuffer
\typebuffer
\getexample

\page
\subsection{Loops}

Let's see how the \quotation{\type{textext}} examples can be rewritten using \type{sometxt} with predefined labels:

\startbuffer
\startTeXtexts
	% equivalent to \TeXtext{i}{i}
	\dorecurse{12}{\TeXtext{\recurselevel}{\recurselevel}}
\stopTeXtexts

\startMPcode
	numeric r; r = 1.5cm;
	draw fullcircle scaled 2r;
	for i=1 upto 12:
		draw (origin--down) scaled 4pt shifted (0,r) rotated -30i;
		label(sometxt(i), up scaled .75r rotated -30i);
	endfor;
\stopMPcode
\stopbuffer
\typebuffer
\getexample

\startbuffer
\startTeXtexts
	% equivalent to \TeXtext{i}{$v_i$}
	\dorecurse{5}{\TeXtext{\recurselevel}{$v_{\recurselevel}$}}
\stopTeXtexts

\startMPcode
	numeric r; r = 1cm;
	pair v[];
	path p;

	for i=1 upto 5:
		% define the five vertices
		v[i] = up scaled r rotated -72i;
		% draw labels: $v_1$, $v_2$, ... $v_5$
		label(sometxt(i), v[i] scaled 1.2);
	endfor;

	% define and draw the pentagon
	p = for i=1 upto 5: v[i]-- endfor cycle; draw p;
\stopMPcode
\stopbuffer
\typebuffer
\getexample

A careful reader will notice a subtle difference in the two graphics: the one created with \type{textext} uses Latin Modern (default font), while the one created with \type+\sometxt+ uses the document font. Those who want to use the same font with \type+textext+ should use something like this to the document preamble:

\startbuffer
\startMPenvironment[global]
   \usetypescript[palatino][ec]
   \setupbodyfont[palatino,10pt]
\stopMPenvironment
\stopbuffer
\typebuffer


\subsection{currentcolor}

When no color is specified, metapost uses black by default. If you want to draw something in the same color as the surrounding text, you can use \type+\MPcolor{currentcolor}+.

\startbuffer
\startuseMPgraphic{current color}
	fill fullcircle scaled 1cm shifted (-5mm,-3mm);
	fill fullcircle scaled 1cm withcolor \MPcolor{currentcolor};
\stopuseMPgraphic

\hbox{         black circle: \useMPgraphic{current color}
\color[blue]{   blue circle: \useMPgraphic{current color}}}

\stopbuffer
\typebuffer
\getexample

\page
\subsection{More complex example}

{\it(Needs more comments.)}

\startbuffer
\defineconversion
    [MySym]
    [$\star$,$\circ$,$\bullet$]

% define the labels
\startTeXtexts
\doloop{
    \doifelseconversionnumber{MySym}{\recurselevel}
        {\TeXtext{\recurselevel}{\convertnumber{MySym}{\recurselevel}}}
        {\exitloop}
}
\stopTeXtexts

% remember the number of different symbols
\doloop{
    \doifelseconversionnumber{MySym}{\recurselevel}
        {\edef\numberofsymbols{\recurselevel}}
        {\exitloop}
}

\startMPcode
for i=0 upto 10:
    draw sometxt(i mod \numberofsymbols + 1)
         shifted ((right scaled 8i) rotated 28i);
endfor;
\stopMPcode
\stopbuffer
\typebuffer
\getexample

\section{Feature requests}
\subsection{Shortcuts with optional parameters}

\startbuffer
\sometxt[my][iwona,20pt]{How can this be typeset with 20pt iwona}
\sometxt[my]{and this with the document font?}

% should become equivalent to
\sometxt{\switchtobodyfont[iwona,20pt]\strut How can this ...}
\stopbuffer
\typebuffer

\subsection{rename \textbackslash sometxt to \textbackslash textext}

\subsection{make \textbackslash TeXtextcolormode default to 0}

\section{Summary}

\starttabulate[|l|p(1.8cm)|p|]
\NC
	{\type{btex ... etex}}
\NC
	deprecated: inefficient,\crlf not flexible
\NC
	A \METAPOST\ command.\crlf
	\type{\sometxt} should be used in \CONTEXT\ instead.
\NC\NR\NC
	{\type{textext("...")}}
\NC
	inefficient,\crlf but flexible
\NC
	A \METAFUN\ command, which enables concatenation of strings and thus {\bf dynamic} generation of labels.
\NC\NR\NC
	\type{\texttext}\type{{{...}}}
\NC
	inefficient,\crlf not flexible
\NC
	This is only a wrapper around \type{textext(...)}.\crlf
	\type{\sometxt} should be used instead;
\NC\NR\NC
	\type{\sometxt}\type{{{...}}}
\NC
	efficient,\crlf not flexible
\NC
	The {\bf recommended} command to typeset text, unless dynamic labels are needed.
\NC\NR\NC
	{\type{sometxt(}{\sl number}\type{)}}
\NC
	low-level
\NC
	Used to access labels, previously defined with \type{\TeXtext}\type{{{number}}}\type{{{...}}}
\NC\NR
\stoptabulate

\startbuffer
\startTeXtexts
   \TeXtext{number}{...}
\stopTeXtexts
\stopbuffer

\starttabulate[|p(5.1cm)|p|]
\NC
	\typebuffer
\NC
	For advanced usage only: to define labels that can be drawn later with \type{sometxt(number)}.
\NC\NR
\stoptabulate


\stoptext