Thanks, Keith. Is the DITA source in SVN? We can clarify the
stage two review process (only introduced recently) and update the
proposal template if needed.
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)
On 3/23/2018 11:49 AM, Keith
Schengili-Roberts wrote:
Here is my draft Stage 2
proposal for the inclusion of strong and em under a new
domain and redefining the b and i elements in a more
semantically-descriptive manner.
I know that both Kris
Eberlein and Bob Thomas have volunteered to review this.
Apologies if this should have been circulated to them
first, but the other Stage 2 proposals I have looked at
did not indicate if they were reviewed beforehand.
Also, I admit my
technical weakness when it comes to devising a DTD
description, so I welcome any guidance in this part of
the proposal where I have inadvertently gone astray.
DITA 2.0 proposed feature #107
Date and version information
Date that this feature
proposal was completed
23 March 2018
Champion of the proposal
Keith
Schengili-Roberts
Links to any previous
versions of the proposal
https://lists.oasis-open.org/archives/dita/201803/msg00012.html
Links to minutes where
this proposal was discussed at stage 1 and moved to
stage 2
https://www.oasis-open.org/apps/org/workgroup/dita/download.php/62726/minutes20180313.txt
Links to e-mail
discussion that resulted in new versions of the proposal
N/A
Link to the GitHub issue
https://github.com/oasis-tcs/dita/issues/107
Original requirement
Many new people coming
to DITA have expressed confusion as to the supposed
semantic nature of DITA, and then seeing the existence
of only 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.
HTML5 has taken 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 for have more than a
passing familiarity with, this proposal suggests that
strong and em be added as elements under a new
domain—tentatively titled “semantic_descriptors”—that is
separate from the highlighting domain, containing these
two new tags. 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 meanings for 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
strong element would
inherit from topic/ph semantic_descriptors, and could be
defined as follows:
The strong element
should be used to indicate strong importance,
seriousness, or urgency of content. Typically, it’s
content will be rendered in boldface at output. This
element is part of the semantic descriptors domain. 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.
em element would also
inherit from topic/ph, and could be defined as follows:
The em element
should 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, it’s content will be
rendered in italics at output. This element is part of
the semantic descriptors domain. 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 more in line with HTML5’s
current definition. 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. 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
1.
Create a new domain for
these two new semantically descriptive elements,
tentatively called “semantic_descriptors”.
2.
Create two new
phrase-level elements within this domain: strong and em.
3.
Add new descriptions
plus example code illustrating the intended usage for
these elements.
4.
Change the descriptions
for the b and i elements within the highlighting domain
and include example code illustrating 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 known
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 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
semantic_descriptors domain would fall under the set of
general-purpose Domain elements.
Adding an element
Two new elements
will be added under the semantic_descriptors domain:
strong and em.
Inheritance:
+ topic/ph
semantic_descriptors/strong
+ topic/ph
semantic_descriptors/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 % semanticdescriptors-d-ph
"strong | em"
>
<!--
=============================================================
-->
<!-- DOMAIN ENTITY
DECLARATION -->
<!--
=============================================================
-->
<!ENTITY semanticdescriptors-d-att
"(semanticdescriptors-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 semantic_descriptors
domain, and one for each new element (strong and em).
·
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
counterparts 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 semantic_descriptors domain is
that it opens the possibility to include other, more
semantically-descriptive elements. For example, the
existing overline element is used within electrical
engineering to describe an “active low” signal, and
subscript is used within mathematics to describe the
base (or “radix”) of a number. These examples may be too
specific to a particular discipline for inclusion here,
but the idea of the semantic_descriptors domain provide
a basis for further, more semantically-defined phrasal
elements.
Vendors of tools
Low cost is
expected. Again, this is less a significant new feature
than an overdue “tweak”.
DITA community-at-large
·
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 migration 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
Example code for strong:
The strong element can
be used to indicate content that is considered to be
important, serious, or some form of urgency (without
being a specific warning). It can be used in the
following manner:
<p><strong>Important:</strong>
Before proceeding to wrangle your first ostrich, ensure
you know the location of the closest first aid
station.</p>
Example code for em:
The em element can be
used to indicate emphasis, stressing the importance of a
particular word to the reader.
<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>
Example code for b:
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>
It can also be used to
highlight things so that the user can easily scan text
for things like the names of roles that otherwise carry
no additional level of importance:
<p><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>
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><b>Ostrich
wrangling is not a job for the faint-hearted.</b>
But it can be a highly rewarding endeavour as they are
raised commercially for their meat, hide and
feathers.</p>
Example code for i:
The i element can also
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>
Or when different
character voices are being indicated:
<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 sharing 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>
Cheers!
-
Keith
Schengili-Roberts
Market Researcher and
DITA Evangelist
IXIASOFT
825
Querbes,
Suite 200, Montréal, Québec,
Canada, H2V 3X1
tel +
1 514 279-4942 / toll free +
1 877 279-4942
/
www.ixiasoft.com
