⟦6b1d28985⟧

TextFile

\texx\ is a previewer that uses the X-11 window system.
\texsun\ is a previewer that uses the SunView window system.
Both previewers allow you to
view documents on your workstation before printing them.
Everything in the following
description applies to both \texx\ and \texsun\ unless
otherwise stated.
{\footnotesize \em Editorial note: this section is mostly Grunwald's
and has not been updated recently
save for minor editing by Torek.}

\subsection{Painting}
When you start \texx\ or \texsun,
a window will be created on your display\footnote
{The interaction for this depends on your window manager.}
and your document will be {\em painted} in that window.
The size of the window corresponds to the size of the tallest and widest
page of your document.
If your display is wide enough, the window will have two {\em leaves},
otherwise it will have a single {\em leaf}.
Each leaf will be painted with a page from your document.

The previewers take some pains
to provide the most viewable document possible.
Omitting the margins---including both the standard one inch margin
and any other white space \TeX\ or \LaTeX\ may have added---may
produce a more readable preview.
If so, this happens automatically.
You may find it advantageous to use smaller document sizes
(increasing the omittable margins)
when formatting for previewing,
just to enhance this effect.

\subsection{Shrinks}
The resolution of most workstation screens
is well below that of most printers.
An exact image of what goes on the paper simply cannot be shown.
Something has to go.

One solution is to generate the \TeX\ fonts
at your workstation display resolution.
This requires at least two sets of fonts,
one for your printer and one for your display.
Another approach is to use the printer's fonts,
but {\em shrink\/} them.
This is what \texx\ and \texsun\ do,
because it reduces the number of fonts
and works with more display resolutions
while still allowing the option of using workstation-specific fonts.

Fonts are shrunk by a {\em shrink factor},
which is an integer in the range of 1 to 9.
For example, with a shrink factor of 4,
a 4 by 4 set of pixels
becomes a single pixel on your display.
The pixel is turned on if $1/\mbox{\em blackness}$ pixels
in the original sample were turned on.
Normally, {\em blackness\/} is $3$,
which was chosen by trial and error,
but it can be set using the {\tt -bl} option or by setting the
{\tt Blackness} option in your defaults file.
A shrink factor of 1 is a direct view of the fonts at the font resolution.

There are usually two goals to previewing documents.
One is to view the {\em overall structure\/} of the document:
to check that tables, equations and figures appear at the right location,
pages break where they should,
and so forth.
Another is to check {\em detail structure}, e.g.,
whether the spacing around an equation looks right.
The previewers provide both a {\em normal shrink\/} and a
{\em large shrink\/} view of your document.
At the normal shrink size, an entire page is visible, providing an
overall view.
At the large shrink size, details are more visible, although the entire
document is not.

\subsection{Differences Between \texx\ and \texsun}
When documents are being painted, the cursor icon for \texx\ changes to a
clock, indicating that you need to wait for the painting to finish.
For \texsun, the cursor changes to an hourglass.
When \texx\ is waiting for input, the cursor changes to a spraycan.
When \texsun\ is waiting for input, the cursor changes to a bulls-eye.

Unless the \texx\ window is {\em obscured\/} by another window,
the image is painted directly to the display.
If the \texx\ window is {\em obscured\/} by another window,
the image is painted to a {\em pixmap}, which is displayed when the
page is painted.
{\em Warning:
You should only obscure the \texx\ window when the cursor is
a spraycan, not when it is a clock.}
If the window is covered or obscured while it is being painted, the
final image will not be correct.
However, if you obscure the window (e.g., overlay it with a
window for editing your document) while the spray scan is present,
the window will be correctly painted when you turn pages.
If you resize the window, \texx\ will repaint it,
but will not take advantage of any new space.

\texsun\ is somewhat more flexible.
Pages are painted directly to memory, and displayed when they are painted.
You can obscure the \texsun\ window at any time.
You can also enlarge the window.
While this will not change the amount of visible text for the
normal shrink size, the entire window will be used to display the
detail view.

\subsection{Moving Around}
In both \texx\ and \texsun,
you move forward in your document by hitting
the {\tt RETURN} or {\tt NEWLINE} key.
If there is a single leaf, it will be erased and painted with the next page.
If there are two leaves, the right hand page will be put on the left leaf
and the right leaf will be painted with the next page.
In other words, hitting return turns the page.
To move backward in your document, hit the {\tt DELETE} or {\tt BACKSPACE} key.
If you type a number before hitting a key, you will move forward or backward
that number of pages.
To move to a given page, type the number of the page and then `{\tt g}'.
To quit \texx, type `{\tt q}'.

To view a part of your document at the large shrink size,
point the cursor at the part you are interested in and hit any mouse button.
The spraycan or bullseye will change to a clock or hourglass
while the page is painted at the larger size.
Since the entire page will not fit on the display at the larger size,
only the part to which you pointed is displayed.
If your window has a single leaf, that leaf is overwritten with the
enlarged image.
In \texx,
if your window has two leaves, the enlarged image is painted
on the leaf to which you were {\em not} pointing.
This allows you to see the overall structure and the detail at the same
time.
In \texsun, the entire window is always used.

If you move the mouse as you hold down the button,
the enlarged page will move past the view window, allowing you
to pan over your document.
In \texsun, the display is not updated until the mouse is inactive
for a period called the `settle time'.
This time can be specified in seconds using the {\tt -settle} flag;
the default value is an eighth of a second.
It is also possible to set the `significant distance' for mouse movements
to avoid a large number of screen updates caused by `flutter fingers'.
If the mouse is moved from the last resting point by
less than the significant distance, the display is not redrawn.
The significant distance can be set using the {\tt -signif} flag.
The argument is the percentage of movement in the large document
which should be considered significant for a redisplay.
The default value is one percent.

When you release the mouse button,
the page that was previously displayed
on the overwritten leaf is restored.
If you point to another spot on the same page, the enlarged page will not
need to be recomputed.
The previewers remember the enlarged page as long as the normal sized page
is visible, i.e., if you turn forward several pages, and then back up,
you will have to wait again to see the detail view.

\subsection{Options}
The previewers
allow you to control the layout of the window,
using either the command line
or the window system's default-value system.
Tables~\ref{tab:texx-options} and~\ref{tab:texsun-options}
list the options for \texx\ and \texsun\ respectively.
To preview the file {\tt myfile.dvi},
run {\tt texx myfile} (or {\tt texsun myfile});
the {\tt .dvi} suffix will be supplied automatically.
The previewer makes a copy of the \dvi\ file,
allowing you to reformat your document while viewing other portions.
%
\begin{table*}
\centering
\begin{tabular}{|@{\coltt}l|c|c|p{2in}|}
\hline
\rm XDefault & Command Line & Argument Type & Meaning \\
\hline
ReverseVideo & \tt -rv & none & Display document in reverse video \\
BorderWidth & \tt -bw & integer & Set the width of the window border \\
ForeGround & \tt -fg & color & Set the foreground color \\
BackGround & \tt -bg & color & Set the background color \\
HighLight & \tt -hl & color & Set the highlight color \\
Border & \tt -bd & color & Set the border color \\
Mouse & \tt -ms & color & Set the mouse color \\
NormalShrink & \tt -ns & integer & Set the shrink for the overview display \\
LargeShrink & \tt -ls & integer & Set the shrink for the detail display \\
Blackness & \tt -bl & integer &
	Set the blackness threshold for shrunken fonts \\
Leaves & \tt -l & integer & Set the number of leaves (1 or 2) \\
TopMargin & \tt -tm & float & Set the top margin in inches \\
SideMargin & \tt -sm & float & Set the left side margin in inches \\
Dpi & \tt -dpi & integer & Set the desired font resolution in dots per inch \\
\hline
\end{tabular}
\caption{Options for \texx}
\label{tab:texx-options}
\end{table*}
%
\begin{table*}
\centering
\begin{tabular}{|@{\coltt}l|c|c|p{2in}|}
\hline
\rm Default & Command Line & Argument & Meaning \\
\hline
ReverseVideo & \tt -rv & none & Display document in reverse video \\
NormalShrink & \tt -ns & integer & Set the shrink for the overview display \\
LargeShrink & \tt -ls & integer & Set the shrink for the detail display \\
Blackness & \tt -bl & integer &
	Set the blackness threshold for shrunken fonts \\
Leaves & \tt -l & integer & Set the number of leaves (1 or 2) \\
TopMargin & \tt -tm & float & Set the top margin in inches \\
SideMargin & \tt -sm & float & Set the left side margin in inches \\
SettleTime & \tt -settle & float &
	Set the mouse tracking settle time in seconds \\
SignificantDistance & \tt -signif & float &
	Set the significant distance for mouse tracking
	as a percentage of the large document size \\
AutoReload & \tt -autoReload & none &
	Automatically reload the file when the window is exposed or opened \\
Dpi & \tt -dpi & integer & Set the desired font resolution in dots per inch \\
\hline
\end{tabular}
\caption{Options for \texsun}
\label{tab:texsun-options}
\end{table*}

\subsection{Remembering Where You Were}
Currently, this section applies only to \texsun.

Since the normal use of \texsun\ involves the repeated viewing of a document
to fix formatting problems,
it would be nice to be able to return to the page you were viewing when
you left \texsun.
One way to do this is to {\em reload\/} the document you are viewing.
However, if you freak out after too much editing and run off for some
crumpets or something,
it would be nice to have \texsun\ itself remember where you
left off.

If you define the environment variable \verb|TEXSUN_STATE| as the name
of a file, a {\em viewing state\/} will be written to that file when you
exit \texsun.
The next time you start \texsun, this state will be added to your list of
command-line arguments before any other argument.
This allows you to override the saved state.
If the first argument is {\tt -new}, the saved state is ignored.

If you use an absolute path name for \verb|TEXSUN_STATE|,
you can invoke \texsun\ from a menu, but all your previewer
sessions will use the same state file.
Choosing a relative path name (e.g., {\tt ./.texsun-state}) lets
you have a state file for each directory, but it is
difficult to convince the SunView environment to start a
tool in a given directory.

\subsection{Reloading your document}
Since the normal editing cycle, crumpets notwithstanding, is to edit, format,
view, and edit again, you can {\em reload\/} your document without restarting
the previewer.
One way to do this is to hit {\tt R} while viewing the document.
If you are using a Sun,
you can use the somewhat more civilized \key{again} key.
Someday, all of this will use menus.

\subsection{Odds and Ends}
\texsun\ has had a bit more development put into it, mainly because it gets
more use. \texsun\ understands the \key{open} and \key{expose} buttons.
The \key{again} button reloads your document.
The \key{delete} button removes the window.
The \texsun\ banner displays the {\em document size\/} in inches.
This is the size of the document you see on your display if it were
actually printed.

If you have free time,
here are a few things you could add to either \texsun\ or \texx.
First, it would be nice if \texx\ and \texsun\ had equivalent user interfaces.
This simply involves a little hackery to \texx.
Other useful widgets would be
\begin{itemize}
\item	An optional ruler to the right of the first page and across the bottom
	of each page. This would make alignments and tweaking much easier.
\item	Menus instead of key presses.
\item	A (menu selected) list of information about your document.
\item	Support for shaded areas in \texx.
\item	A font shrinking method which does a bit more anti-aliasing.
\end{itemize}

If you make improvements,
please tell the world and send the improved code to
the authors.
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦6b1d28985⟧ TextFile

Derivation

TextFile
