\magnification=\magstep1
\input nice
\def\mynum#1{\ifnum #1<10 0\the#1\else \the#1\fi}
\def\mymonth#1{\ifcase#1 \or January \or February \or March \or April
   \or May \or June \or July \or August
   \or September \or October
   \or November \or December \fi}

\def \DVIprint {DVIprint}
\def \ShowDVI {ShowDVI}
\def \spec {SpecialHost}

\article
\contentslevel=3
\contfill={\dotfill}
\contskip=3pt
\let\scstyle=\bf

\titlepage
\vskip 1in
\title{\spec{}, a program to include}
\removelastskip
\smallskip
\title{IFF graphics in \TeX texts}
\removelastskip
\smallskip
\title{for the AMIGA}
\bigskip
\release{$\beta$-Version 0.71}
\smallskip
\release{of}
\release {\mynum{\day}. \mymonth{\month}\mynum{\year}}
\bigskip
\author{by}
\author{Georg He\ss{}mann}
\author{translation by}
\author{Thomas Tavoly}
\vfill
\abstract{
  \spec{} is a utility for the previewer \ShowDVI{} and the
  printerdriver \DVIprint{}. It is started in the background additionally
  to the drivers and waits for messages from these programs.
  It enables the printerdriver and the previewer to display IFF
  graphics. To this end it evaluates the \\special-strings. It loads
  pictures with the help of an IFF library and adjusts their size to
  the resolution of the current driver. It can also store the pictures
  in a manner that when called again the labour intensive enlargement
  or reduction do not have to be done again.
}
\vskip 1.2in
\endtitlepage

\medskip
\plainsection{Table of contents:}
\medskip
\makecontents
\newpage

\section{Copyright and similar}

The program \spec{} is ``freely distributable copyrighted software''.
That is, everyone is allowed to copy and use it, however the copyright
remains with me. The program can also only be redistributed in an
unaltered state.

The program can not be sold commercially without my explicit prior consent.
Distributed as PD software, the price must not exceed 5 DM (=3 DM) per
disk.

It can also only be redistributed in a complete and unaltered shape.

The sources may be altered, as long as this is stated clearly
and the copyright notice remains unaltered in the source.
When alterations have been made, I should be notified of these
as much as possible, so that they can be built into the
general version.

Note the copyright on the files `flext.c' and `specialparse.c'.

For further explanation see the README file.


\section{About \spec{}}
Anyone, who has worked a little with \TeX{}, knows its greatest
disadvantage: the missing possibility to produce graphs and include
them in texts.
There are hooks present though, to do this in \TeX{} (via La\TeX{} or
PIC\TeX{}) but these methods are doomed as soon as the graphs get
just a little bit complicated.

You can bypass these limitations only with a trick:
the use of the \\special-command.
Fortunately a possibility was envisioned in the DVI File Format,
to incorporate non-standardized things in the DVI file too.
For this, the  \\special command is available.
Everything that follows the command within accolades is taken
up in the DVI file without changes. This way driver dependant
commands can get past the \TeX{} program into the DVI file.
The particular driver can evaluate the \\special-string and
bind for example a graph into the current page.

The disadvantage of this method should not be kept secret though.
As sson as you start working with \\special-strings, the DVI file
is not portable anymore. That means, that you cannot transfer this
file to an arbitrary computer and expect, that the output there
will be exactly the same, as on your own system.
However, this limitation does not weigh that heavy altogether,
since in the worst case the \\special-strings are
just ignored and the text is printed without
graphics just the same anyway.

How does \spec work?
\parwithoutskip
\spec{} uses the possibility of multitasking and message transfer of
the AMIGA, to evaluate the \\special-strings in the most flexible
manner possible. \spec{} is started parallel to the particular
driver (\ShowDVI{} or \DVIprint) and waits for an incoming message
of the driver. Should the driver encounter a \\special-string when
evaluating a DVI file, then it passes this unchanged to the \spec-
program together with some further information like the resolution
of the picture at the time.

The task of the \spec{} program is to get the message of
the driver and to evaluate the \\special-string.
If the name of an IFF file is given
in the string, the program loads the
picture stipulated, and adjusts it to the
selected resolution (reduces or enlarges it).
After that, it passes the bitmap created on
to the driver. This only has to copy it into
its own bitmap, in which it keeps an entire \TeX page.

But why a private program for the evaluation of the \\special-string?
\parwithoutskip
This solution is in my view considerably more flexible,
as that of building a complete evaluation of the \\special-string
into every driver. Because a solidly defined interface between
the drivers and the \spec{}-program exists, the programs can be
developed indepently from eachother, without encountering
greater difficulties.

This way you can for example redefine the format of the \\special-string
or build new skills into the \spec{}-program like that of evaluating
of color- or vectorgraphics, without having to change even
a bit in the drivers. Or in case I change something in the
drivers and someone has written an own version of
the \spec{}-program, no trouble should arise,
when these programs cooperate.

I publish the entire source of the \spec{}-program, so that
the advantage can be of some importance. Perhaps somebody,
who knows his way around in graphic processing and is
interested can extend the program.

\section{Calling \spec{}}
At the present development stage \spec{} has not got
any option, which could be passed to it, when calling it.

The only particularity is maybe, that the program
runs itself in the background automatically. The CLI-prompt
appears immediately again after execution. The program
also ignores 'stdin' and 'stdout', 'stderr' is used
for outputting a message in case of a more important
error message. In such a situation the program ends itself.

\section{\spec{}'s window structure}
The window of \spec{} is divided into three parts.
The upper part serves for input. There are all the gadgets,
with which the program is directed.

The centre part only exists from a status line, in which
it is displayed, in what manner the program should pass the pictures.

The lower part is meant as a control window for the activities of
the program. There it is logged, what the program is doing at that
particular moment. It also remembers the lines that are scrolled out
at the top, when it displays a lot of messages. These can be retrieved
with the cursor keys.

\section{Operating \spec{}}
The program is managed completely by gadgets.
These are:
\staggered{\tt base DPI }

\key {\tt Memory} When you click on this gadget, you order the
 \spec{} program, to pass a pointer of the bitmap of the picture
 to be included to the printerdriver or previewer.

\key {\tt File} This gadget makes, that the driver is passed only
 one filename, in which the bitmap is stored in a special (simple)
 format. The file ends on the resolution of the driver in DPI.
 At that however, first it is tested whether this file
 is younger as the actual IFF file. Is the IFF file newer -- so
 it must have been changed -- or the bitmap file does not yet exist,
 then the bitmap is created in memory and the bitmap file is freshly
 created. As the picture is then already in memory anyway,
 the bitmap is now passed directly.

\key {\tt Mem-B} This gadget is related to the {\tt Memory} gadget.
 The only difference is, that the driver is additionally appointed
 to draw a border around the picture.

\key {\tt File-B} This gadget resembles the {\tt File} gadget,
 however, the driver draws a border around the picture.

\key {\tt Border} Here, the \spec{} program points the driver,
 to actually draw a border, which corresponds to the size of
 the picture. The size is evaluated by the \spec program, by
 reading the header of the IFF file.

\key {\tt Rect.} Has the same function as the {\tt Border} gadget.
 But now, not a border, but a filled rectangle
 is shown.

\key {\tt Base DPI} With this gadget you indicate, in which resolution
 the IFF pictures are drawn, which you include in the \TeX-text.
 The default value is 100dpi.
 This means, that a picture in the previewer, set to 100dpi,
 is shown unchanged. In case of a printer driver with 300dpi
 resolution however, the picture is enlarged by a factor 3.
 When the {\tt Base DPI} remains set to 100, it means, that
 100 pixels in the IFF picture are always one inch on the page
 -- all the same with which resolution this picture is displayed
 or printed out.

\key {\tt Icon} By clicking this gadget the window is transformed
 into a small icon. You can reopen this icon with a double click.
 The program continues its work uninterrupted as an icon as well.
\endstaggered

\section{The format of the $\backslash$special-string}

As the \TeX driver \ShowDVI{} and \DVIprint{} ask \spec{} for
the picture to be included, they must know after what they
should be asking. This is present in the \TeX text, the
command is the \\special-string. All of

\centerline{{\tt \\special\{}arbitrary text{\tt \}}}

of the \\special-command that is within the accolades, is
ignored by the \TeX program and passed to the driver unchanged.
If \ShowDVI{} or \DVIprint{} encounters such a string now, then
it is checked, whether a \spec{} program is running in the background.
Is this not the case, then the \\special-command is simply ignored.
If the \spec{} program is present, then it receives the complete
string per message.

Thus it is the \spec{} program, which evaluates the special-string and
determines the meaning of each and every word of the string.
As this special-string is not standardized in any way,
the format can change from driver to driver.

So the suggested format only matters for this collection
of drivers and has not yet been finalized here either.
In newer versions, new functions will probably be added.
However, downward compatibility is stressed,
so that you can switch to newer versions without difficulty.

The present format of the \\special-string:

\centerline{\tt \\special\{com1 com2 com3\}}

The particular commands within the braces
are separated from eachother by one or more
spaces.

A command itself consists of a keyword and a value,
so that a more precise study of the \\special-string shows the
following format:

\centerline{\tt \\special\{key1=val1 key2=val2 key3=val3\}}

Between the keyword (key) and the value (val) an equal sign must
always be present.

As keywords, the following exist up to now:
\staggered{\quad\tt ifffile }
\key{\quad\tt ifffile } defines the filename of an IFF-file,
\key{\quad\tt hoffset } indicates a horizontal offset,
\key{\quad\tt voffset } indicates a vertical offset,
\key{\quad\tt hsize } determines the horizontal size of the picture,
\key{\quad\tt vsize } determines the vertical size of the picture,
\endstaggered

At {\tt ifffile} an IFF-file is given as the value of the filename.
Plus, you should mind that the current directory is that one, from which
the \spec program has been started. Because of this, the filename
of an IFF-file should always contain the entire path. In the
present version it is unfortunately not yet possible, to change the
current directory from within the \spec{} program.

In case of the other four keywords, an indication of the dimension is
expected as the value. This consists of a real number plus a calculation
of the unit. The following units are available:
\staggered{\quad\tt mm }
\key{\quad\tt pt} point (is used by \TeX{})
\key{\quad\tt pc} pica $1 pc = 12 pt$
\key{\quad\tt in} inch $1 in = 72.27 pt$
\key{\quad\tt bp} big point $72 bp = 1 in$
\key{\quad\tt cm} centimeter
\key{\quad\tt mm} millimeter
\key{\quad\tt dd} did\^ot point $1157 dd = 1238 pt$
\key{\quad\tt cc} cicero $1cc = 12dd$
\endstaggered


Here a few examples for a \\special-string:

\itemlist{$\bullet$ }
\next{\tt \\special\{ifffile=dh0:pict/graphic1\}}\hfill\break
 Here the IFF-file ``graphic1'' from the directory ``dh0:pict''
 is included at the current text position.
\next{\tt \\special\{ifffile=graphic2 hoffset=1.5in\}}\hfill\break
 This time, the picture is taken from the current directory of the
 \spec{} program and moved 1,5 inch to the right.
\next{\hbox{\tt \\special\{ifffile=graphic3~voffset=-1cm~hsize=2in~vsize=1in\}}}
 \hfill\break
 The picture ``graphic3'' is moved one centimeter upward in this
 example and enlarged or reduced to the size of 2 by 1 inch.
\enditemlist

When using the keywords {\tt hsize} and {\tt vsize} by the way,
you do not have to take the right selection of the ``Base DPI''
into consideration anymore, as then the picture in any case
will be brought on the size necessary. The original
size of the picture will then be ignored.

\section{The software interface to the drivers}

Here a short view into the working of the \spec{} program.

\subsection{The communication through ports}
The communication of the driver with the \spec{} program is
taking place through a message port. As soon as \spec{} is started,
it opens a port with the name ``special\_dvi''. The program waits
by this port for messages of the driver.

When a driver encounters a \\special-string in the DVI-file,
it first tests, whether the port of the \spec{} program exists.
If not, it ignores the string. In case it does, the driver
creates a port with the name ``special\_reply'' and installs
it as a reply port.

Through the port ``special\_dvi'' it sends the
\spec{} program a message, in which the current
resolution of the printer (or that of the screen)
as well as the \\special-string are contained.

\spec{} evaluates this message and appends the {\tt special\_map}
structure to it. This contains the size of the picture,
the offset and also the name of the bitmap file or a pointer
to the bitmap. This message sends it per ``ReplyMsg'' back to
the driver.

As soon as the driver has evaluated all the information of the
``special\_map'', it sends the \spec{} program another message,
so that it knows, that the storage space of the ``special\_map''
can be freed again. This message is acknowledged by \spec{}
immediately.

After that the driver erases its Reply-Port.

While this communication is happening -- between
the sending of the first message by the driver,
and the return of the second message by the \spec{} program --
the dialogue between the two partners must not be interrupted.
As soon as one of the two terminates the communication,
a deadlock is created. The other program waits until
the next reset. As no timeout is implemented,
in this case only a reboot helps. If you change
the \spec{} program, then you should take notice,
that during the communication the program cannot
be broken. Also in case of an error,
the communication must be finished.

\subsection{The bitmap-file format}

In order to avoid the time consuming enlargement or reduction of
the pictures, there is the possibility of storing the pictures
that have been brought to the right size already.
You can set this with the two {\tt File}-gadgets.

In order to always have the pictures ready in the various resolutions,
the corresponding resolution of the printer (respectively that of the
screen) is appended when storing.
If you store the picture {\tt testpic} in the previewer
with a resolution of 91dpi, a file {\tt testpic.91x91}
is created.

This file has a very special format.\parwithoutskip
The first four bytes of the file are the `Magic Word' ``SPEC''.
You can see from this, that it is a bitmap file of the \spec{}
program.

The next four bytes appear, when you add up the special-string
that belongs to this file, character for character.
This is useful for recognizing whether the special-string has
changed since you have created the file. Is this the case,
then the picture is recomputed and stored.

Now two longwords follow, which indicate the width and the
height of the picture in pixels.

Finally, the bitmap comes, line for line. The length of a line
is rounded upwards to 16 bits. Thus, for a line with 100 bit,
you need seven 16-bit words.

Another piece of data is stored with the file. The date of
creation. It is used to check, whether the IFF picture is
younger then the bitmap file. Is this the case,
then of course the bitmap must be recomputed,
as the IFF picture has apparently changed.

By this comparison of the dates and by the checking of the
\\special-string it is made sure, that no obsolete bitmap file
is used. So you can use the drawing mode {\tt Transfer picture in a file}
as the standard, without trouble. This way,
a picture for a resolution has to be computed only once,
and is always available after that as a file.
The only thing, that can become a problem,
is the memory, as the bitmap files are not stored
compressed.

\subsection{The Source}

In order to quickly learn your way around in the source,
a short description of each file is given here.
\staggered{\tt specialhost.c }
\key{special.c}  Source of the communications-functions for the drivers.
\key{special.h}  Definitions of the structurs, which are used for
   the communication.
\key{flextr.c}  Module for enlargement or reduction of
   monochrome bitmaps. Algorithms taken from the
   FBM-package
\key{specialhost.c} Module with all the funktions, which are used for the
   communication with the drivers. Plus functions
   for the evaluation of the \\special-string.
\key{specialhost.h} Defines for error messages and Draw-Mode.
   Plus prototypes of the module 'violating' functions.
\key{specialparse.c} Module that takes over the evaluation of the
   \\special-string. This module is originating from
   the file ``dospecial.c'' of the PostScript-driver ``dvips''
   by Thomas Rokicki.
\key{specialparse.h} Definitions of the structurs for the file
   ``specialparse.c''.
\key{specialwin.c} In this module the window- and gadget-handling
   is being handled. Also present here is the ``main''-function
   with the main loop, in which there is waited
   for all possible signals.
\key{specialwin.h} The gadgets are defined here.
\key{iff.h} Headerfile of Christian A. Weber's ``iff.library''.
   However, I have changed it in a way, that the pragmas can now
   also be used with the Aztec-C compiler.
\endstaggered

\section{To Do}
Apart from some minor flaws when operating the program,
especially a better picture processing is missing.

For one, no colour pictures can be processed.
On the other side, it would be certainly a great gain,
if you could include vector-graphics.

But that is why I release the complete source to
the program. Perhaps somebody who knows his way around
in graphic-processing, has a little time and is willing
to put some effort into it, will incorporate his knowledge
in the program.

\section{Hard- and software required}
As far as hardware goes: an Amiga, and if possible with somewhat
more memory. Otherwise, it could come to storage shortages
in case of large pictures and high resolution.

As software, the \TeX-drivers, \ShowDVI{} and \DVIprint are needed.
Plus the ``iff.library'' by Christian A. Weber.

\section{Known bugs}
The file ``specialwin.c'' cannot be compiled with the optimizer of Lattice.
On the other hand, the Aztec-C compiler Version 5.0a creates incorrect
code for the module ``specialparse.c''.

Translation from German to English by Thomas Tavoly.

\bye