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/dvi2bitmap/doc | |
Initial commit
Diffstat (limited to 'dviware/dvi2bitmap/doc')
30 files changed, 2959 insertions, 0 deletions
diff --git a/dviware/dvi2bitmap/doc/Makefile.am b/dviware/dvi2bitmap/doc/Makefile.am new file mode 100644 index 0000000000..15f3868255 --- /dev/null +++ b/dviware/dvi2bitmap/doc/Makefile.am @@ -0,0 +1,29 @@ +## Process this file with automake to produce Makefile.in + +XSLTPROC=@XSLTPROC@ + +XML2HTML=xml2html +include xml2html/Makefile + + +doc.html: doc.xhtml style.css +# ReleaseNotes.xml is for pre-1.0 releases +doc.xhtml: doc.xml doc.img version.ent + +doc-m.tex: doc.xml + $(XSLTPROC) --stringparam target m xml2html/structure.xslt doc.xml | \ + sed -e 's/</</g' -e 's/>/>/g' -e 's/&/\&/g' >doc-m.tex +doc.img: doc-m.tex + rm -Rf doc.img; mkdir doc.img + cp doc-m.tex doc.img + cd doc.img; tex doc-m + cd doc.img; ../../dvi2bitmap --magnification=3 --scaledown=3 --output-type=gif doc-m + +style.css: + cp ../html/style.css . + +version.ent: Makefile + rm -f version.ent + echo '<!ENTITY version "$(PACKAGE_VERSION)">' >version.ent + +CLEANFILES=doc.html doc.xhtml doc-m.tex style.css diff --git a/dviware/dvi2bitmap/doc/Makefile.in b/dviware/dvi2bitmap/doc/Makefile.in new file mode 100644 index 0000000000..d1aa56a054 --- /dev/null +++ b/dviware/dvi2bitmap/doc/Makefile.in @@ -0,0 +1,484 @@ +# Makefile.in generated by automake 1.14.1 from Makefile.am. +# @configure_input@ + +# Copyright (C) 1994-2013 Free Software Foundation, Inc. + +# This Makefile.in is free software; the Free Software Foundation +# gives unlimited permission to copy and/or distribute it, +# with or without modifications, as long as this notice is preserved. + +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY, to the extent permitted by law; without +# even the implied warranty of MERCHANTABILITY or FITNESS FOR A +# PARTICULAR PURPOSE. + +@SET_MAKE@ + +# Include this Makefile to include the following rules. +# Before inclusion, set the XML2HTML variable to be the path to this directory. +#XML2HTML=. +VPATH = @srcdir@ +am__is_gnu_make = test -n '$(MAKEFILE_LIST)' && test -n '$(MAKELEVEL)' +am__make_running_with_option = \ + case $${target_option-} in \ + ?) ;; \ + *) echo "am__make_running_with_option: internal error: invalid" \ + "target option '$${target_option-}' specified" >&2; \ + exit 1;; \ + esac; \ + has_opt=no; \ + sane_makeflags=$$MAKEFLAGS; \ + if $(am__is_gnu_make); then \ + sane_makeflags=$$MFLAGS; \ + else \ + case $$MAKEFLAGS in \ + *\\[\ \ ]*) \ + bs=\\; \ + sane_makeflags=`printf '%s\n' "$$MAKEFLAGS" \ + | sed "s/$$bs$$bs[$$bs $$bs ]*//g"`;; \ + esac; \ + fi; \ + skip_next=no; \ + strip_trailopt () \ + { \ + flg=`printf '%s\n' "$$flg" | sed "s/$$1.*$$//"`; \ + }; \ + for flg in $$sane_makeflags; do \ + test $$skip_next = yes && { skip_next=no; continue; }; \ + case $$flg in \ + *=*|--*) continue;; \ + -*I) strip_trailopt 'I'; skip_next=yes;; \ + -*I?*) strip_trailopt 'I';; \ + -*O) strip_trailopt 'O'; skip_next=yes;; \ + -*O?*) strip_trailopt 'O';; \ + -*l) strip_trailopt 'l'; skip_next=yes;; \ + -*l?*) strip_trailopt 'l';; \ + -[dEDm]) skip_next=yes;; \ + -[JT]) skip_next=yes;; \ + esac; \ + case $$flg in \ + *$$target_option*) has_opt=yes; break;; \ + esac; \ + done; \ + test $$has_opt = yes +am__make_dryrun = (target_option=n; $(am__make_running_with_option)) +am__make_keepgoing = (target_option=k; $(am__make_running_with_option)) +pkgdatadir = $(datadir)/@PACKAGE@ +pkgincludedir = $(includedir)/@PACKAGE@ +pkglibdir = $(libdir)/@PACKAGE@ +pkglibexecdir = $(libexecdir)/@PACKAGE@ +am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd +install_sh_DATA = $(install_sh) -c -m 644 +install_sh_PROGRAM = $(install_sh) -c +install_sh_SCRIPT = $(install_sh) -c +INSTALL_HEADER = $(INSTALL_DATA) +transform = $(program_transform_name) +NORMAL_INSTALL = : +PRE_INSTALL = : +POST_INSTALL = : +NORMAL_UNINSTALL = : +PRE_UNINSTALL = : +POST_UNINSTALL = : +build_triplet = @build@ +host_triplet = @host@ +DIST_COMMON = $(srcdir)/xml2html/Makefile $(srcdir)/Makefile.in \ + $(srcdir)/Makefile.am +subdir = doc +ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 +am__aclocal_m4_deps = $(top_srcdir)/m4/libtool.m4 \ + $(top_srcdir)/m4/ltoptions.m4 $(top_srcdir)/m4/ltsugar.m4 \ + $(top_srcdir)/m4/ltversion.m4 $(top_srcdir)/m4/lt~obsolete.m4 \ + $(top_srcdir)/configure.ac +am__configure_deps = $(am__aclocal_m4_deps) $(CONFIGURE_DEPENDENCIES) \ + $(ACLOCAL_M4) +mkinstalldirs = $(install_sh) -d +CONFIG_HEADER = $(top_builddir)/config.h +CONFIG_CLEAN_FILES = +CONFIG_CLEAN_VPATH_FILES = +AM_V_P = $(am__v_P_@AM_V@) +am__v_P_ = $(am__v_P_@AM_DEFAULT_V@) +am__v_P_0 = false +am__v_P_1 = : +AM_V_GEN = $(am__v_GEN_@AM_V@) +am__v_GEN_ = $(am__v_GEN_@AM_DEFAULT_V@) +am__v_GEN_0 = @echo " GEN " $@; +am__v_GEN_1 = +AM_V_at = $(am__v_at_@AM_V@) +am__v_at_ = $(am__v_at_@AM_DEFAULT_V@) +am__v_at_0 = @ +am__v_at_1 = +SOURCES = +DIST_SOURCES = +am__can_run_installinfo = \ + case $$AM_UPDATE_INFO_DIR in \ + n|no|NO) false;; \ + *) (install-info --version) >/dev/null 2>&1;; \ + esac +am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP) +DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST) +ACLOCAL = @ACLOCAL@ +AMTAR = @AMTAR@ +AM_DEFAULT_VERBOSITY = @AM_DEFAULT_VERBOSITY@ +AR = @AR@ +AUTOCONF = @AUTOCONF@ +AUTOHEADER = @AUTOHEADER@ +AUTOMAKE = @AUTOMAKE@ +AWK = @AWK@ +CC = @CC@ +CCDEPMODE = @CCDEPMODE@ +CFLAGS = @CFLAGS@ +CPP = @CPP@ +CPPFLAGS = @CPPFLAGS@ +CXX = @CXX@ +CXXCPP = @CXXCPP@ +CXXDEPMODE = @CXXDEPMODE@ +CXXFLAGS = @CXXFLAGS@ +CYGPATH_W = @CYGPATH_W@ +DEFS = @DEFS@ +DEPDIR = @DEPDIR@ +DLLTOOL = @DLLTOOL@ +DOXYGEN = @DOXYGEN@ +DOXYGEN_OUTPUT_DIRECTORY = @DOXYGEN_OUTPUT_DIRECTORY@ +DSYMUTIL = @DSYMUTIL@ +DUMPBIN = @DUMPBIN@ +ECHO_C = @ECHO_C@ +ECHO_N = @ECHO_N@ +ECHO_T = @ECHO_T@ +EGREP = @EGREP@ +EXEEXT = @EXEEXT@ +EXTRALO = @EXTRALO@ +FGREP = @FGREP@ +GREP = @GREP@ +INSTALL = @INSTALL@ +INSTALL_DATA = @INSTALL_DATA@ +INSTALL_PROGRAM = @INSTALL_PROGRAM@ +INSTALL_SCRIPT = @INSTALL_SCRIPT@ +INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@ +KPSEWHICH = @KPSEWHICH@ +LD = @LD@ +LDFLAGS = @LDFLAGS@ +LIBOBJS = @LIBOBJS@ +LIBS = @LIBS@ +LIBTOOL = @LIBTOOL@ +LIPO = @LIPO@ +LN_S = @LN_S@ +LTLIBOBJS = @LTLIBOBJS@ +MAKEINFO = @MAKEINFO@ +MAKETEXPK_PATH = @MAKETEXPK_PATH@ +MANIFEST_TOOL = @MANIFEST_TOOL@ +MKDIR_P = @MKDIR_P@ +MKTEXPK_PATH = @MKTEXPK_PATH@ +NM = @NM@ +NMEDIT = @NMEDIT@ +OBJDUMP = @OBJDUMP@ +OBJEXT = @OBJEXT@ +OTOOL = @OTOOL@ +OTOOL64 = @OTOOL64@ +PACKAGE = @PACKAGE@ +PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ +PACKAGE_NAME = @PACKAGE_NAME@ +PACKAGE_STRING = @PACKAGE_STRING@ +PACKAGE_TARNAME = @PACKAGE_TARNAME@ +PACKAGE_URL = @PACKAGE_URL@ +PACKAGE_VERSION = @PACKAGE_VERSION@ +PATH_SEPARATOR = @PATH_SEPARATOR@ +PERL = @PERL@ +RANLIB = @RANLIB@ +RELEASEDATE = @RELEASEDATE@ +SED = @SED@ +SET_MAKE = @SET_MAKE@ +SHELL = @SHELL@ +STRIP = @STRIP@ +TEX = @TEX@ +VERSION = @VERSION@ +XDVI_PATH = @XDVI_PATH@ +XSLTPROC = @XSLTPROC@ +abs_builddir = @abs_builddir@ +abs_srcdir = @abs_srcdir@ +abs_top_builddir = @abs_top_builddir@ +abs_top_srcdir = @abs_top_srcdir@ +ac_ct_AR = @ac_ct_AR@ +ac_ct_CC = @ac_ct_CC@ +ac_ct_CXX = @ac_ct_CXX@ +ac_ct_DUMPBIN = @ac_ct_DUMPBIN@ +am__include = @am__include@ +am__leading_dot = @am__leading_dot@ +am__quote = @am__quote@ +am__tar = @am__tar@ +am__untar = @am__untar@ +bindir = @bindir@ +build = @build@ +build_alias = @build_alias@ +build_cpu = @build_cpu@ +build_os = @build_os@ +build_vendor = @build_vendor@ +builddir = @builddir@ +datadir = @datadir@ +datarootdir = @datarootdir@ +docdir = @docdir@ +dvidir = @dvidir@ +exec_prefix = @exec_prefix@ +host = @host@ +host_alias = @host_alias@ +host_cpu = @host_cpu@ +host_os = @host_os@ +host_vendor = @host_vendor@ +htmldir = @htmldir@ +includedir = @includedir@ +infodir = @infodir@ +install_sh = @install_sh@ +libdir = @libdir@ +libdvi2bitmap_la_version_info = @libdvi2bitmap_la_version_info@ +libexecdir = @libexecdir@ +localedir = @localedir@ +localstatedir = @localstatedir@ +mandir = @mandir@ +mkdir_p = @mkdir_p@ +oldincludedir = @oldincludedir@ +pdfdir = @pdfdir@ +prefix = @prefix@ +program_transform_name = @program_transform_name@ +psdir = @psdir@ +sbindir = @sbindir@ +sharedstatedir = @sharedstatedir@ +srcdir = @srcdir@ +sysconfdir = @sysconfdir@ +target_alias = @target_alias@ +top_build_prefix = @top_build_prefix@ +top_builddir = @top_builddir@ +top_srcdir = @top_srcdir@ +XML2HTML = xml2html +CLEANFILES = doc.html doc.xhtml doc-m.tex style.css +all: all-am + +.SUFFIXES: +$(srcdir)/Makefile.in: $(srcdir)/Makefile.am $(srcdir)/xml2html/Makefile $(am__configure_deps) + @for dep in $?; do \ + case '$(am__configure_deps)' in \ + *$$dep*) \ + ( cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh ) \ + && { if test -f $@; then exit 0; else break; fi; }; \ + exit 1;; \ + esac; \ + done; \ + echo ' cd $(top_srcdir) && $(AUTOMAKE) --foreign doc/Makefile'; \ + $(am__cd) $(top_srcdir) && \ + $(AUTOMAKE) --foreign doc/Makefile +.PRECIOUS: Makefile +Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status + @case '$?' in \ + *config.status*) \ + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh;; \ + *) \ + echo ' cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)'; \ + cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe);; \ + esac; +$(srcdir)/xml2html/Makefile: + +$(top_builddir)/config.status: $(top_srcdir)/configure $(CONFIG_STATUS_DEPENDENCIES) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh + +$(top_srcdir)/configure: $(am__configure_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(ACLOCAL_M4): $(am__aclocal_m4_deps) + cd $(top_builddir) && $(MAKE) $(AM_MAKEFLAGS) am--refresh +$(am__aclocal_m4_deps): + +mostlyclean-libtool: + -rm -f *.lo + +clean-libtool: + -rm -rf .libs _libs +tags TAGS: + +ctags CTAGS: + +cscope cscopelist: + + +distdir: $(DISTFILES) + @srcdirstrip=`echo "$(srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + topsrcdirstrip=`echo "$(top_srcdir)" | sed 's/[].[^$$\\*]/\\\\&/g'`; \ + list='$(DISTFILES)'; \ + dist_files=`for file in $$list; do echo $$file; done | \ + sed -e "s|^$$srcdirstrip/||;t" \ + -e "s|^$$topsrcdirstrip/|$(top_builddir)/|;t"`; \ + case $$dist_files in \ + */*) $(MKDIR_P) `echo "$$dist_files" | \ + sed '/\//!d;s|^|$(distdir)/|;s,/[^/]*$$,,' | \ + sort -u` ;; \ + esac; \ + for file in $$dist_files; do \ + if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \ + if test -d $$d/$$file; then \ + dir=`echo "/$$file" | sed -e 's,/[^/]*$$,,'`; \ + if test -d "$(distdir)/$$file"; then \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + if test -d $(srcdir)/$$file && test $$d != $(srcdir); then \ + cp -fpR $(srcdir)/$$file "$(distdir)$$dir" || exit 1; \ + find "$(distdir)/$$file" -type d ! -perm -700 -exec chmod u+rwx {} \;; \ + fi; \ + cp -fpR $$d/$$file "$(distdir)$$dir" || exit 1; \ + else \ + test -f "$(distdir)/$$file" \ + || cp -p $$d/$$file "$(distdir)/$$file" \ + || exit 1; \ + fi; \ + done +check-am: all-am +check: check-am +all-am: Makefile +installdirs: +install: install-am +install-exec: install-exec-am +install-data: install-data-am +uninstall: uninstall-am + +install-am: all-am + @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am + +installcheck: installcheck-am +install-strip: + if test -z '$(STRIP)'; then \ + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + install; \ + else \ + $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \ + install_sh_PROGRAM="$(INSTALL_STRIP_PROGRAM)" INSTALL_STRIP_FLAG=-s \ + "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'" install; \ + fi +mostlyclean-generic: + +clean-generic: + -test -z "$(CLEANFILES)" || rm -f $(CLEANFILES) + +distclean-generic: + -test -z "$(CONFIG_CLEAN_FILES)" || rm -f $(CONFIG_CLEAN_FILES) + -test . = "$(srcdir)" || test -z "$(CONFIG_CLEAN_VPATH_FILES)" || rm -f $(CONFIG_CLEAN_VPATH_FILES) + +maintainer-clean-generic: + @echo "This command is intended for maintainers to use" + @echo "it deletes files that may require special tools to rebuild." +clean: clean-am + +clean-am: clean-generic clean-libtool mostlyclean-am + +distclean: distclean-am + -rm -f Makefile +distclean-am: clean-am distclean-generic + +dvi: dvi-am + +dvi-am: + +html: html-am + +html-am: + +info: info-am + +info-am: + +install-data-am: + +install-dvi: install-dvi-am + +install-dvi-am: + +install-exec-am: + +install-html: install-html-am + +install-html-am: + +install-info: install-info-am + +install-info-am: + +install-man: + +install-pdf: install-pdf-am + +install-pdf-am: + +install-ps: install-ps-am + +install-ps-am: + +installcheck-am: + +maintainer-clean: maintainer-clean-am + -rm -f Makefile +maintainer-clean-am: distclean-am maintainer-clean-generic + +mostlyclean: mostlyclean-am + +mostlyclean-am: mostlyclean-generic mostlyclean-libtool + +pdf: pdf-am + +pdf-am: + +ps: ps-am + +ps-am: + +uninstall-am: + +.MAKE: install-am install-strip + +.PHONY: all all-am check check-am clean clean-generic clean-libtool \ + cscopelist-am ctags-am distclean distclean-generic \ + distclean-libtool distdir dvi dvi-am html html-am info info-am \ + install install-am install-data install-data-am install-dvi \ + install-dvi-am install-exec install-exec-am install-html \ + install-html-am install-info install-info-am install-man \ + install-pdf install-pdf-am install-ps install-ps-am \ + install-strip installcheck installcheck-am installdirs \ + maintainer-clean maintainer-clean-generic mostlyclean \ + mostlyclean-generic mostlyclean-libtool pdf pdf-am ps ps-am \ + tags-am uninstall uninstall-am + + +%.xhtml: %.xml + rm -f $@ $@.tmp + $(XSLTPROC) --stringparam document-id $$PWD/$< $(XML2HTML)/structure.xslt $< >$@.tmp && mv $@.tmp $@ +%.html: %.xhtml + rm -f $@ $@.tmp + $(XSLTPROC) $(XML2HTML)/identity-html.xslt $< >$@.tmp && mv $@.tmp $@ +%.aux: %.xml + rm -f $@ $(@:=.tmp) + $(XSLTPROC) --stringparam document-id $$PWD/$< \ + --stringparam target aux \ + $(XML2HTML)/structure.xslt $< >$@.tmp && mv $@.tmp $@ + printf '\\bibstyle{unsrthtml}\n' >>$@ +%.bbl: %.aux + BSTINPUTS=$(STYLE) bibtex $< + sed -f $(STYLE)/detex.sed -e '1s+<dl>+<dl xmlns="http://www.w3.org/1999/xhtml">+' $@ >$@.tmp + mv $@.tmp $@ + +doc.html: doc.xhtml style.css +# ReleaseNotes.xml is for pre-1.0 releases +doc.xhtml: doc.xml doc.img version.ent + +doc-m.tex: doc.xml + $(XSLTPROC) --stringparam target m xml2html/structure.xslt doc.xml | \ + sed -e 's/</</g' -e 's/>/>/g' -e 's/&/\&/g' >doc-m.tex +doc.img: doc-m.tex + rm -Rf doc.img; mkdir doc.img + cp doc-m.tex doc.img + cd doc.img; tex doc-m + cd doc.img; ../../dvi2bitmap --magnification=3 --scaledown=3 --output-type=gif doc-m + +style.css: + cp ../html/style.css . + +version.ent: Makefile + rm -f version.ent + echo '<!ENTITY version "$(PACKAGE_VERSION)">' >version.ent + +# Tell versions [3.59,3.63) of GNU make to not export all variables. +# Otherwise a system limit (for SysV at least) may be exceeded. +.NOEXPORT: diff --git a/dviware/dvi2bitmap/doc/doc.html b/dviware/dvi2bitmap/doc/doc.html new file mode 100644 index 0000000000..03c80f0215 --- /dev/null +++ b/dviware/dvi2bitmap/doc/doc.html @@ -0,0 +1,2237 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html xmlns:grddl="http://www.w3.org/2003/g/data-view#" grddl:transformation="http://ns.inria.fr/grddl/rdfa/2008/08/07/RDFa2RDFXML.xsl"> +<head profile="http://www.w3.org/1999/xhtml/vocab"> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<link type="text/css" rel="stylesheet" href="style.css"> +<title>dvi2bitmap – convert DVI files to bitmap images</title> +</head> + +<body> +<h1 property="dc:title">dvi2bitmap – convert DVI files to bitmap images</h1> +<div class="abstract"> +<meta property="dcterms:abstract" about="" content="This application processes a DVI file produced by TeX, converting each page to a single bitmap. The conversion is done directly, rather than through a chain of intermediate file formats, making the process extremely fast. It can produce output as XBM, XPM, GIF and PNG files. "> +<p>This application processes a DVI file produced by +TeX, converting each page to a single bitmap. The conversion is done +directly, rather than through a chain of intermediate file formats, +making the process extremely fast. It can produce output as XBM, XPM, +GIF and PNG files.</p> +</div> + +<div id="toc" class="toc"><ul> +<li><a href="#intro">1 Introduction</a></li> +<li><a href="#usage">2 Usage</a></li> +<li><a href="#usagenotes">3 Usage notes</a></li> +<li><a href="#libdvi2bitmap">4 The libdvi2bitmap library</a></li> +<li><a href="#install">5 Building and installing dvi2bitmap</a></li> +<li><a href="#developments">6 Bugs, extras, and further developments</a></li> +<li><a href="#refs">7 References and acknowledgements</a></li> +<li><a href="#sgml.maths">A Maths and SGML/HTML</a></li> +<li><a href="#tex.dimensions">B TeX dimensions</a></li> +<li><a href="#rn">C Release notes</a></li> +</ul></div> + +<h2><a name="intro">1 Introduction</a></h2> + + +<p><kbd>dvi2bitmap</kbd> converts the typeset output of TeX into a bitmap image.</p> + +<p>The most common use-case is to convert +TeX or LaTeX mathematics to HTML. It is possible to do this with a chain of +general-purpose tools, for example going from DVI to postscript to PNM +files to GIFs, but this is generally slow. For an overview of maths +and SGML/HTML, see <a href="#sgml.maths">A Maths and SGML/HTML</a>.</p> + +<p>The tool dvi2bitmap does this processing in a single step, +reading the DVI file and font files, and emitting a bitmap. +It can, at present, generate XBM, XPM, GIF and, if the +relevant library is installed, PNG files.</p> + +<p>See <a href="#usage">2 Usage</a> for usage instructions, and +<a href="#install.general"></a> for installation instructions.</p> + +<p>The <code>dvi2bitmap</code> application is available for download at +<span class="url">http://purl.org/nxg/dist/dvi2bitmap</span>.</p> + +<p>This document matches version 1.0 of the program (you can +see what version you have with the command <kbd>dvi2bitmap +-V</kbd>). This should currently be regarded as beta +software.</p> + + + +<h2><a name="usage">2 Usage</a></h2> + + +<p>Synopsis:</p> +<pre>dvi2bitmap [flags] dvi-file</pre> +<p>This program is intended to conform to the DVI processing +standard.</p> + +<p>The <code>dvi-file</code> argument is the name of a DVI file to be +converted to a bitmap. dvi2bitmap looks for the file both with and +without the default extension <code>.dvi</code>.</p> + +<p>You may also read the DVI file from the standard input by +giving the DVI file as <code>"-"</code>, thus</p> +<pre>cat myfile.dvi | dvi2bitmap -</pre> +<p>is an alternative way of reading the file (rather pointless in this +case, but it shows the principle; see <a href="#usagenotes.pipe">3.2 Using dvi2bitmap in a pipe</a> +for further discussion). +For more arcane purposes, the DVI file may also be specified as +<code><osfile>dvi-file</code> +(which is entirely equivalent), or +<code><osfd>integer</code>, where the given integer specifies an +open file descriptor; specifying <code>"-"</code> as the input file is +equivalent to <code><osfd>0</code></p> + +<p>The motivation for this program was the need for a helper program +to produce small bitmaps for inclusion in web pages. Accordingly, the +program's underlying usage model is that one would generate a file of +TeX or LaTeX material, convert it to a DVI file using TeX, and +convert the result to a collection of bitmap files. The input +text will typically be equations, but any other TeX material +will work as well. For example, the processor which generates +the HTML could spit out a file such as</p> +<pre>\documentclass{article} +\pagestyle{empty} +\begin{document} +$E=mc^2$ +\newpage +% etc... +\end{document}</pre> +<p>and then this program can scoot through it turning each page +into a bitmap. I had thought about some complicated scheme to +delimit areas on the page, but realised that since the file +being processed would typically be generated on the fly +specifically for processing by a tool like this, this wasn't +really necessary. See <a href="#developments">6 Bugs, extras, and further developments</a> for a script +which can help with this.</p> + +<p>I hope that the program is (or can be made to be) flexible +enough to support other modes of use.</p> + +<h3><a name="usage.options">2.1 Options</a></h3> + + +<p>Various of the options below have common syntax features.</p> +<dl> +<dt><code>[keyword-value-list]</code></dt> +<dd> +<p>This +indicates a sequence of <code>keyword=value</code> pairs, +separated by commas. Not all keywords necessarily have a +value.</p> +</dd> + +<dt><code>[boolean]</code></dt> +<dd><p>This can be `yes', `true' or `on' indicating +<em>true</em>; or `no', `false' or `off' indicating +<em>false</em>.</p></dd> +</dl> + +<p>The options are as follows:</p> +<dl> +<dt><code>-c, --crop=[keyword-value-pairs]</code></dt> +<dd> +<p>The <code>--crop</code> option allows you to control +how the generated bitmaps are cropped before they are +written. The keywords are `left', `right', `top', +`bottom' and `all', and the value in each case is the +number of pixels to leave as a margin. If the keywords +`relative' (default) or `absolute' are present, they refer +to all of the keywords following: if the crop is specified +as `relative', then the values specify the number of +pixels to leave around the blackened pixels of the text; +if the crop is `absolute', then it specifies the position +of the crop (in pixels) from the left or top edge of the +`page'. The specification +<code>----crop=absolute,all=dimen</code>, which would set +all the crops to the same position, is silly, and so is +forbidden.</p> + +<p>The conversion from points to pixels takes account of +the magnification set in the +<code>--magnification</code> option, if that's been +specified already, but it doesn't notice if that's set +after this option, and it takes no account of any +magnification in the DVI file.</p> + +<p>See <a href="#usage.special">2.2 DVI specials</a> for TeX +<code>\special</code> commands which set this within +the TeX file.</p> + +<p>See below for TeX <code>\special</code> commands +which set this within the TeX file.</p> + +</dd> + +<dt><a name="usage.options.fp"> +<code>-F, --font-search=[keyword-value-list]</code> +</a></dt> +<dd> +<p>Specifies how <code>dvi2bitmap</code> is to find +the fonts it needs. Keywords are as follows:</p> + +<p><code>path[=list]</code>: use the given list of +filesystem paths to search for PK fonts, or enable +using the default path, if <code>=path</code> is +missing. The default path is given by the environment +variable <code>DVI2BITMAP_PK_PATH</code>. See also +the discussion of font searching below.</p> + +<p><code>kpathsea</code>: enable using the +<code>kpathsea</code> library to find fonts. If the +program was not built against the +<code>kpathsea</code> library, this option has no +effect.</p> + +<p><code>command[=script]</code>: enable using the given +script to find fonts. If the argument is missing, +this enables using the script configured into the +program at compile-time. This script is any program +which will search the filesystem and produce a single +line on output, giving the full path to the specified +font. For example, this might be given as +<code>kpsewhich pk %f.%dpk</code> to run the +<code>kpsewhich</code> program. The command name is a +font-string template, as described <a href="#usage.fonts.template">2.5.4 Font-string templates</a>.</p> + +<p>If the program does not find a font using whichever +methods have been enabled then, following the pattern +of <code>dvips</code> and other DVIware, it writes a +file <code>missfont.log</code> in the current +directory, containing commands which you can use to +generate the fonts immediately or later.</p> + +<p><code>none</code>: disable all font-searching. The +result is that only the <code>missfont.log</code> file +is written.</p> + +<p>Each of the keywords can be prefixed by `no' to turn +off the corresponding option -- thus +<code>--font-search=nopath,nokpathsea,nocommand</code> +has the same effect as +<code>--font-search=none</code>.</p> +</dd> + +<dt> +<code>-G, --font-gen=[boolean], --font-gen=command[=script]</code> +</dt> +<dd> +<p>Switch automatic generation of fonts off and on. If +<code>--font-gen=command</code> is given, then the +command specified at compile time is used to generate +fonts. If, further, a font-generation script is +specified, then it will be used instead of the +default. The specified script is a font-string +template, as described below. The default for +automatic font generation is set at compile time.</p> +</dd> + +<dt><a name="usage.options.g"><code>-g, --debug=[spec]</code></a></dt> +<dd> +<p>Switch on debugging. The <code>[spec]</code> is a +list of letters indicating what to debug, as follows. +You may trace bitmap generation (`b'), DVI file parsing +(`d'), input (`i'), the main program (`m'), PK file +searching and parsing (`p'), font rasterdata parsing +(`r'), or various utility functions (`u', though this is +actually only useful for the maintainer). If kpathsea +is compiled in, then debugging PK files switches on +kpathsea debugging also. Adding an extra `g' at the +beginning of the spec increases +still further the amount of debugging code. The +debugging information may be uninformative or +unintelligible; it might even crash the program (mention +that to me).</p> + +</dd> + +<dt><code>-h, --height=size; -w, --width=size</code></dt> +<dd> +<p>Specify the height and width of the canvas on which +the output bitmap is painted. The program tries to +make an estimate of this based on information within +the DVI file, but it can't efficiently get all the +information it needs, so sometimes the estimate is +wrong. If you get a warning message like +<code>Warning: p.12: bitmap too big: occupies +(1183,1072)...(4134,6255). Requested 4100x6200</code> +then you'll need to specify a bitmap size. The +numbers <code>(1183,1072)...(4134,6255)</code> are the +coordinates of the top-left and bottom-right of the +bitmap: in this case <code>--height=6300 +--width=4200</code> would suffice. At some point, I'd +like to make the bitmap `expandable', obviating the +need for these options.</p> +</dd> + +<dt><code>--help</code></dt> +<dd> +<p>Display outline help for the options on stderr, and +exit</p> +</dd> + +<dt><code>-l, --end-page</code></dt> +<dd> +<p>See option <code>--start-page</code></p> +</dd> + +<dt><a name="usage.options.fm"><code>-M, +--font-mode=[mode]</code></a></dt> +<dd> +<p>Set the MetaFont mode which is used for generating +font files. The default is <code>ibmvga.</code> If +you set this, you will probably have to set the +resolution to a consistent number.</p> +</dd> + +<dt><code>-m, --magnification=[number]</code></dt> +<dd> +<p>The TeX magnification parameter which is used when +processing the DVI file. It is a float, with 1.0 +corresponding to no magnification (the default). This +interacts with the resolution as follows: if you +specify a resolution of 100, and a magnification of 2, +then <code>dvi2bitmap</code> will search for PK files +at 200 dpi.</p> +</dd> + +<dt><code>-n, --nodvi</code></dt> +<dd> +<p>Do not actually process the DVI file, but read the +DVI pre- and postamble. Useful in conjunction with +the <code>--query</code> options. If this option is +present, then the program returns non-zero if any +fonts were missing (see also <a href="#usage.exit">2.3 Exit value</a>). +The <code>-n</code> is for brevity and consistency +with other tools -- the behaviour can be alternatively +specified as <code>--process=nodvi</code></p> +</dd> + +<dt><a name="usage.options.output"><code>-o, +--output=[filename-pattern]</code></a></dt> +<dd> +<p>Choose the output filename pattern. The value is a +`printf' formatting string, with a single +<code>%d</code> formatting descriptor, which will be +replaced in output filenames with the page number. If +there is no such descriptor, the filename `pattern' is +used as-is for the first filename output, after which +the program reverts to the default filename pattern. +The filename pattern can be overridden on a per-page +basis by a TeX <code>\special</code> embedded in the +DVI file (see <a href="#usage.special.opf"></a> in <a href="#usage.special">2.2 DVI specials</a>). If there is no file extension, +or if it does not match the output type, a suitable +file extension will be added.</p> +</dd> + +<dt><code>--pipe</code></dt> +<dd> +<p>Indicates that the dvi-file argument is a +non-seekable file, such as a named or unnamed pipe. +This is automatically the case if you specify the DVI +file as stdin, "-".</p> +</dd> + +<dt> +<code>-p, --start-page=num</code>, +<code>-l, --end-page=num</code>, +<code>-P, --page-range=[spec]</code> +</dt> +<dd> +<p>These select page ranges, using a slight extension of +the notation used by <code>dvips</code> (and the same +option letters, except that <code>dvips</code> uses +<code>-pp</code> instead of <code>-P</code>).</p> + +<p>The <code>--start-page=snum</code> and +<code>--end-page=enum</code> options take single page +numbers; if either of these is given, then the program +will process pages from page <code>snum</code> to page +<code>enum</code>, with the defaults being the +corresponding extremes. The <code>[spec]</code> +consists of a comma-separated sequence of page numbers +and ranges (<code>a-b</code>); only those pages, and +the pages falling in those ranges (inclusive of the +end pages) are processed. Any of these specifications +may be prefixed by either <code>=</code> or +<code>:n:</code>. In the former case, DVI page +numbers are used rather than the TeX +<code>\count</code><img src="doc.img/m-175.gif"> register; in the latter +case, the program examines the +<code>\count</code><img src="doc.img/m-177.gif"> register rather than the +default <code>\count</code><img src="doc.img/m-179.gif"></p> + +<p>You can specify both of these prefixes one or more +times, but you cannot mix the +<code>--start-page</code> and <code>--end-page</code> +options with the <code>--page-range</code> option. +The program will respect only the last +<code>--start-page</code> and <code>--end-page</code> +options, but the <code>--page-range</code> options are +cumulative. There may be no spaces in the +<code>pagelist</code>. The page numbers may be +negative.</p> + +<p>Examples:</p> +<pre>dvi2bitmap --page-range=3,6-10 ...</pre> +<p>process only the specified pages</p> + +<pre>dvi2bitmap --page-range=:2:1 ...</pre> +<p>process only pages where <code>\count2</code> was 1.</p> +</dd> + +<dt><a name="usage.options.q"><code>-Q, +--query=[keyword-list]</code></a></dt> +<dd> +<p>Query various things. The available possibilities +are as given below. The results of each of the +queries is printed on a line by itself, prefixed by a +`Q', the keyword and a space, so that, for example, +each of the lines produced by the +<code>--query=missing-fonts</code> option would start +<code>Qmissing-fonts cmbx10 110 ...</code></p> + +<p>Some of these options +(<code>--query=missing-fonts</code> and +<code>--query=missing-fontgen</code>) are probably +most useful with the <code>-n</code> or +<code>--process=options</code> options, to investigate +a DVI file before processing. Others +(<code>--query=types</code> and +<code>--query=paper</code>) are probably useful only +with <code>--process=options</code>. The option +<code>--query=bitmaps</code> is only useful if you do +actually generate bitmaps. For consistency (and so +you don't have to remember which ones do which), the +appropriate <code>--process</code> option is +<em>not</em> implied in any of them, and you have to +give it explicitly.</p> + +</dd> + +<dt><code>--query=bitmaps</code></dt> +<dd> +<p>Prints on stdout a line for each bitmap it generates, +giving the filename, horizontal size, and vertical +size, in pixels. This also reports the position of +any `mark' in the bitmap -- see <a href="#usage.special.mark"></a>.</p> +</dd> + +<dt><code>-Qf, --query=missing-fonts</code></dt> +<dd> +<p>Show missing fonts. The program writes on standard +output one line per missing font, starting with +<code>Qf</code> or <code>Qmissing-fonts</code> +(depending on which of the variants was given -- the +shorter ones are less mnemonic, but more convenient to +parse in scripts), then five fields: the font name, +the DPI value it was looking for, the base-DPI of the +font, the magnification factor, and a dummy metafont +mode. This output might be massaged for use with the +mktexpk (TeXLive) or MakeTeXPK (teTeX) scripts to +generate the required fonts, but +<code>--query=missing-fontgen</code> is more +straightforward.</p> +</dd> + +<dt><code>-QF, --query=all-fonts</code></dt> +<dd> +<p>As for <code>--query=missing-fonts</code> except that found +fonts are also listed, all prefixed by +<code>Qall-fonts</code></p> +</dd> + +<dt><code>-Qg, --query=missing-fontgen</code></dt> +<dd> +<p>As for <code>--query=missing-fonts</code>, except +that the output consists of the string +<code>Qmissing-fontgen</code> followed by a +<code>mktexpk</code> or <code>MakeTeXPK</code> command +which can be used to generate the font.</p> +</dd> + +<dt><code>-QG, --query=all-fontgen</code></dt> +<dd> +<p>As for <code>--query=missing-fonts</code>, except that +font-generation commands for found fonts are also listed, prefixed by +<code>Qall-fontgen.</code></p> + +<p><em>Note</em>: Only one of +<code>--query=missing-fonts</code>, +<code>--query=all-fonts</code>, +<code>--query=missing-fontgen</code> and +<code>--query=all-fontgen</code> should be specified +-- if more than one appears, only the last one is +respected -- if more than one appears, only the last +one is respected. In each of these four cases, plus +their short forms, font-generation is automatically +suppressed. This is probably what you want (it's not +obvious why you're querying this otherwise), but if +you do not want this, then you can reenable font +generation with <code>--font-gen=true</code></p> +</dd> + +<dt><code>--query=paper</code></dt> +<dd> +<p>Show the list of paper sizes which are predefined for the +<code>--paper-size</code> option.</p> +</dd> + +<dt><code>--query=types</code></dt> +<dd> +<p>List the output image formats which the program can +generate, on stdout, separated by whitespace. The +first output format is the default.</p> +</dd> + +<dt><code>-r, --resolution=[number]</code></dt> +<dd> +<p>Specifies the output resolution, in pixels-per-inch. +This is used when deciding which PK files to use. The +default is 110, which matches the default +<code>ibmvga</code> metafont mode.</p> +</dd> + +<dt><a name="usage.options.r"><code>-R, +--colours=[keyword-value-list], +--colors=[keyword-value-pairs]</code></a></dt> +<dd> +<p>Specifies the foreground or background colours, as +RGB triples. The keywords are either +<code>foreground</code> or <code>background</code>, +and the values are a triple of integers separated by +slashes, for example +<code>--colours=foreground=127/127/255</code>. The +integers must be in the range [0,255], and can be +specified in decimal, octal or hex (for example +<code>127=0177=0x7f</code>), or else the whole spec +may be of the form <code>#rrggbb</code>, where `rr', +`gg' and `bb' are each a pair of hex digits.</p> +</dd> + +<dt><code>-s, --scaledown=[number]</code></dt> +<dd> +<p>Reduces the linear size of the output bitmap by the +given factor (default 1).</p> +</dd> + +<dt><code>-T, --output=type=[type]</code></dt> +<dd> +<p>Choose the output format, which can be +<code>png</code>, <code>gif</code>, <code>xpm</code> +or <code>xbm</code>. The program generates XBM +bitmaps by default, and has simple support for XPM. +The GIF and PNG options may not be available if they +weren't selected when the program was configured.</p> +</dd> + +<dt><code>-t, --paper-size=papersize</code></dt> +<dd> +<p>Set the initial size of the bitmap to be one of the +paper sizes returned by <code>--query=paper</code>. +This is useful either to make sure that there is +enough room on the initial bitmap, to avoid the +warning above, or, along with the +<code>--process=nocrop</code> option, to force the +output bitmap to be a certain size.</p> +</dd> + +<dt><code>-v, --verbose=[quiet|silent]</code></dt> +<dd> +<p>Quiet mode suppresses some chatter, and silent mode suppresses +chatter, and does not display warnings or errors +either.</p> +</dd> + +<dt><code>-V, --version</code></dt> +<dd> +<p>Display the version number and compilation options, +and exit.</p> +</dd> + +<dt><code>-X, --process=[keyword-value-list]</code></dt> +<dd> +<p>Specifies the processing to be done. Keywords are as +follows:</p> + +<p><code>dvi</code> and <code>nodvi</code> : enable or +disable processing of the DVI file. If disabled, we +do not require a DVI file to be present on the command +line. The <code>nodvi</code> option is useful with +some of the <code>--query</code> options.</p> + +<p><code>postamble</code> and <code>nopostamble</code>: +enable or disable processing of the DVI postamble. If +dvi2bitmap is called to invoke a non-seekable device +such as a pipe, you should disable processing of the +postamble. Disabling the postamble processing is +incompatible with the <code>--query</code> options +which examine the fonts in the file. By default, both +the DVI body and the postamble are processed.</p> + +<p><code>--process=options</code>: shorthand for +<code>--process=nopreamble,nodvi,nopostamble</code>. +Only the options are examined.</p> + +<p><code>blur</code> and <code>noblur</code>: if true, +blurs the bitmap, making a half-hearted attempt to +make a low-resolution bitmap look better. This really +isn't up to much -- if you have the fonts available, +or are prepared to wait for them to be generated, a +better way is to use the <code>--magnification</code> +option to magnify the DVI file, and then the +<code>--scale</code> option to scale it back down to +the correct size.</p> + +<p><code>transparent</code> and +<code>notransparent</code>: if true, this makes the +output bitmap have a transparent background, if that's +supported by the particular format you choose using +option <code>--output-type</code></p> + +<p><code>crop</code> and <code>nocrop</code>: if true, +specifies that you want the output bitmap to be +cropped. This is true by default, so you'll most +often use the <code>crop=false</code> to specify that +you do not want the output cropped (for example, if +you're using the <code>--paper-size</code> option and +want the output to stay the specified size).</p> + +<p>By default, bitmaps are not blurred, are cropped, and +are transparent if possible.</p> + +<p>For PNG files, the output bitmap uses a palette plus +an alpha channel; these are calculated in such a way +that if you display the resulting bitmap on the same +colour background as <code>dvi2bitmap</code> was using +(which is white by default, but can be specified using +the <a href="#usage.special.fg"></a>) then the result should look identical +to the result with no transparency information, but +probably progressively worse the further the +background moves from this. I suppose, but can't at +present check, that this implies that you should +choose a mid-grey background colour when making such +transparent PNGs. I'd welcome advice on this +point.</p> +</dd> +</dl> + + +<h3><a name="usage.special">2.2 DVI specials</a></h3> + + +<p>dvi2bitmap recognises several DVI special commands, and emits a +warning if it finds any others.</p> + +<p>The syntax of the special commands is</p> +<pre>\special{dvi2bitmap <special-command>+ }</pre> +<p>There may be one or more <code><special-command></code> +sequences within a single special.</p> + +<p>The <code><special-command></code> which the program +recognises are:</p> +<dl> +<dt><code>default</code></dt> +<dd><p>Makes other special-commands in this same special affect +defaults. See those commands for details.</p></dd> + +<dt><a name="usage.special.opf"><code>outputfile <filename></code></a></dt> +<dd> +<p>The output file used for the current page will be +named <code>filename.gif</code> (if the output type +were `gif'). A filename extension will be added if +none is present, or if it does not match the output +type selected.</p> + +<p>If the <code>default</code> command has been given, +then this instead specifies the default filename +pattern, and the `filename' should contain a single +instance of either <code>%d</code> or <code>#</code>; +if there is no such instance, one will be implicitly +added at the end.</p> + +<p>The <code>%d</code> is precisely analogous to the +behaviour of the <a href="#usage.options.output"></a> option. +However it is actually rather tricky to get an +unadorned percent character into a TeX special, unless +you play catcode tricks, and this is why you may +alternatively include a <code>#</code> character to +indicate where the page number should go. In fact, +since it is <em>also</em> rather tricky to get a +single <code>#</code> character in a special, any +immediately following <code>#</code> characters are +ignored. Thus the recommended way of specifying this +special is through something of the form</p> +<pre> +\special{dvi2bitmap default outputfile myfile-#} +</pre> +<p>using the <code>#</code> form, +and letting the file extension be controlled by the +output type which is actually used.</p> +</dd> + +<dt><code>absolute</code></dt> +<dd> +<p>Affects the <code>crop</code> command.</p> +</dd> + +<dt><code>crop <side> <dimen></code></dt> +<dd> +<p>Crop the bitmap on the current page so that the +specified edge of the bitmap is +<code><dimen></code> points away from the +bounding box of the blackened pixels. +<code><side></code> may be one of `left', +`right', `top', `bottom' or `all', referring to the +corresponding edge, or all four edges at once. If the +<code>default</code> command has been given in this +special, then this pattern of cropping is additionally +made the default for subsequent pages. If the +<code>absolute</code> command has been given, then the +crop position is set at <code><dimen></code> +points from the appropriate edge of the `paper'.</p> + +<p>The <code>-c</code> and <code>-C</code> command-line +options (<a href="#usage.options">2.1 Options</a>) have the effect of +setting initial defaults. In the absence of either of +these, the initial crop is exactly at the bounding +box.</p> +</dd> + +<dt><code>default imageformat <format></code></dt> +<dd> +<p>Set the default image format, which should be one of +the keywords `xbm', `xpm' `gif', `png'. This is +equivalent to specifying the image format through the +<code>-t</code> option (section <a href="#usage.options">2.1 Options</a>).</p> + +<p>The keyword is just <code>imageformat</code>, but you +must specify the <code>default</code> keyword when you +specify <code>imageformat</code>; this is for +consistency, and makes it clear that this is setting a +default format rather than setting the format only for +the next image (that's not implemented at present, but +could be added).</p> +</dd> + +<dt><a name="usage.special.fg"><code>default foreground|background +<red> <green> <blue></code> </a></dt> +<dd> +<p>Sets the (default) foreground and background colours +for text. This works, as long as you specify the +colour change before any text is output, since you +can't, at present, change the colours after that. +Specifically, you can't change the colours for a +fragment of text in the middle of a page; for this +reason, and as with <code>imageformat</code> you +should at present always include the +<code>default</code> keyword when using this +special. The integers must be in the range +[0,255], and can be specified in decimal, octal or +hex (ie, <code>127=0177=0x7f</code>).</p> +</dd> + +<dt><code>strut <left> <right> <top> +<bottom></code></dt> +<dd> +<p>This places a `strut' in the +generated file. Using the usual TeX +<code>\strut</code> won't work: that would leave the +appropriate space when TeXing the file, but that space +doesn't explicitly appear in the DVI file (which is +just a bunch of characters and locations), so when +<code>dvi2bitmap</code> fits its tight bounding box to +the blackened pixels in the file, it knows nothing of +the extra space you want.</p> + +<p>The `strut' special forces the bounding box to be at +least `left', `right', `top' and `bottom' points away +from the position in the file where this special +appears. All the dimensions must be positive, and +they are floats rather than integers.</p> + +<p>If you wanted to set a page containing only the maths +`<code>${}^\circ$</code>' (why, is another matter), +<code>dvi2bitmap</code> would normally make a tight +bounding box for the bitmap, so that you'd get an +image containing only the circle (unless other crop +options were in force). If, in this case, you put in +a special such as <code>\special{dvi2bitmap strut 0 2 +10 2.5}</code>, you would force the bounding box to +come no closer than 0pt to the left of the position in +the file where this special appears, 2pt to the right, +10pt above and 2.5pt below.</p> + +<p>A useful bit of TeX magic is:</p> +<pre>{\catcode`p=12 \catcode`t=12 \gdef\DB@PT#1pt{#1}} +\def\DBstrut{\strut\special{dvi2bitmap strut 0 0 +\expandafter\DB@PT\the\ht\strutbox\space\expandafter\DB@PT\the\dp\strutbox}} +</pre> +<p>Once you've done that, the command +<code>\DBstrut</code> will put an appropriate strut in +the output.</p> +</dd> + +<dt><a name="usage.special.mark"><code>mark</code></a></dt> +<dd> +<p>This sets a `mark' in the generated file, which is +reported when you specify <code>--query=bitmaps</code> +(see <a href="#usage.options.q"></a>). Normally, +<code>--query=bitmaps</code> writes out the horizontal +and vertical size of the generated bitmap. If use of +this special has placed a `mark' in the bitmap, +however, then the <code>--query</code> option also +reports the position of that mark, as a position +within the bitmap, such that the top-left corner of +the bitmap has coordinates <img src="doc.img/m-429.gif">. For +example, after</p> +<pre> +\noindent\special{dvi2bitmap mark}Hello +</pre> +<p>the command line</p> +<pre>dvi2bitmap --query=bitmaps foo +</pre> +<p>might report</p> +<pre> +Qbitmaps foo-page1.png 80 14 -1 10 +</pre> +<p>indicating that the bitmap is 80 pixels +wide by 14 high, and that the reference point, after +cropping, is at position <img src="doc.img/m-436.gif">. The `-1' +is because the mark appears to the left of the `H' of +`Hello' (and the `H' probably has some negative +offset), and the `10' indicates that the baseline of +this text is 10 pixels from the top of the bitmap; +this latter information might be useful when working +out how to position this bitmap within a generated +HTML file. See <a href="#usagenotes.marks">3.4 Using marks to position bitmaps</a> for a +discussion of how to do that.</p> + +<p>Both here and in the support for the `strut' special, +there is a great deal of scope for off-by-one errors; +also it's unclear what is the best interface to this +functionality, so it's possible that this might change +in subsequent versions. The author welcomes +comments.</p> +</dd> + +<dt><a name="usage.special.unit"><code>unit +<u></code></a></dt> +<dd> +<p>The units in the `strut' and `crop' specials are by +default in TeX points. You may switch to a different +unit with the `unit' special. The specifier `u' gives +a unit name, which may be selected from the set of +units TeX knows about (`pt', `bp', `cm', and so on), +plus `pixels', and `dvi' to select DVI file units +(usually the same as `sp'). If the `default' +qualifier is present, this setting applies to +subsequent special strings as well.</p> +</dd> + +</dl> + +<p>For example, the pair of commands</p> +<pre>\special{dvi2bitmap default outputfile trial-# unit pc crop all 5} +\special{dvi2bitmap absolute crop left 5} +</pre> +<p>will change the output filename pattern for the rest of the DVI file, +and set a 5pc margin round the bounding box. The current page, +however, will have a left-hand crop five points in from the left hand +side. Remember that TeX's origin is one inch from the left and the +top of the paper, and it is with respect to this origin that the +program reckons the absolute distances for the cropping.</p> + + + +<h3><a name="usage.exit">2.3 Exit value</a></h3> + + +<p>Exits with a non-zero status if there were any processing errors. +Having <em>no</em> fonts present counts as a processing error.</p> + +<p>If there is at least one font present, then missing fonts +will be replaced by the first <code>cmr10</code> font it +finds, or a more-or-less randomly chosen alternative if that +font is not used at all. The program will produce a warning +if the <code>-q</code> option is not present, but it will +return with a zero (success) status.</p> + +<p>Exception: If the <code>-n</code> option (see <a href="#usage.options">2.1 Options</a>) is present, then the program returns +success only if <em>all</em> fonts are present. </p> + + + +<h3><a name="usage.examples">2.4 Examples</a></h3> + + +<p>Basic usage examples.</p> + +<pre> +% dvi2bitmap --resolution=110 --magnification=2 --scale=2 \ +--output-type=gif hello.dvi +</pre> +<p>This converts the file <code>hello.dvi</code> to a GIF +bitmap. It first sets the magnification factor to 2, so +that the program uses a double-size font (eg, +<code>.../cmr10.220pk</code>), then scales the bitmap down +by a factor of 2 to obtain a bitmap of the correct size.</p> + +<pre> +% dvi2bitmap -n -Qf --resolution=110 --magnification=1.5 \ +--verbose=quiet hello.dvi +Qf cmr10 165 110 1.5 localfont +</pre> +<p>This reads the DVI file to find out what fonts are required, but does +not process it further. It then tries to find the fonts, fails, and +produces a list of parameters which could be used to generate the +font files. </p> + +<p>See also <a href="#usage.fonts">2.5 Finding and generating fonts</a>, and see <a href="#usagenotes">3 Usage notes</a> for more elaborate examples of use.</p> + + + +<h3><a name="usage.fonts">2.5 Finding and generating fonts</a></h3> + + +<h4><a name="usage.fonts.finding">2.5.1 Finding fonts</a></h4> + + +<p>The program searches for fonts using a number of mechanisms.</p> + +<ol> +<li> +<p>The <code>-fp</code> option (see <span><a href="#usage.options.fp"></a></span><span>above</span>) specifies a +colon-separated list of filename templates which +should be searched for font PK files. If this is +given on the command line, it overrides...</p> +</li> + +<li> +<p>The <code>DVI2BITMAP_PK_PATH</code> environment +variable, if defined, specifies a colon-separated +list of filename templates which are to be searched +for PK files.</p> +</li> + +<li> +<p>If the program cannot find fonts using the +environment variable, and if it was configured with +support for the <code>kpathsea</code> library (see +<a href="#install.general"></a>), then it should +find PK files using the same mechanism other DVI +processors use. </p> +</li> + +<li><p><code>dvi2bitmap</code> can be configured to use +a script to find fonts. If the program was not +configured to use <code>kpathsea</code> or the +search fails, then the program invokes a script +which knows where to find font files, given a search +pattern, and which returns a single line containing +a discovered font filename. See <a href="#conf.with-fontfinder"></a>. </p></li> +</ol> + +<p>The third method is the ideal -- you should build +<code>dvi2bitmap</code> using the <code>kpathsea</code> +library if possible (see <a href="#install.web2c">5.1 Obtaining the kpathsea library</a> for how +to obtain it): it is because other DVI-processing programs +like <code>dvips</code> and <code>xdvi</code> are built +with the <code>kpathsea</code> library, that you normally +never have to worry about where fonts live. The +<code>kpathsea</code> library is generally integrated with +the font-generation commands, and can be queried using the +<code>kpsewhich</code> command.</p> + +<p>There are one or two possible wrinkles with the third +method. The path-searching library is very powerful and +flexible, but it is possible to be tripped up by its +configuration file.</p> + +<p>Firstly, the program has to <em>find</em> the +configuration file. The program should sort this out for +itself at configuration time, but it is possible that you +might have to give it some help. If you specify the +<code>TEXMFCNF</code> environment variable, setting it to +the directory which contains your TeX installation's +<code>texmf.cnf</code> file, then this overrides the +program's notion of where the configuration should be. +You can find this file using the command <kbd>kpsewhich +cnf texmf.cnf</kbd>.</p> + +<p>Secondly, it's possible to break the configuration file. +Certain TeX distributions (the ones that came with early RedHat 6.x +distributions are ones I know about) are broken in an +unfortunate way. See <a href="#usage.fonts.notfinding">2.5.2 Not finding fonts</a> +for a discussion.</p> + + +<h4><a name="usage.fonts.notfinding">2.5.2 Not finding fonts</a></h4> + + +<p>It can sometimes happen that <code>dvi2bitmap</code> fails to find fonts, +successfully calls <code>mktexpk</code> to build them, but then <em>still</em> +fails to find them, even though <code>mktexpk</code> has put them where they +should be. There are (at least) three possible reasons for this.</p> + +<p>If you are using the <code>kpathsea</code> library, there +might be some misconfiguration which is confusing it. You +can trace <code>kpathsea</code>'s deliberations in massive +detail by giving the option <code>-ggp</code> (<a href="#usage.options.g"></a>).</p> + +<p>Perhaps you do not have the <code>kpathsea</code> library +installed, or have disabled it, but you <em>have</em> +requested that font-generation be enabled (see <a href="#install.general"></a>). What happens in this case is +that <code>mktexpk</code> successfully builds the fonts, +and installs them in the correct place, where `correct +place' means `the place where <code>kpathsea</code> would +find them'; you're not using <code>kpathsea</code>, so no +fonts for you. What you have to do in this case is work +out where the `correct place' is (<code>kpsepath</code> +and <code>kpsewhich</code> can help here), and specify +that place using either the <code>-fp</code> option or the +<code>DVI2BITMAP_PK_PATH</code> variable, as above (this +is confusing, I know, but more-or-less unavoidable, since +we are here trying to do <code>kpathsea</code>'s job, +without <code>kpathsea</code>).</p> + +<p>I think it is also possible to fall victim to a race +condition, where the font is built successfully, but the +program looks for it in the correct place before the font +is fully flushed to disk, or (mumble) something like that. +Simply running <code>dvi2bitmap</code> a second time seems +to work OK. I'm not sure precisely what's going on here, +and I'd welcome more precise observations, here.</p> + +<p>Another, slightly nastier reason is as follows.</p> + +<p>Some <code>texmf.cnf</code> files declare the location of +the user-writable font directory though a setting like</p> +<pre>VARTEXFONTS=$SELFAUTOPARENT/var/lib/texmf</pre> +<p>whereas others have something like</p> +<pre>VARTEXFONTS=$TEXMFLOCAL/fonts</pre> +<p>Now, +<code>$SELFAUTOPARENT</code> is a variable which is set by +the kpathsea library to be the grandparent directory of +the executable which uses the library. So, for +<code>/usr/bin/{tex,latex,mktexpk,...}</code>, it's +<code>/</code>, but if your <code>dvi2bitmap</code> binary +doesn't live with the other dvi-ware then its +<code>$SELFAUTOPARENT</code> will be different, so that +<code>dvi2bitmap</code> will look for fonts in a +<em>different</em> place from the place where +<code>mktexpk</code> put them when it successfully +generated them.</p> + +<p>I would argue fairly strongly that having the +<code>VARTEXFONTS</code> directory depend on the location +of the dvi-ware <em>executables</em> is a very silly thing +to do. This was the case in the teTeX distribution which +came with RedHat 6.0, though this was fixed pretty +rapidly. If you've fallen foul of this, then you can +either</p> +<ul> +<li> +<p>change your <code>texmf.cnf</code> file to +something more like the second example above; or</p> +</li> + +<li><p>install <code>dvi2bitmap</code> along with the +other TeXware.</p></li> +</ul> +<p>I'd much prefer the first alternative, myself.</p> + +<p>A third option is to get <code>dvi2bitmap</code> to work +around the problem, by telling it to claim to be some +program which <em>is</em> installed along with the other +dvi-ware. You do this with the +<code>--enable-fake-progname</code> option to the +configuration script (see <a href="#conf.enable-fake-progname"></a>).</p> + + +<h4><a name="idm341584259600">2.5.3 Generating fonts by hand</a></h4> + + +<p>If you didn't enable automatic font-generation, or if you +did and something went wrong, you might have to generate +fonts by hand. You need to look at the documentation for +your TeX system, specifically the <code>mktexpk</code> and +<code>MakeTeXPK</code> scripts (one of which might be just +an interface to the other).</p> + +<p>See the discussion of the `<code>make test</code>' script +in <a href="#usage.fonts.finding">2.5.1 Finding fonts</a>. Also, note that the +option <code>-Qg</code>, given to <code>dvi2bitmap</code>, +displays the font-generation commands which would be +required to build the fonts missing from the specified DVI +file. These are the commands which +<code>dvi2bitmap</code> would employ to generate these +fonts, when automatic-font-generation is enabled.</p> + +<p>Since dvi2bitmap's default resolution is 72 dpi, as +opposed to the usual printer resolution of 300 or 600 dpi, +you are unlikely to have suitable fonts on your system, +and will need to generate them. The program will generate +these automatically, if it was configured with support for +that (see <a href="#install.general"></a>); if it wasn't +configured with that support, or if the automatic font +generation fails, you might need to generate the fonts by +hand.</p> + +<p>How you generate fonts depends on your TeX distribution. +As explained in <a href="#usage.examples">2.4 Examples</a>, you can +determine which fonts you need using the <code>-Qf</code> +option. The teTeX and TeXLive TeX distributions include +scripts to generate fonts for you; if you have a different +distribution, there might be a similar script for you to +use, or you might have to do it by hand. In the case of +teTeX, the command you'd use in the example above would +be:</p> +<pre> +% MakeTeXPK cmr10 165 110 1.5 ibmvga</pre> +<p> +This would generate fonts using the +<code>ibmvga</code> Metafont mode, using a base resolution +of 110 dpi (the default for that mode), at a magnification +of 1.5 times, giving a resultant resolution of 165 dpi.</p> + +<p>If you're using the TeXLive distribution, the equivalent +command would be:</p> +<pre> +% mktexpk --mfmode ibmvga --mag 1.5 --bdpi 110 --dpi 165 cmr10</pre> + +<p>If you want to use the same mode as you use for printing +documents, then the mode <code>localfont</code> should do +the right thing. Otherwise, and probably better if these +images are intended for the screen rather than paper, you +could use a more specialised mode such as +<code>ibmvga</code>, which has been tweaked to be readable +at small resolutions. See the file <code>modes.mf</code> +somewhere in your metafont distribution for the list of +possibilities.</p> + +<p>After you have created the fonts, try giving the command</p> +<pre> +% kpsewhich pk cmr10.165pk</pre> +<p> +to confirm +that TeX and friends can find the new fonts, and that your +dvi2bitmap environment variable is set correctly. This +command is part of the <code>kpathsea</code> distribution, +rather than the core TeX distribution, so may not be +present on your system.</p> + + +<h4><a name="usage.fonts.template">2.5.4 Font-string templates</a></h4> + + +<p>The search-path and font-finder routes use font-string +templates. Here, the components of a font file name, or a +font-finding command, are specified using placeholders like +<code>%f</code>. You may use</p> +<table> +<tr> +<td><code>%M</code></td> +<td>mode (eg. ibmvga)</td> +</tr> +<tr> +<td><code>%f</code></td> +<td>font name (eg. cmr10)</td> +</tr> +<tr> +<td><code>%d</code></td> +<td>dpi (eg. 330)</td> +</tr> +<tr> +<td><code>%b</code></td> +<td>base dpi (eg. 110)</td> +</tr> +<tr> +<td><code>%m</code></td> +<td>magnification (eg. 3)</td> +</tr> +<tr> +<td><code>%%</code></td> +<td>%</td> +</tr> +</table> +<p>Thus, using these values as an example, if one of the +entries in <code>DVI2BITMAP_PK_PATH</code> were <code>/var/tmp/%M/%f.%dpk</code>, this would +expand into <code>/var/tmp/ibmvga/cmr10.330pk</code>. +Alternatively, if we had given the font-finder script as +<code>/usr/local/teTeX/bin/kpsewhich pk %f.%dpk</code>, +the <code>dvi2bitmap</code> would have executed the +command <code>.../kpsewhich pk cmr10.330pk</code>, which +would have returned with a suitable font path.</p> + + + + + +<h2><a name="usagenotes">3 Usage notes</a></h2> + + +<h3><a name="usagenotes.fonts">3.1 Good choices of fonts and scaling</a></h3> + + +<p>There is a certain amount of subtlety in choosing fonts and +resolutions for maximum readability.</p> + +<p>The fonts that <code>dvi2bitmap</code> (currently) uses by +default are from the <code>cmr</code> family, and generated +using Metafont mode <code>ibmvga</code>, chosen because its +design resolution, of 110 pixels to the inch, is +approximately right for bitmaps viewed on the screen. This +is not, however, necessarily the optimal choice in all +circumstances.</p> + +<p>You can produce some simple antialiasing by magnifying the +output bitmaps then scaling them down, so that:</p> +<pre> +% dvi2bitmap --magnification=2 --scale=2 myfile.dvi</pre> +<p> +doubles the size of the bitmaps, then halfs it, effectively +blurring it in the latter stage. This works quite well. +You don't <em>necessarily</em> get better results with +larger factors (though it does, of course, depend on the +situation), because Metafont already does some work to make +the characters easier to read, and I suspect that excessive +antialiasing merely frustrates this.</p> + +<p>If you choose a different Metafont mode, it can make a +difference. In your TeX distribution, there should be a +file called <code>modes.mf</code>, containing a large +collection of Metafont font-generation modes (look for it +using <code>kpsewhich modes.mf</code> if you have that +command), and there are several modes in this set which have +resolutions in the 70 to 200 range, which are therefore +about the right size to be useful in this context. You're +probably aiming for a resolution of around 100 pixels per +inch, if you want the text in the output bitmap to be around +the same size as the other text on your monitor. For +example, try the <code>ncd</code> and <code>nec</code> +modes:</p> +<pre> +% dvi2bitmap --magnification=2 --scale=2 --font-mode=ncd --resolution=95 try.dvi +% dvi2bitmap --scale=2 --font-mode=nec --resolution=180 try.dvi +% dvi2bitmap --magnification=2 --scale=4 --font-mode=nec --resolution=180 try.dvi</pre> +<p> +Note that the declared +resolution must match the font mode -- the default +resolution of 110 is designed to match the default mode of +<code>ibmvga</code>. Also the <code>nec</code> mode, +because its base resolution is large anyway, only needs to +be scaled down to get adequate antialiasing.</p> + +<p>It should be possible to create a Metafont mode +specifically for <code>dvi2bitmap</code> applications. That +might be a useful project for someone!</p> + +<p>Another thing to look at is whether changing the font +family can help. The Computer Modern family is, of course, +designed for paper. The <a href="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=concrete">Concrete +Math family</a>, though also designed primarily for +paper, has features which make it particularly suitable for +this application. The <a href="http://www.tex.ac.uk/cgi-bin/texfaq2html?label=psfchoice">FAQ +article which discusses maths font choices</a> remarks +that</p> +<blockquote><p>Since Concrete is considerably darker +than Computer Modern, this variant may be of particular +interest for use in low-resolution printing or in +display-oriented applications such as posters, +transparencies, or online documents.</p></blockquote> +<p>As +well as this, these fonts have rather simpler outlines than +Computer Modern <em>and</em> they are rather more upright, +both of which make them more robust to being rendered at +rather small resolutions.</p> + +<p>You can use the concrete maths fonts simply by adding the +declaration</p> +<pre> +\usepackage{concmath}</pre> +<p> +to the preamble of your LaTeX document. In tests, the best +configuration for clarity in a bitmap appeared to be a +document using the concrete maths fonts, plus the +<code>dvi2bitmap</code> invocation</p> +<pre> +% dvi2bitmap --magnification=2 --scale=4 --font-mode=nec --resolution=180 try-cc.dvi</pre> + +<p>Any observations on this topic would be warmly +appreciated.</p> + +<p>Many thanks to Doug du Boulay at <code>titech.ac.jp</code> +for raising this issue, for thus prompting me to discuss the +various options, and for then doing the critical testing +work.</p> + + + +<h3><a name="usagenotes.pipe">3.2 Using dvi2bitmap in a pipe</a></h3> + + +<p><code>dvi2bitmap</code> is perfectly happy reading DVI +files from a pipe, so that</p> +<pre> +cat myfile.dvi | dvi2bitmap --pipe -</pre> +<p> +will work perfectly well. +Since the program knows that the standard input -- indicated +by the <code>-</code> argument to <code>dvi2bitmap</code> -- +is not seekable, the option <code>--pipe</code> is actually +redundant. This is not by itself particularly useful, since +TeX is not written to send its DVI output into a pipe.</p> + +<p>If, however, you make a `named pipe' beforehand, using the Unix +<code>mkfifo</code> command (a FIFO, or first-in-first-out, is the +other name for such an object), then TeX can be persuaded to send its +output there.</p> +<pre> +% mkfifo myfile.dvi +% ls -l myfile.dvi +prw-r--r-- 1 norman admin 0 Aug 12 00:18 myfile.dvi +% latex myfile >myfile.stdout & +% dvi2bitmap --pipe mkfile.dvi</pre> +<p> +Here, we create the FIFO using the <code>mkfifo</code> +command; looking at it, we see that the first character on +the <code>ls</code> line is a <code>p</code>, indicating the +type of object it is. We start (La)TeX going in the +background (achieved by the <code>&</code>), putting its +chatty output into a file, and it merrily writes into the +`file' <code>myfile.dvi</code>. Immediately afterwards +(we've shown this on two lines, but the two commands could +be run together with only the <code>&</code> separating +them) we start <code>dvi2bitmap</code>, telling it to read +from the named pipe. The pipe effectively synchronises the +two processes, so that if there is nothing to read, +<code>dvi2bitmap</code> is briefly suspended, and if the +pipe is full, LaTeX is suspended. After this performance, +the DVI file, <code>myfile.dvi</code> ends up zero size +again, and the process can be repeated.</p> + +<p>You can go further than this, and use a FIFO for LaTeX's input, +too:</p> +<pre> +% mkfifo myfile.tex myfile.dvi +% cat foo.tex >myfile.tex & \ +latex '\input myfile.tex' >myfile.stderr & \ +dvi2bitmap --pipe myfile.dvi</pre> +<p> +(the trailing backslashes indicate that this second set of +commands is all on one line). The rather odd form of LaTeX +invocation (note the quotes) stops TeX from peeking at the +file, looking for the magic <code>%&</code> line which +can tell it which format to use; since the input is a pipe, +it's unseekable, so we must use this form, or else LaTeX +fails.</p> + + + +<h3><a name="usagenotes.multieqs">3.3 Processing many bitmaps</a></h3> + + +<p>If you have a large number of fragments of TeX to process, +it is best not to invoke <code>dvi2bitmap</code> for each one +individually. Also, the program does not (yet) allow you to specify +more than one DVI file as input. In this situation, it is best to +generate an input TeX or LaTeX file which contains <em>all</em> of the +text you wish to process, with one fragment per page.</p> + +<p>For example, the following can help:</p> +<pre> +\documentclass{article} +\pagestyle{empty} +\special{dvi2bitmap default imageformat png} +\newcommand{\neweq}[1]{\vfil\break\special{dvi2bitmap outputfile #1.png}} +\begin{document} + +\neweq{index-html-alpha} +$\alpha$ + +\neweq{index-html-aprime} +$A'=(0,\alpha,0,0)$ + +[...] + +\end{document}</pre> +<p> +That includes a special to make PNG the default output format, and +defines a command sequence, <code>\neweq</code> which simultaneously +forces a new page and inserts a special to name the output file. A +script which generates a file like this and then looks for the +resulting bitmaps, with known names of course, can run very +efficiently. Combining that with the techniques in <a href="#usagenotes.pipe">3.2 Using dvi2bitmap in a pipe</a> can work wonders.</p> + + + +<h3><a name="usagenotes.marks">3.4 Using marks to position bitmaps</a></h3> + + +<p>When including small images in an HTML page, it can be +difficult to get the images to line up with the rest of the +text, because a text with descenders (characters which go +below the line such as `p' or `g') cause the image to be +offset from the text line. You can use the `mark' facility +to tell you how much you need to offset such an image so +that it lines up properly with the surrounding text.</p> + +<p>For example, consider the following usage:</p> +<pre> +% cat temp.tex +\nopagenumbers +\noindent\special{dvi2bitmap mark}% +Hello, this is dvi2bitmap +\bye +% tex temp.tex +This is TeX, Version 3.14159 (Web2C 7.3.11) +(./temp.tex [1] ) +Output written on temp.dvi (1 page, 240 bytes). +Transcript written on temp.log.</pre> +<p> +So, a simple test file with a single line in it, with descenders (the +`p'). The `mark' special goes at the beginning, following \noindent. +This is important, otherwise the point that is marked is the very +top-left of the image, not the bottom-left.</p> + +<p>The output with <code>--query=bitmaps</code> is:</p> +<pre> +% dvi2bitmap --verbose=quiet --query=bitmaps temp +Qbitmaps temp-page1.png 163 14 -1 11</pre> +<p> +...where <code>verbose=quiet</code> has been used to turn +off the usual chatter. It tells us that the bitmap as a +whole is 14 pixels deep, and that the mark, which is on the +TeX baseline, remember, is at position (-1,11) relative to +an origin at the top-left of the bitmap; or in other words +there's 3 pixels of space between the TeX baseline and the +bottom of the image. We therefore know that we need to +offset the image by three pixels to make it line up +properly.</p> + +<p>There are several ways to do that, but one way is to use +per-element CSS properties, like this:</p> +<pre> +% dvi2bitmap --verbose=quiet --query=bitmaps temp | awk +'{printf "<img src=\"%s\" style=\"margin-bottom: %dpx\"/>\n", $2, +$6-$4}' +<img src="temp-page1.png" style="margin-bottom: -3px"/> +%</pre> +<p> +So that's generated an <code><img></code> element +which has the correct `src' attribute (from column 2 of the +Qbitmaps line) and the correct offset (column6 - column4). +That uses awk, but if you're generating your HTML pages with +something like Perl or Python (substantially more sensible +than awk...!), say, you could do an analogous thing with the +dvi2bitmap output, and put the generated +<code><img></code> elements in the correct places in +the output HTML file. </p> + + + + + +<h2><a name="libdvi2bitmap">4 The libdvi2bitmap library</a></h2> + + +<p>The main bulk of the code which implements <code>dvi2bitmap</code> +is in a library, and the program itself is a rather thin wrapper on +top of this. This library is intended to be usable for other +applications.</p> + +<p>The library is written in C++, and provides an abstraction of DVI +files, PK font files, Bitmaps, and various other objects used to build +these ones. By default, the build procedure creates both static and +dynamic libraries.</p> + +<p>The library API is extensively documented in the +<code>doc_libdvi2bitmap/</code> directory of the +distribution.</p> + + + +<h2><a name="install">5 Building and installing dvi2bitmap</a></h2> + + +<p>The package uses a automake/autoconf/libtool build system. +Building should therefore be simple:</p> +<pre> +% ./configure +% make +% make install</pre> +<p> + +but see the configuration options below.</p> + +<p>By default, both a static and a dynamic library are built. If +there is some reason why building the dynamic library fails on your +platform, configure using <code>--disable-shared</code> and +you'll build a static library only.</p> + +<p>It's a good idea to run <code>(cd test;make)</code> as +well. See <a href="#usage.fonts.finding">2.5.1 Finding fonts</a>.</p> + +<p>To install, just copy the executable +<code>dvi2bitmap</code> wherever you want it to live.</p> + +<p>You can customise the program using flags to the +<code>./configure</code> command:</p> +<dl> +<dt> +<code>--with-kpathsea</code> and <code>--without-kpathsea</code> +</dt> +<dd> +<p>If you have the <code>kpathsea</code> library (see +<a href="#usage.fonts.finding">2.5.1 Finding fonts</a>) but don't, for some +reason, want to use it, then give the configure option +<code>--without-kpathsea</code>. By default, the +configuration enables use of the library if it is +installed (that is, if the <code>kpathsea</code> +include files and library are somewhere the compiler +will find them. If <code>kpathsea</code> is disabled +(by default or by request), then fonts will not be +generated by default.</p> + +<p>If you have the <code>kpathsea</code> library, but it +is not in the standard place, then you can provide an +argument to the <code>--with-kpathsea</code> option +giving the name of a directory below which are +directories <code>include</code> and <code>lib</code>, +containing the required <code>kpathsea</code> include +files and library. + + +If you don't have the +<code>kpathsea</code> library available, see below +(<a href="#install.web2c">5.1 Obtaining the kpathsea library</a>) for notes on obtaining +it.</p> +</dd> + +<dt><code>--disable-texmfcnf</code></dt> +<dd> +<p>The <code>kpathsea</code> library finds its +configuration files in two ways, either automatically +if it is installed in the same directory as the rest +of the TeXware, or using the <code>TEXMFCNF</code> +environment variable. The <code>dvi2bitmap</code> +program sets the latter variable internally, unless it +finds it already set. If this will be inconvenient, +you can suppress this behaviour by providing the flag +<code>--disable-texmfcnf</code>, or equivalently +<code>--enable-texmfcnf=no</code>.</p> +</dd> + +<dt><a name="conf.enable-fontgen"><code>--enable-fontgen</code></a></dt> +<dd> +<p>The program can attempt to generate fonts, and will +do so using the MetaFont mode <code>ibmvga</code>, +which has a resolution of 110 dots-per-inch.</p> + +<p>You can give an argument to this command, which +specifies a command-line which will build and install +a required font, and return its path on standard +output. This uses the font-string template described +in <a href="#usage.fonts.template">2.5.4 Font-string templates</a>. You could +duplicate the default (the <code>mktexpk</code> script +if present) with the option</p> +<pre> +--enable-fontgen='<path>mktexpk --dpi %d --bdpi %b --mag %m --mfmode %M %f'</pre> + +<p>The default for this option is `on' -- the program +will attempt to generate fonts. Do note, however, +that if the <code>kpathsea</code> library is not +enabled, then the program will <em>not</em> be able to +find the fonts it generates, unless you configure it +correctly using either <code>-fp</code> or +<code>DVI2BITMAP_PK_PATH</code> (see <a href="#usage.fonts.finding">2.5.1 Finding fonts</a>).</p> + +<p>If you wish to disable this automatic font +generation, give the option +<code>--disable-fontgen</code>. Note that this does +not completely disable font generation -- it merely +sets the default for font generation to `off', and it +can be switched back on again using the option +<code>-fG.</code></p> + +<p>If you wish to change the default mode, you can do so +using the option <a href="#conf.fontgen-mode"></a>.</p> +</dd> + +<dt><a name="conf.fontgen-mode"> +<code>--with-fontgen-mode=mode,res</code></a></dt> +<dd> +<p>If you wish to change the default parameters for +font-generation, you can set both the Metafont mode +and resolution using this option. For example, the +option <code>--fontgen-mode=pcprevw,118</code> will +make <code>pcprevw</code>, which has a resolution of +118 dpi, the default MetaFont mode. Note that the +resolution you specify <em>must</em> match the mode: +see file <code>modes.mf</code> for a list of modes and +resolutions (use <kbd>kpsewhich mf modes.mf</kbd> to +find this). You can change the resolution and mode on +the fly using the <code>-fm</code> and <code>-r</code> +options to the compiled program (<a href="#usage.options">2.1 Options</a>).</p> +</dd> + +<dt><a name="conf.with-fontfinder"> +<code>--with-fontfinder</code></a></dt> +<dd> +<p>This specifies a command to run to find fonts. It is +preferable to use the <code>kpathsea</code> library if +possible, but if this is difficult, then you can +specify a script to run to find fonts. This uses the +font-string template described in <a href="#usage.fonts.template">2.5.4 Font-string templates</a>. To use the standard +<code>kpsewhich</code> command, for example, you could +give the option</p> +<pre> +--with-fontfinder='/usr/local/teTeX/bin/kpsewhich pk %f.%dpk' +</pre> +</dd> + +<dt> +<code>--enable-mktexpk</code> and +<code>--enable-maketexpk</code> +</dt> +<dd> +<p>In the default configuration, the program will +generate missing fonts using one of the standard +scripts present in most TeX distributions. The +configuration process looks first for +<code>mktexpk</code> then <code>MakeTeXPK</code>, and +uses whichever it finds first. If you have both +scripts but wish to use <code>MakeTeXPK</code> for +some reason, you will have to give the option +<code>--disable-mktexpk</code>; if you wish to disable +both, you will have to give +<code>--disable-maketexpk</code> as well. Both +options take an optional argument giving the path to +an alternative script with the same calling interface.</p> +</dd> + +<dt> +<code>--with-png</code> (default: enabled)</dt> +<dd> +<p>If you give this option, and if the PNG library is +installed (needs a version after 0.96), then the +program will be compiled with support for PNG bitmaps +as an output format. You can obtain the PNG library +from the <a href="http://www.libpng.org/pub/png/">PNG home +page</a>. You can disable the use of PNG with +the option <code>--without-png</code>.</p> +</dd> + +<dt> +<code>--enable-gif</code> (default: disabled)</dt> +<dd> +<p>The program generates only XBM bitmaps by default. +If you want it to be able to generate GIFs, then give +the configure option <code>--enable-gif</code>. The +GIF format is the copyright of CompuServe. As far as +I understand it, one does not need a licence from +CompuServe if one is distributing non-commercial, +not-for-profit software, such as this. You probably +shouldn't enable GIF support when you build this +program unless you're in that category as well. But +don't listen to me: there's a much fuller account of +the whole sorry business in the <a href="ftp://rtfm.mit.edu/pub/usenet/news.answers/graphics/fileformats-faq">Graphics +File Formats FAQ</a> (<a href="http://www.oreilly.com/centers/gff/gff-faq/gff-faq1.htm">HTML</a>).</p> +</dd> + +<dt><a name="conf.enable-fake-progname"> +<code>--enable-fake-progname</code></a></dt> +<dd> +<p>This option enables a workaround which allows +<code>dvi2bitmap</code> to have the expected behaviour +when (a) you do not install <code>dvi2bitmap</code> +along with the other dvi-ware, <em>and</em> (b) your +<code>texmf.cnf</code> file has +<code>VARTEXFONTS</code> (or a similar variable) +depending on one of the <code>SELFAUTO...</code> +variables (such a <code>texmf.cnf</code> file is +probably broken, but that may not be your problem, or +within your power to fix). This option makes +<code>dvi2bitmap</code> claim to be a different +DVI-reading program which <em>is</em> installed in the +standard place. See <a href="#usage.fonts.notfinding">2.5.2 Not finding fonts</a> for discussion. The +configuration script uses the location of the +<code>xdvi</code> program by default, but you can +override this by giving the full path to an +alternative as an argument to this option (that is, +<code>--enable-fake-progname=/path/to/dviprog</code>). </p> + +<p>Since this uses undocumented behaviour of the library +(`use the source, Luke!'), you almost certainly +shouldn't enable it unless you have to.</p> +</dd> + +<dt><code>--with-path-seps</code></dt> +<dd> +<p>The default configuration is for Unix, and uses the +Unix defaults for filesystem path and search path +separators. If you are building it on some other +architecture, you can alter the defaults by giving a +two-character argument to this option, giving the two +separators in order. For example, the arguments +appropriate for DOS would be</p> +<pre>--with-path-seps='\;'</pre> +</dd> + +</dl> + +<p>The <code>./configure</code> command without any options is +equivalent to <code>./configure --with-kpathsea --with-png +--enable-mktexpk</code> (meaning that kpathsea and PNG +output will be enabled if library support for them is +found).</p> + +<p>The program builds successfully on (at least):</p> +<blockquote> +<table> +<tr> +<th>Platform</th> +<th>Version</th> +<th>Compiler</th> +</tr> + +<tr> +<td>powerpc-apple-darwin6.6 (MacOS X, 10.2.6)</td> +<td>0.11b1</td> +<td>g++ 3.1 20020420 (prerelease)</td> +</tr> +<tr> +<td>sun-sparc-solaris2.9</td> +<td>0.11b1</td> +<td>CC: Sun WorkShop 6 update 2 C++ 5.3 +2001/05/15</td> +</tr> +<tr> +<td>alphaev67-dec-osf5.1</td> +<td>0.11b1</td> +<td>Compaq C++ V6.5-014</td> +</tr> +<tr> +<td>i686-pc-linux-gnu (RedHat 7.3)</td> +<td>0.11b1</td> +<td>g++ 2.96</td> +</tr> +<tr> +<td>i686-pc-linux-gnu (RedHat 7.3)</td> +<td>0.10</td> +<td>gcc 2.96</td> +</tr> +<tr> +<td>i686-pc-linux-gnu (RedHat 6.2)</td> +<td>0.10b1</td> +<td>egcs-2.91.66</td> +</tr> +<tr> +<td>powerpc-apple-darwin6.4 (MacOSX 10.2)</td> +<td>0.10</td> +<td>g++ 3.1 20020420 (prerelease)</td> +</tr> +<tr> +<td>sparc-sun-solaris2.8</td> +<td>0.10b1</td> +<td>egcs-2.91.66</td> +</tr> +<tr> +<td>alphaev56-dec-osf5.0</td> +<td>0.10b1</td> +<td>egcs-2.91.66</td> +</tr> +<tr> +<td>i686-pc-linux-gnu (RedHat 6.2)</td> +<td>0.9-7p1</td> +<td>egcs-2.91.66</td> +</tr> +<tr> +<td>powerpc-unknown-linux-gnu (Mac mklinux +DR-0.3?)</td> +<td>0.9</td> +<td>egcs-2.90.25 980302 (egcs-1.0.2 prerelease)</td> +</tr> +<tr> +<td>sparc-sun-solaris2.7</td> +<td>0.9</td> +<td>egcs-2.91.66</td> +</tr> +<tr> +<td>sparc-sun-solaris2.7</td> +<td>0.9</td> +<td>gcc 2.8.1</td> +</tr> +<tr> +<td>sparc-sun-solaris2.7</td> +<td>0.9-6</td> +<td>WorkShop Compilers 5.0 98/12/15 C++ +5.0</td> +</tr> +<tr> +<td>alpha-dec-osf4.0f</td> +<td>0.9-6</td> +<td>Compaq C++ V6.2-024 for Digital UNIX V4.0F</td> +</tr> +<tr> +<td>i386-pc-solaris2.6</td> +<td>0.9-7p1</td> +<td>gcc v2.8.1/libstdc++ v2.8.1.1</td> +</tr> +</table> +</blockquote> +<p>The `version' column is the last version which was actually tested on +that platform/compiler combination. Reports of compilations on other +platform/compiler combinations gratefully received.</p> + +<p>It should be written in standards-conforming C++, so if it +doesn't build then (1) it's not as conformant as I think it +is (in which case please tell me), (2) your compiler is not +as conformant as you think it is (in which case please don't +tell me), or (3) you need to invoke some magic to get the +compiler to be conformant (in which case tell me, if there's +something I can do in the autoconfigure script).</p> + +<p>You can override the C++ compiler the configure script will +choose by setting the environment variable <code>CXX</code>, +either via </p> +<pre>% CXX=cxx ./configure</pre> +<p> +or</p> +<pre>% env CXX=cxx ./configure</pre> +<p> +depending on your shell.</p> + +<p>Run regression tests with <code>(cd test;make)</code> in +the build directory. This includes a separate whole-program +test which additionally gives advice about setting +environment variables. You can run this script separately +with the command <code>(cd test;make pathtest)</code></p> + +<p>Regression test 6 currently fails to link when using Compaq +<code>cxx</code>, for some arcane C++ reason I have yet to +diagnose. The whole-script test mentioned above works, +though.</p> + +<h3><a name="install.web2c">5.1 Obtaining the kpathsea library</a></h3> + + +<p>Not all TeX distributions install the +<code>kpathsea</code> library, even though they install +applications built with it, and the <code>texmf.cnf</code> +configuration file which controls it.</p> + +<p>If the library does not appear to be in your +distribution, then you can obtain and build it yourself. +The library is distributed as part of the +<code>web2c</code> (Unix TeX source) distribution, which +you can find at +<span class="url">ftp://ftp.tug.org/tex/web2c.tar.gz</span>, or mirrored +on CTAN sites (for example at +<span class="url">http://www.tex.ac.uk</span> in directory <code>systems/web2c</code>).</p> + +<p>Take a copy of the library (this is a <em>big</em> +distribution), and unpack it. Go into the +<code>kpathsea</code> directory and do the usual +`<code>./configure; make; make install</code>' routine. +With (some?) older distributions of the library this +appeared not to work, and you had to go to the parent of +the <code>kpathsea</code> directory, delete the web2c +directory (which is the bulk of the distribution), then +configure and build it as usual, ignoring the warnings +about the missing main <code>texmf</code> tree.</p> + + + + + +<h2><a name="developments">6 Bugs, extras, and further developments</a></h2> + + +<p>To report bugs, please send to +<code>norman@astro.gla.ac.uk</code> a brief description of the +problem; a minimal TeX file which reproduces it; some +indication of the machine you're running on (<kbd>uname +-a</kbd> is good); and the output of <kbd>dvi2bitmap -V</kbd>, +which shows the options you have enabled.</p> + +<p>See the <code>TODO</code> list in the distribution, for the +list of things I at least would like to see added to the +code.</p> + +<p>Bright ideas, fixes and (especially) implementations, +cheerfully received.</p> + +<p>In the <code>.../extras</code> directory of the +distribution is a script <code>img-eqlist.pl</code>, which transforms a +file of LaTeX fragments into a LaTeX file, keeping track of +filenames, and avoiding generating duplicate bitmaps for duplicated +maths.</p> + + + +<h2><a name="refs">7 References and acknowledgements</a></h2> + + +<p>CTAN, the Comprehensive TeX Archive Network, is <em>the</em> +repository of TeX and LaTeX documentation. The archive is +mirrored in numerous places, but the UK node is at +<span class="url">http://www.tex.ac.uk</span>.</p> + +<p>DVItype and PKtoPX are two programs Donald Knuth intended as +model DVI and PK file readers, and as containers for the +canonical documentation of the DVI and PK file formats. They +might be available as part of your TeX distribution, but are +also available on CTAN, in <code>/tex-archive/systems/knuth/texware/dvitype.web</code> +and <code>/tex-archive/systems/knuth/pxl/pktopx.web</code>.</p> + +<p>The <cite>DVI Driver Standard, Level 0</cite> is available on +CTAN, in directory <code>/tex-archive/dviware/driv-standard</code>. This +incorporates sections of the DVItype documentation. This +program claims to conform to this standard: if it doesn't, +please let me know.</p> + +<p>Thanks for bug reports and other suggestions to <a href="http://www.cis.ohio-state.edu/~gurari/">Eitan +Gurari</a> (heroic tester), Oliver Schurr and Oleg +Bartunov (<code>oleg@sai.msu.su</code>).</p> + +<p>Yamabe Kazuharu (<code>tako_da@qc4.so-net.ne.jp</code>) +supplied the writer for XPM bitmaps.</p> + + + +<h2>Appendices</h2> + +<h2><a name="sgml.maths">A Maths and SGML/HTML</a></h2> + + +<ul> +<li> +<p><a href="http://www.w3.org/Math/">W3C's maths +WG</a>. This covers <a href="http://www.w3.org/TR/REC-MathML/">MathML</a> which is now a W3C Recommendation. The working group +also supports the <a href="http://lists.w3.org/Archives/Public/www-math/">www-math</a> +mailing list. </p> + +</li> + +<li> +<p><a href="http://www.oasis-open.org/cover/topics.html#sgml-math">Maths +special topic at the SGML web page</a> </p> +</li> + +<li><p>Also, <a href="http://www.oreilly.com/people/staff/crism/math/">maths +proposal from O'Reilly</a>. </p></li> + +<li><p><a href="http://indy.cs.concordia.ca/mathml/">MathML at +Concordia</a> </p></li> + +</ul> + +<h3><a name="sgml.maths.latex">A.1 LaTeX maths within HTML</a></h3> + + +<p>The <em>real</em> issue here (for me at least) is +rendering equations within an HTML document. There are +several tools available which can do that with different +trade-offs. The most popular method is to write the +equations in a LaTeX document, process it, and then hoik +the equations out of the resulting DVI file somehow +(typically using <code>dvips</code> and a postscript to +gif converter), and display them on the web as gifs. The +big disadvantage with this is that you get an awful lot of +gifs, and the conversion is rather inefficient.</p> + +<p>All this hassle <em>should</em> become irrelevant once we +get browsers which can render MathML directly.</p> + +<p>There are reviews of the problems, and some of the tools, +in articles <a href="http://forum.swarthmore.edu/typesetting/index.html"><cite>Maths +Typesetting for the Internet</cite></a>, and <a href="http://hutchinson.belmont.ma.us/tth/mmlreview/"><cite>Comparative +Review of World-Wide-Web Mathematics +Renderers</cite></a>.</p> + +<p><a href="http://www.tex.ac.uk/tex-archive/support/latex2html/">LaTeX2HTML</a> +is the granddaddy of these translators -- it parses the +LaTeX using Perl, and spits out HTML, turning maths into +gifs. It's very robust by now.</p> + +<p>John Walker's <a href="http://www.fourmilab.ch/webtools/textogif/textogif.html">textogif</a> +is a Perl program which orchestrates the various tools to +do the conversion via postscript, once you've generated +the DVI file. It works, but it's <em>terribly</em> slow, +which was the motivation for this program.</p> + +<p><a href="http://www.cis.ohio-state.edu/~gurari/TeX4ht/mn.html">TeX4ht</a> +(TeX for Hypertext) uses TeX's own parser, but still +produces equations as gifs. TeX4ht can also emit MathML +from LaTeX. The TeX4ht documentation has a useful +collection of resources. There's an alternative location +for TeX4ht <a href="http://www.tug.org/applications/tex4ht/mn.html">at +TUG</a>.</p> + +<p><a href="http://hutchinson.belmont.ma.us/tth/">tth: +TeX to HTML translator</a> (<a href="http://hutchinson.belmont.ma.us/tth/manual.cgi">manual</a>). +<code>tth</code> translates LaTeX maths directly to HTML, +with remarkable success and astonishing speed, and with +good failure strategies. It works very sweetly, but (a) +requires you to tweak your browser to have it map the +symbol font appropriately, and (b) the resulting HTML +can't be printed legibly. From the same source is <a href="http://hutchinson.belmont.ma.us/tth/mml/">TtHMML</a>, +which translates (La)TeX to HTML plus MathML.</p> + +<p><a href="http://www.nikhef.nl/~t16/public/ndvi/ndvi_doc.html">nDVI</a> +is a DVI viewer plugin for Unix Netscape. This addresses +the problem at the client end.</p> + + +<h3><a name="sgml.maths.other">A.2 Other approaches to maths</a></h3> + + +<p>A quite different approach is to use a different markup +for maths, possibly requiring specialised client software. +These other notations typically use semantic markup -- +expressing the structure of the maths. At first sight, +this seems preferable to LaTeX's presentational markup, +but its weaknesses for authoring are exposed (I feel) when +you realise that maths is not as closed and unambiguous a +language as computer scientists feel it ought to be. +Semantic markup's strength is in interfaces with computer +algebra systems, and databases -- Abramowitz and Stegun +would be ideal in this form! The major dislocation +between the two approaches is what makes conversion from +presentational to semantic markup so easy. In passing, +I'll note that MathML has both a presentational and a +semantic variant.</p> + +<p><a href="http://www.lfw.org/math/top.html">MINSE</a> uses +a server to render maths into gifs on the fly. It seems +to work rather nicely, but works with its own semantic +maths notation.</p> + +<p>There is (was?) a project called <a href="http://www.dcs.fmph.uniba.sk/~emt/">Euromath</a>, +which includes a structured SGML editor. This project +included a converter which could transform <a href="http://www.dcs.fmph.uniba.sk/~emt/EmSystem.html#editor">LaTeX +to Euromath SGML</a>.</p> + +<p><a href="http://www.nag.co.uk/projects/OpenMath/">OpenMath</a> +might be a successor to Euromath. It's an EC Esprit +project which `proposes to develop standards for the +semantically-rich representation of mathematics'.</p> + +<p><a href="http://www.albany.edu/~hammond/gellmu/">GELLMU</a> +is a LaTeX-like markup language, intended to be easy to +convert to SGML. Specifically, it is intended to support +maths (and hence conversion to MathML) well.</p> + +<p>The following are specifically concerned with maths in +SGML, using either MathML or other maths DTD fragments.</p> + +<p><a href="http://www.webeq.com/">WebEQ</a> is a +suite of Java programs which implement MathML. It's +commercial.</p> + +<p><a href="http://www.alphaworks.ibm.com/formula/texml">TeXML</a> +is a gadget from IBM which converts XML to TeX via a DTD +fragment. You transform your XML to an equivalent +document marked up in TeXML, which you then separately +transform to TeX.</p> + +<p><a href="http://www.w3.org/People/Raggett/EzMath">EzMath</a> +is a Dave Raggett proposal for producing maths on the web. +It uses yet another notation, and converts it to online +form using a plugin (no printing, and Windows only, as of +April 1999).</p> + + + + + +<h2><a name="tex.dimensions">B TeX dimensions</a></h2> + + +<p>When producing this program, I became terribly confused +about the variety of dimensions which appear in DVI and PK +files. <a href="#tsizes"></a> is a summary of the sizes which +appear, for the benefit of anyone else attempting a project +like this. The reference [Dn] refers to section `<img src="doc.img/m-1064.gif">' of the webbed DVItype document +and [Pn] to section `<img src="doc.img/m-1065.gif">' of the +PktoPX document (see <a href="#refs">7 References and acknowledgements</a>).</p> + +<p>If you feel I have misunderstood something here, or got one of the +conversion factors wrong (I hate these!), please correct me.</p> + +<table> +<caption>Sizes in TeX</caption> +<tr> +<th>Context</th> +<th>Description</th> +<th>See</th> +</tr> +<tr> +<td>DVI preamble</td> +<td> +<code>num</code>, <code>den</code>: multiply +a `DVI unit' by <img src="doc.img/m-1077.gif"> to +obtain a length in units of <img src="doc.img/m-1078.gif"> +</td> +<td>[D17]</td> +</tr> +<tr> +<td></td> +<td> +<code>mag</code>: DVI units are actually multiplied by +<img src="doc.img/m-1084.gif"> +</td> +<td>[D17] +</td> +</tr> +<tr> +<td>DVI font definition</td> +<td> +<code>d</code>: a design size, in DVI units. +The nominal size of the font.</td> +<td>[D18]</td> +</tr> +<tr> +<td></td> +<td> +<code>s</code>: a `fixed point' scale factor, range +<img src="doc.img/m-1095.gif">, +scaling <code>d</code> (see note).</td> +<td>[D18]</td> +</tr> +<tr> +<td>PK preamble</td> +<td> +<code>ds</code>: the font design size in +units of <img src="doc.img/m-1102.gif"> +points.</td> +<td>[P12]</td> +</tr> +<tr> +<td></td> +<td> +<code>hppp</code>, <code>vppp</code>: number +of pixels per point, times <img src="doc.img/m-1109.gif"> (see note).</td> +<td>[P12]</td> +</tr> +<tr> +<td>Character</td> +<td> +<code>tfmwidth</code>: the width of the +character (see note).</td> +<td>[D37], [P9]</td> +</tr> +<tr> +<td></td> +<td> +<code>w</code>, <code>h</code>: the width and +height, in pixels, of the character pixel map.</td> +<td>[P21]</td> +</tr> +<tr> +<td></td> +<td> +<code>hoff</code> and <code>voff</code>: +offset of the pixel map from the reference point.</td> +<td>[P21]</td> +</tr> +<tr> +<td></td> +<td> +<code>dm</code>, <code>dx</code>, +<code>dy</code>: the pixel +escapements. <code>dm</code> in pixels, +<code>dx</code> and <code>dy</code> in pixels times +<img src="doc.img/m-1137.gif"> (see +note).</td> +<td>[P21]</td> +</tr> + +</table> + +<ol> +<li> +<p><code>s</code> scales the design size, so that a font +is actually used at <img src="doc.img/m-1143.gif"> +times its normal size.</p> +</li> + +<li> +<p><code>hppp</code> and <code>vppp</code> aren't used +as sizes, but can be used to check you have the right +fonts by comparing resolution, etc..</p> +</li> + +<li> +<p><code>tfmwidth</code> is the `physical' size of a +character, and is the only size that TeX uses in its +calculations, and which the DVI reader uses when +working out how far to move the reference point when +it sets a character. This is defined in [P9] to be in +units of <code>FIXes</code>, where one +<code>FIX</code> is <img src="doc.img/m-1153.gif"> times the design +size in points. [D37] describes how to multiply these +widths by scaling factors without overflowing.</p> +</li> + +<li> +<p>The difference between the pixel escapements and +<code>tfmwidth</code> is that the latter is a +resolution-independent shift of the DVI reference +point, and the former is the PK file's recommendation +of the number of pixels the DVI processor should +actually move. The DVI processor keeps track of the +two reference points, and readjusts the pixel-based +one when rounding errors move it too far from the +resolution-independent one. See [D89] and [D91]; also +[D40].</p> +</li> +</ol> + +<p>A few useful conversions are:</p> +<ul> +<li> +<p>The design size of a font is a physical length, of <img src="doc.img/m-1161.gif"> +points. [P12]</p> +</li> + +<li> +<p>A <code>FIX</code> is a physical size, of length +<img src="doc.img/m-1165.gif"></p> +</li> + +<li> +<p>A TFM width is a physical size. The +<code>tfmwidth</code> parameter is in units of +<code>FIXes</code>, so that the TFM width is a length +of <code>tfmwidth</code> fixes, which is equal to <img src="doc.img/m-1171.gif"> points.</p> +</li> + +<li> +<p>Writing `dviu' for the unit `DVI units', `sp' for the scaled point +of <img src="doc.img/m-1174.gif"> points, `px' +for pixels, and <img src="doc.img/m-1175.gif"> for +Knuth's deci-micron, or <img src="doc.img/m-1176.gif">, +<img src="doc.img/m-1177.gif"> +</p> +</li> + +</ul> + + + +<h2><a name="rn">C Release notes</a></h2> + + +No changes from 1.0. + + + + + +</body> +</html> diff --git a/dviware/dvi2bitmap/doc/doc.img/doc-m.dvi b/dviware/dvi2bitmap/doc/doc.img/doc-m.dvi Binary files differnew file mode 100644 index 0000000000..8ae9269ef4 --- /dev/null +++ b/dviware/dvi2bitmap/doc/doc.img/doc-m.dvi diff --git a/dviware/dvi2bitmap/doc/doc.img/doc-m.tex b/dviware/dvi2bitmap/doc/doc.img/doc-m.tex new file mode 100644 index 0000000000..b957066c25 --- /dev/null +++ b/dviware/dvi2bitmap/doc/doc.img/doc-m.tex @@ -0,0 +1,61 @@ +\nopagenumbers +\def\mbox#1{\hbox{#1}} +\def\mathrm#1{{\rm #1}} +\def\frac#1#2{{#1\over #2}}\special{dvi2bitmap outputfile m-175} +$0$\vfill\eject +\special{dvi2bitmap outputfile m-177} +$n$\vfill\eject +\special{dvi2bitmap outputfile m-179} +$0$\vfill\eject +\special{dvi2bitmap outputfile m-429} +$(0,0)$\vfill\eject +\special{dvi2bitmap outputfile m-436} +$(-1, 10)$\vfill\eject +\special{dvi2bitmap outputfile m-1064} +$n$\vfill\eject +\special{dvi2bitmap outputfile m-1065} +$n$\vfill\eject +\special{dvi2bitmap outputfile m-1077} +$\mbox{num}/\mbox{den}$\vfill\eject +\special{dvi2bitmap outputfile m-1078} +$10^{-7}\mathrm{m}$\vfill\eject +\special{dvi2bitmap outputfile m-1084} +$(\mbox{num} \times +\mbox{mag}) / (1000\times\mbox{den})$\vfill\eject +\special{dvi2bitmap outputfile m-1095} +$2^{27}>s>0$\vfill\eject +\special{dvi2bitmap outputfile m-1102} +$2^{-20}$\vfill\eject +\special{dvi2bitmap outputfile m-1109} +$2^{16}$\vfill\eject +\special{dvi2bitmap outputfile m-1137} +$2^{16}$\vfill\eject +\special{dvi2bitmap outputfile m-1143} +$(\mbox{s} \times \mbox{mag}) / +(1000\times\mbox{d})$\vfill\eject +\special{dvi2bitmap outputfile m-1153} +$2^{-20}$\vfill\eject +\special{dvi2bitmap outputfile m-1161} +$\mbox{ds}/2^{20}$\vfill\eject +\special{dvi2bitmap outputfile m-1165} +$(\mbox{designsize})/2^{20}$\vfill\eject +\special{dvi2bitmap outputfile m-1171} +$\mbox{tfmwidth}/2^{20} \times +\mbox{ds}/2^{20}$\vfill\eject +\special{dvi2bitmap outputfile m-1174} +$2^{-16}$\vfill\eject +\special{dvi2bitmap outputfile m-1175} +$d\mu$\vfill\eject +\special{dvi2bitmap outputfile m-1176} +$10^{-7}\mathrm{m}$\vfill\eject +\special{dvi2bitmap outputfile m-1177} +$$\eqalign{ +1\mathrm{sp} = \frac{1}{2^{20}}\mathrm{pt}&= \frac{25400000}{7227\times 2^{16}} d\mu\cr +7227\mathrm{pt}&= 254\mathrm{cm} = 25400000 d\mu\cr +1\mathrm{dviu}&= \frac{\mathrm{num}\times\mathrm{resolution}}% +{\mathrm{den}\times 254000} \mathrm{px}\cr +1\mathrm{dviu}&= \frac{\mathrm{num}\times 7227}% +{\mathrm{den}\times 25400000} \mathrm{pt}\cr +\crcr}$$ +\vfill\eject +\bye diff --git a/dviware/dvi2bitmap/doc/doc.img/m-1064.gif b/dviware/dvi2bitmap/doc/doc.img/m-1064.gif Binary files differnew file mode 100644 index 0000000000..a414eacaae --- /dev/null +++ b/dviware/dvi2bitmap/doc/doc.img/m-1064.gif diff --git a/dviware/dvi2bitmap/doc/doc.img/m-1065.gif b/dviware/dvi2bitmap/doc/doc.img/m-1065.gif Binary files differnew file mode 100644 index 0000000000..a414eacaae --- /dev/null +++ b/dviware/dvi2bitmap/doc/doc.img/m-1065.gif diff --git a/dviware/dvi2bitmap/doc/doc.img/m-1077.gif b/dviware/dvi2bitmap/doc/doc.img/m-1077.gif Binary files differnew file mode 100644 index 0000000000..37c9f61b3f --- /dev/null +++ b/dviware/dvi2bitmap/doc/doc.img/m-1077.gif diff --git a/dviware/dvi2bitmap/doc/doc.img/m-1078.gif b/dviware/dvi2bitmap/doc/doc.img/m-1078.gif Binary files differnew file mode 100644 index 0000000000..ea3a80dc51 --- /dev/null +++ b/dviware/dvi2bitmap/doc/doc.img/m-1078.gif diff --git a/dviware/dvi2bitmap/doc/doc.img/m-1084.gif b/dviware/dvi2bitmap/doc/doc.img/m-1084.gif Binary files differnew file mode 100644 index 0000000000..d50b138baf --- /dev/null +++ b/dviware/dvi2bitmap/doc/doc.img/m-1084.gif diff --git a/dviware/dvi2bitmap/doc/doc.img/m-1095.gif b/dviware/dvi2bitmap/doc/doc.img/m-1095.gif Binary files differnew file mode 100644 index 0000000000..fc440a13ba --- /dev/null +++ b/dviware/dvi2bitmap/doc/doc.img/m-1095.gif diff --git a/dviware/dvi2bitmap/doc/doc.img/m-1102.gif b/dviware/dvi2bitmap/doc/doc.img/m-1102.gif Binary files differnew file mode 100644 index 0000000000..cb70864875 --- /dev/null +++ b/dviware/dvi2bitmap/doc/doc.img/m-1102.gif diff --git a/dviware/dvi2bitmap/doc/doc.img/m-1109.gif b/dviware/dvi2bitmap/doc/doc.img/m-1109.gif Binary files differnew file mode 100644 index 0000000000..3b958a72f0 --- /dev/null +++ b/dviware/dvi2bitmap/doc/doc.img/m-1109.gif diff --git a/dviware/dvi2bitmap/doc/doc.img/m-1137.gif b/dviware/dvi2bitmap/doc/doc.img/m-1137.gif Binary files differnew file mode 100644 index 0000000000..3b958a72f0 --- /dev/null +++ b/dviware/dvi2bitmap/doc/doc.img/m-1137.gif diff --git a/dviware/dvi2bitmap/doc/doc.img/m-1143.gif b/dviware/dvi2bitmap/doc/doc.img/m-1143.gif Binary files differnew file mode 100644 index 0000000000..b904e4ab7e --- /dev/null +++ b/dviware/dvi2bitmap/doc/doc.img/m-1143.gif diff --git a/dviware/dvi2bitmap/doc/doc.img/m-1153.gif b/dviware/dvi2bitmap/doc/doc.img/m-1153.gif Binary files differnew file mode 100644 index 0000000000..cb70864875 --- /dev/null +++ b/dviware/dvi2bitmap/doc/doc.img/m-1153.gif diff --git a/dviware/dvi2bitmap/doc/doc.img/m-1161.gif b/dviware/dvi2bitmap/doc/doc.img/m-1161.gif Binary files differnew file mode 100644 index 0000000000..386ff777ed --- /dev/null +++ b/dviware/dvi2bitmap/doc/doc.img/m-1161.gif diff --git a/dviware/dvi2bitmap/doc/doc.img/m-1165.gif b/dviware/dvi2bitmap/doc/doc.img/m-1165.gif Binary files differnew file mode 100644 index 0000000000..1836bf0217 --- /dev/null +++ b/dviware/dvi2bitmap/doc/doc.img/m-1165.gif diff --git a/dviware/dvi2bitmap/doc/doc.img/m-1171.gif b/dviware/dvi2bitmap/doc/doc.img/m-1171.gif Binary files differnew file mode 100644 index 0000000000..51eb6ace58 --- /dev/null +++ b/dviware/dvi2bitmap/doc/doc.img/m-1171.gif diff --git a/dviware/dvi2bitmap/doc/doc.img/m-1174.gif b/dviware/dvi2bitmap/doc/doc.img/m-1174.gif Binary files differnew file mode 100644 index 0000000000..4fbe29ba59 --- /dev/null +++ b/dviware/dvi2bitmap/doc/doc.img/m-1174.gif diff --git a/dviware/dvi2bitmap/doc/doc.img/m-1175.gif b/dviware/dvi2bitmap/doc/doc.img/m-1175.gif Binary files differnew file mode 100644 index 0000000000..7570e4b30d --- /dev/null +++ b/dviware/dvi2bitmap/doc/doc.img/m-1175.gif diff --git a/dviware/dvi2bitmap/doc/doc.img/m-1176.gif b/dviware/dvi2bitmap/doc/doc.img/m-1176.gif Binary files differnew file mode 100644 index 0000000000..ea3a80dc51 --- /dev/null +++ b/dviware/dvi2bitmap/doc/doc.img/m-1176.gif diff --git a/dviware/dvi2bitmap/doc/doc.img/m-1177.gif b/dviware/dvi2bitmap/doc/doc.img/m-1177.gif Binary files differnew file mode 100644 index 0000000000..ed321ff840 --- /dev/null +++ b/dviware/dvi2bitmap/doc/doc.img/m-1177.gif diff --git a/dviware/dvi2bitmap/doc/doc.img/m-175.gif b/dviware/dvi2bitmap/doc/doc.img/m-175.gif Binary files differnew file mode 100644 index 0000000000..114b2d50a0 --- /dev/null +++ b/dviware/dvi2bitmap/doc/doc.img/m-175.gif diff --git a/dviware/dvi2bitmap/doc/doc.img/m-177.gif b/dviware/dvi2bitmap/doc/doc.img/m-177.gif Binary files differnew file mode 100644 index 0000000000..a414eacaae --- /dev/null +++ b/dviware/dvi2bitmap/doc/doc.img/m-177.gif diff --git a/dviware/dvi2bitmap/doc/doc.img/m-179.gif b/dviware/dvi2bitmap/doc/doc.img/m-179.gif Binary files differnew file mode 100644 index 0000000000..114b2d50a0 --- /dev/null +++ b/dviware/dvi2bitmap/doc/doc.img/m-179.gif diff --git a/dviware/dvi2bitmap/doc/doc.img/m-429.gif b/dviware/dvi2bitmap/doc/doc.img/m-429.gif Binary files differnew file mode 100644 index 0000000000..f2f800fcbd --- /dev/null +++ b/dviware/dvi2bitmap/doc/doc.img/m-429.gif diff --git a/dviware/dvi2bitmap/doc/doc.img/m-436.gif b/dviware/dvi2bitmap/doc/doc.img/m-436.gif Binary files differnew file mode 100644 index 0000000000..fd600a70a3 --- /dev/null +++ b/dviware/dvi2bitmap/doc/doc.img/m-436.gif diff --git a/dviware/dvi2bitmap/doc/style.css b/dviware/dvi2bitmap/doc/style.css new file mode 100644 index 0000000000..f3594af7f5 --- /dev/null +++ b/dviware/dvi2bitmap/doc/style.css @@ -0,0 +1,128 @@ +body { + /* color: navy; */ + color: #000033; + background: white; + margin-left: 10%; + margin-right: 10%; +} + +/* Link colours should be specified, since text colour was in <body> */ +a:link { color: #009; } +a:active: { color: #00C; } +a:visited { color: #600; } +a[href]:hover { background: #FF9; } /* CSS2 */ + +h1 { + background: #CCF; + padding: 1em; + border-style: none; + margin-left: -10%; + margin-right: -10%; + font-family: Optima, Arial, sans-serif; +} +h2 { + margin-left: -5%; + font-family: Optima, Arial, sans-serif; +} +h3, h4, h5, h6 { + font-family: Optima, Arial, sans-serif; +} + +p.figure { + text-align: center; +} + +p.copyright { + font-size: x-small; +} + +dt { + margin-left: +5%; + font-style: italic; + margin-top: 0.5ex; +} +dd { + margin-bottom: 0.5ex; +} + +li { + margin-top: 0.5ex; + margin-bottom: 0.5ex; +} + +img.smallimage { + float: right; +} + +img.smallimageleft { + float: left; +} + +pre { + margin: +5%; + background: #FF9; + clear: both; +} + +pre.doc-history { + margin-left: 30%; + font-family: Optima, Arial, sans-serif; + font-size: x-small; + background: #EEE; +} + +tr.header { + background-color: navy; + color: white; +} +tr.odd { + background-color: #CCF; +} +tr.even { + background-color: #AAF; +} +/* classes r0 and r1 are easier to generate programmatically */ +tr.r0 { + background-color: #CCF; +} +tr.r1 { + background-color: #AAF; +} +td { + /* Hmmm, I still get the background showing through... */ + border-style: none; + padding: 0px; + margin: 2px; +} + +q:before { content: "`"; } +q:after { content: "\'"; } +/* +q:before { content: open-quote; } +q:after { content: close-quote; } +*/ + +div.abstract { + margin-left: 30%; + margin-right: 0%; + font-style: oblique; + text-align: justify; +} + +div.abstract em { font-style: normal; } + +div.signature { + font-style: oblique; + text-align: right; + margin-left: -10%; + margin-right: -10%; + background: #CCCCFF; + + padding: 1em; + border-width: thin; + border-top: ridge; + border-left: none; + border-right: none; + border-bottom: none; + border-color: black; +} diff --git a/dviware/dvi2bitmap/doc/xml2html/Makefile b/dviware/dvi2bitmap/doc/xml2html/Makefile new file mode 100644 index 0000000000..9507f07b5d --- /dev/null +++ b/dviware/dvi2bitmap/doc/xml2html/Makefile @@ -0,0 +1,20 @@ +# Include this Makefile to include the following rules. +# Before inclusion, set the XML2HTML variable to be the path to this directory. +#XML2HTML=. + +%.xhtml: %.xml + rm -f $@ $@.tmp + $(XSLTPROC) --stringparam document-id $$PWD/$< $(XML2HTML)/structure.xslt $< >$@.tmp && mv $@.tmp $@ +%.html: %.xhtml + rm -f $@ $@.tmp + $(XSLTPROC) $(XML2HTML)/identity-html.xslt $< >$@.tmp && mv $@.tmp $@ +%.aux: %.xml + rm -f $@ $(@:=.tmp) + $(XSLTPROC) --stringparam document-id $$PWD/$< \ + --stringparam target aux \ + $(XML2HTML)/structure.xslt $< >$@.tmp && mv $@.tmp $@ + printf '\\bibstyle{unsrthtml}\n' >>$@ +%.bbl: %.aux + BSTINPUTS=$(STYLE) bibtex $< + sed -f $(STYLE)/detex.sed -e '1s+<dl>+<dl xmlns="http://www.w3.org/1999/xhtml">+' $@ >$@.tmp + mv $@.tmp $@ |
