PDF and DITA source attached. Happy to take comments in e-mail or oXygen-tracked-changes DITA source. I'm hoping to get this in front of the TC on the 17 September meeting, so I'm setting a deadline of next Monday, 16 September. Start rather than the end of the day, please! Dawn, Scott is the office stage two reviewer, but I very much hope that you will have time to review also. Amber and Jang, as other interested parties, I'd be very interested in your feedback as well. -- Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting
www.eberleinconsulting.com +1 919 622-1501; kriseberlein (skype) <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd"> <reference id="issue64-stage-two" xml:lang="en-us"> <title>Stage two: #164 Redesign <xmlelement>hazardstatement</xmlelement></title> <shortdesc>Redesign the hazard statement domain to better support current standards, authoring requirements, and rendering requirements.</shortdesc> <refbody> <section> <title>Date and version information</title> <p>This proposal contains the following information:<dl> <dlentry> <dt>Date that this feature proposal was completed</dt> <dd>10 September 2019</dd> </dlentry> <dlentry> <dt>Champion of the proposal</dt> <dd>Kristen James Eberlein, Eberlein Consulting LLC</dd> </dlentry> <dlentry> <dt>Links to any previous versions of the proposal</dt> <dd>Not applicable</dd> </dlentry> <dlentry> <dt>Links to minutes where this proposal was discussed at stage 1 and moved to stage 2</dt> <dd><xref href="
https://lists.oasis-open.org/archives/dita/201908/msg00082.html" ; format="html" scope="external">20 August 2019</xref><p>In addition, this proposal was discussed (a request for early feedback) at the following TC meetings:</p><ul> <li>03 September 2019</li> <li>10 September 2019</li> </ul></dd> </dlentry> <dlentry> <dt>Reviewers for Stage 2 proposal</dt> <dd> <p>The official stage 2 reviewers are as follows:</p> <sl> <sli>Scott Hudson</sli> <sli>Dawn Stevens</sli> </sl> <p>In addtion, the following individuals were asked for feedback on this proposal:</p> <sl> <sli>Jang Graat, Former individual member</sli> <sli>Amber Swope, Individual member</sli> </sl> </dd> </dlentry> <dlentry> <dt>Links to e-mail discussion that resulted in new versions of the proposal</dt> <dd>Not applicable</dd> </dlentry> <dlentry> <dt>Link to the GitHub issue</dt> <dd><xref href="
https://github.com/oasis-tcs/dita/issues/164" ; format="html" scope="external">Issue #64</xref></dd> </dlentry> </dl></p> </section> <section> <title>Original requirement or use case</title> <!--<p>Include a literal copy of the original requirement or use case that was presented to the TC; be sure to include the date that it was presented to the TC.</p>--> <p>In May 2018, the following TC members suggested changes to the hazard statement domain for DITA 2.0:</p> <ul> <li>Jang Graat, Individual member (no longer an OASIS member)</li> <li>Dawn Stevens, Comtech Services, Inc.</li> <li>Amber Swope, Individual member</li> </ul> <p>All three TC members were motivated to improve the hazard statement domain by increasing its alignment with various safety standards; in addition, they wanted to make it easier for content developers to use and better able to support rendering requirements.</p> <p>In August and September 2019, after a careful study of existing safety standards and the changes suggested by DITA TC members and the larger DITA community, I presented various options to the TC and developed consensus on the solution that is outlined in this proposal.</p> </section> <section> <title>Use cases</title> <p>This proposal will enable hazard statements authored in DITA to meet the following objectives:</p> <dl> <dlentry> <dt>Better comply with the ANSI Z535.6 standard</dt> <dd> <p>While the ANSI Z535.6 standard provides great flexibilty for companies to implement its recommendations, it does provide strict requirements for safety alert symbols and signal words.</p> <p>ANSI Z535.6 defines a <term>signal word</term> as a <q>word that calls attention to a safety message or messages or a property damage message or messages, and designates a degree or level of hazard seriousness.</q> The standard only permits four signal words: <keyword>DANGER</keyword>, <keyword>WARNING</keyword>, <keyword>CAUTION</keyword>, and <keyword>NOTICE</keyword>.</p> <p>The <xmlatt>type</xmlatt> attribute on the <xmlelement>hazardstatement</xmlelement> element specifies the signal word. For DITA 1.2 and 1.3, the values of the <xmlatt>type</xmlatt> attribute are identical to those permitted on <xmlelement>note</xmlelement>. That allows a lot of values that are not germane for hazard statements and so can introduce authoring dissonance.</p> </dd> </dlentry> <dlentry> <dt>Improve the semantic nature of the specialization base</dt> <dd> <p>Currently, <xmlelement>hazardstatement</xmlelement> is specialized from <xmlelement>ul</xmlelement>, and its child elements are specialized from <xmlelement>li</xmlelement>. This specialization hierachy does not make sense.</p> </dd> </dlentry> <dlentry> <dt>Enable hazard images to be associated with <xmlelement>messagepanel</xmlelement> and its child elements</dt> <dd> <p>Currently, the hazard images are part of the content model for the <xmlelement>hazardstatement</xmlelement> element. This presents a problem when the <xmlelement>hazardstatement</xmlelement> element contains multiple <xmlelement>messagepanel</xmlelement> elements; there is no way to determine which hazard images are associated with specific message panels ?? nor can it be determined <i>what</i> the hazard image represents: <xmlelement>typeofhazard</xmlelement>, <xmlelement>consequence</xmlelement>, or <xmlelement>howtoavoid</xmlelement>.</p> </dd> </dlentry> <dlentry> <dt>Simplify the authoring experience</dt> <dd> <p>Currently, the fixed order of the child elements within <xmlelement>messagepanel</xmlelement> forces some authors to author content in a different order than it will be rendered and read by consumers. This can be counter intuitive.</p> <p>Also, often authors must use a value for the <xmlatt>outputclass</xmlatt> attribute in order to indicate how a list in the <xmlelement>howtoavoid</xmlelement> element should be rendered. This makes the authoring process harder than it needs to be.</p> </dd> </dlentry> <dlentry> <dt>Simplify the work of CSS and stylesheet developers</dt> <dd> <p>Many implementations must use transformations, CSS, and stylesheets to swap the order of the <xmlelement>consequence</xmlelement> and <xmlelement>howtoavoid</xmlelement> elements. This can be burdensome to small implementations, and it can easily be avoided by relaxing the content model of <xmlelement>messagepanel</xmlelement>.</p> <p>Currently, many implementations rely on CSS and style sheets to render the simple list allowed within <xmlelement>howtoavoid</xmlelement> as either an ordered or unordered list. Allowing <xmlelement>ol</xmlelement> and <xmlelement>ul</xmlelement> within <xmlelement>howtoavoid</xmlelement> will eliminate this extra work.</p> </dd> </dlentry> </dl> </section> <section rev="2.0"> <title>New terminology</title> <p>Not applicable</p> </section> <section> <title>Proposed solution</title> <ul id="stage-2-technical-requirements"> <li>Restrict the values of the <xmlatt>type</xmlatt> attribute on <xmlelement>hazardstatement</xmlelement> to <keyword>danger</keyword>, <keyword>caution</keyword>, <keyword>warning</keyword>, <keyword>notice</keyword>, and <keyword>-dita-use-conref-target</keyword>; require the <xmlatt>type</xmlatt> attribute.</li> <li>Improve the element-reference topic for <xmlelement>hazardstatement</xmlelement> to include definitions of the values for the <xmlatt>type</xmlatt> attribute that match those in the ANSI Z535.6 standard. The following definition descriptions are taken verbatim from ANSI Z535.6:<dl> <dlentry> <dt><xmlatt>danger</xmlatt></dt> <dd>Indicates a hazardous situation that, if not avoided, will result in death or serious injury. This signal word is to be limited to the most extreme situations.</dd> </dlentry> <dlentry> <dt><xmlatt>warning</xmlatt></dt> <dd>Indicates a hazardous situation that, if not avoided, could result in death or serious injury.</dd> </dlentry> <dlentry> <dt><xmlatt>caution</xmlatt></dt> <dd>Indicates a hazardous situation that, if not avoided, could result in minor or moderate injury.</dd> </dlentry> <dlentry> <dt><xmlatt>notice</xmlatt></dt> <dd>Indicates information considered important, but not hazard-related (e.g. messages relating to property damage).</dd> </dlentry> </dl><p><b>Note</b> that the DITA spec will not use these definitions verbatim. They will be edited to match our style guidelines.</p></li> <li>Expand the content model of <xmlelement>messagepanel</xmlelement> to enable greater flexibility in the order of the child elements. While <xmlelement>typeofhazard</xmlelement> will remain required and the first child of <xmlelement>messagepanel</xmlelement>, it now can be followed by either of the following:<ul> <li><xmlelement>consequence</xmlelement> (zero or more), <xmlelement>howtoavoid</xmlelement> (one or more)</li> <li><xmlelement>howtoavoid</xmlelement> (one or more), <xmlelement>consequence</xmlelement> (zero or more)</li> </ul></li> <li>Expand the content model of <xmlelement>howtoavoid</xmlelement> to permit <xmlelement>ol</xmlelement> and <xmlelement>ul</xmlelement>, in addition to <xmlelement>sl</xmlelement></li> <li>Change the specialization base of <xmlelement>messagepanel</xmlelement>, <xmlelement>typeofhazard</xmlelement>, <xmlelement>consequence</xmlelement>, and <xmlelement>howtoavoid</xmlelement> to <xmlelement>div</xmlelement></li> <li>Add <xmlelement>hazardsymbol</xmlelement> to the content models of <xmlelement>messagepanel</xmlelement>, <xmlelement>typeofhazard</xmlelement>, <xmlelement>consequence</xmlelement>, and <xmlelement>howtoavoid</xmlelement></li> <li>Remove <xmlelement>hazardsymbol</xmlelement> from the content model of <xmlelement>hazardstatement</xmlelement></li> </ul> </section> <section> <title>Benefits</title> <p>This proposal addresses the following questions:<dl> <dlentry> <dt>Who will benefit from this feature?</dt> <dd> <p>The following will benefit from this redesign:</p> <ul> <li>All DITA implementations that use the hazard statement domain</li> <li>DITA implementations that do not use the hazard statement domain due to concerns that the hazard statement domain is inadequate, difficult to use, or difficult to render</li> <li>Companies whose documentation requires hazard statements but who have not migrated to DITA due to concerns that the hazard statement domain is inadequate, difficult to use, or difficult to render</li> </ul> </dd> </dlentry> <dlentry> <dt>What is the expected benefit?</dt> <dd>A hazard statement domain that is easier to use and and easier to render</dd> </dlentry> <dlentry> <dt>How many people probably will make use of this feature?</dt> <dd>Unknown</dd> </dlentry> <dlentry> <dt>How much of a positive impact is expected for the users who will make use of the feature?</dt> <dd>Significant</dd> </dlentry> </dl></p> </section> <section> <title>Technical requirements</title> <p>This proposal involves the following changes:</p> <dl> <dlentry> <dt>Refactoring an element</dt> <!--<dd>Include the current and new names of the element, the module that defines the element, and (if a domain element) the default document type shells that will be affected. If any other changes will be made to the element (new / removed attributes, modified content model, changed specialization ancestry) list those as well.</dd>--> <dd> <ul> <li><xmlelement>hazardstatement</xmlelement><ul> <li>Remove several values for the <xmlatt>type</xmlatt> attribute</li> <li>Make the <xmlatt>type</xmlatt> attribute required</li> <li>Remove <xmlelement>hazardsymbol</xmlelement> from the content model</li> </ul></li> <li><xmlelement>messagepanel</xmlelement><ul> <li>Modify content model to enable better flexibility regarding the order of elements</li> <li>Add <xmlelement>hazardsymbol</xmlelement> (zero or more) to the content model</li> <li>Change specialization base to <xmlelement>div</xmlelement></li> </ul></li> <li><xmlelement>typeofhazard</xmlelement><ul> <li>Add <xmlelement>hazardsymbol</xmlelement> (zero or more) to the content model</li> <li>Change specialization base to <xmlelement>div</xmlelement></li> </ul></li> <li><xmlelement>consequence</xmlelement><ul> <li>Add <xmlelement>hazardsymbol</xmlelement> (zero or more) to the content model</li> <li>Change specialization base to <xmlelement>div</xmlelement></li> </ul></li> <li><xmlelement>howtoavoid</xmlelement><ul> <li>Add <xmlelement>ol</xmlelement> and <xmlelement>ul</xmlelement> to the content model</li> <li>Add <xmlelement>hazardsymbol</xmlelement> (zero or more) to the content model</li> <li>Change specialization base to <xmlelement>div</xmlelement></li> </ul></li> </ul> </dd> </dlentry> <dlentry> <dt>Processing impact</dt> <dd>Not applicable</dd> </dlentry> </dl> <p> <dl> <dlentry> <dt>Overall usability</dt> <dd>Improved usability for current and future users.</dd> </dlentry> </dl> </p> </section> <section rev="2.0"> <title>Backwards compatibility</title> <p>This proposal addresses the following questions:</p> <dl> <dlentry> <dt>Was this change previously announced in an earlier version of DITA?</dt> <dd>No</dd> </dlentry> <dlentry> <dt>Removing a document type that was shipped in DITA 1.3?</dt> <dd>No</dd> </dlentry> <dlentry> <dt>Removing a domain that was shipped in DITA 1.3?</dt> <dd>No</dd> </dlentry> <dlentry> <dt>Removing a domain from a document type shell was shipped in DITA 1.3?</dt> <dd>No</dd> </dlentry> <dlentry> <dt>Removing or renaming an element that was shipped in DITA 1.3?</dt> <dd>No</dd> </dlentry> <dlentry> <dt>Removing or renaming an attribute that was shipped in DITA 1.3?</dt> <dd>No</dd> </dlentry> <dlentry> <dt>Changing the meaning of an element or attribute in a way that would disallow existing usage?</dt> <dd>Yes ?? Removing values for the <xmlatt>type</xmlatt> attribute on <xmlelement>hazardstatement</xmlelement> that were allowed in DITA 1.2 and 1.3.</dd> </dlentry> <dlentry> <dt>Changing a content model by removing something that was previously allowed, or by requiring something that was not?</dt> <dd> <p>Yes ?? Removing <xmlelement>hazardsymbol</xmlelement> from the content model of <xmlelement>hazardstatement</xmlelement></p> <p>Yes ?? Making the <xmlatt>type</xmlatt> attribute required on <xmlatt>hazardstatement</xmlatt></p> </dd> </dlentry> <dlentry> <dt>Changing specialization ancestry?</dt> <dd>Yes ?? As follows:</dd> <dd> <simpletable relcolwidth="1.5* 3* 2*" keycol="1" frame="all"> <sthead> <stentry>Element</stentry> <stentry>DITA 1.3</stentry> <stentry>DITA 2.0</stentry> </sthead> <strow> <stentry><xmlelement>consequence</xmlelement></stentry> <stentry><codeph>"+ topic/li hazard-d/consequence "</codeph></stentry> <stentry><codeph>"+ topic/div hazard-d/consequence "</codeph></stentry> </strow> <strow> <stentry><xmlelement>howtoavoid</xmlelement></stentry> <stentry><codeph>"+ topic/li hazard-d/howtoavoid "</codeph></stentry> <stentry><codeph>"+ topic/div hazard-d/howtoavoid "</codeph></stentry> </strow> <strow> <stentry><xmlelement>messagepanel</xmlelement></stentry> <stentry><codeph>"+ topic/ul hazard-d/messagepanel "</codeph></stentry> <stentry><codeph>"+ topic/div hazard-d/messagepanel "</codeph></stentry> </strow> <strow> <stentry><xmlelement>typeofhazard</xmlelement></stentry> <stentry><codeph>"+ topic/li hazard-d/typeofhazard "</codeph></stentry> <stentry><codeph>"+ topic/div hazard-d/typeofhazard "</codeph></stentry> </strow> </simpletable> </dd> </dlentry> <dlentry> <dt>Removing or replacing a processing feature that was defined in DITA 1.3?</dt> <dd>No</dd> </dlentry> <dlentry> <dt>Are element or attribute groups being renamed or shuffled?</dt> <dd>No</dd> </dlentry> </dl> </section> <section rev="2.0"> <title>Migration plan</title> <p>This proposal addresses the following questions:</p> <dl> <dlentry> <dt>Might any existing documents need to be migrated?</dt> <dd> <p>Yes, implementations will need to rework <xmlelement>hazardstatement</xmlelement> elements to relocate <xmlelement>hazardsymbol</xmlelement> elements.</p> <p>Yes, if existing DITA topics use values of <xmlatt>type</xmlatt> on <xmlelement>hazardstatement</xmlelement> that are removed.</p> <p>Yes, if existing DITA topics contain <xmlelement>hazardstatement</xmlelement> elements that do not set the <xmlatt>type</xmlatt> attribute.</p> </dd> </dlentry> <dlentry> <dt>Might any existing processors or implementations need to change their expectations?</dt> <dd> <p>Authoring tools might need to change the CSS or XSLT that is used to render hazard statements.</p> <p>Implementations might need to adjust their stylesheets for rendering output.</p> </dd> </dlentry> <dlentry> <dt>Might any existing specialization or constraint modules need to be migrated?</dt> <dd>(Unlikely) If an implementation has specialized elements from the hazard statement domain, it might need to modify their specialization modules.</dd> </dlentry> <dlentry> <dt>If no migration need is anticipated, why not?</dt> <dd>Not applicable</dd> </dlentry> </dl> </section> <section> <title>Costs</title> <p>This proposal has a (time and effort) impact on the following groups:</p> <dl> <dlentry> <dt>Maintainers of the grammar files</dt> <dd> <ul> <li>(DTD) Edits to <filepath>hazardstatementDomain.mod</filepath> and <filepath>hazardstatementDomain.ent</filepath></li> <li>(RNG) Edits to <filepath>hazardstatementDomain.rng</filepath></li> </ul> </dd> </dlentry> <dlentry> <dt>Editors of the DITA specification</dt> <dd> <p>The changes to the DITA specification will be minor to medium:</p> <ul> <li>Editorial changes to the <xmlelement>hazardstatement</xmlelement> topic to specify values for <xmlatt>type</xmlatt></li> <li>Updates to the "Specialization hierarchy" sections for the <xmlelement>messagepanel</xmlelement>, <xmlelement>typeofhazard</xmlelement>, <xmlelement>consequence</xmlelement>, and <xmlelement>howtoavoid</xmlelement> topics</li> <li>Changes to the "Example" sections in the <xmlelement>hazardstatement</xmlelement>, <xmlelement>messagepanel</xmlelement>, <xmlelement>typeofhazard</xmlelement>, <xmlelement>consequence</xmlelement>, and <xmlelement>howtoavoid</xmlelement> topics</li> <li>Updates to the "Usage information" section in the <xmlelement>messagepanel</xmlelement> topic, to explain meaning of <xmlelement>hazardsymbol</xmlelement> as direct child of <xmlelement>messagepanel</xmlelement></li> </ul> <p>The entire topic collection for the hazard statement domain is overdue for an edit, but that should be handled separately from this proposal. We should consider providing more information about formatting expectations for elements in the hazard statement domain.</p> <p>No changes to the information architecture or specification terminology will be required.</p> </dd> </dlentry> <dlentry> <dt>Vendors of tools</dt> <dd> <p>Authoring tools that render the <xmlelement>hazardstatement</xmlelement> element will need to modify the CSS or XSLT that renders the element.</p> <p>Applications that style the <xmlelement>hazardstatement</xmlelement> element in output formats will need to modify their stylesheets.</p> </dd> </dlentry> <dlentry> <dt>DITA community-at-large</dt> <dd>The changes to the hazard statement domain should not add to a perception of DITA complexity. The changes should be simple and intuitive for end users to understand.</dd> </dlentry> <dlentry> <dt>Producing migration instructions or tools</dt> <dd> <p>Migration instructions will be straight forward.</p> </dd> </dlentry> </dl> </section> <section> <title>Examples</title> <p>This section provides examples of the new markup.</p> <fig> <title>Loosening content model of <xmlelement>messagepanel</xmlelement> and <xmlelement>howtoavoid</xmlelement></title> <p>The following code sample illustrates the following:</p> <ul> <li>Increased flexibility for the content model of <xmlelement>messagepanel</xmlelement></li> <li>Use of an unordered list within the <xmlelement>howtoavoid</xmlelement> element</li> </ul> <codeblock><hazardstatement type="danger"> <messagepanel> <typeofhazard>HAZARD OF ELECTRIC SHOCK, EXPLOSION, OR ARC FLASH</typeofhazard> <howtoavoid> <ul> <li>Reinstall the inner cover in the bottom of the battery breaker box before proceeding. </li> <li>Ensure correct polarity.</sli> </ul> </howtoavoid> <consequence>Failure to follow these instructions will result in death or serious injury. </consequence> </messagepanel> </hazardstatement></codeblock> <p>This markup might be rendered as the following:</p> <image placement="break" href="images/hazardstatement-1.png"/> <p>This is an actual screen capture from the Schneider Electric installation instructions for <xref href="
https://www.productinfo.schneider-electric.com/portals/ui/galaxyvx_iec/viewer/5ac76f6946e0fb00011d39f9/5ac76f9246e0fb00011d3e6b/r/ConnectthePowerandSignalCablesTSK_0000116630" ; format="html" scope="external">Gallery XV Battery Breaker Box</xref>, taken in August 2019.</p> <p><b>Note</b> that the company currently must override the HTML transformation to get the desired rendering; the changes that we are implementing for DITA 2.0 will make that override unnecessary.</p> </fig> <fig> <title>Adding <xmlelement>hazardsymbol</xmlelement> to <xmlelement>typeofhazard</xmlelement>, <xmlelement>consequence</xmlelement>, and <xmlelement>howtoavoid</xmlelement></title> <p>The following code sample illustrates how a company could use a <xmlelement>hazardstatement</xmlelement> element to generate what ANSI Z535.6 calls a "grouped safety message":</p> <codeblock><hazardstatement type="warning"> <messagepanel> <typeofhazard> <hazardsymbol keyref="electric-shock-hazard"/> ELECTRIC SHOCK HAZARD</typeofhazard> <consequence>The equipment must be grounded. Improper grounding, setup, or usage of the system can cause electric shock </consequence> <howtoavoid> <hazardsymbol keyref="ground-power-source"/> <ul> <li>Turn off and disconnect power at main switch before disconnecting any cables or before servicing or installing any equipment.</li> <li>Connect only to grounded power sources.</li> <li>All electric wiring must be done by a qualified electrician and comply with all local codes and regulations.</li> </ul> </howtoavoid> </messagepanel> ... <messagepanel> <typeofhazard> <hazardsymbol keyref="burn-hazard"/> BURN HAZARD</typeofhazard> <consequence>Electric sufaces and fluid that's heated can become very hot during operation.</consequence> <howtoavoid> To avoid burns: <ul> <li>Do not touch hot fluid or equipment.</li> </ul> </howtoavoid> </messagepanel> </hazardstatement></codeblock> <p>This markup might be rendered as the following:</p> <image placement="break" href="images/grouped-safety-message.png" scale="130"/> </fig> <fig> <title>Adding <xmlelement>hazardsymbol</xmlelement> to <xmlelement>messagepanel</xmlelement></title> <p>The following code sample illustrates how <xmlelement>messagepanel</xmlelement> will be able to contain <xmlelement>hazardsymbol</xmlelement>. This will be useful for companies as they migrate from the old to new content models.</p> <codeblock><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> <hazardsymbol keyref="general-warning"/> </messagepanel> </hazardstatement></codeblock> </fig> <!--<p>Provide examples of the proposed feature. Include an example for each of the use cases. Be sure to include edge cases, if known.</p>--> </section> </refbody> </reference> Attachment: Issue164-RedesignHazardstatement.pdf Description: Adobe PDF document