path: root/dviware/tmview/README

*****************************************************************************
******this is the README for tmview v01.03***********************************
*****************************************************************************

1. What is tmview?
2. Compiling tmview
   - EXTRA NOTES compiling for Solaris
3. Installation and configuration
   - EXTRA NOTES dvisvga.linux
   - EXTRA NOTES dvifb.linux
   - EXTRA NOTES dvilx.linux/dvilx.solaris
4. Compiletime options
   - EXTRA NOTES ghostscript
   - EXTRA NOTES kpathsea
   - EXTRA NOTES mouse
   - EXTRA NOTES X-Window System   
   - EXTRA NOTES non-i386 architectures e.g. Alpha.
5. Get the newest version, send me your comments


*****************************************************************************
*****************************************************************************
*****************************************************************************

1. What is tmview?

tmview is a screen-previewer for .dvi-files compiled by TeX. It let's you see
what your printed output will look like. You can choose between a
black-and-white representation and greyscaling. You can choose an arbitrary
zoomfactor (at some cost of performance). You can set marks to measure
distances.  You can search for textstrings. You can visit lots of DVIfiles, set
bookmarks and get them saved to a startup-file. tmview does not support
pxl-files since I think they are prehistoric. tmview ignores almost all
'special'-commands, sorry lads. tmview tries its best with virtual fonts and
included .eps-figures.  tmview is prepared to be linked with kpathsea.

The current version supports three environments: Linux/svgalib, 
Linux/framebuffer and the X Window System (by Xlib).

List of files:

 ./tmview/README         this file: installing and compiling tmview
 ./tmview/CHANGES        file of changes to tmview
 ./tmview/IAFA-PACKAGE   specification of the package according to IAFA
 ./tmview/VER0103        empty file, indicating current version
 ./tmview/MakeFb         makefile for dvifb.linux (Linux/sframebuffer)
 ./tmview/MakeSVGA       makefile for dvisvga.linux (Linux/svgalib)
 ./tmview/MakeLX         makefile for dvilx.linux (Linux/X Window System)
 ./tmview/MakeSolaris    makefile for dvilx.solaris (Solaris/X Window System)
 ./tmview/src/*          general source files
 ./tmview/fb/*           source files related to the framebuffer support
 ./tmview/lX/*           source files related to the X Window System support
 ./tmview/svga/*         source files related to the svgalib support
 ./tmview/doc/tmview.tex manual (tex source): user interface
 ./tmview/doc/tmview.dvi manual (dvi file)
 ./tmview/doc/tm.ps      example eps-file for the manual
 ./tmview/doc/tmview.1   man page: commandline options only


*****************************************************************************
*****************************************************************************
*****************************************************************************

2. Compiling tmview

tmview come with makefiles to go with Linux/svgalib, Linux/framebuffer, 
Linux/X Window System or Solaris/X Window System:

 ./tmview/MakeSVGA          Linux/svgalib
 ./tmview/MakeFb            Linux/framebuffer
 ./tmview/MakeLX            Linux/X Window System
 ./tmview/MakeSolaris       Solaris/X Window System

To compile tmview, copy one of the above makefiles to "./tmview/Makefile".
Then, make the directory "./tmview" the current directory. Now, running
'make' should generate the desired binary, i.e.

 ./tmview/dvisvga.linux      Linux/svgalib
 ./tmview/dvifb.linux        Linux/framebuffer
 ./tmview/dvilx.linux        Linux/X-Window System
 ./tmview/dvilx.solaris      Solaris/X-Window System

In the case of dvisvga.linux, running 'make' as root will set the superuser
flag of dvisvga.linux. This is usually required.

As long as you don't change any compile-time options of tmview, compiling
should go through without errors. In the rare case that certain include-files 
or libraries are not found, you will need to adjust the paths at the beginning
of the Makefile.


*****************************************************************************
EXTRA NOTES compiling for Solaris

As there are serveral development environments for Solaris, it is
very likely  that you have to edit the makefile. I only tested compiling 
with GNU gcc, GNU binutils etc. Furthermore, you will need to get the GNU 
regex-package since others won't do. After configuring/compiling GNU's regex,
copy the resulting "regex.o" to  "./tmview/src/sol.regex.o"; copy "regex.h" 
to "./tmview/src/sol.regex.h". 


*****************************************************************************
*****************************************************************************
*****************************************************************************

3. Installation and configuration

To install one of the above binaries, simply copy it to a suitable place, e.g.
"/usr/local/bin/dvisvga" for the svgalib version.

There is also a man-page "./tmview/doc/tmview.1", to be copied e.g. to 
"/usr/local/man/man1/dvisvga.1". The man-page provides information about the 
command-line options. These are meant to make tmview go with your TeX 
installation, e.g. they are used to set up search paths for fonts.

The following shall give a quick guide to get tmview running. As an example, 
focus is on using dvisvga to view the .dvi-file "./tmview/doc/tmview.dvi". 
The latter provides detailed information about tmview's user interface, e.g.
how to navigate within .dvi-files. Thus, "tmview.dvi" is essential to make 
best use of tmview. There is no additional info on installing tmview in 
tmview.dvi ;-). Watch out for the platform dependent EXTRA NOTES below.

Make the directory "./tmview/doc/" the current directory. Make sure, that the
fonts used by tmview.dvi exist, e.g. generate them by 

dvips -D 300 -o /dev/null tmview.dvi 

Here, 300dpi is assumed to be your standard resolution. Hence, you should 
replace "300" by "xxx" if you use an xxxdpi printer by default.

Now, invoke tmview by

dvisvga -r300x300 tmview.dvi

It is essential that no "space" appears between the option flag "-r" and 
its argument "300x300". After searching for fonts, tmview should show up 
with the first page of "tmview.dvi", where the boarder of the page is
indicated by a green rectangle. Below you should find a status line.
tmview now accepts a wide range of commands, e.g. use the cursor keys to
navigate, or press <?> twice for online help, or even <q> to quit tmview.
 
If only lots of blue boxes (instead of glyphs) appear, tmview did manage to
find your .tfm-files, but did not find the according .pk-files. If 
only the green border of the page shows up (check this by using the cursor
keys!), tmview neither found .tfm- nor .pk-files. In both cases you will
need to adjust tmview's search paths to your TeX installation. Typical
places for fonts are "/usr/local/lib/texmf//", "/var/spool/texmf//",
"/usr/local/teTeX/texmf/fonts//" a.s.o. In order to inform tmview about
those paths, use the command-line options:

dvisvga -r300x300 -f/where/pk-files/are// -t/where/tfm-files/are// tmview.dvi

By the double slash "...//" all subdirectories are searched. Hence, with
"-f/usr//:/var//" tmview should find all fonts, but becomes quite slow. 
See the man-page "./tmview/doc/tmview.1" for details. You can find the
command-line-options of tmview to go with your TeX Installation just by playing
along: they will be automatically saved to a user startup-file (default
"~/.dvisvga","~/.dvifb" or "~/.dvilx"). Once you are satisfied, you can copy 
the user startup-file to the system startup-file, i.e. "/etc/dvisvga", 
"/etc/dvifb" or "/etc/dvilx". From now on, just calling "dvisvga" with no 
options at all will be fine.  You can check the current command-line defaults
by invoking tmview with the "-?" option.

By editing the startup-file you can replace the line "verb 0" by "verb 1". 
This will make tmview a lot more verbose.


*****************************************************************************
EXTRA NOTES dvisvga.linux

Like with any other program using svgalib, the superuser flag has to be set 
to dvisvga. The makefile will take care of this, if it's run by the superuser
root. Otherwise you will need to apply the following as root:

chown root /usr/local/bin/dvisvga
chmod 4755 /usr/local/bin/dvisvga

Installing, configuring and testing svgalib requires some knowledge.  The
required information can be found in the docs of svgalib. dvisvga  should 
"run on any system with svgalib 1.2.11 or above". But this is at the cost of 
performance and display quality (flickering screen, low resolution etc.). If 
you plan to use tmview frequently, it may be worth taking the time to optimize
your svgalib setup. Otherwise, skip these extra notes.

Usually, a Linux distribution comes along with an svga-library called
"svgalib".  In general, dvisvga goes with svgalib version 1.2.11 or above. If
you recompile dvisvga with the VGAHASWAITIO compile-time option turned off,
this will dramaticly reduce the speed of eps-figure rendering. However, svgalib
version 1.2.5 will be sufficient in that case. If you use a graphics-adapter
with an S3 chip, you should use at least svgalib 1.2.8 since the older versions
have "certain problems" with those cards. In general, updating to the newest
version of svgalib is recommended.
See "ftp://sunsite.edu.unc/pub/Linux/libs/graphics/svgalib*".

You should carefully read the docs of svgalib in order to set up the 
configuration file correctly. This usually is located in 
"/etc/vga/libvga.conf". Then test your configuration using the "vgatest" 
program which comes with svgalib. Unfortunately, this binary is not included 
in some Linux distributions. In this case, it is strongly recommended to get 
the svgalib sources and compile the demo programs which come along. 
"vgatest" is one of those. Running "vgatest" will list the available graphic-
modes. Since dvisvga prefers 256-color-modes, and since you want more than a 
320x200-pixel screen, (standard-)vga won't be enough: super-vga is required. 
Hence, your graphic-chip must be supported by svgalib. Make sure, that your 
favorite 256-color-mode works. To make tmview use that mode, set the variable 
$GSVGAMODE or use the "-d" command-line option of dvisvga.
   
For the case your svgalib supports (standard-)vga only, you can still use
dvisvga with the 640x480 mode at 16 colors (instead of 320x200 at 256
colors). Whenever either the desired resolution or 640x480 is not supported at
256 colors, the 640x480 mode at 16-colors is used. This is meant for easy
installation on "old" notebooks and such.
   

*****************************************************************************
EXTRA NOTES dvifb.linux

The framebuffer device is a kernel module which allows to map the physical 
memory of your graphics adaptor in user space. As within the svgalib 
environment, the low level prodeures of such a device driver will depend on 
very harware specific issues as chipset and I/O addresses. But the framebuffer
device has one extra "compatibility" bonus: the so called VESA framebuffer 
module switches to graphics mode right at boot time and can thus use the 
build-in real mode routines on your actual graphic card ... you have payed 
for it. So even rather exoctic graphic devices can now be addressed -- as long
as they are VESA 2.0 compilant. A drawback of the VESA framebuffer module is 
that the boot time graphics mode cannot be changed without re-booting. See the
kernel docs for how to compile the framebuffer device module. Note that the
VESA framebuffer module may conflict with svgalib and SVGATextMode. If your
machine runs SVGATextMode at startup you may want to alter this behaviour.
dvifb was not tested with kernels below 2.2.1.

dvifb requires a 256 pseudocolor mode. You can query --and eventually set--
the mode of the framebuffer device by the util "fbset". See the man-page.
Examples for boot-time VESA modes are 0x101 and 0x103. The according module
parameters are 0x301 and 0x303 respectively. Again, see the framebuffer kernel 
docs. dvifb uses by default "/dev/fb0" as framebuffer device. However, this can
be overwritten by the environment variable $FRAMEBUFFER. A rather brutal test 
of your framebuffer device would be to copy som4 data to "/dev/fb0" and watch 
the screen beeing messed up. Be prepared to blind-type "reset" to get the 
console back to work. An example output of "fbset" indicating a framebuffer
that suits tmview is as follows (only "geometry" is of relevance here):

  mode "name"
      # D: 48.001 MHz, H: 46.876 kHz, V: 75.121 Hz
      geometry 800 600 800 600 8
      timings 20833 96 32 16 4 96 4
  endmode


Memory mapping the framebuffer requires root permissions, i.e. effective uid 0.
Thus, the superuser flag has to be set to dvifb. The makefile will take care, 
if it's run by root. Otherwise you will need to apply the following as root:

chown root /usr/local/bin/dvifb
chmod 4755 /usr/local/bin/dvifb

The program "gpm" is (ab)used as a mouse driver. The "-R" option of gpm puts gpm in 
"repeater mode" translating mouse data into mouse-systems protocol and piping 
it to "/dev/gpmdata". Make sure that the "-R" option is applied to gpm on your 
system. If you don't have gpm, you should disable the mouse support of dvifb. 
See compile time options below. dvifb was not tested with gpm below version 1.14.




*****************************************************************************
EXTRA NOTES dvilx.linux/dvilx.solaris

These go with the X-Window System. They only rely on Xlib, no motiv or such
required. However, I'm not an expert with Xlib at all, just found a book about
Xlib and played along. Thus, dvilx.linux and dvilx.solaris are not as portable
as they could be. Probably, the popular xdvi is part of your TeX distribution,
perfectly configured, ready to run and able to deal with lots of "specials". 
However, for the case that you've got used to a couple of tmview's features
you can take them along to your new computer, now running with the X Window
System ...  dvilx still "searches text with regular expressions", "keeps
bookmarks for visited dvi-files". If you are an expert, you may try to get 
dvilx running under Unix/X even if this not Linux/XFree or Solaris/Openwindows.
Send me your patches for a true X support of tmview.

If you don't get a tmview-window at all, use the DEBUGX option in
"./tmview/lX/writelx.c".
   
The following resources are used by tmview:

   DviLX.geometry    standard geometry, e.g. 600x300+10+20
   DviLX.foreground  dvi foreground, e.g. black
   DviLX.background  dvi background, e.g. white
   DviLX.sforeground statusline foreground, e.g. tomato4
   DviLX.sbackground statusline background, e.g. OldLace
   DviLX.sfont       statusline font, e.g.
        -b&h-lucidatypewriter-medium-*-*-*-14-*-*-*-*-*-*-*

Note: The sfont should be a fixed-width-font.

The file "./tmview/lX/DviLX" is an example for tmview app-defaults.
There are also icons "./tmview/lX/tmview.x?m" to be used by window managers.


*****************************************************************************
*****************************************************************************
*****************************************************************************

4. Compiletime options

Hopefully, the above runtime-options allow configuring tmview to go with
you TeX installation. There are also some compile time options you might 
like to adjust to your needs. They can be found in the defs*.h files 
indicated below. Probably some programming skills are required to
understand what's going on in these files. However, those options which are 
meant to be adjusted are sort of "well documented".  

  ./tmview/src/defsgen.h        platform independent options
  ./tmview/svga/defssvga.h      Linux/svgalib related options
  ./tmview/fb/defsfb.h          Linux/framebuffer related options
  ./tmview/lX/defslx.h          Linux/X Window related options
  ./tmview/lX/defssolaris.h     Solaris/X Window related options

In the platform independent section, you will find  a couple of startup 
defaults, like how far the <up>/<down> keys scroll or whether tmview shall 
be verbose by default.  There also is a constant to define the maximum amount 
memory in the glyph buffer.  This effects how large a glyph (this includes 
eps-figures!) can be before being ignored. 

The platform dependent things are more interesting. Beside certain defaults 
for commandline arguments, one will find options to

  enable/disable eps-figure rendering by ghostscript
  enable/disable kpathsea support
  define name of user-startupfile/system-startupfile

EXTRA NOTES ghostscript: If you don't have ghostscript on your system disable
eps-figure rendering. Otherwise check the path specified in GSBIN. The quality
(and the speed) of rendering can be adjusted by GSGREY.
  
EXTRA NOTES kpathsea: Kpathsea is disabled by default because there are 
various versions of kpathsea and static linking makes no sense here. If 
your TeX-installation supports kpathsea, you can compile tmview with 
kpathsea support as well. You'll need the include-files and libkpathsea of 
exactly your TeX-installation to do so. I did test this with the
kpathsea which comes along with dviljk-2.5, see CTAN in the "dviware"
directory. I also tested with teTeX-0.4,  see CTAN "systems/unix/".
Finally, the Makefile (and of course defs*.h) has to be edited to enable
kpathsea support. Depending on your version of kpathsea, it might be essential 
to place the binary dvilx/dvisvga/dvifb in the same directory as the other TeX 
related binaries, e.g. dvips.

EXTRA NOTES mouse: If mousesupport is enabled in dvisvga while your mouse 
(or exotic touchpad ...) actually isn't supported by svgalib, you wont be 
able to move the screenmark. This is obviously not desired. In this case you 
might like to disable mousesupport for dvisvga in "./tmview/svga/defssvga.h". 
This line of thought also applies to the framebuffer version dvifb. 

EXTRA NOTES X-Window System: tmview/dvilx runs faster, if the depth of
your screen is known at compiletime.  Because of my poor equipment (Linux on a
pc, no fancy X-terminals) this is only tested for 8bit and 16bit screens.  See
the file "./tmview/lX/writelx.c" to set things up for your needs. To watch 
what's going on when tmview tries to find its way to the XServer, setting up
colors, asking for fonts and so, set DEBUGX in writelx.c . This helps
if no tmview window shows up at all.

EXTRA NOTES non-i386 architectures: Of course I realize that there are several
non-i386 architectures. The clean way of dealing with machine dependand stuff
is to make use of <sys/types.h> and such. Unfortunately I didn't. In a future
version I shall carefully review the code from this perspective. In the 
meanwhile there is on crucial compiletime option to set up how many bits
actually make a "long int". On i386 these are 32. Thus, enable "#define BMLONG32"
in the platformm dependant "defs*.h", e.g. "./tmview/lX/defslx.h". On Alpha
systems a "long int" is made up from 64 bits. Here, "#define BMLONG64" needs
to be enabled. tmview will issue a runtime warning message if it figures out 
that ends don't meet here.


*****************************************************************************
*****************************************************************************
*****************************************************************************

5. Get the newest version, send me your comments

Final releases are to be found on CTAN ftp-servers such as "ftp.dante.de".
Since uploading to an ftp-server is some work, for both, me and the supervisors
of the server, this is not done too often. Bugfixes and minor changes are
therefore uploaded on "members.aol.com", my "private" ftp partition. Make the
directory "/qelis" current, even if it is NOT listed by the dir command. There
you will find any tmview related stuff in tar-gz-archives named "tmvXXXX.tgz"
where XXXX is the release number.


You may have some ideas how tmview could become better. You might have added
code to process some of these fancy special command some macro-packages spread
all over the dvi-files they produce. Bug reports or even fixes are welcome
too. 

qelis@aol.com



*******************************************************************************
End of README******************************************************************