TkDVI and \special commands
===========================

TkDVI supports a number of \special commands, most of which are
unfortunately somewhat non-standard (but cool, man!). Here's a brief
overview:

1. Document information (à la PDF)
----------------------------------

Information about the title, author, ..., of a document may be embedded
by using specials of the form

  \special{info foo bar baz}

This associates `bar baz' with `foo' such that the `General Information'
window of TkDVI will display

  Foo: bar baz

The `canonical' keys used in the General Information window are:

  File	- the name of the DVI file being displayed [*]
  Title - the title of the document
  Author - the author of the document
  Keywords - keywords describing the content of the document
  Producer - the program that the DVI file was generated with (usually TeX)
  Modified - the date when the DVI file was last modified [*]
  Size	- the size of the DVI file in bytes [*]
  Comment - the comment from the DVI file's preamble (usually not very
	  interesting, though) [*]

The items marked [*] are determined at run time and cannot be overwritten
by \special commands in the DVI file itself.

Other keys than these may be used and will be displayed in the General
Information window after the `canonical' keys.


2. Bookmarks (à la PDF)
-----------------------

This makes it possible to jump directly to the start of a chapter,
section, ... in the DVI file by using hypertext `anchors' (see below).
Use the `htkdvi.def' module for hyperref from testdvi/; there is also
a patch that you need to apply to your hyperref.sty. (Eventually this
may become part of the canonical hyperref distribution.)

The DVI file contains a sequence of \special commands like

  \special{bookmark begin}
  \special{bookmark add 1 section.1 First Section}
  \special{bookmark add 2 subsection.1.1 First Subsection}
  \special{bookmark add 1 section.2 Second Section}
  \special{bookmark end}

(this is usually managed by the `hyperref' LaTeX package with the
special TkDVI driver module). TkDVI reads these \special commands and
constructs a list where the user can click on a heading in order to
go to the corresponding place in the DVI file.


3. Source \specials
-------------------

\special commands of the form

  \special{src:<lineNo><filename>}

correlate the DVI output with the lines and files of the (La)TeX input.
Currently this is understood by TkDVI but not really used; in any case
it requires support from the underlying TeX implementation to be really
useful. TkDVI stores the locations and can determine the file name and
line number which is most likely to correspond with a given point on
a page, but no interface to a text editor has been defined yet.


4. Tcl/Tk `graphics'
--------------------

Various types of multimedia gimmicks can be programmed in Tcl and
included in a DVI page. This is really not general enough to be
recommended, and at the current stage it is also quite unsafe, so don't
use this unless you know *exactly* what you are doing.

A versatile and safe interface must still be defined, and therefore
this issue is not taken further here; read the source code in
lib/browser.tcl if you must know how it works.


5. Hypertext anchors
--------------------

According to the HyperTeX standard, TkDVI supports hypertext `anchors'
that label various places in the DVI file. These anchors are of the form

  \special{html:<a name="foobar">}

Anchors are extracted when a DVI file is opened and stored in a Tcl
hash table. A list of anchor names can be obtained using the
`info anchors' subcommand on a dvi::code object, and the page number
that an anchor occurs on can be found using the `findanchor' subcommand.

There should be support for hypertext *links* but that hasn't been
written yet.


6. Color
--------

TkDVI contains some support for color, based on the dvips implementation.
The following commands are defined:

  color push ( rgb <r> <g> <b> | cmyk <c> <m> <y> <k> )
  color pop

Note that color support for X11 is much more difficult than color
support for PostScript. In particular, a situation like

   +--------+--------+
   |red    ***   blue|
   |      *****      |
   |     ***|***     |
   |    *** | **--------- green
   |   ***  |  ***   |
   |  *************  |
   | *************** |
   | ***    |    *** |
   | ***    |    *** |
   | ***    |    *** |
   +--------+--------+

is pretty much hopeless, since anti-aliasing would require us to look
at the colors of each actual background pixel along the glyph's
outline.

Color support would need to be redone in the light of Tom Rokicki's
TUGboat article but this doesn't seem all that urgent. Colored writing
on white background works reasonably well.


7. Layering
-----------

This is a method for `partially' displaying a DVI page, for
presentations à la PowerPoint or fill-in-the-blanks exams. It is
similar but not identical to the `\pause' feature implemented at the
PDF level by programs such as Klaus Guntermann's PPower4. Think of a
`layered' DVI page as a stack of transparent overlays. The main
difference between this and `\pause' is that, with \pause, display of
the page in question stops at the \pause, while with layering, only
material on or below the current layer is displayed while material on
a higher layer is suppressed.

The following \special commands govern layering:

  layer push	Let n be the current level of layering. The following
                material will appear on level n+1.
  layer pop     Let n be the current level of layering. The following
                material will appear on level n-1.
  layer reset	Resets the current level to zero.

There is a LaTeX package called `layers.dtx', which explains this in
more detail. It can be found in the testdvi/ subdirectory of the TkDVI
distribution.


$Id: README.specials,v 1.1 2000/06/30 10:28:50 lingnau Exp $