summaryrefslogtreecommitdiff
path: root/dviware/tmview/README
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /dviware/tmview/README
Initial commit
Diffstat (limited to 'dviware/tmview/README')
-rw-r--r--dviware/tmview/README403
1 files changed, 403 insertions, 0 deletions
diff --git a/dviware/tmview/README b/dviware/tmview/README
new file mode 100644
index 0000000000..85206c9103
--- /dev/null
+++ b/dviware/tmview/README
@@ -0,0 +1,403 @@
+*****************************************************************************
+******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******************************************************************
+
+