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

TkDVI supports a number of \special commands, most of which are
unfortunately 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).

The DVI file contains a sequence of \special command 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.
For the time being, the Unix TeX implementation (Web2C) doesn't support
putting such specials into a DVI file automatically, so you need to
use a TeX-level implementation such as srcltx.sty to put them there.

If source specials are enabled for a DVI file (via `configure
-sourcespecials 1', X resources, or, more conveniently, on the TkDVI
command line (`$ tkdvi -x sourcespecials:1 foo'), clicking mouse
button 3 on a position within a DVI image with the Meta key held down
will try to locate the file name and line number most likely to
correspond with that point and to communicate this to a text
editor. The text editor will be invoked by means of a command template
in the -editor configuration option of a tkdvi::browser widget; the
default value is

  emacsclient --no-wait +%l %f

In a command template, `%l' will be replaced with the line number
and `%f' with the file name in the source special.

For the time being, this facility should be considered experimental.


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. Adding support for more \specials
------------------------------------

You can add support for your own favourite \special commands by defining
a procedure called `::tkdvi::browser::special::foo' to handle \special
commands like `\special{foo ...}'. The initial `word' consists of
letters and digits only. For TkDVI to be able to access your procedure,
it is most convenient to place it in a package
`tkdvi::browser::special::foo', and either to add the package name
to the `*TkDVIBrowser.specials' or `*TkDVIBrowser.userspecials' resources,
or to `package require' the package in a `userInit' procedure. The
resource method is preferable in that it guarantees that most of the
relevant initialization of the tkdvi::browser code has already taken
place. (You can conveniently set the `*TkDVIBrowser.userspecials'
resource in a `userInit' procedure by means of

  option add *TkDVIBrowser.userspecials foo userDefault

). By way of an example, here is the implementation of the relevant
bits of `\special{info ...}':

  namespace eval ::tkdvi::browser::special {}

  proc ::tkdvi::browser::special::info {name key x y cookie s} {
      variable ::tkdvi::browser::State

      if {[scan $s {info %[^ ]} k] != 1} {
	  return
      }
      set State($name-info,$k) \
	      [string range $s [expr {6+[string length $k]}] end]
  }

  package provide tkdvi::browser::special::info 1.0

The `namespace eval' makes sure that the special namespace exists and
can accept procedure definitions. The special-handling procedure
takes five arguments:

  name	- name of the browser megawidget; necessary to access the
	  `State' array
  key   - identifies the DVI image within the megawidget (see the
	  source code for the CreateDviImage procedure for details)
  x, y  - canvas coordinates of the current DVI interpreter position
  cookie - identifes the \special node currently being handled
  s     - full command string from the \special command

The `package provide' is near the end of the file in order to make
sure that the package isn't declared operational when something goes
wrong during loading.

You can define more procedures as required but you should put them
into their own namespace to be safe. See the source code for the
bookmark specials (in specBM.tcl) for an example.

Note that the procedures in question will be invoked each time the
DVI page is rendered. You should take appropriate care to ensure that
your procedures are either idempotent or will be executed only once
(you could use an approach like

  if {[info exists State($name,spec-foo-$cookie)]} {
      return
  }
  set State($name,spec-foo-$cookie) 1

Your special-handling code can `hook' into the file-opening and page
display routines of TkDVI by registering suitable procedures using
calls like `tkdvi::browser::addHook open foo-init'. The first argument
is the `hook name' -- currently `open', `predisplay', and
`postdisplay' --, the second is the name of a procedure to be
called. This procedure will be invoked like `foo-init name', where
`name' is the browser megawidget name. Again, see the source code for
the bookmark specials for an example. The `predisplay' hooks are
called before a page is being displayed, and the `postdisplay' hooks
are called immediately before a page is replaced by another page
in the display.


$Id: README.specials,v 1.3 2001/08/03 12:47:29 anselm Exp $