Element Domain Specialization Step 1: Design The Domain Element Types

The first step in specialization is designing your markup.

For this exercise, the element types to be declared are all specializations of <keyword>, which is a pretty typical use case: you just need a few additional keyword-type elements to mark up mentions of things that are specific to your documentation.

The element types to be declared are:

<xmlelem>: Identifies mentions of XML element types. Intended typographic effect is to put the name in a monospaced font, surrounded by angle brackets: <an-element>.
<xmlatt>: Identifies mentions of XML attributes. Intended typographic effect is to put the name in monospaced font with a leading "@" sign: @an-attribute.
<textent>: Identifies mentions of XML text entities. Intended typographic effect is to put the name in monospaced font with a leading ampersand and trailing semicolon: &a-text-entity-name;. (To be pedantic about it, the formatting specification actually produces an entity reference rather than a mention of an entity name, but Charles Goldfarb and I are probably the only people on the planet who would both notice the difference and care about the distinction. So we add the closing semicolon ("entity reference close"), because that's how people expect something starting with an ampersand to look. Alternatively, I could have used a different typographic convention—maybe small caps—and omitted the ampersand, but that would probably have just made it more confusing.)
<parment>: Identifies mentions of XML parameter entities. Intended typographic effect is to put the name in monospaced font with a leading percent sign and a trailing semicolon: %a-parameter-entity-name;. (To be pedantic again, technically, the "%" is part of the parameter entity name and also serves as the entity reference open, so even if for text entities we didn't show the ampersand we would show the "%" for parameter entity references. Again, probably only Charles Goldfarb and I know or care about the difference. But I am compelled by years of deep standards work and an uncontrollable pedantic streak to mention that there is in fact a difference. Not that anyone cares. And yes, I was that kid who always said "technically, a peanut is not a nut, it's a legume.")
<numcharref>: Identifies mentions of XML numeric character references. Intended typographic effect is to put the number in monospaced font with a leading "numeric character reference open" (&#) and closing semicolon: —. The content should be the numeric value, preceded by an "x" for hex values. (I don't even have to say it do, I?)

None of these elements allows any subelements, so their content models will all be just #PCDATA.

Domain modules must be given a short name that is used in the filenames, entity names, and in the @class attributes. For this tutorial, the domain module name is "xml." In practice, you should give your domains more distinctive names so there is minimal chance of name collisions with other domains. You see this with the DITA 1.2 Learning and Training specializations, where both the domains and the element types all start with "lc" (for "Learning Content"). This is essentially the same as having a namespace prefix on your names, but of course DITA 1.x cannot use namespaces, so you have to make do with the simple convention of distinguishing bits in your names.