Appendix B. DITA tags for highlighting
Use the following DITA tags to produce output that matches the highlighting guidelines.
(1) Only opening tags are shown in this column. Other tags that are included within an element are indented.
(2) This column shows what highlighting you should expect to see for each element according to the style described in “Highlighting” on page 102. Generally, styles for margin, padding, and so on, are not indicated.
(3) These tags do not convey any semantic meaning. Therefore, do not use them if you can use another tag. For example, use <i> only to put stress on a word in normal text.
(4) Do not use <keyword> to tag tokens, such as a single value from an enumerated list, the name of a command or parameter, product name, or a lookup key for a message. There are usually other suitable tags such as <option>. Or you could consider using <synph><kwd>. Restrict use of <keyword> for marking reusable text (“text entities”) that you might want to use anywhere in your documentation with a conref parameter. (<ph> might be considered a reasonable alternative, but there are some places where you might want to insert a text entity, where <ph> is not allowed, whereas <keyword> can appear almost anywhere.) This restriction avoids confusion between these two distinct usages.
(5) If an element, such as a command name, uses a normal English word that might be inadvertently translated, add the translate=“no” attribute to ensure that it is not translated. If the element would not normally be tagged, use <ph translate=“no”>.
(6) There is no set way of creating notes for tables, but it is probably most appropriate to add a <note> element that contains an ordered list immediately following the table and use <sup> tags around corresponding numbers within the body of the table:
<note othertype="Notes" type="other">
<!— setting type to "other" means that the title of the note is set to "Notes" —>
<ol>
<li> ... </li>
<li> ... </li>
(7) There is currently no DITA element for a single letter. Use <i> because this highlighting is purely presentational and has no semantic meaning. (Do not use <term>, which should be reserved for definitions. See Definition in text.)
(8) There is currently no explicit DITA element for an environment or registry variable. Use <parmname> for the name of the variable, and <option> for its value.