New DITA File

Creates a new DITA map or topic file.

There are two groups of items on the DITA-FMx > New DITA File menu. Items above the divider create a new map file and items below the divider create a new topic file. The number and label text of these items will vary depending on the map and topic structure applications you have selected in the Options dialog. Any element definition that defines a class attribute with a default value that contains “map/map” will be considered a “map” and any with a default value that contains “topic/topic” are considered a “topic.”

Figure 1. New DITA File menu

Each topic or map type is assigned a keyboard shortcut, if you want to define your own shortcut for specific topic types, see the information on the NewMapShortcuts and NewTopicShortcuts parameters in INI-Only Settings.

At the bottom of the “map” area is the command New ‘Map from Outline’ Template. This command creates a new FM file using the “Map from Outline” file as the template. By default, this template is named map-from-outline_template.fm and is in the root of the DITA-FMx structure application folder ($STRUCTDIR\xml\DITA-FMx_1.2\). You can specify an alternate template file by changing the MapFromOutlineTemplate parameter in the INIOnly section of the ditafmx.ini file. For more information, see Build Map from Outline and INI-Only Settings.

Choosing one of the New <ELEMNAME> menu items displays the New DITA File dialog. This dialog provides fields for entering the topic or map title, the topic ID, the file name, file path, and an optional element template to insert predefined structure and content into the new file.

Figure 2. DITA-FMx New DITA File dialog box

For new topics, the title is inserted into the first title element, for maps, the title text is entered as the map/@title attribute or in the map/title element (depending on the DITA version). The file name field is populated based on the value of the New File Name Format setting (in Options: New File Options). If the new file name format includes a building block that includes the title, the file name field will update as you enter text into the title field.

Entering a folder name into the File Name field will create the new file in the specified folder. If that folder, or folders, do not exist, you will be prompted to allow them to be created.

Tip: You can use building blocks to automatically create new files in folders based on the topic type. For an example, see the New File Options topic.

You can also select the Wrap in Dita Element option to create a topic file that includes the dita element as the root element. This is useful if you are creating files with nested topics, and required if you want to have multiple top-level sibling topics. The default value for this option is defined in the New File Options dialog.

When you choose OK, the file is immediately saved as XML using the name specified. If you don’t provide a file name extension for the new topic file, one is added based on the type specified in the Default File Type option in the Options dialog. DITA map files are always given the extension of “ditamap.”

When creating a new topic or map file, if your insertion point is in a DITA map at a location that is valid for a topicref-based element, a dialog displays asking for the type of element to insert, or none (to not insert as an element).

Creation of new DITA files differs from the standard FrameMaker “New” command because FrameMaker does not provide a method for creating an “Untitled” XML file (one that is not saved to the file system). If you want to start with an “Untitled” file, select the standard New command (File > New) and use the DITA template as the template file.