%D \module
%D   [       file=supp-emp,
%D        version=2000.08.09,
%D          title=\CONTEXT\ Support Macros,
%D       subtitle=\EMTEX\ specials to \PDF\ conversion,
%D         author=Hans Hagen,
%D           date=\currentdate,
%D      copyright={PRAGMA / Hans Hagen \& Ton Otten}]
%C
%C This module is part of the \CONTEXT\ macro||package and is
%C therefore copyrighted by \PRAGMA. See mreadme.pdf for 
%C details. 

%M \input supp-emp 

%D When \THANH, the author of \PDFTEX, and I were exchanging
%D some emails on \PDFTEX\ functionality, positional
%D information popped up as potential extension. Actually, it
%D did not take that much time to cook up the basic
%D functionality and the author had implemented it before I
%D could even start to think about real advanced applications. 
%D 
%D I'm sure that \TEX\ programmers can spend many days on how
%D and what kind of information is needed if you want to have
%D access to positions, but since high level macros will
%D probably be used anyway, even things like multiple reference
%D points have proved to be rather unimportant at the system
%D level. 
%D 
%D Therefore, \PDFTEX\ provides just these three primitives: 
%D 
%D \starttabulatie[|l|l|]
%D \NC \type {\pdfsavepos}  \NC marks the current position          \NC \NR
%D \NC \type {\pdflastxpos} \NC the last marked horizontal position \NC \NR
%D \NC \type {\pdflastypos} \NC the last marked vertical position   \NC \NR
%D \stoptabulatie
%D 
%D Based on these three primitives, very advanced systems can
%D be build, and for some time now, \CONTEXT\ has such a
%D system in its core. However, not everyone uses \CONTEXT, so
%D we will demonstrate position tracking in generic applications. 
%D 
%D Because \PDFTEX\ produces its output directly, many of those
%D nice tricks provided by back||ends by means of \type
%D {\special} fail when producing \PDF\ code directly. Take for
%D instance \EMTEX\ specials. When someone sent me a mail
%D asking if \PDFTEX\ did support those specials, the original 
%D answer was \citaat {no}, but in the last few years I have learned 
%D that you must never underestimate \TEX's capabilities. 
%D 
%D I must admit that I never use those specials myself, but
%D from the way they were used in the macros I was sent, I
%D learned that they depend on the back||end's capability to
%D access the current position. For those who know \TEX\ this
%D may be bad news, since pure \TEX\ does not provide any
%D positional information. So in order to use those specials,
%D you must be sure that they are supported by every driver you
%D use. However, the good news is that \PDFTEX\ does support
%D position tracking, so here is our generic example. 
%D 
%D The two \EMTEX\ specials we need to implement are packaged
%D into the macros \type {\EMmoveto} and \type {\EMlineto},
%D like: 
%D 
%D \starttypen
%D \def\EMmoveto{\special{em:moveto}}
%D \def\EMlineto{\special{em:lineto}}
%D \stoptypen
%D 
%D They are used in macro packages to draw lines, and the
%D results are often boxes with content like the following: 
%D 
%D \startbuffer
%D \vbox to 2cm
%D   {\offinterlineskip \EMmoveto
%D    \hskip 7cm        \EMlineto
%D    \vskip 2cm        \EMlineto
%D    \vskip-2cm        \EMlineto}
%D \stopbuffer
%D 
%D \typebuffer
%D 
%D This box will contain a triangle, and when typeset, it should
%D look like: 
%D 
%D \startregelcorrectie[blanko]
%D \haalbuffer
%D \stopregelcorrectie

\ifx\dosetpositionpt\undefined % non context part

%D These two macros can be implemented as follows. When moving
%D to a position, we only have to register the new coordinates.
%D Once they are known, we use them to draw a line and
%D afterwards we save these end coordinates as starting point
%D for the next line segment. So, at each point specified by
%D \type {\EMlineto} we need to know the coordinates. 

\def\EMmoveto%
  {\EMgetposition\EMlastmovex\EMlastmovey}

%D The primitives \type {\pdflastxpos} and \type
%D {\pdflastypos} return a number, representing the $x$ and
%D $y$ coordinate in scaled points, \TEX's smallest unit of
%D length. We need to convert this number into base points as
%D used by \POSTSCRIPT\ and \PDF. When done, we insert some
%D literal \PDF\ code into the text using \type {\pdfliteral}.
%D Here, the \type {m} means \citeer {moveto}, the \type {l}
%D means \citeer {lineto} and the \type {S} operator \citeer
%D {strokes} (draws) the line. The macro \type {\EMlinewd} 
%D holds the linewidth in basepoints. 

\def\EMlinewd{.4}

\def\EMlineto%
  {\bgroup
   \EMgetposition\EMlastlinex\EMlastliney
   \count0=\EMlastmovex \advance\count0 by -\EMlastlinex
   \count2=\EMlastmovey \advance\count2 by -\EMlastliney
   \divide\count0 by 65536
   \divide\count2 by 65536
   \pdfliteral{\EMlinewd\space w 0 0 m \the\count0 \space\the\count2 \space l S}%
   \global\let\EMlastmovex\EMlastlinex
   \global\let\EMlastmovey\EMlastliney
   \egroup}

%D We need a fresh start, so we first set the current position 
%D to zero. 

\def\resetEMspecials%
  {\gdef\EMlastmovex{0}\gdef\EMlastmovey{0}}

%D Next comes the macro that keeps track of the position. The
%D current position is marked with \type {\pdfsavepos} and its
%D coordinates are written to a file whenever the page is
%D shipped out, since \type {\write} postpones its action
%D until that moment. The file has entries like: 
%D 
%D \starttypen
%D \EMsetpos 1 4661756 46651918
%D \EMsetpos 2 5000359 46990521
%D \EMsetpos 3 4661756 46313315
%D \EMsetpos 4 5338962 46990521
%D \EMsetpos 5 4661756 45974712
%D \stoptypen
%D 
%D These lines are written with the command: 
%D 
%D \starttypen
%D \write\EMfile
%D   {\EMsetpos\number\EMcounter
%D    \space\number\pdflastxpos\space\number\pdflastypos}%
%D \stoptypen
%D 
%D In reality the argument to \type {\write} looks slightly
%D more complicated, because we have to make sure that the
%D number of the current position is frozen and \type
%D {\EMsetpos} is not expanded. We do so by explicitly
%D expanding the number beforehand and preventing expansion of
%D \type {\EMsetpos}. 
 
\def\EMgetposition#1#2%
  {\bgroup
   \pdfsavepos
   \global\advance\EMcounter by 1
   \expandafter\write\expandafter\EMfile\expandafter
     {\expandafter\noexpand\expandafter\EMsetpos\number\EMcounter
      \space\number\pdflastxpos\space\number\pdflastypos}%
   \EMsetcounters
   \xdef#1{\the\count0}%
   \xdef#2{\the\count2}%
   \egroup}

%D The counter mentioned a few lines ago needs to be 
%D declared before it can be used. 

\newcount\EMcounter 

%D We also need a dedicated file slot.  

\newwrite\EMfile

%D Before we open the file for writing, we read in the data 
%D written in the previous pass, but only if the file is 
%D present.

\def\EMfilename{\jobname.emp}

\def\startEMspecials%
  {\resetEMspecials
   \openin\scratchread=\EMfilename \relax
   \ifeof\scratchread\else \input \EMfilename \relax \fi
   \closein\scratchread
   \immediate\openout\EMfile=\EMfilename\relax}

\def\stopEMspecials%
  {\closeout\EMfile}

%D Just to be sure, we test if \type {\scratchread} is defined, 
%D and if not, we allocate a slot. 

\ifx\undefined\scratchread \newread\scratchread \fi

%D This leaves us two commands. The \type {\EMsetpos} command 
%D that ends up in the file stores each position in a macro.
%D When this macro is expanded, it assigns the coordinates to 
%D two scratch counters.

\def\EMsetpos#1 #2 #3 % number x y
  {\expandafter\xdef\csname EM:#1\endcsname{\count0=#2 \count2=#3}}

%D This position is recalled with its companion macro. First we
%D set the counters to zero. When the position is unknown,
%D nothing happens since the \type {\csname...} will expand to
%D \type {\relax}. 

\def\EMsetcounters%
  {\count0=0 \count2=0 
   \csname EM:\the\EMcounter\endcsname}

%D These macros are rather independent of the macro package you
%D use. For instance, in \CONTEXT\ the following works well:  
%D 
%D \startbuffer[pos-en]
%D \setuppositioning[unit=ex]
%D \startpositioning
%D   \dostepwiserecurse{-10}{10}{1}
%D     {\position(0,\recurselevel){\EMmoveto}
%D      \position(\recurselevel,0){\EMlineto}}
%D \stoppositioning
%D \stopbuffer
%D 
%D \startbuffer[pos-nl]
%D \stelpositionerenin[eenheid=ex]
%D \startpositioneren
%D   \dostepwiserecurse{-10}{10}{1}
%D     {\positioneer(0,\recurselevel){\EMmoveto}
%D      \positioneer(\recurselevel,0){\EMlineto}}
%D \stoppositioneren
%D \stopbuffer
%D 
%D \typebuffer[pos-en]
%D 
%D Here, we hook the \EMTEX\ macros into an existing text 
%D positioning mechanism, which positions the commands
%D using \TEX's skips and kerns. 
%D 
%D \startregelcorrectie[blanko]
%D \haalbuffer[pos-nl]
%D \stopregelcorrectie
%D 
%D Of course one should start and end the file with:
%D 
%D \starttypen
%D \startEMspecials
%D \stopEMspecials
%D \stoptypen 
%D 
%D and, if needed, reset the begin position at each page using: 
%D 
%D \starttypen
%D \resetEMspecials 
%D \stoptypen

\fi % end of non context part 

\ifx\dosetpositionpt\undefined \else % context part

\edef\EMlinewd{\the\linewidth}

%D A few pages ago, we mentioned that \CONTEXT\ has built||in 
%D position tracking. This means that when we want to implement
%D this kind of trickery in this macro package, we can fall
%D back on existing functionality. In the following alternative
%D we will also use a few skips. This keeps the source readable
%D and \CONTEXT\ has plenty of unused registers to accomodate 
%D this strategy.

\newcount\EMcounter \def\EMvariable{EM:\the\EMcounter}

\newskip \EMlastmovex \newskip \EMlastmovey
\newskip \EMlastlinex \newskip \EMlastliney

\def\resetEMspecials%
  {\global\EMlastmovex=0pt \global\EMlastmovey=\EMlastmovex}

\resetEMspecials \appendtoks\resetEMspecials\to\everyshipout

%D Watch how we reset the specials after a page is flushed. We
%D don't have to bother about files here, because saving and
%D recalling is already implemented. Although not needed, we
%D define the start||stop macros, so that \CONTEXT\ users who 
%D key them in are not confronted with error messages. 

\let\startEMspecials\relax \let\stopEMspecials\relax

\def\EMgetposition#1#2%
  {\global\advance\EMcounter 1 
   \setposition\EMvariable
   \global#1=\POSx\EMvariable
   \global#2=\POSy\EMvariable}

\def\EMmoveto%
  {\EMgetposition\EMlastmovex\EMlastmovey}

\def\EMlineto%
  {\EMgetposition\EMlastlinex\EMlastliney
   \global\advance\EMlastmovex -\EMlastlinex
   \global\advance\EMlastmovey -\EMlastliney
   \ScaledPointsToBigPoints{\number\EMlastmovex}\EMx
   \ScaledPointsToBigPoints{\number\EMlastmovey}\EMy
   \pdfliteral{\EMlinewd\space w 0 0 m \EMx \space \EMy \space l S}%
   \global\EMlastmovex\EMlastlinex
   \global\EMlastmovey\EMlastliney}

%D The command \type {\setposition} registers a position by
%D name (here \type {\EMvariable}), while \type {\POSx} and
%D \type {\POSy} give you access to the coordinates. 
%D 
%D These three commands are containes in a suite of low level
%D commands that can be used to register and get access to
%D positional information. The current mechanism is not yet
%D complete, but already provides enough hooks for advanced
%D embedded graphics. Its functionality is a natural extension
%D to the \METAPOST\ support already present in \CONTEXT.
%D Therefore, more advanced examples can be found in the
%D \METAFUN\ manual, since they fall beyond the scope of this
%D module. 

\fi % end of context part 
 
%D As a bonus, I will now provide a few macros that will make
%D this mechanism transparant to \DVI\ as well as \PDF\
%D output. We will use \type {\pdfoutput} as trigger. 

\ifx\pdfoutput\undefined \chardef\pdfoutput=0 \fi 

%D We save some of the macros we defined previously:

\let\pdfEMmoveto\EMmoveto \let\pdfstartEMspecials\startEMspecials
\let\pdfEMlineto\EMlineto \let\pdfstopEMspecials \stopEMspecials

%D We now redefine them to support \DVI\ and \PDF. 

\def\EMmoveto{\ifcase\pdfoutput\special{em:moveto}\else\pdfEMmoveto\fi}
\def\EMlineto{\ifcase\pdfoutput\special{em:lineto}\else\pdfEMlineto\fi}

\def\startEMspecials{\ifcase\pdfoutput\else\pdfstartEMspecials\fi}
\def\stopEMspecials {\ifcase\pdfoutput\else\pdfstopEMspecials \fi}

%D If there is any real demand for this in \CONTEXT, I will
%D hook these macros in the special drivers, so that their
%D support becomes more natural. 
 
%D You may want to change the default linewidth. The following
%D macro does the job. Beware of the fact that \type
%D {\special}'s may interfere with the typesetting process. 
%D
%D \starttypen 
%D \setEMlinewidth{1pt}
%D \stoptypen

\def\setEMlinewidth#1% this could be done more efficient for
  {\bgroup           % context alone, but it's a hack anyway
   \dimen0=#1\relax
   \count0=\dimen0
   \divide\count0 by 65536
   \ifcase\pdfoutput 
     \special{em:linewidth \the\dimen0}%     
   \fi
   \xdef\EMlinewd{\the\count0}%
   \egroup}

%D You may wonder to what extent positional tracking is
%D \PDFTEX\ specific. In \CONTEXT, we also support position
%D tracking in \DVI\ by using specials and analyzing the \DVI\
%D file afterwards using a \PERL\ script created by Taco
%D Hoekwater. Since many of the advanced \TEX\ features depend
%D on some kind of back||end, we don't consider it to be a
%D disadvantage. Of course, the \PDFTEX\ way is not only
%D cleaner, but also faster. It was more out of curiosity than
%D out of need that we provided the \DVI\ methods as well.
%D Also, it is always good to have more roads to reach the same
%D goal. 

\endinput 
