path: root/Build/source/texk/dvipng/doc/dvipng.texi

\input texinfo
@setfilename dvipng.info
@settitle A DVI-to-PNG translator
@ifset man
@c man begin SYNOPSIS
dvipng [options] filename

dvipng [options] [filename] -
@c man end
@end ifset

@set version 1.17
@set month-year January 2020

@c Put everything in one index (arbitrarily chosen to be the concept index).
@syncodeindex fn cp
@syncodeindex ky cp
@syncodeindex pg cp
@syncodeindex vr cp

@include macros.texi
@iftex
@tolerance 10000 @emergencystretch 3em
@end iftex

@dircategory TeX
@direntry
* DVI-to-PNG: (dvipng).              Translating TeX DVI files to Portable Network Graphics (PNG).
* dvipng: (dvipng).                  A DVI-to-PNG translator.
@end direntry

@finalout
@titlepage
@title dvipng
@subtitle A DVI-to-PNG Translator
@subtitle Version @value{version}


@author by Jan-@AA{}ke Larsson.
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 2002-2020 Jan-@AA{}ke Larsson

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).
@end ignore

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
section entitled ``Copying'' is included exactly as in the original, and
provided that the entire resulting derived work is distributed under the
terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the Free Software Foundation.
@end titlepage
@page

@c @summarycontents
@contents

@ifnottex
@node Top
@top dvipng

This manual documents dvipng, a program to translate a DVI (DeVice
Independent) file into PNG (Portable Network Graphics).

This file documents dvipng version @value{version}

Corrections or perhaps rewrites of sections are @emph{very welcome}.

Jan-@AA{}ke Larsson

@end ifnottex

@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
@end menu



@node Introduction
@chapter Introduction

@c man begin DESCRIPTION
@include readme.texi
@c man end

@node Installation
@chapter Installation

@cindex configuration, of dvipng
@cindex compilation
@cindex installation, of dvipng

@include install.texi

@node Basic usage
@chapter Basic usage of dvipng

@cindex invoking dvipng

To use dvipng at its simplest, simply type

@example
dvipng foo
@end example

@noindent
where @file{foo.dvi} is the output of @TeX{} that you want to convert to
PNG format. If there are four pages in @file{foo.dvi}, those pages will
be output as @file{foo1.png}, @file{foo2.png}, @file{foo3.png}, and
@file{foo4.png}, respectively.

If you have enabled the PostScript font support (via FreeType),
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. @xref{Unable to
generate fonts,,, kpathsea, Kpathsea}.)

Many options are available (see the next section).  For a brief summary
of available options, just type

@example
dvipng --help
@end example

@node Command-line options
@chapter Command-line options

@cindex command-line options
@cindex options, dvipng

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.
@end menu


@node Option summary
@section Option summary

@cindex options, summary
Here is a handy summary of the options; it is printed out when you run
dvipng with no arguments or with the standard @samp{--help} option.

@example
@include dvipng.help
@end example


@node Option details
@section Option details

@cindex option, details of
@c man begin OPTIONS

Many of the parameterless options listed here can be turned off by
suffixing the option with a zero (@samp{0}); for instance, to turn off
page reversal, use @samp{-r0}.  Such options are marked with a trailing
@samp{*}.

@table @samp
@item -
@cindex options, reading from standard input
@cindex standard input, reading options from
Read additional options from standard input after processing the command
line.

@item --help
Print a usage message and exit.

@item --version
Print the version number and exit.

@item -bd @var{num}
@item -bd @var{color_spec}
@item -bd '@var{num} @var{color_spec}'
@cindex transparent border width
@cindex transparent border fallback color
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 @var{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. @xref{Color}.

@item --bdpi @var{num}
@cindex base resolution, setting
This option only has an effect when using bitmapped (PK) fonts. The
option sets the base (Metafont) resolution, both horizontal and
vertical, to @var{num} dpi (dots per inch). This option is necessary
when manually selecting Metafont mode with the --mode option (see
below).

@item -bg @var{color_spec}
@cindex background color (option)
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.  @xref{Color}.

@item -d @var{num}
@cindex debugging
Set the debug flags, showing what dvipng (thinks it) is doing. This will
work unless dvipng has been compiled without the @code{DEBUG} option
(not recommended). Set the flags as you need them, use @samp{-d -1} as
the first option for maximum output. @xref{Debug options}.

@item -D @var{num}
@cindex output resolution, setting
Set the output resolution, both horizontal and vertical, to @var{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 @var{font_px} pixels (in
Mozilla) the correct formula is
@example
@var{dpi} = @var{font_px} * 72.27 / 10 [px * @TeX{}pt/in / @TeX{}pt]
@end example
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
@example
@var{font_px} = @var{font_pt} * 96 / 72 [pt * px/in / (pt/in)]
@end example
On some high-res screens, the value is instead 120 dpi. Good luck!

@item --depth*
@cindex baseline reporting
@cindex depth reporting
Report the depth of the image. This only works reliably when the
@LaTeX{} style @file{preview.sty} from @previewlatex{} is used with
the @samp{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)
@example
<IMG SRC="@var{filename.png}" STYLE="vertical-align: -@var{depth}px">
@end example
The depth is a negative offset in this case, so the minus sign is
necessary, and the unit is pixels (px).

@item --dvinum*
Set this option to make the output page number be the @TeX{} page
numbers rather than the physical page number. See the @samp{-o} switch.

@ignore
@item -e @var{num}
@cindex maxdrift
@cindex accuracy in positioning
@cindex positioning accuracy
Maximum drift in pixels of each character from its `true'
resolution-independent position on the page. The default value of this
parameter is resolution dependent (it is the number of entries in the
list [100, 200, 300, 400, 500, 600, 800, 1000, 1200, 1600, 2000, 2400,
2800, 3200, @dots{}] that are less than or equal to the resolution in
dots per inch). Allowing individual characters to `drift' from their
correctly rounded positions by a few pixels, while regaining the true
position at the beginning of each new word, improves the spacing of
letters in words.

@item -f*
@cindex filter, running as a
@cindex standard I/O
@cindex pipes, not readable
@vindex PRINTER@r{, avoided with @samp{-f}}
Run as a filter.  Read the DVI file from standard input and write the
PostScript to standard output.  The standard input must be seekable, so
it cannot be a pipe.  If your input must be a pipe, write a shell script
that copies the pipe output to a temporary file and then points dvipng at
this file.  This option also disables the automatic reading of the
@code{PRINTER} environment variable; use @samp{-P$PRINTER} after the
@samp{-f} to read it anyway.  It also turns off the automatic sending of
control-D if it was turned on with the @samp{-F} option or in the
configuration file; use @samp{-F} after the @samp{-f} to send it anyway.

@item -k*
@cindex cropmarks
Print crop marks.  This option increases the paper size (which should be
specified, either with a paper size special or with the @samp{-T}
option) by a half inch in each dimension.  It translates each page by a
quarter inch and draws cross-style crop marks.  It is mostly useful with
typesetters that can set the page size automatically.  This works by
downloading @file{crop.pro}.
@end ignore

@item -fg @var{color_spec}
@cindex foreground color (option)
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'.
@xref{Color}.

@item --follow*
@cindex follow mode
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 @samp{tail -f} but for DVI-to-PNG conversion.

@item --freetype*
@cindex FreeType font rendering
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 @samp{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. 
One reason to disable FreeType font rendering would be to generate 
identical output on different platforms, since FreeType uses the native 
renderer and therefore can give slightly different output on each platform.

@item --gamma @var{num}
@cindex gamma
@cindex dark fonts
@cindex light fonts
@cindex fuzzy images
Control the interpolation of colors in the greyscale anti-aliasing
color palette.  Default value is 1.0.  For 0 < @var{num} < 1, the
fonts will be lighter (more like the background), and for @var{num} >
1, the fonts will be darker (more like the foreground).

@item --gif*
@cindex GIF image format
The images are output in the GIF format, if GIF support is enabled.
This is the default for the @samp{dvigif} binary, which only will be
available when GIF support is enabled. GIF images are palette images
(see the @samp{--palette} option) and does not support true alpha
channels (see the @samp{--bg} option). See also the @samp{--png}
option.

@item --height*
@cindex baseline reporting
@cindex height reporting
Report the height of the image. This only works reliably when the
@LaTeX{} style @file{preview.sty} from @previewlatex{} is used with
the @samp{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
@samp{--height} and @samp{--depth}.

@item -l [=]@var{num}
@cindex last page printed
@cindex page, last printed
@cindex physical page number, and @samp{-l}
@cindex absolute page number, and @samp{-l}
The last page printed will be the first one numbered @var{num}. Default
is the last page in the document.  If @var{num} is prefixed by an equals
sign, then it (and the argument to the @samp{-p} option, if specified)
is treated as a physical (absolute) page number, rather than a value to
compare with the @TeX{} @samp{\count0} values stored in the DVI file.
Thus, using @samp{-l =9} will end with the ninth page of the document,
no matter what the pages are actually numbered.

@item --mode @var{mode}
@cindex mode name, specifying
@cindex Metafont mode, specifying
This option only has an effect when using bitmapped (PK) fonts. Use
@var{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 @samp{--bdpi} option. See the file
@url{ftp://ftp.tug.org/tex/modes.mf} for a list of resolutions and mode
names for most devices. @xref{Unable to generate fonts,,, kpathsea,
Kpathsea}.

@item -M*
@cindex font generation, avoiding
@pindex mktexpk@r{, avoiding}
@c this description repeated in kpathsea.texi
This option only has an effect when using bitmapped (PK) fonts. It turns
off automatic PK font generation (@file{mktexpk}).
@ignore
@flindex missfont.log
If @code{mktexpk}, the invocation is appended to a file
@file{missfont.log} (by default) in the current directory. You can then
execute the log file to create the missing files after fixing the
problem.
@vindex TEXMFOUTPUT
@vindex MISSFONT_LOG
If the current directory is not writable and the environment variable or
configuration file value @samp{TEXMFOUTPUT} is set, its value is used.
Otherwise, nothing is written.  The name @samp{missfont.log} is
overridden by the @samp{MISSFONT_LOG} environment variable or
configuration file value.
@end ignore

@item --nogs*
@cindex GhostScript, turning off
This switch prohibits the internal call to GhostScript for displaying
PostScript specials. @samp{--nogs0} turns the call back on.

@item --nogssafer*
@cindex GhostScript and -dSAFER
@cindex -dSAFER
Normally, if GhostScript is used to render PostScript specials, the
GhostScript interpreter is run with the option @samp{-dSAFER}. The
@samp{--nogssafer} option runs GhostScript without @samp{-dSAFER}. The
@samp{-dSAFER} option in Ghostscript disables PostScript operators such
as deletefile, to prevent possibly malicious PostScript programs from
having any effect.

@item --norawps*
@cindex PostScript, turning off raw PostScript specials
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. @samp{--norawps0}
turns the call back on.

@item -o @var{name}
@cindex output, redirecting
@cindex standard output, output to
Send output to the file @var{name}. A single occurrence of @samp{%d} or
@samp{%01d}, @dots{}, @samp{%09d} will be exchanged for the physical
page number (this can be changed, see the @samp{--dvinum} switch). The
default output filename is @samp{@var{file}%d.png} where the input DVI
file was @samp{@var{file}.dvi}.

@item -O @var{x-offset},@var{y-offset}
@cindex offset pages
Move the origin by @var{x-offset},@var{y-offset}, a comma-separated
pair of dimensions such as @samp{.1in,-.3cm}.
@c (@pxref{papersize special}).
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.

@item -p [=]@var{num}
@cindex first page printed
@cindex page, first printed
@cindex physical page number, and @samp{-p}
@cindex absolute page number, and @samp{-p}
The first page printed will be the first one numbered @var{num}. Default
is the first page in the document.  If @var{num} is prefixed by an
equals sign, then it (and the argument to the @samp{-l} option, if
specified) is treated as a physical (absolute) page number, rather than
a value to compare with the @TeX{} @samp{\count0} values stored in the
DVI file.  Thus, using @samp{-p =3} will start with the third page of
the document, no matter what the pages are actually numbered.

@item --palette*
@cindex forcing palette output
When an external image is included, @samp{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 @samp{dvipng} revert to opaque
clipped image inclusion. This will also override the @samp{--truecolor}
switch if present.

@item --picky*
@cindex no erroneous images
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.

@item --png*
@cindex PNG image format
The images are output in the PNG format. This is the default for the
@samp{dvipng} binary. See also the @samp{--gif} option.

@item -pp @var{firstpage}-@var{lastpage}
@cindex page range
Print pages @var{firstpage} through @var{lastpage}; but not quite
equivalent to @samp{-p @var{firstpage} -l @var{lastpage}}. For example,
when rendering a book, there may be several instances of a page in the
DVI file (one in @code{\frontmatter}, one in @code{\mainmatter}, and one
in @code{\backmatter}). In case of several pages matching, @samp{-pp
@var{firstpage}-@var{lastpage}} will render @emph{all} pages that
matches the specified range, while @samp{-p @var{firstpage} -l
@var{lastpage}} will render the pages from the @emph{first} occurrence
of @var{firstpage} to the @emph{first} occurrence of @var{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 @samp{-pp} between the pages from @samp{-p} to @samp{-l}. Also
multiple @samp{-pp} options accumulate, unlike @samp{-p} and @samp{-l}.
The @samp{-} separator can also be @samp{:}. Note that @samp{-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 @samp{-pp -1--1},
or more readable, @samp{-pp -1:-1}.

@item -q*
@cindex quiet operation
@cindex silent operation
@cindex warnings, suppressing
Run quietly.  Don't chatter about pages converted, etc.@: to standard
output; report no warnings (only errors) to standard error.

@item -Q @var{num}
@cindex antialiasing levels@r{, number of}
@cindex quality
Set the quality to @var{num}. That is, choose the number of antialiasing
levels for bitmapped fonts (PK), to be
@var{num}*@var{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.

@item -r*
@cindex reverse pagination
Toggle output of pages in reverse/forward order. By default, the first
page in the DVI is output first.

@ignore
@item -R
@cindex security
@cindex shell command execution, disabling
@cindex absolute filenames, disabling
@cindex pipes, disabling output to
Run securely.  This disables shell command execution in @code{\special}
(via @samp{`}, @pxref{Dynamic creation of graphics}) and config files
(via the @samp{E} option, @pxref{Configuration file commands}), pipes as
output files, and opening of any absolute filenames.

@item -t @var{papertype}
@cindex paper type
@cindex media
@cindex letter papertype
@cindex legal papertype
@cindex ledger papertype
@cindex a4 papertype
@cindex a3 papertype
@cindex landscape papertype
Set the paper type to @var{papertype}.
@c usually defined in one of the
@c configuration files, along with the appropriate PostScript code to
@c select it (@pxref{Config file paper sizes}).
You can also specify a @var{papertype} of @samp{landscape}, which
rotates a document by 90 degrees. To rotate a document whose paper type
is not the default, you can use the @samp{-t} option twice, once for the
paper type, and once for @samp{landscape}.
@end ignore

@item --strict*
@cindex exit on erroneous images
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 @samp{--picky} option
above for a list of when warnings occur.

@item -T @var{image_size}
Set the image size to @var{image_size} which can be either of
@samp{bbox}, @samp{tight}, or a comma-separated pair of dimensions
@var{hsize},@var{vsize} such as @samp{.1in,.3cm}. The default is
@samp{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 @samp{tight} will make dvipng
only include all ink put on the page, producing neat images.
@c (@pxref{papersize special}).
@c This option overrides any papersize special in the DVI file.

@item --truecolor*
@cindex truecolor output
This will make @samp{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 @samp{graphics} or
@samp{graphicx} package). This switch is overridden by the
@samp{--palette} switch.

@item -v*
Enable verbose operation. This will currently indicate what fonts is
used, in addition to the usual output.

@item --width*
@cindex width reporting
Report the width of the image. See also @samp{--height} and
@samp{--depth}.

@item -x @var{num}
@cindex magnification, overriding DVI
This option is deprecated; it should not be used. It is much better to
select the output resolution directly with the @samp{-D} option. This
option sets the magnification ratio to @math{@var{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.  @var{num} may be a real number, not
an integer, for increased precision.

@item -z @var{num}
@cindex compression
Set the PNG compression level to @var{num}. This option is enabled if
your @samp{libgd} is new enough. The default compression level is 1,
which selects maximum speed at the price of slightly larger PNGs. For an
older @samp{libgd}, the hard-soldered value 5 is used. The include file
@samp{png.h} says
@ifclear man
@quotation
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.
@end quotation
@end ifclear
@ifset man
``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.''
@end ifset
@end table
@c man end

@node Graphics
@chapter Graphics

@samp{dvipng} attempts to handle graphics as included by the
@samp{graphicx} and @samp{graphics} packages, without the need of
specifying a driver to these packages. This means that it recognizes
the encapsulated postscript inclusion meant for @samp{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
@end menu

@node Encapsulated PostScript
@section 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 @samp{pngalpha} output device to be present
in your copy of GhostScript. If that device is not present, or you use
the @samp{--palette} switch or request GIF output, the fallback is to
use the @samp{png16m} device to produce a cropped opaque image for
inclusion. Other relevant switches are @samp{--noghostscript} and
@samp{--nogssafer}. @xref{Option details}.

@cindex PostScript inclusion problems
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 @samp{\includegraphics} call, as
in this example (using @samp{graphicx}):

@example
\includegraphics[bb=10 20 100 200]@{imagename.eps@}
@end example


@node Bitmapped graphics
@section Bitmapped graphics

dvipng can include PNG, JPEG and GIF graphics. When including such
images via @samp{\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 @samp{0 0 w h} in pixels,
e.g., if the file @samp{imagename.png} is 300x400 pixels, the
inclusion would read

@example
\includegraphics[bb=0 0 300 400]@{imagename.png@}
@end example

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:

@example
\includegraphics[bb=0 0 300 400,witdh=1.5in]@{imagename.png@}
@end example

@node Raw PostScript
@section 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 @samp{pngalpha} device in GhostScript (automatically
selecting @samp{truecolor} mode in dvipng).

Included PostScript headers are respected, and if the header
@samp{tex.pro} is included, dvipng also throws in @samp{color.pro} and
@samp{special.pro}. The package @samp{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
@samp{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 @samp{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 @samp{--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
@samp{--picky} to disable page rendering of pages with warnings, and use
the slower fallback for these pages.

@node Color
@chapter Color

To support color, dvipng recognizes a certain set of specials as
generated by the @samp{color} and @samp{xcolor} style files. These
specials start with the keyword @samp{color} or the keyword
@samp{background}, followed by a color specification.

@menu
* Color specifications::
* Color specials::
@end menu


@node Color specifications
@section Color specifications

@cindex 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 @samp{rgb},
@samp{hsb}, @samp{cmy}, @samp{cmyk}, or @samp{gray}) followed by the
appropriate number of parameters. Thus, the color specification
@samp{rgb 0.3 0.4 0.5} would correspond to the color that is @samp{0.3
0.4 0.5} in its red, blue and green values. The color model used
internally in dvipng is @samp{RGB} (discretized to 256 levels), for
details on the formulas used in conversion, see the @samp{xcolor}
documentation.

By-name color specifications are single (case-dependent) words and are
compared with color names defined in @samp{dvipsnam.def} (from the
@samp{graphics} bundle), @samp{svgnam.def} and @samp{xcolor.sty} (from
the @samp{xcolor} bundle). See the @samp{xcolor} documentation for a
list of names and the corresponding colors.

On the command-line, the name @samp{Transparent} can also be used as
an argument to @samp{--bg} to choose transparent background.
@xref{Option details}.

@node Color specials
@section Color specials

We will describe @samp{background} first, since it is the simplest. The
@samp{background} keyword must be followed by a color specification.
That color specification is used as a fill color for the background. The
last @samp{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 @samp{color} special itself has three forms. The first is just
@samp{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 @samp{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 @samp{color} special is just @samp{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.

@node Diagnosing problems
@chapter Diagnosing problems

@cindex problems
@cindex trouble
@cindex debugging

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.
@end menu

@node Contact information
@section Contact information

Bug reports should be sent to
@email{dvipng@@nongnu.org}.

Questions, suggestions for new features, pleas for help, and/or praise
should go to @email{dvipng@@nongnu.org}. For more information on this
mailing list, send a message with just the word `help' as subject or
body to @email{dvipng-request@@nongnu.org} or look at
@url{http://lists.nongnu.org/mailman/listinfo/dvipng}.

Offers to support further development will be appreciated. For developer
access, ask on @email{dvipng@@nongnu.org}.

For details on the @TeX{} path-searching library, and @code{mktexpk}
problems, @pxref{Common problems,,, kpathsea, Kpathsea}.


@node Debug options
@section Debug options

The @samp{-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 @code{-1}.

Some of these debugging options are actually provided by Kpathsea
(@pxref{Debugging, , , kpathsea, Kpathsea}).

The classes are:
@table @asis
@item 1
Normal dvi op-codes
@item 2
Virtual fonts
@item 4
PK fonts
@item 8
TFM files
@item 16
Glyph rendering
@item 32
FreeType calls
@item 64
Encoding loads
@item 128
Color specials
@item 256
GhostScript specials
@item 512
Kpathsea @code{stat} calls
@item 1024
Kpathsea hash table lookups
@item 2048
Kpathsea path element expansion
@item 4096
Kpathsea path searches
@ignore
@item 8192
@item 16384
@end ignore

@end table

@node Credits
@chapter Credits

A number of persons have contributed, if I forget to mention someone,
I apologize. First and foremost we have David Kastrup whose
@previewlatex{} 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 (te@TeX{}), Christian Schenk (MIK@TeX{}), 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 Ridderstr@"om, Ezra Peisach,
William H Wheeler, Thomas Klausner, Harald Koenig, Adrian Bunk, Kevin
Smith, Jason Riedy, Wolfram Krause, Reinhard Kotucha, Takeshi Abe, 
Waldeck Schutzer, Ahzo, and Andy Nguyen.

@ifset man
@c man begin NOTES
The full manual is accessible in info format, on most systems by typing
@example
info dvipng
@end example
@c man end
@c man begin COPYRIGHT
This program is released under the GNU Lesser General Public License
version 3, see the COPYING file in the dvipng distribution or
@url{http://www.gnu.org/licenses/gpl.html}.

Copyright @copyright{} 2002-2015, 2019 Jan-@AA{}ke Larsson
@c man end
@end ifset

@node Copying
@chapter 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/>.

@sp 2
@noindent
Copyright @copyright{} 2002-2015, 2019 Jan-@AA{}ke Larsson

@node Index
@unnumbered Index

@printindex cp
@bye