Merge pull request #621 from keberlein/edit-hazard-statement

Edit of hazard-statement domain
oasis-tcs · Feb 6, 2022 · bb18cde · bb18cde
2 parents a77a4f1 + 19bde18
commit bb18cde
Show file tree

Hide file tree

Showing 7 changed files with 72 additions and 99 deletions.
diff --git a/specification/langRef/base/consequence.dita b/specification/langRef/base/consequence.dita
@@ -21,11 +21,11 @@
       <p conkeyref="reuse-attributes/only-universal"/>
     </section>
 <example id="example" otherprops="examples"> 			<title>Example</title>
-      <p>In the following code sample, a hazard statement is assigned a
-        "CAUTION" signal word. The type of hazard is a specified as "HOT
-        SURFACES," and the consequence of not avoiding the hazard is
-        "Contact may cause a burn." The hazard image is explicitly
-        associated with the type of hazard.</p>
+      <!--<p>In the following code sample, a hazard statement is assigned a "CAUTION" signal word. The type of hazard is a specified as "HOT SURFACES," and the consequence of not avoiding the hazard is "Contact may cause a burn." The hazard image is explicitly associated with the type of hazard.</p>-->
+      <p>The following code sample shows the markup for a hazard statement
+        that warns about hot surfaces. The
+          <xmlelement>consequence</xmlelement> element provides information
+        about what might happen: "Contact might cause a burn."</p>
       <codeblock>&lt;hazardstatement type="caution"&gt;
   &lt;messagepanel&gt;
     &lt;typeofhazard&gt;

diff --git a/specification/langRef/base/hazardstatement.dita b/specification/langRef/base/hazardstatement.dita
@@ -3,7 +3,8 @@
 <reference id="hazardstatement" xml:lang="en-us">
   <title><xmlelement>hazardstatement</xmlelement></title>
   <shortdesc>A hazard statement provides information about a hazard and its
-    consequences. It also explains how to avoid the hazard.</shortdesc>
+    consequences. It also explains how to avoid the hazard. It can also
+    associate an image.</shortdesc>
   <prolog>
     <metadata>
       <keywords>
@@ -13,10 +14,6 @@
     </metadata>
   </prolog>
   <refbody>
-    <section id="usage-information">
-      <title>Usage information</title>
-      <p/>
-    </section>
     <section id="specialization-hierarchy">
       <title>Specialization hierarchy</title>
       <p>The <xmlelement>hazardstatement</xmlelement> element is
@@ -71,10 +68,8 @@
           <xmlelement>hazardstatement</xmlelement> element can be used.</p>
       <fig>
         <title>Simple hazard statement</title>
-        <p>The following code sample defines a hazard statement with a
-          signal word of "DANGER". It also includes an image that
-          illustrates the possible consequences of not avoiding the
-          hazard.</p>
+        <p>The following code sample shows the markup for a hazard
+          statement that warns about rotating blades:</p>
         <codeblock>&lt;hazardstatement type="danger">
   &lt;messagepanel>
     &lt;typeofhazard>
@@ -84,31 +79,48 @@
     &lt;howtoavoid>Follow lockout procedure before servicing.&lt;/howtoavoid>
   &lt;/messagepanel>
 &lt;/hazardstatement></codeblock>
-        <p>
-          <draft-comment author="Kristen J Eberlein" time="02 January 2021">
-            <p>Would it be helpful to have a screen capture of one possible
-              rending of the hazard statement, with the caveat that
-              rendering is implementation-specific?</p>
-          </draft-comment>
-        </p>
       </fig>
       <fig>
         <title>Example of a hazard statement that contains multiple
           hazards</title>
-        <p/>
-        <codeblock/>
+        <p>The following code sample generates an ANSI Z535.6 grouped
+          safety message that specifies information about multiple
+          hazards:</p>
+        <codeblock>&lt;hazardstatement type="warning">
+  &lt;messagepanel>
+    &lt;typeofhazard>
+      &lt;hazardsymbol keyref="hazard-electricshock"/>
+      ELECTRIC SHOCK HAZARD&lt;/typeofhazard>
+      &lt;consequence>The equipment must be grounded. Improper grounding, setup, or usage of
+                    the system can cause electric shock
+      &lt;/consequence>
+      &lt;howtoavoid>
+        &lt;hazardsymbol keyref="hazard-groundpowersource"/>
+        &lt;ul>
+          &lt;li>Turn off and disconnect power at main switch before disconnecting any
+              cables or before servicing or installing any equipment.&lt;/li>
+          &lt;li>Connect only to grounded power sources.&lt;/li>
+          &lt;li>All electric wiring must be done by a qualified electrician and comply
+              with all local codes and regulations.&lt;/li>
+        &lt;/ul>
+      &lt;/howtoavoid>
+    &lt;/messagepanel>
+    &lt;!-- ... -->
+    &lt;messagepanel>
+      &lt;typeofhazard>
+        &lt;hazardsymbol keyref="hazard-hotsurface"/>
+        BURN HAZARD&lt;/typeofhazard>
+        &lt;consequence>Electric sufaces and fluid can become very hot during
+                    operation.&lt;/consequence>
+        &lt;howtoavoid>
+          To avoid burns:
+          &lt;ul>
+            &lt;li>Do not touch hot fluid or equipment.&lt;/li>
+          &lt;/ul>
+        &lt;/howtoavoid>
+  <b>&lt;/messagepanel></b>
+&lt;/hazardstatement></codeblock>
       </fig>
-      <hazardstatement>
-        <messagepanel>
-          <typeofhazard/>
-          <howtoavoid/>
-        </messagepanel>
-        <messagepanel>
-          <typeofhazard/>
-          <howtoavoid/>
-        </messagepanel>
-      </hazardstatement>
-      <p/>
     </example>
   </refbody>
 </reference>
diff --git a/specification/langRef/base/hazardsymbol.dita b/specification/langRef/base/hazardsymbol.dita
@@ -18,7 +18,8 @@ a result of not avoiding a hazard, or any combination of these messages.</shortd
       <p>When a <xmlelement>hazardsymbol</xmlelement> element is directly
         contained by <xmlelement>messagepanel</xmlelement>, the
           <xmlelement>hazardsymbol</xmlelement> is assumed to be associated
-        with the <xmlelement>typeofhazard</xmlelement> element.</p>
+        with the <xmlelement>typeofhazard</xmlelement> element. Otherwise,
+        the image is associated with the containing element.</p>
     </section>
     <section id="rendering-expectations">
       <title>Rendering expectations</title>
@@ -66,9 +67,8 @@ a result of not avoiding a hazard, or any combination of these messages.</shortd
       </dl>
     </section>
 <example id="example" otherprops="examples"><title>Example</title>
-      <p>The following code sample defines a hazard statement with a signal word of "DANGER." The
-          <xmlelement>hazardsymbol</xmlelement> element is explicitly associated with the
-          <xmlelement>typeofhazard</xmlelement> element.</p>
+      <p>The following code sample defines a hazard statement that
+        specifies an image that illustrates the type of hazard: </p>
       <codeblock>&lt;hazardstatement type="danger">
   &lt;messagepanel>
     &lt;typeofhazard>
@@ -78,19 +78,15 @@ a result of not avoiding a hazard, or any combination of these messages.</shortd
     &lt;howtoavoid>Follow lockout procedure before servicing.&lt;/howtoavoid>
   &lt;/messagepanel>
 &lt;/hazardstatement></codeblock>
-      <p>In the following code sample, the <xmlelement>hazardsymbol</xmlelement> is contained by the
-          <xmlelement>messagepanel</xmlelement> element. By default, this markup also associates the
-          <xmlelement>hazardsymbol</xmlelement> element with the
-          <xmlelement>typeofhazard</xmlelement> element. This markup can be useful when migrating
-        hazard statements from earlier versions to DITA 2.0.</p>
-      <codeblock>&lt;hazardstatement type="danger">
+      <!--<p>In the following code sample, the <xmlelement>hazardsymbol</xmlelement> is contained by the <xmlelement>messagepanel</xmlelement> element. By default, this markup also associates the <xmlelement>hazardsymbol</xmlelement> element with the <xmlelement>typeofhazard</xmlelement> element. This markup can be useful when migrating hazard statements from earlier versions to DITA 2.0.</p>-->
+      <!--<codeblock>&lt;hazardstatement type="danger">
   &lt;messagepanel>
     &lt;typeofhazard>Rotating blade&lt;/typeofhazard>
     &lt;consequence>Moving parts can crush and cut.&lt;/consequence>
     &lt;howtoavoid>Follow lockout procedure before servicing.&lt;/howtoavoid>
     <b>&lt;hazardsymbol keyref="hazard-rotatingblade"/></b>
   &lt;/messagepanel>
-&lt;/hazardstatement></codeblock></example>
+&lt;/hazardstatement></codeblock>--></example>
 </refbody>
 </reference>
 
diff --git a/specification/langRef/base/howtoavoid.dita b/specification/langRef/base/howtoavoid.dita
@@ -21,11 +21,11 @@ not use solvents to clean the drum surface."</shortdesc>
       <p conkeyref="reuse-attributes/only-universal"/>
     </section>
 <example id="example" otherprops="examples"><title>Example</title>
-      <p>The following code sample shows a hazard statement with the signal
-        word of "NOTICE", which is reserved for situations that only
-        involve possible property damage or other undesirable states. The
-          <xmlelement>howtoavoid</xmlelement> element provides instructions
-        about how to avoid the undesirable state:</p>
+      <p>The following code sample shows the markup for a hazard statement
+        that warns about possible damage to machinery. The
+          <xmlelement>howtoavoid</xmlelement> element provides specific
+        information about what the reader needs to do to avoid the
+        hazard.</p>
       <codeblock>&lt;hazardstatement type="notice">
   &lt;messagepanel>
     &lt;typeofhazard>
@@ -39,8 +39,7 @@ not use solvents to clean the drum surface."</shortdesc>
       &lt;/ul>
     <b>&lt;/howtoavoid></b>
   &lt;/messagepanel>
-&lt;/hazardstatement></codeblock>
-      <!--<p>Note that the hazard symbol is explicitly associated with the <xmlelement>howtoavoid</xmlelement> element.</p>--></example>
+&lt;/hazardstatement></codeblock></example>
 </refbody>
 </reference>
 
diff --git a/specification/langRef/base/messagepanel.dita b/specification/langRef/base/messagepanel.dita
@@ -2,11 +2,11 @@
 <!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
 <reference id="messagepanel" xml:lang="en-us">
 <title><xmlelement>messagepanel</xmlelement></title>
-<shortdesc>The <xmlelement>messagepanel</xmlelement> element contains
-the textual information that is displayed on the hazard statement.
-This information identifies the hazard, specifies how to avoid the
-hazard, and states the probable consequences of failing to avoid the
-hazard.</shortdesc>
+<shortdesc>The <xmlelement>messagepanel</xmlelement> element contains the
+    textual information that is displayed on the hazard statement. This
+    information identifies the hazard, specifies how to avoid the hazard,
+    states the probable consequences of failing to avoid the hazard, and
+    might specify one or more images.</shortdesc>
 <prolog><metadata>
 <keywords>
         <indexterm>hazard statement
@@ -23,42 +23,8 @@ hazard.</shortdesc>
       <p conkeyref="reuse-attributes/universal-compact"/>
     </section>
 <example id="example" otherprops="examples"><title>Example</title>
-      <p>The following code sample generates an ANSI Z535.6 grouped safety message that specifies
-        information about multiple hazards.</p>
-      <codeblock>&lt;hazardstatement type="warning">
-  <b>&lt;messagepanel></b>
-    &lt;typeofhazard>
-      &lt;hazardsymbol keyref="hazard-electricshock"/>
-      ELECTRIC SHOCK HAZARD&lt;/typeofhazard>
-      &lt;consequence>The equipment must be grounded. Improper grounding, setup, or usage of
-                    the system can cause electric shock
-      &lt;/consequence>
-      &lt;howtoavoid>
-        &lt;hazardsymbol keyref="hazard-groundpowersource"/>
-        &lt;ul>
-          &lt;li>Turn off and disconnect power at main switch before disconnecting any
-              cables or before servicing or installing any equipment.&lt;/li>
-          &lt;li>Connect only to grounded power sources.&lt;/li>
-          &lt;li>All electric wiring must be done by a qualified electrician and comply
-              with all local codes and regulations.&lt;/li>
-        &lt;/ul>
-      &lt;/howtoavoid>
-    <b>&lt;/messagepanel></b>
-    &lt;!-- ... -->
-    <b>&lt;messagepanel></b>
-      &lt;typeofhazard>
-        &lt;hazardsymbol keyref="hazard-hotsurface"/>
-        BURN HAZARD&lt;/typeofhazard>
-        &lt;consequence>Electric sufaces and fluid can become very hot during
-                    operation.&lt;/consequence>
-        &lt;howtoavoid>
-          To avoid burns:
-          &lt;ul>
-            &lt;li>Do not touch hot fluid or equipment.&lt;/li>
-          &lt;/ul>
-        &lt;/howtoavoid>
-  <b>&lt;/messagepanel></b>
-&lt;/hazardstatement></codeblock></example>
+      <p>See <xref keyref="elements-hazardstatement/example"
+            ><xmlelement>hazardstatement</xmlelement>.</xref></p></example>
 </refbody>
 </reference>
 
diff --git a/specification/langRef/base/typeofhazard.dita b/specification/langRef/base/typeofhazard.dita
@@ -20,9 +20,8 @@ a description of the type of hazard, for example, "Hot surfaces inside."</shortd
       <p conkeyref="reuse-attributes/only-universal"/>
     </section>
 <example id="example" otherprops="examples"><title>Example</title>
-      <p>The following code sample generates a "CAUTION" hazard statement,
-        which warns users against lifting heavy objects without referring
-        to the product safety manual:</p>
+      <p>The following code sample shows the markup for a hazard statement
+        that warns about a lifting hazard:</p>
       <codeblock>&lt;hazardstatement type="caution">
   &lt;messagepanel>
     <b>&lt;typeofhazard></b>

diff --git a/specification/langRef/containers/hazard-d.dita b/specification/langRef/containers/hazard-d.dita
@@ -6,9 +6,10 @@
     <!--<shortdesc>The hazard statement domain contains the <xmlelement>hazardstatement</xmlelement> element, which can be used to provide information about product safety hazards. The domain can be included in any topic type or map. Hazard statements are used to inform readers about potential hazards, consequences, and avoidance strategies. </shortdesc>-->
     <shortdesc>The <xmlelement>hazardstatement</xmlelement> domain adds
       markup to support hazard statements. It is based on the regulations
-      of ANSI Z535 and ISO 3864. The domain enables authors to select the
-      signal word, describe the hazard and its consequences, explain how to
-      avoid it, and add one or more safety images.</shortdesc>
+      of ANSI Z535 and ISO 3864. The domain enables authors to provide all
+      the information necessary for a hazard statement: a signal word,
+      description of the hazard and its consequences, how to avoid the
+      hazard, and one or more images.</shortdesc>
   </abstract>
 <prolog><metadata>
 <keywords><indexterm>domains<indexterm>hazard statement</indexterm></indexterm>