Goal: Declare an element domain vocabulary module that provides elements for identifying mentions of XML constructs: element types, attributes, text entities, parameter entities, and numeric character references.
In any XML vocabulary for documents there is a general class of elements whose purpose is to hold the names or labels of real things in order to indicate what type of thing the name or label is for. A typical example would be an element named "person" whose purpose is to hold the names of people. Likewise, an element named "color" would identify the names of colors. Given the string "Brown" an author would tag it either <person>Brown</person> to indicate a reference to a Mr or Ms Brown or <color>brown</color> to indicate a mention of the color brown. This markup then enables finding all mentions of people named "Brown" but not the color brown. It also enables applying different typographic effects to person names and color names, if necessary. They can also enable things like automatic indexing where the element type is the primary entry (e.g., "colors") and the element content is used for secondary entries (e.g., "colors, brown", "colors, blue").
In my practice as a markup designer I refer to these types of elements as "mention" elements because their primary purpose is to identify mentions of things. In DITA the base element type for mentions is <keyword>. In technical documentation in particular mentions are very important because technical documentation is about real things that usually have specific component types or properties that need to be clearly identified, listed, searched on, and visually distinguished.
For Publishing applications, mentions are less important only because Publishing content tends to be less domain-specific and because the cost of adding mention markup is often not justified by the value, especially where content is not authored in XML originally. However, some Publishing content does benefit from specialized mention elements, especially reference content like travel and nature guides, where identifying things like place names or species names becomes important for both typography and search.
In DITA, mention elements can use the @keyref attribute to both get their effective text and become navigation links to the things they mention. This allows you to have mentions of things directly connected to their formal definition (e.g., in reference topics). This makes mention elements very powerful and a place where a relatively small investment in specialization can provide huge value for authors.
After attribute specialization, creating specialized mention elements is probably the easiest specialization to do and provides immediate value to authors. Because you don't normally need to worry about the content model details, this is entirely an exercise in naming and copying.
As much of what I write about involves XML markup, I find it necessary to have elements that identify mentions of different XML components: tag names (element types), attribute names, parameter entities, text (general) entities, and numeric character references. These components need distinguishing typographic presentation but that presentation can vary in different contexts. For example, I have historically used the convention "attname=" for attributes, but the DITA TC resolved on the convention "@attname" for attributes in the course of the development of DITA 1.2. By having markup for attribute name mentions it is easy to modify the style sheets to change from "attname=" to "@attname".
For this tutorial you will define an element domain module that provides the element types <xmlelem> (XML element), <xmlatt> (XML attribute), <textent> (general entity), <parment> (parameter entity), and <numcharref> (numeric character reference, e.g., "—").1
Element domains are typically either topic domains or map domains, meaning that they specialize either elements exclusively allowed within topics or exclusively within maps. However, if a domain only specializes elements that are common to maps and topics, then the domain may be used in both maps and topics. This includes domains that specialize from <text>, <keyword>, <term>, or <ph> and domains that specialize from <data>. This allows you to use the same mention elements within maps (e.g., within titles defined in maps and within metadata) and within topics.