2.7. Images

Preparing Cogent Documentation :
	Chapter 2. Making Edits in doc/i/

2.7.1. Creating images

Our documents are set up to use three image different image formats: GIF, PDF, and EPS for HTML, PDF and Postscript outputs respectively. There are two main types of input for these formats: bitmaps and vector images. We'll discuss each output format separately.

HTML works best with small, bitmapped images, and GIF is the format of choice for the time being. It is recognized by DocBook, and is produced easily in many ways; we use Paint Shop Pro. Vector images can be converted to GIFs in Corel Draw, as well as several other packages.

PDF supports a limited number of image formats. We choose PDF images since they seem to be most compatible. We have found a way to convert bitmaps and vector images to PDF where they can be scaled with no loss of resolution, and where their file size remains relatively small. The former is important for good-looking output, and the latter for making the files accessible for downloading and storage. We use Corel Draw to convert GIFs or Corel vector drawings to PDF.

Postscript uses EPS. These image files tend to be very big, but can be printed at excellent resolution. We aren't currently distributing EPS documents electronically, so the size is not important. EPS images for Postscript can be either bitmaps or vectors. Either can be converted in Corel Draw. GIFs can also be converted to EPS in Linux, using ImageMagik (the display command).

Procedures

Procedure 2.1. Creating GIFs

Create the image or make a screen capture in Paint Shop Pro.
Save image as a GIF. (Reduce color depth to 256).
Import the GIF into Corel Draw 9 for conversion to PDF.

Procedure 2.2. GIF and vector image conversions in Corel Draw 9

Resize the page to the size of the image (using the sizing tool on the toolbar).
Center the image on the page.
Choose Publish to PDF from the File menu to export the image.
- Select the PDF for Prepress option at the bottom of the dialog box if your original is a GIF.
- Select the PDF for Web option in this box if your original is a vector image. Make sure your fonts are Ariel for best output.
If the image is a vector image, save it as a GIF.
Move or copy the image into the Linux document directory.
For some reason we haven't figured out yet, the image is displayed about 25% larger in the PDF generated from DocBook than in Windows. No problem, you can rescale it to any size with no loss of resolution using the scale and scalefit attributes of the <graphic> tag in DocBook.

File sizes

The size of these files can vary greatly, as the following chart illustrates. The original file in this chart is a single GIF file created in Paint Shop Pro, converted to PDF with various Publish to PDF options (as shown), and to EPS in Corel Draw 9. It was also redrawn as a vector image in Corel Draw 9 and converted to GIF, PDF, and to EPS, as shown:

Original	Converted to:	File size
GIF	no conversion	5 K
GIF	PDF for Document Distribution	35 K
GIF	PDF for Prepress	10 K
GIF	PDF for Web	27 K
GIF	EPS	1069 K
vector	GIF (8-bit palette)	4 K
vector	PDF for Document Distribution	17 K
vector	PDF for Prepress	16 K
vector	PDF for Web	6 K
vector	EPS	154 K

Current Guidelines

Based on this, we currently follow these guidelines for single-source images:

Screen captures: GIF originals, used as is for HTML, and converted to PDF for Prepress (PDF documents).
Diagrams: vector originals, converted to GIF (HTML documents), and PDF for Web (PDF documents).
EPS remains large-sized image files.

2.7.2. Including images

An image can be included in three ways:

A figure is automatically numbered, appears in a special table of contents section, and has a title. Its code looks like this:

<figure> <title>The Cascade Connect runtime window</title>
  <mediaobject>
    <imageobject>
      <imagedata  fileref="cc-test_10.gif"/>
    </imageobject>
    <imageobject>
      <imagedata  fileref="cc-test_10.pdf" scale=66 scalefit="1"/>
    </imageobject>
  </mediaobject>
</figure>

A normal image looks identical to a figure in the output, but has no number or title. Its code looks like this:

<mediaobject>
  <imageobject>
    <imagedata  fileref="cc-test_10.gif"/>
  </imageobject>
  <imageobject>
    <imagedata  fileref="cc-test_10.pdf" scale=66 scalefit="1"/>
  </imageobject>
</mediaobject>

An inline image is generally small, like an icon, and appears inside a string of text. Its code looks like this:

     ... then click on the
   <inlinemediaobject>
     <imageobject>
       <imagedata fileref="cc-icon_3.gif"/>
     </imageobject>
     <imageobject>
       <imagedata fileref="cc-icon_3.pdf"/>
     </imageobject>
   </inlinemediaobject>
                icon to start the installation.

There are SGML templates for these three types of images in doc/i/sgmltemplates/images.sgml. Notice that they each we have two image objects, one for GIFs and one for PDFs, which are used in HTML and PDF output respectively. The <imagedata/> tag is called an empty tag, because it has no closing tag and no content per se. Instead of content, we use attributes to specify the desired image, as explained below. Because it is an empty tag, we have to put a closing slash at the end of the tag, for XML compliance. The attributes we commonly use for the <imagedata/> tag are:

fileref refers to the file name of the graphic, with the .gif, .pdf, or other extension. Our processing tools choose the correct file type at run-time based on the kind of output we request. There is no relative path for the filename because the HTML image file must be in in the directory where the output is being processed, so it can be copied into the html/ subdirectory. (This is not nessary for PDF images, but right now we use the same system.)

For this to work correctly, we have added "pdf" to the list of preferred and acceptable mediaobject filename extensions in several places in both of our HTML and print stylesheet customization layers. To find these, look at the doc/config/cogent-both.dsl file and search for "mediaobject".

scale sets the scale factor, as a percent. This only works (and is only necessary) in PDF output.
scalefit="1" just activates the scale attribute, telling the processor that yes, we do want to scale this graphic.


2.6. Reference entries and sections		2.8. Screens and program listings