Sometimes, the server encounters problematic character entities that can’t be rendered correctly when extracting text from XML documents. Usually, DTDs define how entities should be rendered in XML documents, but the Acrolinx server can't always access your DTDs . However, you can still render entities without a DTD. You do this by configuring the server to use an entity conversion file .
An entity conversion file contains instructions for the server on how to interpret special character codes and entities. The server comes installed with several entity conversion files that convert some standard entity types.
If an entity conversion file isn’t configured, the server renders the codes for the entities instead of the intended characters. These entity codes are then sent to the server with the text, and can cause Acrolinx to report non-issues.
Standard Entity Conversion Files
Acrolinx has some standard entity conversion files to help you get started. We'll start including them in newer guidance packages, but in the meantime, you can download a zip file that contains 3 entity conversion files:
This file contains instructions for resolving both alphanumeric and Unicode entities.
This file contains instructions for resolving alphanumeric entities only.
This file contains instructions for resolving Unicode entities only.
Once you have downloaded and extracted the standard entity conversion files, put them in the following directory:
The next step is to configure the entity conversion file for checking .
Creating or Editing an Entity Conversion File
To create or edit an entity conversion file, follow these steps:
- Create a new file in a text editor or open an existing entity conversion file.
- For each conversion, type the character code and the desired output character separated by a tab character.
Specify each entity conversion on a separate row.Tip: If you don’t want to render the character for a particular entity, add a row containing the entity only. When no output character is provided, the entity is hidden during conversion.
- Save the text file in the directory
%ACROLINX_CONFIGURATION_ROOT%\data\csd\using the same encoding as the documents which contain the specified entities (the documents you intend to check).
- (Follow this step if you have created a new entity conversion file) Configure the entity conversion file for checking .
Configuring an Entity Conversion File for Checking
To ensure that the server uses entity conversion file for checking, you associate it with a CSD file. As a result, the server converts the entities whenever it checks a document with the associated CSD.
To configure an entity conversion file for checking, follow these steps:
- Update an existing CSD file or create a new CSD file .
- Add or edit the following properties:
entity_conversion_file=ISO_entities.txt entity_conversion_encoding=UTF-8The entity_conversion_encoding property is necessary because the server is unable to detect the encoding of the entity conversion file automatically. Using the following link for a list of the canonical names which this property accepts https://docs.oracle.com/javase/8/docs/technotes/guides/intl/encoding.doc.html
- Save your changes and upload the CSD.
- Open the dashboard and navigate to .
- Click Upload CSD , browse to your local copy of the CSD, and click Upload .
Your CSD is uploaded to the server. Acrolinx stores uploaded CSDs in the following directory:
- Restart your language servers.
After you've restarted your language servers, Acrolinx recognizes the new settings in your CSD.CSD profiles that use entity conversion have a heavy performance overhead. It may take up to nine times as long to analyze a document with entity conversion, depending on the size of the entity conversion file.