Adding Specialized DITA Document Types

Document Types > Document Types Available from Arbortext > Adding Specialized DITA Document Types

You can add your own specialized DITA document types to Arbortext Editor. Refer to the OASIS web site at www.oasis-open.org/ for more information about developing a specialized DITA document type. You can use the default DITA document types and their associated files in the Arbortext-path\doctypes\dita directory as a basis for your specialized document type. Note that many of the files you will need are located in the Arbortext-path\doctypes\dita\ditabase directory. The OASIS version of the DITA document types is also available in the Arbortext-path\doctypes\dita\oasis directory.

The base and technical content DITA topic document types have been consolidated in the DITA Ditabase document type. For the learning and training specialization, the topic types are consolidated in the Learning Ditabase document type.

Once you have specialized a DITA document type, follow these steps to add the document type to Arbortext Editor:

1. Create a directory in the Arbortext-path\custom\doctypes directory to store your specialized document type.

Give the directory the same name as your new document type. For example, if you create a specialization of the DITA Task document type named businessTask, then create a directory with the same name in the custom directory.

Move your new DTD or schema file(s) to that directory.

2. Create a catalog file for your new document type and add it to your document type's directory.

It is recommended that you use the catalog file for the DITA document type that was the basis for your specialization as a template for your catalog file, but only include entries for the files in your new document type directory.

For example, following is a catalog entry for a new business Task document type:

PUBLIC "-//ACME//DTD DITA Business Task//EN" "businessTask.dtd"

3. Create a document type configuration file (.dcf) for your new document type and add it to your document type's directory.

The distributed DITA and Technical Information Application document types use modular .dcf files. A modular .dcf file is a base .dcf file that includes one or more .dcf module files using file entities defined in catalog file entries. A .dcf module is a .dcf file or a partial .dcf file that you can include in a base .dcf file. If the same .dcf file entry is set more than once in a .dcf file or in one or more .dcf file modules, the last setting overrides any earlier settings.

If desired, you can use .dcf modules to create your own customized .dcf files for the distributed document types or new DITA specializations. Using the distributed .dcf file modules ensures that common .dcf file options that are not explicitly set in your .dcf file are automatically updated when new Arbortext Editor releases are installed. You can also create your own .dcf file modules, which simplifies maintenance of common .dcf file settings across a family of related document types. The distributed .dcf file modules are located in the Arbortext-path\doctypes\dita\common\dcfmodules and Arbortext-path\application\com.ptc.arbortext.techinfo\dcfmodules directories.

It is recommended that you rename a copy of the .dcf file for the document type used as the basis for your specialization and use that as the basis for your .dcf file. Following are the elements and attributes you might need to modify in the file:

◦ NewDialog element — Change the description, sample file, and template file attributes to match your new document type.

◦ idAttribute attribute on the Options element — Change the DITA ID attribute, if necessary.

◦ stylesheetDirectory attribute on the Options element — Designate the document type directory containing the .style file to use for the document type, if you are sharing stylesheets among document types.

◦ macroFile attribute on the Options element — Designate the document type scope macro file, if necessary.

◦ conrefAttribute attribute on the DitaOptions element — Change the DITA content reference attribute, if necessary.

◦ specializationAttribute attribute on the DitaOptions element — Change the DITA specialization attribute, if necessary.

◦ dragAndDropElementList attribute on the DitaOptions element — Designate how users can drag and drop folder structures into a map, if necessary.

◦ topicCompositionMap attribute on the DitaOptions element — Designate the map to use when composing topics, if necessary.

◦ RDEdit attribute on the DitaOptions element — Change the resolved document for editing document type, if necessary.

◦ RDStyle attribute on the DitaOptions element — Change the resolved document for styling document type, if necessary.

◦ Graphic element in the Specials element — Add any specialized graphic elements from your new document type, if necessary.

◦ Link element in the Specials element — Add any specialized link elements from your new document type, if necessary.

◦ Paragraph element in the Specials element — Add any specialized paragraph elements from your new document type, if necessary.

◦ Profiling element — Change the .pcf file reference to match your new document type, if necessary.

If you are installing a specialized DITA map, you might need to modify the following additional elements and attributes:

◦ ColumnView element — Change the Column View configuration to match your new document type.

◦ NewTopicDialog element — Modify the topic types available in the Resource ManagerNew Topic tab and the Insert Relationship Table dialog box, if desired.

◦ assignId attribute on the Options element — Disable user override of DITA ID assignment, if desired.

◦ resolvedMapEditing attribute on the DitaOptions element — Designate whether users can edit the resolved document for editing, if necessary.

4. Create sample and template documents for your document type and add them to the document type's directory.

You can use the existing custom\ditarefs directory to store files referenced from DITA documents. This directory is automatically added to the DITA references path. You can also use the existing custom\graphics directory to store graphic files.

5. Develop an Arbortext Styler stylesheet (.style file) for your document type and add it to the document type's directory, or edit the .dcf file to use an existing .style file.

If you create a new .style file, it is recommended that you rename a copy of the .style file for the document type used as the basis for your specialization and use that as the basis for your .style file. Be sure to set the element style correctly for any specializations you have made for graphic or link elements.

Note that the stylesheet distributed with the default DITA documents is also available as a modular stylesheet. The stylesheet modules are stored in the Arbortext-path\stylermodules directory. If you develop your stylesheet using modules, you can use the Arbortext StylerFile > Save as Merged Stylesheet feature to merge all of your modules into a single stylesheet when you have finished development. This can improve system performance. Refer to the Arbortext Styler help for more information on the DITA stylesheets.

You should also produce a new .genfos file to match your new .style file. In Arbortext Styler, edit your new .style file and select File > Update Stylesheet for Editor to export the .style file as a .genfos file. Add the file to the document type's directory.

The .genfos file supports Editor view of a document styled by the stylesheet. Having it available improves the time taken to open the document.

Refer to the Arbortext Styler documentation for more information about developing .style files.

6. If you are using profiling, create a profiling configuration file (.pcf) for your new document type and add it to your document type's directory, or edit the .dcf file to use an existing .pcf file.

Note that while multiple values for a single attribute are usually separated by semicolons in .pcf files, the DITA standard uses spaces to separate multiple values. By default, the Arbortext Editor DITA .pcf files use spaces to separate multiple values for a single attribute to match the standard.

If you create a new .pcf file, it is recommended that you rename a copy of the .pcf file for the document type used as the basis for your specialization and use that as the basis for your .pcf file. Note that you do not need to create a new .pcf file for all of your new specialized document types. If you have a family of specialized document types, you can use a single .pcf file for all of those document types. In this case, set the Profiling element in the .dcf file for each document type to point the common .pcf file.

7. If you are using alias maps, create an alias map (.alias) for your new document type and add it to your document type's directory or use a .alias file in the custom\lib directory.

If you create a new .alias file, it is recommended that you rename a copy of the .alias file for the document type used as the basis for your specialization and use that as the basis for your .alias file.

If a .alias file is present, Arbortext Editor automatically uses that alias map with a DITA document type. Note that a new alias map will not be used if the aliasmap preference is already set before the DITA document is opened in Arbortext Editor. Arbortext Editor searches for alias maps in this order in the following locations:

doctypedir\locale\lclocale\doctype.alias
doctypedir\locale\lclocale2\doctype.alias
doctypedir\locale\mclocale\doctype.alias
doctypedir\locale\mclocale2\doctype.alias
doctypedir\doctype.alias
Arbortext-path\doctypes\dita\common\dita.alias

Following are explanations of the locations in these file paths:

◦ doctypedir — The document type directory path for the current document as returned by the ACL function doc_type_dir

◦ doctype — The base name from the document type directory path

◦ lclocale — The locale value converted to lowercase

The locale value is either the value of the aliaslocale preference, if set, or the short form of the operating system locale returned by the ACL function get_locale.

◦ lclocale2 — The first two letters of the locale value converted to lowercase

◦ mclocale — The original mixed case locale value

◦ mclocale2 — The first two letters of the original mixed case locale value

8. Optionally, develop a DITA Ditabase document type that integrates your new topic specializations with each other and some or all of the existing OASIS DITA document types.

DITA Ditabase document types are used to collect different types of DITA topics into a single document. If you are installing one or more specialized DITA topics, you might want to develop a Ditabase document type that integrates your new specializations. Do not modify the distributed DITA Ditabase document type directly. Create a new directory for the document type in the Arbortext-path\custom\doctypes directory and put your new Ditabase document type there. Use the distributed Ditabase document type as a template to help you develop your new Ditabase.

9. Optionally, develop new document types for the resolved documents for editing and styling.

If you skip this step, Arbortext Editor will automatically generate a resolved document for styling DTD and a resolved document for editing XML schema when performing those operations. For details on developing custom resolved document types, refer to Working with DITA Resolved Documents.

10. If you are installing a specialized DITA topic, update the .dcf file for the DITA map document types you support.

Do not modify the distributed .dcf file directly. Create a new directory for the DITA map document type in the Arbortext-path\custom\doctypes directory, put a copy of the distributed .dcf file in that directory, and modify the copy.

Update the ditaRDEdit and ditaRDStyle attributes on the Options element to match your new custom-rdedit and custom-rdstyle resolved document types.

If desired, you can also update the NewTopicDialog element to include your new DITA topic type in the Resource Manager and the Insert Relationship Table dialog box.