Providing Additional Documentation for XML Elements and Attributes

Oxygen XML Editor gathers documentation from the associated schemas (DTDs, XML Schema, RelaxNG) and presents it for each element or attribute. For example, if you open the Content Completion Assistant for a recognized XML vocabulary, documentation is displayed for each element provided by the associated schema. Similar information is displayed when you hover over tag names presented in the Elements view. If you hover over attributes in the Attributes view you also see information about each attribute, gathered from the same schema.

If you have a document type configuration set up for your XML vocabulary, there is a special XML configuration file that can be added to provide additional documentation information or links to specification web pages for certain elements and attributes. To provide this additional information, follow these steps:

Create a new folder in the configuration directory for the document type. For instance: OXYGEN_INSTALL_DIR/frameworks/dita/styleguide.
Use the New document wizard to create a file using the Oxygen content completion styleguide file template.
Make the appropriate changes to your custom mapping file. For example, you can look at how the DITA mapping file is configured: OXYGEN_INSTALL_DIR/frameworks/dita/styleguide/contentCompletionElementsMap.xml. The associated XML Schema contains additional details about how each element and attribute is used in the mapping file.
Save the file in the folder created in step 1, using the fixed name: contentCompletionElementsMap.xml.
Open the Preferences dialog box, go to Document Type Association, and edit the document type configuration for your XML vocabulary. Now you need to indicate where Oxygen XML Editor will locate your mapping file by doing one of the following:
- In the Classpath tab add a link to the newly created folder.
- In the Catalogs tab add a new catalog file. The selected file needs to contain the following:
```
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE catalog PUBLIC "-//OASIS//DTD XML Catalogs V1.1//EN" "http://www.oasis-open.org/committees/entity/release/1.1/catalog.dtd">
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
    <uri name="http://www.oxygenxml.com/{processed_dt_name}/styleguide/contentCompletionElementsMap.xml" uri="contentCompletionElementsMap.xml"/>
</catalog>
```
  where {processed_dt_name} is the name of the document type in lower case and with spaces replaced by underscores.
  
  Note: If Oxygen XML Editor finds a mapping file in both locations, the one in the Catalogs tab takes precedence.
Re-open the application and open an XML document.

In the Content Completion Assistant you should see the additional annotations for each element.