From 56f24194a3f05e1f654ce7e0038a456f98ad1210 Mon Sep 17 00:00:00 2001
From: "Robert D. Anderson" <robert.dan.anderson@oracle.com>
Date: Tue, 2 Jul 2024 16:56:18 -0500
Subject: [PATCH] Add warning about 2 titles to example topic

---
 .../common/reuse-w-lwdita/reuse-example.dita  | 20 ++++++++++++++++++-
 specification/langRef/base/example.dita       |  2 ++
 2 files changed, 21 insertions(+), 1 deletion(-)

diff --git a/specification/common/reuse-w-lwdita/reuse-example.dita b/specification/common/reuse-w-lwdita/reuse-example.dita
index 8a1818ef..e33bd9d9 100644
--- a/specification/common/reuse-w-lwdita/reuse-example.dita
+++ b/specification/common/reuse-w-lwdita/reuse-example.dita
@@ -4,7 +4,25 @@
 <title><xmlelement>example</xmlelement></title>
   <shortdesc id="shortdesc" platform="dita lwdita">An example illustrates
     the subject of the topic or a portion of the topic.</shortdesc>
-<refbody><!--<section id="usage-information"><title>Usage information</title><p platform="dita">Use <xmlelement>example</xmlelement> to contain both sample code (or similar artifacts) and the discussion that illustrates the sample. For example, a topic about programming code could use the <xmlelement>example</xmlelement> element to contain both the sample code and the text that describes the code.</p><p platform="lwdita">Use the example component to contain both sample code (or similar artifacts) and the discussion that illustrates the sample. For example, a topic about programming code could use the example component to contain both the sample code and the text that describes the code.</p></section>-->
+<refbody>
+    <section id="usage-information">
+      <title>Usage information</title>
+      <p>For maximum flexibility in creating specializations, examples allow
+        plain text as well as phrase and block level elements. Because of the way XML grammars are
+        defined within a DTD, any element that allows plain text cannot restrict the order or
+        frequency of other elements. As a result, the <xmlelement>example</xmlelement> element
+        allows <xmlelement>title</xmlelement> to appear anywhere as a child of
+          <xmlelement>example</xmlelement>. However, the intent of the specification is that
+          <xmlelement>title</xmlelement> only be used once in any <xmlelement>example</xmlelement>,
+        and when used, that it precede any other text or element content.</p>
+    </section>
+    <section id="rendering-expectations">
+      <title>Rendering expectations</title>
+      <p platform="dita" outputclass="errorcondition">Processors <term outputclass="RFC-2119"
+          >SHOULD</term> treat the presence of more than one <xmlelement>title</xmlelement> element
+        in a <xmlelement>example</xmlelement> element as an error.</p>
+      <!--<p platform="lwdita" outputclass="errorcondition">Processors <term outputclass="RFC-2119">SHOULD</term> treat the presence of more than one title component in an example component as an error.</p>-->
+    </section>
     <section id="attributes">
       <title>Attributes</title>
       <p conkeyref="reuse-attributes/only-universal" platform="dita"/>
diff --git a/specification/langRef/base/example.dita b/specification/langRef/base/example.dita
index 55077b49..71256aa5 100644
--- a/specification/langRef/base/example.dita
+++ b/specification/langRef/base/example.dita
@@ -8,6 +8,8 @@
 </keywords>
 </metadata></prolog>
 <refbody>
+  <section conkeyref="reuse-example/usage-information" id="usage-information"/>
+  <section conkeyref="reuse-example/rendering-expectations" id="rendering-expectations"/>
     <section conkeyref="reuse-example/attributes" id="attributes"/>
 <example id="example" otherprops="examples"><title>Example</title>
       <p>The following code sample shows an <xmlelement>example</xmlelement> element that contains a