From 47f2e275119eceb643b2cbc089d2a7bd2aab9027 Mon Sep 17 00:00:00 2001
From: Steven Clontz <steven.clontz@gmail.com>
Date: Fri, 31 May 2024 13:22:27 -0500
Subject: [PATCH] Guide: update commentary on "commentary" element (PR #2166)

---
 doc/guide/publisher/instructor-version.xml | 9 ++-------
 1 file changed, 2 insertions(+), 7 deletions(-)

diff --git a/doc/guide/publisher/instructor-version.xml b/doc/guide/publisher/instructor-version.xml
index 821baa837..89b4f6c7d 100644
--- a/doc/guide/publisher/instructor-version.xml
+++ b/doc/guide/publisher/instructor-version.xml
@@ -27,17 +27,12 @@
     <section>
         <title>Notes and Commentary</title>
 
-        <p>The <tag>commentary</tag> element is designed primarily for the purpose of adding material to a document to make an enhanced version.  It is similar in many ways to a <tag>paragraphs</tag> in that it can be placed within any division and must be titled.  The main difference is that it is not displayed by default, so you must set a processing switch to enable its appearance.  In the project manifest inside your desired target, add the following.
+        <p>The <tag>commentary</tag> element is designed primarily for the purpose of adding material to a document to make an enhanced version (see <xref ref="publisher-versions"/>).  It is similar in many ways to a <tag>paragraphs</tag> in that it can be placed within any division and must be titled.
         </p>
-        <pre>
-        <![CDATA[
-            <stringparam key="commentary" value="yes"/>
-            ]]>
-        </pre>
 
         <p>
         Other distinctions are:<ul>
-            <li>Since it is elective, you need to be careful about cross-references to and from a <tag>commentary</tag>.  It is highly likely that you will want to make cross-references <em>within</em> a <tag>commentary</tag> <em>pointing to</em> other portions of your text, and this is always a good idea.  You will want to avoid making cross-references <em>to</em> a <tag>commentary</tag> from other parts of the text, with the exception of a cross-reference that originates <em>within</em> some <tag>commentary</tag>.</li>
+            <li>Since it is often elective, you need to be careful about cross-references to and from a <tag>commentary</tag>.  It is highly likely that you will want to make cross-references <em>within</em> a <tag>commentary</tag> <em>pointing to</em> other portions of your text, and this is always a good idea.  You will want to avoid making cross-references <em>to</em> a <tag>commentary</tag> from other parts of the text, with the exception of a cross-reference that originates <em>within</em> some <tag>commentary</tag>.</li>
             <li>Numbered items are prohibited within a <tag>commentary</tag>, such as a <tag>figure</tag> or a <tag>theorem</tag>.  Doing so would disrupt consecutive numbering in different versions, with or without, <tag>commentary</tag> included.  Numbered equations are not prohibited in the schema, but should definitely be avoided anyway.</li>
         </ul></p>
     </section>