From 6471025219578501000553c5d5099e21da43e635 Mon Sep 17 00:00:00 2001
From: Michael Kay <mike@saxonica.com>
Date: Wed, 13 Nov 2024 00:33:45 +0000
Subject: [PATCH] Change spec of fn:siblings to include self in all cases

---
 .../src/function-catalog.xml                  | 37 +++++++++++++------
 1 file changed, 25 insertions(+), 12 deletions(-)

diff --git a/specifications/xpath-functions-40/src/function-catalog.xml b/specifications/xpath-functions-40/src/function-catalog.xml
index ac4500996..568751fbb 100644
--- a/specifications/xpath-functions-40/src/function-catalog.xml
+++ b/specifications/xpath-functions-40/src/function-catalog.xml
@@ -13897,20 +13897,25 @@ return empty($break)
          <fos:property>focus-independent</fos:property>
       </fos:properties>
       <fos:summary>
-         <p>Returns the siblings of the supplied node.</p>
+         <p>Returns the supplied node together with its siblings, in document order.</p>
       </fos:summary>
       <fos:rules>
          <p>If the <code>$node</code> argument is omitted, it defaults to the context value (<code>.</code>).</p>
-         <p>If the value of <code>$node</code> is an empty sequence, or if it is an attribute or namespace node,
-         or if <code>$node</code> has no parent, the function returns an empty sequence.</p>
-         <p>The function returns the siblings of <code>$node</code>, that is, the sequence of nodes having the
-         same parent as <code>$node</code>, in document order. The result includes <code>$node</code> itself.</p>
+         
+         <p>If the value of <code>$node</code> is an empty sequence, the function returns an empty sequence.</p>
+         
+         <p>If <code>$node</code> is a child of some parent node <var>P</var>, the function returns all the
+         children of <var>P</var> (including <code>$node</code>), in document order.</p>
+         
+         <p>Otherwise (specifically, if <code>$node</code> is parentless, or if it is an attribute or namespace node),
+         the function returns <code>$node</code>.</p>
+         
          
       </fos:rules>
       <fos:equivalent style="xpath-expression">
-if ($node[self::(attribute() | namespace-node())])
-then ()
-else $node/parent::node()/child::node()
+if ($node intersect $node/parent::node()/child::node())
+then $node/parent::node()/child::node()
+else $node
       </fos:equivalent>
       <fos:errors>
          <p>The following errors may be raised when <code>$node</code> is omitted:</p>
@@ -13928,9 +13933,17 @@ else $node/parent::node()/child::node()
          </ulist>
 
       </fos:errors>
+      <fos:notes>
+         <p>The result of <code>siblings($n)</code> (except in error cases) is the same as
+         the result of <code>$n/(preceding-sibling::node() | following-sibling-or-self::node())</code>.
+         It is also the same as <code>$n/(preceding-sibling-or-self::node() | following-sibling::node())</code></p>
+         <p>As with names such as <code>parent</code> and <code>child</code>, the word <term>sibling</term>
+         used here as a technical term is not a precise match to its use in describing human family relationships,
+         but is chosen for convenience.</p>
+      </fos:notes>
       
       <fos:examples>
-         <fos:variable name="e" id="v-siblings-e"><![CDATA[<doc x="1"><a>A</a>text<?pi 3.14159?></doc>]]></fos:variable>
+         <fos:variable name="e" id="v-siblings-e"><![CDATA[<doc x="X"><a>A</a>text<?pi 3.14159?></doc>]]></fos:variable>
          <fos:example>
             <fos:test use="v-siblings-e" spec="XQuery">
                <fos:expression>siblings($e//a) ! string()</fos:expression>
@@ -13941,13 +13954,13 @@ else $node/parent::node()/child::node()
                <fos:result>"A", "text", "3.14159"</fos:result>
             </fos:test>
             <fos:test use="v-siblings-e" spec="XQuery">
-               <fos:expression>siblings($e//@x)</fos:expression>
-               <fos:result>()</fos:result>
+               <fos:expression>siblings($e//@x) ! string()</fos:expression>
+               <fos:result>"X"</fos:result>
             </fos:test>
          </fos:example>
       </fos:examples>
       <fos:changes>
-         <fos:change issue="1542" PR="1547 1551"><p>New in 4.0</p></fos:change>
+         <fos:change issue="1542 1552" PR="1547 1551"><p>New in 4.0</p></fos:change>
       </fos:changes>
 
    </fos:function>