Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)
-------- Forwarded Message --------
Background
Pretty much everyone who has chimed in on
this thread agrees that we need to make changes
regarding where <hazardsymbol> is permitted.
But ... Different people have very different ideas
about where it should be allowed.
Current
content model
Below is markup for a simple hazard
statement and its rendered output:
ÂÂÂÂÂÂÂ <hazardstatement
type="warning">
ÂÂÂÂÂÂÂÂÂÂÂ <messagepanel>
ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ <typeofhazard>GENERAL
HAZARDS</typeofhazard>
ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ <consequence>Overriding or
defeating the interlocks will expose personnel to
ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ hazardous
conditions.</consequence>
ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ <howtoavoid>DO NOT override or
defeat the interlocks unless specifically directed
to
ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ do so in the procedures. When
directed to override an interlock, follow all
ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ safety procedures and apply HEI
(Lockout/Tagout) procedures as
ÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂÂ necessary.</howtoavoid>
ÂÂÂÂÂÂÂÂÂÂÂ </messagepanel>
ÂÂÂÂÂÂÂÂÂÂÂ <hazardsymbol keyref="warning"/>
ÂÂÂÂÂÂÂ </hazardstatement>
Note that each
<hazardstatement> element can contain:
- One or more <messagepanel>
- Zero or more <hazardsymbol>
The <hazardstatement> element might
be rendered as follows:
<hazard-one-image.png>
Issues
with the current content model
Obviously the current content model works
fine for the simple hazard statement provided above.
But what happens when a hazard statement has
multiple message panels? Multiple hazard symbols?
Then it is unclear which symbol is associated with
which message panel -- or even which child component
of the message panel. Does a image represent the
"type of hazard" or "how to avoid" the hazard? This
might matter if a company's style calls for
rendering one type of image on the left and another
type of image on right.
Current
suggestions for modifying the content model
Person
|
Suggestion
|
Comments
|
Jang Graat
|
Associate
<hazardsymbol> with <messagepanel>
|
Requires changing the
specialization base of <messagepanel>
and its child elements
|
Toshihiko Makita,
Antenna House
|
Associate
<hazardsymbol> with
<messagepanel>; allow only a single
<hazardsymbol>
|
Not an option that we
can consider. DITA 1.2-13 allowed multiple
<hazardsymbol>, and we have many clear
use cases for multiple <hazardsymbol>
|
Kris Eberlein
|
Associate
<hazardsymbol> with the child elements
of <messagepanel>:
- <typeofhazard>
- <consequence>
- <howtoavoid>
|
Requires expanding the
content model of the following elements to
include zero or more<hazardsymbol>:
- <typeofhazard>
- <consequence>
- <howtoavoid>
This also might (better)
accommodate designs where a company wants to
use the hazardsymbol image as a bullet
point. From dita-users:
"
I
am having difficulty placing symbols
exactly where I want them (currently we
use a symbol in a similar way to a bullet
point) â but that may be due to my lack of
experience with DITA."
Realistically, any
company using the hazard statement domain
is going to need to invest in custom
stylesheets.
|
Assumptions
that drive design choices
There IS a reason for the
current design; the only reason that multiple
<messagepanel> elements are permitted is that
Chris Kravogel anticipated that companies might want
to have hazard statements that presented the
information in multiple languages. (KJE: This is not
a use case that I have seen in real world usage, at
least yet. And the design does not allow for
presenting the "signal word" -- based on the value
of the @type attribute -- on <hazardstatement>
in multiple languages )
Use cases that the original design did not
consider:
- Combining multiple message panels with
different information (and hazard symbols)
<image001.png>
This is a real world example from a Comtech
Services client, who uses this sort of rendering
in a "Safety" chapter. It also parallels what ANSI
Z 535.6 calls "grouped safety messages" and
"section safety messages".
- Single message panel but with
hazardsymbol images placed based on what they
represent:
<image001.jpg>
This is a real world example from Applied
Materials, a company that Amber and I and
Comtech have all worked with, I think.
What do you all think? Which option is
best? And do we continue to allow
<hazardsymbol> to be associated with
<hazardstatement>?
--
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)