FAQ for DITA CMS Technical Writers

Transcription

1 FAQ for DITA CMS Technical Writers / IXIASOFT / Copyright 2018 IXIASOFT Technologies. All rights reserved. Last revised: May 02, 2018

2 2 FAQ for DITA CMS Technical Writers Table of contents DITA CMS troubleshooting How can I get rid of unnecessary menus cluttering my perspective? 5 Why am I seeing a "Status is too low to change status" error when I try to change the status of an object? 6 How do I locate a topic in a map? 7 Why doesn't my saved search provide the expected results? 8 Why does DITA CMS show a Synchronize Thumbnails error? 8 Why am I seeing an "Invalid XML character" error when importing a topic? 9 How can I see which conditional attributes are used within topics in my map? 9 Why is a table inserted into my referable-content topic as a choicetable? 10 Where can I find the version number for the DITA CMS components?11 How can I get all the Eclipse installation and configuration details for the DITA CMS? 11 Where are my preferences stored? 13 Why don't my locked documents appear when working offline? 14 Why is the font in the DITA CMS Eclipse Client so small when using a high resolution monitor? 15 How do I stop unnecessary ISO Schematron warnings from appearing? 16

3 Table of contents 3 DITA CMS performance troubleshooting How do I delete a workspace? 19 Why is my Eclipse workspace unstable and how can I fix it? 20 How can I improve DITA CMS performance? 23 Why does a.metadata error appear when trying to launch the DITA CMS Eclipse Client? 24 Why am I seeing an "JVM terminated. Exit code = -1" error when I try to start EclipseEclipse and how can I fix it? 25 How can I prevent Java heap space errors when performing large client actions like publishing, localizing, and DRM cloning? 26 How do I get a log file for debugging the DITA CMS? 27 Editing topics troubleshooting How can I configure default preferences for oxygen XML editor? 30 Why can't I view my topic in oxygen Author mode? 31 How do I install or update oxygen XML Editor or oxygen XML Author in the DITA CMS? 32 Why is my XML file not opening in the default editor? 33 Why is nothing displayed in the Help pane or in the Preview view? 34 How can I use a hazard symbol in a topic? 36 How can I link to a PDF file? 36 How can I add a link to another element within the same topic? 37 How can I add a link to an element in another topic? 38 Citrix troubleshooting

4 4 FAQ for DITA CMS Technical Writers Why can't I edit a file that I previously locked from my Citrix machine? 39 Why is the Output Generator failing to generate output in a Citrix environment? 40 Why don't I see any directories when trying to export an image from my Citrix machine? 41 Localization troubleshooting Why are images included in the image localization kit when they don't require translation? 42 What are some best practices for sequential localization? 42 Dynamic Release Management troubleshooting How can I clear the "Does not exist in target version" error when trying to create a new DRM instance of a map? 45 How can I remove a topic added to the wrong DRM version? 45 How can I move a map to another version? 46

5 DITA CMS troubleshooting 5 DITA CMS troubleshooting This section contains FAQs for troubleshooting the DITA CMS Eclipse Client. How can I get rid of unnecessary menus cluttering my perspective? You can customize the perspective to improve its usability. In the main menu, click Window and click Customize Perspective. The perspective contains many menus and buttons that are never used. It impedes the usability of the interface. The standard DITA CMS perspective contains menus offered by the Eclipse IDE that may be of little or no use. This can make the Eclipse interface seem overwhelming with too many choices of menus and toolbars many of which have nothing to do with the tasks you want to accomplish. Simplify the perspective. You can create a customized perspective which not only allows you to hide these unnecessary menus from the interface, but can also allow you to choose which toolbars, menus, command groups, and shortcuts you want to show or hide. Customize your perspective To customize your perspective: 1. From the menu bar, select Window > Customize Perspective. 2. Tool Bar Visibility: Choose to show or hide a tool bar or its available buttons. Click the tab containing the menu, button, command group, or shortcut that you want to show or hide: Menu Visibility: Choose to show or hide a menu or its available items. Command Group Availability: Choose to show or hide a command group or its available menu or toolbar items. Shortcuts: Choose to show or hide a shortcut or group of related shortcuts from a submenu. 3. Click the tab containing the menu, button, command group, or shortcut that you want to showclick the arrow next to the element to display what it contains. Select the checkbox to show the item or click to clear the checkbox to hide it.

6 6 FAQ for DITA CMS Technical Writers 4. Click OK when you are done. WARNING: Do NOT remove the Window menu. This is the entry point to the Customize Perspective dialog. Save your changes as a new Perspective To save your customized perspective: 1. From the menu bar, select Window > Save Perspective As. 2. In the Name field, type an appropriate name for your perspective. 3. Click OK. Why am I seeing a "Status is too low to change status" error when I try to change the status of an object? The Status is too low to change status error appears when you are attempting to move a parent object to a higher status in the workflow than its child objects. A "Status is too low to change status" error appears when you click Change Status and attempt to select a higher status for the object. For example, you try to change the status of a topic from Review to Done. The DITA CMS workflow dictates that the parent object must be in an equal or lower state than its children. Therefore, if an object such as a topic contains child objects such as an image or conref which are at a lower state than the parent object, the parent cannot be changed to a higher state. You will also see this in situations when you have a "conref loop" or circular reference between topics; for example, topic A has a conref of a paragraph from topic B and topic B has a conref of a note from topic A. Although this is a valid situation in DITA, it is not supported in DITA CMS because the workflow cannot identify which is the parent since each topic is both parent and child of the other topic.

7 DITA CMS troubleshooting 7 To resolve the issue, move all the child objects to a higher state before changing the state of the parent. For example, the image must be in a Done state before its parent topic can move to a Done state. In the case of the "conref loop", use referable-content topic type to hold the reusable content so the topics are no longer dependant on each other. How do I locate a topic in a map? You can use the Select In Map tool to expose the selected topic in the ditamap open in the DITA Map view. You have a topic open in the editor or selected in one of the views and you need to find its location in the ditamap open in the DITA Map view. Finding a topic in the ditamap by expanding each node in the DITA Map view is tedious and potentially time-consuming in the case of a large or complex map. You can use the Select In Map tool ( ditamap open in the DITA Map view. ) to expose the selected topic if it is contained in the To select the topic in the map: 1. Open the ditamap in the DITA Map view. 2. Do one of the following: Right-click the topic in one of the views and click Select In Map. Open the topic in the editor and click. If the map contains the topic, the topic will be exposed and selected in the DITA Map view. If the topic does not appear in the map, no change will in occur in the DITA Map view.

8 8 FAQ for DITA CMS Technical Writers Why doesn't my saved search provide the expected results? Changes to indexes that are part of saved search queries can cause unexpected search results. A saved search query doesn't load all saved values and the resulting search results are inaccurate. A search index has been removed from the indexdefinitions file by the DITA CMS System Administrator. This search index was part of a saved search query. When a user loads their saved query, the missing parameters are not loaded in the search panels. There is no warning or error message provided. When search indexes are removed, users need to review their saved queries. If the deleted index is part of their query, save a new query. Why does DITA CMS show a Synchronize Thumbnails error? Users with laptops who switch networks frequently can receive this error. DITA CMS shows a Synchronize Thumbnails has encountered a problem error. This error can occur for users with laptops who change networks frequently. If a user needs to travel or switch between a WI-FI and network cable connection, ensure they close DITA CMS, change location or network, and launch DITA CMS again.

9 DITA CMS troubleshooting 9 Why am I seeing an "Invalid XML character" error when importing a topic? Some XML characters are invalid and cannot be imported into DITA CMS. I get an "Invalid XML character' error when trying to import a topic that has the following text: When you open a note that has special Unicode characters (such as  or ) in the note accumulator, an error is displayed. There are certain characters that are not valid in XML. Escape or remove the character from topic prior to importing it into the DITA CMS. How can I see which conditional attributes are used within topics in my map? You can use the Search Results view to see the conditions. In the past, the Generate Output dialog box used to show a list of all conditions used within a map. With the use of ditavals, this functionality no longer exists. I do not know which conditions are used in the map so I do not know which ditaval I should select. 1. In the Search Results view, enable the Product, Platform, and Audience columns. 2. Open the map in DITA Map view. 3. In the Search view, in the Document Types panel, select Topics. 4. In the Limit to panel, under Dependencies of, select DITA Map view. 5. In the Advanced Search panel, select the following values:

10 10 FAQ for DITA CMS Technical Writers 6. Click Search. Note: Make sure to use the OR operator for the second and third values. Why is a table inserted into my referable-content topic as a choicetable? This is the expected behavior based on the model of the <rcbody> element. When inserting a table into a referable-content topic, the table is inserted as a choicetable instead of a regular table. This is the expected behavior based on the model of the <rcbody> element, which is defined to include "ANY" element. When you insert a table, oxygen looks at the context and provides the appropriate dialog: Insert Choice Table or Insert Table. A choicetable has a very specific context and does not normally overlap with the table/simpletable context. However, in the case of a referable-content topic, choicetable does overlap with table/simpletable. In this case, oxygen presents the first qualifying dialog available, Insert Choice Table. Add a table to your referable-content topic template. If users don't need a table in the referable-content topic that they're creating, they can delete it.

11 DITA CMS troubleshooting 11 Where can I find the version number for the DITA CMS components? You can find the version number for several different components of DITA CMS. I need to find out which version of DITA CMS and its components we are using. I do not know where to find the version information. To find the DITA CMS and oxygen version: 1. In DITA CMS Eclipse Client click Help > About Eclipse SDK. 2. Click Installation Details. 3. Click the Plug-ins tab. 4. Click on the Provider column heading twice to reverse sort the entries by Provider. 5. The DITA CMS plugin versions are listed beside the entry for IXIASOFT Technologies Inc and the oxygen version is listed beside the entry for Syncro Soft SRL. To find the DITA CMS Web version: 1. The DITA CMS Web login page shows the version number at the bottom of the page. How can I get all the Eclipse installation and configuration details for the DITA CMS? All the installation and configuration details are available in the Eclipse SDK Installation Details window. You need to provide IXIASOFT Support with details about how your Eclipse is installed and configured so they can assist you in resolving an issue. You may not remember all the information being requested.

12 12 FAQ for DITA CMS Technical Writers The Eclipse SDK Installation Details window contains the information required and provides a means for extracting that information into a file. Once the information is saved in a file, it can easily be sent and searched. To create a file of the installation details: 1. In the main menu of your Eclipse DITA CMS Eclipse Client, click Help > About Eclipse SDK 2. Click Installation Details. 3. Click the Configuration tab. 4. Click Copy to Clipboard.

13 DITA CMS troubleshooting Open a text editor such as Notepad and paste the configuration information into a new document. 6. Save the file. 7. Send the file to IXIASOFT Support. Where are my preferences stored? You can save a copy of your Eclipse preferences. I would like to export my Eclipse preferences before performing a DITA CMS upgrade or switching to a new computer. I cannot locate where my preferences are stored.

14 14 FAQ for DITA CMS Technical Writers The preferences are stored in various locations depending on the plugin: Preference Perspective layout The default export folder oxygen license key oxygen preferences such as tags view, Show profiling attributes, and track changes always on. Location \workspace\.metadata\.plugins\org.eclipse.e4.workbench\workbench.xmi \workspace\.metadata\.plugins\org.eclipse.core.runtime\.settings\com.ixiasoft.eclipse.dita.prefs %APPDATA%\com.oxygenxml.author\license.xml. For example, C:\Users\janedoe\AppData\Roaming\com.oxygenxml.author 1. Click Window > Preferences > oxygen XML Author. 2. Click Export Global Options. Why don't my locked documents appear when working offline? Before going offline make sure the documents appear in the Offline perspective. When trying to work offline, my documents that are locked don't appear in the Offline perspective. The documents need to be synchronized to the Offline perspective before going offline. Before going offline, perform the following:

15 DITA CMS troubleshooting Lock the documents you want to edit. 2. Open the Offline perspective to make sure you see the locked documents. If the documents do not appear: a. Open the DITA perspective. b. Release the topics. c. Lock the topics again. Make sure the Keep Locked checkbox is cleared. d. In the Offline perspective, click the Refresh icon. Why is the font in the DITA CMS Eclipse Client so small when using a high resolution monitor? You can add a registry key to fix the resolution issue. When using a high resolution monitor, the fonts used in the DITA CMS Eclipse Client are very small and hard to read. When Eclipse loads, Windows asks if the application is High DPI aware and Eclipse answers yes. Add a new entry to a Windows registry: 1. Close the DITA CMS Eclipse Client. 2. In the Windows search box, type regedit. 3. Press Enter. 4. In the Windows registry, navigate to HKEY_LOCAL_MACHINE > SOFTWARE > Microsoft > Windows > CurrentVersion. 5. Right-click SideBySide. 6. Click NEW > DWORD (32 bit) Value. 7. Type PreferExternalManifest. 8. Press Enter. 9. Right-click PreferExternalManifest. Click Modify. 10. In the Value field, type 1.

16 16 FAQ for DITA CMS Technical Writers 11. In the Base section, select Decimal. 12. Click OK. 13. Download the manifest.txt file to the root folder of your DITA CMS Eclipse Client installation. 14. Rename the file to eclipse.exe.manifest. 15. Start the DITA CMS Eclipse Client. How do I stop unnecessary ISO Schematron warnings from appearing? Schematron schemas are a set of business rules used to validate content. If validation using Schematron schemas is not required, they can be disabled in Window > Preferences for the oxygen editor. Many ISO Schematron warnings are displayed in the DITA CMS. The oxygen editor supports validation against ISO Schematron schemas, which validate XML documents using Schematron schemas, XML Schemas, or Relax NG schemas that contain embedded Schematron rules. These validation scenarios are run against the topics open in the XML editor and may result in a list of of warnings being displayed. The validation scenario called ${framework}/resources/dita-1.2-for-xslt2-other.sch adds Schematron checks that are performed for manual validation and are triggered every time a document is saved. This validation scenario contains checks that are related to specification and are not mandatory so it can be disabled.

17 DITA CMS troubleshooting 17 If validation using Schematron schemas is not required, you can disable Schematron validation in the oxygen editor. To disable Schematron validation: 1. Open the DITA CMS EclipseEclipse Client. 2. In the main menu, click Window > Preferences. 3. The next step depends on the editor you are using: In oxygen Author, expand Author and select Document Type Association. In oxygen Editor, expand Oxygen XML Editor and select Document Type Association. The following dialog opens: 4. Click DITA and click Edit. 5. Click the Validation tab. Note: The Validation tab contains a DITA validation scenario that can be edited. 6. Click DITA in the Scenario pane and click the Edit icon (the small wrench icon just above the OK button). For example:

18 18 FAQ for DITA CMS Technical Writers 7. Select the ${framework}/resources/dita-1.2-for-xslt2-other.sch scenario and click Remove button. 8. Click OK.

19 DITA CMS performance troubleshooting 19 DITA CMS performance troubleshooting This section contains FAQs for troubleshooting DITA CMS performance issues. How do I delete a workspace? The workspace can be deleted by deleting the workspace folder; however, before deleting it you should release all the topics locked by you and possibly export your preferences from the existing workspace. The DITA CMS Eclipse Client repeatedly becomes unresponsive or the plugins stop working reliably so you suspect your workspace is unstable. Over time an Eclipse workspace may become unstable as plugins are added, upgraded, or removed. This instability can cause plugins to malfunction such as causing searches or autocomplete to fail. To delete the workspace: 1. Perform a search to find all the topics locked by you. Use Release or Replace With Server Version to update the Content Store with any changes that you want to keep. 2. Find the location of your workspace. a. Open the DITA CMS Eclipse Client associated to the workspace that you want to delete. b. In the main menu, click Help > About Eclipse SDK. c. Click Installation Details. d. Click the Configuration tab. e. Click Copy to Clipboard. f. Paste the content into a text editor like Notepad so you can search it. g. Search for osgi.instance.area to find the path to your workspace. For example: osgi.instance.area=file:/c:/users/jsmith/workspaces/yourworkspace 3. Close DITA CMS. 4. Navigate to the location and delete the workspace folder.

20 20 FAQ for DITA CMS Technical Writers Why is my Eclipse workspace unstable and how can I fix it? The Eclipse workspace may become unstable over time and must be cleaned or replaced. The DITA CMS Eclipse Client repeatedly becomes unresponsive or the plugins stop working reliably. Over time an Eclipse workspace may become unstable as plugins are added, upgraded, or removed. This instability can cause plugins to malfunction such as causing searches or autocomplete to fail. You can try the following procedures one at a time and test in between each one to check if the problem is resolved: 1. Clean the Eclipse caches 2. Create a new workspace 3. Reinstall Eclipse Clean the Eclipse caches Using the -clean argument forces Eclipse to reinitialize the caches, which removes all cached data used by the OSGi framework and Eclipse runtime. This should restore workspace stability. To use the -clean argument, perform one of the following procedures: Method Edit the eclipse.ini file Procedure 1. Open the eclipse.ini file located in the Eclipse installation directory. For example, in C:\eclipses\eclipse-SDK win32-x86_ Add -clean to the end of the first line in the file. 3. Save the file. 4. Restart Eclipse. 5. Delete -clean from the file. 6. Save the file.

21 DITA CMS performance troubleshooting 21 Method Procedure For example: -clean -startup plugins/org.eclipse.equinox.launcher_1.3.0.v jar --launcher.library plugins/org.eclipse.equinox.launcher.win32.win32.x86_64_ v showsplash org.eclipse.platform --launcher.xxmaxpermsize 256m --launcher.defaultaction openfile --launcher.appendvmargs -vmargs -Xms256m -Xmx1024m -Dixia.level=DEBUG -Dsun.java2d.d3d=false -Dosgi.requiredJavaVersion=1.6 -Dosgi.bundlefile.limit=1000 -Djava.security.krb5.conf=krb5.ini -Djava.security.auth.login.config=login.conf -Ddita.cms.mode=STD Edit the Eclipse shortcut 1. Right-click the DITA CMS Eclipse shortcut. 2. Click Properties. 3. In the Target box, add -clean to the end of the target statement. For example, C:\eclipses\eclipse-SDK win32-x86_64-test-4.2\eclipse.exe -clean 4. Click OK. 5. Restart Eclipse. 6. Delete -clean from the target statement. Create a batch or shell script Create a batch or shell script that calls the Eclipse executable with the -clean argument. Create a new workspace If the -clean argument did not resolve the issue, then you need to create a new workspace and import your preferences and projects into it. To create a new workspace: 1. Export your preferences from the existing workspace:

22 22 FAQ for DITA CMS Technical Writers a. Open the DITA CMS Eclipse Client associated to the workspace that is unstable. b. In the main menu, click File > Export c. In the Export window, click General > Preferences. d. Click Next. e. Select Export all. f. In the To preference file box, type the path and file name where you want to save your preferences file or click Browse to choose a location. g. Click Finish. 2. Create a new workspace: a. In the main menu, click File > Switch workspace > Other. b. In the Workspace box, type the path to your new workspace or click Browse to choose a location. The Eclipse Client will restart with the new workspace associated to it. 3. Import your preferences: a. In the main menu, click File > Import. b. In the Import window, click General > Preferences. c. Click Next. d. In the From preference file box, type the path and file name where you saved your preferences file or click Browse to choose the location. e. Select Export all. f. Click Finish. Clean reinstall of Eclipse If creating a new workspace did not resolve the issue, then you need to reinstall Eclipse. A broken Eclipse installation is usually caused by using incompatible versions of plugins with the wrong base version of Eclipse. Do not delete the old installation until your new installation is sufficiently tested and you are confident in it. If you do not know how to reinstall Eclipse, please contact your DITA CMSDITA CMS Administrator.

23 DITA CMS performance troubleshooting 23 How can I improve DITA CMS performance? You can perform some troubleshooting to improve the performance of DITA CMS. DITA CMS has slow response times to operations such as right-clicking on a topic or working in DITA Map view. The DITA CMS Eclipse Client has slow response times for one or a few users. Since it is not an issue for all users using DITA CMS, the problem can be caused by some local settings. Here are some troubleshooting steps that you can perform: Action Clear the workspace Ensure there is no anti-virus software that scans the user's workspace Turn off image thumbnail sync Disable native hooks This will reduce the frequency that Eclipse tries to access the disk. This should improve Instructions 1. In DITA CMS, click Window > Preferences. 2. Expand DITA CMS. 3. Click General Behaviour. 4. Click Clear Workspace. The workspace and Eclipse installation folders must be excluded from the anti-virus scan. 1. In DITA CMS, click Window > Preferences. 2. Expand DITA CMS. 3. Click General Behaviour. 4. Clear the Synchronize Image Thumbnails checkbox. 5. In the Search Results view, click to turn off thumbnail display. 1. In DITA CMS Window > Preferences. 2. Expand General. 3. Click Workspace.

24 24 FAQ for DITA CMS Technical Writers Action performance if the network share containing the workspaces is slow to access. When this is enabled, the operating system lets Eclipse know when to do a refresh so it is always in listen mode. It is more efficient to use it for local workspaces. Instructions 4. Clear the Refresh using native hooks or polling checkbox. If the problem still occurs, contact IXIASOFT support and provide the following information: The eclipse.ini from the Eclipse installation folder Amount of RAM on the client computer If it is a local or a remote installation using Citrix or RDP Debug logs Why does a.metadata error appear when trying to launch the DITA CMS Eclipse Client? This can be resolved by removing some corrupted Eclipse files. When starting DITA CMS, an Eclipse dialog box appears saying An error has occurred. See the <workspace>/.metadata/.log file. The Eclipse workspace has been corrupted. 1. Close DITA CMS. 2. Delete the.metadata\.plugins\org.eclipse.e4.workbench\workbench.xmi file from the workspace. 3. Start DITA CMS. To prevent this issue, IXIASOFT recommends closing all topics open in the oxygen Editor before exiting Eclipse.

25 DITA CMS performance troubleshooting 25 Why am I seeing an "JVM terminated. Exit code = -1" error when I try to start EclipseEclipse and how can I fix it? Eclipse cannot get a continuous block of memory of the size specified by the -Xmx value, which prevents the DITA CMS from opening. When you try to start Eclipse, you receive an error message with JVM terminated. Exit code -1, as shown below: This error occurs when you run a 32-bit version of Eclipse on Windows, and Eclipse cannot get a continuous block of memory of the size specified by the -Xmx value in the eclipse.ini file. For the technical details about this issue, see:

26 26 FAQ for DITA CMS Technical Writers You can resolve the issue by following one of these solutions: Method Reduce the -Xmx value to a lower value Edit the Eclipse shortcut Procedure 1. Open the eclipse.ini file located in the Eclipse installation directory. For example, in C:\eclipses\eclipse-SDK win32-x86_ Reduce the value set for -Xmx. For example, if the value is set as -Xmx1024m, try setting it to -Xmx512m. 3. Save the file. 4. Restart Eclipse. 1. Right-click the DITA CMS Eclipse shortcut. 2. Click Properties. 3. In the Target box, add -vm c:\path\to\the\java\bin\javaw.exe to the target statement. For example, C:\eclipses\eclipse-SDK win32-x86_64-test-4.2\eclipse.exe -vm c:\path\to\the\java\bin\javaw.exe 4. Click OK. 5. Restart Eclipse. Use a 64-bit version of Eclipse If the host machine has a 64-bit operating system and you are not using XMAX, try installing the 64-bit version of Eclipse instead. How can I prevent Java heap space errors when performing large client actions like publishing, localizing, and DRM cloning? You can increase the amount of memory allocated to DITA CMS. When publishing, localizing, or DRM cloning a large map, a java.lang.outofmemoryerror: Java heap space error appears.

27 DITA CMS performance troubleshooting 27 The DITA CMS Eclipse Client is running out of memory. 1. Close DITA CMS. 2. In your Eclipse folder, edit the eclipse.ini file. 3. Increase the -Xmx1024m value to -Xmx2048m. 4. Try the localize, publish, or DRM clone operation again. 5. If it still fails, increase the value to either -Xmx3072m, -Xmx4096m, -Xmx5120m, or -Xmx6144m. We recommend trying the increase one value at a time to reserve as little memory as possible. Note: In order to increase the memory allocated, make sure that you have enough physical RAM installed on your computer. 6. After each failed attempt, the partially created content needs to be removed from DITA CMS. Contact IXIASOFT Support if you need assistance. How do I get a log file for debugging the DITA CMS? You need to launch the DITA CMS in debugging mode so you can obtain the log files. Once you start the DITA CMS in debugging mode, a log file called DITA_CMS.log will be created in your workspace folder. An issue is occurring in the DITA CMS and you want to review the log files so you can diagnose the problem. The DITA CMS is not configured to output the debug log file by default. You need to configure DITA CMS to launch in debugging mode so you can access the debug log file. Configuring debug mode on a local installation To launch the DITA CMS in debugging mode: 1. Right-click the shortcut for the DITA CMS and click Properties.

28 28 FAQ for DITA CMS Technical Writers 2. In the Target field, type -debug to the end of the Target statement. For example: 3. Click Apply. 4. Click OK. The next time that you start the DITA CMS, a log file called DITA_CMS.log will be created in your workspace folder. The file continues to log events until it hits its maximum size. Each time the maximum size is reached, the log events are saved into a file called DITA_CMS.log.[count] where [count] is replaced by a number in ascending order each time a new file is created. For example, the first time it reaches its maximum size, a new file called DITA_CMS.log.1. is created. When the maximum size is reached again, then another file is created, called DITA_CMS.log.2 and so on. Configuring debug mode on Citrix To launch the DITA CMS in debugging mode:

29 DITA CMS performance troubleshooting Open the Run dialog (click the Windows logo key + R). 2. In the Open box, type the path to your workspace. To find the path to your workspace, follow the FAQ called How can I get all the Eclipse installation and configuration details for the DITA CMS? on page 11 to obtain the configuration details of your DITA CMS Eclipse Client and copy the path following the -data parameter. 3. In that location create an empty text file and name it debug.txt. 4. Close your DITA CMS Eclipse Client. 5. Restart your DITA CMS Eclipse Client. 6. Click a key when the instruction press any key to continue appears in the command prompt window. Do not close the command prompt window. 7. When the DITA CMS opens, reproduce your issue so the information is captured in the log.

30 30 FAQ for DITA CMS Technical Writers Editing topics troubleshooting This section contains FAQs for troubleshooting when editing topics. How can I configure default preferences for oxygen XML editor? You can create a new default preferences file for the XML editor to import by default. You want to configure default preferences for oxygen Author or Editor. As with any other Eclipse plugin, the preferences for the oxygen XML Editor or Author plugins are stored in the Eclipse preferences store in the user's workspace. Each time you create a new workspace, you need to reimport your preferences into the workspace or reset your preferences manually. To have your preferences imported automatically, you need to export the desired preferences from an existing instance of the oxygen editor and use them to create a custom preferences file for the XML editor to import by default. To create the custom preferences file: 1. In the DITA CMS Eclipse Client, configure the oxygen preferences as desired in: Window > Preferences. 2. Click Apply to apply the changes. 3. Click oxygen XML Editor or oxygen XML Author. 4. Click Export Global Options to export the preferences. 5. Save the file in the %EclipseDir%/configuration folder. 6. Open the file in a text editor and clean the file so only your customized preferences remain (delete factory default preferences) and save the file. To configure oxygen to import a custom preferences file: 1. Locate the config.ini file in the %EclipseDir%/configuration folder and open it in a text editor.

31 Editing topics troubleshooting Set the com.oxygenxml.default.options property with the path to your custom preferences file by adding the following line to the file: com.oxygenxml.default.options=file\:{path to oxygen preferences file} 3. Save the file. For example, if your custom preferences file was called OxygenPreferences.xml and you saved it in the %EclipseDir%/configuration folder, then the property would be set as follows since it is in the same folder as the config.ini file: com.oxygenxml.default.options=file\:oxygenpreferences.xml Information from the oxygen website: Why can't I view my topic in oxygen Author mode? You can perform some troubleshooting to allow topics to open in oxygen Author mode. While using the oxygen XML Editor, you are unable to open your topic using Author mode or there are red CSS errors at the top of the topic. The oxygen XML Editor is not configured with the correct DTD or document type to validate and display the topic properly. Here are some troubleshooting steps that you can perform: Action Configure oxygen XML Editor with the XML catalog. Instructions 1. Click Window > Preferences > oxygen XML Author > XML > XML Catalog. 2. Verify the root catalog is set.

32 32 FAQ for DITA CMS Technical Writers Action Configure the Document Type Association. Note: This procedure will cause loss of preferences for the oxygen Editor. Instructions 1. Click Window > Preferences > oxygen XML Author > Document Type Association. 2. Make sure that there is a DITA document type listed and that it is checked. If the entry is missing, continue with the next step. 3. Close the DITA CMS Eclipse Client. 4. In the C:\Users\<username>\AppData\Roaming\com.oxygenxml.author directory, remove all content except license.xml. 5. Start the DITA CMS Eclipse Client. How do I install or update oxygen XML Editor or oxygen XML Author in the DITA CMS? You can install or update the XML editor from an update site or by using a dropin. You are missing the oxygen XML editor in the DITA CMS Eclipse Client or the XML editor is out of date. You need to install a new version of oxygen XML editor to work with the DITA CMS Eclipse Client. The oxygen XML Editor web site provides information on how to install or upgrade the Author or Editor editions in an Eclipse environment. You can install the software by using one of the following methods: Using an update site (requires write access to the installation folder of Eclipse) Using the dropins mechanism To install or upgrade:

33 Editing topics troubleshooting Open the appropriate oxygen XML Editor web site according to the edition of the XML editor you wish to use: For Author: For Editor: 2. Click the Eclipse tab. 3. Depending on the method you want to use, follow one of the following: To use an Update Site, follow the "Update Site Distribution" instructions. To use the Dropins method, follow the "Zip distribution" instructions. Note: Any customizations you made in oxygen such as changes to the CSS or Schematron will have to be re-implemented. For more information, contact your DITA CMS Administrator. Why is my XML file not opening in the default editor? Eclipse has been configured to open unlocked XML files in a read-only XML editor. When a topic is double-clicked is a view, it opens using another editor such as the Simple XML Editor rather than the XML editor that was installed as the intended default editor. The option Open unlocked XML files in a read-only XML editor is enabled in the Eclipse Preferences window. To open XML files in the default editor: 1. In the DITA CMS Eclipse Client, click Window > Preferences 2. In the left pane, click DITA CMS > General Behavior 3. Clear the Open unlocked document in Read-only Editor checkbox. 4. Click Apply. 5. Click OK.

34 34 FAQ for DITA CMS Technical Writers Why is nothing displayed in the Help pane or in the Preview view? The file association for HTML files in Window > Preferences is not configured properly. The Help, Preview view, or other windows are blank. Eclipse uses the default web browser set on your computer to display HTML pages. If the file association for HTML is not configured properly, the window will be blank. Configure the file association for HTML files in Window > Preferences. 1. Open the DITA CMS Eclipse Client. 2. In the main menu, click Window > Preferences. 3. In the left pane, expand General > Editors. 4. Click File Associations 5. In the File Types pane, click.html. 6. If the file association is correctly configured, Web Browser should appear in the Associated editors pane. If it does not, you must fix the association. To fix it: a. Click the Add button next to the Associated editors pane. b. Click Web Browser. c. Click OK. d. Click Web Browser in the Associated editors pane and click the Default button. e. Remove any other entries by clicking them and clicking Remove. f. Click OK. 7. Repeat the file association with.htm.for example:

35 8. Click OK. Editing topics troubleshooting 35

36 36 FAQ for DITA CMS Technical Writers How can I use a hazard symbol in a topic? You can insert an image to use as a hazard symbol. I am trying to add a hazard symbol in SVG format to a warning but it does not work. If I insert the image using the right-click Oxygen Editor > Insert Image menu option, I get an error releasing my topic. 1. Import the hazard image into the Content Store. 2. In the Search Results view, right-click the image. 3. Click Copy > Copy Reference. 4. In your locked topic where you want to insert the hazard symbol, insert an <image> element. 5. Right-click the <image> element. 6. Click Edit Attributes. 7. In the Name drop-down list, select href. 8. In the Value field, paste the copied reference value. How can I link to a PDF file? You can add a link to an external PDF file. I am trying to insert a cross-reference to a PDF file into a topic that will be post processed in the HTML environment. DITA CMS indicates that it cannot validate the href attribute because the file cannot be found.

37 Editing topics troubleshooting Set the format attribute to pdf and the scope attribute to external. For example: <xref href="sample.pdf" format="pdf" scope="external"/> How can I add a link to another element within the same topic? You can use the Link icon and manually edit the attributes to insert a link to another element. I want to link to another element within the same topic. I do not know how to link to another element. Perform the following to insert a link to another element. Note: This solution requires DITA 1.3 and a 2.x OT. 1. Add an ID to the element you want to link to. For example, <p ixia_locid="6" id="link-para"> 2. Place your cursor where you want to insert the link. 3. In the oxygen editor, click. 4. Click Cross Reference. 5. In the Location drop-down list, select the current topic. 6. In the Select the target element section, select the ID to link to. 7. Click Insert and close. The xref is inserted as <xref href="#hqm /link-para" format="dita"/> 8. Right-click the xref element. 9. Click Edit Attributes. 10. Edit the href attribute to remove the topic ID and replace it with a period: <xref href="#./link-para" format="dita"/>

38 38 FAQ for DITA CMS Technical Writers How can I add a link to an element in another topic? You can use the Link icon to insert a link to an element in another topic. I want to link to an element in another topic that is a standard topic type. For example, a concept, it is not a referable-content topic. I do not know how to link to an element in another topic. 1. Add an ID to the element that you want to link to. For example, <p ixia_locid="6" id="link-othertopic"> 2. In DITA Map view or the Search Results view, right-click the topic that has the element that you want to link to. 3. Click Copy > Copy ID. 4. Place your cursor where you want to insert the link. 5. In the oxygen editor, click. 6. Click Cross Reference. 7. Perform one of the following: For a standard deployment, in the Location field, delete the current topic ID and paste the copied topic ID. For a DRM deployment, in the Choose the target resource section, select the Key radio button. Click. Select the topic to link to. Click OK. 8. In the Select the target element section, select the ID to link to. 9. Click Insert and close.

39 Citrix troubleshooting 39 Citrix troubleshooting This section contains FAQs for troubleshooting Citrix deployments. Why can't I edit a file that I previously locked from my Citrix machine? In some environments the DITA CMS Eclipse Client must be configured with a logical_citrix_server_name to ensure the user's lock information is recognized. A user logs in to the DITA CMS Eclipse Client and locks a file. After working on it, the user closes the DITA CMS Eclipse Client and the remote session without releasing the file. When the user logs back in and tries to edit the locked file, it cannot be edited and is displayed in purple in the Search Results or Map view. The DITA CMS Eclipse Client uses the hostname and the username to create unique lock information.this may cause issues when there are multiple servers in a Citrix or Remote Desktop farm and a load balancer is used to dispatch user sessions. When multiple servers are in a farm, the hostname used for the lock information is the local server name. With a load balancer, once a session is running, the user will connect back to the same session on the same server. If the session is closed (the user logs off or closes the application), then there is no guarantee that the user will log back in to the same server. In this case, the lock information will be different, so the user will not be recognized as the person who did the initial lock. The files will be displayed in purple and the user will not be able to work on them. To solve this issue, add the following line to the eclipse.ini file, after the -vmargs line: -Dcom.ixiasoft.cms.override.hostname=<logical_citrix_server_name> where <logical_citrix_server_name> is the name given to all the servers in the farm; for example, "Citrix-Farm-Prod". The same name must be configured in each eclipse.ini file for each server in the farm.

40 40 FAQ for DITA CMS Technical Writers Why is the Output Generator failing to generate output in a Citrix environment? The monitor port in Window > Preferences > DITA CMS is not set correctly. When users attempt to generate output in a Citrix environment, the following error is displayed: Output Generator opens a single monitor port on the client machine for the server to send feedback information. In a Citrix environment, multiple users run on the same machine. When an output is triggered, only one port is opened; therefore, only one instance can use the monitor port and the others will receive the error message. For example: eclipse.buildid=m java.version=1.6.0_21 java.vendor=sun Microsystems Inc. BootLoader constants: OS=win32, ARCH=x86, WS=win32, NL=en_US Command-line arguments: -os win32 -ws win32 -arch x86 Error=The system could not produce the requested output. See the Error Log for details. java.lang.nullpointerexception at com.ixiasoft.dita.eclipse.actions.runnablewithprogress.rungeneratedoc$progressmonitorfactory. createmonitor(rungeneratedoc.java:276) at com.ixiasoft.dita.eclipse.actions.runnablewithprogress.rungeneratedoc. generatedocument(rungeneratedoc.java:213) at com.ixiasoft.dita.eclipse.actions.runnablewithprogress. RunGenerateDoc.run(RunGenerateDoc.java:96) at com.ixiasoft.dita.eclipse.jobs.generateoutputjob.doit(generateoutputjob.java:98) at com.ixiasoft.dita.eclipse.jobs.abstractactionjob.run(abstractactionjob.java:59) at org.eclipse.core.internal.jobs.worker.run(worker.java:55) All Citrix users should set their monitor port in the DITA CMS Preferences window to the number "0". 1. In the main DITA CMS menu, click Window > Preferences 2. In the left pane, click DITA CMS.

41 Citrix troubleshooting In the Monitor Port box, type Click Apply. 5. Click OK. Why don't I see any directories when trying to export an image from my Citrix machine? A missing Desktop folder can cause this issue. When trying to export an image, the dialog box does not show any file directories to select. There is a missing Desktop folder in the users profile. In the users Citrix environment, create a Desktop folder and restart the application.

42 42 FAQ for DITA CMS Technical Writers Localization troubleshooting This section contains FAQs for troubleshooting the localization process. Why are images included in the image localization kit when they don't require translation? You can manually remove the images that are not required. Images are included in the image localization kit even though they don't require translation. The image Needs Translation checkbox is not selected. The images were created with the Needs Translation checkbox selected and were later edited to clear this checkbox. Manually remove the images from the exported localization kit. What are some best practices for sequential localization? There are some recommended configuration settings and process steps for optimizing sequential localization. We use the sequential localization method and would like to know the recommended best practices. We would like to optimize our localization process. Here are some configuration best practices:

43 Localization troubleshooting 43 To only include files that require translation in the localization kit, edit the system/conf/localizationmanagers.xml file and make sure <config name="full.context">false</config> is set to false. The default is false. To enable auto-translation, edit the system/conf/localizationmanagers.xml file and make sure that in.context.exact.matches is set to true. The default is false. In the system/conf/localizationmanagers.xml file, the include.default.images setting adds the images as.image files in the localization kit. This is not to enable the translation of those images, but to provide context for the translators if their tool supports the preview of DITA topics. Here are some best practices for the localization process: Before performing a Localize, check the status of the files in the target languages. If the map exists in the target languages, it should be at Localization:done. This will ensure that all of the files of the source map are processed and that the translations are updated if they need to. If some files in the target languages are at still at Localization:in translation or Localization:review, they will not be updated, which will result in a partial update. If the content in the target language is not at Localization:done and you want push the new version of the map anyway, to reset the translations to the latest version, all files that are not at Localization:done should be changed back to Localization:tb translated. This can be done with the Retranslate from source feature. Warning: If changing the status back to Localization:tb translated manually, make sure that the topics are not set to Localization:done when cycling through the statuses. After performing a Localize and before preparing a kit, review any topics that are at Localization:review and change their status to Localization:done. If a topic is reused in multiple maps and is currently at Localization:in translation, it will not be included in subsequent localization kits, even if the content in English has changed. It can only be out for translation once. When the content is imported, it is automatically set to Localization:review. At this status, it is still possible to import new translations. The content should remain at this status as long as the translations are not final. If you need to make corrections to the translated content that has been imported, ask the translators to do the corrections and to send the corrected files. Then do the import again. Once you have imported the final translated content, review the topics and move all of the content to Localization:done. If this step is not performed, the next translation will not work correctly. Note:

44 44 FAQ for DITA CMS Technical Writers It is possible to set up the localization workflow to skip the Localization:review state. Contact IXIASOFT for assistance on how to do this.

45 Dynamic Release Management troubleshooting 45 Dynamic Release Management troubleshooting This section contains FAQs for troubleshooting Dynamic Release Management deployments. How can I clear the "Does not exist in target version" error when trying to create a new DRM instance of a map? You can use the DRM Add To feature to clear the error. When trying to create a new instance of a bookmap the following error appears: content/authoring/vxq ditamap The ID [htr xml] exists in current version [1.0] of library, but it does not exist in target version [2.0]. The product version or library version that you are trying to create the map in does not contain the referenced topics. In the example above, the topics exist in the 1.0 library but not the 2.0 library. Use the DRM Add To feature to add the topics to the 2.0 library. How can I remove a topic added to the wrong DRM version? You can update the topic reference to allow it to be deleted. A topic was added to the wrong DRM version using the Create New Instance feature. For example, one of our users selected version A of the topic and did a Create New Instance to version B instead of version C. The topic will not delete due to parent references.

46 46 FAQ for DITA CMS Technical Writers Perform the following to remove the topic from version B. Note: Steps 1-4 can be completed if the topic already exists in both versions B and C. 1. Right-click the source topic, for example the topic in version A. 2. Click Dynamic Release Management > Update to. Select version B. Note: This replaces the container reference in version B with version A of the topic. The instance that was created for version B will become an orphan. 3. Delete the topic in version B. 4. Right-click the source topic, for example the topic in version A. 5. To create the new instance in version C, click Dynamic Release Management > Create New Instance. Select version C. How can I move a map to another version? You can use the Create New Instance DRM option to move maps to another version. We want to move a map from one version to another. The Move tool is no longer available. To move a map from one version to another within the same product, using the Create New Instance DRM option and then remove it from the original version. To move the map to a different product version, refactor it to a sub-library and then add the library to the product.