[Lxml-checkins] r42723 - lxml/trunk/doc

[scoder at codespeak.net]

Author: scoder
Date: Sun May  6 08:57:03 2007
New Revision: 42723

Modified:
   lxml/trunk/doc/resolvers.txt
   lxml/trunk/doc/xpathxslt.txt
Log:
restructuring of XSLT docs

Modified: lxml/trunk/doc/resolvers.txt
==============================================================================
--- lxml/trunk/doc/resolvers.txt	(original)
+++ lxml/trunk/doc/resolvers.txt	Sun May  6 08:57:03 2007
@@ -3,13 +3,20 @@
 
 .. contents::
 ..
-   1  Document loaders in context
-   2  I/O access control in XSLT
+   1  Resolvers
+   2  Document loading in context
+   3  I/O access control in XSLT
 
 
 Lxml has support for custom document loaders in both the parsers and XSL
 transformations.  These so-called resolvers are subclasses of the
-etree.Resolver class as in the following example::
+etree.Resolver class.
+
+
+Resolvers
+---------
+
+Here is an example of a custom resolver::
 
   >>> from lxml import etree
 
@@ -32,10 +39,10 @@
 * ``resolve_file`` takes an open file-like object that has at least a read() method
 * ``resolve_empty`` resolves into an empty document
 
-The ``resolve`` method may choose to return None, in which case the next
-registered resolver (or the default resolver) is consulted.  It is never
-called if the resolver returns the result of any of the above ``resolve_*``
-methods.
+The ``resolve()`` method may choose to return None, in which case the next
+registered resolver (or the default resolver) is consulted.  Resolving always
+terminates if ``resolve()`` returns the result of any of the above
+``resolve_*()`` methods.
 
 Resolvers are registered local to a parser::
 
@@ -58,7 +65,7 @@
 fragment.
 
 
-Document loaders in context
+Document loading in context
 ---------------------------
 
 XML documents memorise their initial parser (and its resolvers) during their
@@ -180,12 +187,16 @@
 I/O access control in XSLT
 --------------------------
 
-XSLT has an additional mechanism to control the access to certain I/O
-operations during the transformation process.  This is most interesting where
-XSL scripts come from potentially insecure sources and must be prevented from
-modifying the local file system.  Note, however, that there is no way to keep
-them from eating up your precious CPU time, so this should not stop you from
-thinking about what XSLT you execute.
+By default, XSLT supports all extension functions from libxslt and libexslt as
+well as Python regular expressions through EXSLT.  Some extensions enable
+style sheets to read and write files on the local file system.
+
+XSLT has a mechanism to control the access to certain I/O operations during
+the transformation process.  This is most interesting where XSL scripts come
+from potentially insecure sources and must be prevented from modifying the
+local file system.  Note, however, that there is no way to keep them from
+eating up your precious CPU time, so this should not stop you from thinking
+about what XSLT you execute.
 
 Access control is configured using the ``XSLTAccessControl`` class.  It can be
 called with a number of keyword arguments that allow or deny specific

Modified: lxml/trunk/doc/xpathxslt.txt
==============================================================================
--- lxml/trunk/doc/xpathxslt.txt	(original)
+++ lxml/trunk/doc/xpathxslt.txt	Sun May  6 08:57:03 2007
@@ -28,11 +28,11 @@
 findtext`_ methods on ElementTree and Element, as known from the original
 ElementTree library (ElementPath_).  As an lxml specific extension, these
 classes also provide an ``xpath()`` method that supports expressions in the
-complete XPath syntax, as well as `extension functions`_.
+complete XPath syntax, as well as `custom extension functions`_.
 
 .. _ElementPath: http://effbot.org/zone/element-xpath.htm
 .. _`find,  findall and findtext`: http://effbot.org/zone/element.htm#searching-for-subelements
-.. _`extension functions`: extensions.html
+.. _`custom extension functions`: extensions.html
 
 There are also specialized XPath evaluator classes that are more efficient for
 frequent evaluation: ``XPath`` and ``XPathEvaluator``.  See the `performance
@@ -115,9 +115,11 @@
   'Text'
 
 There is also an optional ``extensions`` argument which is used to define
-`extension functions`_ in Python that are local to this evaluation.
+`custom extension functions`_ in Python that are local to this evaluation.
 
-.. _`extension functions`: extensions.html
+
+XPath return values
+-------------------
 
 The return values of XPath evaluations vary, depending on the XPath expression
 used:
@@ -315,6 +317,18 @@
     [...]
   LookupError: unknown encoding: UCS4
 
+By default, XSLT supports all extension functions from libxslt and libexslt as
+well as Python regular expressions through EXSLT.  Also see the documentation
+on `custom extension functions`_ and `document resolvers`_.  There is a
+separate section on `controlling access`_ to external documents and resources.
+
+.. _`document resolvers`: resolvers.html
+.. _`controlling access`: resolvers.html#i-o-access-control-in-xslt
+
+
+Stylesheet parameters
+---------------------
+
 It is possible to pass parameters, in the form of XPath expressions, to the
 XSLT template::
 
@@ -342,7 +356,11 @@
   >>> str(result)
   '<?xml version="1.0"?>\n<foo>Text</foo>\n'
 
-There's also a convenience method on the tree object for doing XSL
+
+The ``xslt()`` tree method
+--------------------------
+
+There's also a convenience method on ElementTree objects for doing XSL
 transformations.  This is less efficient if you want to apply the same XSL
 transformation to multiple documents, but is shorter to write for one-shot
 operations, as you do not have to instantiate a stylesheet yourself::
@@ -351,12 +369,16 @@
   >>> str(result)
   '<?xml version="1.0"?>\n<foo>A</foo>\n'
 
-By default, XSLT supports all extension functions from libxslt and libexslt as
-well as Python regular expressions through EXSLT.  Note that some extensions
-enable style sheets to read and write files on the local file system.  See the
-`document loader documentation`_ on how to deal with this.
+This is a shortcut for the following code::
+
+  >>> transform = etree.XSLT(xslt_tree)
+  >>> result = transform(doc, a="'A'")
+  >>> str(result)
+  '<?xml version="1.0"?>\n<foo>A</foo>\n'
+
 
-.. _`document loader documentation`: resolvers.html
+Profiling
+---------
 
 If you want to know how your stylesheet performed, pass the ``profile_run``
 keyword to the transform::