Information and tips regarding the image handling features.
When an image is added by inserting an image or fig element, the anchored frame is “shrink-wrapped” to the size of the image. The relative path to the image file is added to the href attribute and the height/width in pixels is added to the height and width attributes. When an image is added the initial value of the placement attribute matches that specified as the default in the EDD, unless the image is auto-inserted as the result of inserting a fig element in which case the placement attribute is set to “break.” For images where the placement attribute value is “break,” the initial alignment is set to match that of the default value of the align attribute as defined in the EDD; no alignment value is set for “inline” images.
You can change the alignment after inserting the image by editing the value of the align attribute or by selecting an alignment option in the Anchored Frame dialog (). The height and width cannot be set through the attribute value; they can only be changed by re-importing the image using a different scaling, or by changing the properties through the Object Properties dialog. The href attribute also cannot be changed through the attribute value.
If you do not want any height/width values associated with an image, deleting those attributes in the XML or Frame document will result in the image element being written with no values for height and width which uses the “native” (default) size of the image. This is often desirable for output being generated as HTML.
If you want to use the native size of raster images for output generated through the Open Toolkit but want to use a specific DPI for output generated from FrameMaker, add an “fmdpi:<DPI>” attribute value to the image/@otherprops attribute, where <DPI> is the DPI value. Adding this value to the otherprops attribute allows the DPI setting to round trip from XML to Frame and it will only be used by FrameMaker; other output processes will see no height and width values and will use the native image size. Adding this value to the otherprops attribute deletes any value set to the height or width attributes.
If you want to use the fmdpi feature for all raster images, enable the “Use fmdpi” setting in the Options dialog. This will set the fmdpi value to the DPI value you select when importing the image. The fmdpi value is only set for raster images; this feature is not avalable for vector images.
By default, the baseline offset for inline images is set to “2pts” (this shifts the image 2 pts below the baseline of the surrounding text). If you want to set this property to a different value, set the value of the BaselineOffset key in the INIOnly section of the ditafmx.ini file to the appropriate value. This property is only applied to inline images. Setting the “baseline offset” property in the read/write rules file has no effect.
Content of an image/alt element is stored in the image/@alt attribute while being edited in FrameMaker. To modify the alt element content edit the @alt attribute. Because this content is stored in an attribute, any attributes on the alt element or child elements of the alt attribute are discarded when the file is opened in FrameMaker.
As of DITA-FMx 1.1, you can now include callouts and other graphic overlay objects in your DITA files. Although this is not specifically supported in DITA, the data to round-trip these objects is stored in nested data elements immediately following the image element within a fig. This support is only available for images that are child elements of a fig element.
DITA-FMx supports the following types of graphic objects as overlay objects within an anchored frame:
Note that a Text Frame can only contain a single paragraph and the only properties that are saved are horizontal alignment and paragraph style. Other types of nested frames are not currently supported. Additionally, the object grouping mechanism is not supported.
The Text Line object uses the character style applied to the first character, and applies that style to all characters in the object. The Text Frame object stores the paragraph style name that is applied when it is created. Both of these styles, the character style for Text Line objects and the paragraph style for Text Frame objects, should be predefined in the Topic and Book templates so they will be formatted properly in the final output.
If you plan to edit callouts as XML (for localization or other purposes) you should not use the Text Line object. The dimensions of the text are stored in the data elements and will not update when you change the actual text. The result will be that the callout remains the same size with the text stretched or compressed to fit into the same area. If you plan to edit the callout text as XML, you should use the Text Frame object which defines the bounds of a region in which the text will flow.
The data stored in the nested data elements is very FrameMaker-specific, but can be translated into other formats such as SVG with a little effort. If your image element is within a fig element and contains graphic overlay objects, a data element will be inserted immediately following the image element. This data element will have the @datatype attribute set to “fm:imagedata”. Within this data element will be a child data element for each of the graphic overlay objects, and each will have a @datatype attribute set to a value appropriate for the object type (e.g. “fm:textline” for a TextLine object and “fm:polyline” for a Polyline object).
When written to XML, all of these data elements will be empty elements (just specifying @name and @value attribute values) except for the text of a Text Frame object. Because this content is likely to be modified for localization purposes, it is written to XML as content of the data element. On import to FrameMaker, this is converted to a data/@value.
Each of the child data elements will have the @value attribute set to a tilde-delimited string that specifies the property names and values. For some properties the associated value may be a very large numeric value, this is a FrameMaker “MetricT” value (this has nothing to do with the metric measurement system). When used for linear measurement, value of 65536 is equal to a point (1/72 inch).
The image/@placement attribute controls the anchoring position of images. By default, when inserting an image without a fig container, the @placement attribute will be set to “inline” (since this would typically be used for inline images). When inserting an image within a fig (inserting the fig, automatically inserts the image), the @placement attribute will be set to “break”. You are free to change the @placement value as needed for situations that require a different setting. When @placement is set to “inline” the anchoring position () is set to “At Insertion Point”, and when @placement is set to “break” the anchoring position is set to “Below Current Line” (these settings cannot be changed).
When @placement is “break” and @align is “left”, the image will be forced to the left margin (page margin or side head margin). If you are using side heads this is typically the formatting that’s needed, but if you’re not using side heads or when you have an image in indented text (like a list), you will probably want the image to be indented to match the text block.
If you make use of the “Move Figure Title” book-build option, you will find that setting the @placement of an image within a fig to “inline” will probably achieve the desired result. To automate this processing, DITA-FMx provides the “BreakToInline” parameter for the BookBuildOverrides section of the book-build INI file (ditafmx-bookbuild.ini). Setting this parameter to “1” will change all of the @placement=’break’ images to @placement=’inline’ that are in a paragraph whose left indent is greater than zero. This setting must be made manually in the book-build INI file, and may not work well in all situations, so it’s best to experiment a bit and test to make sure it is providing the proper results.