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:
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>:
|
Requires expanding the content model of the
following elements to include zero or
more<hazardsymbol>:
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)
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:
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)