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, 0 insertions, 984 deletions
diff --git a/Build/source/texk/dvipng/dvipng-src/dvipng.texi b/Build/source/texk/dvipng/dvipng-src/dvipng.texi deleted file mode 100644 index 2b8e157bdc2..00000000000 --- a/Build/source/texk/dvipng/dvipng-src/dvipng.texi +++ /dev/null @@ -1,984 +0,0 @@ -\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 |