Various documentation fixes for docs on internals

Michael pointed out a number of errors, inaccuracies or
unclear points with new wording.

1 files changed, 38 insertions, 29 deletions

diff --git a/doc/xslt.html b/doc/xslt.html
index 574a19d0..902f27cf 100644
--- a/doc/xslt.html
+++ b/doc/xslt.html
@@ -1604,6 +1604,7 @@ processor to generate DOM trees compliant with the XPath data model.</p>
   <li><a href="internals.html#Extension">Extension support</a></li>
   <li><a href="internals.html#Futher">Further reading</a></li>
   <li><a href="internals.html#TODOs">TODOs</a></li>
+  <li><a href="internals.html#Thanks">Thanks</a></li>
 </ul>
 
 <h3><a name="Introducti2">Introduction</a></h3>
@@ -1723,13 +1724,18 @@ level:</p>
 
 <p>A few things should be noted here:</p>
 <ul>
-  <li>the steps 1/ 3/ and 5/ are optional</li>
+  <li>the steps 1/ 3/ and 5/ are optional:  the DOM representing the
+    stylesheet and input can be created by other means, not just by parsing
+    serialized XML documents, and similarly the result tree DOM can be
+    made available to other processeswithout being serialized.
   <li>the stylesheet obtained at 2/ can be reused by multiple processing 4/
     (and this should also work in threaded programs)</li>
   <li>the tree provided in 2/ should never be freed using xmlFreeDoc, but by
     freeing the stylesheet.</li>
-  <li>the input tree 4/ is not modified except the _private field which may
-    be used for labelling keys if used by the stylesheet</li>
+  <li>the input tree created in step 3/ is not modified except the
+    _private field which may be used for labelling keys if used by the
+    stylesheet. It's not modified at all in step 4/ to allow parallel
+    processing using a shared precompiled stylesheet.</li>
 </ul>
 
 <h3><a name="XSLT1">The XSLT stylesheet compilation</a></h3>
@@ -1788,15 +1794,10 @@ compiled in this stylesheet are indexed by the value of the the target
 element (or attribute, pi ...) name, so when a element or an attribute "foo"
 needs to be processed the lookup is done using the name as a key.</p>
 
-<p>Each of the patterns is compiled into an xsltCompMatch structure. It holds
+<p>Each of the patterns is compiled into an xsltCompMatch
+(i.e. an ''XSLT compiled match') structure. It holds
 the set of rules based on the tokenization of the pattern stored in reverse
-order (matching is easier this way). It also holds some information about the
-previous matches used to speed up the process when one iterates over a set of
-siblings. (This optimization may be defeated by trashing when running
-threaded computation, it's unclear that this is a big deal in practice.)
-Predicate expressions are not compiled at this stage, they may be at run-time
-if needed, but in this case they are compiled as full XPath expressions (the
-use of some fixed predicate can probably be optimized, they are not yet).</p>
+order (matching is easier this way). </p>
 
 <p>The xsltCompMatch are then stored in the hash table, the clash list is
 itself sorted by priority of the template to implement "naturally" the XSLT
@@ -1818,15 +1819,16 @@ linked lists of xsltCompMatch.</p>
 <p>The processing is defined by the XSLT specification (the basis of the
 algorithm is explained in <a
 href="http://www.w3.org/TR/xslt#section-Introduction">the Introduction</a>
-section). Basically it works by taking the root of the input document and
-applying the following algorithm:</p>
+section). Basically it works by taking the root of the input document
+as the cureent node and applying the following algorithm:</p>
 <ol>
-  <li>Finding the template applying to it. This is a lookup in the template
-    hash table, walking the hash list until the node satisfies all the steps
-    of the pattern, then checking the appropriate(s) global templates to see
-    if there isn't a higher priority rule to apply</li>
+  <li>Finding the template applying to current node.
+    This is a lookup in the template hash table, walking the hash list until
+    the node satisfies all the steps of the pattern, then checking the
+    appropriate global template(s) (i.e.  templates applying to a node type)
+    to see if there isn't a higher priority rule to apply</li>
   <li>If there is no template, apply the default rule (recurse on the
-    children)</li>
+    children as the current node)</li>
   <li>else walk the content list of the selected templates, for each of them:
     <ul>
       <li>if the node is in the XSLT namespace then the node has a _private
@@ -1837,14 +1839,16 @@ applying the following algorithm:</p>
       <li>otherwise copy the node.</li>
     </ul>
     <p>The closure is usually done through the XSLT
-    <strong>apply-templates</strong> construct recursing by applying the
-    adequate template on the input node children or on the result of an
-    associated XPath selection lookup.</p>
+    <strong>apply-templates</strong>construct, which invokes this process
+      recursively starting at step 1, to find the appropriate template
+      for the nodes selected by the 'select' attribute of the apply-templates
+      instruction (default: the children of the node currently being
+      processed)</p>
   </li>
 </ol>
 
 <p>Note that large parts of the input tree may not be processed by a given
-stylesheet and that on the opposite some may be processed multiple times.
+stylesheet and that conversely some may be processed multiple times.
 (This often is the case when a Table of Contents is built).</p>
 
 <p>The module <code>transform.c</code> is the one implementing most of this
@@ -1866,7 +1870,7 @@ allocates an xsltTransformContext containing the following:</p>
 <p>Then a new document gets allocated (HTML or XML depending on the type of
 output), the user parameters and global variables and parameters are
 evaluated. Then <strong>xsltProcessOneNode()</strong> which implements the
-1-2-3 algorithm is called on the root element of the input. Step 1/ is
+1-2-3 algorithm is called on the docuemnt node of the input. Step 1/ is
 implemented by calling <strong>xsltGetTemplate()</strong>, step 2/ is
 implemented by <strong>xsltDefaultProcessOneNode()</strong> and step 3/ is
 implemented by <strong>xsltApplyOneTemplate()</strong>.</p>
@@ -1916,7 +1920,7 @@ sounds likely to be more efficient.</p>
 which is the front-end to <strong>xmlXPathCompOpEval()</strong> the function
 implementing the evaluation of the expression tree. This evaluation follows
 the KISS approach again. It's recursive and calls
-<strong>xmlXPathNodeCollectAndTest()</strong> to collect nodes set when
+<strong>xmlXPathNodeCollectAndTest()</strong> to collect a set of nodes when
 evaluating a <code>COLLECT</code> node.</p>
 
 <p>An evaluation is done within the framework of an XPath context stored in
@@ -1926,7 +1930,8 @@ follows the requirements from the XPath specification:</p>
 <ul>
   <li>the current document</li>
   <li>the current node</li>
-  <li>a hash table of defined variables (but not used by XSLT)</li>
+  <li>a hash table of defined variables (but not used by XSLT,
+      which uses its own stack frame for variables, described below)</li>
   <li>a hash table of defined functions</li>
   <li>the proximity position (the place of the node in the current node
   list)</li>
@@ -1938,8 +1943,8 @@ follows the requirements from the XPath specification:</p>
 <p>For the purpose of XSLT an <strong>extra</strong> pointer has been added
 allowing to retrieve the XSLT transformation context. When an XPath
 evaluation is about to be performed, an XPath parser context is allocated
-containing and XPath object stack (this is actually an XPath evaluation
-context, this is a remain of the time where there was no separate parsing and
+containing an XPath object stack (this is actually an XPath evaluation
+context, this is a relic of the time where there was no separate parsing and
 evaluation phase in the XPath implementation). Here is an overview of the set
 of contexts associated to an XPath evaluation within an XSLT
 transformation:</p>
@@ -2008,7 +2013,7 @@ variables and parameters as they are defined through the recursive calls of
 call-template, apply-templates and default templates. This is used to define
 the scope of variables being called.</p>
 
-<p>This part seems to be the most urgent attention right now, first it is
+<p>This part seems to be one needing most work , first it is
 done in a very inefficient way since the location of the variables and
 parameters within the stylesheet tree is still done at run time (it really
 should be done statically at compile time), and I am still unsure that my
@@ -2029,7 +2034,7 @@ extension support works</a>.</p>
 <p>Michael Kay wrote <a
 href="http://www-106.ibm.com/developerworks/library/x-xslt2/?dwzone=x?open&amp;l=132%2ct=gr%2c+p=saxon">a
 really interesting article on Saxon internals</a> and the work he did on
-performance issues. I wishes I had read it before starting libxslt design (I
+performance issues. I wish I had read it before starting libxslt design (I
 would probably have avoided a few mistakes and progressed faster). A lot of
 the ideas in his papers should be implemented or at least tried in
 libxslt.</p>
@@ -2073,6 +2078,10 @@ elements/attributes in different namespaces).</p>
 modified at run time (extra removal of blanks nodes, hint on the
 xsltCompMatch).</p>
 
+<h3><a name="Thanks">Thanks:</a></h3>
+<p>Thanks to <a href="http://cmsmcq.com/">Michael Sperberg-McQueen</a> for
+   various fixes and clarifications on this document!</p>
+
 <p></p>
 
 <h2><a name="Extensions">Writing extensions</a></h2>