Illustrations

The illustrations in this manual have been created using 3DLDF. The code that generates them is in the Texinfo files themselves, that contain the text of the manual. Texinfo is based on TeX, so it's possible to make use of the latter's facility for writing ASCII text to files using TeX's `\write` command.

The file `3DLDF-1.1.5.1/CWEB/exampman.web` contains the C++ code, and the file `3DLDF-1.1.5.1/CWEB/examples.mp` contains the MetaPost code for generating the illustrations. 3DLDF was built using GCC 2.95 when the illustrations were generated. For some reason, GCC 3.3 has difficulty with them. It works to generate them in batches of about 50 with GCC 3.3.

MetaPost outputs Encapsulated PostScript files. These can be included in TeX files, as explained below. However, in order to display the illustrations in the HTML version of this manual, I had to convert them to PNG ("Portable Network Graphics") format. See Converting EPS Files, for instructions on how to do this.

Please note that the illustrations cannot be shown in the Info output format!

If you have problems including the illustrations in the printed version, for example, if your installation doesn't have `dvips`, look for the following lines in `3DLDF.texi`:

```     \doepsftrue    %% One of these two lines should be commented-out.
%\doepsffalse
```

Now, remove the `%` from in front of `\doepsffalse` and put one in front of `\doepsftrue`. This will prevent the illustrations from being included. This should only be done as a last resort, however, because it will make it difficult if not impossible to understand this manual.

The C++ code in an example is not always the complete code used to create the illustration that follows it, since the latter may be cluttered with commands that would detract from the clarity of the example. The actual code used always follows the example in the Texinfo source file, so the latter may be referred to, if the reader wishes to see exactly what code was used to generate the illustration.

You may want to skip the following paragraphs in this section, if you're reading this manual for the first time. Don't worry if you don't understand it, it's meaning should become clear after reading the manual and some experience with using 3DLDF.

The file `3DLDF.texi` in the directory `3DLDF-1.1.5.1/DOC/TEXINFO`, the driver file for this manual, contains the following TeX code:

```     \newif\ifmakeexamples
\makeexamplestrue     %% One of these two lines should be commented-out.
%\makeexamplesfalse
```

When `texi2dvi` is run on `3DLDF.texi`, `\makeexamplestrue` is not commented-out, and `\makeexamplesfalse` is, the C++ code for the illustrations is written to the file `examples.web`. If the EPS files don't already exist (in the directory `3DLDF-1.1.5.1/DOC/TEXINFO/EPS`), the TeX macro `\PEX`, which includes them in the Texinfo files, will signal an error each time it can't find one. Just type `s` at the command line to tell TeX to keep going. If you want to be sure that these are indeed the only errors, you can type `<RETURN>` after each one instead.

`texi2dvi 3DLDF.texi` also generates the file `extext.tex`, which contains TeX code for including the illustrations by themselves.

`examples.web` must now be moved to `3DLDF-1.1.5.1/CWEB/` and ctangled, `examples.c` must compiled, and 3DLDF must be relinked. `ctangle examples` also generates the header file `example.h`, which is included in `main.web`. Therefore, if the contents of `examples.h` have changed since the last time `main.web` was ctangled, `main.web` will have to be ctangled, and `main.c` recompiled, before `3dldf` is relinked.1

Running `3dldf` and MetaPost now generates the EPS (Encapsulated PostScript) files `3DLDFmp.1` through (currently) `3DLDFmp.199` for the illustrations. They must be moved to `3DLDF-1.1.5.1/DOC/TEXINFO/EPS`. Now, when `texi2dvi 3DLDF.texi` is run again, the `dvips` command `\epsffile` includes the EPS files for the illustrations in the manual. `3DLDF.texi` includes the line `\input epsf`, so that `\epsffile` works. Of course, `dvips` (or some other program that does the job) must be used to convert `3DLDF.dvi` to a PostScript file. To see exactly how this is done, take a look at the `.texi` source files of this manual.2

In the `3DLDF.texi` belonging to the 3DLDF distribution, `\makeexamplestrue` will be commented-out, and `makeexamplesfalse` won't be, because the EPS files for the illustrations are included in the distribution.

The version of `examples.web` in `3DLDF-1.1.5.1/CWEB` merely includes the files `subex1.web` and `subex2.web`. If you rename `3DLDF-1.1.5.1/CWEB/exampman.web` to `examples.web`, you can generate the illustrations.

Footnotes

1. `ctangle` creates `<`filename`>.c` from <filename>`.web`, so the compiler must compile the C++ files using the `-x c++` option. Otherwise, it would handle them as if they contained C code.

2. If you want to try generating the illustrations yourself, you can save a little run-time by calling `tex 3DLDF.texi` the first time, rather than `texi2dvi`. The latter program runs TeX twice, because it needs two passes in order to generate the contents, indexing, and cross reference information (and maybe some other things, too).