The psfig macro

Use of the psfig macro has been found to be the most successful at incorporating external postscript files into LaTeX documents, and at producing reasonable latex2html output.

In order to use this macro, the LaTeX document must contain the required definitions. This is most easily done by making use of the LaTeX \include command:

\include{psfig.tex}

somewhere soon after the \begin{document} command.

A copy of the psfig.tex is available from legacy.gsfc.nasa.gov via the OGIP's anonymous ftp or gopher servers. The following LaTeX code can then be used to include an external postscript file called fig1.ps in the LaTeX and html documents:

{\begin{figure}[tbh]
        \htmlimage{thumbnail=0.1}
        \centerline{
        \psfig{figure=fig1.ps,width=15cm}}
        \caption{This is the caption of the figure. 
	This particular example is actually the components of the PSPC
        {\it psf} versus off-axis angle at 0.188 keV.}
        \label{fig:fig1}
\end{figure}}

with the result shown in Figure 1.

Figure 1: This is the caption of the figure. This particular example is actually the components of the PSPC psf versus off-axis angle at 0.188 keV.

There are several points to note in the above example:

Firstly, it should be noted that in the LaTeX document, the placement of the 'figure' follows the normal LaTeX rules for floats. In the above example the [tbh] qualifier to the \begin{figure} commands instructs LaTeX to attempt to place the 'figure' in the following locations with the following priorities:

1. at the top of a page (the t in [tbh]),
2. at the bottom of a page (the b in [tbh]),
3. right here on the current page (the h in [tbh])
4. (if all else fails) the next available position.

As can be seen for them the inspection of the figure produced in the LaTeX document, the external postscipt file to be included (fig1.ps) is actually fairly large, and takes an entire page to be plotted along with the figure caption (at least for those funny US-sized pages). Thus the figure floats to the end of the document.

In contrast, in the latex2html version of the document, the figure (having been converted to a GIF image) is displayed exactly where it is defined in the LaTeX source code (ie in a location equivalent to h in the [tbh] qualifier).

Secondly there are many possible arguments to the \psfig command:

\psfig{file=, figure=, height=, width=, bbllx=, bblly=, bburx=, bbury=,
       rheight=, rwidth=, clip=, angle=, silent=}

where

• file is the name of the external postscript file. If no path name is specified and the file is not found in the current directory, then it will be looked for in directory specified by the \psfigurepath environment variable.
• figure is a synonym for file.
• By default, the width and height of the figure are taken from the BoundingBox of the external postscript file, however:
  • If width is specified, the figure is scaled so that it has the specified width. Its height changes proportionately.
  • If height is specified, the figure is scaled so that it has the specified height. Its width changes proportionately.
  • If both width and height are specified, the figure is scaled anamorphically.
• bbllx, bblly, bburx, and bbury control the postscript BoundingBox. If these four values are specified before the file option, the \psfig will not try to open the postscript file.
• rheight and rwidth are the reserved height and width of the figure, i.e., how big TeX actually thinks the figure is. They default to width and height.
• The clip option ensures that no portion of the figure will appear outside its BoundingBox. clip= is a switch and takes no value, but the = must be present.
• The angle option specifies the angle of rotation (in degrees, anti-clockwise).
• The silent option makes \psfig work silently.

Besides the obvious figure (or file), the width, height and angle arguments are straightforward and allow novice users to satisfy most of their requirements.

Thirdly latex2html provides some control of the image size in the html version of the document via arguments to the \htmlimage command:

• external to prevent the inlined images being created, but instead to produce a hyperlink to the image.
• scale to control the overall size of the image
• thumbnail to produce a (small) inlined image to be created in the html document, but also to produce a hyperlink to the full-size image.
• map to turn the inlined image into an active image map.

These are further described in the latex2html manual (see the latex2html "Home Page") For most applications, we have found the thumbnail argument to most useful since it allows small inlined images to be produced speeding up load-time, but (assuming it is big enough !) still enables users to get a feel as to what the figure contains and hence whther they wish to bother viewing the full-sized image.