2 Figures and Images

Follow these guidelines to get the images to look correct in all output formats.

To insert an inline image (typically an icon), insert an <image> element. An inline image will be placed in line with the rest of the text, but this is something we seldom use. Most images will be inserted as block elements, which you can see in Figure 2-1

To insert an image as a block element or a figure with a title, always use the <fig> element.

Out of the box, an inserted figure with a title will be rendered, as shown below. The figure title is left adjusted above the image while the image is centered.

This is an inline image:

Figure 2-1. This is a Title and Image Inside a Figure Element

Tip: These tips apply only to PDF outputs. For all other output types, they have no effect:

If you have a vast figure and want to use the extra space in the left margin, you can specify outputclass="wide" on the fig element together with the width="column" on the image element
If you have a wide but not so tall figure, you can utilize the whole page by rotating the figure 90°. Set outputclass="rotatepage" on the fig element, and the page will be rotated in the PDF
If you use outputclass="rotatepage", the system will check if the title of the topic can stay on the same page as the figure. This will happen if there is no text between the title and the figure. This works fine for topics at level 1 , but for level 2, you do not have a page break before the heading, which may give you too much content on the rotated page. The workaround here is manually inserting a page break as the last item in the topic body before the topic with the rotated figure.

Image Sizes

Remember that images and figures will be used in different output types (PDF, HTML, etc.) when inserting them. Image resolutions are also different for print and web. Tridion Docs helps with these issues by automatically generating lower resolutions if you upload a high-resolution image.

PDF output is the most restrictive output format. You only have as much space as defined by the paper size. (More specifically, the column width is 160 mm, so your figures and images should not be wider than this.)

If you insert an image, the rendering size is based on the resolution found in the image file. In most photo editors for bitmap images, this is the DPI setting you can adjust.

For vector graphics (SVG), it gets more complicated. For some reason, SVG renders slightly differently in different editors and viewers. A 10x10 cm square in one editor may end up with sides that are 9.375 cm or 10.667 cm long in the output PDF, which is because there are different opinions on what DPI (!) an SVG has. The numbers are often 72, 90 or 96. You have to try your editor and see what appears in the PDF.

If you want an image of a specific size, you can set the width and/or the imageelement’s (NOT the figure!) height attributes.

In the PDF, you may want the image to be precisely the width of the column, which you achieve by specifying width='column'. If the PDF column width ever changes, this ensures that all images will still fit nicely into it.

Drawing Figures

All drawn figures must be in vector format. Tridion Docs supports SVG and PDF files.

Note: PDF preserves the fonts and alignment better than SVG. The recommendation is to use PDF.

The most common figures in data sheets are:

Block diagrams
Flow charts
Timing diagrams
Typical characterization graphs/plots

In application notes and user guides, we often have, in addition to the mutual data sheet figures:

Kit images
Kit set-up
- Complete set up/how add-on boards are connected to the motherboard/where to connect power/etc.
- Connector details: on which connector pins should the different cables be connected etc.
Screenshots of user interfaces
- Overview images
- Detailed images with arrows and labels

Vector graphic files can be created in applications like Visio, Illustrator, CorelDRAW, and Inkscape (free software). They can save in PDF format. Plots and graphs are usually created using Excel. Save the plot as PDF.

Screenshots are easily captured using the Snipping Tool found in Windows. Save as PNG.

Store photos in JPEG format.

Table 2-1. Graphics Formats
Illustration Type	Graphics Format
Block diagrams, flow charts, timing diagrams, graphs, plots, pinouts, schematics	PDF (recommended) or SVG
Photos (kit images, setup, etc.)	JPEG
Screen shots	PNG
Annotated photos (example: Kit image with arrows pointing at connectors, buttons, and LEDs)	JPEG embedded in SVG¹
Annotated screen-shot (example: User interface image with arrows pointing to buttons, check boxes, and text fields)	PNG embedded in SVG¹

Note: Import the bitmap into your favorite vector drawing tool (Illustrator, Inkscape). Then draw the arrows and labels. This way, you will always get sharp lines and labels when publishing to PDF. Use numbers for the arrow labels, and put a horizontal list below the image inside the fig element as a figure legend. If ever translated, the numbers are universal, so you don't have to edit the figure.

Equations

You shall use MathML to create equations. Do NOT use images of equations created in another application.