%************************************************************************
%* Filename: DVIDOC_E.TEX                                               *
%* Funktion: Installation/User's Guide in ENGLISH                       *
%************************************************************************        

\documentstyle[11pt]{article}
%macropackage=lplain

%************************************************************************
%* Einige Seitendefinitionen                                            *
%************************************************************************

\oddsidemargin=0.1 true in
\evensidemargin=0.1 true in

\marginparwidth=.08 true in
\marginparsep= .01 true in

\textwidth= 5.7 true in

\topmargin= 1pt
\textheight=8.5 true in

\headsep=0pt

\parindent 0pt
\parskip=5pt plus 2pt minus 1pt

% \setlanguage{\german}
\frenchspacing
\sloppy

%************************************************************************
%* Abk�rzungen                                                          *
%************************************************************************

\def\dw{{\it DECwindows}}
\def\dv{{\it DVIDECW}}
\def\tp{\TeX-Preview}

%************************************************************************
%* Anfang des Dokuments                                                 *
%************************************************************************

\begin{document}

%************************************************************************
%* Titelseite                                                           *
%************************************************************************

\setcounter{page}{0}
\thispagestyle{empty}

\begin{flushright}
DVI-Driver for \dw
\vskip200pt
\Huge \bf DVIDECW
\vskip20pt
\normalsize Installation Guide\\
            User's Guide
\vskip60pt
\normalsize \today
\vskip30pt
\large      Christian Markus\\
            Fahrenkr\"on 124\\
            D-2000 Hamburg 71\\
            Fed.Rep.of Germany\\
\normalsize Tel.: (040)-643\,21\,73
\vskip20pt            
\large      FB Informatik\\
            Universit\"at Hamburg\\    
\normalsize Email: 
            {\tt markus@rz.informatik.uni-hamburg.dbp.de}    
\vskip50pt
\end{flushright}
\newpage

%************************************************************************
%* Inhaltsverzeichnis                                                   *
%************************************************************************

\tableofcontents
\newpage

%************************************************************************
%* GUIDE Installations/Bedienungsanleitung                              *
%************************************************************************

\section{Installation of \dv}
\dv\ itself can be installed after the command file TEXVIEW.COM is 
modified to suit the system paths of the local \TeX installation. 
Please perform the following steps to do so:
\begin{itemize}
\item in {\it FileView}, select the {\sf Customize/Verbs and Menus} option
\item enter {\tt TeX Preview} below the 'verb names' box as a new name and
click on the 'Enter' button to accept it
\item enter the required DCL command for the \tp\ entry, e.g.
{\tt \@<path>texview.com}, then click on the 'Enter' button
\item select 'Applications' from the  'Menu Names' box and click on 
'Add' below the 'Verbs in menu' box
\item click on the 'Apply' and 'Ok' buttons to install the entry into
the menu bar.
\item in {\it FileView}, select the {\sf Customize/File Types} option and
install the {\tt .DVI} file type
\end{itemize}

\section{Operation of \dv}         
\subsection{Invocation of \dv}
\subsubsection{Starting from {\it DECTERM}}
Enter command name, options and filename as described in \cite{dvixxx} within
the {\it DECTERM} window.

\subsubsection{Starting from {\it FileView}/{\it DCL Command Window}}
Create a {\it DCL Command Window} by clicking on 
{\sf Utilities/DCL Command Window} in {\it FileView}. Enter command name, 
options and filename as described in \cite{dvixxx}.

\subsubsection{Starting from {\it FileView} menu bar}
If the installation of \dv\ was done properly, \dv\ can be started by
choosing the {\sf Applications/TeX Preview} option from the {\it FileView}
menu bar. A dialog box will appear and ask for the filename to be
processed, after clicking on the 'OK' button a second dialog box will
appear and ask for processing options.

\subsubsection{Starting by double-clicking within {\it FileView} window}
If the installation of \dv\ was done properly, \dv\ can be started by
double-clicking on any DVI-file (Filename has the extension {\tt .DVI}).
A dialog box will appear and ask for processing options.

\subsubsection{Remarks}
\dv\ offers the same options as the Beebe {\it BBN Bitgraph}-driver.
However, it ignores the {\tt -o} option (order pages) and will only
display the first page (Default: 1) given in the {\tt -o} option . 
All other options conforms to the description of N.F.Beebe's driver
family \cite{dvixxx}.

\dv\ initially operates with 69 dpi fonts which permit a full page
preview in all formats. The option {\tt -m1} (as well as zooming from
the menu bar) uses 83 dpi fonts which are quite readable and allow a
full page preview in most cases (if offsets are disabled).

During page creation \dv\ writes status reports to the 
\dw\ standard output window. These status reports (and the creation of a
standard output window) can be suppressed by entering the {\tt quiet} option
({\tt -q}) in the processing options dialog box. This will switch to quiet
mode which only writes error messages to the standard output window.

After invocation \dv\ creates a window with a menu bar (for interactive
commands) and two scrollbars. The window title bar contains information
about the current page and resolution.

If the 'TeX Preview' is active (it has the {\it Input Focus}), some of
the menu bar options can be operated with keyboard shortcuts which 
correspond to those defined by Nelson F. Beebe in \cite{dvixxx}. To give
the {\it Input Focus} to the 'TeX Preview' window, just click with the 
mouse somewhere within the window area. All shortcut key combinations
are also displayed in the menu bar next to the option names.

\subsection{\dv\ menus}
\subsubsection{File-Menu}
\begin{itemize}
\item {\sf About \dv \dots}\quad will display a dialog box which 
contains information about the program version and copyrights.
\item {\sf Quit}\quad closes all \dv\-windows and terminates the
application.
\end{itemize}

\subsubsection{Edit-Menu}
\begin{itemize}
\item {\sf Cut}
\item {\sf Copy}\quad copies the window contents to the Clipboard
\footnote{The {\sf Copy} operation does not work in the current
version of \dv}
\item {\sf Paste}
\item {\sf Clear}
\item {\sf Select All}
\end{itemize}
The Edit Menu is implemented according to the standards defined in 
\cite{dwstyleguide}, but only the {\tt Copy} option is currently supported.

\subsubsection{Page-Menu}
\begin{itemize}
\item {\sf Previous}\quad switches to the previous page
\item {\sf Next}\quad switches to the next page
\item {\sf Goto\dots}\quad opens a dialog box, where a page number
can be entered. After clicking on 'OK' or 'GO', the selected page will
be displayed.
\item {\sf Zoom in}\quad magnifies the current page (by one \TeX\  
magstep)
\item {\sf Zoom out}\quad reduces the current page (by one \TeX\ 
magstep) 
\item {\sf Top of Page}\quad moves window contents to top of page
\item {\sf Bot of Page}\quad moves window contents to bottom of page
\end{itemize}

\subsubsection{Move-Menu}
\begin{itemize}
\item {\sf Up}\quad moves window contents up
\item {\sf Down}\quad moves window contents down
\item {\sf Left}\quad moves window contents left
\item {\sf Right}\quad moves window contents right
\end{itemize}

\subsubsection{Options-Menu}
\begin{itemize}
\item {\sf No offset/Use offset}\quad deactivates/activates any offset
specified in the commandline
\item {\sf Fast move/Slow move}\quad switches between big/small move
distances
\item {\sf Reset position}\quad resets window position
\end{itemize}

\subsection{Dialog boxes}
\dv\  provides six dialog boxes:
\begin{itemize}
\item {\sf AlertNYI}\quad pops up, if an unimplemented program operation 
was selected by the user
\item {\sf About\dv\ }\quad shows information about the \dv\ program
version and copyrights
\item {\sf LastpageInfo}\quad is displayed, if a page beyond the last page
in the DVI file is selected
\item {\sf FirstpageInfo}\quad is displayed, if a page beyond the first page
in the DVI file is selected
\item {\sf ZoomrangeInfo}\quad pops up, if the zoom range is exceeded
\item {\sf Gotopage\_box}\quad provides the possibility to enter a page 
number, which is to be displayed next. This dialog box is of the 
'{\it modeless}' type and remains on the screen if the 'Go' button is 
clicked. If the 'Cancel' or 'Ok' buttons are clicked, this dialog box
will disappear. The 'Enter' key can be used instead of clicking the
'Ok' button.  
\end{itemize}


\newpage

%************************************************************************
%* Anh�nge/Literaturverzeichnis                                         *
%************************************************************************

\appendix

\begin{thebibliography}{9}
\bibitem{texbook}
        Knuth, Donald E. {\it The \TeX book}, Addison-Wesley, Menlo Park
        (California) 1989

\bibitem{dvixxx}
        Beebe, Nelson H.F. {\it DVIxxx - Display \TeX\ DVI Files on 
        Assorted Output Devices}, University of Utah, Salt Lake City (Utah)

\bibitem{dviprog}
        Beebe, Nelson H.F. {\it A \TeX DVI Driver Family}, University of
        Utah, Salt Lake City (Utah) 15.April 1987, Rev. 2.07

\bibitem{dwoverview}
        {\it Overview of VMS DECwindows}, Digital Equipment Corporation, 
        Maynard (Massachusetts) 1988

\bibitem{dwstyleguide}
        {\it XUI Style Guide}, Digital Equipment Corporation,
        Maynard (Massachusetts) 1989

\end{thebibliography}
\newpage

%************************************************************************
%* Listings                                                             *
%************************************************************************

\section{DCL-Command files}
\subsection{DVIDECW.COM}
Command file to compile/link \dv
\begin{verbatim}
$ !-------------------------------------------------------------------!
$ ! Filename: DVIDECW.COM                                             !
$ ! Function: Compiles and links the DVIDECW DEC-Windows application  !
$ ! (c) 19-06-90 by Ch. Markus                                        !
$ !-------------------------------------------------------------------!
$ !
$ !
$ if f$trnlnm("decw$include") .nes. "" then goto startupok
$ write sys$output "Invoke @DECW$STARTUP before using this procedure"
$ !
$startupok:
$ !
$ ! Defines which have to be adapted to system installation before
$ ! attempting to compile (will need modifications)
$ !
$ define/nolog dvi$decw $disk1:[1050101.includes] !modified .H files
$ define/nolog dvi$beebe $disk2:[dvi-beebe.dvi]   !standard .H files
$                                                 !from BEEBE package
$ ! 
$ ! Defines which rely on system symbols set previously (partly
$ ! defined in DECW$STARTUP)
$ !
$ define/nolog c$include dvi$decw,dvi$beebe,decw$include,sys$library
$ define/nolog vaxc$include c$include
$ define/nolog X11 decw$include
$ define/nolog sys sys$library
$ define/nolog uil$include decw$include
$ !
$ ! General checkup of old errors
$ !
$ on warning then goto error
$ ! 
$ !
$ ! Compile the 'C'-Source to 'OBJ'
$ !                             
$ if f$search("DVIDECW.C") .eqs. "" then goto compile_uil
$ !
$ vue$set_task_label "CC DVIDECW"
$ vue$popup_progress_box
$ cc /define=("OS_VAXVMS"=1) /define=("ANSI_LIBRARY"=1) dvidecw  
$ !
$ !
$compile_uil:
$ !
$ if f$search("DVIDECW.UIL") .eqs. "" then goto do_link
$ !
$ ! Compile the 'UIL'-Source to 'UID'
$ !
$ vue$set_task_label "UIL DVIDECW"
$ vue$popup_progress_box
$ uil dvidecw.uil
$ !
$do_link:
$ !
$ ! Link the DEC-Windows program
$ !
$ vue$set_task_label "LINK DVIDECW"
$ vue$popup_progress_box
$ !
$ link /exe=dvidecw.exe -                   
 sys$input:/options
 dvidecw.obj
 unixclib/lib
 sys$library:vaxcrtl/lib
 sys$share:decw$dwtlibshr/share
$ ! 
$ !
$ ! Change APPLY button to UPDATE button on FileView
$ !
$ vue$highlight_update
$end:
$ exit
$ !
$error:
$ vue$set_error_status
$ exit
\end{verbatim}
\subsection{DVILINK.COM}
Command file to link \dv
\begin{verbatim}
$ !-------------------------------------------------------------------!
$ ! Filename: DVILINK.COM                                             !
$ ! Function: Links the DVIDECW DEC-Windows application (neccesary if !
$ !           DVIDECW will run under a VMS version  other than 5.3)   !
$ ! Important:There will be a linker warning message for multiply     !
$ !           defined Symbols QSORT and SYSTEM, this can be ignored   !
$ ! (c) 21-03-90 by Ch. Markus                                        !
$ !-------------------------------------------------------------------!
$ !
$ !
$ vue$set_task_label "LINK DVIDECW"
$ vue$popup_progress_box
$ !
$ link /exe=dvidecw.exe -                   
 sys$input:/options
 dvidecw.obj
 unixclib/lib
 sys$library:vaxcrtl/lib
 sys$share:decw$dwtlibshr/share
$ ! 
$ !
$ ! Change APPLY button to UPDATE button on FileView
$ !
$ vue$highlight_update
$ exit
\end{verbatim}
\subsection{TEXVIEW.COM}
Integration of \dv\ in {\it FileView} menu bar
\begin{verbatim}
$ !-------------------------------------------------------------------!
$ ! Filename: TEXVIEW.COM                                             !
$ ! Function: This is the interface between DECWindow FILEVIEW and the!
$ !           DVIDECW Tex Preview driver which runs in the DECWindows !
$ !           environment. Fileview selections are scanned and passed !
$ !           in the command line.                                    !
$ ! (c) 19-06-90 by Christian MARKUS                                  !
$ !-------------------------------------------------------------------!
$ !
$ ! These definitions supersede global definitions and have to be 
$ ! corrected in other environments
$ !
$ define/nolog TEX_FONTS $DISK0:[TEX29.DVI.CM.]    !path for fonts
$ define/nolog TEX_INPUTS $disk1:[1050101.dvidecw] !path for .UID file
$ dvidecw := $$disk1:[1050101.dvidecw]dvidecw      !path for .EXE file  
$ ! 
$ ! Check if files are selected in FileView
$ !
$ vue$get_selection_count
$ vue$read count
$ !
$ ! If files are selected then go on processing
$ !
$ if count .ne. 0 then goto get_file
$ !
$ ! Ask for filename
$ !
$ vue$inquire_symbol "VUE$TEXVIEW_DVI Filename:"
$ vue$read selection  
$ !
$ ! Check for valid filename
$ !
$ if "''selection'".eqs. "" then goto end
$ goto do_dvi
$ !
$ ! Get Filename from FileView selection
$ !
$get_file:
$ vue$get_next_selection
$ vue$read selection
$ !
$ ! Start DVIDECW with filename argument
$ !
$do_dvi: 
$ ! 
$ ! Extract the filename from selection
$ !
$ filename= "''f$parse(selection,,,"NAME")'"
$ !
$ ! Check if file exists
$ !                             
$ if f$search("''filename'"+".dvi") .eqs. "" then goto end
$ !
$ ! Ask for processing parameter
$ !
$ vue$inquire_symbol "VUE$TEXVIEW Parameter:"
$ vue$read parameter 
$ !
$ ! Write info box
$ !
$ vue$set_task_label "DVIDECW ''filename'"
$ vue$popup_progress_box
$ !
$ dvidecw 'filename' 'parameter'
$ !
$end:
$ exit
\end{verbatim}
\newpage

%************************************************************************
%* Ende des Dokuments                                                   *
%************************************************************************

\end{document}

%************************************************************************

