diff options
Diffstat (limited to 'Build/source/texk/dvipng/dvipng-src/dvipng.texi')
-rw-r--r-- | Build/source/texk/dvipng/dvipng-src/dvipng.texi | 984 |
1 files changed, 984 insertions, 0 deletions
diff --git a/Build/source/texk/dvipng/dvipng-src/dvipng.texi b/Build/source/texk/dvipng/dvipng-src/dvipng.texi new file mode 100644 index 00000000000..2b8e157bdc2 --- /dev/null +++ b/Build/source/texk/dvipng/dvipng-src/dvipng.texi @@ -0,0 +1,984 @@ +\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 |