Add comments to pythonhosted.xsl

stylesheets/pythonhosted.xsl

@@ -5,14 +5,24 @@
 
   <xsl:output method="text"/>
 
+  <!-- The pyhosted-inc.xsl file contains two variables, one containing
+       the text of
+       pythonhosted.xml before the creation of pythonhosted-files.md5,
+       the other containing the text after that.-->
   <xsl:include href="pyhosted-inc.xsl"/>
+  <!-- list of python modules whose dependencies should be listed -->
   <xsl:param name="packages">requests sphinx_rtd_theme pytest</xsl:param>
+  <!-- Name of the .xml where to find all python dependencies -->
   <xsl:variable name="python-deps">python-dependencies.xml</xsl:variable>
+  <!-- This variable is a scan of the dependency graph in depth first order.
+       it is a suitable order for building, except it contains many
+       duplicates.-->
   <xsl:variable name="raw-dep-list">
     <xsl:call-template name="gen-deps">
       <xsl:with-param name="list" select="$packages"/>
     </xsl:call-template>
   </xsl:variable>
+  <!-- This variable is a copy of raw-dep-list, but with duplicates removed -->
   <xsl:variable name="dep-list">
     <xsl:call-template name="make-unique">
       <xsl:with-param name="list" select="$raw-dep-list"/>
@@ -20,6 +30,7 @@
     </xsl:call-template>
   </xsl:variable>
 
+  <!-- scan the list of modules and generates dependencies for each -->
   <xsl:template name="gen-deps">
     <xsl:param name="list" select="$packages"/>
     <xsl:choose>
@@ -39,8 +50,9 @@
     </xsl:choose>
   </xsl:template>
 
+  <!-- This template is applied recursively for each dependency. -->
   <xsl:template match="*" mode="gen-dep">
-    <!--
+    <!-- for debugging
     <xsl:message>
       <xsl:text>generating deps for </xsl:text>
       <xsl:value-of select="@id"/>
@@ -54,8 +66,14 @@
       mode="dep-list"/>
   </xsl:template>
 
+  <!-- this template calls the preceding one for each dependency found,
+       printing the name of the dependency afterwards. This generates the
+       depth-first order -->
   <xsl:template match="para" mode="dep-list">
     <xsl:for-each select="xref">
+      <!-- The linkend may point either to the current document, or
+           if not found to the python-dependencies.xml document. Note
+           that the current document may be already python-dependencies.xml.-->
       <xsl:choose>
         <xsl:when test="//*[@id=current()/@linkend]">
           <xsl:apply-templates select="//*[@id=current()/@linkend]" mode="gen-dep"/>
@@ -71,6 +89,9 @@
     </xsl:for-each>
   </xsl:template>
 
+  <!-- Template to remove duplicates. Each time it is called, the param
+       "list" contains the list remaining to be processed, and the
+       param "temp" contains the already processed list with no duplicates -->
   <xsl:template name="make-unique">
     <xsl:param name="list" select="$raw-dep-list"/>
     <xsl:param name="temp" select="' '"/>
@@ -79,6 +100,8 @@
         <xsl:variable name="package" select="substring-before($list,' ')"/>
         <xsl:variable name="temp1">
           <xsl:choose>
+       <!-- the concat is needed to prevent problems with a package
+            containing the name of another package -->
             <xsl:when test="contains($temp,concat(' ',$package,' '))">
               <xsl:copy-of select="$temp"/>
             </xsl:when>
@@ -109,8 +132,11 @@
     </xsl:choose>
   </xsl:template>
 
+  <!-- with the variable dep-list, we can apply templates for generating
+       the content of the .md5 file. We just have to copy the variables set
+       in pyhosted-inc before and after that file -->
   <xsl:template match="/">
-    <!--
+    <!-- debug
     <xsl:message>
       <xsl:text>Generating new pythonhosted.xml with list:
 </xsl:text>
@@ -140,11 +166,14 @@
         </xsl:call-template>
       </xsl:when>
       <xsl:otherwise>
+       <!-- first try to find the dependency in python-modules. If so, precede
+            it with a `#' -->
         <xsl:apply-templates
           select="id($list)"
           mode="md5-line">
           <xsl:with-param name="first-char" select="'#'"/>
         </xsl:apply-templates>
+        <!-- then try in python-dependencies -->
         <xsl:apply-templates
           select="document($python-deps,/)//sect2[@id=$list]"
           mode="md5-line"/>
@@ -154,7 +183,7 @@
 
   <xsl:template match="sect2" mode="md5-line">
     <xsl:param name="first-char" select="''"/>
-    <!--
+    <!-- debug
     <xsl:message>
       <xsl:text>Generating md5 for </xsl:text>
       <xsl:value-of select="@id"/>