Importing DITA Files

Darwin Information Typing Architecture (DITA) file content is supported in Flare. DITA is an XML-based markup language with its own schema for authoring, producing, and delivering technical information. It is a standard of the Organization for the Advancement of Structured Information Standards (OASIS), and it consists of a set of design principles for creating "information-typed" modules at a topic level and for using that content in various delivery modes.

You can import DITA files in the a few ways.

How to Import DITA Files

1. Do the following, depending on how you are importing your files:

   To Import Into a New Project

   1. Select Project > Import > DITA Document Set.

      The Import DITA Wizard opens.

   2. Select Import into a new project.
   3. In the Project name field, type a name for the new Flare project that will be created after you perform the import.
   4. In the Project folder field, either accept the default location for the new project or click to find and select a folder.

   5. From the Output Type field, select the primary target for your project.

      A target is a file that generates output from your project. You want your output to look and behave in a certain way, but not all authors have the same audience or work for the same company with the same needs and the same computer networking setup. Therefore, Flare lets you choose the best type of output(s) for your needs. A target file is used for each instance of an output type. And you can have many targets in your project (e.g., eight targets using PDF, two targets using HTML5). See Determining the Output Type and Step 4: Developing Targets.

      This page of the wizard lets you select a primary target as you get your project off the ground. This means that—although you can use more than one target for your project—you might use one target most of the time. By selecting a primary target, you will be able to use shortcut buttons to build, view, and publish its output more quickly. Also, when you open topics in the XML Editor, they will be displayed by default with the styles and other specifications associated with the primary target. However, you can use the Layout and Medium drop-downs in the local toolbar of the XML Editor to view topics with other settings.

      Do not worry if you're not yet sure of the best output type for your project. No matter which output type you select now, you can always change the primary target later.

   To Import Into an existing Project (Wizard)

   1. Select Project > Import > DITA Document Set.

      The Import DITA Wizard opens.

   2. Select Import into this project.

   To Import Into an Existing Project (Import Editor)

   Do one of the following:

   if you do not yet have a dita import file

   1. Complete the steps for adding an import file. See Adding a DITA Import File.
   2. Open the file in the DITA Import Editor.

   if you already have a dita import file

   1. In the Project Organizer, expand the Imports subfolder.
   2. Double-click the appropriate import file. The file opens in the DITA Import Editor to the right.

2. Do one of the following, depending on the part of the interface you are using:

   • Wizard Click Next.

   • Import Editor Select the Source Files tab.
3. Click .

4. Find and select the files you want to import. You can hold the SHIFT key to select a range, or you can hold the CTRL key to select individual items. When you are finished, click Open.

   You can select DITA or DITAMAP files.

   Note You cannot select multiple DITAMAP files from different folders during the same import process. You must first import the DITAMAP file(s) from one folder. Then in the project that is created as a result, you can import the DITAMAP file(s) from a second folder.

5. You can use the following options as necessary.

   	This opens the file that is selected in the list.
   Link Generated Files to Source Files	This creates a connection between the original files and the files that are created as a result of the import. This is useful if you want to continue editing the content outside of Flare, instead of editing in the Flare project. Flare recognizes when changes have been made to the source documents and reminds you to reimport the documents to ensure the Flare project also reflects the changes. If you use this option, a link icon is added to the top of a linked file in the Flare interface. This lets you know that you need to edit the source file, rather than editing this file. If you remove the connection to the source file, this icon no longer displays on the file. Please note that if you have bound the project to source control, the icons used for source control take precedence over the link icon.
   	This removes the selected file(s) from the list.
   	This moves the selected file higher in the list (if you have more than one file to import). The file at the top is used for the name of the content folder holding the imported topics in Flare. Also, the order determines how the imported files are arranged in the Flare TOC that is created as a result.
   	This moves the selected file lower in the list (if you have more than one file to import).

6. Do one of the following, depending on the part of the interface you are using:

   • Wizard Click Next.

   • Import Editor Select the Options tab.

7. You can use the following options as necessary.

   • Import all Content files to one folder Select this option if you want all of the imported DITA file content to be placed in just one folder in the Content Explorer.

   • Auto-reimport before 'Generate Output' If you selected “Link Generated Files to Source Files” earlier in the wizard, you will likely make future content changes in the source files. When you make such changes, the source files need to be reimported into the project so that they can be included in the output. You have the option of reimporting the files manually. However, you can also tell Flare to do this for you automatically, so that you do not have to. Select this option if you want Flare to automatically reimport files when you attempt to build output.

   • Preserve ID attributes for elements Every element inside a DITA file has an ID. This ID is not needed in Flare. However, if you intend to send your output back out to DITA at any point, you can select this option to make sure the ID is preserved.

8. Do one of the following, depending on the part of the interface you are using:

   • Wizard Click Next.

   • Import Editor Select the Stylesheet tab.

9. Use this page to specify whether the imported topics should be associated with a stylesheet and/or styles from your DITA files.

   • Conversion Styles This opens the DITA Import Styles Editor, which lets you specify how to convert each property of the DITA elements. If you do not enter a property value, the value from the DITA file is used. If you enter a property value, it overrides the value from the DITA file. You can also use the dialog to import and export styles.

     Note When you import content from DITA files, there is a one-to-one conversion that occurs. For each DITA element in your file, a style class is created in Flare. For example, let's say you have a paragraph-level DITA element called "topictitle," after you import the file, a style class called "h1.topictitle" might be created in Flare. Or if you have a character-level DITA element called "cmdname," after you import the file, a style class called "span.cmdname" might be created as a result in Flare. If necessary, you can later edit those style classes in Flare (see Editing DITA Styles). If you generate DITA output from your project, the style classes are converted back to DITA elements.

   • Stylesheet If you already have a CSS file that you want to associate with the imported files, click the Stylesheet button. Then navigate to the stylesheet and select it.

10. Do one of the following, depending on the part of the interface you are using:

    • Wizard Click Finish. The Accept Imported Documents dialog opens. The files that will be created as a result of the import are listed on the left. A preview of each file can be seen to the right when you click the file.

    • Import Editor In the local toolbar click Import (if this is the first time importing files) or Reimport (if files have been imported previously). The Accept Imported Documents dialog opens. The files that will be created as a result of the import are listed on the left. A preview of each file can be seen to the right when you click the file.
11. When you are finished previewing the files to be created, click Accept.

What’s Next?

Now you can move on to any of the other basic steps:

• Step 2: Adding Content and Features
• Step 3: Designing
• Step 4: Developing Targets
• Step 5: Building and Publishing Output