What's New In DITA CMS 4.0

Transcription

1 What's New In DITA CMS / DITACMS v. 4.0 / Copyright 2014 IXIASOFT Technologies. All rights reserved. Last revised: December 11, 2014

2

3 Table of contents 3 Table of contents Chapter 1: New DITA CMS 4.0 features Dynamic Release Management 8 Overview 8 Understanding containers 9 Working on multiple documentation versions in parallel 13 Implementing and using Dynamic Release Management 15 For more information 16 Snapshots 16 Understanding the Snapshots feature 16 Create a snapshot 19 Generate the output of a snapshot 20 Branch a snapshot 21 Publish a snapshot 21 View the contents of a snapshot 22 Search view enhancements 23 Search for documents 24 Search example: Searching for a specific topic type 29 Search example: Searching for a DITA element 30 Working with the Referable-Content view 31

4 4 What's New In DITA CMS 4.0 Reusable components best practices 33 Create a referable_component_library map 34 Create a reusable component 35 Search for reusable components 36 Add a reusable component in oxygen 37 Add a reusable component in XMetaL 37 Viewing the release and change status comment history 38 Release a locked map, topic, or image 39 Change status 41 About the Information view 43 View information about selected objects 44 Disable update of the Information view 45 Spell checking improvements 46 Spell checking maps and documents 46 Check the spelling of topics and maps 47 Open the output folder automatically when using Generate Output 49 Preview a map 50 Minor enhancements 51 Terminology change 51 Chapter 2: New DITA CMS 4.0 Administration features Configure Search view options 54

5 Table of contents 5 Configure the Document Types panel 58 Add links to a bug tracking system in the release comments 60 Configuring jobs in the Scheduler 62 Configure the elements skipped during spell check 63 Encrypting passwords in text files 64 Encrypt a password 64 Chapter 3: New documentation Working with SVG files in Visio 68 Keep the topic.fo file 72

6 6 What's New In DITA CMS 4.0

7 1New DITA CMS 4.0 features New DITA CMS 4.0 features Topics: Dynamic Release Management Snapshots Search view enhancements Working with the Referable-Content view Viewing the release and change status comment history About the Information view Spell checking improvements Open the output folder automatically when using Generate Output Preview a map Minor enhancements This section describes the new features introduced in this release of the DITA CMS. For more information about these features, see the User's References on DITA CMS 4.0 documentation page.

8 8 What's New In DITA CMS 4.0 Dynamic Release Management This section describes the Dynamic Release Management module. Overview The Dynamic Release Management (DRM) module allows technical publication teams to easily manage the documentation for multiple products across multiple release cycles. In most technical writing projects, you need to maintain different versions of the same documentation set at the same time: As you're finalizing the delivery of the current version of Product A, you are already working on the next version of this product. You may also need to document multiple products, which may reuse the same content. The DRM module allows you to easily plan, deliver, and maintain your documentation releases. Branching and merging The DRM module provides two very flexible release management features: Branching: Branching lets you create a new documentation version based on the current version. For example, let's say that you are working on the documentation for Version 1 of Product A, and you need to start working on Version 2 right away. You simply branch the Version 1 documentation set and work from this new base to make the changes for the new version. You can edit existing topics, add new ones, and remove unnecessary ones in Version 2 without impacting Version 1. When you edit a topic, you can apply the changes to all the versions of the object or you can branch the topic and apply the changes to the new version of the topic only. Updating to previous versions: You can apply changes made in a new document version back to another version. For example, let's say that you had branched a topic to document new parameters added in Version 2 of the product. If Product Management decides to also add that feature in Version 1, you can simply update the new topic to that version, so that Version 1 now uses the updated topic. Products, releases, and versions In the DRM model, documentation is classified into three release management levels: Products: At the top level, you define a product. A product has its own configurable metadata (such as name and description) and contains one or more releases.

9 New DITA CMS 4.0 features 9 Releases: A release provides a second level of logical grouping for the documentation. A release has its own configurable metadata (such as name and description) and contains one or more versions. Versions: A version contains the actual documentation objects. Content is always created for a version. A version must exist before content can be added to it, and the same content object can be used in more than one version. The following diagram shows these concepts: For example, dynamic release management could be implemented as follows for the IXIASOFT documentation: There are two main products in this sample implementation: DITA CMS and TEXTML Server. Each product has two releases, and each release has multiple versions. The content of the DITA CMS and TEXTML Server product documentation is created at the version level. Understanding containers The DRM implementation is supported by a DITA map specialization called container. With the DRM module, maps do not contain links to the actual topics. Instead, they contain key references that are resolved by a container file. There is a one-to-one relationship between versions and containers: Each version is associated with a single container and a container is associated with a single version. The following diagram shows these concepts:

10 10 What's New In DITA CMS 4.0 In this diagram, MapA contains 4 topics: a concept and three tasks. The map does not reference the topics directly; instead, each topic is defined with a key. MapA also includes a reference to a container, Container_v1, which includes the key resolution. Let's illustrate these concepts with a fictional document called the DITA CMS Quick Start. This document has two topics: "About DITA" and "Working with topics". In the standard DITA CMS (without the DRM module), this map would be as follows: <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE bookmap PUBLIC "-//IXIA//DTD IXIA DITA Map//EN" "IxiaMap.dtd"> <bookmap id="lar " xml:lang="en-us"> <title>dita CMS Quick Start</title> <chapter href="lar xml"/> <chapter href="lar xml"/> </bookmap> As you can see in the code above, the map references the actual topic files directly using the href attribute. With the DRM module, the map does not reference the topics directly. Instead, it specifies the topics to include using key references. To resolve the keys, the map references a container, which contains the key definitions. For example, the following code shows the DITA CMS Quick Start map when using release management: <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE bookmap PUBLIC "-//IXIA//DTD IXIA DITA Map//EN" "IxiaMap.dtd"> <bookmap id="lar " xml:lang="en-us"> <title>dita CMS User Guide</title> <containerref href="lar ditamap"/>

11 New DITA CMS 4.0 features 11 <chapter keyref="lar "/> <chapter keyref="lar "/> </bookmap> As you can see in the example above, the topics are referenced with a keyref instead of being directly referenced with an href. The key name is always the ID of the object. The map also includes a reference to a container map. The following code shows the container that resolves the key definitions: <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE containerpart PUBLIC "-//IXIA//DTD DITA Container Part//EN" "containerpart.dtd"> <containerpart id="lar " xml:lang="en-us"> <title> {0001}</title> <keydefs> <topicgroup id="map"> <keydef href="lar ditamap" keys="lar " scope="local"/> </topicgroup> <topicgroup id="topic"> <keydef href="lar xml" keys="lar " scope="local"/> <keydef href="lar xml" keys="lar " scope="local"/> </topicgroup> <topicgroup id="image"/> </keydefs> </containerpart> Containers and container parts To simplify the explanation, the section above skipped a step in the chain of files required to resolve the keys. In reality, the map for a document points to a container, which in turn points to a container part. The container part is the file that contains the actual key definitions. The following diagram shows how containers and container parts are defined in the DRM module: There is a one-to-one relationship between versions and containers: Each version is associated with a single container and a container is associated with a single version. A container can have

12 12 What's New In DITA CMS 4.0 one or more container parts. Container parts allow projects with many objects to be organized into smaller parts for improved performance. By default, a container part holds 1000 objects (configurable). The following diagram shows an example of how containers and container parts are used in the fictional DITA CMS Quick Start document. Let's assume that this document is created in version of the DITA CMS product, release 3.4. As shown above, the DITA CMS Quick Start map points to container and includes two keys, one for each topic that it contains. Container references container part , which contains the definition for the keys used in the DITA CMS Quick Start map. Note that containers, container parts, and keys are transparent to end users, who do not need to understand these concepts to write their documentation.

13 New DITA CMS 4.0 features 13 Working on multiple documentation versions in parallel Branching and updating previous versions allow you to work on multiple documentation versions in parallel. When you need to work on a new documentation version that is based on an existing version, you can clone the documentation set used in that version. This allows you to use the existing content as a starting point for the next version. When you clone an existing version, the DITA CMS creates a new container and automatically branches all the maps in that version. For each existing map, it creates a new version of the map with the same content as the source version. The following diagram shows how the DITA CMS handles maps when branching a documentation set. In this diagram, when MapA in Version 1 is branched to Version 2, the DITA CMS creates a new version of the map and this map references the Version 2 container. At this point, the Version 2 container references the same content objects as in Version 1, as shown in the example below: The new version automatically reuses all the content objects from its source version. At this point, changes made in Version 1 are automatically propagated to Version 2. Important note Topics, images, and resources can be reused in multiple versions, but you cannot use the same map in multiple versions.when you add a map to another version, the DITA CMS creates a new version of this map, which references another container. The topics, images, and resources that the map contains can be reused in other versions, but each map version is used in a single version.

14 14 What's New In DITA CMS 4.0 Writers make the changes for Version 2 in the new map version. They can edit existing topics by branching them, they can add new ones, and they can also remove unnecessary ones, without impacting the source version. For example, the following diagram shows that Task 1 was branched: The DITA CMS has created a new version of Task1 (Task1 v2) and updated Container_v2 so that KeyB now references Task1 v2. Changes made to Task1 v2 will not be applied to Task1 v1. In the example below, a new concept was also added in Version 2. Version 2 will continue to use the same Concept1, Task2, and Task3 as Version 1, which means that any change made to these objects in Version 1 will be propagated to Version 2, and vice versa. Updating to previous versions You can apply changes made in a new document version back to another version. For example, let's say that version 2 of Task1 should also be applied to version 1 (MapA v1). You then simply update version 2 of Task1 to version 1, as shown below:

15 New DITA CMS 4.0 features 15 When version 2 of Task1 is updated to version 1, the DITA CMS updates Container_v1 so that KeyB now references Version 2 of the topic. Implementing and using Dynamic Release Management Implementing and using Dynamic Release Management in your deployment involves the following steps: Setting up the documentation structure Adding the documentation to versions These steps are introduced below. The remainder of this document provides the procedures for these steps. Setting up the documentation structure The first step for using the DRM module is to set up the documentation structure, which implies determining the products, releases, and versions that apply to your documentation suites. When you create the version for a release, you can create an empty version (usually appropriate for the first version in a release) or you can clone an existing version. When you clone an existing version, all the maps in that version are branched to the new version. This allows you to use the existing content as a starting point for the next version. Setting up the correct documentation structure is a very important step that should be discussed with IXIASOFT to ensure that the structure is optimal for your deployment. Once that structure is set up, it should be communicated clearly to end users so that they understand how they should create their documentation. Note: Only users with the right role are allowed to create and update the documentation structure. This is configured per deployment. Adding the documentation to versions When the documentation structure is set up, writers can add content to versions. Two options are possible: Creating content: When creating content, writers must assign it to one or more versions. The menus to create maps, topics, images, and resources in the DRM module require the writers to specify the version(s) in which the newly created object will be added. Note: In the current version of the DRM module, the standard DITA CMS import feature is not available. To import existing documents, please contact IXIASOFT Services to request an import script.

16 16 What's New In DITA CMS 4.0 Working on multiple versions of documentation sets: To work on a new version of an existing documentation set, you branch the documentation set by cloning that version. When you clone a version, the DITA CMS creates a new container and all the maps are branched automatically in the new version. Writers can then branch topics, images, and resources as necessary to modify the object used in the new version without impacting the source version. Note: You never branch a map. Maps are branched automatically when you clone a version or when you add a map to another version. You can also update objects to previous versions so that changes made in a new document version can be applied to the previous versions. For example, if you had branched a topic to document new parameters added in Version 2 and you need to apply these changes to Version 1 also, you can simply update the new topic to Version 1 so that both versions now use the updated topic. For more information For more information about the Dynamic Release Management module, see the Dynamic Release Management Module User Guide on the DITA CMS 4.0 documentation page. Snapshots This section describes the new Snapshots feature. Understanding the Snapshots feature You can now create snapshots of your working maps. A snapshot is a DITA CMS object that captures a map at a particular point in time. You can use this snapshot to rebuild the map and the objects that it contains topics, images, referable content, sub-maps, etc. exactly as they were when the snapshot was created. When you create a snapshot for a map, the DITA CMS creates an.xml file that contains the list of all the objects in the map (and sub-maps, if any) along with their current version numbers. For example, consider the following map, which contains a topic and a sub-map: <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE bookmap PUBLIC "-//IXIA//DTD IXIA DITA Map//EN" "IxiaMap.dtd"> <bookmap id="lar " xml:lang="en-us"> <title ixia_locid="1">sample map</title>

17 New DITA CMS 4.0 features 17 <chapter href="lar xml"/> <chapter format="ditamap" href="lar ditamap"/> </bookmap> The following code shows the contents of the snapshot file for this map. The snapshot includes the contents of the topic (in this case, an image and referable content) as well as the contents of the sub-map (in this case, a task that also includes an image). <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE snapshot PUBLIC "-//IXIA//DTD IXIA DITA Snapshot//EN" "snapshot.dtd"> <snapshot id="lar " xml:lang="en-us"> <title>sample map--snapshot</title> <snapshotmeta> <resourceid base="/content/authoring/" id="lar ditamap"/> </snapshotmeta> <manifest> <snapshotref cms-status="authoring:done" href="../../authoring/lar ditamap" navtitle="sample map" rev="4" type="bookmap"> <!-- Snapshot for topic lar xml and its image and referable-content --> <snapshotref cms-status="authoring:done" href="../../authoring/lar xml" navtitle="topic 1" rev="3" type="concept"> <snapshotref cms-status="authoring:done" href="../../authoring/lar image" navtitle="lock manager icon" rev="1" type="imagemeta"/> <snapshotref cms-status="authoring:done" href="../../authoring/lar xml" navtitle="contact Technical Support" rev="3" type="referable-content"/> </snapshotref> <!-- Snapshot for sub-map lar ditamap and its task, which also includes an image --> <snapshotref cms-status="authoring:done" href="../../authoring/lar ditamap" navtitle="sample sub-map" rev="3" type="bookmap"> <snapshotref cms-status="authoring:done" href="../../authoring/lar xml" navtitle="install Tomcat on Windows" rev="3" type="task"> <snapshotref cms-status="authoring:done" ref="../../authoring/lar image" navtitle="apache Tomcat Configuration" rev="1" type="imagemeta"/> </snapshotref> </snapshotref> </snapshotref>

18 18 What's New In DITA CMS 4.0 </manifest> </snapshot> For each object in the map that is, the map itself as well as all the objects that it contains: topics, images, referable content, sub-maps (and their contents), etc. the following information is kept: Status of the object Link to the object in the DITA CMS Navtitle Revision number Object type This information allows the DITA CMS to recreate the map exactly as it was when the snapshot was created. As with any DITA CMS object, you can search for a snapshot in the Content Store. You can also output a snapshot, branch it, or publish it. Important note To create the snapshot, the DITA CMS uses the latest released versions of the objects in the map. Therefore, if you have locked documents in your map, the snapshot will not include these locked versions but rather the latest released versions of these objects. Why use snapshots? In previous releases of the DITA CMS, if you wanted to keep track of the different versions of a map, you had to publish the map. For example, if you wanted to be able to go back to all the versions of all the maps that you delivered to your end users, you had to publish the maps at each milestone. There are two main issues with publishing maps: You need to bring the map and its objects to the final state of the Authoring cycle (for example, Authoring:done). This can be quite time-consuming for large maps. When you publish a map, the DITA CMS makes a copy of the map and all its objects and stores them in the Content Store, so the size of the database keeps growing even if the volume of source content is stable. Creating a snapshot does not create copies of the map and its objects. It's simply a text file that lists the map's contents at a specific point in time, so creating a snapshot has virtually no impact on the Content Store. Another advantage of snapshots is that you can create a snapshot from a map that is in any state, as long as the map is not locked. When using snapshots, you can:

19 New DITA CMS 4.0 features 19 Create a branch from a snapshot: Let's say that your team is still working on the documentation for Version 10 of your product, but you need to start working on Version 11. You can simply create a snapshot of the Version 10 documentation and then create a branch from the snapshot. Since you can create the snapshot of a map from any state, the Version 10 documentation can remain in the Authoring:work status. Generate the output of a snapshot: At any time you can see the content of a snapshot by generating its output. When you generate the output of a snapshot, the Output Generator retrieves from the Content Store the versions of the map and its objects as specified by the snapshot. New files are not created. Keep a historical record of all your documentation releases: Every time that you release your documentation or at important milestones, you can make a snapshot of your map. This ensures that you can see the content of a specific release at any time by generating its output or return to it by branching the snapshot. Create a snapshot When you create a snapshot, the DITA CMS creates an.xml file that contains the list of all the objects in the map along with their version numbers. Requirements The map must not be locked, but the objects in the maps may be locked. When you create a snapshot, the map and its objects can be in any state. Important note To create the snapshot, the DITA CMS uses the latest released versions of the objects in the map. Therefore, if you have locked documents in your map, the snapshot will not include these locked versions but rather the latest released versions of these objects. In the default configuration, when you create a snapshot, the snapshot object is in the Authoring:done status (or the equivalent in your deployment). You can create a snapshot from any view that lists the map (Search Results, DITA Map, Dependencies, etc.). To create a snapshot of a map: 1. In a view that lists the map, right-click the map and select Create snapshot. The Create Snapshot window appears:

20 20 What's New In DITA CMS 4.0 By default, the title of the map is used as the title of the snapshot. 2. If desired, modify the snapshot title in the Title field. This might be useful to differentiate the snapshots for a map. For example, to indicate that a snapshot identifies the version of the Web Author Installation Guide that was sent for technical review, you could enter "Web Author Installation Guide - Tech Review". 3. Click OK. The snapshot is created. As with any DITA CMS object, you can search for a snapshot in the Content Store. You can also output a snapshot, branch it, or publish it. Generate the output of a snapshot Just as with maps, you can output a snapshot using the Generate Output command. When you generate the output of a snapshot, the Output Generator retrieves from the Content Store the versions of the map and its objects as specified by the snapshot. You can generate the output of your snapshot in any format supported by the Output Generator. Note: You need Output Generator Version 4.0 to generate the output of a snapshot. To generate the output of a snapshot: 1. Use Search to find the snapshot you want to output. 2. Right-click the snapshot and select Generate Output. 3. Select the Output Format, specify required conditions and user fields (if any), and click Create. The Output Generator outputs the snapshot. Note: The Output Generator does not create copies of the snapshot objects. Instead, it simply retrieves the objects from the Content Store to create the output.

21 New DITA CMS 4.0 features 21 Branch a snapshot When you branch a snapshot, the DITA CMS first publishes the snapshot and then creates a branch from it. New, editable versions of the map and its objects are created in the Authoring cycle and given the status Authoring:work (or its equivalent in your workflow). To branch a snapshot: 1. Use Search to find the snapshot you want to branch. 2. Right-click the snapshot and select Branch > Create new branch. The DITA CMS first publishes the map. The Branch Map dialog is then displayed. 3. Enter a tag for this branch and click OK. The snapshot is branched and the branched map is displayed in the DITA Map view. Publish a snapshot When you publish a snapshot, the DITA CMS creates copies of the snapshot map and its objects and puts them to the Publish:done status (or as configured for your deployment). To publish a snapshot: 1. Use Search to find the snapshot you want to publish. 2. Right-click the snapshot and select Publish. The Publishing Tags dialog appears. 3. Enter the required tag Value(s) and click Create. The map and its object are created from the snapshot with the Publish:done status (or its equivalent in your configuration).

22 22 What's New In DITA CMS 4.0 View the contents of a snapshot You can view the contents of a snapshot using the Show Preview command. When you use the Show Preview command, the DITA CMS lists the objects in the snapshot, as shown below: Note: You need Output Generator Version 4.0 to preview a snapshot. To view the contents of a snapshot: 1. Use Search to find the snapshot to preview. 2. Right-click the snapshot and select Show Preview. The preview of the snapshot is displayed.

23 New DITA CMS 4.0 features 23 Search view enhancements You can now search the Content Store more easily thanks to enhancements in the Search view. In DITA CMS 4.0, many of the most common Advanced Searches have been moved directly to the Cycles, Document Types, and Search for panels. For example, you can search the objects that are in the Authoring:work status directly from the Cycles panel, without having to use the Advanced Search panel. As shown in the diagram below, the items in the Cycles and Document Types panels now have submenus: To search a specific state for a cycle, you now use the drop-down arrow directly in the Cycles panel instead of having to specify the state index in the Advanced Search panel. You can also search an index, attribute, or element by specifying it directly in the Search for panel with the Search in drop-down list: Figure 1: Search for panel

24 24 What's New In DITA CMS 4.0 By default, the DITA CMS searches the whole document for the string specified (i.e., the fulltext option is selected, as shown above). You can specify any index, attribute, or element directly in this panel instead of using the Advanced Search panel. Note: The Advanced Search panel is still useful to construct complex searches using many different criteria. Related Links Search for documents on page 24 To search for documents, you enter search criteria in the Search view. Results are displayed in the Search Results view. Search example: Searching for a DITA element on page 30 This example builds on the previous example searching for a specific topic type and refines the search so that it finds all referable-content topics that contain the <note> element. Search example: Searching for a specific topic type on page 29 In this example, we'll search for all referable-content topics in the Authoring cycle. Search for documents To search for documents, you enter search criteria in the Search view. Results are displayed in the Search Results view. The Search view is divided into panels, such as Document Types, Languages, Cycles, etc., that let you specify search criteria. Each panel has expand and collapse buttons that let you hide the panels you aren't currently working with. They each also have a set of buttons that let you: Function Button Save the current settings as the default for that panel Select all checkboxes Clear all checkboxes Apply the defaults for that panel The Search Results view lists the documents returned by your search criteria. You can group and filter the results.

25 New DITA CMS 4.0 features 25 By default, a maximum of 100 results can be displayed at one time. Search defaults are configurable. Note: Search is performed on the last version released to the server. To search the Content Store: 1. Open the DITA perspective. 2. Click the Search tab. 3. In the Cycles panel, select the document cycles you want to search. Figure 2: Cycles panel By default, all the states in the cycle selected will be searched. For example, if you select Authoring and click the drop-down arrow to the right of Authoring, a menu similar to the following is displayed: This menu displays all the states that are defined for your deployment. 4. To specify a different list of states, check and uncheck the states as required. A check sign ( ) in the check box indicates that all the states in the cycle are selected; a shaded check box ( ) indicates that only some of the states are selected. Click the drop-down arrow to see the selections.

26 26 What's New In DITA CMS 4.0 Note: If you see the message "selected items are different from default items" at the top of a panel, this means that the selections you have made are different from the selections that you have saved as default with the button. 5. In the Document Types panel, select the document objects you want to search. Figure 3: Document Types panel By default, all the subtypes for the document type selected will be searched. For example, if you select Maps and click the drop-down arrow to the right of Maps, a menu similar to the following is displayed: This menu displays all the map types that are defined for your deployment. 6. To specify a different list of subtypes, check and uncheck the subtypes as required. 7. In the Search for panel, enter a search string, such as the title of the document object.

27 New DITA CMS 4.0 features 27 Figure 4: Search for panel Search is not case-sensitive. Tip: You can use wildcards to refine your search; click the operators and their descriptions. button for a list of By default, the DITA CMS searches the whole document for the string specified (i.e., the fulltext option is selected).you can search a specific element, index, or attribute by changing the value in Search in. 8. To search a specific section of the objects (for example, the title element), select the element from the Search in list. To search the whole document, select the fulltext option. 9. (Optional) In the Limit to panel, select additional search criteria: a) Under Locked by:, choose me or others. b) To find documents assigned to you (whether Incoming, Active, or Retained), select Assigned to me. c) To search documents that are not referenced by any other document in the repository, select Orphans. d) To search for branched documents, select Branch and then select the branch tag from the drop-down list. e) To search for document objects within the active map, select Dita Map view. f) To search for document objects belonging to a specific project, select Project and choose a project. Note: The list displays only projects to which you belong. g) To search for document objects that were last modified by a specific user, select Last Modified By and select a user name.

28 28 What's New In DITA CMS 4.0 Figure 5: Limit to panel 10. In the Languages panel, select at least one language of the documents to be searched. Figure 6: Languages panel 11. To append the search results to an existing search results list, select Append to current results.

29 New DITA CMS 4.0 features Click the Search button. Document objects matching your search criteria are displayed in the Search Results view. Figure 7: Search results for "log in" search Note: Search criteria stay in effect when a panel is collapsed. If you previously performed an elaborate search, click in each panel of the Search window to restore the default settings before you search again. This topic describes the most common panels in the Search view. For more information on the Dates, Advanced Search, Taxonomy Terms, and Queries panel, see the documentation for these panels. Related Links Search view enhancements on page 23 You can now search the Content Store more easily thanks to enhancements in the Search view. Search example: Searching for a specific topic type In this example, we'll search for all referable-content topics in the Authoring cycle. 1. If necessary, click the New Query button. This sets all panels of the Search view to their defaults. 2. In the Cycles panel of the Search view, select Authoring. 3. In the Document Types panel, select Topics. 4. Click the drop-down arrow to the right of Topics. The list of all topic types are displayed. 5. Unselect all types and keep only referable-content.

30 30 What's New In DITA CMS Click the Search button. Note: If the Search button is disabled, check to see if you've supplied values in all the panels where one is required. Panels that need values show error messages such as the following. Documents matching your search criteria are displayed in the Search Results view. Related Links Search view enhancements on page 23 You can now search the Content Store more easily thanks to enhancements in the Search view. Search example: Searching for a DITA element This example builds on the previous example searching for a specific topic type and refines the search so that it finds all referable-content topics that contain the <note> element. We'll assume that you just finished running the referable-content search and that your search returned several hundred topics in the results. So now we'll add a search criteria to narrow its scope. At the end of the previous example, the Cycles and Document Types panels looked like the image below.

31 New DITA CMS 4.0 features In the Search for panel, select note from the Search in drop-down list. 2. Click the Search button. All the refererable-content documents in the Authoring cycle that contain a note are displayed in the Search Results view. Related Links Search view enhancements on page 23 You can now search the Content Store more easily thanks to enhancements in the Search view. Working with the Referable-Content view The Referable-Content view lets you search for reusable components and insert them into documents. What is a reusable component? The DITA CMS provides a topic specialization the referable-content topic type that you can use to store the text you plan to use in multiple topics. In the DITA CMS, a reusable component is an element that is within a <referable-content> body and has an id attribute. For example, consider the following referable-content topic: <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE referable-content PUBLIC "-//IXIA//DTD IXIA DITA Composite//EN" "IxiaDitabase.dtd"> <referable-content id="per " xml:lang="en-us"> <title>configure Kerberos authentication on the client</title> <rcbody> <note id="kerberos_prerequisites">to use Kerberos authentication, the client application and TEXTML Server must be running on Windows. Linux is not supported. </note> </rcbody> </referable-content> The <note> with the kerberos_prerequisites id is considered a reusable component by the DITA CMS. You can reuse these components in other topics using conrefs. For example, to reuse the Kerberos prerequisites paragraph in other topics, you create a conref to this paragraph in the target topic, as shown below: <note conref="per xml#per /kerberos_prerequisites"/> To easily find reusable components and insert conrefs to them into other topics, the DITA CMS now provides the Referable-Content view.

32 32 What's New In DITA CMS 4.0 Overview of the Referable-Content view Once you have created reusable content components, you use the Referable-Content view to search for these components and reuse them in other topics. The following diagram shows an example of the Referable-Content view after a search: The Referable-Content view provides the following information about the reusable components: Text Preview: Overview of the text that can be reused Element: Element type of the reusable component Element ID: ID assigned to the reusable component Owner Document: Name of the document that contains the reusable component This information can help you select the component to reuse in your document. You can restrict your search using the following criteria: Element type: This drop-down list displays all the elements for which a reusable component is defined.you can search inside a specific element type or select All element types to search inside all element types. Containing library: This drop-down list displays all the referable-component-library maps found in the Content Store. You can search inside a specific map or select All libraries to search inside all the maps. Once you have found the text that you want to reuse, you can easily insert it into the target topic using the Referable-Content view. Related Links Create a referable_component_library map on page 34

33 New DITA CMS 4.0 features 33 IXIASOFT recommends that you organize your referable-content topics into a referable_component_library map. Reusable components best practices The DITA CMS provides a topic specialization and a map template that let you store and organize your reusable components. You use the referable-content topic type to hold the text that you plan to reuse in other topics. You then build libraries of referable-content topics using a referable_component_library map. When creating reusable components and maps, IXIASOFT recommends that you follow these best practices. About reusable components Always use the referable-content topic type to store your reusable components. Otherwise, they will not be searchable with the Referable-Content view. Ideally, keep each reusable component as small as possible and store them in a separate referable-content topic. While this is not mandatory, it allows for a better organization of the reusable components and will have less impact on your work flow. For example, if you plan to reuse error messages, keep each error message in its own topic. This ensures that if you need to update a single message, only the topics that refer to this message will be impacted in your work flow (as opposed to storing all messages in a single topic, which would cause all the objects that reference any error message in the topic to be impacted). Assign IDs to each referable piece of content. IDs should follow a pre-defined naming convention for ease of use and standardization.you can also use the IDs that are automatically generated when you release the referable-content topic. See the DITA CMS System Administrator's Guide for more information about configuring the DITA CMS to automatically generate IDs. Label your reusable components so that you can also find them using the Advanced Search. Note: For small phrases such as product names or standard filepaths, IXIASOFT recommends that you use keys instead of reusable components. About reusable maps Organize your referable-content topics in a referable_component_library map. Maps are the key to organizing your reusable components so that you can find them easily. Determine a strategy for organizing your maps; for example, you could organize your maps: By logical group: Create a map for error messages, a map for warnings, a map for labels, etc.

34 34 What's New In DITA CMS 4.0 By product: Create a map for product A, a map for product B, etc. You could also build a map from all reusable objects that share the same label. Related Links Create a referable_component_library map on page 34 IXIASOFT recommends that you organize your referable-content topics into a referable_component_library map. Create a referable_component_library map IXIASOFT recommends that you organize your referable-content topics into a referable_component_library map. A referable_component_library map is a map that includes the <data name="referable_component_library"/> element. For example, the following code shows a sample referable_component_library map: <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE map PUBLIC "-//IXIA//DTD IXIA DITA Map//EN" "IxiaMap.dtd"> <map id="lar " xml:lang="en-us"> <title>acme Referable Content Map</title> <data name="referable_component_library"/> <topicref href="lar xml" keys="lar "/> <topicref href="lar xml" keys="lar "/> <topicref href="lar xml" keys="lar "/> </map> Note: The DITA CMS provides a referable_component_library template that you can use to create your referable component library maps. But you can also use any other type of map, as long as you add the following element in the map: <data name="referable_component_library"/> To create a referable content map: 1. Do one of the following: Press Ctrl-Alt-M On the Document Creation toolbar, click the Create Map button ( ) From the menu bar, select DITA CMS > Create Map The Create Map dialog appears. The ID field displays the system-assigned ID. 2. Enter a title in the Map Title field. 3. In the Map template area, select referable_component_library.ditamap.

35 New DITA CMS 4.0 features Specify the other options as required and click Create. 5. Add your referable-content topics to the map. Related Links Working with the Referable-Content view on page 31 The Referable-Content view lets you search for reusable components and insert them into documents. Reusable components best practices on page 33 The DITA CMS provides a topic specialization and a map template that let you store and organize your reusable components. Create a reusable component You store reusable components in a topic of type referable-content so that you can search for them with the Referable-Content view and insert them into other topics. The referable-content topic specialization is designed specifically to store reusable components. You can then use the Referable-Content view to search reusable components and reuse them in other topics. Referable-content topics are created like any other topic. Simply select the specialized template (referable-content.xml) when you create a topic. The referable-content topic supports all valid DITA elements. To create a reusable component: 1. Create a topic of type referable-content. 2. Open the referable-content topic in your XML editor. 3. Place your cursor inside the <rcbody> element. 4. Enter the text you want to reuse in other topics. You can use any valid XML element. You could, for example, create the following note: <note>to use Kerberos authentication, the client application and TEXTML Server must be running on Windows. Linux is not supported. </note> 5. In the opening tag of the source text, insert an ID attribute. For example, you might use the string "kerberos_prerequisites", which would give you the following code: <note id="kerberos_prerequisites">to use Kerberos authentication, the client application and TEXTML Server must be running on Windows. Linux is not

36 36 What's New In DITA CMS 4.0 supported. </note> Note: The DITA CMS will automatically insert an ID to any element that is a direct child of <rcbody> when you release the topic. If you prefer, you can use these automatic IDs instead of inserting your own. 6. Save and release the referable-content topic. 7. Add the topic to a referable component library map. You can now use the Referable-Content view to search for the reusable content and add it to your topics. Search for reusable components The Referable-Content view displays the components that you can reuse in your documents. To search for reusable components 1. To display the Referable-Content view, from the menu bar select Window > Show View > Other. The Show View window is displayed. 2. Expand DITA CMS - General, select Referable-Content, and click OK. The Referable-Content view is displayed. 3. In the Search area, enter a search string. You can use the standard Search wildcards to refine your search. If you don't enter a search string, all available reusable components are returned. 4. To search within a specific element type, click the element types drop-down list and select an element type. This list displays the element types for which referable content is currently defined. To search all element types, select All element types. 5. To search within a specific referable content map, click the libraries drop-down list and select a map. This list displays all the referable_component_library maps. These are the maps that contain the <data name="referable_component_library"/> element. To search within all referable_component_library maps, select All libraries. 6. Click Search.

37 New DITA CMS 4.0 features 37 The referable components that match the search criteria are listed in the search results area. The search results area displays 20 results at a time. Use the page buttons to navigate through your results if there are more than 20 results. Tip: If you assigned labels to your reusable components, you can also use the Advanced Search panel to search for reusable components with a specific label. Add a reusable component in oxygen You can add a reusable component to a target topic in oxygen from the Referable-Component view. When you add a reusable component using the Referable-Component view, the DITA CMS inserts a conref to the reusable component in the target topic. To add a reusable component in oxygen: 1. Open the topic where you want to reuse text in your XML editor. 2. Place your cursor where you want to add the reusable component. Make sure that your cursor is in a valid position for the type of element you want to insert. For example, you cannot add a reusable component of type <step> in a topic of type concept. 3. Use the Referable-Content view to search for the component to reuse. 4. In the search results, right-click the reusable text and select oxygen Edit > Insert as conref. The reusable text is included in the document. 5. Save your target file. Add a reusable component in XMetaL You can add a reusable component to a target topic in XMetaL from the Referable-Component view. When you add a reusable component using the Referable-Component view, the DITA CMS inserts a conref to the reusable component in the target topic. To add a reusable component in XMetaL: 1. Open the topic where you want to reuse text in your XML editor. 2. Place your cursor where you want to add the reusable component.

38 38 What's New In DITA CMS 4.0 Make sure that your cursor is in a valid position for the type of element you want to insert. For example, you cannot add a reusable component of type <step> in a topic of type concept. 3. Use the Referable-Content view to search for the component to reuse. 4. In the search results, right-click the reusable text and select XMetaL Edit > Insert as conref. The reusable text is included in the document. 5. Save your target file. Viewing the release and change status comment history You can now reuse a previously entered comment when you release a document or change its status. In previous releases of the DITA CMS, you could either use one of the configured preset comments or enter a comment manually in the Comment area. The Change Status and Release windows now include a new option that lets you select a previously entered comment, as shown below: The window keeps the last ten comments entered.

39 New DITA CMS 4.0 features 39 Release a locked map, topic, or image The Release command saves your latest modifications to the server and frees the file so other users can edit it. Prerequisites: The document object (that is, a map, image, or topic) must be in the locked state. Document objects can only be released by the user who locked them. Releasing a map, topic, or image saves your latest modifications to the server and frees the file so other users can edit it. In the case of a map, the release command updates changes to the map's structure. In the case of an XML topic, the release command validates the topic to ensure that references are correct and that the XML is well-formed. If your XML document has errors, you will be able to save it locally, but you will not be able to release it to the server. Using the release function regularly serves two purposes: Data preservation: saves a copy of your work in the repository. Collaboration: shares your update with other users. The Release function is available from all DITA CMS views. To release a document: 1. Search to locate the map, topic, or image you want to release. 2. Select one or more document objects to release. 3. Right-click and select Release. The Release dialog box appears:

40 40 What's New In DITA CMS 4.0 Figure 8: Releasing a topic 4. Do one of the following to describe the changes since the last update: Under Comment, enter a comment. Select a comment from the Choose a previously entered comment area. Select one or more comments in the Preset comments area. Note: If preset comments have not been configured for your DITA CMS, the Preset comments area will be blank. 5. (Optional) If you are using a bug tracking system (such as JIRA or Bugzilla), add the bug number that you are fixing with this release in the Tracker link field. A link to the bug will be added to the Release History. To add more than one bug, separate them by a comma. 6. (Optional) To update the document without releasing it, select Keep locked. Note: The Substantial Change option, selected by default, means that when the document is released, it can be advanced to the next status (typically edit/review). However, if you made a minor change to a previously-edited topic, you can clear the Substantial Change option. The document state will pass directly from rework to done (or according to your configuration) and the document will not appear in SMEs' Todo lists.

41 New DITA CMS 4.0 features Click OK. The document is updated in the repository of your Content Store. If you release a document that has not been changed, the lock is simply removed; no new document version is created in the DITA CMS. If you did not keep the file locked (Step 5), the file properties are displayed in black text in the various views. The comment you specified appears under Last User Comment in Todo Lists, as well as in the other places that file properties are displayed, such as Search Results view and DITA Map view. Tip: The procedure above described how to release a closed topic. Alternatively, you can use release to update an already-open topic: If you're using the XMetaL editor and you want to release a topic that's currently open in your editor, you can do one of the following: Right-click anywhere in the topic, then select Release Type Ctrl-Alt-Shift-R If you're using the Oxygen editor and you want to release a topic that's currently open in your editor, you can do one of the following: In Text mode, right-click anywhere in the topic, then select Release Type Ctrl-Alt-Shift-R Click the Release file button in the toolbar ( ) Change status This procedure describes how to update the status of a document object in the document cycle. Prerequisites: The document object must have a status other than published (or as defined in your configuration). The document object must be unlocked. This function is available from all DITA CMS views. 1. From the DITA perspective, perform a search to locate the document object. Tip: For topics, you might prefer to search for and open the parent map. Expand the map ( ) to view all its topics. 2. Release any locked document objects for which you want to change the status.

42 42 What's New In DITA CMS Select the document objects for which you want to change the status. Note: If you are selecting more than one document object, they must all have the same status (check the Status column). 4. Right-click and select Change Status from the menu. The Change Status window appears: Figure 9: Change Status window The statuses available depend on which cycle is applicable for the parent map (Authoring in the example above) and the states configured for your DITA CMS. 5. Do either of the following: Beside New Status, select a status from the drop-down list. Click a status in the flow chart. Note: If you cleared the Substantial Change option when releasing the document object, certain states may not be available. 6. (Optional) To enter a comment, do one of the following: Under Comment, enter a comment. Select a comment from the Choose a previously entered comment area. Select one or more comments in the Preset comments area. Note: If preset comments have not been configured for your DITA CMS, the Preset comments area will be blank.

43 New DITA CMS 4.0 features 43 The comment that you enter will appear under Last User Comment in everyone's Todo Lists, as well as in the other places that file properties are displayed. 7. Click Change. Note: If your system is configured for obligatory comments, you will need to enter a comment. If this change impacts other documents other maps that refer to a topic, for example a warning dialog appears. 8. Click OK to continue with the change. The status is updated and displayed in the various views. If you have demoted a document to the beginning of its cycle, you are automatically assigned that document. About the Information view The DITA CMS offers a view that provides information about an object selected in any DITA CMS view (such as the Search Results and DITA Map views). The following diagram shows a sample Information view:

44 44 What's New In DITA CMS 4.0 The Information view provides the following details: The Display All Values section lists the values for all the fields that can be displayed in any view (for example, in the Search Results columns). This information is configurable per deployment. Note: For more information about adding or removing the information displayed in the DITA CMS views, see the DITA CMS System Administrator's Guide. The Display Parents section lists the parents (for example, containing maps) to which the selected object belongs. View information about selected objects You can view information about DITA CMS objects using the Information view. The Information view is updated whenever you select an object in any DITA CMS view. To view information about an object: 1. To display the Information view, from the menu bar select Window > Show View > Other. The Show View window is displayed. 2. Expand DITA CMS - General, select Information, and click OK. The Information view is displayed. 3. Select an object in any of the DITA CMS views (DITA Map, Search Results, Dependencies, etc.).

45 New DITA CMS 4.0 features 45 The Information view is updated and provides details about the selected object. 4. To customize the information displayed in the Information view: a) Click the Show/Hide Sections button ( ) in the top-right corner of the view. b) Customize the options as follows: Display All Values: Clear this option to hide the values section. Display Parents: Clear this option to hide the parents section. Show Empty Values: Clear this option to see only the fields with available values. The view is updated with your changes. By default, the Information view is updated whenever you select an object in any DITA CMS view. You can disable this behavior by pinning a specific document in the view. Related Links Disable update of the Information view on page 45 You can keep a specified document open in the Information view while you open other documents. Disable update of the Information view You can keep a specified document open in the Information view while you open other documents. By default, the Information view is updated whenever you open a document. You can disable this behavior by pinning a specific document in the view. To disable update of the Information view: In the Information view, click the Pin Content button. The Information view will no longer be updated when you open other documents.

46 46 What's New In DITA CMS 4.0 Spell checking improvements The DITA CMS now provides a Spellchecker view with additional functionality. Spell checking maps and documents You can spell check selected topics and maps without opening them by simply right-clicking the topic or map and selecting Spellcheck. The results of the spell check are displayed in the Spellchecker view, shown in the following diagram: The Spellchecker view provides the following information: Number of errors found in the spellchecked documents For each spelling error, the following information is provided: Misspelled word Number of occurrences of the misspelled word Document in which the misspelled word was found Words are listed once per document, even if the document contains multiple occurrences of the misspelled word. Words that are misspelled in multiple documents are listed once per document. Case sensitivity The Spellchecker is case sensitive; for example, Unix and unix are considered two different words when spell checking.

47 New DITA CMS 4.0 features 47 Note: The Replace feature is case insensitive; for example, if you select unix and replace it with Unix, it will replace all occurrences of the word unix, no matter its casing (e.g., Unix, unix, UNIX will be replaced with Unix). Language The Spellchecker works with any language configured for your deployment. To determine the dictionary used to spell check a document, the Spellchecker uses the value of the xml:language attribute in the root element of the map or topic. For example, consider the following topic: <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE concept PUBLIC "-//IXIA//DTD IXIA DITA Composite//EN" "IxiaDitabase.dtd"> <concept id="lar " xml:lang="en-us"> <title ixia_locid="1">troubleshooting the Tomcat installation</title>... The en-us dictionary will be used to spell check that document, and custom words will be added to the en-us custom dictionary. Skipped elements By default, the spell checker skips the contents specified in the <codeblock> and <codeph> elements. This is configurable per deployment, so check with your CMS Administrator for the list of skipped elements. Check the spelling of topics and maps This procedure describes how to spell check topics and maps. From the Spellchecker view you can: Open the document that contains the misspelled word and fix the error Add a word to a global custom dictionary Choose from a list of suggestions and fix all occurrences of the misspelled word in the selected document To check the spelling of a topic or map: 1. Right-click the topic(s) or map you want to check and select Spellcheck. If you select a map or the parent topic of a sub-tree, all of its child topics are checked as well. The Spellchecker view is displayed, listing misspelled words, if any.

48 48 What's New In DITA CMS To fix a spelling mistake: a) If the containing document is unlocked, right-click the document in the Spellchecker view and select Lock. The containing document is locked. b) Double-click the misspelled word. The containing document opens in the XML editor. c) Fix the spelling in the document. 3. To replace all occurrences of a misspelled word in the selected document with a suggestion: a) If the containing document is unlocked, right-click the document in the Spellchecker view and select Lock. b) Select the misspelled word in the Spellchecker view. c) In the Suggestions area, select the correct word. d) Click Change All. A message similar to the following is displayed: To replace all occurrences of the word in the document, click OK. Note: You will not be able to undo these changes using the Undo feature of your XML editor. If you clicked OK but need to revert your changes, you can use the DITA CMS Replace with Server Revision feature. 4. To add a word to the custom dictionary: a) Select the word to add in the Spellchecker view. b) Click Add to Dictionary. c) Click OK to confirm. The word is added to the custom dictionary, which is shared by all users in your deployment. Note: If you get a message similar to the following:

49 New DITA CMS 4.0 features 49 Then a custom dictionary does not exist for your deployment. Ask your CMS Administrator to create the custom dictionary by adding a word to it. Open the output folder automatically when using Generate Output You can configure the Generate Output command to automatically open the output folder and unzip the generated output when the transformation is completed. The following diagram shows the new Generate Output dialog box for DITA CMS 4.0: The dialog now contains the following two options: Open output folder when done: When you select this option, the Output Generator opens the folder that contains the generated output when the transformation is completed. Unzip when done: When you select this option, the Output Generator unzips the generated output in the output folder, in a sub-folder with the file name. For example, if the output directory is called Outputs and the generated output is saved in a file called Web_Author_Installation_Guide.Dita2Pdf.English.zip, the file is unzipped in the Outputs\Web_Author_Installation_Guide.Dita2Pdf.English directory.

50 50 What's New In DITA CMS 4.0 If you select both the Open output folder when done and Unzip when done options, the Output Generator opens the folder that contains the unzipped files. Preview a map You can view the contents of a map using the Show Preview command. When you use the Show Preview command, the DITA CMS lists the objects in the map, as shown below: Note: You need Output Generator Version 4.0 to preview a map. To view the contents of a map: 1. Open the Preview view. 2. Use Search to find the map to preview. 3. Right-click the map and select Show Preview. The preview of the map is displayed.

51 New DITA CMS 4.0 features 51 Minor enhancements This section lists minor enhancements to the DITA CMS. 1013:You can now specify the linking attribute from the right-click menu in the Reltable Editor. 1266: You can now apply a label when creating and cloning DITA CMS objects (maps, topics, images, and resources). 1450: You can now configure the title of the sent by the Scheduler. 1478: A warning is now displayed when trying to delete a search that is shared by multiple users. 1479: When you clicked the Set Conditions button in the DITA map view and the map was not locked, no error message was displayed. The DITA CMS now displays a warning indicating that the user should lock the map. 1488: In previous releases, when trying to perform a search and replace operation on files that could not be locked, the DITA CMS skipped the files without warning users. A warning is now displayed. 1493: The notification sent by the Scheduler now includes the latest release comment for the reviewed object. 1515: In the Search Results view, you can now jump to a specific page number. 1545: In previous releases, you could not sort the results in views based on columns that included multiple entries (such as Labels, Versions, etc.).you can now sort results alphabetically by clicking any column header. 1549: The Search for panel of the Search view now includes a Clear button. Terminology change The following terminology has changed in this release of the DITA CMS: The term Content Store is now used to represent a docbase. The Postmaster is now called the Scheduler.

52 52 What's New In DITA CMS 4.0

53 New DITA CMS 4.0 Administration 2features New DITA CMS 4.0 Administration features Topics: Configure Search view options Configure the Document Types panel Add links to a bug tracking system in the release comments Configuring jobs in the Scheduler Configure the elements skipped during spell check Encrypting passwords in text files This section describes the new features for CMS Administrators. For more information about these features, see the Administrator's References on the DITA CMS 4.0 documentation page.

54 54 What's New In DITA CMS 4.0 Configure Search view options You can configure the options available in the Search for and Advanced Search panels of the Search view. The following table describes the types of searches that you can configure and the search panels to which they apply: Table 1: Search view options Search type Description Search for panel Applies to Advanced Search panel Index Search according to indexed criteria. Yes Yes Elements Search within a specific XML element. Yes Yes Attributes Search for XML elements having specific attribute values. Yes Yes Dates Search for documents created or modified on fixed or relative dates. No Yes They are shown in the following diagram: Figure 10: Advanced Search window

55 New DITA CMS 4.0 Administration features 55 The DITA CMS comes with a default set of indexes, elements, attributes, and dates that are available to your users.you can modify the advancedsearchindexes.xml file to add more search options by adding a new element according to the search type, as follows: Search type Index Element Date Attribute Element to add Add an <index> element to <indexes> Add an <element> element to <elements> Add a <date> element to <dates> Add an <attribute> element to <attributes> For example: <indexes> <index display="created By" name="createdby" type="property" listable="true" views="all"/> <index...>... </indexes> The following table describes the attributes for the <index>, <element>, <date>, and <attribute> elements. Table 2: Search element attributes Attribute display name Description Determines the label that appears in: The Name column in the Advanced Search panel. The Search in drop-down list in the Search for panel. Links the element with the corresponding index definition. Values Can be any sequence of characters. Must be the same string as is used in the index definition document (NAME attribute). type Indicates whether an index definition can be modified. Property indicates a system-created index. While you can change a property Applies to <index> and <date> elements. display label, you cannot modify its

56 56 What's New In DITA CMS 4.0 Attribute Description Values name or definition in the index definition document. Index indicates a user-created index, which means that you can modify its definition in the index definition document. listable Determines whether the Value field is presented to the user as a list. True values are presented as a selection list. The corresponding TEXTML index definition must be a <stringindex>. False values must be entered by the user. Note that only the indexes with listable="false" are displayed in the Search in drop-down list. attr Determines whether users can True searches within attribute values search inside non-standard for the specified string. You could, for attributes (such as version number, which contains spaces). example search for first and the search would return files with labels such as first release, first beta, and ladies first. False performs the standard index search. views Deprecated. To configure Search view options: 1. Open the TEXTML Administration view. 2. Connect to your server and Content Store. 3. Locate the advancedsearchindexes.xml file in the repository's /system/conf collection. 4. Check out advancedsearchindexes.xml and open it with a text editor. 5. To add or modify an Index search, locate the <indexes> element and add a new <index> element or modify an existing one, as necessary.

57 New DITA CMS 4.0 Administration features 57 The <index> element defines all the labels displayed under Name when users select an index type search. For example, to add the option to search the createdby index, enter: <index display="created By" name="createdby" type="property" listable="true"> 6. To add or modify an Elements search, locate the <elements> element and add a new <element> element or modify an existing one, as necessary. The <elements> element defines all the elements that are displayed under Name when users select an elements type search. There must be a corresponding <unit> element defined in the Content Store's index definition document. For example, to add the option to search for the <fig> element, enter: <element display="fig" name="fig"/> 7. To add or modify a Dates search, locate the <dates> element and add a new <date> element or modify an existing one, as necessary. Note: Date searches only apply to the Advanced Search panel. The <date> element defines all the date properties displayed under Name when a user sets up a date search. For example, to add the option to search the creation date of a document, enter: <date display="creation Date" name="creationdate" type="property"/> 8. To add or modify an Attributes search, locate the <attributes> element and add a new <attribute> element or modify an existing one, as necessary. The <attribute> element defines all the attributes displayed under Name when a user sets up a date search. For example, to add the option to search for the align attribute, enter: <attribute display="align" name="align"/> 9. Save, close, and check in the advancedsearchindexes.xml file. 10. Restart the DITA CMS.

58 58 What's New In DITA CMS 4.0 Configure the Document Types panel You can configure the contents of the Document Types panel in the Search View. In the default configuration, the Document Types panel looks as follows (when the Maps type is selected): The Document Types panel is configured in the equivalence.xml file. This file determines how DITA and custom objects are handled by the DITA CMS interface. Objects that are designated as equivalent to topics, for example, display the same right-click menu options and are searched in a similar manner. The following code shows the default configuration in the equivalence.xml file for the Maps document type: <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE equivalences PUBLIC "-//ixiasoft.com//cms//config//equivalence" "equivalence.dtd"> <equivalences> <equivalence type="map" standardsearch="true" groupname="maps"> <object type="map"/> <object type="bookmap" icon="/system/conf/icons/bookmap-icon.png"/> <object type="subjectscheme"/> </equivalence>... </equivalences> The following table describes the elements and attributes used to configure the Document Type panel: Table 3: Elements and attributes of the equivalence.xml file Element <equivalence> Description Defines a top-level document type in the Document Type panel (for example, Maps, Topics, etc.) It has the following attributes:

59 New DITA CMS 4.0 Administration features 59 Element Description Attribute type Description Type of the object.this must be a valid type (for example, map, topic, resource, etc.). Mandatory. standardsearch Indicates if this type is displayed in the Document Type panel. Valid values are true (type is displayed) and false (type is not displayed). This attribute is optional; if not specified, it defaults to true. groupname Label displayed in the Document Type panel. This attribute is optional; if not specified, it defaults to the value of the type attribute. All the <equivalence> objects with the same group name will be organized in the same drop-down list. For example, consider the following configuration: <equivalence type="project" standardsearch="true" groupname="others"> <object type="project"/> </equivalence> <equivalence type="snapshot" standardsearch="true" groupname="others"> <object type="snapshot"/> </equivalence> Both project and snapshot will appear in the Others drop-down list. <object> Defines the items in the document type's drop-down list. It has the following attributes: Attribute type Description Type of the object.this must be a valid type (for example, map, topic, resource, etc.). Mandatory.

60 60 What's New In DITA CMS 4.0 Element Description icon Specifies a link to the icon that should be used for this object in the DITA CMS view.the image must be stored in the Content Store. For example: <object type="bookmap" icon="/system/conf/icons/bookmap-icon.png"/> To configure the Document Types panel: 1. Open the TEXTML Administration view. 2. Connect to your server and Content Store. 3. Locate the equivalence.xml file in the repository's /system/conf collection. 4. Check out the file. 5. Open equivalence.xml with a text editor. 6. Make the necessary changes in the file. 7. Save, close, and check in the equivalence.xml file. Add links to a bug tracking system in the release comments You can configure the DITA CMS so that users can specify the number of the bug that they are fixing when they release a topic. To enable this feature, you specify the link to your bug tracking system in the DITA CMS textmlservercfg.properties configuration file. When users release a topic related to a bug fix, they can specify the bug number in the Tracker link field of the Release window, as shown below:

61 New DITA CMS 4.0 Administration features 61 When the user releases the topic, the link to the bug is available in the Revision History: Clicking on the bug number opens the bug in a browser. To configure the DITA CMS to add links to a bug tracking system in the release comments: 1. Open the TEXTML Administration view. 2. Connect to your server and Content Store. 3. Locate the textmlservercfg.properties file in the repository's /system/conf collection. 4. Check out textmlservercfg.properties and open it with a text editor. 5. Locate the following line at the end of the file: #Don't remove this line. It is required for proper parsing of the file

62 62 What's New In DITA CMS Before this line, add the following lines: #Uncomment the following line if you want to enable support for tracker web linking tracker.url=<url_of_tracking_system>%tracker.id% Where <URL_of_Tracking_system> is the URL of the tracking system and %TRACKER.ID% represents the location of the bug ID. For example, consider the following URL for Bugzilla: This URL would be configured as follows in the textmlservercfg.properties file: tracker.url= For the following JIRA URL: Configure it as follows in the textmlservercfg.properties file: tracker.url= 7. Save, close, and check in the textmlservercfg.properties file. 8. Restart the DITA CMS. Configuring jobs in the Scheduler To schedule jobs in the Scheduler, you can now use a UNIX crontab-like pattern, which provides more flexibility. In previous releases of the DITA CMS, you used the <schedule> element to specify the hour at which to run the job. For example, the following job was configured to run at 4 a.m. every day: <job useclass="com.ixiasoft.cms.plugins.reviewreport"> <textml url="hostname" version="4" port="2500" docbase="docbase"> <user domain="ixiasoft" username="testuser" password="password"/> </textml> <smtp url="smtp.ixiasoft.local" port="25" ="postmaster-noreply@ixiasoft.com"/> <schedule> <when>4</when><!-- The job will run at 4 am --> </schedule> </job> You can now use a UNIX crontab-like pattern to configure when the job will run. A crontab-like pattern allows you to schedule jobs to run periodically at fixed times, dates, or intervals.

63 New DITA CMS 4.0 Administration features 63 For example, you can now specify that a job must be run on Mondays and Thursdays, or every day at 8 a.m. and 6 p.m., etc. The following code indicates that a job should run at 6:15 every day: <when>15 6 * * *<when> For more information, see the DITA CMS System Administrator's Guide. Configure the elements skipped during spell check You can configure the spell checker feature so that specific elements are skipped. This can be very useful with elements such as <codeblock> and <codeph>, which often contain code and commands that you do not want to spell check. By default, the DITA CMS is configured to skip the <codeblock> and <codeph> elements, but you can configure it as appropriate for your deployment. For example, you could configure the spell checker so that <filepath> elements are skipped. The elements to skip during spell check are defined in the dictionaryexclusions.xml configuration file. To configure the elements skipped during spell check: 1. Open the TEXTML Administration view. 2. Connect to your server and Content Store. 3. Locate the dictionaryexclusions.xml file in the repository's /system/conf collection. 4. Check out dictionaryexclusions.xml and open it with a text editor. The default file looks as follows: <?xml version="1.0" encoding="utf-8"?> <!DOCTYPE dictionaryexclusions PUBLIC "-//ixiasoft.com//cms//config//dictionaryexclusion" "dictionaryexclusion.dtd"> <!-- Offers the possibility of excluding elements from the IXIASOFT spell checker --> <dictionaryexclusions> <!-- The elements matching the following classes will be excluded from spellchecking --> <!-- Please consult the DITA OASIS specification or your DTD specialization to determine class attributes --> <exclude _class="pr-d/codeblock"/> <exclude _class="pr-d/codeph"/> </dictionaryexclusions> Elements to skip are specified using class attributes. See the DITA OASIS specification or your DTD specialization to determine the class attributes for the elements you want to exclude.

64 64 What's New In DITA CMS For each element to skip, add an <exclude> element before the closing </dictionaryexclusions> element. For example, to skip the <filepath> element, add the following: <exclude _class="sw-d/filepath"/> 6. Save, close, and check in the dictionaryexclusions.xml file. 7. Synchronize the DITA CMS configuration. Encrypting passwords in text files You can now encrypt passwords in the different DITA CMS configuration files. In previous releases of the DITA CMS, the passwords had to be specified in plain text. The DITA CMS now provides an encrypting tool for better security. This tool, called encrypt, takes the password as input and returns an encrypted string that you insert in the configuration file. This tool ensures that users can run the different DITA CMS components without having to know passwords. The encrypt tool is available for all DITA CMS components that include a configuration file requiring a password. These include: Output Generator: %OutputGenDir%/bin Scheduler: %SchedulerDir%/bin Web Author: %TomcatDir%/conf/webauthor/ CMS Application Server: %GlassFishDir%/domains/cmsappserver/config Web Collaborative Reviewer: %WcrDir%/conf Encrypt a password You can encrypt a password before specifying it in a DITA CMS configuration file. To encrypt a password, you use the encrypt utility, available in the following locations: Output Generator: %OutputGenDir%/bin Scheduler: %SchedulerDir%/bin Web Author: %TomcatDir%/conf/webauthor/ CMS Application Server: %GlassFishDir%/domains/cmsappserver/config Web Collaborative Reviewer: %WcrDir%/conf To encrypt a password:

65 New DITA CMS 4.0 Administration features Run the command as follows: On Windows: 1. Open a command prompt and go to the directory where the encrypt tool is located. 2. Enter the following command: encrypt <password> Where <password> is the password that you want to encrypt. For example, to encrypt the password HelloWorld2014, enter: encrypt HelloWorld2014 On Linux: 1. Go to the directory where the encrypt tool is located. 2. Enter the following command:./encrypt.sh <password> Where <password> is the password that you want to encrypt. For example, to encrypt the password HelloWorld2014, enter:./encrypt.sh HelloWorld2014 Note: If you get an error message indicating that Java could not be found, set the JAVA_HOME environment variable to point to the JRE installation and try again. 2. The tool returns the encrypted password, as follows: C:\ixiasoft\OutputGenerators\OutputGen_40_Prod\bin>encrypt HelloWorld2014 IXIASOFT Technologies inc. ****************************************** Encrypting [HelloWorld2014] Crypted using TripleDES [#!;di0w5ubkd08ujimaunnullbwu2t/5mlvnarnutgredi=] Decrypted using TripleDES [HelloWorld2014] ****************************************** The encrypted password is provided on the "Crypted using TripleDES" line, inside the brackets [], as shown in bold above. 3. In the configuration file, enter the encrypted string without specifying the brackets. For example, in the outputgenerator.xml file, enter the password as follows: <outputgenerator> <textml address="localhost" port="2500" forceupdate="false" version="4">

66 66 What's New In DITA CMS 4.0 <docbase>update36_test</docbase> <user domain="ixiasoft" name="outgen" password="#!;di0w5ubkd08ujimaunnullbwu2t/5mlvnarnutgredi="/> <timeout>500000</timeout> </textml> </outputgenerator>

67 3New documentation New documentation Topics: Working with SVG files in Visio Keep the topic.fo file This section includes new topics added to the DITA CMS documentation about existing features.

68 68 What's New In DITA CMS 4.0 Working with SVG files in Visio For testing, have handy a Visio file and its equivalent SVG file for import. The problem: Visio cannot edit SVG files within the CMS. Rather than simply overwriting the current file, Visio requires a Save As, which is not intuitive within the CMS. The solution: Use the file folder structure of the local workspace to make the Save As approach feasible. 1. CMS Administrator: In the TEXTML Admin view, edit the mimetypes.xml file. a) Change the following code as shown: <mimetype type="application/vnd.ms-visio.drawing"> <extensions> <defaultextension>vdx</defaultextension> <extension>vsdx</extension> </extensions> </mimetype> to <mimetype type="application/vnd.ms-visio.drawing"> <extensions> <defaultextension>vsdx</defaultextension> </extensions> </mimetype> b) Ensure that all users synchronize their system configuration. The following steps are for end users. 2. Edit your CMS file associations so that the.vsd extension uses Microsoft Visio Drawing as the default editor and the.vsdx extension uses Microsoft Visio Document as the default editor. For instructions on setting file associations, refer to the DITA CMS User Guide online. 3. Ensure your operating system's file associations are set to open.vsd/.vsdx files with Visio. 4. In the CMS, create a new image object (DITA CMS > Create Image). The Show/Edit Image dialog appears:

69 New documentation Enter a title and any other information you want, such as a description, image type, or language. 6. In the Images panel, select the Source format and click Import. 7. Import the Visio file you have handy. If you see a message about the file type not being visible in the CMS, you can disregard it. It only indicates that the CMS will not be able to display a preview or other information about the Visio file. 8. In the Images panel, select the HiRes format and click Import. 9. Import the SVG file you have handy. When you have imported both files, the Images panel should resemble this example: 10. Select the HiRes format and click Set as Default.