path: root/tex/context/base/spec-ini.tex

%D \module
%D   [       file=spec-ini,
%D        version=1996.01.25,
%D          title=\CONTEXT\ Special Macros,
%D       subtitle=Initialization,
%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. 

%D Specials are \TEX's channel to the outside world. They make
%D \TEX\ even more platform independant and permit easy
%D adaption to new developments. One major drawback of specials
%D is that they have to be supported by printer drivers. We've
%D tried to overcome this problem by implementing specials as
%D a sort of drivers themselves.

\writestatus{loading}{Context Special Macros / Initialization}

\unprotect

\startmessages  dutch  library: specials
  title: specials
      1: -- geladen
      2: verdere nesting is niet toegestaan --
      3: -- gereset
      4: commando -- bestaat niet
      5: definitiefile -- wordt geladen
      6: nesting is niet toegestaan
      7: onbekende driver --
\stopmessages

\startmessages  english  library: specials
  title: specials
      1: -- loaded
      2: no deeper nesting is permitted --
      3: -- is reset
      4: command -- does not exist
      5: loading definition file --
      6: nesting is not permitted
      7: unknown driver --
\stopmessages

\startmessages  german  library: specials
  title: spezielles
      1: -- geladen
      2: keine tiefere Verschachtelung erlaubt --
      3: -- ist zurueckgesetzt
      4: Befehl -- existiert nicht
      5: lade Definitionsdatei --
      6: Verschachtelung nicht erlaubt
      7: unbekante Driver --
\stopmessages

\startmessages  czech  library: specials
  title: speciality
      1: -- nacteno
      2: neni dovoleno hlubsi zanoreni --
      3: -- je resetovano
      4: prikaz -- neexistuje
      5: nacita se definicni soubor --
      6: zanoreni neni dovoleno
      7: neznamy ovladac (driver) --
\stopmessages

\startmessages  dutch  library: interactions
     21: -- code tussengevoegd
\stopmessages

\startmessages  english  library: interactions
     21: -- code inserted
\stopmessages

\startmessages  german  library: interactions
     21: -- Code eingefuegt
\stopmessages

\startmessages  czech  library: interactions
     21: -- kod vlozen
\stopmessages

%D \TEX\ produces files in the \DVI\ format. This format is
%D well defined and stable. In this format one||byte commands
%D are used which can optionally be followed by length
%D specifiers and arguments. The \DVI||format incorporates a
%D channel to the outside world. This channel is activated by
%D the \TEX\ primitive \type {\special}. The sequence 
%D 
%D \starttypen
%D \special{Hello here I am.}
%D \stoptypen
%D
%D results in \DVI||codes:
%D
%D \starttypen
%D xxx1 16 Hello here I am.
%D \stoptypen
%D
%D The \type {xxx1} is represented in byte code 239 and the
%D number of following bytes in a~1, 2, 3 or~4 byte number. So
%D here we get $1+1+16$ bytes of code.
%D 
%D Translating these codes is upto the \DVI\ driver. It's
%D common use to ignore specials that cannot be interpreted, so
%D the example string should have no consequences for the
%D output. 

%D \macros 
%D   {everyresetspecials}
%D
%D Now what will this one do? We'll see in a few lines. 

\newevery \everyresetspecials \relax

%D \macros
%D   {jobsuffix}
%D
%D By default, \TEX\ produces \DVI\ files which can be 
%D converted to other filetypes. Sometimes it is handy to 
%D know what the target file will be. In other driver 
%D modules we wil set \type {\jobsuffix} to \type {pdf}.  

\def\jobsuffix{dvi}

\appendtoks \def\jobsuffix{dvi} \to \everyresetspecials

%D A rather fundamental difference between special and direct
%D settings is that the latter don't interfere with typesetting
%D but must be set before the first shipout, while the specials
%D must be packaged in the shipped out box in such a way that
%D they don't interfere. 

\newif\ifspecialbasedsettings \specialbasedsettingstrue

\appendtoks \specialbasedsettingstrue \to \everyresetspecials

%D Because there is no standardization in the use of specials,
%D more than one driver or program can be supported. The
%D specials are grouped in libraries. Some of these are
%D general, such as the \type{postscript} library, some are
%D tuned to a special kind of program, like the \type{pdf}
%D ones, and some support a specific driver, as we can see in
%D the \type{yandy} library. A library is build with the
%D commands:
%D
%D \starttypen
%D \startspecials[name][inheritance]
%D
%D \definespecial\none{...}
%D \definespecial\onlyone#1{...}
%D \definespecial\alot#1#2#3#4{...}
%D
%D \stopspecials
%D \stoptypen
%D
%D Because drivers can have overlap in low level macros, a 
%D mechanism of inheritance is implemented. The libraries 
%D defined as second argument are loaded first. 
%D
%D Every special has to be predefined first. We  do this with
%D the command:
%D
%D \starttypen
%D \installspecial [\none]    [and] [0]
%D \installspecial [\onlyone] [and] [1]
%D \installspecial [\alot]    [or]  [4]
%D \stoptypen
%D
%D This means as much as: there is a special names
%D \type{\none} which has no arguments and has more than one
%D appearance. The special \type{\alot} on the other hand has
%D four arguments and is only defined once. Every instance in
%D the libraries of a special of category \type{and} is
%D executed when called upon, but only one special of
%D category \type{or} can be active. Most of the
%D \type{postscript}||specials are of category \type{or},
%D because they tend to interfere with driver specific ones.
%D The interactive specials of \type{dviwindo} and \type{pdf}
%D are an example of specials that can be called both.
%D
%D A library is defined in a file with the name
%D \type{spec-...}. We load a library with the command:
%D
%D \starttypen
%D \usespecials [list]
%D \stoptypen
%D
%D where the list can contain one or more file tags, the
%D \type{...} in the filename. The keyword \type{reset}
%D resets all loaded specials. This is equivalent to
%D \type{\resetspecials}.

%D Although a mechanism of nesting can be implemented, we
%D prefer to use a inheritance mechanism as mentioned. Calls
%D upon \type{\usespecials} within a \type{\startspecials}
%D would lead to confusion and errors.

\newif\ifinheritspecials

%D We define some local constants and variables. They look a
%D bit horrible but we don't want conflicts.

\def\@@specfil@@{@@specfil@@}
\def\@@speclst@@{@@speclst@@}
\def\@@speccat@@{@@speccat@@}
\def\@@specarg@@{@@specarg@@}
\def\@@specexc@@{@@specexc@@}

\let\currentspecial    =\empty
\let\currentspecialfile=\empty
\let\preloadedspecials =\empty

%D \macros
%D   {preloadspecials}
%D
%D The following command can be used to show the loaded list
%D of specials.

\def\preloadspecials%
  {\doifsomething{\preloadedspecials}
     {\showmessage{\m!specials}{1}{\preloadedspecials}}}

%D \macros
%D   {startspecials}
%D
%D Every library has a unique name, which is given as the first
%D argument to \type{\startspecials}. When another library is
%D defined with the same name, previous specials can be
%D overruled. The name may differ from the file||tag.
%D
%D The optional second argument can consist of a list of
%D libraries that are to be loaded first. 

% to fuzzy and error prone 
%
% \def\dostartspecials[#1][#2]%
%   {\let\mainspecialfile=\currentspecialfile
%    \doifelsenothing{#2}
%      {\inheritspecialsfalse}
%      {\ifinheritspecials
%         \showmessage{\m!specials}{2}{(#2)}%
%       \else
%         \inheritspecialstrue
%         \processcommalist[#2]\dousespecials
%         \inheritspecialsfalse
%       \fi}%
%    \doifelsenothing{#1}
%      {\let\currentspecial\s!unknown}
%      {\def\currentspecial{#1}}%
%    \let\currentspecialfile=\mainspecialfile
%    \setevalue{\@@specfil@@\currentspecial}{\currentspecialfile}%
%    \unprotect
%    \addtocommalist{\currentspecial}\preloadedspecials}
% 
% \def\startspecials%
%   {\dodoubleempty\dostartspecials}
% 
% \def\stopspecials%
%   {\def\currentspecial{}%
%    \protect}

\def\dostartspecials[#1][#2]%
  {\doifsomething{#2}
     {\processcommalist[#2]\dousespecials}%
   \doifelsenothing{#1}
     {\let\currentspecial\s!unknown}
     {\def\currentspecial{#1}}%
   \unprotect
   \addtocommalist\currentspecial\preloadedspecials}

\def\startspecials%
  {\pushmacro\currentspecial
   \dodoubleempty\dostartspecials}

\def\stopspecials%
  {\popmacro\currentspecial
   \protect}
 
%D \macros
%D   {installspecial,
%D    resetspecials}
%D
%D We have to install specials before we can define and use
%D them. The command itself is defined as a call to another
%D command that executes one or more user||defined specials,
%D depending of it's category: \type{or} versus \type{and}.
%D
%D The command \type{\installspecial} takes three
%D (non||optional) arguments: the name of the command, the
%D category it belongs to and the number of arguments it
%D takes.
%D
%D With \type{\resetspecials} we can unload the predefined
%D specials. Special reset actions |<|look in \type{spec-mis}
%D for an example|>| can be assigned to the token register 
%D \type{\everyresetspecials}.

\let\@@allspecials=\empty

\def\doinstallspecial[#1][#2][#3]%
  {\setvalue{\@@speclst@@\string#1}{}%
   \setvalue{\@@speccat@@\string#1}{#2}%
   \setvalue{\@@specarg@@\string#1}{#3}%
   \addtocommalist{\string#1}\@@allspecials
   \def#1{\executespecial#1}}

\def\installspecial%
  {\dotripleargument\doinstallspecial}

\def\resetspecials%
  {\the\everyresetspecials
   \def\docommando##1%
     {\letvalue{\@@speclst@@##1}\empty}%
   \processcommacommand[\@@allspecials]\docommando
   \ifx\preloadedspecials\empty \else
     \showmessage{\m!specials}{3}{\preloadedspecials}%
     \let\preloadedspecials\empty
   \fi}

%D \macros
%D   {definespecial}
%D
%D The command \type{\definespecial} take the place of
%D \type{\def} in the definition of a special. Just to be
%D sure, we first check if the command is permitted, i.e.
%D installed. If not, we give a warning and gobble the
%D illegal command in an quite elegant way.
%D
%D If the command can be combined (\type{and}) with others,
%D we append it to a list, otherwise (\type{or}) it becomes
%D the only item in the list.

\def\definespecial#1%
  {\ifx#1\undefined
     \showmessage{\m!specials}{4}{\string#1}%
     \def\next%
       {\def\@@illegalspecial@@}%
   \else
     \def\next%
       {\doifelse{\getvalue{\@@speccat@@\string#1}}{or}
          {\edef\@@newspeclst@@{\currentspecial}}
          {\edef\@@newspeclst@@{\getvalue{\@@speclst@@\string#1}}%
           \addtocommalist{\currentspecial}\@@newspeclst@@}%
        \setevalue{\@@speclst@@\string#1}{\@@newspeclst@@}%
        \setvalue{\currentspecial\string#1}}%
   \fi
   \next}

%D \macros
%D   {usespecials}
%D
%D We use \type{\usespecials} to load a specific library.
%D This command is only permitted outside de definition part.

\def\dousespecials#1%
  {\doifelse{#1}{\v!reset}
     {\resetspecials}
     {\doifdefinedelse{\@@specfil@@#1}
        {\edef\currentspecialfile{\getvalue{\@@specfil@@#1}}}
        {\edef\currentspecialfile{#1}}%
      \makeshortfilename[\f!specialprefix\currentspecialfile]%
      \showmessage{\m!specials}{5}{\currentspecialfile}%
      \startreadingfile
      \readsysfile{\shortfilename}{}{}%
      \stopreadingfile
      \showmessage{\m!specials}{1}{\preloadedspecials}}}

\def\usespecials[#1]%
  {\doifelsenothing{\currentspecial}
     {\processcommalist[#1]\dousespecials}
     {\showmessage{\m!specials}{6}{}}}

%D \macros
%D   {executespecials}
%D
%D The command \type{\executespecials} is used to execute the
%D defined specials. Once a special is installed, the special
%D itself calls for this command, so it's not needed outside
%D this module. One can use it if wanted.
%D 
%D A former implementation grouped the execution. Recent 
%D additions however |<|like the specials that implement object 
%D handling|>| asked for non||grouped execution. 

\def\executespecials#1#2%
  {\def\doonespecial##1%
     {\getvalue{##1\string#1}#2\relax}%
   \processcommacommand
     [\getvalue{\@@speclst@@\string#1}]\doonespecial}

\def\executespecial#1%
  {\expandafter\ifcase\getvalue{\@@specarg@@\string#1}\relax
     \def\next%
       {\executespecials#1{}}%
   \or
     \def\next##1%
       {\executespecials#1{{##1}}}%
   \or
     \def\next##1##2%
       {\executespecials#1{{##1}{##2}}}%
   \or
     \def\next##1##2##3%
       {\executespecials#1{{##1}{##2}{##3}}}%
   \or
     \def\next##1##2##3##4%
       {\executespecials#1{{##1}{##2}{##3}{##4}}}%
   \or
     \def\next##1##2##3##4##5%
       {\executespecials#1{{##1}{##2}{##3}{##4}{##5}}}%
   \or
     \def\next##1##2##3##4##5##6%
       {\executespecials#1{{##1}{##2}{##3}{##4}{##5}{##6}}}%
   \or
     \def\next##1##2##3##4##5##6##7%
       {\executespecials#1{{##1}{##2}{##3}{##4}{##5}{##6}{##7}}}%
   \or
     \def\next##1##2##3##4##5##6##7##8%
       {\executespecials#1{{##1}{##2}{##3}{##4}{##5}{##6}{##7}{##8}}}%
   \or
     \def\next##1##2##3##4##5##6##7##8##9%
       {\executespecials#1{{##1}{##2}{##3}{##4}{##5}{##6}{##7}{##8}{##9}}}% 
   \else
     \def\next%
       {\message{illegal special: \string#1}}%
   \fi
   \next}

%D The \type{{{...}}} are needed because we pass all those 
%D arguments to the specials support macro. 

\let\openspecialfile  = \relax
\let\closespecialfile = \relax

%D \macros
%D   {doifspecialavailableelse}
%D 
%D For testing purposes (this was first needed when object 
%D support was implemented) we have: 
%D 
%D \starttypen
%D \doifspecialavailableelse\specialcommand{true}{false}
%D \stoptypen
%D 
%D e.g: 
%D 
%D \starttypen
%D \doifspecialavailableelse\doinsertobject{...}{...}
%D \stoptypen

\def\doifspecialavailableelse#1#2#3%
  {\doifelsevaluenothing{\@@speclst@@\string#1}{#3}{#2}}

% %D This is some new, experimental code, used for testing some 
% %D proposals of Laurent Siebenmann on behalf of the 
% %D \kap{EMJ} discussionlist. 
% 
% \newif\ifexternalspecials  \externalspecialsfalse
% \newif\ifspecialstatus     \specialstatustrue
% 
% \newwrite\specialfile
% 
% \def\openspecialfile%
%   {\immediate\openout\specialfile=\jobname.etc\relax}
% 
% \def\closespecialfile%
%   {\immediate\closeout\specialfile}
% 
% \let\internalspecial=\special
% 
% \def\externalspecial#1%
%   {\internalspecial{}%
%    \immediate\write\specialfile{\currentspecialdriver\space: #1}}
% 
% \def\doinstallspecial[#1][#2][#3]%
%   {\setvalue{\@@specexc@@\string#1}{}%
%    \setvalue{\@@speclst@@\string#1}{}%
%    \setvalue{\@@speccat@@\string#1}{#2}%
%    \setvalue{\@@specarg@@\string#1}{#3}%
%    \addtocommalist{\string#1}\@@allspecials
%    \def#1{\executespecial#1}}
% 
% \def\resetspecials%
%   {\def\docommando##1%
%      {\setvalue{\@@specexc@@##1}{}%
%       \setvalue{\@@speclst@@##1}{}}%
%    \processcommacommand[\@@allspecials]\docommando
%    \showmessage{\m!specials}{3}{\preloadedspecials}}
% 
% \def\executespecials#1#2%
%   {\edef\supportedspecials{\getvalue{\@@speclst@@\string#1}}%
%    \def\doonespecial##1%
%      {\doifdefined{##1\string#1}
%         {\def\currentspecialdriver{##1}%
%          \getvalue{##1\string#1}#2\relax}}%
%    \ifexternalspecials
%      \let\special=\externalspecial
%      \doifelse{\supportedspecials}{}
%        {\ifspecialstatus
%           \immediate\write\specialfile{}%
%           \immediate\write\specialfile{skipping  : \string#1}
%           \immediate\write\specialfile{}%
%         \fi}
%        {\ifspecialstatus
%           \immediate\write\specialfile{}%
%           \immediate\write\specialfile{executing : \string#1}%
%           \immediate\write\specialfile{supported : \supportedspecials}%
%         \fi
%         \immediate\write\specialfile{}%
%         \processcommacommand[\supportedspecials]\doonespecial}%
%    \else
%      \let\special=\internalspecial
%      \doifelse{\getvalue{\@@speccat@@\string#1}}{or}
%        {\doonespecial{\getvalue{\@@specexc@@\string#1}}}
%        {\processcommacommand[\supportedspecials]\doonespecial}%
%    \fi}
% 
% \def\definespecial#1%
%   {\ifx#1\undefined
%      \showmessage{\m!specials}{4}{\string#1}%
%      \def\next%
%        {\def\@@illegalspecial@@}%
%    \else
%      \def\next%
%        {\edef\@@newspeclst@@{\getvalue{\@@speclst@@\string#1}}%
%         \addtocommalist{\currentspecial}\@@newspeclst@@
%         \setevalue{\@@speclst@@\string#1}{\@@newspeclst@@}%
%         \setevalue{\@@specexc@@\string#1}{\currentspecial}%
%         \setvalue{\currentspecial\string#1}}%
%    \fi
%    \next}
% 
% %D So far for the experiment. 

%D The following libraries are defined. Two postscript
%D drivers are supported, as well as two mechanisms for
%D interactive texts.
%D
%D \startregelcorrectie
%D \starttabel[|l|l|l|l|l|]
%D \HL
%D \NC \bf file             \NC
%D     \bf name             \NC
%D     \bf calls            \NC
%D     \bf support          \NC
%D     \bf program / driver \NC\SR
%D \HL
%D \NC \tttf spec-tex       \NC
%D     \tttf tex            \NC
%D                          \NC
%D     Generic \TEX\ (\DVI) \NC
%D     (default)            \NC\FR
%D \NC \tttf spec-tpd       \NC
%D     \tttf \PDF           \NC
%D                          \NC
%D     Han The Thanh        \NC
%D     (pdftex)             \NC\MR
%D \NC \tttf spec-ps        \NC
%D     \tttf postscript     \NC
%D                          \NC
%D     Adobe PostScript     \NC
%D     (default)            \NC\MR
%D \NC \tttf spec-tr        \NC
%D     \tttf rokicki        \NC
%D     \tttf postscript     \NC
%D     Thomas Rokicki       \NC
%D     (dvips)              \NC\MR
%D \NC \tttf spec-yy        \NC
%D     \tttf yandy          \NC
%D     \tttf postscript     \NC
%D     YandY                \NC
%D     (dvipsone, dviwindo) \NC\MR
%D \NC \tttf spec-pdf       \NC
%D     \tttf pdf            \NC
%D                          \NC
%D     Adobe PDF V2.1       \NC
%D     (Acrobat)            \NC\MR
%D \NC \tttf spec-win       \NC
%D     \tttf dviwindo       \NC
%D     YandY                \NC
%D     (dviwindo)           \NC\MR
%D \NC \tttf spec-1p0       \NC
%D     \tttf pdf            \NC
%D                          \NC
%D     Adobe PDF V 1.0      \NC
%D     (Acrobat)            \NC\MR
%D \NC \tttf spec-2p0       \NC
%D     \tttf pdf            \NC
%D                          \NC
%D     Adobe PDF V 2.0      \NC
%D     (Acrobat)            \NC\MR
%D \NC \tttf spec-htm       \NC
%D     \tttf html           \NC
%D                          \NC
%D     HTML V 2.0           \NC
%D     (dvips)              \NC\LR
%D \HL
%D \stoptabel
%D \stopregelcorrectie

%D \macros
%D   {dostartgraymode,dostopgraymode,
%D    dostartrgbcolormode,dostartcmykcolormode,dostartgraycolormode,dostopcolormode}
%D
%D Switching to and from color can be done in two ways:
%D
%D \startopsomming[opelkaar,n]
%D \som  insert driver specific commands
%D \som  pass instructions to the output device
%D \stopopsomming
%D
%D The first approach is more general and lays the
%D responsibility at the driver side. Probably due to the fact
%D that \TEX\ does not directly support color, we have been
%D confronted for the last few years with changing special
%D definitions. The need for support depends on how a macro
%D package handles colored text that crosses the page boundary.
%D Again, there are two approaches.
%D
%D \startopsomming[opelkaar,n]
%D \som  let \TEX\ do the job
%D \som  let the driver handle things
%D \stopopsomming
%D
%D The first approach is as driver independant as possible and
%D can easily be accomplished by using \TEX's mark mechanism.
%D In \CONTEXT\ we follow this approach. More and more, drivers
%D are starting to support color, including stacking them.
%D 
%D Colors as well as grayscales can be represented in scales
%D from~0 to~1. When drivers use values in the range 0..255,
%D this value has to be adapted in the translation process.
%D Technically it's possible to get a grayscale from combining
%D colors. In the \kap{RGB} color system, a color with Red,
%D Green and Blue components of 0.80 show the same gray as a
%D Gray Scale specified 0.80. The \kap{CMYK} color system
%D supports a Black component apart from Cyan, Magenta and
%D Yellow. 
%D 
%D Depending on the target format, color support differs from
%D gray support. PostScript for example offers different
%D operators for setting gray and color. This is because
%D printing something using three colors is someting else than
%D printing with just black.
%D
%D In \CONTEXT\ we have implemented a color subsystem that
%D supports the use of well defined colors that, when printed
%D in black and white, still can be distinguished. This
%D approach enables us to serve both printed and electronic
%D versions, using colored text and illustrations. More on the
%D fundamentals of this topic can be found in the \kap{MAPS} of
%D the Dutch User Group, 14 (95.1).
%D
%D To satisfy all those needs, we define four specials which
%D supply enough information for drivers to act upon. We
%D could have used more general commands with the keywords
%D 'rgb' and 'gray', but because these specials are used often,
%D we prefer the more direct and shorter alternative.
%D
%D We start with the installation of color and grayscale
%D specials. The values are in the range 0..1 (e.g. 0.25).
%D
%D \starttypen
%D \dostartgraymode      {gray} ... \dostopgraymode
%D \dostartrgbcolormode  {red} {green} {blue} ... \dostopcolormode
%D \dostartcmykcolormode {cyan} {magenta} {yellow} {black} ... \dostopcolormode
%D \dostartgraycolormode {gray} ... \dostopcolormode
%D \stoptypen
%D
%D Because we can expect conflicts between drivers, we
%D implement them as category \type{or}. In previous versions
%D of \DVIPSONE\ the use of their color||specials did not
%D interfere with the PostScript ones, but recent versions do.

\installspecial [\dostartgraymode]      [or] [1]
\installspecial [\dostopgraymode]       [or] [0]

\installspecial [\dostartrgbcolormode]  [or] [3]
\installspecial [\dostartcmykcolormode] [or] [4]
\installspecial [\dostartgraycolormode] [or] [1]
\installspecial [\dostopcolormode]      [or] [0]

%D For some drivers, the stop special is of no use and can
%D simply call the start one with zero arguments.

%D \macros
%D   {doinsertfile}
%D
%D Probably the most problematic special is the following
%D one. Because we want to be able to support different
%D schemes, we pass a lot of data to it.
%D 
%D The support of inserting files (like illustrations) comes in
%D many flavors. Some drivers use scales, some take dimensions.
%D Some need offsets and others act on stored characteristics.
%D They need one thing in common: a filename. Although separate
%D specials for different formats sometimes are more clear, we
%D decided to combine them all in one: 
%D 
%D \starttypen
%D \doinsertfile {type,method} {file,label} 
%D               {xscale} {yscale} {x} {y} {w} {h} 
%D               {options}
%D \stoptypen
%D
%D The scale is given percents, the other values are base 
%D points.
%D 
%D The special is implemented as \type{or}. Because \DVIPSONE\
%D understands them all, a chain of alternatives would generate
%D multiple occurrences of the same illustration. 
%D 
%D When option 1 is passed, the viewers is asked to present a
%D preview, like the first frame of a movie. 

\installspecial [\doinsertfile] [or] [9]

%D No start||stop construction is needed here, because there in
%D no further interference of \TEX. All dimensions are output
%D as scaled points and scales as a number, where 100 equal
%D 100\%. 

%D \macros
%D   {doinsertsoundtrack}
%D
%D Sounds are (for the moment) just files with 
%D associated options. 
%D
%D \starttypen
%D \doinsertsoundtrack {file} {label} {options} 
%D \stoptypen

\installspecial [\doinsertsoundtrack] [or] [3]

%D \macros
%D   {dogetnofinsertpages}
%D
%D Some file formats support more than one page, like \PDF, 
%D and for special applications, one may want to have access 
%D to the total number of pages. 
%D
%D \starttyping
%D \dogetnofinsertpages{filename}
%D \stoptyping
%D
%D The number is also available after the insert is placed, 
%D since inclusion may take place immediate when an insert is 
%D called upon. 

\def\nofinsertpages{1} % one of the few 'talk backs' 

\installspecial [\dogetnofinsertpages] [or] [1] 

%D \macros
%D   {dostartrotation,
%D    dostoprotation}
%D
%D We support rotation with the special:
%D
%D \starttypen
%D \dostartrotation {angle} ... \dostoprotation
%D \stoptypen
%D
%D For the moment these specials are installed as
%D category \type{or}.

\installspecial [\dostartrotation] [or] [1]
\installspecial [\dostoprotation]  [or] [0]

%D \macros
%D   {dostartscaling,
%D    dostopscaling}
%D
%D Scaling is also supported:
%D
%D \starttypen
%D \dostartscaling {x} {y} ... \dostopscaling
%D \stoptypen
%D
%D Like the previous one, these specials are of category 
%D \type{or}.

\installspecial [\dostartscaling] [or] [2]
\installspecial [\dostopscaling]  [or] [0]

%D \macros
%D   {dostartmirroring,
%D    dostopmirroring}
%D
%D And indeed, mirroring is there too:
%D
%D \starttypen
%D \dostartmirroring {x} {y} ... \dostopmirroring
%D \stoptypen
%D
%D Again these specials are installed as category \type{or}.

\installspecial [\dostartmirroring] [or] [0]
\installspecial [\dostopmirroring]  [or] [0]

%D \macros
%D   {dostartnegative,
%D    dostopnegative}
%D
%D When producing output for an image setter, negating the 
%D page comes into view. Here are the tools:

\installspecial [\dostartnegative] [or] [0]
\installspecial [\dostopnegative]  [or] [0]

%D \macros
%D   {doselectfirstpaperbin,
%D    doselectsecondpaperbin}
%D
%D Here are some very printer||specific ones. No further
%D comment.

\installspecial [\doselectfirstpaperbin]  [or]  [0]
\installspecial [\doselectsecondpaperbin] [or]  [0]

%D \macros
%D   {doovalbox}
%D
%D When we look at the implementation, this is a complicated
%D one. There are seven arguments.
%D
%D \starttypen
%D \doovalbox {w} {h} {d} {linewidth} {radius} {stroke} {fill}
%D \stoptypen
%D
%D This command has to return a \type{\vbox} which can be used
%D to lay over another one (with text). The radius is in
%D degrees, the stroke and fill are~\type{1} (true) of~\type{0}
%D (false). 

\installspecial [\doovalbox] [or] [7]

%D \macros 
%D   {dostartclipping,dostopclipping}
%D 
%D Clipping is implemented in such a way that an arbitrary 
%D can be fed. 
%D 
%D \starttypen 
%D \dostartclipping {pathname}{width} {height} 
%D \dostopclipping 
%D \stoptyping
%D
%D 

\installspecial [\dostartclipping] [or] [3]
\installspecial [\dostopclipping]  [or] [0]

%D \macros
%D   {dosetupidentity}
%D
%D We can declare some characteristics of the document with
%D
%D \starttypen 
%D \dosetupidentity {title} {subject} {author} {creator} {date} 
%D \stoptypen
%D
%D All data is in string format. 

\installspecial [\dosetupidentity] [and] [5]

%D \macros
%D   {dosetuppaper}
%D
%D This special can be used to tell the driver what page size
%D to use. The special takes three arguments. 
%D
%D \starttypen
%D \dosetuppaper {type} {width} {height}
%D \stoptypen
%D
%D The type is one of the common identifiers, like A4, A5 or 
%D B2. 

\installspecial [\dosetuppaper] [and] [3]

%D \macros
%D   {dosetupprinter}
%D
%D Some drivers enable the user to specify the paper type 
%D used and/or page dimensions to be taken into account. 
%D
%D \starttypen
%D \dosetupprinter {type} {hoffset} {voffset} {width} {height}
%D \stoptypen
%D
%D The first argument is one of \type{letter}, \type{legal}, 
%D \type{A4}, \type{A5} etc. The dimensions are in 
%D basepoints. 

\installspecial [\dosetupprinter] [and] [5]

%D \macros
%D   {% dosetuppage,
%D    dosetupopenaction, dosetupclosaction,
%D    dosetupopenpageaction, dosetupclospageaction,
%D    dosetupinteraction,
%D    dosetupscreen,
%D    dosetupviewmode}
%D
%D Here come some obscure interactive commands. Probably the
%D specs will change with the development of the macros that
%D use them.
%D
%D The first ones can be used to set up the interaction.
%D
%D \starttypen
%D \dosetupinteraction
%D \stoptypen
%D
%D Normally this command does nothing but giving a message
%D that some scheme is supported. 
%D
%D \starttypen
%D \dosetupstartaction
%D \dosetupstopaction
%D \stoptypen
%D
%D These two setup the actions to be executed when the document
%D is opened and closed. 
%D
%D The next command sets up the screen. It takes five 
%D arguments:
%D
%D \starttypen
%D \dosetupscreen {hoffset} {voffset} {width} {height} {options}
%D \stoptypen
%D
%D The first four arguments are in scaled points. Option~1 
%D results in a full screen launch.
%D
%D \starttypen
%D \dosetuppageview {keyword}
%D \stoptypen
%D
%D For the moment we only support \type{fit}. 

\installspecial [\dosetupinteraction]     [and] [0]
\installspecial [\dosetupopenaction]      [and] [0]
\installspecial [\dosetupcloseaction]     [and] [0]
\installspecial [\dosetupopenpageaction]  [and] [0]
\installspecial [\dosetupclosepageaction] [and] [0]
\installspecial [\dosetupscreen]          [and] [5]
\installspecial [\dosetuppageview]        [and] [1]

%D \macros
%D   {dostarthide,
%D    dostophide}
%D
%D Not every part of the screen is suitable for paper. Menus
%D for instance have no meaning on an non||interactive medium.
%D These elements are hidden by means of:
%D
%D \starttypen
%D \dostarthide
%D \dostophide
%D \stoptypen

\installspecial [\dostarthide] [or] [0]
\installspecial [\dostophide]  [or] [0]

%D \macros
%D   {dostartgotolocation, dostopgotolocation,
%D    dostartgotorealpage, dostopgotorealpage}
%D
%D When we want to support hypertext buttons, again we have 
%D to deal with two concepts.
%D
%D \startopsomming[opelkaar,n]
%D \som let \TEX\ highlight the text
%D \som let the driver show us where to click
%D \stopopsomming
%D 
%D The first approach is the most secure one. It gives us
%D complete control over the visual appearance of hyper
%D buttons. The second alternative lets the driver guess what
%D part of the text needs highlighting. As long as we deal with
%D not too complicated textual buttons, this is no problem.
%D It's even a bit more efficient when we take long mid
%D paragraph active regions into account. When we let \TEX\
%D handle active sentences {\em for instance marked like this
%D one}, we have to take care of line- and pagebreaks ourselve.
%D However, it's no trivial matter to let a driver find out
%D where things begin and end. Because most hyperlinks can be
%D found in tables of contents and registers, the saving in
%D terms of bytes can be neglected and the first approach is a 
%D clear winner. 
%D 
%D The most convenient way of cross||referencing is using named
%D destinations. A more simple scheme is using page numbers as
%D destinations. Because the latter alternative can often be
%D implemented more efficient, and because we cannot be sure
%D what scheme a driver supports, we always have to supply a
%D pagenumber, even when we use named destinations.
%D
%D To enable a driver to find out what to make active, we have
%D to provide begin and endpoints, so like with color, we use
%D pairs of specials. The first scheme can be satisfied with
%D proper dimensions of the areas to be made active.
%D
%D The interactive real work is done by the following four
%D specials. The reason for providing the first one with both
%D a label and a number, is a result of the quite poor
%D implementation of \type{pdfmarks} in version 1.0 of
%D Acrobat. Because only pagenumbers were supported as
%D destination, we had to provide both labels (\DVIWINDO) and
%D pagenumbers (\PDF). Some drivers use start stop pairs. 
%D
%D \starttypen
%D \dostartgotolocation {w} {h} {url} {file} {label} {page}
%D \dostartgotorealpage {w} {h} {url} {file}         {page}
%D \stoptypen
%D
%D Their counterparts are:
%D
%D \starttypen
%D \dostopgotolocation  
%D \dostopgotorealpage  
%D \stoptypen
%D
%D The internal alternative is used for system||generated
%D links, the external one for user||generated links. The 
%D Uniform Resource Locator can be used to let the reader 
%D surf the net. 

\installspecial [\dostartgotolocation] [and] [6]
\installspecial [\dostopgotolocation]  [and] [0]
\installspecial [\dostartgotorealpage] [and] [5]
\installspecial [\dostopgotorealpage]  [and] [0]

%D One may wonder why jumps to page and location are not
%D combined. By splitting them, we enable macro||packages to
%D force the prefered alternative, while on the other hand
%D drivers can pick up the alternative desired most.

%D \macros
%D  {dostartgotoJS, doflushJSpreamble}
%D   
%D Rather special is the option to include and execute 
%D JavaScript code. This is a typical \PDF\ option.
%D
%D \starttypen
%D \dostartgotoJS {w} {h} {script}
%D \stoptypen
%D
%D This not so standard \TEX\ feature should be used with 
%D care. Preamble scripts are flushed by
%D
%D \doflushJSpreamble {script}

\installspecial [\dostartgotoJS]    [and] [3]
\installspecial [\dostopgotoJS]     [and] [0]
\installspecial [\doflushJSpreamble][and] [1]

%D \macros
%D   {dostartthisislocation, dostopthisislocation,
%D    dostartthisisrealpage, dostopthisisrealpage}
%D
%D Before we can goto some location or page, we have to tell
%D the system where it can be found. Because some drivers
%D follow the \SGML\ approach of begin||end tags, we have to
%D support pairs. A possible extension to this scheme is
%D supplying coordinates for viewing the text.
%D
%D The opposite commands of \type{\dogotosomething} have only
%D one argument:
%D
%D \starttypen
%D \dostartthisislocation {label}
%D \dostartthisisrealpage {page}
%D \stoptypen
%D
%D These commands are accompanied by: 
%D
%D \starttypen
%D \dostopthisislocation  
%D \dostopthisisrealpage 
%D \stoptypen
%D
%D As with all interactive commands's they are installed as
%D \type{and} category specials.

\installspecial [\dostartthisislocation] [and] [1]
\installspecial [\dostopthisislocation]  [and] [0]
\installspecial [\dostartthisisrealpage] [and] [1]
\installspecial [\dostopthisisrealpage]  [and] [0]

%D In \CONTEXT\ we don't use the \type{\stopsomething} 
%D macros because we let \TEX\ take care of typographic 
%D issues.  

%D \macros
%D   {doresetgotowhereever}
%D 
%D These and others need:

\installspecial [\doresetgotowhereever] [and] [0]

%D \macros
%D   {dostartexecutecommand, dostopexecutecommand}
%D
%D The actual behavior of the next pair of commands depends 
%D much on the viewing engine. Therefore one cannot depend 
%D too much on their support. 
%D
%D \starttypen
%D \dostartexecutecommand {w} {h} {command} {options} 
%D \stoptypen
%D
%D At least the next commands are supported (more examples 
%D can be found in \type {spec-fdf.tex}: 
%D
%D \startregelcorrectie\steluitlijnenin[midden]\leavevmode
%D \starttabel[|l|l|] 
%D \HL
%D \NC \bf command  \NC \bf action                  \NC\SR 
%D \HL
%D \NC first        \NC go to the first page        \NC\FR
%D \NC previous     \NC go to the previous page     \NC\MR
%D \NC next         \NC go to the next page         \NC\MR
%D \NC last         \NC go to the last page         \NC\MR
%D \NC backward     \NC go back to the  link list   \NC\MR
%D \NC forward      \NC go forward in the link list \NC\MR
%D \NC print        \NC enter print mode            \NC\MR
%D \NC exit         \NC exit viewer                 \NC\MR
%D \NC close        \NC close document              \NC\MR
%D \NC enter        \NC enter viewer                \NC\MR
%D \NC help         \NC show help on the viewer     \NC\LR
%D \HL
%D \stoptabel
%D \stopregelcorrectie
%D
%D Options are to be passed as a comma separated list of 
%D assignments.

\installspecial [\dostartexecutecommand] [and] [4]
\installspecial [\dostopexecutecommand]  [and] [0]

%D \macros
%D   {dostartobject, 
%D    dostopobject,
%D    doinsertobject}
%D
%D Reuse of object can reduce the output filesize 
%D considerably. Reusable objects are implemented with: 
%D
%D \starttypen
%D \dostartobject{class}{name}{width}{height}{depth}
%D some typeset material
%D \dostopobject
%D \stoptypen
%D
%D \starttypen
%D \doinsertobject{class}{name}
%D \stoptypen
%D
%D The savings can be huge in interactive texts. 

\installspecial [\dostartobject]  [or] [5]
\installspecial [\dostopobject]   [or] [0]
\installspecial [\doinsertobject] [or] [2]

%D \macros
%D   {doregisterfigure}
%D 
%D Images can be objects as well and it's up to the driver to
%D handle this. Alternative images are also up to the driver,
%D and the next macro tells the driver that the previous image
%D is somehow followed by another and that both have to be
%D handled together. This is a rather fuzzy model, but for the 
%D moment it suits its purpose: low res screen versions combined
%D with high res printable ones. 

\installspecial [\doregisterfigure][or] [2]

% %D \macros
% %D   {dogetobjectreference} 
% %D
% %D For very special purposes, one can ask for the internal 
% %D reference to the object. Beware!
% 
% \installspecial [\dogetobjectreference] [or] [3]
% 
% %D The first argument is the name, the second a macro that 
% %D gets the assiciated value.

%D \macros
%D   {dostartrunprogram, dostoprunprogram,
%D    dostartgotoprofile, dostopgotoprofile,
%D    dobeginofprofile,
%D    doendofprofile}
%D
%D These specials are still experimental. They are not yet
%D supported by the programs the way they should be.
%D
%D {\em --- still undocumented ---}

\installspecial [\dostartrunprogram]  [and] [3]
\installspecial [\dostoprunprogram]   [and] [0]
\installspecial [\dostartgotoprofile] [and] [3]
\installspecial [\dostopgotoprofile]  [and] [0]
\installspecial [\dobeginofprofile]   [and] [4]
\installspecial [\doendofprofile]     [and] [0]

%D \macros
%D   {doinsertbookmark}
%D 
%D Bookmarks, that is viewer generated tables of contents, are
%D a strange phenomena, mainly because \TEX\ can provide
%D whatever kind of table in much better quality. 

\installspecial [\doinsertbookmark] [and] [5]

%D This special is called as:
%D 
%D \starttypen
%D \doinstallbookmark {level} {nofsubentries} {text} {page} {open}
%D \stoptypen
%D
%D This definition is very \PDF\ oriented, so for more 
%D information we kindly refer to the \PDF\ manuals. 

%D \macros
%D   {dosetpagetransition}
%D
%D In presentations, fancy page transitions can, at least for a
%D short moment, let the audience focus at the screen. Like the
%D previous one, this special is very \PDF. 
%D
%D \starttypen
%D \dosetpagetransition{dissolve}{0}
%D \stoptypen
%D
%D Transitions have symbolic names, like dissolve, box, split,
%D blinds, wipe and glitter. The second argument determines 
%D the wait time (unless zero). 

\installspecial [\dosetpagetransition] [or] [2]

%D \macros
%D   {dopresettextfield,dopresetlinefield,
%D    dopresetchoicefield,dopresetpopupfield,dopresetcombofield,
%D    dopresetbuttonfield,dopresetcheckfield,
%D    dopresetradiofield,dopresetradiorecord}
%D
%D The special drivers are programmed independant from their
%D calling macros are thereby use the standard \TEX\ way of
%D passing parameters. Unfortunately fields often have more
%D than nine characteristics, so we pack some arguments in one. 
%D 
%D \starttypen
%D \dopresettextfield / \dopresetlinefield
%D   {name} {width} {height} {default} {length} 
%D   {style,color} {options} {alignment} {actions}
%D 
%D \dopresetchoicefield / \dopresetpopupfield / \dopresetcombofield
%D   {name} {width} {height} {default} 
%D   {style,color} {options} {values} {actions}
%D 
%D \dopresetpushfield 
%D   {name} {width} {height} {default}
%D   {options} {values} {actions}
%D 
%D \dopresetcheckfield 
%D   {name} {width} {height} {default} 
%D   {options} {values} {actions}
%D 
%D \dopresetradiofield
%D   {name} {width} {height} 
%D   {options} {parent} {values} {actions}
%D 
%D \dopresetradiorecord
%D   {name} {top} {options} {kids} {actions}
%D \stoptypen

\installspecial [\dopresetlinefield]   [or] [9]
\installspecial [\dopresettextfield]   [or] [9]
\installspecial [\dopresetchoicefield] [or] [8]
\installspecial [\dopresetpopupfield]  [or] [8]
\installspecial [\dopresetcombofield]  [or] [8]
\installspecial [\dopresetpushfield]   [or] [7]
\installspecial [\dopresetcheckfield]  [or] [7]
\installspecial [\dopresetradiofield]  [or] [7]
\installspecial [\dopresetradiorecord] [or] [5]

%D \macros
%D   {dodefinefieldset,dogetfieldset,doiffieldset}
%D 
%D Field sets, used in resetting and submitting, are handled
%D by:

\installspecial [\dodefinefieldset] [or] [2]
\installspecial [\dogetfieldset]    [or] [1]
\installspecial [\doiffieldset]     [or] [2]

%D \macros 
%D   {dosetfieldstatus}
%D
%D For practical reasons we set some field characteristics 
%D using: 
%D
%D \starttypen
%D \dosetfieldstatus {mode} {parent} {kids} {root}
%D \stoptypen

\installspecial [\dosetfieldstatus] [or] [4]

%D with:

\def\fieldlonermode {0} % no \chardef here
\def\fieldparentmode{1} % no \chardef here
\def\fieldchildmode {2} % no \chardef here
\def\fieldcopymode  {3} % no \chardef here

%D \macros 
%D   {doregistercalculationset}
%D
%D We can define a calculation order list with:
%D
%D \starttypen
%D \doregistercalculationset {set identifier}
%D \stoptypen

\installspecial [\doregistercalculationset] [or] [1]

%D \macros 
%D   {doinsertcomment}
%D
%D Not so much out of need, but to be complete, we also 
%D implement text annotations, so called  comment:
%D 
%D \starttypen
%D \doinsertcomment
%D   {title} {width} {height} {color} {open} {symbol} {data} 
%D \stoptypen

\installspecial[\doinsertcomment] [and] [7]

%D \macros
%D   {dosetposition, dosetpositionwhd, dosetpositionpapersize}
%D
%D Not natural to \TEX, but available in \PDFTEX, and by 
%D means of postprocessed \DVI, we can save and call upon 
%D positions. 
%D
%D \starttypen
%D \dosetposition          {identifier}
%D \dosetpositionwhd       {identifier} {width} {height} {depth}
%D \dosetpositionpapersize {width} {height} 
%D \stoptypen
%D
%D This is one of the few specials where when using \PDFTEX\ 
%D the driver directly deals with the utility file. 

\installspecial [\dosetposition]          [or] [1] 
\installspecial [\dosetpositionwhd]       [or] [4] 
\installspecial [\dosetpositionpapersize] [or] [2] 

%D So far for the installation. For quite some time the 
%D \CONTEXT\ way of specifying the output format has been: 
%D
%D \starttypen
%D \usespecials[ps,yy,win,pdf]
%D \stoptypen
%D
%D Because at \PRAGMA\ we use \DVIPSONE, this was a suitable 
%D setting, but with \CONTEXT\ going public, the next sequence 
%D is more suitable for \DVIPS\ users: 
%D 
%D \starttypen
%D \usespecials[reset,ps,tr,pdf]
%D \stoptypen
%D
%D On the other hand, for \PDFTEX\ we needed: 
%D
%D \starttypen
%D \usespecials[tpd]
%D \stoptypen
%D
%D To simplify things, I decided to provide a higher level 
%D command. 
%D
%D \starttypen
%D \defineoutput[name][specials]
%D \setupoutput[name,...]
%D \stoptypen
%D
%D In a few lines, we will see some examples. 

\def\defineoutput%
  {\dodoubleargument\dodefineoutput}

\def\dodefineoutput[#1][#2]%
  {\setvalue{\??ui#1}{#2}} 

\def\dosetupoutput#1%
  {\doifdefinedelse{\??ui#1}
     {\processcommacommand[\getvalue{\??ui#1}]\dousespecials}
     {\doifdefinedelse{\@@specfil@@#1}
        {\dousespecials{#1}}
        {\showmessage{\m!specials}{7}{#1}}}}

\def\setupoutput[#1]%
  {\resetspecials\processcommacommand[#1]\dosetupoutput}

%D Some suitable definitions are: 

\defineoutput [dvipsone] [dvi,ps,yy]
\defineoutput [dviwindo] [dvi,ps,yy,win]
\defineoutput [dvips]    [dvi,ps,tr]
\defineoutput [dviview]  [dvi,ps,tr,dv]
\defineoutput [dvipdfm]  [dpm]
\defineoutput [pdftex]   [tpd]   
\defineoutput [pdf]      [tpd]   
\defineoutput [acrobat]  [pdf,ps,tr] % use: [acrobat,dvipsone]   

%D Please let me know if we need more. From now on we default
%D to:

\setupoutput [dvips]

%D We don't enable \ACROBAT, because pure \POSTSCRIPT\ is not
%D that strong on objects and \PDFTEX\ does a better job. 
%D Some reasonable alternatives are:
%D 
%D \starttypen
%D \setupoutput [dvipsone,acrobat]
%D \setupoutput [dviwindo,acrobat]
%D \stoptypen
%D 
%D Although, better is:
%D 
%D \starttypen
%D \setupoutput [pdftex]
%D \stoptypen

\protect

\endinput