dita — archive

[Robert Thomas <bob.thomas@tagsmiths.com>]

I like Kris's proposal for adding hazardsymbol to each of the child elements in messagepanel. To understand why, do a search on images.google.com for "ansi z.535 safety" and look at all of the use cases that show up. Should the model change, the current position for hazardsymbol would become redundant, and it should be removed from the model. If not, organizations would have to write a constraint to prevent erroneous use. Migration strategy: move messagepanel/hazardsymbol to messagepanel/typeofhazard/hazardsymbol. Support for safetysymbols within each messagepanel is essential. I had a client that was unaware of the hazardstatement element, and they had 24 contiguous warnings in their safety section. (I implemented hazardstatement as an fo:table with the safety panel as a heading row and with each messagepanel as a row with keep-together. That way, the safety panel automatically regenerated itself across page boundaries.) Best regards, Bob Thomas On Sun, Sep 8, 2019 at 5:41 PM Kristen James Eberlein < kris@eberleinconsulting.com > wrote: 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>: <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) 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) -- Bob Thomas +1 720 201 8260 Skype: bob.thomas.colorado Instant messaging: Gmail chat ( bob.thomas@tagsmiths.com ) or Skype Time zone: Mountain (GMT-7)