%************************************************************************
%* Filename: DVIMOTIF.TEX                                               *
%* Funktion: Report on porting DVIDECW to OSF/MOTIF                     *
%************************************************************************

\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 DVIMOTIF}}
\def\tp{\TeX-Preview}
\def\om{{\it OSF/Motif}}

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

\begin{document}

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

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

\begin{flushright}
DVI-Driver for \om
\vskip200pt
\Huge \bf DVIMOTIF
\vskip20pt
\normalsize Porting Report\\
            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{\dv\ release notes}
This is the first version of {\it DVIDECW} destined to run under the
new \om\ Graphical User Interface (GUI). The program itself was renamed to
\dv, the command file TEXVIEW.COM was renamed to TEXVIEWM.COM, the
command file DVIDECW.COM was renamed to DVIMOTIF.COM and the command
file DVILINK.COM was renamed to DVILINKM.COM. Installation and Operation
should be very similar to the \dw\ Version of the \tp\ software, more
information can be retrieved from the Installation and User's Guide
section of this document. However, be aware that there might be still
changes in the \om\ system software, so this program is provided on an
'as is' basis. Everyone is encouraged to work with this version, any
bug reports are greatly appreciated. \dv\ is based on the field test (DXM\_BL1) 
version of the DEC \om\/-Toolkit, I will try to adapt it to newer versions
when I can get hold of them.

The provided version of \dv\ has all required libraries linked with it 
instead of using shareable libraries, so the executable program size is
very large.

\section{Porting {\it DVIDECW} to \om}
\subsection{Introduction}
The basic idea behind this program port was to find out how easy and
straitforward it can be to port existing software written under the
\dw\ GUI to \om. The goal was to perform as little
work and modifications as neccesary to port the program source code
successfully to the \om\ environment. This is an important goal bearing
in mind that not all software which has been written under the \dw\ GUI
is so small and easy to comprehend as DVIDECW. So an approach using the
automatic conversion tools provided by DEC was the way to proceed.

Before I was able to start the conversion project, these things were
essentially required:
\begin{itemize}
\item DIGITAL's \om\/-Toolkit software (field test) which consists of libraries, bindings,
an UIL-Compiler, the \om\ window manager, sample programs and porting tools
\item DIGITAL's \om\/-Toolkit documentation
\end{itemize}
Before the actual work can start, the command
procedure DXM\_LOGICALS.COM has to be executed. It defines all neccesary
symbols and logical names required to work with the \om\/-Toolkit. As a
side-effect, some previous defined symbols and logical names required
for the \dw-Tookit are superseeded, they have to be re-initialized
in order to continue work on \dw\ projects.

\subsection{Using the porting tools}
Within the \om\/-Toolkit software is a collection of porting tools and
a command procedure DXM\_PORT.COM to call each of these tools. I converted
both my .UIL and my .C file by executing {\tt \@ dxm\_port <source path> 
<dest path>}.
After this, nearly all logical names, types and procedure entries were
automatically transferred to the corresponding \om\/-calls. As described
by the documentation, some portions of the original coding where flagged
with {\tt '>>>> Developer decision'} or {\tt '>>>> Motif transition'} 
texts indicating
that some manual work had to be done there. 
 
\subsection{Adapting the UIL-File}
First, it turned out to be critical to use names like 'OK', 'Cancel' or
'Quit' because they are partly converted by default to a wrong type
or a type cast is set on these names. This occured in my UIL-File
within the {\sf GotoPageDlg} dialog box with its 'OK' button. This resulted in
an UIL-Compiler error, the message was {\tt 'nested instructions issued'}
with no line number where this error occured. This can be very nasty with
larger UIL files, so better check for special names.

In some objects, the {\tt X} argument in the {\tt arguments} section was
not automatically converted to {\tt XmNx}.

All {\tt XmInformationDialog}
widgets as created by the porting utilities had to be renamed to 
{\tt XmMessageDialog} widgets, the {\tt XmLabelString} argument had to
 be renamed to {\tt XmNmessageString}. In all {\tt XmBulletinBoardDialog}
definitions, the {\tt XmNtitleString} had to be converted to 
{\tt XmNdialogTitle} and the {\tt take focus} argument had to be
ommited. Any occurence of {\tt XmNlabelString} within a {\tt XmPushButton}
widget is acceptable, the {\tt '>>>> Developer decision'} flag could be cancelled.
All marked {\tt XmNactivateCallback} functions within the menu bar definition
were right, the {\tt '>>>> Developer decision'} flag was removed here too.

In the {\sf GotoPageDlg} dialog box, the {\tt accept\_focus} argument of \dw\ had 
to be removed, some of the size dimensions of this dialog box had to
be adjusted. The {\tt XmNdialogStyle} argument was added to the definition.

Some modifications were neccessary in the {\sf MainWindow} definition. It was
impossible to take over the scrollbar definitions used in the \dw\ version
of the program. Instead, the required width and height had to be 
supplied by means of the {\tt XmNheight} and {\tt XmNwidth} arguments and the
{\tt XmNscrollingPolicy} argument had to be set to zero. All scrollbar definitions
and references were deleted and the width and height arguments had to
be defined in the {\tt XmDrawingArea} widget too, an extra 
{\tt XmNcreateCallback} definition had to be added there. Generally speaking, 
\om\ has a more automatic approach towards scrollbar handling.

\subsection{Adapting the C-File}
Due to the changes in the {\sf MainWindow} definition (namely scrollbars),
all related procedures in the .C file had to be modified. The {\it scrollbar}
callback procedure was fully deleted, in the {\it output-exposed} callback procedure
all code related to the resizing of the main window and the updating of
the scrollbars was removed, instead the {\tt XmDrawingArea} size is adjusted
according to the zoom range. \om\ itselfs takes care of window content's 
scrolling if the actual window is smaller than the size of the
drawing area widget. Unfortunately, there is no chance of controlling
the scrollbar's positions and size, so moving the \TeX\ page with the
{\sf Move} menu commands wont be reflected in the scrollbars!

Additional code was written in the {\tt devinit()} procedure to set 
the drawing area size, all string creation routines where converted
in the right way but were flagged by the conversion tools, these flags
were deleted. 

All coding regarding the {\sf Copy} operation of the {\sf Edit} menu had
to be revised to be compatible with \om. 
 
\subsection{General problems}
There were some general problems which turned up while working with
the \om\ window manager. If the {\sf Close box} of any window is clicked, the
program will crash. This is extremly bad if the crashed program is the
\om\ window manager. A program crash also occurs if the Eve editor's window is maximized
using either the System command menu or the maximize button.

In the preliminary documentation, no hints are given which actual 
{\tt \#include} files are required for a specified UIL-object. The same is
true with all the other include files supplied with the toolkit, a
general guideline or instructions which file to include would be greatly
appreciated as the conversion utilities do not provide any hints. 

There was no description of available formats for the copy to clipboard
functions. The only information is a reference to another document, which
I did not get so far. Currently, the format is named {\tt XYBitmap}, but it
was impossible to paste any clipboard contents to another application.

\section{Installation of \dv}
\dv\ itself can be installed after the command file TEXVIEWM.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>texviewm.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 
\om\ 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{DVIMOTIF.COM}
Command file to compile/link \dv
\begin{verbatim}
$ !-------------------------------------------------------------------!
$ ! Filename: DVIMOTIF.COM                                            !
$ ! Function: Compiles and links the DVIMOTIF application             !
$ ! (c) 19-06-90 by Ch. Markus                                        !
$ !-------------------------------------------------------------------!
$ !
$ ! Define symbols for OSF/Motif toolkit
$ !
$ @$disk1:[1050101]dxm_logicals.com
$ !
$ ! 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 packg. 
$ ! 
$ ! Defines which rely on system symbols set previously (partly
$ ! defined in DXM_LOGICALS)
$ !
$ define/nolog C$INCLUDE -
"DEC$KIT$XT:",-
"DEC$KIT$XM:",-
"DEC$KIT$DXM:",-
"DEC$KIT$UIL:",-
"DEC$KIT$MRM:",-
"SYS$LIBRARY:",-
"SYS$COMMON:[DECW$INCLUDE]",-
"dvi$decw:",-
"dvi$beebe:"  
$ define/nolog vaxc$include c$include
$ define/nolog X11 decw$include
$ define/nolog sys sys$library
$ define/nolog uil$include dec$kit$uil
$ !
$ ! General checkup of old errors
$ !
$ on warning then goto error
$ ! 
$ !
$ ! Compile the 'C'-Source to 'OBJ'
$ !                             
$ if f$search("DVIMOTIF.C") .eqs. "" then goto compile_uil
$ !
$ vue$set_task_label "CC DVIMOTIF"
$ vue$popup_progress_box
$ cc /define="_MOTIF" /define="DEC_MOTIF_EXTENSION" - 
  /define=("OS_VAXVMS"=1) /define=("ANSI_LIBRARY"=1) dvimotif  
$ !
$ !
$compile_uil:
$ !
$ if f$search("DVIMOTIF.UIL") .eqs. "" then goto do_link
$ !
$ ! Compile the 'UIL'-Source to 'UID'
$ !
$ vue$set_task_label "UIL DVIMOTIF"
$ vue$popup_progress_box
$ uil dvimotif.uil
$ !
$do_link:
$ !
$ ! Link the DEC-Windows program
$ !
$ vue$set_task_label "LINK DVIMOTIF"
$ vue$popup_progress_box
$ !
$ link /exe=$disk2:[1050101]dvimotif.exe -                   
 sys$input:/options
 dvimotif.obj
 unixclib/lib
 dec$kit$mrmlib/lib
 dec$kit$dxmlib/lib       
 dec$kit$xmlib/lib        
 dec$kit$xtlib/lib
 sys$library:decw$xlibshr/share         
 sys$library:vaxcrtl/share
 dec$kit$xm:clib/lib
$ ! 
$ !
$ ! Change APPLY button to UPDATE button on FileView
$ !
$ vue$highlight_update
$end:
$ exit
$ !
$error:
$ vue$set_error_status
$ exit
\end{verbatim}
\subsection{DVILINKM.COM}
Command file to link \dv
\begin{verbatim}
$ !-------------------------------------------------------------------!
$ ! Filename: DVILINKM.COM                                            !
$ ! Function: Links the DVIMotif OSF/Motif application (neccesary if  !
$ !           DVIMotif 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) 08-06-90 by Ch. Markus                                        !
$ !-------------------------------------------------------------------!
$ !
$ @$disk1:[1050101]dxm_logicals.com     
$ !
$ vue$set_task_label "LINK DVIMOTIF"
$ vue$popup_progress_box
$ !
$ link /exe=$disk2:[1050101]dvimotif.exe -                    
 sys$input:/options
 dvimotif.obj
 unixclib/lib
 dec$kit$mrmlib/lib
 dec$kit$dxmlib/lib       
 dec$kit$xmlib/lib        
 dec$kit$xtlib/lib
 sys$library:decw$xlibshr/share         
 sys$library:vaxcrtl/share
 dec$kit$xm:clib/lib   
$ ! 
$ !
$ ! Change APPLY button to UPDATE button on FileView
$ !
$ vue$highlight_update
$ exit
\end{verbatim}
\newpage
\subsection{TEXVIEWM.COM}
Integration of \dv\ in {\it FileView} menu bar
\begin{verbatim}
$ !-------------------------------------------------------------------!
$ ! Filename: TEXVIEWM.COM                                            !
$ ! Function: This is the interface between OSF/Motif FILEVIEW and the!
$ !           DVIMOTIF Tex Preview driver which runs in the OSF/Motif !
$ !           environment. Fileview selections are scanned and passed !
$ !           in the command line.                                    !
$ ! (c) 19-06-89 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.dvimotif] !path for .UID file
$ dvimotif := $$disk2:[1050101]dvimotif             !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 "DVIMOTIF ''filename'"
$ vue$popup_progress_box
$ !
$ dvimotif 'filename' 'parameter'
$ !
$end:
$ exit
\end{verbatim}
\newpage

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

\end{document}

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

