Edit online

Terminology Checker Add-on

Oxygen XML Editor offers an add-on that provides support for checking terminology. Once the add-on is installed, you can create a terminology file with a set of rules for each term (or sequence of characters) you want flagged. After referencing the custom file, Oxygen XML Editor will automatically highlight matched terms in the Author visual editing mode and offer some contextual menu actions.

To add this terminology checking functionality to Oxygen XML Editor, follow this procedure:

  1. Go to Help > Install new add-ons to open an add-on selection dialog box.
  2. Enter or paste https://www.oxygenxml.com/InstData/Addons/default/updateSite.xml in the Show add-ons from field or select it from the drop-down menu.
  3. Select the Terminology Checker add-on and click Next.
  4. Select the I accept all terms of the end-user license agreement option and click Finish.
  5. Restart the application.

Creating Custom Rules for the Terminology Checker

To create your own custom rules for the terminology checker, follow this procedure:

  1. Create a terminology file. There is a template available to help you get started in the New Document wizard. Click the New button on the toolbar or select File > New and search for the Terminology File template. Here is an example of the structure for this type of file:
    <incorrect-terms>
        <incorrect-term ignorecase="true">
            <match>Oxygen</match>
            <suggestion></suggestion>
            <message>Product name should be inside a tag.</message>
        </incorrect-term>
    </incorrect-terms>
    Notes:
    • The <incorrect-term> element must include a <match> element.
    • On the <match> element, you can specify the @type attribute with the values character, whole-words, or regular-expression. The default value is whole-word, except when the matched term contains Japanese, Chinese, or Korean characters because Asian languages do not usually use spaces to separate words. Example:
          <incorrect-term>
              <match type="character">ing</match>
              <message>Progresive tense should not be allowed</message>
          </incorrect-term>
    • Each <match> element has a @severity attribute that can be set to one of the values info, warning, or error. Example:
          <incorrect-term severity="error">
              <match>he</match>
              <message>Pronounts should be avoided.</message>
          </incorrect-term>
    • The <suggestion> element can be left blank or there can be one or more of them inside the <incorrect-term> element. It supports regular expressions grouping.
    • If you want to replace the match with an XML fragment, you can set the @format attribute on the <suggestion> element with the value xml. For example:
         <incorrect-term ignorecase="true">
              <match type="whole-word">Oxygen XML Editor</match>
              <suggestion format="xml">&lt;ph keyref=&quot;oxygen&quot;/></suggestion>
              <message>Replace all occurrences of product with key reference</message>
          </incorrect-term>
    • The <message> element is optional. If present, its content is displayed in a tooltip when you hover over a highlight. It supports regular expressions grouping.
    • The @ignorecase attribute specifies whether or not the match is case-sensitive.
  2. Go to Options > Preferences > Plugins > Oxygen Terminology Checker and in the Terminology Folder field, specify the folder where your terminology file is located.
  3. Click OK several times to apply the changes and close the preferences dialog box.
Result: If any of the terms (or sequence of characters) that are defined in the terminology file are detected in any open file, Oxygen XML Editor highlights the matches in the Author visual editing mode.
Note: If you have a folder named oxygen-term-checker in the current project that is open in the Project view, all the files in that folder will also be loaded by the terminology checker.

Using Vale Rules with the Terminology Checker

The Terminology Checker has partial support for applying custom Vale rules.

Supported Vale scopes: heading, table.header, table.cell, list, paragraph, code,strong,emphasis.

Supported Vale extension points: Existence, Substitution, Occurrence.

Result: If any of the terms (or sequence of characters) that are defined in the terminology file are detected in any open file, Oxygen XML Editor highlights the matches in the Author visual editing mode.
Note: If you have a folder named oxygen-term-checker in the current project that is open in the Project view, all the files in that folder will also be loaded by the terminology checker. As an example, the Oxygen XML Editor user guide has a folder with some of the Microsoft style guide rules: https://github.com/oxygenxml/userguide/tree/dev/DITA/oxygen-term-checker. Once the user guide project is opened in the Oxygen XML Editor Project view, the add-on will start using those rules to check the content.

Working with the Terminology Checker

The Terminology Helper side view shows all problems found in the document. You can right-click each problem to apply possible fixes or to find out more details about it. The tooltip for each problem displays a custom message and more information (e.g. for Vale rules, it also displays the name of the Vale rule file that defines the rule). You can filter problems based on their severity, match, and message and the toolbar has actions to navigate between problems or to open the Terminology Checker preferences page.

You can also right-click problems highlighted in the Author visual editing mode to access the following contextual menu actions:
  • Replace with "…" - Replaces the currently highlighted match with the content inside the <suggestion> element.
  • Replace all with "…" - Replaces all instances of the highlighted match found in the current document with the content inside the <suggestion> element.
  • Correct all matching highlights - Replaces all highlighted matches (all matched terms) within the document with the content inside the first <suggestion> element from the terminology file.

The terminology checking can be disabled by clicking the Show/Hide Terminology Highlights toolbar button. The checker automatically skips space-preserve elements such as codeblocks.

In the Oxygen XML Editor Options > Preferences > Plugins > Oxygen Terminology Checker page, you can define the highlight colors to be used for each issue depending on its severity. You can also reference a folder that contains the terminology rules. This folder can contain other folders with terminology files or just the terminology files.