
                                 DVI2PM



     A public domain DVI Previewer for the OS/2 Presentation Manager


                    written by Christian Monte
             email:<zimmermann@iskp.physik.tu-berlin.dbp.de>


 DVI2PM is derived from Doug McDonald's DVIVGA for the IBM PC
 (see file changes.os2) and provides the same keyboard interface.

 
 Mouse and Scrollbar interface will be made available in the near future. 
 For now DVI2PM is just a keyboard driven TeX-Previewer. I'm sorry but i 
 need it now and not tomorrow. So there is many room for improvements. 
 Someday it should work with fonts rather then bitmaps. Maybe anybody has 
 an idea who to turn a PK-font in a PM-screen font. 


 DVI2PM is a TeX screen previewer for OS/2 PM. It expects the name of
 the .DVI file on the command line, and the extension .dvi can always
 be omitted. If no command line arguments are given, the filename can
 be set from the open menu.


           This driver is based on a driver family written by
           Nelson Beebe of the University of Utah and others.


 EQUIPMENT REQUIREMENTS

 A Computer running OS/2 Presentation Manager. The program is developed
 an tested with IBM OS/2 SE 1.2 and MSC 6.0. It does not support long
 filenames and extended attributes.


 COMMAND LINE OPTIONS

 The order of command options and .DVI file name is not significant; all
 switch values are accepted by this driver, but not all are really
 meaningful.

 Letter case is ignored in option switches:  -A and -a are equivalent.

                -a Implement virtual font caching. This option is
                   essentially useless for this driver.

                -d Produce debugging output on stderr if a non-zero
                   value is given.  These are:

                     2 --- Display coordinates, metrics, and bitmap
                           of each character.
                     8 --- Display each successful file opening.
                    16 --- Display each unsuccessful file opening.
                    32 --- Show discarded off-page text.
                    64 --- Trace virtual font caching.
                   128 --- Trace character setting.

                   It is possible to combine these options by adding
                   their values.

		   IMPORTANT:
		   It is at this time not possible to view debug output
		   in a PM window. To inspect debug results stderr can be
             redirected to a file. For example:
               DVI2PM -d24 test.dvi 2> debug.out

       -eVAR=value Define environment variables on command line. This
                   is an alternative to placing them in the DOS
                   environment.


     -ffontsubfile Define an alternate font substitution file which is
                   to be used instead of the default ones (see below).

                -l Inhibit logging.

                -m Reset magnification. The default for the screen
                                                                  (k/2)
                   driver is -m502. Useful values are int(1500*1.2     )
                   from 279 to 1500. Other values will be reset to the
                   nearest value in this set. Magnification values less
                   than 25 are taken to be a TeX magstep parameter
                   which is applied to the standard magnification for
                   that device. Thus -m-0.5 will reduce the output size
                   by the square root of 1.2, -m2 will increase it by 
                   a factor of 1.44.

                   You may well need to use this parameter frequently;
                   good values to try are 603, 502, 459, 419, 382,
                   349, 318, and 289. These are equivalent to -m0.5,
                   -m-0.5, -m-1, ... -m-3.5. -m382 or -m-2 gives actual
                   size output using VGA on an IBM8513 monitor.
                   
                   Sizes smaller than 459 use substitute fonts, so that
                   they may not come out looking quite perfect.

                   Read about "Batch Files" to find an easy way of
                   changing sizes.


          -x#units The -x options specify the left margin of the TeX
                   page on the output page in any of several units.
                   Letter case is not significant in the units field,
                   which must not be separated from the number by any
                   space.  The number may be fractional.  For example,
                   -x1.0in, -x2.54cm, -x72.27pt, and -x6.0225pc all
                   specify a one-inch left margin. Negative values are
                   permissible, and may be used to shift the output
                   page left (possibly truncating it on the left) in
                   order to display a wide TeX page.

                   The units field is mandatory, and may be one of

                           big point (1in = 72bp)
                           cicero (1cc = 12dd)
                           centimeter (1in = 2.54cm)
                           didot point (1157dd = 1238pt)
                           inch
                           millimeter (10mm = 1cm)
                           pica (1pc = 12pt)
                           point (72.27pt = 1in)
                           scaled point (65536sp = 1pt)

          -y#units This is just like -x except that it is for the top
                   margin.

                   Because the normal defaults waste screen space, the
                   defaults for the screen driver have both been set to
                   zero. If you wish to get the correct margins and
                   size, try -x1.in -y1.in -m382 for DVIVGA.



 FONT SUBSTITUTION

 If no -ffontsubfile option is given, and font substitution is required,
 if the current .DVI file is  foo.dvi, then the files  foo.sub,
 texfonts.sub, and TEXINPUTS\texfonts.sub will be tried in order.  The
 first two will be found on the current directory, and the last is the
 default given in the environment string TEXINPUTS.  The -f option
 allows all of these to be overridden. It is essentially necessary to
 have this file if you use a magnification smaller than the default for
 DVI2PM. A copy of a suitable one is supplied.

 Font substitution lines have the form:


             oldname.oldmag      subname.submag   % comment
             oldname oldmag      subname submag   % comment
             oldname             subname          % comment

 Examples are:

----------

 % These provide replacements for some LaTeX invisible fonts:
 icmr10 1500     ->      cmr10 1500      % comment
 icmr10.1500     ->      cmr10.1500      % comment
 icmssb8         ->      cmssb8          % comment

----------


 The first two forms request substitution of a particular font and
 magnification. The third form substitutes an entire font family; the
 closest available magnification to the required one will be used.  Any
 dots in the non-comment portion will be converted to spaces, and
 therefore, cannot be part of a name field.

 The first matching substitution will be selected, so
 magnification-specific substitutions should be given first, before
 family substitutions.

 Comments are introduced by percent and continue to end-of-line, just as
 for TeX. One whitespace character is equivalent to any amount of
 whitespace. Whitespace and comments are optional.



 SCREEN CONTROL

 DVI2PM supports interactive viewing of the TeX output. Here is the
 current command list. Input is immediate; no terminating carriage
 return is necessary, except for the number command to go to a
 particular page.

 home              Displays first page.

 end               Displays last page.

 pageup            Displays previous page.

 pagedown          Displays next page.

 number keys       Goto page. For example: "66 <ENTER>" diplays page 66.

 uparrow downarrow Move the view of the current page up or down. These
                   commands do not require recalculating the screen
                   image and are very fast.

                 D Move the page origin one inch down.

                 d Move the page origin one-quarter inch down.

                 U Move the page origin one inch up.

                 u Move the page origin one-quarter inch up.

                 L Move the page origin one inch left.

    leftarrow or l Move the page origin one-quarter inch right.

                 R Move the page origin one inch right.

   rightarrow or r Move the page origin one-quarter inch right.
                   "Inches" refers to the "printed" page, and is only
                   approximate on the screen.


                 Q (or q or X or x or Ctrl Break or Ctrl C or Ctrl Y) Quit
                   or exit.  The screen will be cleared and restored to
                   its normal mode.

                 B Zoom up one magstep (1.2 times larger) from current
                   size.

                 b Zoom up 1/2 magstep (1.09 times larger) from
                   current size.

                 S Zoom down one magstep (1.2 times smaller) from
                   current size.

                 s Zoom down 1/2 magstep (1.09 times smaller) from
                   current size.

                   How well these zoom options work depends on how many
                   fonts you have loaded: more is better.

                   The command sequence RDSS will result in a display of
                   approximately the same size and origin as a printed
                   page if your physical display is the same size as
                   the IBM 8513, and you start at the normal defaults.


 FONTSIZE MENU

 Zooms the page according to selected fontsize.

		fontsize   |	equivalent magnification
		----------------------------------------
		 92	   |	 459	
		100	   |	 502
		110	   |	 550	defualt value
		121	   |	 603
		132	   |	 660
		145	   |	 723
		174	   |	 868
		208	   |	1042
		250	   |	1250
		300	   |	1500 

 SPECIALS

 The TeX \special command is intended to allow the specification in a
 .tex file of a request to the .DVI driver, usually for the insertion
 of graphical material at that point in the document.  It is not
 implemented for the DVI2PM driver.


 BATCH FILES

 If you need to use other than the default size a lot, for instance if
 your text is wider than 5.6 inches, you can make this convenient by
 using a batch file. For example, make a batch file, say DVIWIDE.CMD
 containing the line
 
                      DVI2PM -m459 -x0.1in %1

 and nothing else. Then if you say "DVIWIDE filename" you will get your
 6.5 inch wide file to fit on the page. You can of course adjust these
 numbers for your own favorite text shape, and can change other things
 as well.


 ENVIRONMENT VARIABLES

 The behaviour of the .DVI translators can be influenced by definition
 of logical names under OS/2. They should be
 entirely in upper case.

 The names currently recognized are as follows:

    FONTLIST  Normally, the drivers are prepared to search first for
              .pk, then  .gf, then .pxl font files. This variable can
              be used to change this search order, or remove one or
              more of the possibilities.  It is expected to contain at
              least one of the strings  PK,  GF, or PXL, possibly
              separated by arbitrary punctuation and other text. Letter
              case is not significant.    Some acceptable strings are
              PXL-then-PK-then-GF,  pk.gf,  use-only-PXL-fonts, and
              PXL/GF/PK. For the fonts provided with this product, use
              "set FONTLIST=pk".

    TEXFONTS  This defines the directory path for finding font files.
              Its value is  prepended to the name of a  font to get a
              full file specification.  A typical value for TEXFONTS
              would be d:\tex\texfonts\. 

    TEXINPUTS This defines the directory path for finding files which
              are not in the current working directory. It is
              prepended to file names. A typical value for TEXINPUTS
              would be d:\tex\texinput\


 You can omitting FONTLIST (which at worst would slow things down a bit).
 You could get rid of TEXINPUTS entirely by putting a copy of texfonts.sub
 in your current directory. 



 DIRECTORY STRUCTURE FOR FONTS

 The fonts have to be placed in a proper manner. Assuming you set, as I
 do, TEXFONTS to d:\tex\texfonts\, you need to place all the fonts
 for size 100 in directory d:\tex\texfonts\100, those for size 121 in
 d:\tex\texfonts\121, etc. Note that this implies that you will have
 a lot of subdirectories with names that are numbers. These numbers
 are dot per inch values, and are 1/5 the "magnification value" used
 with the "m" command line parameter. It is traditional to put .pk
 and .gf fonts in directories numbered like that. Pixel (.pxl) files
 are, on the other hand, placed in directories with the magnification
 value in their name. Thus \100\cmr10.pk and \502\cmr10.pxl are likely
 the same font. It appears that PcTeX uses .pxl files a lot for their
 drivers. DVI2PM will use those if they are in the size series it expects.
 Having .pk and .pxl files in the same directory structure PROBABLY
 won't hurt, though it has not been tested. There is nothing magic
 about these directory names - if you like \pixel\ instead of \texfonts\,
 perhaps because it is already there, use it instead.



 BUGS

 May appear because the program is not tested under all conditions.



 WARRANTIES

 This program is distributed in the hope that it will be useful, but
 without any warranty.













