Incorporating the image into

This section covers only the incorporation of graphics as floating figures. Most of its suggestions can be generalised to cover other uses, but what appears here should suffice for most purposes.

Every object placed on a page by and is enclosed in a box. Usually there is a hierarchy of boxes involved in all but the simplest objects. For example, a letter in a word appears in a box which contains only that letter, which appears in a box containing all or part of the word (which might, after all be hyphenated), which appears in a box containing a line of text, which appears vertically between all the other line boxes which constitute a paragraph, etc...The general principle of graphics incorporation is to persuade to allocate a box of the right size and shape in the right place, in which the diagram will be drawn using the \special{} directive. Continuing the analogy drawn several times in this document to as a programming language, \special{} is similar in approach to the `assembly language insert' features often found in lower-level and systems programming languages.

Text found between the braces in \special{} is not `interpreted' at all by , but passed on to the tools used to process the .dvi file. Thus, the use of \special{} is almost always `non-portable', in the sense that changes may well have to be made to generate a document containing the directive at a different site or on a different computer system. This important point is often ignored by users, but is only too well-understood by producers of camera-ready conference proceedings. Collecting a large number of separately produced articles together may sound like a simple business, given the relatively high level of compatibility of basic systems, but the addition of graphics to each paper usually means coming to terms with a large number of different methods of graphics production and incorporation, and tempers can become frayed. If you are asked to send a document in source form to another site, agree with the remote site in advance how graphics, if there are any, are to be presented.

The two dvips tools used on site take different approaches to diagram incorporation with \special{}. By far the best way to explain this is with reference to an example. Suppose, for example, that the diagram to be included is held in a PostScript file called trivial.ps, has a correct %%BoundingBox, draws from the origin, and is 162 by 54 points in size (2.25''x0.75'' or 57x19mm). Assume also that the document uses 11pt.sty and a4wide.sty.

The dvips program offers a fairly sophisticated set of `hooks' on which to hang Postscript graphics. The style file epsf.sty contains a (locally-added) macro \epsffig{} which does almost all of the work for itself, as well as others which take care of more complex examples. In this case, since the PostScript file contains a sensible %%BoundingBox, the figure can be produced simply with the source given in Fig. .

In this case, the various calculations are done partly by the macros, and partly by dvips itself, and the \special{} is `hidden' in the \epsffig{} macro. Note that, since \epsffig was added locally, it should not be relied upon when shipping documents off-site. It is intended purely as a `simplest route' option to solve straightforward incorporation problems.

The general form of Postscript-graphic incorporation into is via the \special{} directive. If the Postscript file you wish to incorporate is considered `well-formed', then the locally-available Perl script pssp will generate a fragment to incorporate that file, consisting of a \vspace{} directive to allocate some vertical space and a \special{} directive to pull the file in. Running the command pssp with no arguments gives a summary of usage: there may even be a real manual page available by the time you read this document.

Practically speaking, you should approach the incorporation of PostScript graphics into in the following manner:

1. Do your best to generate the graphics in such a way as to follow the conventions mentioned above. If that fails, do your best to handcraft the conventions in the manner described above.
2. Try the methods described above to incorporate the graphics file. In each case, you should be able to get some sort of output, even if it looks odd. The best way to fix problems in this field is first to get to the stage where you have some output, then work towards making it correct output. Previewers and the ability to print out only one problematic page come in very useful here.
3. Investigate the `periphery' of each of the techniques described above, to see if a more complex form of one of them solves your problem. For example, dvips gives a large collection of different options for \special{}, allowing extensive flexibility in scaling, rotating, clipping and translating PostScript pictures. One of these configurations is almost bound to work. It may be that you have not fully exploited the options to the Postscript generation program; go back and check the manual pages to see if a better way can be found.