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.¹

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.²

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.