Action QT4CG-051-06

 [ ] QT4CG-051-06: MK to help DN with the markup in fn:chain
      examples.

I'd suggest following the example markup used by fn:serialize or fn:transitive-closure.

The <fos:example> element can enclose either a prose example or a testable example. Testable examples are preferred if at all possible! An example of a testable example is:

<fos:example>
            <fos:test use="transitive-closure-data">
               <fos:expression><eg>let $tc := transitive-closure($direct-reports)
return $tc($data//person[@id="2"])/string(@id)</eg></fos:expression>
               <fos:result>("3", "4", "6", "7", "8")</fos:result>
            </fos:test>
</fos:example>

The "use" attribute is a reference to variables that the example uses, in this case:

<fos:variable name="data" id="transitive-closure-data"><![CDATA[document{<doc>
   <person id="0"/>
   <person id="1" manager="0"/>
   <person id="2" manager="0"/>
   <person id="3" manager="2"/>
   <person id="4" manager="2"/>
   <person id="5" manager="1"/>
   <person id="6" manager="3"/>
   <person id="7" manager="6"/>
   <person id="8" manager="6"/>
</doc>}]]>
         </fos:variable>

If you use multiple variables, I suspect the "use" attribute can be a whitespace-separated list.

The fos:expression should be valid XQuery (but use XPath if possible), and the fos:result should be valid XPath. Both contain expressions that should be context-free (except for references to variables, as discussed) and the results of the two expressions should compare equal when compared with deep-equal(). The fos:result expression, by convention, should contain only "constants", but that can include things like calls to constructor functions.

The example gets turned into a human-readable example in the spec, and also into a test case in app/fo-spec-examples.xml, for example in this case

<test-case name="fo-test-fn-transitive-closure-001">
      <description>Test case for fn:transitive-closure</description>
      <created by="Michael Kay using generate-qt3-test-set.xsl" on="2023-10-18"/>
      <environment ref="global"/>
      <dependency type="spec" value="XQ40+" satisfied="true"/>
      <test>
          let $data := 
          document{&lt;doc&gt;
   &lt;person id="0"/&gt;
   &lt;person id="1" manager="0"/&gt;
   &lt;person id="2" manager="0"/&gt;
   &lt;person id="3" manager="2"/&gt;
   &lt;person id="4" manager="2"/&gt;
   &lt;person id="5" manager="1"/&gt;
   &lt;person id="6" manager="3"/&gt;
   &lt;person id="7" manager="6"/&gt;
   &lt;person id="8" manager="6"/&gt;
&lt;/doc&gt;}
         
           return 

        
        let $tc := transitive-closure($direct-reports)
return $tc($data//person[@id="2"])/string(@id)
      </test>
      <result>
         <assert-deep-eq>("3", "4", "6", "7", "8")</assert-deep-eq>
      </result>
   </test-case>


Michael Kay
Saxonica