DITA-FMx User Guide

Adding Map to Book Metadata Mappings

Extending the default metadata mappings allows you to pass custom element and attribute data from the map to the generated book and component files.

Two DITA-FMx features read the attribute values on the fm-ditabook element (the root of a generated book file). These attributes can define values that are passed to the book components as FrameMaker variables. These attributes can also be used to control the show/hide state of conditions in the generated book components. For information on enabling these features see the ImportAttrsAsVars, and ImportAttrsAsConds parameter information in Book-Build INI file.

In order to add your own metadata mappings, you need to modify a number of files in the Book structure application. The following is an overview of the steps required; details are provided below.

  1. Modify the Book EDD to add new attributes to the fm-ditabook element definition, then import the updated EDD into the Book template.
  2. Modify the fmxbook.dtd file to add the new attribute definitions.
  3. Modify the bookmap2fmbook.xsl file to copy the desired metadata (attributes or element content) into the new fm-ditabook attributes.

Specific information regarding the modification of the DTD and XSL files are provided below.

Modifying the fmxbook.dtd file

The fmxbook.dtd file is found in the Book application’s dtd folder.

  1. Open the fmxbook.dtd file and locate the attribute definitions for the fm-ditabook element. The unaltered attribute definition should look like the following.

    <!ATTLIST fm-ditabook 
        href CDATA #IMPLIED 
        format CDATA #IMPLIED 
        title CDATA #IMPLIED 
  2. Add the new attributes. The example below adds a new “version” attribute.

    <!ATTLIST fm-ditabook 
        href CDATA #IMPLIED 
        format CDATA #IMPLIED 
        title CDATA #IMPLIED 
        version CDATA #IMPLIED 
  3. Save and close the DTD file.

Modifying the bookmap2fmbook.xsl file

The bookmap2fmbook.xsl file is used to aggregate the DITA topics into a book file and component FM files. It can be used to copy data from the DITA map into attributes of the fm-ditabook element. Most likely you would copy data from the bookmeta or topicmeta elements, but any accessible element or attribute data could be used.

Open the bookmap2fmbook.xsl file in a text editor. The default import XSLT file contains some default mappings that can be copied and modified to create your own. To locate this code, scan the XSLT file for the following:

<xsl:attribute name="created"> 
  <xsl:value-of select="translate(//critdates/created[1]/@date,'&#10;',' ')"/> 

Just copy the entire xsl:attribute block (3 lines), change the @name attribute to the value of the fm-ditabook attribute you want to create, then change the xsl:value-of/@select code to grab the value of the attribute or element you want to be assigned to the new attribute. You’ll see examples of both element and attribute matching, plus code that locates the first or last instance of that value (in case there may be multiple).

You’ll need to add a similar attribute definition for each type of metadata that you want to extract from the map. Note that even if you don’t expect there to be more than one instance of a metadata value, it’s a good practice to explicitly select the first (or last) value, just in case there are more than one in a file you’re processing.

Also note that these attribute definitions are found in two areas in the XSLT file, in the map template and the bookmap template. You’ll want to modify both or either as needed.