summaryrefslogtreecommitdiff
path: root/dviware/mdvi/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/mdvi/README
Initial commit
Diffstat (limited to 'dviware/mdvi/README')
-rw-r--r--dviware/mdvi/README241
1 files changed, 241 insertions, 0 deletions
diff --git a/dviware/mdvi/README b/dviware/mdvi/README
new file mode 100644
index 0000000000..80991fceed
--- /dev/null
+++ b/dviware/mdvi/README
@@ -0,0 +1,241 @@
+
+This is MDVI, a free DVI previewer.
+
+MDVI is distributed under the terms of the GNU General Public License. See
+the file `COPYING' for details.
+
+MDVI is currently is in its early stages of development, and needs much more
+work before being considered ready for general use. Although it is quite
+usable, it lacks key features that any self-respecting DVI previewer must
+include. See the file `TODO' for details.
+
+Requirements
+============
+
+ - An ANSI C compiler (tested with gcc and Sun's cc).
+ - X11 (no toolkits, just Xlib).
+ - kpathsea. Any version should do, but I use 3.3.3. If you want to use
+ TrueType fonts, you need at least version 3.2.
+ - GNU Make, any version (ftp://ftp.gnu.org/pub/make)
+ - To use Type 1 fonts, you also need the T1lib library. Get it from
+ ftp://ftp.neuroinformatik.ruhr-uni-bochum.de/pub/software/t1lib/
+ - To use TrueType fonts, you need the FreeType library. MDVI currently
+ supports only versions 1.x (tested with 1.3) of FreeType. A port to
+ FreeType 2.x should be completed soon. Get 1.x from
+ http://freetype.sourceforge.net
+
+You can get all the necessary libraries from MDVI's anonymous FTP site, at
+ftp://mdvi.sourceforge.net/pub/mdvi. The files you'll find there are:
+
+ kpathsea-3.3.3.tar.gz
+ A stripped down version of the web2c-7.3.3 package that contains
+ the kpathsea library only. Use this if your TeX distribution does
+ not use kpathsea to locate files.
+ t1lib-1.0.1.tar.gz
+ The T1lib library, required to support Type1 PostScript fonts.
+ freetype-1.3.tar.gz
+ The FreeType library.
+ tex-ttf-fonts.tar.gz
+ TrueType fonts for use with TeX. These fonts are free, originally
+ obtained from ftp://ftp.tug.org.
+ dvips-config.tar.gz, pdftex-config.tar.gz
+ Fontmap files
+
+Why use MDVI?
+=============
+
+Although MDVI is far from complete, it already has some unique features.
+Namely:
+
+ - A clean, minimal, but efficient interface. No buttons, no distractions.
+ - Rendering of pages in 8 different orientations.
+ - Independent horizontal and vertical scaling factors and resolutions
+ implemented for all font formats. MDVI can closely match the final
+ printed output as produced by dvips or other printer drivers.
+ - Ability to partially read a DVI file, including a powerful mechanism to
+ select the pages that are actually processed, based on either DVI page
+ numbers, TeX \counters, or both.
+ - Several ways of sorting pages, which is nice when viewing LaTeX
+ documents that have a table of contents. Sorting pages up by TeX number,
+ the table of contents comes up as the first page.
+ - Modular design, with a clear division between device-independent code to
+ process DVI files and the actual rendering of glyphs. Adding support for
+ a new font format is a trivial task.
+ - Ability to change all rendering parameters on the fly (including
+ resolutions).
+ - Can process DVI files in `batch mode' without a user interface. Useful
+ for detecting font-related problems (and to generate all the fonts
+ needed by a DVI file without actually displaying it).
+ - Fully customizable via environment variables and `texmf.cnf' - no need
+ for yet another configuration file to maintain.
+ - Support for fonts in PK, GF, VF and OVF formats.
+ - Support for Type1 PostScript fonts, metric files, fontmaps and
+ encodings. MDVI can use the same configuration files and fonts used by
+ dvips/pdftex.
+ - Experimental support for TrueType fonts via FreeType 1.x, using
+ PostScript fontmaps and encoding files.
+ - Builtin support for font metrics in TFM, AFM, OFM0 and OFM1 formats. If
+ a font is missing but a metrics file can be found, MDVI can display a
+ box with the right dimensions in its place, or simply ignore the
+ characters from that font.
+ - Extensible: Support for new fonts and \specials can be added at run-time
+ through an extremely simple API.
+ - Font support completely configurable at run-time, via environment
+ variables and/or command line options.
+
+The most important omissions in MDVI:
+
+ - Support for X resource files.
+ - Rendering of PostScript specials (but EPS bounding boxes are displayed
+ correctly, unless they are rotated).
+ - Transparent glyphs. Currently MDVI uses a cheap trick to simulate
+ transparent glyphs, which consists in drawing with a GXand function.
+ This will NOT work in many common X visuals, and even when it does it
+ still does not yield correct results when the background color is not
+ white.
+ - Zooming. This effect can still be achieved by changing the resolution or
+ the shrinking factor inside the viewer. See the description of keyboard
+ commands at the end.
+ - It's slower than it could be.
+
+These will be improved in the future, but for now the priority is robustness
+and correctness.
+
+Building
+========
+
+First make sure you have all the required tools and libraries, described
+above, and that they are properly installed.
+
+If you plan to use Type1 and/or TrueType fonts, you also need to have the
+configuration files used by dvips or pdftex installed in kpathsea's texmf
+tree. More precisely, you need the PostScript font maps and encoding vector
+files.
+
+If your TeX distribution does not use kpathsea, you'll have to install that
+library independently. It's not hard at all, and it's worth the effort.
+
+If the kpathsea library is in a standard place, you can just type
+
+ $ ./configure
+ $ make
+ $ make install
+
+If the `configure' script fails, or if you want to enable additional
+features of MDVI, you can use the following options:
+
+ --with-kpathsea-headers=DIRECTORY
+ --with-kpathsea-library=DIRECTORY
+ Use these to tell the configure script where to look for kpathsea
+
+ --with-type1-fonts
+ --with-t1lib-headers=DIRECTORY
+ --with-t1lib-library=DIRECTORY
+ The option --with-type1-fonts enables support for Type1 fonts. Notice
+ that support for these fonts is not enabled by default. The other two
+ options tell `configure' where to find t1lib's headers and the
+ library itselg.
+
+ --with-freetype
+ --with-freetype-headers=DIRECTORY
+ --with-freetype-library=DIRECTORY
+ The option --with-freetype enables support for TrueType fonts. Notice
+ that support for these fonts is not enabled by default. The other two
+ options tell `configure' where to find FreeType's headers and the
+ library itself.
+
+ --disable-nls
+ If you don't want MDVI to support languages other than english.
+
+Note: I have had problems during the final link against the kpathsea
+library on Solaris if the library was compiled with gcc, and MDVI is
+compiled with Sun's cc. To solve the problem, just use the commands
+
+ $ ar x `gcc --print-libgcc-file-name` _eprintf.o
+
+and add `_eprintf.o' to KPSE_LIBS in the Makefile. Then the link should be
+successful. It shouldn't be hard to make `configure' detect this, but I
+don't think it's worth it. If you do, let me know.
+
+Fonts
+=====
+
+To use Type1/TrueType fonts, MDVI needs PostScript fontmaps. These are
+usually distributed with dvips and pdftex, but you can get them separately
+from MDVI's ftp site (see above). Please notice that you need to have a
+correct fontmap entry for *each* font you want to use, or the output will be
+incorrect.
+
+Using MDVI
+==========
+
+MDVI's UI is a bit primitive by today's standards, but it is easy to learn
+and powerful. It is driven exclusively with the keyboard, although some
+functionality is bound to the mouse. All the parameters that affect the
+reading and rendering of DVI files can be specified in the command line, and
+also via environment variables. To see a list of these variables, run mdvi
+with the `--info' option.
+
+Keyboard commands
+-----------------
+
+Although some of this commands may be considered rather exotic, to say the
+least, they exist mostly to test the basic DVI interpreter and the rendering
+engine.
+
+Keyboard commands without arguments:
+
+ PageUp/PageDown go to previous/next page
+ Control+PageUp go to the first page
+ Control+PageDown go to the last page
+ Up/Down/Left/Right scroll the window in the given direction
+ (the movement rate can be reduced by holding
+ the Shift key while pressing the direction
+ key, and further reduced by holding the
+ Control key).
+ Control+Fn save the displayed page number
+ Fn restore a saved page number
+ q quits MDVI
+ b switches between human and TeX's eyes
+ a toggles glyph antialiasing
+ l redraws the page
+ L reloads the DVI file from disk
+ R rotates the page clockwise by 90 degrees
+ r rotates the page counter-clockwise
+ F flips the page vertically
+ f flips the page horizontally
+ ? displays a summary of keyboard commands on
+ standard output (sorry, but this is all the
+ online help available at this point).
+
+Keyboard commands that accept a numeric argument:
+
+The argument is typed before pressing the specified key. You will not see
+it, but it'll be there. Some commands accept negative or even
+floating point numbers.
+
+ Command Description Neg Pos Floats
+ p go to current page + ARG yes yes truncated
+ j jump to page number ARG (last+ARG if negative) yes yes truncated
+ t jump to TeX's page number ARG yes yes truncated
+ d change resolution no yes truncated
+ m change magnification no yes yes
+ x change horizontal shrinking ratio no yes truncated
+ y change vertical shrinking ratio no yes truncated
+ n change pixel density (for bitmap shrinking) no yes truncated
+ g change gamma correction (for antialiased glyphs) no yes yes
+
+where `truncated' means that all the decimal digits are dropped. Be advised
+that changing the resolution or the magnification may take some time,
+because fonts may need to be recreated by kpathsea. Also, not all fonts
+support arbitrary resolutions (Type1 and TrueType fonts do, as far as I
+know), and kpathsea may fail with a message saying that it is not able to
+guess the MF mode from the specified resolution. Using the --mfmode option
+might help.
+
+Mouse usage
+-----------
+
+ Button 1 displays a ruler that can be moved around the page
+ Button 1 + Shift displays a horizontal ruler only
+ Button 1 + Control displays a vertical ruler only