Know what DITA maps are and how to work with them in FrameMaker.
A DITA map allows you to organize DITA topics in a hierarchical structure. You can then create output for your organized content using different output formats.
For details on generating DITA output, see DITA publishing.
You can also use DITA maps to create keyspaces that you can use for indirect referencing.
See Using keyspaces to manage DITA key references.
See the specifications on DITA maps.
See how you can create a DITA map in FrameMaker
Choose .
Alternatively, choose . In the New XML dialog, go to the DITA tab and choose map.
By default, a DITA map is opened in the Resource Manager.
You can use the Resource Manager to:
Insert topics in the DITA map
Save the DITA map
Switch to the Document view to display the DITA map contents.
You can use the available FrameMaker tools, such as the Structure View and Elements panel, to work with a DITA map.
You can also include relationship tables to a DITA map.
For details, see DITA relationship tables.
Understand how you can insert topicref elements in a DITA map.
You can add topics to a DITA map by using the <topicref> elements
in the Elements catalog. You can also add topics
using Insert Child in the Resource
Manager.
FrameMaker supports the following <topicref> elements
that you can insert in a DITA map:
Identifies topics such as dita, topic, concept, task, reference, glossary entry, and glossary group. A topicref element can also contain other topicref elements to create a hierarchal structure.
See the specifications on topicref elements.
A convenience element that is equivalent to a <topicref> element
with the format attribute set to “ditamap”.
See the specifications on mapref elements.
A set of <topicref> elements that
can be reused in DITA maps and other topicset elements.
See the specifications on topicset elements.
A convenience element that is used to define keys without
any of the other effects that occur when using a <topicref> element:
no content is included in output, no title is included in the table
of contents, and no linking or other relationships are defined.
See the specifications on keydef elements.
References a <topicset> element.
See the specifications on topicsetref elements.
To insert a <topicref> element in a DITA map:
Place the insertion point at the root level of the map element, in the Structure View.
Choose .
If you select topicref, mapref, topicset, or keydef, the Insert Element dialog appears:
To use the inserted topicref as a key reference, enter a key name.
For details, see Using keyspaces to manage DITA key references.
In the HRef box, enter the location of the topic to reference. Or click Browse to navigate and select the topic. The topic is added as a direct reference.
Alternatively, if you have defined a keyspace for the current topic, you can select a key reference in the KeyRef drop-down list. The topic is added as an indirect reference.
For details on key references and indirect referencing, see Using keyspaces to manage DITA key references.
Understand how you can display DITA map content using FrameMaker, show or hide the preview of topicref elements
After you have inserted one or more topicref elements in a DITA map, you can choose to view the content of the referenced topics in the Document view.
You can also open the referenced DITA topics as separate documents in FrameMaker.
To preview the contents on a single reference element, select the topicref element in the Structure View.
To preview the contents of all reference elements, click anywhere in the topic but ensure that no element is selected. You are prompted to show content for all topicrefs. Also, you can choose to display referenced child maps.
To preview the content, choose .
To hide the preview, .
If a DITA map includes references to child maps, the Show and Hide options in the DITA map will show or hide the topics referenced in the child maps.
In the Document
view, FrameMaker displays > to denote that a topic
is a top-level topic in the DITA map. >> denotes
a topic is a second-level topic and >>> denotes
the topic is at level 3 (and beyond) in the DITA map.
If a DITA map contains references to one or more topics, you can open all the referenced topics in FrameMaker.
Ensure the DITA map is selected.
Press the Shift key and choose .
Alternatively, in the DITA map, choose .
To close all topic references, press the Shift key and choose .
Learn to save a DITA map in FrameMaker
The Save Ditamap As functionality in FrameMaker () allows you to save the DITA map to multiple outputs. When you save a DITA map as a book, you can take advantage of the FrameMaker book hierarchical features such as folders and groups. You can use FrameMaker book functionality such as page numbering and table of contents.
The following list of outputs, provide specific functionality:
A single self-contained FrameMaker document file (.fm). The document contains all the content from the DITA map. For example, the topic references. The topic references are embedded within the document. This implies that any changes to the topic files are not reflected in the composite document. If you share this document with another author, the author does not require the referenced topic documents. However, you can continue to work on the composite document using the available structure tools in FrameMaker.
The DITA map is saved as a .book file that includes each referenced topic file as a document within the book.
The DITA map is saved as a .book file. Each referenced topic file is converted to a .fm file.
When you save a DITA map as a composite document or book with FrameMaker components, you can use the DITAVAL conditional output functionality. In the Save Document dialog, if you check the Prompt For DitaVal File option, you are prompted for a DITAVAL file that you can use to conditionally output the contents to the selected output format. For details on DITAVAL, see DITAVAL.
Understand DITA referencing in FrameMaker, learn to set up reference content and update DITA references
DITA referencing (also known as DITA addressing) provides the capability to reference or link among DITA elements and between DITA elements and non-DITA resources.
You reference DITA content by DITA content references. You create links to DITA or non-DITA resources, by Using DITA cross-references to single source content. You can also use DITA links to Add links to related content.
The DITA specifications define two types of referencing:
References are established by pointing direct to the target. For example, in FrameMaker, when you create a conref using direct referencing, you navigate to and choose the DITA topic (.xml file). Similarly, you point directly to the DITA topic (.xml file) to create a DITA link or a DITA cross-reference. Direct referencing requires authors to explicitly choose the file containing the content to reference or link. This can be cumbersome and confusing if you have a large set of related content. Direct referencing is preferred if you do not have a large set of documents that reference or link to.
See the specifications on URI-based (direct) addressing.
References are established globally at the DITA map level using keys. For example, in FrameMaker, when you create a conref using indirect referencing, you do not point directly to the DITA topic. Instead, you point to a key that is defined Using keyspaces to manage DITA key references. Indirect referencing requires authors to choose user-defined keys when creating references or links. When setting up the keyspaces, a well defined nomenclature should be used to name keys. Indirect referencing is recommended if you are authoring in a large set of related content.
See the specifications on Key-based addressing.
To create a conref in your DITA topics, you first need to create a DITA topic (direct referencing) or a DITA map (indirect referencing) that contains the content (elements) that you plan to reuse. For example, say you plan to reuse a table, an ordered list, and an image across multiple topics. You will need to add these elements to the source topic. If you are using indirect referencing, the topic is then added to the DITA map. For details, see Using keyspaces to manage DITA key references.
To make an element reusable, you need to assign a unique identifier to the element. For details, see DITA ID attribute. FrameMaker uses this unique identifier to differentiate the conref elements. For example, if you update the source element, FrameMaker uses the unique identifier to identify the elements in the container topics that need to be updated.
The DITA ID attribute provides a method to uniquely identify content (topics or elements) to reference.
In a DITA topic, you can assign a unique ID to an element to use the element when you are creating a conrefs (DITA content references) or cross-references (Cross-references) to the element from another topic. By default, FrameMaker assigns a unique ID to the topic, when you Create a DITA topic.
See the specifications on ID attribute.
In the Structure View, select an element in the source topic.
Choose .
Alternatively, right-click on the element and choose Assign ID to Element from the pop-up menu.
To check if an element has an ID assigned to it, in the Structure View, click arrow sign to the right of the element.
If you assign a unique ID to an element to which an ID is previously assigned, you will be prompted to replace the existing ID.
Select an instance of the element for which you want to assign IDs.
Select to open the Assign ID dialog.
By default, the element selected before selecting Assign ID to Elements is selected in the drop-down.
Select Include specializations to assign IDs to specializations of the selected element. If you are in a DITA map, select Process Topicrefs in Ditamap to assign IDs to all instances of the selected element in the topics in the DITA map.
If you have multiple files open, select All open files to assign IDs to all the instances of the selected element in all the open files.
Click Assign.
In a DITA topic, you can directly reference content by specifying the DITA topic file (.xml). For example, to add links in the related links section, of a DITA topic, you can choose the topic files to reference (see Add links to related content).
However, DITA also provides the specifications for using keys to indirectly reference content. See the specifications on Key-based addressing.
Using keys, adds a degree of indirection to the referenced content. When working with keys, the author does not reference topic files directly. The author is provided with a keyspace, a collection of user-defined keys to reference. The keyspace internally references any number of topics. The author is then concerned only with the keys in the provided keyspaces. Also, since the keys are user-defined, they can be named appropriately to allow author to easily recognize them.
The keydef elements are used to create keymaps since, by default, these elements are not generated in DITA output.
A keyspace is created using a DITA map. To create a DITA map to use as a keyspace, you need to add keydef elements to the DITA map.
Add <keydef> elements to the DITA map.
For details, see Insert topicref elements in a DITA map.
The
keys attribute is used to identify a specific keydef in a keyspace.
Since the @keys attribute is mandatory for a <keydef> element,
you can specify the attribute value in the Attributes
for New Elements dialog or in the Key Name field
in the Insert Element dialog.
An author using the keyspace then will only refer to the key names and not directly to the associated DITA topics. For this reason, you should specify key values that are clearly indicative of the referenced (underlying) topic content.
Save the DITA map.
To use a key reference in your DITA topic, you need to load the container keyspaces in FrameMaker authoring environment.
Open the DITA Keyspace Manager dialog ().
From the Keyspace drop-down list, select a DITA map that is defined as a keyspace. For details, see Create a keyspace.
By default, the first key in the list is always selected. DITA maps that are open in the current session are displayed in the Keyspace drop-down list. You can search for a keyspace by entering the first few characters of the key.
If the required DITA map is not available in the list, click Load Keyspace and select the DITA map file. The key references defined in the keyspace are displayed in the defined keys list.
If you make changes to the keyspace (DITA map) after loading the keyspace in the current environment, click the Refresh icon to view changes to the key references.
Click OK to apply the selected keyspace across all open DITA maps.
To select a different keyspace for a particular document, use the set keyspace manager. You can set keyspace from multiple paths, such as, DITA cross-references, DITA links, and insert conrefs.
You can create references in DITA topics or maps, by any of the following methods:
Conrefs (See DITA content references)
Cross-references (See Cross-references)
Topicrefs (See Insert topicref elements in a DITA map)
If you update the referenced content, the references in the current topic are not immediately updated. For example, if a DITA map references a specific topic and the title of the topic is changed, the updated title does not immediately display in the DITA map.
To update the references in a selected topic or map, use the DITA Update References dialog:
Choose .
The DITA Update References dialog is displayed:
To update the references in the current topic or map, check the specific options and click OK.
You can search through a document or recursively through multiple files in a folder for links such as conref, topicref, link, or xref. By default, the Find References dialog box populates the ID of the current topic and element, if any is selected. Typically, you select the element which is referenced elsewhere, and then call this option.
Select . Or, to find the reference of the current element, right-click within the element, and select Find References. The element ID is populated automatically.
In the Find References dialog, enter the ID of the element, if necessary.
Optionally, to limit the search within a keyspace, select the keyspace for the current document.
Set the search scope. If you select a folder, you can recursively search for references to the element in all the files in the folder.
Click Search.