rtsi.com/2014.01.www.rtsi.com.tar/www.rtsi.com/OS9/OSK/APPS/DVI_MGR/dvimgr_s.lzh/readme.osk

Text File | 1993-08-08 | 19KB | 429 lines

        This is the README file for the OSK/MGR TeX DVI-Previewer
       -----------------------------------------------------------

General
-------
  This is DVIMGR, a TeX previewer for OSK and the MGR window environment.
It is based on the TeX DVI-driver family developed by N.Beebe, Utah, USA.
DVIMGR again is based on the DECWindows version by Christian Markus (see the
original readme file 'readme.txt' for more details).  The basis for DVIMGR
is version 2.10 of N.Beebe's driver family.  I added a separate DVIMGR
version number in order to make different versions of this driver
distinguishable.

DVIMGR has been developed on the folowing platform:

 -  Eltec Eurocom 6  (68030/25MHz)  with
 -  IPIN Workstation module (16 colors)
 -  OSK v2.4.5
 -  MGR v1.3
 -  GNU Compiler v1.37 from Eltec

Any newer version of the GNU Compiler should do the job as well.  I couldn't
test if the DVIMGR will run under an older or a monochrome version of MGR,
but I think I used no functions special to MGR version 1.3, so let's hope
the best.

Changing the driver from the DEC-Windows version to the MGR version has been
surprisingly easy.  I threw away all the X stuff and replaced it with the
corresponding MGR functions.  It basically worked at the first attempt.

The principle of DVIMGR is very simple.  A part of the TeX page is built in
the memory and then copied to the window.  The coordiantes of the top left
corner of the displayed part can be changed in many different ways.

During startup, DVIMGR searches for a simple configuration file called
".dvimgrinit".  I added this configuration file in order to allow
adaptations of colors and font numbers and window sizes, especially in case
of a monochrome MGR environment or older versions of MGR.

Unfortunately DVIMGR is not the fastest previewer there is.  It takes about
3 to 5 seconds - depending on window size and magnification - to display the
next page (on a 68030/25MHz machine).  But the bottleneck isn't the driver
itself, but the MGR function m_bitloadcol() that is needed to copy the
monochrome bitmap to the color display.  This may be faster on a monochrome
display.


DISCLAIMER
-----------
  This preview program and its source code are supplied on an 'as is'
basis. I regret any liability for any damage, inconvenience or malfunction
caused by these programs. There might still be errors in the programs
itself or in the documentation.  Please contact me if you find any errors.


Files
-----
  I found the sources for DECWindow and OSF/Motif previewer on our
VAXstation.  I left the structure of the directories and files basically
the same as for the DECwindows and OSF/Motif Previewers.  In order to
reduce the file size I only included those files into the archive which are
necessary to compile DVIMGR and the original DECwindows and OSF/Motif
previewers (cf. the original readme file).  The complete driver family
contains many other files to build drivers for nearly every type of printer.
The complete source codes for all drivers can be obtained from

                science.utah.edu

and many other FTP sites.

The structure of the directories containing the sources is now:

  dvimgr/               contains all .H files from the Beebe driver V2.10
            (FINDPOST.H and GBLVARS.H contain error corrections!)
                        all sources to compile DVIMGR and the original
                        documentation DVIxxx.*
  dvi_fbi_hh/includes/  contains all modified .H files
  dvi_fbi_hh/dvimotif/  contains source code for OSF/Motif DVI Preview
  dvi_fbi_hh/dvidecw/   contains source code for DECwindows DVI Preview
  README.TXT        The original readme file.
  README.OSK        This file.


I changed the name of the directory 'dvi_fbi_hh/beebe' to 'dvimgr'.  This
directory now contains all the files necessary to compile DVIMGR.  The
modified .H files from the 'dvi_fbi_hh/includes' directory have already been
copied to this directory.  To distinguish them from the original files these
files have been renamed with the extension '.beebe'.


Installation
------------
  The directory 'dvimgr' contains the file dvixxx.dvi, which is a complete
manual.  It contains a description of all options and gives installation
hints.  The only thing that needs to be done is to tell DVIMGR where to find
its font via the environment variable TEXFONTS.  You can use the -d16 option
to find out where DVIMGR is trying to find its fonts.


Starting DVIMGR
---------------
  DVIMGR can be started by simply typing "dvimgr <dvifile>".  A second
window will be opened in which the TeX output will be displayed.  The main
window is used to print some general information.


The configuration file .dvimgrinit
-----------------------------------
  During startup DVIMGR searches for a configuration file called
".dvimgrinit".  I added this file in order to make installation on a new
site as easy as possible.  DVIMGR looks for its configuration file first in
the current directory, then in /dd/sys and then in /h0/sys.  If it cannot
find the file, it will use its internal default values.

The configuration file contains one parameter per line and has the following
syntax:

    <parameter name> <Space> <value>

Empty lines or lines starting with a ';' or a '*' as the _first_ character
are treated as comment lines.

The configuration file allows initialization of the following parameters.
If a parameter is not explicitly initialized, its default value will be
used.

 -  "font", default value = 8.
    This is the MGR font number which is used in the m_makewindowfcol()
    command.  This font will be used by MGR when displaying the popup menu.

 -  "fgcolor",  default value = 1.
    This color is used as the foreground color in the m_makewindowfcol()
    command.

 -  "bgcolor",  default value = 0.
    This color is used as the background color in the m_makewindowfcol()
    command.

 -  "text-fgcolor",  default value = 1.
    This color is used to set the text color for the TeX window via the
    m_fcolor() command.

 -  "text-bgcolor",  default value = 0.
    This color is used to set the text background color for the TeX winddow
    via the m_bcolor() command.

 -  "startmag",  default value = 0.
    Magnification (magstep) DVIMGR uses after start.

 -  "x_maxwsize",  default = 850 pixel.
 -  "y_maxwsize",  default = 650 pixel.
 -  "x_mag0wins",  default = 850 pixel.
 -  "y_mag0wins",  default = 850 pixel.

    These parameters are used to determine the maximum window size.  See
    section "Window sizes" for more details.


Command line options
--------------------
  I have not fully tested all the command line options which are described
in the manual.  Most of these options are not needed for DVIMGR anyway.  The
following options will work:

 -  The -d option of course will work as usual.

 -  The -o option allows to select the first page to be displayed as for the
    DECwindows Previewer.

 -  The -m option will work, too, but DVIMGR will get confused about the
    window size, because two different magnification mechanisms are working
    against each other.  I you want another magnification right after
    startup you can use the 'startmag' option of the init file instead.
    This is not the best solution and may be improved if I'll find some more
    time.


The Popup Menu
--------------
  When pushing the middle mouse button a popup menu will be displayed.  All
functions of the driver can be activated via this menu.  Most of the
functions can also be selected via the keyboard.  The menu items are ordered
so that the mostly used items are accessable via the main menu and the less
used items via child menus.  This menu is only accessable if the TeX output
window is the active window.  The following items can be selected:

 -  "forward",  keyboard character 'f'.
    Go forward on the current TeX page.  If the end of the page is reached,
    DVIMGR will automatically switch to the top of the next page.

 -  "backward",  keyboard character 'b'.
    Go backward on the current TeX page.  If the top of the page is reached,
    DVIMGR will automatically switch to the bottom of the previous page.

Note:   The vertical stepsize can be set via the menu "steps >>>" and
----    "y stepsize >>>" .  The stepsize can be adjusted in % of the window
        height.  The default value for the vertical stepsize is 90%.


 -  "next page",  keyboard character 'n'.
    Go to the next page.  The coordinates of top left corner of the
    displayed part of the TeX page will not be changed.

 -  "prev page",  keyboard character 'p'.
    Go to the previous page.  The coordinates of top left corner of the
    displayed part of the TeX page will not be changed.

 -  "goto page ...",  keyboard character 'g'.
    A particular page can be selected.  The main window will be made the
    active window, then the desired page number can be entered.  The top of
    the selected page will be displayed.

Note:   The page number is a sequence number, not a number to be compared
-----   with \count0 values.

------------------------------------------------------------------------------

 -  "steps >>>".
    When selecting this item and moving the mouse to the right a child menu
    will appear which provides the following items:

     -  "step down".
        Go down one step as with the "forward" item, but never go to the
        next page.

     -  "step up".
        Go up one step as with the "backward" item, but never go to the
        previous page.

     -  "step right".
        Go right one step.

     -  "step left".
        Go left one step.

Note:   The horizontal stepsize can be set via the menu "steps >>>" and
----    "x stepsize >>>" .  The stepsize can be adjusted in % of the
        window width. The default value for the horizontal stepsize is 5%.

------------------------------------------------------------------------------

 -  "zoom in",  keyboard character '+'.
    The magnification is increased by one magstep.  Displaying the magnified
    page will take some seconds because the new fonts have to be loaded.

 -  "zoom out",   keyboard character '-'.
    The magnification is decreased by one magstep.  Again this will take a
    few second to reload the fonts.

 -  "set zoom >>>",  keyboard characters '0', '1', '2', '3', '4' and '5'.
    Moving the mouse to the right of this menu will show a child menu which
    allows direct selection of a particular magnification.  This is faster
    than using "zoom in" and "zoom out" several times.

 -  "redraw",   keyboard character 'w'.
    This items performs a redraw of the actual page with the actual
    coordinates of the displayed TeX page part.  It is mainly for use
    together with item "auto reshape".

 -  "auto reshape",  keyboard character 'h'.
    This item reactivates the automatic reshape mechanism of the window
    size.  It does not perform an automatic redraw in order to avoid a
    possible superfluous redraw.  For example, if you want to reactivate the
    automatic redraw and then change the magnification the display will be
    redrawn due to the change in magnification anyway.  See "Window sizes"
    for more details.

------------------------------------------------------------------------------

 -  "top of page",  keyboard character 't'.
    Go to the top of the actually displayed TeX page.

 -  "bottom of page",  keyboard character 'o'.
    Go to the bottom of the actually displayed TeX page.

 -  "top left of page",     keyboard character 'y'.
    Reset the coordiates of the actually displayed part of the TeX page to
    the top left corner of the TeX page.

------------------------------------------------------------------------------

 -  "tgl. top margin",  keyboard character 'a'.
    The size of the top margin is toggled between TeX's standard size of one
    inch and 10% of the base resolution of 69 dpi.

 -  "tgl. left margin",  keyboard character 'm'.
    The size of the left margin is toggled between TeX's standard size of one
    inch and 10% of the base resolution of 69 dpi.

 -  "reload fonts",  keyboard character 'e'.
    This menu item forces unloading and reloading of all fonts.
    See "Known Bugs" for more details.

------------------------------------------------------------------------------

 -  "exit",  keyboard character 'x'.
    Guess what this means...  Destroying the TeX output window by selecting
    'destroy' from the system menu will also terminate DVIMGR correctly.
    (Destroying the _main_ window is another way to quit DVIMGR but this
    might not be the best idea ...)


Window sizes
------------
  Selecting the right window size for all magifications is a delicate job.
The standard size used for magstep0 (69 dpi) is well suited to get an
overview over the page structure, but the characters are hard to read.
Using magstep 2 (100 dpi) will provide well readable characters, but if the
window has a fixed size, the text lines are likely not fit into the window
because its width is to small.  This is a little bit nerving when reading a
text.

To improve this the following mechanism has been implemented.  The size of
the bitmap has been increased so that up until magstep 2 a whole TeX page
will be built im memory even if only a part is displayed on the screen.
This allows full text lines to be displayed in the window up to magstep 2.

When changing the magnification, DVIMGR will always try to make the window
large enough to fit the whole page into the window.  But the maximum window
size is limited by the two following mechanisms:

 -  The size of a window is automatically limited by MGR if it is too large.
    Therefore each time a window has been reshaped the actual window
    parameters are inquired from MGR in order to do the following
    calculations with correct values.

 -  The size of a window is also limited by DVIMGR's internal parameters
    called 'x_maxsize' and 'y_maxsize'.  To allow the user to select its
    favourite maximum window size the parameters "x_maxsiye" and y_maxsize"
    of the init file are provided.  These parameters can be used to adapt
    the size of the window to the size of the physical screen.

But there is an exception for magstep0.  Because the MGR manages a virtual
screen much larger than the physical screen, it could be useful in order to
get a better overview to see the whole page even if it does not fit in the
physical screen.  Therefore the parameters "x_mag0wins" and "y_mag0wins" of
the init file allow to set the maximum window size used for magstep 0
independently.  If they are _both_ set to -1 DVIMGR sets the window size in
a manner that the whole TeX page will fit exactly into the window.

The user may also change the window size via the reshape item of the system
menu.  Once the window has been reshaped manually, the automatic reshaping
mechanism is turned off.  It can be turned on again by selecting the item
"auto reshape" from the popup menu.


Hints
-----
  I would recommend to activate a harddisk cache (the Microware diskcache
utility for example) when running DVIMGR.  If DVIMGR cannot find a font it
tries to find the nearest neighbouring font in order to produce the best
possible result.  Doing this DVIMGR tries to open about a hundred (!) files,
which can be observed by using the option -d16.  Without the cache activated
this will take about 1 or 2 minutes (!) for each font DVIMGR cannot find.


Known Bugs
----------
There are two known bugs:

 1. If DVIMGR is started a second time in the same window, it sometimes
    complains about non-matching font checksums, and the picture looks a
    little bit weird.  The driver obviously accesses the wrong font files.
    I don't know why this happens and if this is a problem of DVIMGR, MGR or
    OSK.  All font files seems to get closed correctly when DVIMGR exits.

    As a workaround I added the menu item "reload fonts".  This forces
    all fonts to be unloaded and reloaded again like when changing the
    magnification.  (Changing the magnification will have the same effect
    and can be used instead.) Then everything will be ok.

 2. Sometimes DVIMGR crashed with a bus trap error when building the bitmap
    in memory.  I found that this error was caused by the function
    dispchar() and seems to occur sometimes when a character has to be set
    near to the 'border' of the bitmap.

    As a workaround I simply made the bitmap a 2 KBytes larger than the
    needed size.  This error never occured since then. (This might not be
    the best way to correct this error but the fastes.)


Running a monochrome version
----------------------------
  I'm using the MGR with a color display.  So I could not test DVIMGR
running in a monochrome MGR environment.  Therefore I made all parameters,
which could be important -- like font numbers and colors -- adaptable via the
configuration file.  Another item which could be resolution dependent is the
function m_bitloadcol(), which I used to copy the monochrome bitmap to the
color display.  But there has been no hint in the manual that this function
will not be available for the monochrome MGR server, so I hope everything
will be ok.


Possible improvements
---------------------
  There are surely some parts of the program which could be improved.  I
tried to implement some improvements like building not only a part but the
whole page at once and keeping already computed pages in memory in order to
speed up the display.  It took me a whole weekend to find out, that the time
DVIMGR needs for bulding the page in memory is neglectable against the time
the MGR server needs to copy the bitmap to the window.  I assume this is
because the server has to expand each bit of the bitmap to 4 bits needed for
the display (I'm using a display with 16 colors.) There's space for
improvements.

The other result of my experiments was that page caching eats up a lot of
memory.  So I decided to remove the code again in order to keep the
structure of the programm as simple and clear as possible.  Caching of pages
may be an advantage if DVIMGR is running on a monochrome MGR.  If anybody is
really interested in this code I could mail it to him.  I do not have much
time for further experiments.


I hope this driver will be usefull for somebody.  If you'll find any errors
or have any suggestions or if I forgot something please contact:

--------------------------------+-------------------------------------------
  Lars-Christian Schulze        |  Institute for Communications Technology
                                |                at the
  Internet:  (preferred)        |     Braunschweig Technical University
  [e-mail]      |
                                |  Schleinitzstr. 23
  [e-mail]   |  38092 Braunschweig
  Voice:   [phone]     |  Germany
                                |
  07-Aug-1993                   |
--------------------------------+-------------------------------------------