Proposal for the inclusion of the <strong>
and
<em>
elements under a new domain, while redfining
the <b>
and <i>
elements in a more semantic manner.
Date and version information
Original requirement or use case
Many new people coming to DITA have expressed confusion as to the supposed semantic nature
of DITA when they notice the existence of the <b>
(bold) and <i>
(italics) elements.
HTML has long supported (since the "HTML+" specification from 1993) the additional
<strong>
and
<em>
elements as more descriptive, semantic
equivalents for <b>
and
<i>
. In late 2014 the HTML5 standard took this
one step further by fully defining <b>
and
<i>
as semantic elements, distinct from
<strong>
and
<em>
.
In keeping with HTML5, a standard that many coming to DITA have more than a passing
familiarity with, this proposal suggests that
<strong>
and
<em>
be added as elements under a new domain
called "emphasis". At the same time, the existing
<b>
and
<i>
elements within the highlighting domain will
be re-defined within the DITA 2.0 specification in a more semantic manner. This will bring
them more in-line with their equivalent elements in HTML5; they are otherwise unchanged.
Use cases
For users seeking a semantic equivalent for the <b>
and <i>
elements,
<strong>
and
<em>
could now be used instead.
The retention and redefining of the <b>
and
<i>
elements would also make it clear as to the
situations for which <strong>
and
<em>
should be used, and the scenarios where
<b>
and
<i>
are more appropriate.
New terminology
The <strong>
element
would inherit from topic/ph emphasis
, and could be defined as follows:
"The <strong>
element can be used to indicate
content that is considered to be important, serious, or has some form of urgency (without
being a specific warning). Typically, its content will be rendered in boldface at output.
Use this element only when a more semantically appropriate element is not available. For
example, for a specific warning, consider using an appropriate element from the hazard
statement domain, such as <hazardstatement>
."
The <em>
element would also inherit from
topic/ph emphasis
, and could be defined as follows:
"The <em>
element can be used to indicate emphasis.
A stress emphasis is designed to change the meaning of a phrase or sentence, or stressing
the importance of a particular noun, verb or adjective. Typically, its content will be
rendered in italics at output. Use this element only when a more semantically appropriate
element is not available. For example, when indicating a different mood or voice, the
<i>
element may be more relevant."
The <b>
element description would also change,
making it more semantically descriptive, and aligning with its equivalent in HTML5. This
could look like the following:
"The <b>
element should be used to draw attention to a word or phrase for utilitarian purposes
without implying that there is any extra importance. There is also no implication of an
alternate voice or mood, or that its content should be actionable. For example, it can be
used to indicate product names within a review, highlighting roles within a process, or
for use in spans of text where the typical presentation is expected to be in a
boldface."
Similarly, the <i>
element
would also be redefined to make it more semantically descriptive, and aligning with its
equivalent in HTML5. It could look like the following:
"The
<i>
element should be used for a word or
phrase indicating either an alternate voice or mood, or to otherwise offset it from the
content around it to indicate a different quality of text, such as a taxonomic
designation, an idiomatic phrase from another language, technical term, or a ship
name."
Proposed solution
- Create a new
emphasis
domain.
- Create two new phrase-level elements within this domain:
<strong>
and
<em>
.
- Add new descriptions plus example code illustrating the intended usage for these
elements.
- Change the descriptions for the
<b>
and
<i>
elements within the highlighting domain
and include example code illustrating their intended usage.
Benefits
- Who will benefit from this feature?
- Authors seeking a more semantic element for encapsulating content that should either
be
<strong>
or emphasized. The redefinition of
the <b>
and
<i>
elements will also make it plain when and
where these highlighting elements should be used. It will also benefit DITA trainers who
will now be able to point to more semantic equivalents to the existing
<b>
and
<i>
elements.
- What is the expected benefit?
- Authors working within DITA will have a more clear-cut choice on when to use
<strong>
and
<em>
, and when to use
<b>
and
<i>
, in keeping with how these elements are
currently defined within HTML5.
- How many people probably will make use of this feature?
- There are cases where technical writing teams have constrained out the highlighting
domain because of its lack of semantic elements. Similarly, there are DITA authoring
groups that have either specialized
<ph>
to
create their own equivalent of <strong>
and
<em>
, or, more awkwardly, use
@outputclass
with <ph>
to
achieve the same ends. The redefinitions proposed for
<b>
and
<i>
may convince the former to retain the
highlighting domain, while providing the new, semantically-described
<strong>
and
<em>
elements ought to take care of the
latter group.
- While this proposal is not sufficient to draw people to use DITA 2.0, it will likely
be welcomed by the user community.
- How much of a positive impact is expected for the users who will make use of the
feature?
- Likely minimal; in many ways this is less a feature than a long-overdue tweak to the
specification. However, those who will use this feature are likely to be pleased with
its addition.
Technical requirements
- Adding new elements or attributes
- Two new elements,
<strong>
and
<em>
, will be added under a new domain.
- Adding a domain
- The new
emphasis
domain would fall under the set of general-purpose
Domain elements. It is possible that other elements may fit into this domain in the
future; for example, active-low signals in electrical engineering/semiconductor
documentation are typically rendered with an overline, indicating logical negation. This
is currently handled using the <overline>
element from the highlight domain. Similarly, instead of using subscript letters to
indicate voltage nodes, these could be more specifically and semantically described
within the emphasis domain, which can then be formatted according to the style for that
industry sector.
- Adding an element
- Two new elements will be added under the emphasis domain:
<strong>
and
<em>
.
- Inheritance:
+ topic/ph emphasis/strong
+ topic/ph emphasis/em
- DTDs:
- (Please note that the following is based on DITA 1.3 and does not include any proposed
changes for phrase-level elements that may have already been proposed for DITA
2.0).
<!ENTITY % emphasis-d-ph
"strong | em"
>
<!-- ============================================================= -->
<!-- DOMAIN ENTITY DECLARATION -->
<!-- ============================================================= -->
<!ENTITY emphasis-d-att
"(emphasis-d-ph)"
>
<!-- ============================================================= -->
<!-- ELEMENT NAME ENTITIES -->
<!-- ============================================================= -->
<!ENTITY % strong "strong" >
<!ENTITY % em "em" >
<!-- LONG NAME: Strong -->
<!ENTITY % strong.content
"(#PCDATA |
%basic.ph; |
%data.elements.incl; |
%draft-comment; |
%foreign.unknown.incl; |
%required-cleanup;)*"
>
<!ENTITY % strong.attributes
"%univ-atts;
outputclass
CDATA
#IMPLIED"
>
<!ELEMENT strong % strong.content;>
<!ATTLIST strong % strong.attributes;>
<!-- LONG NAME: Em -->
<!ENTITY % em.content
"(#PCDATA |
%basic.ph; |
%data.elements.incl; |
%draft-comment; |
%foreign.unknown.incl; |
%required-cleanup;)*"
>
<!ENTITY % em.attributes
"%univ-atts;
outputclass
CDATA
#IMPLIED"
>
<!ELEMENT em % em.content;>
<!ATTLIST em % em.attributes;>
- Renaming or refactoring elements and attributes
- Only the description of the
<b>
and
<i>
elements need to be updated in the DITA
2.0 specification. See the "New Terminology" section for the proposed changes in
wording.
- Renaming or refactoring an attribute
- N/A
- Removing elements or attributes
- N/A
- Processing impact
- Expected to be minimal.
- Overall usability
- Users will have a choice between using
<strong>
and
<em>
vs. the
<b>
and
<i>
elements. There may be some confusion as
to when to best use <strong>
vs.
<b>
and
<em>
vs.
<i>
, but this can be mitigated by providing
numerous, relevant code examples in the specification for each element.
Backwards compatibility
- Changing the meaning of an element or attribute in a way that would disallow existing
usage?
- As the
<b>
and
<i>
elements are not being removed, going
forward DITA 2.0 users can continue to use these elements if they choose, opt to use
<strong>
and
<em>
as their replacements, or to use both
sets of elements in parallel.
Migration plan
- Might any existing documents need to be migrated?
- Use of
<strong>
and
<em>
is optional as
<b>
and
<i>
are still present, so there is no need to
update all instances of <b>
to
<strong>
, and
<i>
to
<em>
, though there will undoubtedly be some
technical documentation teams that choose to do so.
- Might any existing processors or implementations need to change their
expectations?
- Not in terms of expectations, though output processors (such as the DITA-OT) will need
to accommodate the formatting of the two new elements, though for compatibility it is
suggested that
<strong>
copies the default
output behavior of <b>
, and that
<em>
copies that of
<i>
.
- Might any existing specialization or constraint modules need to be migrated?
- Groups that have previously constrained out the highlighting domain, or who have
specialized
<ph>
for creating equivalents for
<strong>
and
<em>
, are likely to drop their modifications
with this proposal. There may still be groups that choose to constrain out the
highlighting domain despite the revised semantic descriptions for
<b>
and
<i>
, but if so that would be their
choice.
Costs
Outline the impact (time and effort) of the feature on the following groups:
- Maintainers of the grammar files
- Minor cost in adding the new domain and its associated elements.
- Editors of the DITA specification: How many new topics will be required?
- Three. One to describe the intent of the new
emphasis
domain, and one
for each new element (<strong>
and
<em>
).
- Editors of the DITA specification: How many existing topics will need to be
edited?
- Two. The topics for
<b>
and
<i>
ought to be updated to be more
semantically descriptive, which will align them with their equivalent elements in HTML5.
- Will the feature require substantial changes to the information architecture of the
DITA specification? If so, what?
- Only the addition of the new domain. Other than that, no significant architectural
change is required.
- A possible advantage of having a new
emphasis
domain is that it opens
the possibility to include other, more semantically-descriptive elements that lend
themselves to specific formatting styles. For example, active-low signals in electrical
engineering/semiconductor documentation are typically rendered with an overline,
indicating logical negation. This is currently handled using the
<overline>
element from the highlight
domain. Similarly, instead of using subscript letters to indicate voltage nodes, these
could be more specifically and semantically described within the emphasis domain, which
can then be formatted according to the style for that industry sector.
- Vendors of tools
- Low cost is expected. Again, this is less a significant new feature than an overdue
"tweak".
- Will this feature add to the perception that DITA is becoming too complex?
- Any additional element adds to the total number of elements available in DITA.
However, the intent is to bring DITA more in line with current HTML5 practice, something
that will likely be welcomed by the community.
- Will it be simple for end users to understand?
- Yes. As mentioned earlier, this is less of a wholly new feature than a long-overdue
tweak. It seems likely that the community is likely to embrace these new tags, along
with the alignment with their equivalents in HTML5.
- Producing migration instructions or tools
- If there are teams that decide to migrate all instances of
<b>
and
<i>
to
<strong>
and
<em>
, there are already tools capable of
doing this one-for-one switch. It is unlikely that there will be new tools needed to do
this.
- A white paper to describe the correct usage of the new and revised elements would be
overkill, especially if sufficient code examples explaining the context for usage are
provided within the specification.
- If there is new terminology, is it likely to conflict with any usage of those terms in
the existing specification?
- The new definitions for
<strong>
and
<em>
, plus
<b>
and
<i>
, will make it clear as to their scenarios
for use, along with a good set of code examples to demonstrate best practices for when
they should be used.
Examples
(The following is a draft description of the
<strong>
element intended for use in the DITA
2.0 specification. It includes several examples).
The <strong>
element can be used to indicate
content that is considered to be important, serious, or has some form of urgency (without
being a specific warning). Typically, its content will be rendered in bold at output.
Examples
The following examples show how it can be used.
Emphasizing an important detail:
<p>Your doctor prescribed this medicine to treat an infection. It is important that you <strong>take all of
the medicine</strong> as described.</p>
Another example:
<p>When starting a car with a keyless ignition, you must <strong>step on the brake pedal</strong> before
pressing the start button.</p>
Underscoring a serious point:
Use the word <em>very</em> <strong>sparingly</strong>. Where emphasis is necessary, use words strong in
themselves.
Pointing out a critical/urgent detail:
<p>SERVICE HEADLIGHTâ<strong>Black</strong> wire with <strong>red tracer</strong> from handlebar toggle switch
to large terminal screw; <strong>red</strong> wire with <strong>yellow tracer</strong> from handlebar toggle
switch to small terminal screw.</p>
This element is part of the emphasis domain. The addition of this element brings DITA more
into alignment with its equivalent in the current HTML specification.
(The following is a draft description of the
<em>
element intended for use in the DITA 2.0
specification. It includes several examples).
The
<em>
element can be used to indicate emphasis. A
stress emphasis is designed to change the meaning of a phrase or sentence, or stressing the
importance of a particular noun, verb or adjective. Typically, its content will be rendered
in italics at output. Use this element only when a more semantically appropriate element is
not available. For example, when indicating a different mood or voice, the
<i>
element may be more relevant.
Examples
The following examples show how it can be
used.
Emphasizing meaning within a
sentance:
<p>What was previously called <em>block-level</em> content up to HTML 4.1 is now called
<em>flow</em> content in HTML5.</p>
Stressing
the importance of a noun within a sentence:
<p>A <em>condenser</em> is an apparatus for condensing a large quantity of electricity
on a comparatively small surface.</p>
Stressing the importance of a verb or actions within a sentence:
To remove a message from a pigeon, first <em>catch</em> the bird, then <em>hold</em> it
in one hand, <em>extend</em> its leg, and <em>remove</em> the message holder with the other hand.
Stressing the importance of an adjective or adjectival phrase within a sentence:
<p>A good plan once adopted and put into execution <em>should not be abandoned</em> unless it
becomes clear that it can not succeed.</p>
This element is part of the emphasis domain. The addition of this element brings DITA
more into alignment with its equivalent in the current HTML specification.
(The
following is a draft description of the <b>
element intended for use in the DITA 2.0 specification. It includes several
examples).
The
<b>
element is used to draw
attention to a word or phrase for utilitarian purposes without implying that there is any
extra importance. There is also no implication of an alternate voice or mood, or that its
content should be actionable. For example, it can be used to indicate product names within a
review, highlighting roles within a process, or for use in spans of text where the typical
presentation is expected to be in a boldface.
Examples
The
<b>
element can be used to indicate a product
name within a
review:
<p>One of the best features of <b>Mr. Flip-it</b> is its ability to manipulate objects within a
three-dimensional space so that you can see the other side.</b>
The
<b>
element can be used to highlight related
concepts within a topic:
<p>The <b>Solid Waste Operations Manager</b> plans and manages the countywide transfer station and
landfill operations, coordinates solid waste processing operations with the planning and
engineering staff, and performs related duties as required.</p>
[...lots of intervening text]
<p>The <b>Sanitation Engineer</b> creates strategies for landfill sites that minimize the
impact on the environement.</p>
The
<b>
element can also be used in situations where
boldfaced text is expected for stylistic purposes, such as when the house style for an
article lede is to be rendered in
boldface:
<p><strong>Know where to get help.</strong> Before proceeding to wrangle your first ostrich, ensure
you know the location of the closest first aid station.</p>
The
redefining of this element brings DITA more into alignment with the equivalent element in
the current HTML specification.
(The following is a draft description of the
<i>
element intended for use in the DITA 2.0
specification. It includes several examples).
The
<i>
element is
used to indicate either an alternate voice or mood, or to otherwise offset it from the content
around it to indicate a different quality of text, such as a taxonomic designation, an
idiomatic phrase from another language, technical term, or a ship name.
Examples
The <i>
element can be used
for indicating text in a different voice, such as when foreign words or phrases are
used:
<note type="caution">Even highly experienced operators of heavy machinery should remain alert
for dangerous situations. Having a <i>laissez-faire</i> attitude is a recipe for
disaster.</note>
The
<i>
element can also be used to indicate
different character voices:
<p><i>Edgar</i>: I know thee wellâa serviceable villain, as duteous to the vices of thy mistress
as badness would desire.</p>
<p><i>Gloucester</i>: What, is he dead?</p>
It
can also be used to indicate a taxonomic
designation:
<p>When wrangling ostriches (<i>Struthio camelus</i>) people are advised that while they are a type of bird
(Class: <i>Aves</i>), they are thought to be descendants of their extinct dinosaur (Suborder:
<i>Theropoda</i>) relatives and share the same type of temperament.</p>
The
<i>
element can also be used to designate the
name of a
ship:
<p>The MV <i>Rena</i> was a container ship that ran aground near Tauranga, New Zealand, resulting in an
oil spill.</p>
It
can also be used to indicate a new or technical term the first time it is
introduced:
<p>Immediately prior to undergoing an MRI, a doctor may inject a contrast agent called the <i>gadolinium
contrast medium</i> into the patient. This 'dye' highlights the part of the body being scanned and can
provide more information to the radiologist who is assessing the patient's problem.</p>
The
redefining of this element brings DITA more into alignment with the equivalent element in
the current HTML specification.