summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/info/dvipng.info
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2013-04-07 18:26:53 +0000
committerKarl Berry <karl@freefriends.org>2013-04-07 18:26:53 +0000
commitb04c2e1a42573e9735547702356c7b9a769a6855 (patch)
treec0753443f39500a062d7698fe6b94359c813f871 /Master/texmf-dist/doc/info/dvipng.info
parentfb0bf13304a356f197bfc1add17f98c07e96f17b (diff)
texmf -> texmf-dist: doc
git-svn-id: svn://tug.org/texlive/trunk@29714 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/info/dvipng.info')
-rw-r--r--Master/texmf-dist/doc/info/dvipng.info1211
1 files changed, 1211 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/info/dvipng.info b/Master/texmf-dist/doc/info/dvipng.info
new file mode 100644
index 00000000000..62d070278ad
--- /dev/null
+++ b/Master/texmf-dist/doc/info/dvipng.info
@@ -0,0 +1,1211 @@
+This is dvipng.info, produced by makeinfo version 4.13 from dvipng.texi.
+
+INFO-DIR-SECTION TeX
+START-INFO-DIR-ENTRY
+* DVI-to-PNG: (dvipng). Translating TeX DVI files to Portable Network Graphics (PNG).
+* dvipng: (dvipng). A DVI-to-PNG translator.
+END-INFO-DIR-ENTRY
+
+
+File: dvipng.info, Node: Top, Next: Introduction, Up: (dir)
+
+dvipng
+******
+
+This manual documents dvipng, a program to translate a DVI (DeVice
+Independent) file into PNG (Portable Network Graphics).
+
+ This file documents dvipng version 1.14
+
+ Corrections or perhaps rewrites of sections are _very welcome_.
+
+ Jan-AAke Larsson
+
+* Menu:
+
+* Introduction:: Introduction
+* Installation:: How to compile and install dvipng
+* Basic usage:: First things first
+* Command-line options:: Advanced usage
+* Graphics:: Including PostScript and/or bitmaps
+* Color:: Using color with dvipng
+* Diagnosing problems:: Problems?
+* Credits:: People who have contributed
+* Copying:: GNU Lesser General Public License
+* Index:: General index
+
+
+File: dvipng.info, Node: Introduction, Next: Installation, Prev: Top, Up: Top
+
+1 Introduction
+**************
+
+This program makes PNG and/or GIF graphics from DVI files as obtained
+from TeX and its relatives.
+
+ If GIF support is enabled, GIF output is chosen by using the
+`dvigif' binary or with the `--gif' option.
+
+ It is intended to produce anti-aliased screen-resolution images as
+fast as is possible. The target audience is people who need to generate
+and regenerate many images again and again. The primary target is the
+preview-latex (X)Emacs package, a package to preview formulas from
+within (X)Emacs. Yes, you get to see your formulas in the (X)Emacs
+buffer, see `http://www.gnu.org/software/auctex/preview-latex.html'.
+
+ Another example is WeBWorK, an internet-based method for delivering
+homework problems to students over the internet, giving students
+instant feedback as to whether or not their answers are correct, see
+`http://webwork.math.rochester.edu'.
+
+ A more recent addition to the dvipng-using applications out there is
+MediaWiki, the software behind Wikipedia and many other wikis out
+there. Dvipng is used to render mathematical formulae from version
+1.8.0 of MediaWiki, see `http://www.mediawiki.org'.
+
+ Other applications may also benefit, like web applications as
+latex2html and WYSIWYG editors like LyX.
+
+ The benefits of `dvipng'/`dvigif' include
+
+ * Speed. It is a very fast bitmap-rendering code for DVI files, which
+ makes it suitable for generating large amounts of images
+ on-the-fly, as needed in preview-latex, WeBWorK and others.
+
+ * It does not read the postamble, so it can be started before TeX
+ finishes. There is a `--follow' switch that makes dvipng wait at
+ end-of-file for further output, unless it finds the POST marker
+ that indicates the end of the DVI.
+
+ * Interactive query of options. dvipng can read options interactively
+ through stdin, and all options are usable. It is even possible to
+ change the input file through this interface.
+
+ * Supports PK, VF, PostScript Type1, and TrueType fonts, subfonts
+ (i.e., as used in CJK-LaTeX), color specials, and inclusion of
+ PostScript, PNG, JPEG or GIF images.
+
+ * and more...
+
+
+
+File: dvipng.info, Node: Installation, Next: Basic usage, Prev: Introduction, Up: Top
+
+2 Installation
+**************
+
+Installing dvipng should be simple: merely `./configure', `make', and
+`make install'.
+
+* Menu:
+
+* Prerequisites::
+* Configure::
+* Build/install::
+* Installation outside the texmf tree::
+* Advice for non-privileged users::
+
+
+File: dvipng.info, Node: Prerequisites, Next: Configure, Up: Installation
+
+2.1 Prerequisites
+=================
+
+ * The GD Graphics Draw library, libgd
+
+ The drawing library `libgd' is necessary, and is downloadable at
+ `http://www.boutell.com/gd', and there are binary packages for
+ most operating systems from their respective distributors. In any
+ case, the latest version of the library installs using `autoconf'
+ so it should not be difficult for you to install it from source,
+ and then proceed with installing dvipng.
+
+ * The path-searching library kpathsea
+
+ Kpathsea is most likely included in your LaTeX installation, but it
+ may happen that ./configure does not find it; see below. If you do
+ not have it, download it from `http://www.ctan.org' and compile it.
+ I have no experience with this, so I cannot help much here.
+
+ * The font-rendering library FreeType 2
+
+ While not strictly necessary, a recent FreeType 2 is recommended
+ since dvipng currently will produce better-quality images when
+ this library is available. To take advantage of this, you should
+ have at least FreeType 2.1.9.
+
+ FreeType 2 will enable direct support for PostScript and TrueType
+ fonts, so that dvipng will not need to generate bitmapped variants
+ on disk of the TeX fonts since modern TeX distributions include
+ PostScript versions of them. Then, you can render images at
+ different (and unusual) resolutions without cluttering the disk
+ with lots of bitmapped fonts.
+
+ Finally, it will enable subfont support in dvipng. That is, if you
+ want to render CJK-LaTeX characters, you must have FreeType 2
+ installed.
+
+ * The font-rendering library T1lib
+
+ An alternative to FreeType 2 is T1lib, but this will enable only
+ PostScript fonts in dvipng and will not include subfont support.
+ Also here, you can render images at different (and unusual)
+ resolutions without cluttering the disk with lots of bitmapped
+ fonts. If both FreeType 2 and T1lib are present, FreeType will be
+ internally preferred by dvipng but T1lib can be chosen at runtime.
+
+ * libpng and libz
+
+ To be able to compress and write PNG files to disk, dvipng (or
+ really libgd) uses libpng which in turn uses libz. These should be
+ available on any modern system, if not, download them and install
+ them.
+
+ * The `texinfo' package
+
+ This is needed for building the documentation.
+
+
+File: dvipng.info, Node: Configure, Next: Build/install, Prev: Prerequisites, Up: Installation
+
+2.2 Configure
+=============
+
+The first step is to configure the source code, telling it where
+various files will be. To do so, run
+
+ ./configure OPTIONS
+
+ (Note: if you have fetched dvipng from CVS rather than a regular
+release, you will have to first generate `./configure' by running
+`autoconf' 2.53 or later.)
+
+ On many machines, you will not need to specify any options, but if
+`configure' cannot determine something on its own, you'll need to help
+it out. For a list of the options type
+
+ ./configure --help
+
+ On some machines, the libraries will be installed in directories that
+are not in the linker's search path. This will generate an error when
+running `./configure', indicating that it cannot find libgd or
+libkpathsea (most likely). You then need to specify the path to the
+respective library's object files. They are typically called e.g.,
+`libgd.a' or `libgd.so'. If they are located in e.g., `/sw/local/lib',
+do
+
+ ./configure LDFLAGS=-L/sw/local/lib
+
+ If the library is available as a shared object file (`.so'), the
+runtime linker may also need to be told where to find the library, then
+use
+
+ ./configure LDFLAGS='-L/sw/local/lib -R/sw/local/lib'
+
+ When either of these is necessary, it is likely that the C header
+files are also installed in directories that are not in the C
+preprocessor's search path. This will also generate an error when
+running `./configure', indicating that it cannot find e.g., `gd.h' or
+`kpathsea.h' (most likely). You then need to specify the path to the
+respective library's C header files. If they are located in e.g.,
+`/sw/local/include', do
+
+ ./configure CPPFLAGS=-I/sw/local/include
+
+ On my SUN Solaris workstation, I had to combine this into
+
+ ./configure CPPFLAGS='-I/sw/local/include -I/sw/tex/teTeX/1.0/include'\
+ LDFLAGS='-L/sw/local/lib -R/sw/local/lib -L/sw/tex/teTeX/1.0/lib/'
+
+where the backslash denotes a continuation of the line.
+
+
+File: dvipng.info, Node: Build/install, Next: Installation outside the texmf tree, Prev: Configure, Up: Installation
+
+2.3 Build/install
+=================
+
+Once `configure' has been run, simply enter
+
+ make
+
+at the prompt to compile the C code, and build the documentation files.
+To install the files into the locations chosen earlier, type
+
+ make install
+
+You may need special privileges to install, e.g., if you are installing
+into system directories.
+
+
+File: dvipng.info, Node: Installation outside the texmf tree, Next: Advice for non-privileged users, Prev: Build/install, Up: Installation
+
+2.4 Installation outside the texmf tree
+=======================================
+
+In some cases, a dvipng binary installed outside the texmf tree will
+not be able to find virtual fonts, or the PostScript font maps
+(normally used by dvips). This may be because _only_ $SELFAUTOLOC,
+$SELFAUTODIR, and $SELFAUTOPARENT are used in the texmf tree
+configuration file `texmf.cnf'. If so, give the switch
+`--enable-selfauto-set' to `./configure'. This will make dvipng adjust
+these three internally so that kpathsea thinks that dvipng _is_
+installed in the texmf tree.
+
+
+File: dvipng.info, Node: Advice for non-privileged users, Prev: Installation outside the texmf tree, Up: Installation
+
+2.5 Installation for non-privileged users
+=========================================
+
+Often people without system administration privileges want to install
+software for their private use. In that case you need to specify more
+options to the `configure' script, usually this is done by using the
+`--prefix' option to the `configure' script, and let it point to the
+personal home directory. In that way, resulting binaries will be
+installed under the `bin' subdirectory of your home directory, manual
+pages under `man' and so on. That way, it is reasonably easy to
+maintain a bunch of additional packages, since the prefix argument is
+supported by most `configure' scripts.
+
+ You'll have to add something like `/home/myself/bin' to your `PATH'
+shell variable, if it isn't there already, and similarly set the
+`INFOPATH' and `MANPATH' variables to be able to access the
+documentation.
+
+
+File: dvipng.info, Node: Basic usage, Next: Command-line options, Prev: Installation, Up: Top
+
+3 Basic usage of dvipng
+***********************
+
+To use dvipng at its simplest, simply type
+
+ dvipng foo
+
+where `foo.dvi' is the output of TeX that you want to convert to PNG
+format. If there are four pages in `foo.dvi', those pages will be
+output as `foo1.png', `foo2.png', `foo3.png', and `foo4.png',
+respectively.
+
+ If you have enabled the PostScript font support (via FreeType or
+T1lib), fonts will be rendered as they are needed. Otherwise, dvipng
+will use bitmapped (PK) fonts, and if you use PK fonts that have not
+been used on your system before, they may be automatically generated;
+this process can take a few minutes, so progress reports appear by
+default. The next time the same font is used, it will have been saved
+on disk, so rendering will go much faster. (If dvipng tries to
+endlessly generate the same fonts over and over again, something is
+wrong. *Note Unable to generate fonts: (kpathsea)Unable to generate
+fonts.)
+
+ Many options are available (see the next section). For a brief
+summary of available options, just type
+
+ dvipng --help
+
+
+File: dvipng.info, Node: Command-line options, Next: Graphics, Prev: Basic usage, Up: Top
+
+4 Command-line options
+**********************
+
+dvipng has a plethora of command line options. Reading through this
+section will give a good idea of the capabilities of the driver.
+
+* Menu:
+
+* Option summary:: Quick listing, from dvipng --help.
+* Option details:: More information about each option.
+
+
+File: dvipng.info, Node: Option summary, Next: Option details, Up: Command-line options
+
+4.1 Option summary
+==================
+
+Here is a handy summary of the options; it is printed out when you run
+dvipng with no arguments or with the standard `--help' option.
+
+ This is ./dvipng 1.14 Copyright 2002-2010 Jan-Ake Larsson
+
+ Usage: ./dvipng [OPTION]... FILENAME[.dvi]
+ Options are chosen to be similar to dvips' options where possible:
+ -d # Debug (# is the debug bitmap, 1 if not given)
+ -D # Output resolution
+ -l # Last page to be output
+ -o f Output file, '%d' is pagenumber
+ -O c Image offset
+ -p # First page to be output
+ -pp #,#.. Page list to be output
+ -q* Quiet operation
+ -T c Image size (also accepts '-T bbox' and '-T tight')
+ -v* Verbose operation
+ - Interactive query of options
+
+ These do not correspond to dvips options:
+ -bd # Transparent border width in dots
+ -bd s Transparent border fallback color (TeX-style color)
+ -bg s Background color (TeX-style color or 'Transparent')
+ --depth* Output the image depth on stdout
+ --dvinum* Use TeX page numbers in output filenames
+ -fg s Foreground color (TeX-style color)
+ --follow* Wait for data at end-of-file
+ --freetype* FreeType font rendering (preferred, default on)
+ --gamma # Control color interpolation
+ --gif Output GIF images (dvigif default)
+ --height* Output the image height on stdout
+ --nogs* Don't use ghostscript for PostScript specials
+ --nogssafer* Don't use -dSAFER in ghostscript calls
+ --norawps* Don't convert raw PostScript specials
+ --palette* Force palette output
+ --picky When a warning occurs, don't output image
+ --png Output PNG images (dvipng default)
+ --strict When a warning occurs, exit
+ --t1lib* T1lib font rendering (default on)
+ --truecolor* Truecolor output
+ -Q # Quality (T1lib and PK subsampling)
+ --width* Output the image width on stdout
+ -z # PNG compression level
+
+ # = number f = file s = string * = suffix, '0' to turn off
+ c = comma-separated dimension pair (e.g., 3.2in,-32.1cm)
+
+
+File: dvipng.info, Node: Option details, Prev: Option summary, Up: Command-line options
+
+4.2 Option details
+==================
+
+Many of the parameterless options listed here can be turned off by
+suffixing the option with a zero (`0'); for instance, to turn off page
+reversal, use `-r0'. Such options are marked with a trailing `*'.
+
+`-'
+ Read additional options from standard input after processing the
+ command line.
+
+`--help'
+ Print a usage message and exit.
+
+`--version'
+ Print the version number and exit.
+
+`-bd NUM'
+
+`-bd COLOR_SPEC'
+
+`-bd 'NUM COLOR_SPEC''
+ Set the pixel width of the transparent border (default 0). Using
+ this option will make the image edges transparent, but it only
+ affects pixels with the background color. Giving a COLOR_SPEC will
+ set the fallback color, to be used in viewers that cannot handle
+ transparency (the default is the background color). The color spec
+ should be in TeX color \special syntax, e.g., 'rgb 1.0 0.0 0.0'.
+ Setting the fallback color makes the default border width 1 px.
+ *Note Color::.
+
+`--bdpi NUM'
+ This option only has an effect when using bitmapped (PK) fonts. The
+ option sets the base (Metafont) resolution, both horizontal and
+ vertical, to NUM dpi (dots per inch). This option is necessary
+ when manually selecting Metafont mode with the -mode option (see
+ below).
+
+`-bg COLOR_SPEC'
+ Choose background color for the images. This option will be
+ ignored if there is a background color \special in the DVI. The
+ color spec should be in TeX color \special syntax, e.g., 'rgb 1.0
+ 0.0 0.0'. You can also specify 'Transparent' or 'transparent'
+ which will give you a transparent background with the normal
+ background as a fallback color. A capitalized 'Transparent' will
+ give a full-alpha transparency, while an all-lowercase
+ 'transparent' will give a simple fully transparent background with
+ non-transparent antialiased pixels. The latter would be suitable
+ for viewers who cannot cope with a true alpha channel. GIF images
+ do not support full alpha transparency, so in case of GIF output,
+ both variants will use the latter behaviour. *Note Color::.
+
+`-d NUM'
+ Set the debug flags, showing what dvipng (thinks it) is doing.
+ This will work unless dvipng has been compiled without the `DEBUG'
+ option (not recommended). Set the flags as you need them, use `-d
+ -1' as the first option for maximum output. *Note Debug options::.
+
+`-D NUM'
+ Set the output resolution, both horizontal and vertical, to NUM
+ dpi (dots per inch).
+
+ One may want to adjust this to fit a certain text font size (e.g.,
+ on a web page), and for a text font height of FONT_PX pixels (in
+ Mozilla) the correct formula is
+ DPI = FONT_PX * 72.27 / 10 [px * TeXpt/in / TeXpt]
+ The last division by ten is due to the standard font height 10pt in
+ your document, if you use 12pt, divide by 12. Unfortunately, some
+ proprietary browsers have font height in pt (points), not pixels.
+ You have to rescale that to pixels, using the screen resolution
+ (default is usually 96 dpi) which means the formula is
+ FONT_PX = FONT_PT * 96 / 72 [pt * px/in / (pt/in)]
+ On some high-res screens, the value is instead 120 dpi. Good luck!
+
+`--depth*'
+ Report the depth of the image. This only works reliably when the
+ LaTeX style `preview.sty' from preview-latex is used with the
+ `active' option. It reports the number of pixels from the bottom
+ of the image to the baseline of the image. This can be used for
+ vertical positioning of the image in, e.g., web documents, where
+ one would use (Cascading StyleSheets 1)
+ <IMG SRC="FILENAME.PNG" STYLE="vertical-align: -DEPTHpx">
+ The depth is a negative offset in this case, so the minus sign is
+ necessary, and the unit is pixels (px).
+
+`--dvinum*'
+ Set this option to make the output page number be the TeX page
+ numbers rather than the physical page number. See the `-o' switch.
+
+`-fg COLOR_SPEC'
+ Choose foreground color for the images. This option will be
+ ignored if there is a foreground color \special in the DVI. The
+ color spec should be in TeX color \special syntax, e.g., 'rgb 1.0
+ 0.0 0.0'. *Note Color::.
+
+`--follow*'
+ Wait for data at end-of-file. One of the benefits of dvipng is
+ that it does not read the postamble, so it can be started before
+ TeX finishes. This switch makes dvipng wait at end-of-file for
+ further output, unless it finds the POST marker that indicates the
+ end of the DVI. This is similar to `tail -f' but for DVI-to-PNG
+ conversion.
+
+`--freetype*'
+ Enable/disable FreeType font rendering (default on). This option is
+ available if the FreeType2 font library was present at compilation
+ time. If this is the case, dvipng will have direct support for
+ PostScript Type1 and TrueType fonts internally, rather than using
+ `gsftopk' for rendering the fonts. If you have PostScript versions
+ of Computer Modern installed, there will be no need to generate
+ bitmapped (PK) variants on disk of these. Then, you can render
+ images at different (and unusual) resolutions without cluttering
+ the disk with lots of bitmapped fonts. Note that if you have both
+ FreeType and T1lib on your system, FreeType will be preferred by
+ dvipng. If you for some reason would want to use T1lib rendering,
+ use this option.
+
+`--gamma NUM'
+ Control the interpolation of colors in the greyscale anti-aliasing
+ color palette. Default value is 1.0. For 0 < NUM < 1, the fonts
+ will be lighter (more like the background), and for NUM > 1, the
+ fonts will be darker (more like the foreground).
+
+`--gif*'
+ The images are output in the GIF format, if GIF support is enabled.
+ This is the default for the `dvigif' binary, which only will be
+ available when GIF support is enabled. GIF images are palette
+ images (see the `--palette' option) and does not support true alpha
+ channels (see the `--bg' option). See also the `--png' option.
+
+`--height*'
+ Report the height of the image. This only works reliably when the
+ LaTeX style `preview.sty' from preview-latex is used with the
+ `active' option. It reports the number of pixels from the top of
+ the image to the baseline of the image. The total height of the
+ image is obtained as the sum of the values reported from
+ `--height' and `--depth'.
+
+`-l [=]NUM'
+ The last page printed will be the first one numbered NUM. Default
+ is the last page in the document. If NUM is prefixed by an equals
+ sign, then it (and the argument to the `-p' option, if specified)
+ is treated as a physical (absolute) page number, rather than a
+ value to compare with the TeX `\count0' values stored in the DVI
+ file. Thus, using `-l =9' will end with the ninth page of the
+ document, no matter what the pages are actually numbered.
+
+`--mode MODE'
+ This option only has an effect when using bitmapped (PK) fonts. Use
+ MODE as the Metafont device name for the PK fonts (both for path
+ searching and font generation). This needs to be augmented with
+ the base device resolution, given with the `--bdpi' option. See
+ the file `ftp://ftp.tug.org/tex/modes.mf' for a list of
+ resolutions and mode names for most devices. *Note Unable to
+ generate fonts: (kpathsea)Unable to generate fonts.
+
+`-M*'
+ This option only has an effect when using bitmapped (PK) fonts. It
+ turns off automatic PK font generation (`mktexpk').
+
+`--nogs*'
+ This switch prohibits the internal call to GhostScript for
+ displaying PostScript specials. `--nogs0' turns the call back on.
+
+`--nogssafer*'
+ Normally, if GhostScript is used to render PostScript specials, the
+ GhostScript interpreter is run with the option `-dSAFER'. The
+ `--nogssafer' option runs GhostScript without `-dSAFER'. The
+ `-dSAFER' option in Ghostscript disables PostScript operators such
+ as deletefile, to prevent possibly malicious PostScript programs
+ from having any effect.
+
+`--norawps*'
+ Some packages generate raw PostScript specials, even non-rendering
+ such specials. This switch turns off the internal call to
+ GhostScript intended to display these raw PostScript specials.
+ `--norawps0' turns the call back on.
+
+`-o NAME'
+ Send output to the file NAME. A single occurrence of `%d' or
+ `%01d', ..., `%09d' will be exchanged for the physical page number
+ (this can be changed, see the `--dvinum' switch). The default
+ output filename is `FILE%d.png' where the input DVI file was
+ `FILE.dvi'.
+
+`-O X-OFFSET,Y-OFFSET'
+ Move the origin by X-OFFSET,Y-OFFSET, a comma-separated pair of
+ dimensions such as `.1in,-.3cm'. The origin of the page is
+ shifted from the default position (of one inch down, one inch to
+ the right from the upper left corner of the paper) by this amount.
+
+`-p [=]NUM'
+ The first page printed will be the first one numbered NUM. Default
+ is the first page in the document. If NUM is prefixed by an
+ equals sign, then it (and the argument to the `-l' option, if
+ specified) is treated as a physical (absolute) page number, rather
+ than a value to compare with the TeX `\count0' values stored in the
+ DVI file. Thus, using `-p =3' will start with the third page of
+ the document, no matter what the pages are actually numbered.
+
+`--palette*'
+ When an external image is included, `dvipng' will automatically
+ switch to truecolor mode, to avoid unnecessary delay and quality
+ reduction, and enable the EPS translator to draw on a transparent
+ background and outside of the boundingbox. This switch will force
+ palette (256-color) output and make `dvipng' revert to opaque
+ clipped image inclusion. This will also override the `--truecolor'
+ switch if present.
+
+`--picky*'
+ No images are output when a warning occurs. Normally, dvipng will
+ output an image in spite of a warning, but there may be something
+ missing in this image. One reason to use this option would be if
+ you have a more complete but slower fallback converter. Mainly,
+ this is useful for failed figure inclusion and unknown \special
+ occurrences, but warnings will also occur for missing or unknown
+ color specs and missing PK fonts.
+
+`--png*'
+ The images are output in the PNG format. This is the default for
+ the `dvipng' binary. See also the `--gif' option.
+
+`-pp FIRSTPAGE-LASTPAGE'
+ Print pages FIRSTPAGE through LASTPAGE; but not quite equivalent
+ to `-p FIRSTPAGE -l LASTPAGE'. For example, when rendering a book,
+ there may be several instances of a page in the DVI file (one in
+ `\frontmatter', one in `\mainmatter', and one in `\backmatter').
+ In case of several pages matching, `-pp FIRSTPAGE-LASTPAGE' will
+ render _all_ pages that matches the specified range, while `-p
+ FIRSTPAGE -l LASTPAGE' will render the pages from the _first_
+ occurrence of FIRSTPAGE to the _first_ occurrence of LASTPAGE.
+ This is the (undocumented) behaviour of dvips. In dvipng you can
+ give both kinds of options, in which case you get all pages that
+ matches the range in `-pp' between the pages from `-p' to `-l'.
+ Also multiple `-pp' options accumulate, unlike `-p' and `-l'. The
+ `-' separator can also be `:'. Note that `-pp -1' will be
+ interpreted as "all pages up to and including 1", if you want a
+ page numbered -1 (only the table of contents, say) put `-pp -1--1',
+ or more readable, `-pp -1:-1'.
+
+`-q*'
+ Run quietly. Don't chatter about pages converted, etc. to standard
+ output; report no warnings (only errors) to standard error.
+
+`-Q NUM'
+ Set the quality to NUM. That is, choose the number of antialiasing
+ levels for bitmapped fonts (PK) and fonts rendered using T1lib, to
+ be NUM*NUM+1. The default value is 4 which gives 17 levels of
+ antialiasing for antialiased fonts from these two. If FreeType is
+ available, its rendering is unaffected by this option.
+
+`-r*'
+ Toggle output of pages in reverse/forward order. By default, the
+ first page in the DVI is output first.
+
+`--strict*'
+ The program exits when a warning occurs. Normally, dvipng will
+ output an image in spite of a warning, but there may be something
+ missing in this image. One reason to use this option would be if
+ you have a more complete but slower fallback converter. See the
+ `--picky' option above for a list of when warnings occur.
+
+`-T IMAGE_SIZE'
+ Set the image size to IMAGE_SIZE which can be either of `bbox',
+ `tight', or a comma-separated pair of dimensions HSIZE,VSIZE such
+ as `.1in,.3cm'. The default is `bbox' which produces a PNG that
+ includes all ink put on the page and in addition the DVI origin,
+ located 1in from the top and 1in from the left edge of the paper.
+ This usually gives whitespace above and to the left in the
+ produced image. The value `tight' will make dvipng only include
+ all ink put on the page, producing neat images.
+
+`--t1lib*'
+ Enable T1lib font rendering (default on). This option is available
+ if the T1lib font library was present at compilation time. If this
+ is the case, dvipng will have direct support for PostScript Type1
+ fonts internally, rather than using `gsftopk' for rendering the
+ fonts. If you have PostScript versions of Computer Modern
+ installed, there will be no need to generate bitmapped variants on
+ disk of these. Then, you can render images at different (and
+ unusual) resolutions without cluttering the disk with lots of
+ bitmapped fonts. Note that if you have both FreeType and T1lib on
+ your system, FreeType will be preferred by dvipng, and if you for
+ some reason rather want to use T1lib, give the option
+ `--freetype0' (see above).
+
+`--truecolor*'
+ This will make `dvipng' generate truecolor output. Note that
+ truecolor output is automatic if you include an external image in
+ your DVI, e.g., via a PostScript special (i.e., the `graphics' or
+ `graphicx' package). This switch is overridden by the `--palette'
+ switch.
+
+`-v*'
+ Enable verbose operation. This will currently indicate what fonts
+ is used, in addition to the usual output.
+
+`--width*'
+ Report the width of the image. See also `--height' and `--depth'.
+
+`-x NUM'
+ This option is deprecated; it should not be used. It is much
+ better to select the output resolution directly with the `-D'
+ option. This option sets the magnification ratio to NUM/1000 and
+ overrides the magnification specified in the DVI file. Must be
+ between 10 and 100000. It is recommended that you use standard
+ magstep values (1095, 1200, 1440, 1728, 2074, 2488, 2986, and so
+ on) to help reduce the total number of PK files generated. NUM
+ may be a real number, not an integer, for increased precision.
+
+`-z NUM'
+ Set the PNG compression level to NUM. This option is enabled if
+ your `libgd' is new enough. The default compression level is 1,
+ which selects maximum speed at the price of slightly larger PNGs.
+ For an older `libgd', the hard-soldered value 5 is used. The
+ include file `png.h' says
+
+ Currently, valid values range from 0 - 9, corresponding
+ directly to the zlib compression levels 0 - 9 (0 - no
+ compression, 9 - "maximal" compression). Note that tests have
+ shown that zlib compression levels 3-6 usually perform as
+ well as level 9 for PNG images, and do considerably fewer
+ calculations. In the future, these values may not correspond
+ directly to the zlib compression levels.
+
+
+File: dvipng.info, Node: Graphics, Next: Color, Prev: Command-line options, Up: Top
+
+5 Graphics
+**********
+
+`dvipng' attempts to handle graphics as included by the `graphicx' and
+`graphics' packages, without the need of specifying a driver to these
+packages. This means that it recognizes the encapsulated postscript
+inclusion meant for `dvips', but is also able (from version 1.8) to
+include bitmapped graphics. It also tries to handle some of the raw
+PostScript that is output from various packages. Some of the
+possibilities and problems are mentioned below.
+
+* Menu:
+
+* Encapsulated PostScript:: An internal call to GhostScript
+* Bitmapped graphics:: PNG, JPEG and GIF
+* Raw PostScript:: Ignore or give to GhostScript
+
+
+File: dvipng.info, Node: Encapsulated PostScript, Next: Bitmapped graphics, Up: Graphics
+
+5.1 Encapsulated PostScript
+===========================
+
+When an EPS file is included, a call to GhostScript is performed to
+produce a bitmapped image that can be included. The default is to
+produce an image with transparent background, at the same size as the
+DVI page currently being converted to PNG, and include that as
+foreground on the PNG. Of course, if the image is to be cropped, that
+is done. The included image will be a truecolor image, so for maximum
+performance the output PNG will be in truecolor mode as well.
+
+ This conversion needs the `pngalpha' output device to be present in
+your copy of GhostScript. If that device is not present, or you use the
+`--palette' switch or request GIF output, the fallback is to use the
+`png16m' device to produce a cropped opaque image for inclusion. Other
+relevant switches are `--noghostscript' and `--nogssafer'. *Note Option
+details::.
+
+ The most common problem with including graphics is an incorrect
+bounding box. Complain to whoever wrote the software that generated the
+file if the bounding box is indeed incorrect. An adjusted boundingbox
+can be specified in the `\includegraphics' call, as in this example
+(using `graphicx'):
+
+ \includegraphics[bb=10 20 100 200]{imagename.eps}
+
+
+File: dvipng.info, Node: Bitmapped graphics, Next: Raw PostScript, Prev: Encapsulated PostScript, Up: Graphics
+
+5.2 Bitmapped graphics
+======================
+
+dvipng can include PNG, JPEG and GIF graphics. When including such
+images via `\includegraphics' you need to specify the bounding box
+since TeX itself cannot read them from the files in question. The
+bounding box size should be given as `0 0 w h' in pixels, e.g., if the
+file `imagename.png' is 300x400 pixels, the inclusion would read
+
+ \includegraphics[bb=0 0 300 400]{imagename.png}
+
+ The default size is the image size in bp ("big points" in TeX
+nomenclature or PostScript points as other people have it, 72 per inch).
+That is, default resolution will be 72 dpi for included bitmaps, which
+is the default size in the few other bitmap-capable drivers that are
+known to me (dvipdfm and PDFLaTeX).
+
+ If you want 100 dpi you need to specify the width accordingly. You
+just divide your image width by 100: a 135 pixel wide image at 100 dpi
+will take up 1.35 inches. If you want 200 dpi you divide by 200, and so
+on. Simple, eh? The example above at 200 dpi would be 1.5 inches wide:
+
+ \includegraphics[bb=0 0 300 400,witdh=1.5in]{imagename.png}
+
+
+File: dvipng.info, Node: Raw PostScript, Prev: Bitmapped graphics, Up: Graphics
+
+5.3 Raw PostScript
+==================
+
+dvipng attempts to handle raw PostScript. Rendering raw PostScript
+specials is done on top of the page by including a transparent image
+generated by the `pngalpha' device in GhostScript (automatically
+selecting `truecolor' mode in dvipng).
+
+ Included PostScript headers are respected, and if the header
+`tex.pro' is included, dvipng also throws in `color.pro' and
+`special.pro'. The package `xcolor' includes its own headers with color
+names, and this is not only kept as a PostScript header, but is also
+read and interpreted by dvipng itself. An attempt is also made to
+respect the PGF header. The non-rendering specials from `hyperref' are
+handled via some heuristics and do not give an error.
+
+ Really rendering and moving things with raw PostScript specials is
+more troublesome. The \rotatebox macro serves as a good example. The
+dvips driver of the graphicx package surrounds DVI glyphs with
+PostScript code so that after conversion by dvips, the glyphs (now
+themselves in PostScript) will be rotated in the desired way. dvipng
+does not handle this, at present. An attempt has been made to handle
+the rendering specials output by PGF (tikz), and also PSTricks. Some
+things work, but others do not. This is especially clear when mixing
+PostScript and DVI rendering commands such as glyphs. dvipng cannot at
+present detect if PostScript code moves `currentpoint' or rotates the
+frame since GhostScript does not return such information. A
+recommendation would be to produce images from these packages as EPS
+files and include them into your document in the standard manner.
+
+ Another way to handle this would be to use a slower fallback (with
+dvips and gs, for example). If you want to disable raw PostScript
+handling in dvipng, use the switch `--norawps'. This switch turns off
+the internal call to GhostScript intended to display these raw
+PostScript specials. Further, when dvipng encounters raw PostScript and
+the gs call is turned off, it gives a warning. It is now possible to
+use the switch `--picky' to disable page rendering of pages with
+warnings, and use the slower fallback for these pages.
+
+
+File: dvipng.info, Node: Color, Next: Diagnosing problems, Prev: Graphics, Up: Top
+
+6 Color
+*******
+
+To support color, dvipng recognizes a certain set of specials as
+generated by the `color' and `xcolor' style files. These specials start
+with the keyword `color' or the keyword `background', followed by a
+color specification.
+
+* Menu:
+
+* Color specifications::
+* Color specials::
+
+
+File: dvipng.info, Node: Color specifications, Next: Color specials, Up: Color
+
+6.1 Color specifications
+========================
+
+The color specification supported by dvipng is by-value or by-name. The
+by-value spec starts with the name of a color model (one of `rgb',
+`hsb', `cmy', `cmyk', or `gray') followed by the appropriate number of
+parameters. Thus, the color specification `rgb 0.3 0.4 0.5' would
+correspond to the color that is `0.3 0.4 0.5' in its red, blue and
+green values. The color model used internally in dvipng is `RGB'
+(discretized to 256 levels), for details on the formulas used in
+conversion, see the `xcolor' documentation.
+
+ By-name color specifications are single (case-dependent) words and
+are compared with color names defined in `dvipsnam.def' (from the
+`graphics' bundle), `svgnam.def' and `xcolor.sty' (from the `xcolor'
+bundle). See the `xcolor' documentation for a list of names and the
+corresponding colors.
+
+ On the command-line, the name `Transparent' can also be used as an
+argument to `--bg' to choose transparent background. *Note Option
+details::.
+
+
+File: dvipng.info, Node: Color specials, Prev: Color specifications, Up: Color
+
+6.2 Color specials
+==================
+
+We will describe `background' first, since it is the simplest. The
+`background' keyword must be followed by a color specification. That
+color specification is used as a fill color for the background. The
+last `background' special on a page is the one that gets used, and is
+used for the whole of the page image. (This is possible because the
+prescan phase of dvipng notices all of the color specials so that the
+appropriate information can be written out during the second phase.)
+
+ The `color' special itself has three forms. The first is just
+`color' followed by a color specification. In this case, the current
+global color is set to that color; the color stack must be empty when
+such a command is executed.
+
+ The second form is `color push' followed by a color specification.
+This saves the current color on the color stack and sets the color to be
+that given by the color specification. This is the most common way to
+set a color.
+
+ The final form of the `color' special is just `color pop', with no
+color specification; this says to pop the color last pushed on the
+color stack from the color stack and set the current color to be that
+color.
+
+ dvipng correctly handles these color specials across pages, even when
+the pages are rendered repeatedly or in reverse order.
+
+
+File: dvipng.info, Node: Diagnosing problems, Next: Credits, Prev: Color, Up: Top
+
+7 Diagnosing problems
+*********************
+
+You've gone through all the trouble of installing dvipng, carefully read
+all the instructions in this manual, and still can't get something to
+work. The following sections provide some helpful hints if you find
+yourself in such a situation.
+
+* Menu:
+
+* Contact information:: Who to ask.
+* Debug options:: Getting diagnostics.
+
+
+File: dvipng.info, Node: Contact information, Next: Debug options, Up: Diagnosing problems
+
+7.1 Contact information
+=======================
+
+Bug reports should be sent to <dvipng@nongnu.org>.
+
+ Questions, suggestions for new features, pleas for help, and/or
+praise should go to <dvipng@nongnu.org>. For more information on this
+mailing list, send a message with just the word `help' as subject or
+body to <dvipng-request@nongnu.org> or look at
+`http://lists.nongnu.org/mailman/listinfo/dvipng'.
+
+ Offers to support further development will be appreciated. For
+developer access, ask on <dvipng@nongnu.org>.
+
+ For details on the TeX path-searching library, and `mktexpk'
+problems, *note Common problems: (kpathsea)Common problems.
+
+
+File: dvipng.info, Node: Debug options, Prev: Contact information, Up: Diagnosing problems
+
+7.2 Debug options
+=================
+
+The `-d' flag to dvipng helps in tracking down certain errors. The
+parameter to this flag is an integer that tells what errors are
+currently being tracked. To track a certain class of debug messages,
+simply provide the appropriate number given below; if you wish to track
+multiple classes, sum the numbers of the classes you wish to track. To
+track all classes, you can use `-1'.
+
+ Some of these debugging options are actually provided by Kpathsea
+(*note Debugging: (kpathsea)Debugging.).
+
+ The classes are:
+1
+ Normal dvi op-codes
+
+2
+ Virtual fonts
+
+4
+ PK fonts
+
+8
+ TFM files
+
+16
+ Glyph rendering
+
+32
+ FreeType calls
+
+64
+ Encoding loads
+
+128
+ Color specials
+
+256
+ GhostScript specials
+
+512
+ T1lib calls
+
+1024
+ Kpathsea `stat' calls
+
+2048
+ Kpathsea hash table lookups
+
+4096
+ Kpathsea path element expansion
+
+8192
+ Kpathsea path searches
+
+
+
+File: dvipng.info, Node: Credits, Next: Copying, Prev: Diagnosing problems, Up: Top
+
+8 Credits
+*********
+
+A number of persons have contributed, if I forget to mention someone, I
+apologize. First and foremost we have David Kastrup whose preview-latex
+project provided the incentive to write this program. There is also a
+number of people who have contributed by reporting bugs and suggesting
+improvements as the thing has evolved. These include but is perhaps not
+limited to (in semi-random order): Thomas Esser (teTeX), Christian
+Schenk (MIKTeX), Brian R Furry (debian package), Angus Leeming (LyX),
+Thomas Boutell (libgd), John Jones (first user report), Uwe Kern
+(xcolor), Karl Berry and Peter Breitenlohner (TeX Live), David Harvey
+(hinting in Freetype), Neal Harmon, Alan Shutko, Reiner Stieb, Nick
+Alcock, Adam Buchbinder, Svend Tollak Munkejord, James Longstreet,
+Bernhard Simon, Bob McElrath, Georg Schwarz, Jason Farmer, Brian V.
+Smith, Samuel Hathaway, Thomas R. Shemanske, Stephen Gibson, Christian
+Ridderstro"m, Ezra Peisach, William H Wheeler, Thomas Klausner, Harald
+Koenig, Adrian Bunk, Kevin Smith, Jason Riedy, Wolfram Krause, Reinhard
+Kotucha, Takeshi Abe, and Waldeck Schutzer.
+
+ Use of the `gd' library requires inclusion of the following
+copyright notice, which applies to the `gd' library:
+
+ Portions copyright 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001,
+ 2002, 2003, 2004 by Cold Spring Harbor Laboratory. Funded under
+ Grant P41-RR02188 by the National Institutes of Health.
+
+ Portions copyright 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003,
+ 2004 by Boutell.Com, Inc.
+
+ Portions relating to GD2 format copyright 1999, 2000, 2001, 2002,
+ 2003, 2004 Philip Warner.
+
+ Portions relating to PNG copyright 1999, 2000, 2001, 2002, 2003,
+ 2004 Greg Roelofs.
+
+ Portions relating to gdttf.c copyright 1999, 2000, 2001, 2002,
+ 2003, 2004 John Ellson (ellson@graphviz.org).
+
+ Portions relating to gdft.c copyright 2001, 2002, 2003, 2004 John
+ Ellson (ellson@graphviz.org).
+
+ Portions relating to JPEG and to color quantization copyright
+ 2000, 2001, 2002, 2003, 2004, Doug Becker and copyright (C) 1994,
+ 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004 Thomas
+ G. Lane. This software is based in part on the work of the
+ Independent JPEG Group. See the file README-JPEG.TXT for more
+ information.
+
+ Portions relating to GIF compression copyright 1989 by Jef
+ Poskanzer and David Rowley, with modifications for thread safety
+ by Thomas Boutell.
+
+ Portions relating to GIF decompression copyright 1990, 1991, 1993
+ by David Koblas, with modifications for thread safety by Thomas
+ Boutell.
+
+ Portions relating to WBMP copyright 2000, 2001, 2002, 2003, 2004
+ Maurice Szmurlo and Johan Van den Brande.
+
+ Portions relating to GIF animations copyright 2004 Jaakko
+ Hyva"dtti (jaakko.hyvatti@iki.fi)
+
+ Permission has been granted to copy, distribute and modify gd in
+ any context without fee, including a commercial application,
+ provided that this notice is present in user-accessible supporting
+ documentation.
+
+ This does not affect your ownership of the derived work itself,
+ and the intent is to assure proper credit for the authors of gd,
+ not to interfere with your productive use of gd. If you have
+ questions, ask. "Derived works" includes all programs that utilize
+ the library. Credit must be given in user-accessible documentation.
+
+ This software is provided "AS IS." The copyright holders disclaim
+ all warranties, either express or implied, including but not
+ limited to implied warranties of merchantability and fitness for a
+ particular purpose, with respect to this code and accompanying
+ documentation.
+
+ Although their code does not appear in the current release, the
+ authors also wish to thank Hutchison Avenue Software Corporation
+ for their prior contributions.
+
+
+File: dvipng.info, Node: Copying, Next: Index, Prev: Credits, Up: Top
+
+9 Copying
+*********
+
+This program is free software: you can redistribute it and/or modify it
+under the terms of the GNU Lesser General Public License as published
+by the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+ This program is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
+General Public License for more details.
+
+ You should have received a copy of the GNU Lesser General Public
+License along with this program. If not, see
+<http://www.gnu.org/licenses/>.
+
+
+
+Copyright (C) 2002-2010 Jan-AAke Larsson
+
+
+File: dvipng.info, Node: Index, Prev: Copying, Up: Top
+
+Index
+*****
+
+
+* Menu:
+
+* -dSAFER: Option details. (line 168)
+* absolute page number, and -l: Option details. (line 142)
+* absolute page number, and -p: Option details. (line 195)
+* antialiasing levels, number of: Option details. (line 248)
+* background color (option): Option details. (line 42)
+* base resolution, setting: Option details. (line 35)
+* baseline reporting: Option details. (line 78)
+* color specifications: Color specifications.
+ (line 6)
+* command-line options: Command-line options.
+ (line 6)
+* compilation: Installation. (line 6)
+* compression: Option details. (line 314)
+* configuration, of dvipng: Installation. (line 6)
+* dark fonts: Option details. (line 121)
+* debugging <1>: Diagnosing problems. (line 6)
+* debugging: Option details. (line 56)
+* depth reporting: Option details. (line 78)
+* exit on erroneous images: Option details. (line 259)
+* first page printed: Option details. (line 195)
+* follow mode: Option details. (line 99)
+* font generation, avoiding: Option details. (line 160)
+* forcing palette output: Option details. (line 204)
+* foreground color (option): Option details. (line 93)
+* FreeType font rendering: Option details. (line 107)
+* fuzzy images: Option details. (line 121)
+* gamma: Option details. (line 121)
+* GhostScript and -dSAFER: Option details. (line 168)
+* GhostScript, turning off: Option details. (line 164)
+* GIF image format: Option details. (line 127)
+* height reporting: Option details. (line 134)
+* installation, of dvipng: Installation. (line 6)
+* invoking dvipng: Basic usage. (line 6)
+* last page printed: Option details. (line 142)
+* light fonts: Option details. (line 121)
+* magnification, overriding DVI: Option details. (line 304)
+* Metafont mode, specifying: Option details. (line 151)
+* mktexpk, avoiding: Option details. (line 160)
+* mode name, specifying: Option details. (line 151)
+* no erroneous images: Option details. (line 213)
+* offset pages: Option details. (line 189)
+* option, details of: Option details. (line 6)
+* options, dvipng: Command-line options.
+ (line 6)
+* options, reading from standard input: Option details. (line 11)
+* options, summary: Option summary. (line 6)
+* output resolution, setting: Option details. (line 62)
+* output, redirecting: Option details. (line 182)
+* page range: Option details. (line 226)
+* page, first printed: Option details. (line 195)
+* page, last printed: Option details. (line 142)
+* physical page number, and -l: Option details. (line 142)
+* physical page number, and -p: Option details. (line 195)
+* PNG image format: Option details. (line 222)
+* PostScript inclusion problems: Encapsulated PostScript.
+ (line 21)
+* PostScript, turning off raw PostScript specials: Option details.
+ (line 176)
+* problems: Diagnosing problems. (line 6)
+* quality: Option details. (line 248)
+* quiet operation: Option details. (line 244)
+* reverse pagination: Option details. (line 255)
+* silent operation: Option details. (line 244)
+* standard input, reading options from: Option details. (line 11)
+* standard output, output to: Option details. (line 182)
+* T1lib font rendering: Option details. (line 276)
+* transparent border fallback color: Option details. (line 25)
+* transparent border width: Option details. (line 25)
+* trouble: Diagnosing problems. (line 6)
+* truecolor output: Option details. (line 290)
+* warnings, suppressing: Option details. (line 244)
+* width reporting: Option details. (line 301)
+
+
+
+Tag Table:
+Node: Top297
+Node: Introduction1192
+Node: Installation3431
+Node: Prerequisites3778
+Node: Configure6268
+Node: Build/install8307
+Node: Installation outside the texmf tree8775
+Node: Advice for non-privileged users9482
+Node: Basic usage10490
+Node: Command-line options11662
+Node: Option summary12086
+Node: Option details14512
+Node: Graphics30430
+Node: Encapsulated PostScript31182
+Node: Bitmapped graphics32525
+Node: Raw PostScript33748
+Node: Color35987
+Node: Color specifications36375
+Node: Color specials37474
+Node: Diagnosing problems38886
+Node: Contact information39369
+Node: Debug options40110
+Node: Credits41145
+Node: Copying45146
+Node: Index45926
+
+End Tag Table