Images and Figures

Edit online

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

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

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

This is a good technique to change the size of all raster images from your documentation. This will not work for vector images, such as PDF or SVG. If the images (PNG, for example) contain the image resolution in their metadata, this will be taken into account. For all other images, the default resolution is 120dpi.

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

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.

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.

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 second chapter starts over with "Figure 1" instead of incrementing to "Figure 3").

For the DITA Map PDF - based on DITA & CSS (WYSIWYG) transformation scenario type, you must reset the figure counter on each topic. In your customization CSS, use the following rules:

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

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

For the DITA Map PDF - based on HTML5 & CSS transformation scenario type, 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;
}