Edit online

Images and Figures

Images are an important part of a publication.
Note: You can use raster image formats (such as PNG or JPEG), but it is best to use vector images (such as SVG or PDF). They scale very well and produce better results when printed. In addition, the text from these images is searchable and can be selected (if the glyphs have not been converted to shapes) in the PDF viewer.
Edit online

Images - Built-in CSS

Image properties are defined in [PLUGIN_DIR]css/print/p-figures-images.css.

  *[class ~= "topic/image"] {
        prince-image-resolution: 96dpi;
        -ah-image-resolution: 96dpi;
        image-resolution: 96dpi;
        max-width: 100%;
    }
Edit online

How to Fix Image Bleeding - Control Image Size

Sometimes the images may be too big for the page. The built-in CSS rules specify a maximum size for images, limiting to the width of the parent block. But if the parent block is itself too wide and bleeds out of page, you might consider specifying a length.

In your customization CSS, add the following snippet:

  *[class ~= "topic/image"] {
    ...
        /* The US-letter page size minus page margins. See p-page-size.css for the current page size. */
        max-width: 6.5in;         
    }

Pay attention to images that have an image map associated. The built-in rules set the max-width: auto for them to avoid scaling. Otherwise, it would cause a misalignment between the image and its clickable areas. These images are best to have a @width and @height attribute.

Edit online

How to Change Image Resolution

This is a technique to change the size of all raster images from your documentation. It will not work for vector images, such as PDF or SVG.

The default resolution is 96dpi, just as in a web browser. If the default resolution is not good (suppose you need a higher pixel density of 300dpi), you can change it by adding the following in your customization CSS:

*[class ~= "topic/image"] {
        prince-image-resolution: 300dpi;
        -ah-image-resolution: 300dpi;
        image-resolution: 300dpi;
}    
Important: The above selector does not apply to images from the <imagemap> element. You can use the selector for that purpose:
*[class ~= "ut-d/imagemap"] > *[class ~= "topic/image"] {
  ...
}
Make sure you verify the area shapes to match the new image boundaries. The pixels specified in the image map area coordinates are always 1/96 in. For more details, see: How to Use Image Maps.
Edit online

How to Place Big Images on Rotated Pages

Very wide images may bleed out of the page. One solution for this is to use landscape pages for these wide images.

In your customization CSS, add:

*[class~="topic/image"][outputclass='land'] {
    page: landscape-page;
}

Setting the attribute @outputclass = 'land' on the table element will force the table on a new landscape page.

Another solution is to set an @outputclass attribute on the image, then create a rule that matches it, and associate a landscape page for it.

Edit online

How to Place a Text and Image Side by Side

If you need to align text and an image side by side, you can use the following technique:

  1. Organize your text and image under a <div> element like this:
    ...
     <div outputclass="side-by-side">
          <p> This will be in the left side, the next figure in the right. </p>
          <fig>
            <image href="cactus.jpeg"/>
          </fig>
     </div>
    ...
    Note: You can use the @outputclass attribute to mark the <div> elements that have this special layout.
  2. In your customization CSS, add:
    *[outputclass ~= "side-by-side"] > *[class ~= "topic/p"] {
      display:inline-block;
      width: 45%;
    }  
    
    *[outputclass ~= "side-by-side"] > *[class ~= "topic/fig"] {
      display:inline-block;
      width: 45%;
    }  
    
    The image should fill the entire width of the parent <fig> element:
    *[outputclass ~= "side-by-side"] > *[class ~= "topic/fig"]  > *[class ~= "topic/image"] {
      width:100%;
    }
    By default, the bottom of the image is on the same line as the text baseline. If you want the text and the image to be aligned at the top, add these lines:
    *[outputclass ~= "side-by-side"] > *[class ~= "topic/p"] {
      vertical-align:top;
    }  
    
    *[outputclass ~= "side-by-side"] > *[class ~= "topic/fig"] {  
      vertical-align:top;
      font-size:0pt;  
    }  
    Note: The font-size:0pt is needed to remove the font ascent and descent around the image rectangle.
Edit online

How to Control the Image Size in Complex Static Content

It is common to have text and images mixed together in a :before or :after pseudo-element. For example, for notes you may have both artwork and text:

*[class ~= "topic/note"]::before {
    content: url('note.png') "Some text";
}

If you want to change the size of the image, you have two options:

  • Use the image-resolution CSS property:
    *[class ~= "topic/note"] {
        image-resolution:300dpi;
    }
  • Separate the image from the text and apply the width and height CSS properties only on the image, using the width and height properties. You could use multiple :before pseudo-elements for that, considering that the farthest content presented before the actual content of an element is matched by the :before with the highest number in the brackets:
    *[class ~= "topic/note"]:before(2) {
        content: url('note.png') ;
        width:0.5in;
    }
    
    *[class ~= "topic/note"]:before(1) {
        content: "Some text";
    } 
Edit online

How to Center Images

DITA defines a @placement attribute for the <image> elements. The implicit value is inline. Suppose that you need to center the images that have the placement set to break (for example, they are not on the same line with other content and the images from the <fig> element).

In your customization CSS, add:

*[class ~= "topic/fig"] {
  text-align:center;
}

/* Other images, with break placement. */
*[class ~= "topic/image"][placement='break']{
  display:block;
  text-align:center;
}

/* 
 Scaled images are getting a computed width attribute, so we can use the auto margins.
 Auto margins function only if the block they apply to has a width. 
*/
*[class ~= "topic/image"][placement='break'][width] {
  margin-left:auto;
  margin-right:auto;
  border: 2pt solid red; 
}
Edit online

How to Change/Reset the Figure Numbering

Note: This topic is applicable for the DITA Map PDF - based on HTML5 & CSS DITA PDF - based on HTML5 & CSS transformation types.
There are cases when you need to change the aspect of the figure counter that is shown before the figure titles. By default, the figure titles are formatted like this:
Figure NN. Lore Ipsum Title

NN is the number of the figure that starts being counted from the beginning of the publication.

One use-case is to have the NN counter be incremented only within one chapter (for example, the first chapter contains "Figure 1" and "Figure 2", and the second chapter starts over with "Figure 1" instead of incrementing to "Figure 3").

You should reset the figure counter on each topic marked as chapter, then hide the label from the figure <figcaption> (this is an HTML element generated by the XSL transformation), and create another label using a :before selector on the <figcaption>.

*[class ~= "topic/topic"][is-chapter] {
  counter-reset: figcount;
}

.fig--title-label{
  display:none;
}

*[class ~= "topic/fig"] > .figcap:before{
  /* Add more styling or change the content if needed */
  content: "Figure " counter(figcount) ". ";
  counter-increment: figcount;
}
Edit online

How to Fix Missing Images

If your images are not accessible, you may receive an error message in the transformation console like this:

Image not found. URI:file:/path/to/my/image

This is usually because they are in a folder that is not in the folder subtree of the transformed map or topic.

To solve this, you can set the following transformation parameter: fix.external.refs.com.oxygenxml=true.

Edit online

How to Use Image Maps

To use the DITA <imagemap> element in a PDF transformation, follow this procedure:

  1. Start by determining the width and height of your image in CSS pixels and specify it on the <image> element using the @width and @height attributes.
    Notes:
    • A CSS pixel is 1/96 in, so if the image is created at a 96dpi resolution, one dot from the image is one pixel in the CSS space. If your image is displayed at another resolution, then it is adjusted accordingly (for example, 192dpi results in two dots from the image being equal to one pixel in the CSS space).
    • You can use other CSS units, including percentages. The percentages are solved relative to the image size and represent a way of creating responsive image maps.
    Warning: If you publish the content for both PDF and HTML web output, make sure you only use pixels, as some browsers only support these units.

    Example:

    Suppose you have a very large image that is 6400x4800 dots, but you want to make it fit in a box of 640x480 CSS pixels. In the following snippet, this is done by specifying the width and height attributes. The areas must use coordinates relative to these values.
      <imagemap>
        <image href="../images/Gear_pump_exploded.png"
            id="gear_pump_exploded"
            width="640"
            height="480">
            <alt>Gear Pump</alt>
        </image>
    </imagemap>
  2. In the map element, add areas (each with a shape and a set of coordinates):
      <imagemap>
        <image ...> ... </image>
        <area>
            <shape>circle</shape>
            <coords>172, 265, 14</coords>
            <xref
                href="parts/bushings.dita#bushings_topic/bushings"
                format="dita">Bushings</xref>
        </area>
        <area>
            <shape>poly</shape>
            <coords>568, 81, 576, 103, 468, 152, 455, 130</coords>
            <xref
                href="parts/drive-shaft.dita#drive_shaft_topic/drive_shaft"
                format="dita">Drive Shaft</xref>
        </area>
        ....
     </imagemap

    The type of areas are the ones defined in the HTML standard: circle, poly, rect, default. For more details, see: https://html.spec.whatwg.org/multipage/image-maps.html#the-area-element.

  3. Verify how the shapes look in the output. You can make the shapes visible by one of the following methods:
    • Using the show.image.map.area.numbers and show.image.map.area.shapes transformation parameters.
    • Adding a CSS snippet to your customization. The shapes have the image-map-shape class, the bullet around the image map number (image-map-number), and the text inside the bullet (image-map-number-text). To make them translucent yellow:
      .image-map-shape{
      	fill: yellow;
      	fill-opacity: 0.5;
      	stroke-opacity: 0.5;
      }
      .image-map-number-text {
      	visibility: visible;	
      }
      .image-map-number {
      	fill: yellow;
      	fill-opacity: 0.4;
      	stroke-opacity: 0.7;
      }
Tip: An SVG with links can be used as an alternative to the DITA <imagemap> element. Make sure that each link is a relative URI to an ID inside the publication content.

How to Hide the Image Map Links List

Below every image map, a list of links that point to the image map targets is displayed. This list can be hidden from the final output by using the following CSS selector:

.imagemap--areas {
  display: none;
}
Edit online

How to Use SVG Syntax Diagrams

The DITA <syntaxdiagram> element is supported by the PDF transformation. To use SVG syntax diagrams, follow this procedure:
  1. Download the latest version of the svg-syntaxdiagrams plugin, unzip it, and copy all the folders into your DITA-OT-DIR\plugins folder (they all start with "com.").
  2. Open a command prompt inside DITA-OT-DIR\bin and run the dita install command.
  3. You can now add your custom <syntaxdiagram> element in your topic, as in the following example:
    <syntaxdiagram id="syntaxdiagram_ok4_c1k_xnb">
      <title>CopyFile</title>
      <groupseq><kwd>COPYF</kwd></groupseq>
      <groupcomp><var>input-filename</var><kwd>*INFILE</kwd></groupcomp>
      <groupseq><var>output-filename</var><kwd>*OUTFILE</kwd></groupseq>
      <groupchoice> <var>input-filename</var> <kwd>*INFILE</kwd></groupchoice>
      <groupchoice> <var>output-filename</var> <kwd>*OUTFILE</kwd></groupchoice>
    </syntaxdiagram>
  4. Run the DITA Map PDF - based on HTML5 & CSS (or DITA PDF - based on HTML5 & CSS) transformation.
    Warning: If you are not publishing the content for the first time, you may need to delete the out/ and temp/ folders to see the syntax diagram correctly in the .merged.html file.

Result: The PDF is generated and the syntax diagram is displayed as a referenced SVG file like this: