Images and Figures

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%;
    }

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.

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 @outputclass = 'land' attribute on the <image> element forces the image to be displayed on a new landscape page.

*[class~="topic/topic"]:has(*[class~="topic/body"] > *[class~="topic/image"][outputclass="land"]),
*[class~="topic/topic"]:has(*[class~="topic/body"] > * > *[class~="topic/image"][outputclass="land"]),
*[class~="topic/topic"]:has(*[class~="topic/body"] > * > * > *[class~="topic/image"][outputclass="land"]) {
  page: landscape-page;
}

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

1. Organize your text and image inside 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;
   }  

   Note: If your figure does not have a title, you can also set font-size:0pt to remove the font ascent and descent around the image rectangle.

   *[outputclass ~= "side-by-side"] > *[class ~= "topic/fig"] {  
     vertical-align:top;
     font-size:0pt;  
   }

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";
  } 

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; 
}

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 {
  display: inline;
  content: "Figure " counter(chapter) "-" counter(figcount) " ";
}

Of course you will need to update the links to these figures to show the same number:

.fig--title-label-number,
.fig--title-label-punctuation {
  display: none;
}

.fig--title-label-number-placeholder {
  content: target-counter(attr(href), chapter) "-" target-counter(attr(href), figcount) "  ";
}

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.

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

.imagemap--areas {
  display: none;
}

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