***************************************************************************** ******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******************************************************************