summaryrefslogtreecommitdiff
path: root/dviware/dvipng/dvipng.texi
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /dviware/dvipng/dvipng.texi
Initial commit
Diffstat (limited to 'dviware/dvipng/dvipng.texi')
-rw-r--r--dviware/dvipng/dvipng.texi981
1 files changed, 981 insertions, 0 deletions
diff --git a/dviware/dvipng/dvipng.texi b/dviware/dvipng/dvipng.texi
new file mode 100644
index 0000000000..16a40ec3a0
--- /dev/null
+++ b/dviware/dvipng/dvipng.texi
@@ -0,0 +1,981 @@
+\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.15
+@set month-year February 2015
+
+@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-2015 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.
+
+@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, and
+Waldeck Schutzer.
+
+@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 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 Jan-@AA{}ke Larsson
+
+@node Index
+@unnumbered Index
+
+@printindex cp
+@bye