% -*- mode: latex; buffer-read-only: nil; -*-
\documentstyle{article}
\topmargin0.5cm  \footskip15mm
\oddsidemargin0.5cm 
\headheight0in\headsep0in
\textwidth150mm
\textheight297mm
\advance\textheight-1in
\advance\textheight-14mm
\advance\textheight-\topmargin
\advance\textheight-\headheight
\advance\textheight-\headsep
\advance\textheight-\footskip
\pagestyle{plain}
\newbox\mybox
\newcount\keywidth
\newcount\halfkeywidth
\def\keys#1{%          %<-------
\setbox\mybox=\hbox spread 6pt{\hfill\footnotesize #1\hfill}%
\keywidth=\wd\mybox%
\divide\keywidth by 65536%
\halfkeywidth=\keywidth%
\divide \halfkeywidth by 2%
\unitlength1pt\begin{picture}(\keywidth,10)(0,3)
\put(\halfkeywidth,5){\oval(\keywidth,10)}%
\put(\halfkeywidth,5){\vbox to0pt{\vss\hbox to0pt{\hss\unhbox\mybox\hss}\vss}}
\end{picture}}
\def\key#1{%          %<-------
\unitlength1pt\begin{picture}(10,10)(0,3)
\put(5,5){\oval(10,10)}%
\put(5,5){\vbox to 0pt{\vss\hbox to 0pt{\hss\footnotesize #1\hss}\vss}}
\end{picture}}
\def\kitem#1{\subsubsection*{\mediumseries #1}}
\parindent0in
\parskip.3ex plus .1pt
\bgroup
  \catcode`\!00\relax
  \catcode`\[01\relax
  \catcode`\]02\relax
  \catcode`\"12\relax
  \catcode`\}12\relax
  \catcode`\{12\relax
  !catcode`!\12!relax
  !gdef!hyperquote["]
  !gdef!hyperbackslash[\]
  !gdef!hypergopen[{]
  !gdef!hypergclose[}]
  !global!edef!hyperhash[!string#]
  !global!edef!hypertilde[!string~]
!egroup
\def\fragilehyperanchor#1#2{%
   \ifvmode\leavevmode\fi%
   \special{%
        html:<a name=\hyperquote#1\hyperquote>%
   }#2%
   \special{html:</a>}%
}
\let\fha\fragilehyperanchor
\edef\fragilehyperref#1#2{%
   \special{%
      html: <a href=\hyperquote\hyperhash #1\hyperquote>%
   }#2%
   \special{html:</a>}%
}
\let\fhr\fragilehyperref


\begin{document}
\language0
\def\bottomfraction{1}
\setbox\mybox=\hbox spread 5pt{\hfill\Huge TMVIEW -- V 98.06\hfill}
\vglue-2cm
\centerline{\vtop spread 5pt{\hsize\wd\mybox\hrule height 1pt\vfill
        \box\mybox
        \vfill\hrule height 1pt}}
\vskip1cm       
%\section{Introduction}
What is tmview?  tmview is a screen-previewer for \verb+.dvi+-files compiled
by \TeX. It let's you see what your printed output will look like. You can
choose between a black-and-white representation and greyscaling. You can choose
an arbitrary zoomfactor (at some cost of performance). You can set marks to
measure distances. You can search for textstrings. You may visit lots of
\verb+.dvi+-files, set bookmarks and get them saved to a startup-file. tmview
does not support pxl-files since I think they are prehistoric.
tmview ignores all \verb'special'-commands, sorry lads.
tmview tries its best with virtual fonts and
is prepeared to be linked with kpathsea.\\

The current version goes with linux/svgalib as well as
the X Window System.

\tableofcontents

\section[Commandline options]{Starting tmview -- Commandline options}

\subsubsection*{Usage}
{\catcode`\<\active\def<#1>{{\rm\em #1\/}}
\begin{verbatim}
tmview [-?] [-h<marg>] [-v<marg>] [-p<width>x<height>] [-r<xres>x<yres>] 
       [-f<path>] [-n<name>] [-t<path>] [-g<path>] [-d<width>x<height>]
       [-m<mag>] [-k<leftmarg>,<rightmarg>,<uppermarg>,<lowermarg>]
       [-s<startup>] [<file>[.[dvi]]]
\end{verbatim}}

If you call tmview with the option \verb+-?+, tmview will give a complete list
of all possible options and their default-values, before reading any
startup-file.

{\bf Important:} All options have to be followed {\bf immediately} by their
arguments, {\bf no} spaces must be inserted !!!

%\subsection{Commandline-Options}

The command-line-options are meant to prepare tmview for going with your
systems \TeX-setup. While the defaults work fine on my system, you may have to
pass suitable values. See \verb+-s+ for keeping your defaults in a
startup-file.
\begin{itemize}
\def\tem#1{\item[\verb+#1+]}
\tem{-?}     (Help command-line-options)\\
       List all command-line-options and their defaults, before reading
       any startup-file (see \verb+-s+).

\tem{-h} (Horizontal-offset)\\
       A lot of printer drivers do a horizontal offset
       of 1 inch. If yours does as well, you should use \verb+-h25.4+. The
       length following \verb+-h+ must be given in mm.  Default: \verb+25.4+

\tem{-v}     (Vertical-offset)\\
       A lot of printer drivers do a vertical offset of 1 inch. If yours
       does as well, you should use \verb+-v25.4+. The length following
       \verb+-v+ must be given in mm.
       Default: \verb+25.4+

\tem{-p}     (Paper-size)\\
       Tells tmview width and height of the paper you are using. The width is 
       given first and both width and height are given in mm. Width and height
       are separated by an \verb+x+.
       Default: \verb+210.0x297.0+ (German DIN A4)                 

\tem{-r}     (Resolution)\\
       Tells tmview what kind of \verb+.pk+-files to use.
       The horizontal resolution is 
       given first and both horizontal and vertical resolution are given in
       dpi (dots per inch). The two values are separated by an \verb+x+. Saying
       \verb+-r600x600+ means tmview will use fonts which were generated for a 
       600-dpi-printer. As tmview assumes that pixels on the screen are square,
       different values for horizontal and vertical resolution will result in 
       a distorted image. Always make sure the desired \verb+.pk+-files
       are available.
       The chosen resolution determines the (maximum) size of the 
       representation (comp. \key{+} below).
       Default: \verb+300x300+                                     

\tem{-f}     (Font-path)\\
       A list of paths telling tmview where to look for the \verb+.pk+-files.
       The items
       in this list have to be separated by '\verb+:+'. The given list is
       executed from left to right. If an item ends with \verb+//+ all
       subdirectories will be scanned too. This is programmed in a very odd
       way, so it takes a lot of time. You should place such items at the end
       of the list. Default: \verb+./:/usr/lib/texmf/fonts//+                   

\tem{-n}     (Name-of-the-font-file)\\
       If your \verb+.dvi+file tells tmview to use a font called
       \verb+thisnthatfont+ and tmview was told to use a resolution of
       \verb"123" dpi, tmview has to know how the desired file is named. In the
       string following \verb+-n+ the following replacements are made:

       \smallbreak
       \begin{tabular}{@{\unskip}ll}
       \hskip0pt plus 1filxxx & \hskip5em replaced by\\[.5ex]
       \verb+@N+   &   thisnthatfont\\
       \verb+@K+   &   thisntha  (this is \verb+@R+ reduced to 8 characters
                       (MS-DOG !))\\ 
       \verb+@M+   &   123       (the resolution)\\
       \verb+@R+   &   615       (this is \verb+@M+$*5$, intended for magnified
                       200 dpi fonts used instead of 300 dpi fonts)\\
       \end{tabular}

       \smallbreak
       Default: \verb+@N.@Mpk+

\tem{-t}     (Tfm-path)\\
       A list of paths telling tmview where to look for the
       \verb+.tfm+-files. The 
       items in this list have to be separated by '\verb+:+'. The given list is
       executed from left to right. \verb+.tfm+-files are used, when
       tmview can't find a fonts \verb+.pk+-file. In that case boxes
       are drawn instead of the  glyphs. 
       Default: \verb+./:usr/lib/texmf/fonts//+ 
 
\tem{-g}     (Vf-path)\\
       A list of paths telling tmview where to look for the \verb+vf+-files.
       The support of \verb+vf+-files is not very well tested. If anything
       goes wrong with \verb+vf+-files, use dvicopy to replace them by
       ordinary dvi-code.
       Nomenclature of the list is as above.
       Default: \verb+./:usr/lib/texmf/fonts//+ 
 
\tem{-d}     (Display)\\
       Tells tmview the desired size of your display. The width is given 
       first and both width and height are given in pixels. Width and height 
       are separated by an \verb+x+. Using linux you may choose a resolution
       supported by your version of svgalib with respect to your hardware. 
       Only 256-color-modes are allowed. That means to get more than 320x240 
       you must have a supported svga chip-set, standard vga won't do. 
       See {\em Installation\/} on how to run tmview with standard vga. 
       Default: look for the value of \verb+$GSVGAMODE+ if set, otherwise try
       \verb+640x480+.
       
\tem{-m}     (Magnification)\\
       If you want to magnify by a factor $n$ you have to specify $n*1000$ as
       an argument to \verb+-m+, e.g. \verb+-m2000+ means all lengths will be
       doubled. {\bf Note:} tmview magnifies according to the origin of the
       dvi-coordinates, which is -- in most cases -- {\em not\/} the upper left
       corner of the paper. Always make sure the desired \verb+.pk+-files are
       available. \verb+-m+ doesn't magnify the paper, so if you wish a larger
       image use the \verb,+, and \verb+-+ keys or the \verb+-r+ option.
       Default: get magnification from \verb+.dvi+-file.

\tem{-k}     (Kannot-print-any-further)\\
       Most printers stop printing if they are too close at the papers edge 
       (some might even do strange things). The \verb+-k+ option describes the 
       printable area, e.g. saying \verb+-k1.0,2.0,3.0,4.0+ means that your
       printer can print as close as\\
       1 mm to the left\\
       2 mm to the right\\
       3 mm to the upper\\ 
       4 mm to the lower\\
       edge of the paper. These values are used to draw a frame indicating the
       printable area (comp. \key{p} below). When searching textstrings, any
       text outside the printable area is ignored. All four values have to be
       given and they have to be separated by '\verb+,+'.  All lengths are
       given in mm.  Default: \verb+4.0,4.0,4.0,12.0+

\tem{-s}     (startup-file)\\ 
       The above options, a list of visited \verb+.dvi+-files (see bookmarks
       below) and lots of other interna may be loaded from the startup-file,
       specified directly after the -s. When you say \verb*+-s +, i.e.\ give
       {\em no\/} argument to \verb+-s+, {\em no\/} startup-file is loaded.

       The startup-file is read {\em before\/} reading any commandline-options
       -- this means you can override the defaults from the startup-file. When
       quitting tmview the current options etc.\ will be saved in the
       startup-file. If this is not desired, the startup-file has to be set
       read-only !! Therefore a possible tactic is to run tmview with suitable
       options, visit often used \verb+.dvi+files, set within these desired
       manual-bookmarks and save all that information in the startup-file. Then
       set it read-only and/or copy it somewhere save. See also {\em editing
       the startup-file\/} below.  Default: \verb+~/.dvisvga+
\end{itemize}

\section[Viewing a .dvi-file]{Using tmview -- Viewing a  \verb+.dvi+-file}

\begin{table}[b]
\centerline{\bf commands of tmview}
\fha{keylist}{}%

\vskip2ex
\begin{tabular}{lp{10cm}}
\key{?}         & give a short description of the following command\\
\key{?}\,\key{?} &  give a list of all commands\\
\keys{PgUp}, \keys{PgDn}& select a page relative to the current page\\
%\key{\fhr{goto}{g}}         & select a page w.r.t.\ \TeX-counters\\
\key{g}         & select a page w.r.t.\ \TeX-counters\\
%\key{\fhr{left}{$\leftarrow$}}, \key{$\rightarrow$},
\key{$\leftarrow$}, \key{$\rightarrow$},
\key{$\uparrow$}, \key{$\downarrow$} &   scroll the visible area\\
\key{f}, \key{c}& make scrolling finer/coarser\\
\key{z}         & center visible area\\
\key{$+$}, \key{$-$} & zoom in/out\\
\key{v}         & set zoom-factor\\
\key{b}         & set a bookmark\\
\key{w}         & move to a bookmark\\
\key{\bf\^{}}   & move back\\
\key{o}         & toggle greyscaling\\
\key{x}         & toggle statusline-information\\
\key{t}         & set unit of measurement\\
\key{l}         & show/hide screenmark and pagemark\\
\key{y}         & set pagemark at the position of screenmark\\
\key{a}         & how/hide marked rectangle\\
\key{p}         & show/hide printable area\\
\key{e}         & set page-offset and -size\\
\key{\fhr{half-hyper}{k}} & show/hide half-hyper-tex-mark\\
%\key{k}         
\keys{TAB}       & move to next href\\
%\keys{RET}       & follow current href\\
\keys{$\hookleftarrow$} & follow current href\\
\key{s}         & search for text\\
\key{r}         & re-read \verb+.dvi+file and re-draw screen\\
\key{d}         & load/kill \verb+.dvi+file\\
\key{q}         & quit tmview\\
\end{tabular}
\end{table}

When everything is set up to suit your needs, visiting a \verb+.dvi+file simply
means to navigate the visible area through the files using the
cursor-keys. A great varity of commands is available, including commands for
loading files, changing the paper-size or setting marks. The table shows all
available commands. Commands are invoked by single key-strokes e.g.\ \key{q}
quits tmview.

For the sake of information there is a more secure way of invoking a command:
If you insert \key{?} before hitting another key the status-line will give a
short description of the command which includes information about the commands
arguments. Now there are two possibilities: Hit \keys{$\hookleftarrow$}
(perhaps after inserting arguments) to execute the command or \keys{ESC} to
cancel. Besides \key{?} there is another way of invoking commands this
way: Just insert the appropriate uppercase letter. This leads to a convenient
way of getting accustomed to tmview, the {\em tutorial-mode\/}. Do caps-lock
right after tmview has started: from now on nothing happens without your
explicit confirmation.

\subsection{Arguments}

Some of the commands in table 1 take numerical arguments. Arguments are always
{\em optional\/}. They have to be entered {\em before\/} calling the
command. Multiple arguments are separated by '\verb+,+' or '\verb+;+'. If you
{\em are\/} giving arguments to a command, give {\em all\/} arguments, if you
don't give enough, the command will behave as if {\em none\/} had been
given. After inserting the arguments just call the command, no Return or
whatever is required (as a matter of fact \keys{$\hookleftarrow$} even destroys
your arguments). If you give arguments to a command that doesn't want them, the
arguments are simply discarded -- no error.

If no argument is given, a default is used. If an argument is passed, it serves
as the default for future invocations of this command. Commands doing similar
things share the same default arguments.

{\bf Example:} typing {\tt 10}\,\key{$\leftarrow$} results in scrolling 10\% to
the left. Thus typing \key{$\rightarrow$} afterwards scrolls 10\% to the right
and \key{$\uparrow$} scrolls 10\% upwards.

\subsubsection{{\tt *}  -- the magic argument}

As a special argument most of the commands accept the so-called {\em magic
argument\/} \verb+*+. It is used either to modify the behaviour of the command
in some way or to get the arguments from somewhere else (e.g.\ from the
command-line or even the startup-file). To get an understanding of the {\em
magic argument\/} consider the following examples:

\begin{description}
\item{\key{p}} draws a rectangle showing the {\em printable area\/}. It takes
four arguments stating where your printer will refuse to print any closer to
the paper's edges.
If \verb+*+ is given as an argument (one '\verb+*+' {\bf not} four),
the according numbers are taken from the startup-file.
\item{\key{w}} moves through one of two rings of bookmarks: the ring of
file-bookmarks or the ring of manual-bookmarks. If \key{w} receives the
{\em magic argument\/} the other ring is chosen, no movement is performed. The
status-line will say 'SET TO MANUAL-BOOKMARKS' if the current ring {\em was\/}
the file-bookmark-ring (and is {\em now\/} the manual-bookmark-ring). So in
this case \verb+*+ acts as a kind of flag argument.\\
\end{description}

\subsection{The detailed command list}

%\subsubsection*{Selecting the page}
\subsubsection*{Moving through the document}
\kitem{\keys{PgUp}, \keys{PgDn} Select a page relative to the current page}

\keys{PgUp} moves towards the beginning of the \verb+.dvi+file, while
\keys{PgDn} moves towards the end. A single argument $n$ specifies the number
of pages to move. If the argument is \verb+*+, the page-moving-mode is toggled
(no movement). The two possible modi are:

\begin{enumerate}
\item Keep the visible area where it is.
\item Perform a centering (horizontal {\em and\/} vertikal) -- just like
calling \key{z}\,\key{z} -- after reaching the new page.
\end{enumerate}

The second modus comes in quite handy when you want to read the \verb+.dvi+file
rather than to check it. After a \keys{PgDn} the top of the page will allways
be visible -- at least if the centered point is set up appropriately, see
\key{z} below.

{\bf Example:} \verb+1+\,\keys{PgUp} selects the previous page
\keys{PgDn} selects the next page

%\kitem{\key{\fha{goto}g} Select a page with respect to \TeX counters}
\kitem{\key{g} Select a page with respect to \TeX counters}

A list of ten arguments ($c_0$, $c_1$, \dots $c_9$) specifies the page to be
selected. tmview will jump to the first page with a value of $c_i$ in
\verb+\count+$i$ ($i=0,\dots9$), \verb+*+ may be used as a wildcard. If there
are more than one but less than ten arguments given, the others will be taken
as \verb+*+.
 
{\bf Example:} \verb+26+\,\key{g} selects the first page with a value of 26 in
\verb+\count0+.

%\subsection{Moving around on the current page}

%\kitem{\fha{left}{}\key{$\uparrow$}, \key{$\downarrow$}, \key{$\leftarrow$},
\kitem{\key{$\uparrow$}, \key{$\downarrow$}, \key{$\leftarrow$},
\key{$\rightarrow$} Scrolling the visible area}

A single argument $p$ may be used to specify the amount of scrolling in percent
of the screen-width. \key{$\uparrow$} \key{$\downarrow$} both accept the
argument \verb+*+ to toggle between: 1.~stay on the current page; 2.~scroll
over pages. When scrolling over pages, you may view the whole document while
using only the single key \key{$\downarrow$}.

{\bf Example:} \verb+20+\,\key{$\leftarrow$} scrolls $1/5$ to the left.

%\kitem{\fha{finer}{\key{f}}, \key{c} Make scrolling finer/coarser}
\kitem{\key{f}, \key{c} Make scrolling finer/coarser}

These commands change the default argument for the above scrolling commands. So
\key{f} and \key{c} don't move the visible area at all, but they change the
way the scrolling-commands act.

\subsubsection*{replacements for the cursor keys}
    
If your terminal sends strange escape sequences when you hit a cusror key, you
don't need to worry: tmview supports keys to replace the cusor keys. These are:
\key{i} to replace \keys{PgUp}, \key{m} for \keys{PgDn}, \key{u} for
\key{$\uparrow$}, \key{n} for \key{$\downarrow$}, \key{h} for
\key{$\leftarrow$} and \key{j} for \key{$\rightarrow$}. 
$$\begin{tabular}{ccc@{\hspace{10em}}ccc}
      & \dots &                                                     &
      & \dots &                                                    \\
      & \key{$\uparrow$}\,\keys{PgUp}&                              &
      & \key{u}\,\key{i}          &                                \\[-.5ex]
\dots & \key{$\leftarrow$}\,\key{$\rightarrow$}\,\hphantom{\keys{PgUp}}&\dots&
\dots & \key{h}\,\key{j}\,\hphantom{\key{x}} & \dots\\[-.5ex]
      & \key{$\downarrow$}\,\keys{PgDn} &                           &
      & \key{n}\,\key{m} & \\
      &\dots&                                                       &
      &\dots& \\
\end{tabular}$$

\kitem{\key{z} Center the visible area}

Without any argument \key{z} centers horizontally only, while \key{z}\,\key{z}
centers in both directions.  When two arguments $x$, $y$ are given, they
describe the point on the page, which will become the middle of the visible
area. When the argument \verb+*+ is given, the current position is taken as the
centre. When the screenmark is shown (see below \key{l}), and the argument
\verb+*+ is given, the position of the screenmark becomes the center. This
moves the visible area, but it does not move the screenmark.
    
%\subsection{Zooming}
\kitem{\key{v} Set the zoom-factor}
 
This command requires one argument $f$ which must be between 0.1 and 2. $f$
will become the zoom-factor and the visible-area will be redrawn. If the
zoom-factor is 1, the pixels found in the \verb+.pk+-files are just
copied one by one
to the screen. Since the resolution of our days screens seems to be less than
that of our days printers, and since you propably still want to use the same
\verb+.pk+-files for printing and viewing, $f=1$ usually results in a positive
magnification. So when you're just reading some text in some \verb+.dvi+file
the best value for $f$ is something like 0.3, depending on the involved
resolutions. When the screenmark is visible (see \key{l}) the position of the
screenmark is taken as the origin of zooming, i.e. it is fixed. When the
screenmark is not visible, the middle of the screen is fixed. The current
zoom-factor is displayed in the {\em second} statusline, see \key{x}.

There are two zooming modi. The fast modus only works if $1/f$ is an integer.
So good values are $f=1.0$, 0.5, 0.333, 0.25, 0.2, 0.167 and so on. When in the
fast modus, the \key{$+$}/\key{$-$} keys described below step through these
values only. Usually you don't need to use \key{v} at all.
       
The good thing about the slow modus is, that it allows you to choose the
zoom-factor arbitrarily (between 0.1 and 2). So poor students with small
screens might find some optimum to make the text fit on the screen still being
readable.
The bad thing about the slow modus is that it is slow.  But since
glyphs are kept in memory once zoomed, this slowlyness only hurts while viewing
the first few pages after changing the zoom-factor. Anyway, \verb+*+\,\key{v}
brings you back to the fast modus, choosing the nearest possible zoom-factor.


\kitem{\key{$+$}, \key{$-$} Zoom in/out}

Increase/decrease the zoom-factor. When in the fast modus, step through
the fast values only (see above). When an argument $p$ is given, it
is taken as the amount of increasing/decreasing in percent of the
current zoom-factor. This is likely to result in slow modus.

{\bf Example:}\\
\begin{tabular}{lcll}
{\tt 0.17}\,\key{v}  & set zoomfactor to &  0.17                  & slow\\
{\tt 10}\,\key{$+$}  & set zoomfactor to & $1.1\ast0.17=0.187$    & slow\\
{\tt 3}\,\key{$-$}   & set zoomfactor to & $0.97\ast1.87=0.181$   & slow\\
\key{$-$}            & set zoomfactor to & $0.97\ast0.181=0.176$  & slow\\
\verb+*+\key{v}      & set zoomfactor to & $1/6=0.167$            & fast\\
\key{$+$}            & set zoomfactor to & $1/5=0.2$              & fast\\
\end{tabular}

\subsubsection*{Bookmarks}
A bookmark remembers what is seen on the screen. That is the \verb+.dvi+file,
the page within that file, the position of the visable area and the
zoom-factor. There are three kinds of bookmarks:

{\bf back-bookmarks:}
When searching a text-string, following a href or moving to a bookmark, the
position within the \verb+.dvi+file might be changed to somewhere far far
away. To allow returning from such excursions easily , a back-bookmark will be
generated automaticly.  To prevent getting fed up with thousands of
back-bookmarks, the total number of these is limited. See \key{\bf\^{}} below.

{\bf file-bookmarks:}
Each file visited has one (and {\em only\/} one) file-bookmark, containing the
information mentioned above, plus some information on the file, that is the
paper-offset and -position, the location of the printable-area.  File-bookmarks
are generated automaticly.  This results in easy re-visiting a \verb+.dvi+file:
you'll find it as left. A file-bookmark is removed by killing the
\verb+.dvi+file with \key{d}\,\key{k}, see \key{d} below.

{\bf manual-bookmarks:}
After all you may install your own bookmarks, marking often visited places, say
in some manuals. manual-bookmarks are named by a number.  This number has to be
unique whithin the \verb+.dvi+file they belong to.  To define a manual-bookmark
use \key{b}. Since manual-bookmarks belong to the \verb+.dvi+file they are
defined on, they get lost, when that \verb+.dvi+file is killed by
\key{d}\,\key{k}.

All kinds of bookmarks are kept in a ring-buffer. There is a so called current
bookmark of each type. Visiting the bookmarks along the ring-buffer is done by
\key{w} for file- and manual-bookmarks, while \key{\bf\^{}} acts on
back-bookmarks.

\kitem{\key{b} Define/undefine manual-bookmark.}

When the current position is not already defined as a manual-bookmark, \key{b}
defines one. When a single numeric argument $n$ is given, $n$ will be the name
of the newly defined bookmark. With no argument, a name will be generated
automaticly. See \key{w} below, for how to visit manual-bookmarks.
When the current position is already defined as a manual-bookmark, \key{b}
undefines that manual-bookmark.

\kitem{\key{w} Move to bookmark.}

When a single numeric argument $n$ is given, \key{w} moves to the
manual-bookmark named $n$, if there is one. Since manual bookmarks are bound to
\verb+.dvi+files, the current \verb+.dvi+file will never change in that
case. If no argument is given, \key{w} moves the postion either through
the ring-buffer of file-bookmarks or through the one of manual-bookmarks.
When \key{w} is acting on file-bookmarks, it will switch to another
\verb+.dvi+file , since every \verb+.dvi+file has got only one file-bookmark.
To toggle between theese two modi, use the magic argument \verb+*+.

\kitem{\key{\bf\^{}} Move back}
   
Move to the latest back-bookmark, if there is one. When a single numeric
argument $n$ is given, the $n$ latest back-bookmarks are kept and all the
others are discarded.


\subsubsection*{Measuring}

To allow you to measure distances on the page, there are two marks, the
screenmark, which is fixed on the physical screen you're looking at, and the
pagemark, which is fixed on the \verb+.dvi+files page. When you move the
visible-area, the screenmark acts as drawn with chalk on your monitor. The
pagemark acts as drawn on the page. The second statusline tells the position of
the pagemark relative to the corner of the sheet of paper you're viewing. It
also tells the position of the screenmark relative to the pagemark. To measure
distances you first switch this marks on, using \key{l}. When the marks are
shown, the scrolling commands don't act on the visible area anymore, but move
the screenmark, now only moving the screenmark at the boarder of the screen
results in scrolling. To move the pagemark just move the screenmark at the
desired position and use \key{y} to make the pagemark follow.
 
\kitem{\key{l} (this is the letter 'ell') Show/hide screenmark and pagemark}

This commands takes the two arguments $x,y$. The pagemark is put at position
$x,y$ w.r.t. the upper left corner of the page. The Screenmark may be moved
with the scrolling-commands.

\kitem{\key{y} Set pagemark at the position of the screenmark}

\subsubsection*{Rectangles}
       
Besides the marks there are three rectangles for measurement. First there is
the boarder of the paper setup by the command-line options \verb+-h+,\verb+-v+
and \verb+-p+. Then there is the printable area, setup with the \verb+-k+
command-line option.  Third the so called marked rectangle.

\kitem{\key{a} Show/hide marked rectangle}

The four arguments $t,l,w,h$ specify the position on the page and
the size of the marked rectangle. When no argument is given and pagemark and
screenmark are shown, their positions are used as default.  When they are
hidden, the last position of the marked rectangle is used as default.

\kitem{\key{t} Set unit of measurement}

Whenever you specify arguments which are to describe a point on the page, this
is done w.r.t.\ a unit of measurement, i.e.\ cm, mm, a.s.o. This unit is also
used, when the position of a mark is displayed in the statusline.
 
\kitem{\key{p} Show/hide printable area }
       
The four arguments $l,r,t,b$ specify the margins of the printable area with
respect to the boarder of the page. When pagemark and screenmark are shown, the
argument \verb+*+ sets the printable area to the rectangle described by
screenmark and pagemark.  When they are hidden, \verb+*+ takes the
command-line-options resp. defaults for \verb+-k+.
       
\kitem{\key{e} Set paper-offset and -size}

The four arguments $h,v,w,h$ describe the boarder of the page. Have the
top-left corner of a sheet of paper in mind. $h,v$ is the offset of the
\verb+.dvi+file's origin to this top-left point of the paper.  Standard values
are $h=v=2.54$cm. $w$ and $h$ are the width and the height of the sheet of
paper. The sheet of paper is represented only by a frame on the screen. It does
not affect the drawing of the \verb+.dvi+file.

When pagemark and screenmark are shown, the argument \verb+*+ sets the boarder
of the page to the rectangle described by screenmark and pagemark.  When they
are hidden, \verb+*+ takes the command-line-options resp. defaults for
\verb+-h+,\verb+-v+ and \verb+-p+.

\subsubsection*{Half-hyper}

\fha{half-hyper}{}%
tmview does some of the fancy hyper-tex things. I talk about
{\em half\/}-hyper-tex, because tmview only follows links which point to
somewhere in the currently visited \verb+.dvi+-file. So there is no connection
to the net or so. But you might find it useful (when editing a major project)
to view an equation number this-and-that by clicking on this-and-that whereever
the text refers to that equation.
For information about hyper-tex, related
macropackages and fully compatible viewer scan the net \dots

\kitem{\key{k} Show/hide half-hyper-mark}
\kitem{\keys{TAB} Goto next href}
\kitem{\keys{$\hookleftarrow$} Follow current href, if one is present on the current page}

The \verb+.dvi+-file you're viewing right now provides two links:
one of them is from here to the list of \fhr{keylist}{commands}.
So you may press \key{k},  \keys{TAB} and \keys{$\hookleftarrow$}
to check this out.
Hint: \key{\bf\^{}} moves back. Alternatively \keys{TAB} will
bring you to the next href.





\subsubsection*{Miscellaneous}

\kitem{\key{o} Toggle greyscaling}
 
When the zoom-factor is less than 1, the glyphs usually are displayed using
grey-levels, making them smoother. This takes some memory, so perhaps you will
like to switch it off. On high-res displays there is no need for it anyway.
 
\kitem{\key{x} Toggle statusline-information}

In the bottom line of your screen tmview will always display a statusline. This
statusline is either the {\em standard\/} statusline or the {\em second\/}
statusline. While the standard statusline shows you the number of the current
page and the arguments you are about to pass to a command, the second one shows
additional information for measuring out distances and the current zoom. See
below. \key{x} toggles between these two statuslines.

\kitem{\key{s} Search for text}

You will be asked for the text-string to search for. You may enter a regular
expression\footnote{here 'regular expression' means {\em extended\/} regular
expression} describing that string, this especially includes just to enter the
string as it is.

If a search appears to take infinitely long (which might easily happen, if you
enter a funny regexp), just hit \keys{ESC}, this stops the search. 
      
tmview will take the entire \verb+.dvi+file as one huge text-string and then
search for the next substring, matching the regular expression you've
entered. Here {\em next\/} is meant with respect to the current page.

So far this sounds quite easy, but there are some ugly details, based on the
fact, that a \verb+.dvi+file contains information on how to draw a bitmap
representing your text. It does not contain information about from what
characters in which order your text is made up. Even the PKfiles which are used
to draw your text consist only of lots of glyphs but no character-codes, like
ASCII or so. Building a huge text-string from a \verb+.dvi+file is some kind of
guessing.

First: What kind of huge text-string is build from the \verb+.dvi+file?

This string will consist of the letters A \dots Z, a \dots z, the accent
\verb+"+ and the digits 0 \dots 9. It does {\bf not} contain anything else
like whitespaces, linefeeds or hyphens.\\
Whenbeingprinteditwouldlooklikethisnotreadableatall.\\ Taking the
\verb+.dvi+file as a huge string allows you to find all locations of a
sub-string, say \verb+commandlineoptions+, even those that are seperarted by
linebreaks (and hyphens) or pagebreaks. In turn, there is no chance to find
{\em only\/} those locations, where \verb+commandlineoptions+ is separated by a
hyphen. To keep tmview from getting confused by headings, there is another
rule for building up the huge text-string: any glyph outside the printable area
(see \key{p}) is ignored. So you may set up the printable area to ignore
headings when searching.

Second: How is the huge text-string build up?

%To translate the list of glyphs found in the \verb+.dvi+file to a text-string,
%the tfm-files are asked for the encoding-scheme. This works with dc-fonts and
%cm-fonts, since the following encoding-scheme names are accepted: {\bf ASCII},
%{\bf \TeX text}, {\bf TeX math italic}, {\bf TeX math symbols}, {\bf TeX
%typewriter text}, {\bf Extended TeX Font Encoding - Latin}, {\bf Adobe
%StandardEncoding}.
The alphanumerics A \dots Z, a \dots z, 0 \dots 9 are
copied one by one to the huge text-string. Glyphs that look like a simple
alphanumeric will be taken as the one they look like.  So the \TeX\ input
\verb'\c o', producing an \c o, will be represented as a simple 'o' in the
text-string. This rule also applies to all kind of ligatures. The \TeX\ input
\verb'ffl\AE', producing ffl\AE\ will be represented by f\/f\/lAE.  Any accent
{\em on top\/} of a glyph will be translated to a \verb+"+, preceding whatever
the glyph without that accent would be translated to.  The \TeX\ input
\verb'\"a' producing the german umlaut \"a, will be found as \verb+"a+ in the
generated text-string. The \TeX\ input \verb'\aa' producing the scandinavian
\aa\ will be found as \verb+"a+ too. Any other glyphs are ignored.

Third: In what does the above result?

Visiting english documents, say manuals to some computer related stuff like
elisp.dvi, searching for keywords works fine. Searching in documents in which
extensive use of accents and funny characters is made works too, but requires
some luck and/or experience in how \TeX\ acts on such things.

{\bf Example:}
Take the file story.tex from the \TeX book, chapter 6, page 24.  It contains
the line

\hglue3em \verb+galaxy called \"O\"o\c c+

The text-string build from the corresponding story.dvi will therefore contain

\hglue5em \verb+galaxycalled"O"oc+

%\medbreak
\smallbreak
So you can search for {\em str\/}  getting as result {\em ans\/}

\smallbreak\hglue3em
\begin{tabular}[t]{@{\unskip\tt}lc}
\hskip0pt plus 1fil\rm\em str &    \em ans       \\[.5ex]
%\hline
galaxy                &      found       \\
galaxycalled          &      found       \\  
galaxy called         &    not found     \\
\verb+d"+             &      found       \\
galaxy.\verb+*"O"+oc  &      found       \\
Ooc                   &    not found     \\
\end{tabular}

\kitem{\key{r} Re-read current \verb+.dvi+file and re-draw screen}

When the argument \verb+*+ is given, re-read the font-files too.

\kitem{\key{d} Load/kill \verb+.dvi+file}

After typing \key{d} you may select between \key{l} to load a
\verb+.dvi+file and \key{k} to kill a \verb+.dvi+file.
      
Loading a \verb+.dvi+file: 

tmview will look for a file-bookmark belonging to that file. If there is one,
it becomes the current file-bookmark. The \verb+.dvi+file will be shown as
left, and any defined manual-bookmarks are accessible by
\key{w}. When loading a \verb+.dvi+file for the first time, a new
file-bookmark will be created.  This will be set up with default values from
the command-line options and won't contain any manual-bookmarks.

Killing a \verb+.dvi+file: To kill a \verb+.dvi+file means to kill it's
file-bookmark and any related manual-bookmark. Killing a \verb+.dvi+file won't
hurt the file itself.  You don't have to kill a \verb+.dvi+file just to load
another one.
    
\kitem{\key{q} Quit tmview }
    
When quitting, a startup-file will be written. When running tmview next time,
you will find almost everything as you left it.

\section[The startup-file]{Customizing tmview -- The startup-file}

The following explains the contents of the startup-file which is used to set up
tmview. When the startup-file is not set read-only, tmview writes down a
startup-file every time you quit tmview. If no startup-file can be found, a new
one will be created.
Hence the list of bookmarks resp. visited files will keep growing, as long as
you don't explicitly kill them with \key{d}\,\key{k}.  Since also command-line
options are kept in the startup-file you are not able to reset any nonsense by
quiting/restarting tmview (which is not necessary anyway because you can reset
everything from inside tmview using the {\em magic argument\/}). If you are
trying out funny command-line options which you don't want to creep into your
startup-file, just set the startup-file read-only -- or call tmview with
\verb*+-s +. Although there are great
chances to get a lot of nonsense into your startup-file, there are two good
reasons to make tmview remember all the above mentioned information:\footnote{I
designed this feature -- no wonder I like it.}


1. You are working on a major \TeX\ project, creating a huge document. 
This will take some days, and you still turn the system off now and then. 
You want tmview to remember all the bookmarks you have set in your document,
the unusual papersize, the paths to special fonts used nowhere else, a.s.o. 
Since this kind of information is tied to your document, call tmview
with \verb+-sMyDoc.tmv+. So the tmview related settings on that project
will be kept in \verb+MyDoc.tmv+ and won't disturb your standard startup-file
in \verb+~/.dvisvga+. 

2. You are using tmview as a viewer of serveral manuals.
This is similar to the above. Every once in a while you should save the
current startup-file, to prevent loosing the valueable information
(=bookmarks) by accident.

However, as mentioned above, you might one day end up in a somehow ugly large
or even corrupted startup-file. The easy way out is to remove the
startup-file, call tmview with suitable standard-options and thereby get a new
startup-file. In case you want to copy some of the information contained
in the old startup-file to the new one, the internal structure of the
startup-file will be explained by the following example startup-file:
\begin{verbatim}
# **** this is an example startupfile of tmview *****
#
#
# basic rules:
# 1. all charakters from a '#' to the end of a line are ignored.
# 2. spaces, tabs and newlines act as separators.
# 3. a symbol starts with a letter, consists of letters and digits,
#    and ends at the next separator.
# 4. a string starts just after a '"' and ends just befor the next '"'.
#    exeption: to get a string containing a '"' type  '""'.
# 5. a number starts with '+' '-' '.' or a digit and must look like
#    numbers look like, i.e. no two '.' and so on.
# 6. a value is a list of strings and/or numbers separated by separators.
# 
# The purpose of the startup-file is to set symbols to values. This is done
# by typing the symbol followed by a value (separated by ... guess ...)  
# Therefore a number of valid symbols are defined, each expecting some
# kind of value. If a valid symbol is not set in the startup-file, a
# default value is used. You may therefore remove any suspect setting from
# your startup-file.

# most important: the symbol sufp
# Set the startupfile.
# Setting sufp sets the name of the file
# to write startup information when quitting tmview.
# Not setting sufp prevents writing a startup-file at all.
# Setting sufp to some other file prevents overwriting the current 
# startup-file, while still saving newly generated bookmarks a.s.o.
  
sufp "/home/thomas/.dvisvga"

# now set the commandline-options ...

hoff  25.40  # -h(hoff) 
voff  25.40  # -v(voff)
papx 210.00  # -p(papx)x(papy)
papy 297.00
xres 300     # -r(xres)x(yres)
yres 300
tfmp "./:/usr/lib/texmf/fonts/tfm//:/usr/lib/texmf/fonts//"     # -t(tfmp)
vffp "./:/usr/lib/texmf/fonts/vf//:/usr/lib/texmf/fonts//"      # -g(vf)
ffor "@N.@Mpk"                                                  # -n(ffor)
fntp "./:/usr/lib/texmf/fonts/tmp/pk//:/usr/lib/texmf/fonts//"  # -f(fntp)
disx 640     # -d(disx)x(disy)
disy 480
nmag 0       # -m(nmag)
lrnd   4.00  # -k(lrnd);(rrnd);(ornd);(urnd)
rrnd   4.00
ornd   4.00
urnd  12.00

#other defaults 

verb 0      # 'verb 1' makes tmview a bit more verbose

# file-bookmarks and manual-bookmarks
#
# The symbol fmk starts the definition of a file-bookmark. 
# It is followed by the name of the file as a string and lots
# of other values. Manual-bookmarks, belonging to a file, have to follow
# immediatly, starting with the symbol bmk. This results in blocks
# starting with fmk and ending just before the next fmk, containing
# all the information related one DVIfile.
# 
# You may either delete some of the lines starting with bmk to get rid
# of those bookmarks. Or you may delete all the lines beloning to one
# file-bookmark, including the manual-bookmarks that follow. Be sure
# not to leave some of the related manual-bookmarks, when deleting
# a file-bookmark.
# You may either copy a file-bookmark only, or copy a file-bookmark together
# with the related manual-bookmarks from another startup-file.
 
# one block, containing 3 manual-bookmarks
fmk "/home/thomas/cc/tmview/asmith.dvi" 210.00 297.00  25.40  25.40 105.00 
148.50   4.00   4.00   4.00  12.00 0 1 -7 389  3.000  
bmk 3 1 -7 517  3.000 
bmk 1 1 -7 261  3.000 
bmk 2 1 -7 389  3.000 

# another block, not containing manual-bookmarks at all.
fmk "/home/thomas/cc/tmview/tmview/dort.dvi" 186.10 276.78  17.19   8.89   
186.10 261.37   4.00   4.00   4.00  12.00 0 3 -163 -120  7.000  

# end of example startup-file
\end{verbatim}

\section[Copying]{Copying tmview -- rights and lefts}

The code of tmview uses some rather basic ideas stolen from xdvi. This
includes some few lines of code just copied. The author of xdvi is Eric
Cooper. In a similar kind, tmview's code depends on some lines of dvidjc,
written by Wolfgang R. Mueller. The hyper-TeX related parts are taken from
xhdvi, written by Arthur Smith. The sources of the above can be found on the
CTAN. So by having mentioned the authors here, and giving a reference how to
get the original sources, this should not be a violation of their copyrights.
 
As far as I am concerned, tmview may be modified or distributed without any
restrictions. tmview is distributed in the hope that it will be useful, but
without any warranty.
\end{document}