summaryrefslogtreecommitdiff
path: root/Build/source/texk/dvipng/dvipng.texi
diff options
context:
space:
mode:
Diffstat (limited to 'Build/source/texk/dvipng/dvipng.texi')
-rw-r--r--Build/source/texk/dvipng/dvipng.texi819
1 files changed, 787 insertions, 32 deletions
diff --git a/Build/source/texk/dvipng/dvipng.texi b/Build/source/texk/dvipng/dvipng.texi
index 1fa1e81ceab..352938caf8c 100644
--- a/Build/source/texk/dvipng/dvipng.texi
+++ b/Build/source/texk/dvipng/dvipng.texi
@@ -9,8 +9,8 @@ dvipng [options] [filename] -
@c man end
@end ifset
-@set version 1.10
-@set month-year May 2008
+@set version 1.9
+@set month-year November 2006
@c Put everything in one index (arbitrarily chosen to be the concept index).
@syncodeindex fn cp
@@ -39,7 +39,7 @@ dvipng [options] [filename] -
@author by Jan-@AA{}ke Larsson.
@page
@vskip 0pt plus 1filll
-Copyright @copyright{} 2002-2008 Jan-@AA{}ke Larsson
+Copyright @copyright{} 2002-2006 Jan-@AA{}ke Larsson
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
@@ -92,7 +92,7 @@ Jan-@AA{}ke Larsson
* Color:: Using color with dvipng
* Diagnosing problems:: Problems?
* Credits:: People who have contributed
-* Copying:: GNU Lesser General Public License
+* Copying:: GNU General Public License
* Index:: General index
@end menu
@@ -263,11 +263,11 @@ On some high-res screens, the value is instead 120 dpi. Good luck!
@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)
+@LaTeX{} style @file{preview.sty} from @previewlatex{} is used. 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
@@ -370,11 +370,10 @@ option.
@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}.
+@LaTeX{} style @file{preview.sty} from @previewlatex{} is used. 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
@@ -647,6 +646,761 @@ correspond directly to the zlib compression levels.''
@end table
@c man end
+@ignore
+@c @node Environment variables
+@chapter Environment variables
+
+@cindex environment variables
+
+dvipng looks for many environment variables, to define search paths and
+other things. The path variables are read as needed, after all
+configuration files are read, so they override values in the
+configuration files. (Except for @code{TEXCONFIG}, which defines where
+the configuration files themselves are found.)
+
+@xref{Path specifications,,, kpathsea, Kpathsea}, for details of
+interpretation of path and other environment variables common to all
+Kpathsea-using programs. Only the environment variables specific to
+dvipng are mentioned here.
+
+@vtable @code
+@item DVIPSMAKEPK
+@pindex mktexpk@r{, changing name}
+Overrides @samp{mktexpk} as the name of the program to invoke to
+create missing PK fonts. You can change the arguments passed to the
+@code{mktexpk} program with the @code{MAKETEXPK} environment
+variable; @pxref{MakeTeX script arguments,,, kpathsea, Kpathsea}.
+
+@item DVIPSRC
+Specifies the name of the startup file (@pxref{Configuration file
+searching}) which is read after @file{config.ps} but before any
+printer-specific configuration files.
+
+@item TEXPICTS
+Path to search for included graphics files. Overrides the @samp{S}
+config file option (@pxref{Configuration file commands}). If not set,
+@code{TEXINPUTS} is looked for. @xref{Supported file formats,,,
+kpathsea, Kpathsea}.
+
+@end vtable
+
+@c @node Paper size and landscape
+@chapter Paper size and landscape orientation
+
+@cindex paper size, general
+
+Most @TeX{} documents at a particular site are designed to use the
+standard paper size (letter size in the United States, A4 in Europe).
+The dvipng program can be customized either sitewide or for a particular
+printer.
+
+@cindex landscape orientation, defined
+But many documents are designed for other paper sizes. For instance,
+you may want to design a document that has the long edge of the paper
+horizontal. This can be useful when typesetting booklets, brochures,
+complex tables, or many other documents. This type of paper orientation
+is called @dfn{landscape} orientation (the default orientation is
+@dfn{portrait}). Alternatively, a document might be designed for ledger
+or A3 paper.
+
+Since the intended paper size is a document design decision, not a
+printing decision, such information should be given in the @TeX{} file
+and not on the dvipng command line. For this reason, dvipng supports a
+@samp{papersize} special. It is hoped that this special will become
+standard over time for @TeX{} previewers, printer drivers, and other DVI
+drivers.
+
+@menu
+* papersize special:: Specifying the paper size in TeX.
+* Config file paper sizes:: Specifying printer- and site-specific sizes.
+@end menu
+
+
+@c @node papersize special
+@section @samp{papersize} special
+
+@findex papersize @r{special}
+
+The format of the @samp{papersize} special is
+
+@example
+\special@{papersize=@var{width},@var{height}@}
+@end example
+
+@noindent
+@var{width} is the horizontal size of the page, and @var{height} is the
+vertical size. The dimensions supported are the same as for @TeX{};
+namely, in (inches), cm (centimeters), mm (millimeters), pt (points), sp
+(scaled points), bp (big points, the same as the default PostScript
+unit), pc (picas), dd (didot points), and cc (ciceros).
+
+@findex landscape@r{, as @code{\special}}
+For a US letter size landscape document, the @code{papersize} would be:
+@example
+\special@{papersize=11in,8.5in@}
+@end example
+
+@noindent
+An alternate specification of @code{landscape}:
+@example
+\special@{landscape@}
+@end example
+
+@noindent
+This is supported for backward compatibility, but it is hoped that
+eventually the @code{papersize} comment will dominate.
+
+Of course, such a @code{\special} only informs dvipng of the desired
+paper size; you must also adjust @code{\hsize} and @code{\vsize} in your
+@TeX{} document typeset to those dimensions.
+
+The @code{papersize} special must occur somewhere on the first page of
+the document.
+
+
+@c @node Config file paper sizes
+@section Configuration file paper size command
+
+@cindex paper size configuration file command
+@cindex configuration file paper size command
+
+The @samp{@@} command in a configuration file sets the paper size
+defaults and options. The first @samp{@@} command defines the default
+paper size. It has three possible parameters:
+
+@example
+@@ @r{[}@var{name} @r{[}@var{hsize} @var{vsize}@r{]]}
+@end example
+
+If @samp{@@} is specified on a line by itself, with no parameters, it
+instructs dvipng to discard all previous paper size information (possibly
+from another configuration file).
+
+If three parameters are given, with the first parameter being a name and
+the second and third being a dimension (as in @samp{8.5in} or
+@samp{3.2cc}, just like in the @samp{papersize} special), then the
+option is interpreted as starting a new paper size description, where
+@var{name} is the name and @var{hsize} and @var{vsize} define the
+horizontal and vertical size of the sheet of paper, respectively. For
+example:
+
+@example
+@@ letterSize 8.5in 11in
+@end example
+
+If both @var{hsize} and @var{vsize} are zero (you must still specify
+units!) then any page size will match. If the @samp{@@} character is
+immediately followed by a @samp{+} sign, then the remainder of the line
+(after skipping any leading blanks) is treated as PostScript code to
+send to the printer, presumably to select that particular paper size:
+
+@example
+@@ letter 8.5in 11in
+@@+ %%BeginPaperSize: Letter
+@@+ letter
+@@+ %%EndPaperSize
+@end example
+
+After all that, if the first character of the line is an exclamation
+point, then the line is put in the initial comments section of the final
+output file; else, it is put in the setup section of the output file.
+For example:
+
+@example
+@@ legal 8.5in 14in
+@@+ ! %%DocumentPaperSizes: Legal
+@@+ %%BeginPaperSize: Legal
+@@+ legal
+@@+ %%EndPaperSize
+@end example
+
+When dvipng has a paper format name given on the command line, it looks
+for a match by the @var{name}; when it has a @samp{papersize} special,
+it looks for a match by dimensions. The first match found (in the order
+the paper size information is found in the configuration file) is used.
+If nothing matches, a warning is printed and the first paper size is
+used. The dimensions must match within a quarter of an inch. Landscape
+mode for all paper sizes is automatically supported.
+
+If your printer has a command to set a special paper size, then give
+dimensions of @samp{0in 0in}; the PostScript code that sets the paper
+size can refer to the dimensions the user requested as @samp{hsize} and
+@samp{vsize}; these will be macros defined in the PostScript that return
+the requested size in default PostScript units. Virtually all of the
+PostScript commands you use here are device-dependent and degrade the
+portability of the file; that is why the default first paper size entry
+should not send any PostScript commands down (although a structured
+comment or two would be okay). Also, some printers want
+@samp{BeginPaperSize} comments and paper size setting commands; others
+(such as the NeXT) want @samp{PaperSize} comments and they will handle
+setting the paper size. There is no solution I could find that works
+for both (except maybe specifying both).
+
+@flindex mkdvipngpapers
+The Perl 5 script @file{contrib/mkdvipngpapers} in the distribution
+directory may help in determining appropriate paper size definitions.
+
+@cindex a4 paper size, as default
+If your printers are configured to use A4 paper by default, the
+configuration file (probably the global @file{config.ps} in this case)
+should include this as the first @samp{@@} command:
+
+@example
+@@ A4size 210mm 297mm
+@@+ %%PaperSize: A4
+@end example
+
+@noindent
+so that @code{A4size} is used as the default, and not @code{A4} itself;
+thus, no PostScript @code{a4} command is added to the output file,
+unless the user explicitly says to use paper size @samp{a4}. That is,
+by default, no paper size PostScript command should be put in the
+output, but dvipng will still know that the paper size is A4 because
+@samp{A4size} is the first (and therefore default) size in the
+configuration file.
+
+Executing the @samp{letter} or @samp{a4} or other PostScript operators
+cause the document to be nonconforming and can cause it not to print on
+certain printers, so the default paper size should not execute such an
+operator if at all possible.
+
+
+
+@c @node Interaction with PostScript
+@chapter Interaction with PostScript
+
+@cindex interaction with PostScript
+@cindex PostScript interaction
+
+dvipng supports inclusion of PostScript figure files (e.g., Encapsulated
+PostScript), downloading other header files (e.g., fonts), including
+literal PostScript code, and hypertext.
+
+@menu
+* PostScript figures:: Including an Encapsulated PostScript figure.
+* Header files:: Downloading extra definitions.
+* Diagnosing problems::
+@end menu
+
+
+@c @node PostScript figures
+@chapter PostScript figures
+
+Scaling and including PostScript graphics is a breeze---if the PostScript
+file is correctly formed. Even if it is not, however, the file can usually
+be accommodated with just a little more work.
+
+@menu
+* Bounding box:: The %%BoundingBox EPS comment.
+* EPSF macros:: Including the file in TeX.
+* psfile special:: The basic special.
+* Dynamic creation of graphics:: Handling compressed or generated figures.
+* Fonts in figures:: The %*Font comment.
+@end menu
+
+
+@c @node Bounding box
+@section The bounding box comment
+
+@cindex bounding box, comment for
+
+The most important feature of a good PostScript file from the standpoint
+of including it in another document is an accurate bounding box comment.
+Every well-formed PostScript file has a comment describing where on the
+page the graphic is located, and how big that graphic is.
+
+@cindex big points
+@cindex PostScript units
+@cindex bounding box, defined
+This information is given as the lower left and upper right corners of
+the box just enclosing the graphic, and is thus referred to as the
+@dfn{bounding box}. These coordinates are given in the default
+PostScript units (there are precisely 72 PostScript units to the inch,
+like @TeX{} big points) with respect to the lower left corner of the
+sheet of paper.
+
+@findex %%BoundingBox
+To see if a PostScript file has a bounding box comment, just look at the
+first few lines of the file. PostScript files are standard ASCII, so
+you can use any text editor to do this. If within the first few dozen
+lines there is a line like
+
+@example
+%%BoundingBox: 25 50 400 300
+@end example
+
+@noindent
+(with any reasonable numbers), chances are very good that the file is
+Encapsulated PostScript and will work easily with dvipng. If the file
+contains instead a line like
+
+@findex atend@r{, bounding box specification}
+@findex (atend)@r{, bounding box specification}
+@example
+%%BoundingBox: (atend)
+@end example
+
+@noindent
+the file is still probably Encapsulated PostScript, but the bounding box
+is given at the end of the file. dvipng needs it at the beginning. You
+can move it with that same text editor, or a simple script. (The
+bounding box is given in this way when the program that generated the
+PostScript couldn't know the size in advance, or was too lazy to compute
+it.)
+
+@pindex bbfig
+@cindex bounding box, determining
+If the document lacks a @samp{%%BoundingBox:} altogether, you can
+determine one in a couple of ways. One is to use the @samp{bbfig}
+program distributed with dvipng in the @file{contrib} directory. This can
+usually find the correct bounding box automatically; it works best with
+Ghostscript.
+
+@vindex 612 792 @r{bounding box size}
+If the comment looks like this:
+@example
+%%BoundingBox: 0 0 612 792
+@end example
+
+@noindent
+the graphic claims to take up an entire sheet of paper. This is
+usually a symptom of a bug in the program that generated it.
+
+The other is to do it yourself: print the file. Now, take a ruler, and
+make the following measurements (in PostScript units, so measure in
+inches and multiply by 72): From the left edge of the paper to the
+leftmost mark on the paper is @var{llx}, the first number. From the
+bottom edge of the paper to the bottommost mark on the paper is
+@var{lly}, the second number. From the left edge of the paper to the
+rightmost mark on the paper is @var{urx}, the third number. The fourth
+and final number, @var{ury}, is the distance from the bottom of the page
+to the uppermost mark on the paper.
+
+Once you have the numbers, add a comment of the following form as the
+second line of the document. (The first line should already be a line
+starting with the two characters @samp{%!}; if it is not, the file
+probably isn't PostScript.)
+
+@example
+%%BoundingBox: @var{llx} @var{lly} @var{urx} @var{ury}
+@end example
+
+@noindent
+Or, if you don't want to modify the file, you can simply write these
+numbers down in a convenient place and give them in your @TeX{} document
+when you import the graphic, as described in the next section.
+
+If the document does not have such a bounding box, or if the bounding
+box is given at the end of the document, or the bounding box is wrong,
+please complain to the authors of the software package that generated
+the file.
+
+
+@c @node EPSF macros
+@section Using the EPSF macros
+
+@cindex EPSF macros
+@cindex macros for epsf inclusion
+
+Once the figure file has a bounding box comment (see the previous
+section,) you are ready it the graphic into a @TeX{} document. Many
+packages for using EPS files exist. One distributed with dvipng is the
+files @file{epsf.tex} (for plain @TeX{}) and @file{epsf.sty} (for
+La@TeX{}). For plain @TeX{}, add a line like this near the top of your
+input file:
+
+@flindex epsf.tex
+@example
+\input epsf
+@end example
+
+@noindent
+If you are using La@TeX{} 2e, use the @samp{graphics} or @samp{graphicx}
+package.
+@flindex epsf.sty
+If you are using La@TeX{} 2.09, add the @samp{epsf} style option, as in:
+
+@example
+\documentstyle[12pt,epsf]@{article@}
+@end example
+
+@noindent
+In any case, the above only needs to be done once, no matter how many
+figures you plan to include.
+
+Now, at the point you want to include a file, enter a line such as:
+
+@example
+\epsffile@{foo.eps@}
+@end example
+
+@findex \leavevmode
+@cindex bounding box, supplying to @TeX{}
+If you are using La@TeX{}, you may need to add @code{\leavevmode}
+immediately before the @code{\epsffile} command to get certain
+environments to work correctly. If your file does not have a bounding
+box comment, you can supply the numbers as determined in the previous
+section, in the same order they would have been in a normal bounding box
+comment:
+
+@example
+\epsffile[100 100 500 500]@{foo.ps@}
+@end example
+
+@noindent
+Now, save your changes and run @TeX{} and dvipng; the output should have
+your graphic positioned at precisely the point you indicated, occupying
+the proper amount of space.
+
+@findex \epsffile @r{macro}
+@cindex figures, natural size
+The @code{\epsffile} macro typesets the figure as a @TeX{} @code{\vbox}
+at the point of the page that the command is executed. By default, the
+graphic will have its `natural' width (namely, the width of its bounding
+box). The @TeX{} box will have depth zero and its natural height. By
+default, the graphic will be scaled by any DVI magnification in effect,
+just as is everything else in your document. See the next section for
+more information on scaling.
+
+@vindex \epsfverbosetrue
+@cindex verbose EPSF processing
+If you want @TeX{} to report the size of the figure as a message on your
+terminal when it processes each figure, give the command:
+
+@example
+\epsfverbosetrue
+@end example
+
+@menu
+* EPSF scaling::
+* EPSF clipping::
+@end menu
+
+
+@c @node EPSF scaling
+@subsection EPSF scaling
+
+@cindex scaling of figures
+@cindex figures, scaling
+
+Usually, you will want to scale an EPSF figure to some size appropriate
+for your document, since its natural size is determined by the creator
+of the EPS file.
+
+The best way to do this is to assign the desired size to the @TeX{}
+@code{\epsfxsize} or @code{\epsfysize} variables, whichever is more
+convenient for you. That is, put
+
+@vindex \epsfxsize
+@example
+\epsfxsize=@var{dimen}
+@end example
+
+@noindent
+right before the call to @code{\epsffile}. Then the width of the @TeX{}
+box will be @var{dimen} and its height will be scaled proportionately.
+Similarly, you can set the vertical size with
+
+@vindex \epsfysize
+@example
+\epsfysize=@var{dimen}
+@end example
+
+@noindent
+in which case the height will be set and the width scaled
+proportionally.
+
+If you set both, both will be honored, but the aspect ratio of the
+included graphic may necessarily be distorted, i.e., its contents
+stretched in one direction or the other.
+
+@findex \epsfsize
+You can resize graphics in a more general way by redefining the
+@code{\epsfsize} macro. @code{\epsffile} calls this with two
+parameters: the natural horizontal and vertical sizes of the PostScript
+graphic. @code{\epsfsize} must expand to the desired horizontal size,
+that is, the width of the @code{\vbox}. Schematically:
+
+@example
+\def\epsfsize#1#2@{@var{body}@}
+@end example
+
+Some useful definitions of @var{body}:
+
+@table @samp
+@item \epsfxsize
+This definition (the default) enables the default features listed above,
+by setting @code{\epsfxsize} to the same value it had before the macro
+was called.
+
+@item #1
+Force the natural size by returning the first parameter (the original
+width).
+
+@item 0pt
+A special case, equivalent to @samp{#1}.
+
+@item 0.5#1
+Scale to half the natural size.
+
+@item \hsize
+Scale to the current @code{\hsize}. (In La@TeX{}, use @code{\textwidth}
+instead of @code{\hsize}.)
+
+@item \ifnum#1>\hsize\hsize\else#1\fi
+If the natural width is greater than the current @code{\hsize}, scale to
+@code{\hsize}, otherwise use the natural width.
+
+@end table
+
+@cindex DVI magnification
+@cindex magnification, DVI
+@vindex \magnification
+For compatibility with other PostScript drivers, it is possible to turn
+off the default scaling of included figures by the DVI magnification
+with the following @TeX{} command:
+
+@vindex /magscale
+@example
+\special@{! /magscale false def@}
+@end example
+
+@noindent
+Use of this command is not recommended because it will make the
+@code{\epsffile} graphics the ``wrong'' size if global magnification is
+being used, and it will cause any PostScript graphics to appear
+improperly scaled and out of position if a DVI to DVI program is used to
+scale or otherwise modify the document.
+
+@findex bop-hook
+DVI magnification is not applied to any output from code you write in
+@samp{bop-hook} or its ilk (@pxref{PostScript hooks}),
+
+
+@c @node EPSF clipping
+@subsection EPSF clipping
+
+@cindex clipping of EPSF
+@cindex bounding box, inaccurate
+@cindex text in figures, chopped off
+@cindex lines in figures, wrong width
+
+By default, clipping is disabled for included EPSF images. This is
+because clipping to the bounding box dimensions often cuts off a
+small portion of the figure, due to slightly inaccurate bounding
+box arguments. The problem might be subtle; lines around the boundary
+of the image might be half their intended width, or the tops or
+bottoms of some text annotations might be sliced off. If you want to
+turn clipping on, just use the command
+
+@example
+\epsfclipon
+@end example
+
+@noindent
+and to turn clipping back off, use
+
+@example
+\epsfclipoff
+@end example
+
+
+@c @node psfile special
+@section @samp{psfile} special
+
+@findex psfile @r{special}
+
+The basic special for file inclusion is as follows:
+
+@example
+\special@{psfile=@var{filename}.ps @r{[}@var{key}=@var{value}@r{]} @dots{} @}
+@end example
+
+@noindent
+This downloads the PostScript file @file{@var{filename}.ps} such that
+the current point will be the origin of the PostScript coordinate
+system. The optional @var{key}@t{=}@var{value} assignments allow you to
+specify transformations on the PostScript.
+
+The possible @var{key}s are:
+
+@table @samp
+
+@item hoffset
+The horizontal offset (default 0)
+@item voffset
+The vertical offset (default 0)
+@item hsize
+The horizontal clipping size (default 612)
+@item vsize
+The vertical clipping size (default 792)
+@item hscale
+The horizontal scaling factor (default 100)
+@item vscale
+The vertical scaling factor (default 100)
+@item angle
+The rotation (default 0)
+@item clip
+Enable clipping to the bounding box
+@end table
+
+The dimension parameters are all given in PostScript units.
+The @samp{hscale} and @samp{vscale} are given in non-dimensioned percentage
+units, and the rotation value is specified in degrees.
+Thus
+
+@example
+\special@{psfile=foo.ps hoffset=72 hscale=90 vscale=90@}
+@end example
+
+@noindent
+will shift the graphics produced by file @file{foo.ps} right by one inch
+and will draw it at 0.9 times normal size. Offsets are given relative
+to the point of the special command, and are unaffected by scaling or
+rotation. Rotation is counterclockwise about the origin. The order of
+operations is to rotate the figure, scale it, then offset it.
+
+For compatibility with older PostScript drivers, it is possible to change
+the units that @samp{hscale} and @samp{vscale} are given in. This can be
+done by redefining @samp{@@scaleunit}
+@vindex scaleunit
+in @samp{SDict}
+@vindex SDict
+by a @TeX{} command such as
+
+@example
+\special@{! /@@scaleunit 1 def@}
+@end example
+
+@noindent
+The @samp{@@scaleunit} variable, which is by default 100, is what
+@samp{hscale} and @samp{vscale} are divided by to yield an absolute
+scale factor.
+
+
+@c @node Dynamic creation of graphics
+@section Dynamic creation of PostScript graphics files
+
+@cindex dynamic creation of graphics
+@cindex compressed PostScript
+@cindex uncompressing PostScript
+
+PostScript is an excellent page description language---but it does tend
+to be rather verbose. Compressing PostScript graphics files can reduce
+them by factor of five or more. For this reason, if the name of an
+included PostScript file ends with @file{.Z} or @file{.gz}, dvipng
+automatically runs @samp{gzip -d}. For example:
+
+@example
+\epsffile[72 72 540 720]@{foo.ps.gz@}
+@end example
+
+@noindent
+Since the results of such a command are not accessible to @TeX{}, if you
+use this facility with the @file{epsf} macros, you need to supply the
+bounding box parameter yourself, as shown.
+
+More generally, if the filename parameter to one of the graphics
+inclusion techniques starts with a left quote (@samp{`}), the parameter
+is instead interpreted as a command to execute that will send the actual
+file to standard output. For example:
+
+@example
+\special@{psfile="`gnuplot foo"@}
+@end example
+
+@noindent
+@flindex gnuplot
+to include the file @file{foo}. Of course, the command to be executed
+can be anything, including using a file conversion utility such as
+@file{tek2ps} or whatever is appropriate. This feature can be disabled
+with the @samp{-R} command-line option or @samp{R} configuration option.
+
+
+@c @node Fonts in figures
+@section Fonts in figures
+
+@cindex figures and fonts
+@cindex fonts, in PostScript figures
+@findex %*Font
+
+You can use any font available to @TeX{} and dvipng within a graphics
+file by putting a @code{%*Font:} line in the leading commentary of the
+file. Schematically, this looks like:
+
+@example
+%*Font: @var{tfmname} @var{scaledbp} @var{designbp} @var{hex-start}:@var{hex-bitstring}
+@end example
+
+Here is the meaning of each of these elements:
+
+@table @var
+@item tfmname
+The @TeX{} TFM filename, e.g., @file{cmr10}. You can give the same
+@var{tfmname} on more than one @samp{%*Font} line; this is useful when
+the number of characters from the font used needs a longer
+@var{hex-bitstring} (see item below) than conveniently fits on one line.
+
+@item scaledbp
+The size at which you are using the font, in PostScript points (@TeX{}
+big points). 72@dmn{bp} = 72.27@dmn{pt} = 1@dmn{in}.
+
+@item designbp
+The designsize of the font, again in PostScript points. This should
+match the value in the TFM file @var{tfmname}. Thus, for @file{cmr10},
+it should be @samp{9.96265}.
+
+@item hex-start
+The character code of the first character used from the font, specified
+as two ASCII hexadecimal characters, e.g., @samp{4b} or @samp{4B} for
+@samp{K}.
+
+@item hex-bitstring
+An arbitrary number of ASCII hexadecimal digits specifying which
+characters following (and including) @var{hex-start} are used. This is
+treated as a bitmap. For example, if your figure used the single letter
+@samp{K}, you would use @samp{4b:8} for @var{hex-start} and
+@var{hex-bitstring}. If it used @samp{KLMNP}, you would use
+@samp{4b:f4}.
+
+@end table
+
+MetaPost's output figures contain lines like this for bitmap fonts used
+in a MetaPost label (@pxref{MetaPost,,, web2c, Web2c}).
+
+
+@c @node Header files
+@chapter PostScript header files
+
+@cindex header files, defined
+@cindex PostScript header files
+
+@dfn{Header files} are bits of PostScript included in the output file;
+generally they provide support for special features, rather than
+producing any printed output themselves. You can explicitly request
+downloading header files if necessary for some figure, or to achieve
+some special effect.
+
+@vindex psheaderdir
+@flindex .pro @r{prologue files}
+@flindex .lpro @r{long prologue files}
+dvipng includes some headers on its own initiative, to implement features
+such as PostScript font reencoding, bitmap font downloading, handling of
+@code{\special}'s, and so on. These standard headers are the
+@file{.pro} files (for ``prologue'') in the installation directory
+@samp{$(psheaderdir)}; they are created from the @file{.lpro} (``long
+prologue'') files in the distribution by stripping
+comments, squeezing blank lines, etc., for maximum efficiency. If you
+want to peruse one of the standard header files, read the @file{.lpro}
+version.
+
+@vindex userdict@r{, and dictionary files}
+@cindex dictionary, @code{userdict}
+The PostScript dictionary stack will be at the @samp{userdict} level
+when header files are included.
+
+@end ignore
+
@node Graphics
@chapter Graphics
@@ -725,8 +1479,7 @@ wide:
@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
+To support color, dvipng recognizes a certain set of specials. These
specials start with the keyword @samp{color} or the keyword
@samp{background}, followed by a color specification.
@@ -893,7 +1646,7 @@ 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, and Takeshi Abe.
+Wolfram Krause, and Reinhard Kotucha.
@ifset man
@c man begin NOTES
@@ -903,34 +1656,36 @@ 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
+This program is released under the GNU General Public License, see the
+COPYING file in the dvipng distribution or
@url{http://www.gnu.org/licenses/gpl.html}.
-Copyright @copyright{} 2002-2008 Jan-@AA{}ke Larsson
+Copyright @copyright{} 2002-2006 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.
+This program is free software; you can redistribute it and/or
+modify it under the terms of the GNU General Public License
+as published by the Free Software Foundation; either version 2
+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 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/>.
+You should have received a copy of the GNU General Public License
+along with this program; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+02110-1301 USA.
@sp 2
@noindent
-Copyright @copyright{} 2002-2008 Jan-@AA{}ke Larsson
+Copyright @copyright{} 2002-2006 Jan-@AA{}ke Larsson
@node Index
@unnumbered Index