Terminology Checker Add-on
Quick Installation
You can drag the following Install button and drop it into the main editor in Oxygen to quickly initiate the installation process:
Manual Installation
To manually install the add-on, follow this procedure:
- Go to to open an add-on selection dialog box.
- 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.Note: If you have issues connecting to the default update site, you can download the add-on package, unzip it, then use the Browse for local files action in the Install new add-ons dialog box to locate the downloaded addon.xml file.
- Select the Terminology Checker add-on and click Next.
- Read the end-user license agreement. Then select the I accept all terms of the end-user license agreement option and click Finish.
- Restart the application.
Creating Custom Rules for the Terminology Checker
To create your own custom rules for the terminology checker, follow this procedure:
- 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 and search for the Terminology File template. Here is an example of the structure for this type of file:
<incorrect-terms lang="en"> <incorrect-term ignorecase="true"> <match>Oxygen</match> <suggestion></suggestion> <message>Product name should be inside a tag.</message> </incorrect-term> </incorrect-terms>
- Save the newly created terminology rules XML file either in a new subfolder named oxygen-term-checker located in the current project folder (the current project opened in the application Project view), or in a custom folder.
- If you saved the terminology file in a custom folder path, go to the Additional Terminology folder path to point to that folder. preferences page and set the
- Click OK several times to apply the changes and close the preferences dialog box.
Structure of Terminology Rules File
<incorrect-terms>
- This is the root element of the XML rules file.
<incorrect-term>
-
Defines ways to match and correct an incorrect term. The
<incorrect-term>
element must include a<match>
element.The
@ignorecase
attribute specifies whether or not the match is case-sensitive.The@severity
attribute can be set to one of the following values:info
,warning
, orerror
. Example:<incorrect-term severity="error"> <match>he</match> <message>Pronouns should be avoided.</message> </incorrect-term>
An experimental@part-of-speech
attribute can be set on the<incorrect-term>
element with the value set to a part of speech tag (for example:adjective
,verb
, etc.) If set, when scanning for terminology problems, the problem is presented only if the term's part of speech matches the one specified. The processor used to identify the part of speech is Apache OpenNLP and this feature is supported only for the English language.Note: The results may not be 100% accurate, so you should double-check them. <match>
Specify the text fragment to match.
You can specify the@type
attribute on the<match>
element, with the valuescharacter
,whole-word
, orregular-expression
. The default value iswhole-word
, unless the matched term contains Japanese, Chinese, or Korean characters because Asian languages often do not use spaces to separate words. Example:<incorrect-term> <match type="character">ing</match> <message>Progressive tense should not be allowed</message> </incorrect-term>
<suggestion>
-
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 valuexml
. For example:<incorrect-term ignorecase="true"> <match type="whole-word">Oxygen XML Editor</match> <suggestion format="xml"><ph keyref="oxygen"/></suggestion> <message>Replace all occurrences of product with key reference.</message> </incorrect-term>
<message>
- 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. <link>
- The
<link>
element is optional. If present, it provides the source for this rule. Example:<incorrect-term ignorecase="true"> <match type="whole-word">Oxygen XML Editor</match> <suggestion format="xml"><ph keyref="oxygen"/></suggestion> <link>https://www.oxygenxml.com/doc/ug-editor/topics/terminology-checker.html</link> </incorrect-term>
<xpath-context>
The
You can specify<xpath-context>
element can be used to define simple XPath expressions that match specific elements.@include
and@exclude
attributes. The elements covered by this simplified XPath will be checked for matches (or the exclusion of a match). A list of comma-separated XPath values can be used. Example:<xpath-context include="p, div, codeblock">
The following are examples of how simplified XPath expressions might look like:
elementName
//elementName
/elementName1/elementName2/elementName3
//xs:localName
Note: The namespace prefixes (such asxs
) are treated as part of the element name without taking its binding to a namespace into account.
You can use one or more of the following attribute conditions:
Attention: Default attribute values are not taken into account.element[@attr]
- Matches all instances of the specified element when it includes the specified attribute.element[not(@attr)]
- Matches all instances of the specified element when it does not include the specified attribute.element[@attr = 'value']
- Matches all instances of the specified element when it includes the specified attribute with the given value.element[@attr != 'value']
- Matches all instances of the specified element when it includes the specified attribute and its value is different than the one given.
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, sentence.
Supported Vale extension points: Existence, Substitution, Occurrence, Repetition, Conditional.
- Vale rules that aim to replicate Grammarly checks: https://github.com/testthedocs/Openly/tree/master/Openly.
- Vale rules that aim to automate the Microsoft style guide:https://github.com/errata-ai/Microsoft/tree/master/Microsoft.
- Vale rules that aim to automate the Google style guide: https://github.com/errata-ai/Google/tree/master/Google.
Working with the Terminology Checker
The Terminology Checker 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.
- 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 deleted content with tracked changes and space-preserved elements (e.g. codeblocks).
- When replacements are performed, the capitalization is preserved.
- In the Oxygen XML Editor 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. The option that controls automatic capitalization can also be found in this preferences page.
- If you select Project Options (in the Terminology Checker preferences page), the settings are stored in the project file (.xpr) that can be shared with other users.
Terminology Checker Preferences
- Highlight background
- You can specify various colors to influence the background colors for terminology highlights that are added in the Author visual editing mode.
- Highlight decoration
- You can specify various colors to influence the highlight decoration styles for terminology highlights that are added in the Author visual editing mode.
- Editing
-
- Preserve case when performing replacements
- Controls whether or not the original letter casing is automatically preserved when replacing words. The option is selected by default.
- Report unsupported Vale rules as errors
- If selected (default), errors that are related to Vale terms (such as unsupported extension points or invalid properties) are reported. If not selected, unsupported Vale rules are ignored (although an error is still reported if the file is invalid).
- Learned terms
-
- Default project terminology folder
- Displays the default location where all the terminology rule files (XML or Vale) are stored. By default, the rule files located in the oxygen-term-checker subfolder of the current project folder (the current project loaded in the Project view) are automatically loaded and used.
- Additional terminology folder
- You can use this option to specify an additional terminology folder where XML and Vale rule files are located. You can use editor variables such as ${pd}/terms to specify the path to the terminology folder.
Checking Multiple Resources
- Right-click on the root of the DITA map opened in the DITA Maps Manager view and choose Check terminology.
- Right-click a folder in the Project view and choose Check terminology.
- Create a new validation scenario or edit an existing validation scenario, and add a
new validation stage. For the File type field, choose
XML Document and for the Validation
engine field, choose Terminology checker. The
validation scenario can be used in multiple ways:
- In the Project view, you can right-click a folder and validate using a specific validation scenario.
- In the DITA Maps Manager view, you can use the Validate and Check for Completeness toolbar action and choose to Batch validate referenced DITA resources. This will apply the associated validation scenario for each topic or map referenced in the context of the main DITA map.
Terminology Files Contributed from Other Oxygen Add-ons
Any Oxygen add-on can contribute terminology files that will be used by the Terminology Checker. The contributed terminology files will be loaded and used if the contributor add-on is enabled.
- The contributor add-on's plugin.xml
descriptor file should reference the rules folder in the plugin.xml
as a
librariesFolder
with aglobal
scope:<plugin id="unique.identifier.name" name="My Style Guide" description="Style Guide" version="1.0" vendor="Vendor Name" class="ro.sync.exml.plugin.Plugin" classLoaderType="preferReferencedResources"> <runtime> <librariesFolder name="Rules_Folder" scope="global"/> </runtime> </plugin>
- The contributor add-on should have a marker file named oxy-terms-auto-detect inside the rules folder. The terminology files can be added in the rules folder or organized in subfolders (the Terminology Checker scans the subfolders to identify the terminology files). Inside the oxy-terms-auto-detect file, there should be a textual description of the terminology file contents, which is used when presenting add-on contributed terms in the Terminology Checker preferences page ( ).
ASD Simplified Technical English Specification (ASD-STE100) Rules
An extra add-on is available that contributes ASD Simplified Technical English Specification rules to the Terminology Checker. It contains technical rules based on ASD-STE100 (http://www.asd-ste100.org), but note that these rules are not endorsed by ASD-STE100.
To install these rules, use the manual add-on install procedure and select ASD Simplified Technical English Specification (ASD-STE100) Writing Style Guide Rules (experimental) for the add-on to install.
MS Writing Style Guide Vale Rules
An extra add-on is available that contributes a set of rules based on the Microsoft Writing Style Guide to the Terminology Checker. It contains a Vale-compatible (https://vale.sh) implementation of the MS Writing Style Guide (https://learn.microsoft.com/en-us/style-guide/welcome/) as provided by the errata-ai open-source project (https://github.com/errata-ai/Microsoft). Note that this project is neither maintained nor endorsed by Microsoft.
To install these rules, use the manual add-on install procedure and select MS Writing Style Guide Vale Rules for the add-on to install.