Deprecate the use of pre@source in datafiles

doc/guide/author/topics.xml

@@ -3866,7 +3866,7 @@
         <paragraphs>
             <title>Text as Data Files</title>
 
-            <p>Inside of a <tag>datafile</tag> place an <tag>pre</tag> element.  There are then two options: provide the contents of the text file right in your source <pretext/> file, as you might for other preformatted text, or supply a <attr>source</attr> attribute whose value is the name of an external text file you provide.  The former is appropriate for <q>toy</q> examples, while the latter may be used for <q>serious</q> files with many lines, or with long lines.  Note that if you provide the file as the content of the <tag>pre</tag> element, it can be indented to match your source file indentation, and will undergo some manipulation, such as removing leading whitespace, and ensuring a final newline, but preserving any <em>relative</em> indentation.  If provided via a <attr>source</attr> attribute, there is no manipulation.</p>
+            <p>Inside of a <tag>datafile</tag> place an <tag>pre</tag> element. There are then two options: provide the contents of the text file right in your source <pretext/> file, as you might for other preformatted text, or use a <tag>xi:include</tag> element to include the external text file you provide.  The former is appropriate for <q>toy</q> examples, while the latter may be used for <q>serious</q> files with many lines, or with long lines.  Note that if you provide the file as the content of the <tag>pre</tag> element, it can be indented to match your source file indentation, and will undergo some manipulation, such as removing leading whitespace, and ensuring a final newline, but preserving any <em>relative</em> indentation. If provided via a <tag>xi:include</tag> tag, any spacing in front of that tag will be preserved and the contents of the linked file will not be indented to match it, so you may prefer to place that tag at the same line as the enclosing <tag>pre</tag> tag to avoid any extra spacing at the start.</p>
 
             <p>Such a text file may be declared editable by the reader, presumably to allow them to witness the resulting behavior of a some employing program.  The <attr>rows</attr> and <attr>cols</attr> attributes describe the viewport into the file provided in the <init>HTML</init> output.  Typically scrollbars will allow the reader to survey all of a large file.  In static outputs, the first few lines are shown, given by the value of <attr>rows</attr>, and lines are truncated according to the value of <attr>cols</attr>.</p>
         </paragraphs>

examples/sample-book/rune.xml

@@ -874,7 +874,7 @@ TEST_CASE( "Test the add function" ) {
             </ol></p>
 
             <datafile label="stack-overflow-survey" filename="so_survey.csv" rows="10" cols="65" editable="no" include-source="yes">
-                <pre source="datafiles/stackoverflow.csv"/>
+                <pre><xi:include parse="text" href="./ext/datafiles/stackoverflow.csv" /></pre>
             </datafile>
         </data>
 
@@ -2292,7 +2292,6 @@ TEST_CASE( "Test the add function" ) {
             } // end of SimplePicture class
             ]]>
             </pre>
-            <!-- <pre source="datafiles/picture-classes-library.jar"/> -->
         </datafile>
 
         <program label="java-only-blue" interactive='activecode' language="java" add-files="file-picture-classes-jar, beach-datafile" include-source="yes">
@@ -3495,7 +3494,7 @@ TEST_CASE( "Test the add function" ) {
     <idx>matching function types</idx>
     <statement>
       <p>
-        Sort the following functions into their correct categories. 
+        Sort the following functions into their correct categories.
       </p>
     </statement>
     <feedback>

xsl/pretext-common.xsl

@@ -12138,6 +12138,13 @@ http://andrewmccarthy.ie/2014/11/06/swung-dash-in-latex/
         <xsl:with-param name="message" select="'an &quot;mdn&quot; element without any &quot;mrow&quot; children (&quot;bare&quot;) was only implemented briefly and was never supported.  Your instance is being ignored and will not be visible in output.  You can switch it to the supported bare &quot;md&quot; element with a &quot;@number&quot; attribute set to &quot;yes&quot;.'"/>
     </xsl:call-template>
     <!--  -->
+    <!-- 2025-12-29  Deprecating the use of pre@source inside datafile, in favor of xi:include -->
+    <xsl:call-template name="deprecation-message">
+        <xsl:with-param name="occurrences" select="&quot;$document-root//datafile[pre[@source]]&quot;" />
+        <xsl:with-param name="date-string" select="'2025-12-29'" />
+        <xsl:with-param name="message" select="'The use of pre@source inside of datafiles is deprecated. Please use pre+xi:include instead.'"/>
+    </xsl:call-template>
+    <!--  -->
 </xsl:template>
 
 <!-- Miscellaneous -->