diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /dviware/tmview/README |
Initial commit
Diffstat (limited to 'dviware/tmview/README')
-rw-r--r-- | dviware/tmview/README | 403 |
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****************************************************************** + + |