Roll libxslt to 891681e3e948f31732229f53cb6db7215f740fc7

third_party/libxslt/NOTES

Index: third_party/libxslt/NOTES
diff --git a/third_party/libxslt/NOTES b/third_party/libxslt/NOTES
new file mode 100644
index 0000000000000000000000000000000000000000..1314b8d1f518a95379f4ec2f50465a08f63e50dd
--- /dev/null
+++ b/third_party/libxslt/NOTES
@@ -0,0 +1,253 @@
+
+        NOTES relative to the implementation
+	====================================
+
+xsl:stylesheet:
+
+  all children except xsl:import can be in any order, so this
+can be stored as one big structure.
+
+xsl:include:
+  
+  this is really similar to XInclude, can be implemented as a
+nearly separate processing just after the XML stylesheet has been
+parsed.
+  Detect loops using a limited stack ...
+
+xsl:import:
+
+  seems this should be really implemented as having a stylesheet
+sublist being itself an import list
+
+  add the list at the end
+  when doing a resolution explore child before siblings in the list
+
+3 Data Model, we should operate on parsed trees
+
+3.1 No problem
+
+3.2 use the XML Base call, XSLT-1.1 references it
+
+3.4 Whitespace Stripping
+
+  Seems one may have to do a bit of preprocessing on both the
+stylesheet trees and the source trees.
+
+4 Expressions
+
+  looks okay, wondering about variable bindings though...
+  default namespace not in scope
+
+5.1 Processing Model
+
+  look in Michael Kay's book about how to efficiently find the
+template applying to a node. Might influence the in-memory stylesheet
+representation
+
+5.2 Patterns
+
+  the end of that section suggest that the expression could be computed in
+a simpler way. Maybe templates needs to be evaluated differently than
+through the normal XPath processing. This can be implemented separately
+or build an expression tree in the XPath module and use a different 
+evaluation mechanism. Not sure this is best.
+
+5.4 Applying Template Rules
+
+  xsl:apply-templates is the recurstion mechanism, note the select
+mechanism.
+
+  detection of loop: once the applied nodeset has been computed,
+check that none of the elements is part of the existing set in use, this
+may be costly and should be triggered only at a certain depth.
+
+5.5 Conflict Resolution for Template Rules
+
+  Sounds again that evaluation of a pattern rule should provide one
+more information not provided by the standard XPath evaluation
+
+5.6 Overriding Template Rules
+
+  another recursion mechanism, confirm that it is needed to separate
+the imported stylesheets.
+
+5.7 Modes
+
+  Confusing ??? need an example.
+
+6 Named Templates
+
+  No big deal it seems
+
+7.1.1 Literal Result Elements
+
+  cleanup of the namespace template should be done initially at stylesheet
+parsing.
+
+7.1.2 Creating Elements with xsl:element
+
+   okay, I bet it's usually used with { } expression computations
+
+7.1.3 Creating Attributes with xsl:attribute
+
+   need some running code to better understand all the subtilties
+
+7.1.4 Named Attribute Sets
+
+   Okay just a way to mimick param entities use fo attrib groups in Dtd's
+
+7.2 Creating Text
+
+   adjacent text nodes are merged ... okay
+   output escapeing might need a libxml API extension
+
+7.3 Creating Processing Instructions
+7.4 Creating Comments
+
+   RAS, one just need to make a couple of trivial checks
+
+7.5 Copying
+
+   Okay will need some testing
+
+7.6.1 Generating Text with xsl:value-of
+
+   will be a good test for XPath string() function
+   note in the example that the text nodes are coalesced
+
+7.6.2 Attribute Value Templates
+
+   hum, this is 
+    - contextual
+    - uses XPath
+
+  best seems to parse, generate an evaluation tree then evaluate
+when accessed. Note that multipe expressions can be associated to 
+a single attribute. Sounds like i will have to introduce a new
+element type inserted in the attribute nodelist. dohh ...
+
+7.7 Numbering
+
+  sounds interesting for users but might be costly, we will see ...
+
+7.7.1 Number to String Conversion Attributes
+
+   format="..." :-( it's gonna be painful ...
+
+8 Repetition
+9 Conditional Processing
+
+  doesn't sounds hard to implement since we are at an interpreter
+level but really useful in practice. Will be simple once the overall
+framework is set-up.
+
+10 Sorting
+
+  Okay applied to the node list of an xsl:apply-templates or xsl:for-each
+
+  The NOTEs are a bit scary ...
+
+11 Variables and Parameters
+
+   Variables can only be afttected at the top level, so it
+seems they act only as global variables ...
+   But this is by regions .... so some of the statements within
+a stylesheet my use a different set than others ... in practice
+it turns to be nearly like loacal variables ....
+  Need more thinking on this to handle it properly.
+  Might explain on of TOM's requests w.r.t. variable resolution
+
+11.1 Result Tree Fragments
+
+  Dohhh a new type ...
+  actually it's just a node set restricted type
+
+11.2 Values of Variables and Parameters
+
+  okay, real problem is scoping ...
+
+11.3 Using Values of Variables and Parameters with xsl:copy-of 
+
+  No surprize
+
+11.4 Top-level Variables and Parameters
+
+   It is an error if a stylesheet contains more than one binding
+   of a top-level variable with the same name and same import precedence
+
+   => ah ah, so it seems one can associate the variable bindings
+to a stylesheet and if needed recurse down the import list if not
+found, would simplify things a lot !
+
+   If the template or expression specifying the value of a global variable
+x references a global variable y, then the value for y must be computed
+before the value of x.
+
+   => Values can probably be computed dynamically at reference
+time, if this generate a loop, then it's an error. Lazy computations
+are great ...
+
+11.5 Variables and Parameters within Templates
+
+   
+   xsl:variable is allowed anywhere within a template that an instruction
+is allowed. In this case, the binding is visible for all following siblings
+and their descendants.
+   It is an error if a binding established by an xsl:variable or xsl:param
+element within a template shadows another binding established by an
+xsl:variable or xsl:param element also within the template.
+
+  => the example seems to imply that we can simply keep a list of
+     local variable binding to a template ... sounds fine.
+
+11.6 Passing Parameters to Templates
+
+  => Okay the parameter overrides the local binding
+
+12.1 Multiple Source Documents
+12.2 Keys
+
+  skipped for now
+
+12.3 Number Formatting
+
+  reimplementing Java formatting in C is gonna be a pain !
+
+12.4 Miscellaneous Additional Functions
+
+  current() => trivial
+
+  unparsed-entity-uri() => support in uri.c should do
+
+  generate-id() => use the in-memory address of the node ???
+
+  system-property() => sounds simple
+
+13 Messages
+
+  trivial I/Os
+
+14 Extensions
+15 Fallback
+
+   skipped for now
+
+16 Output
+
+16.1 XML Output Method
+
+  sounds that calling directly libxml output on the result tree
+should do it with a few caveats, for example one need to be
+able to parametrize the output
+
+16.2 HTML Output Method
+
+  sounds that calling libxml HTML output should do it too
+
+16.3 Text Output Method
+
+  doesn't sounds too hard ...
+
+16.4 Disabling Output Escaping
+
+  hum ... might be a bit painful to implement with the current framework.