<?xml version='1.0' encoding='iso-8859-1'?>
<section><title>Migrating to version 2.15</title>

<section><title>Changes to plain text conversion</title>

<par>The node method <method>asText</method> has been moved to the
<module>html</module> namespace, so you have to replace:</par>

<prog>print node.asText()</prog>

<par>with:</par>

<prog>
from ll.xist.ns import html
print html.astext(node)
</prog>

</section>

<section><title>Changes to <class>htmlspecials.pixel</class></title>

<par>If you've been using the <lit>color</lit> attribute for
<class>htmlspecials.pixel</class>, you have to add a <lit>#</lit> in from of
the value, as it is a &css; color value now. (And if've you've been using
<lit>color</lit> and a &css; padding of a different color: This will no longer
work).</par>

</section>


<section><title>Migrating to version 2.14</title>

<section><title>Changes to presenters</title>

<par>Presenters work differently now. Instead of:</par>

<prog>print node.asrepr(presenters.CodePresenter)</prog>

<par>simply do the following:</par>

<prog>print presenters.CodePresenter(node)</prog>

</section>

</section>


<section><title>Migrating to version 2.13</title>

<section><title>Changes to <module>ll.xist.xsc</module></title>

<par><method>xsc.Namespace.tokenize</method> no longer has an <arg>encoding</arg>
argument, but operates on a unicode string directly. You can either use the
result of a <method>asString</method> call or decode the result of an
<method>asBytes</method> call yourself.</par>
</section>

</section>


<section><title>Migrating to version 2.11</title>

<section><title>Changes to <module>ll.xist.xsc</module></title>

<par>The function <function>ToNode</function> has been renamed to
<function>tonode</function>.</par>

<par><class>ll.xist.Context</class> no longer subclasses <class>list</class>.
If you need a stack for your context, simply add the list as an attribute
of the context object.</par>

</section>

<section><title>Code rearrangements</title>

<par>The iterator stuff from <module>ll.xist.xfind</module> has been moved to
the <module>ll</module> package/module, i.e. you have to use
<function>ll.first</function> instead of <function>ll.xist.xfind.first</function>.</par>

</section>

<section><title>Changes to the <method>walk</method> method</title>

<par>The <method>walk</method> method has changed again. There are no inmodes
and outmodes any longer. Instead input and output are <class>Cursor</class>
objects. If you're using your own <method>walk</method> filters, you have to
update them. For different output modes you can use the methods <method>walknode</method>,
<method>walkpath</method> or <method>walkindex</method> instead of using
the cursor yielded by <method>walk</method>.</par>

<par>The node methods <method>find</method> and <method>findfirst</method>
have been removed. Use <lit>xsc.Frag(node.walk(<rep>...</rep>)</lit> or
<lit>node.walk(<rep>...</rep>)[0]</lit> instead.</par>

</section>

<section><title>Changes to publishing</title>

<par>Publishing has changed: If you've used the method <method>repr</method>
before to get a string representation of an &xml; tree, you have to use
<method>asrepr</method> instead now (<method>repr</method> is a generator
which will produce the string in pieces).</par>

</section>


<section><title>Changes to the <module>xfind</module> module</title>

<par>The functions <function>item</function>, <function>first</function>,
<function>last</function>, <function>count</function> and
<function>iterone</function> as well as the class <class>Iterator</class>
have been moved to the <module>ll</module> module.</par>

</section>


<section><title>Migrating to version 2.10</title>

<section><title>Changes to publishing</title>
<par>Publishing has been changed from using a stream &api; to using a
iterator &api;. If you've been using <method>Publisher.write</method> or
<method>Publisher.writetext</method> (in your own <method>publish</method>
methods) you must update your code by replacing <lit>publisher.write(<rep>foo</rep>)</lit>
with <lit>yield publisher.encode(<rep>foo</rep>)</lit> and
<lit>publisher.writetext(<rep>foo</rep>)</lit> with
<lit>yield publisher.encodetext(<rep>foo</rep>)</lit>.</par>
</section>

<section><title>Changes to the test suite</title>
<par>The test suite now uses <link href="http://codespeak.net/py/current/doc/test.html">py.test</link>,
so if you want to run it you'll need py.test.</par>
</section>

<section><title>Changes to <module>ll.xist.ns.code</module></title>
<par>The code in a <class>ll.xist.ns.code.pyexec</class> object is no longer
executed at construction time, but at conversion time. So if you relied on
this fact (e.g. to make a namespace available for parsing the rest of the
&xml; file) you will have to change your code.</par>
</section>

<section><title>Removed namespaces</title>
<par>The namespace modules <module>ll.xist.ns.css</module> and
<module>ll.xist.ns.cssspecials</module> have been removed.</par>
</section>

</section>


<section><title>Migrating to version 2.9</title>

<section><title>Changes to exceptions</title>
<par>All exception classes have been moved from <module>ll.xist.errors</module>
to <module>ll.xist.xsc</module>.</par>
</section>

<section><title>Changes to &xml; name handling</title>
<par>The class attribute <lit>xmlname</lit> no longer gets replaced with a tuple
containing both the Python and the &xml; name. If you want to get the Python name,
use <lit><rep>foo</rep>.__class__.__name__</lit>.</par>
</section>

<section><title>Changes to the methods <method>walk</method>, <method>find</method> and <method>findfirst</method></title>
<par>The argument <arg>filtermode</arg> has been renamed to <arg>inmode</arg>
and (for <method>walk</method>) <arg>walkmode</arg> has been renamed to <arg>outmode</arg>.</par>
</section>

</section>


<section><title>Migrating to version 2.8</title>

<section><title>Changes to display hooks</title>
<par>The way &xist; uses <function>sys.displayhook</function> has been
enhanced. To make use of this, you might want to update your Python
startup script. For more info see the
<link href="root:xist/Installation.html">installation instructions</link>.</par>
</section>

<section><title>Changes to the <lit>xmlns</lit> attribute</title>
<par>Each element (or entity, or processing instruction) class had an attribute
<lit>xmlns</lit> that references the namespace module. This attribute has been
renamed to <lit>__ns__</lit>.</par>
</section>

<section><title>Other minor changes</title>
<par><class>ll.xist.ns.specials.x</class> has been renamed to
<class>ll.xist.ns.specials.ignore</class>.</par>
<par><class>ll.xist.xfind.item</class> no longer handles slices.
If you've used that functionality, you may now use slices
on XFind operators, and materilize the result, i.e. replace
<lit>xfind.slice(<rep>foo</rep>, 1, -1)</lit>
with <lit>list(<rep>foo</rep>[1:-1])</lit>, if <lit><rep>foo</rep></lit> is
an XFind operator. Otherwise you can use <lit>list(<rep>foo</rep>)[1:-1]</lit></par>
</section>

</section>


<section><title>Migrating to version 2.7</title>

<section><title>Changes to <module>ll.xist.xfind</module></title>
<par>The functions <function>xfind.first</function> and
<function>xfind.last</function> now use <function>xfind.item</function>, so
they will raise an <class>IndexError</class> when no default value is passed.
To get the old behaviour, simply pass <lit>None</lit> as the default.</par>
</section>

</section>


<section><title>Migrating to version 2.6</title>

<section><title>Changes to the publishing &api;</title>
<par>The top level publishing method in the publisher has been
renamed from <method>dopublication</method> to <method>publish</method>.
If you're using the publishing &api; directly (instead of the node methods
<method>asBytes</method> and <method>write</method>), you'll have to
update your code.</par>
<par>The method that writes a unicode object to the output stream has
been renamed from <method>publish</method> to <method>write</method>.
This is only relevant when you've overwritten the <method>publish</method>
method in your own node class (e.g. in &jsp; tag library directives
or similar stuff, or for special nodes that publish some text literally).</par>
</section>

<section><title>Changes to the presentation &api;</title>
<par>The presentation &api; has been changed too: The top level presentation
method in the presenter has been renamed from <method>dopresentation</method> to
<method>present</method>. This is only relevant if you've written your own
presenter, or are using the presentation &api; directly (instead of the node
method <method>repr</method>).</par>
</section>

<section><title>Parsing &html;</title>
<par>Parsing &html; is now done via libxml2's &html; parser, instead of using
µTidyLib of mxTidy. You can no longer pass arguments to tidy. Only the boolean
values of the <arg>tidy</arg> argument will be used. There are no other visible
changes to the &api; but the result of parsing might have changed.</par>
</section>

<section><title>Removed &api;s and scripts</title>
<par>The script <filename>xscmake.py</filename> has been removed.</par>

<par>The <method>visit</method> method has been removed.</par>

<par><method>ll.xist.xsc.FindOld</method> has been removed.</par>

<par><class>ll.xist.ns.xml.header</class> has been renamed to
<class>ll.xist.ns.xml.declaration</class>.</par>

</section>

</section>


<section><title>Migrating to version 2.5</title>

<section><title>Changes to content model</title>
<par>The boolean class attribute <lit>empty</lit> for element classes has been
replaced by an object <lit>model</lit>. <lit>empty</lit> is still supported,
but issues a <class>PendingDeprecationWarning</class>. If you don't want to specify
a proper content model for your own elements you can replace <lit>empty = False</lit>
with <lit>model = True</lit> (which is a shortcut for <lit>model = sims.Any()</lit>)
and <lit>empty = True</lit> with <lit>model = False</lit> (which is a shortcut
for <lit>model = sims.Empty()</lit>).</par>
</section>

</section>


<section><title>Migrating to version 2.4</title>

<section><title>Changes to parsing</title>
<par>Parsing has changed internally, but the module level parsing functions in
<module>ll.xist.parsers</module> are still available (and will create a parser
on the fly), but a few arguments have changed:</par>
<dlist>
<term><arg>handler</arg></term><item>This argument is no longer available, if you
need a special handler, you have to subclass <class>ll.xist.parsers.Parser</class>
and call its parsing methods.</item>
<term><arg>parser</arg></term><item>This argument has been renamed to
<arg>saxparser</arg> and is <em>not</em> a &sax;2 parser instance any longer,
but a callable that will create a &sax;2 parser.</item>
<term><arg>sysid</arg></term><item><arg>sysid</arg> is now available for all
parsing functions not just <function>parseString</function>.</item>
</dlist>
</section>

<section><title>Changes to converter contexts</title>
<par><method>ll.xist.converters.Converter.__getitem__</method> now doesn't use
the key passed in, but <lit><rep>key</rep>.Context</lit> as the real dictionary
key. This has the following consequences:</par>
<ulist>
<item><par>If you want a unique context for your own element class,
you <em>must</em> implement a new <class>Context</class> class (otherwise you'd
get <class>ll.xist.xsc.Element.Context</class>):</par>
<example>
<prog>
class Foo(xsc.Element):
	empty = False

	class Context(xsc.Element.Context):
		def __init_(self):
			xsc.Element.Context.__init__(self)
			<rep>...</rep>
</prog>
</example>
</item>
<item>Subclasses that don't overwrite <class>Context</class> (as well as instances
of those classes) can be passed to <method>ll.xist.converters.Converter.__getitem__</method>
and the unique base class context object will be returned.</item>
</ulist>
</section>

<section><title>Changed namespaces</title>
<par>The character reference classes from <module>ll.xist.ns.ihtml</module>
that are duplicates of those in <module>ll.xist.ns.chars</module> have been removed, so you
have to use <module>ll.xist.ns.chars</module> for those characters in addition to
<module>ll.xist.ns.ihtml</module>
</par>
</section>

</section>


<section><title>Migrating to version 2.3</title>

<section><title>Changes in namespace handling</title>
<par>Namespace handling has changed. There are no entity or processing instruction
prefixes any longer and creating a proper <class>Prefixes</class> object has
been simplified. For example:</par>
<prog>
prefixes = xsc.Prefixes()
prefixes.addElementPrefixMapping(None, html)
prefixes.addElementPrefixMapping("svg", svg)
</prog>
<par>can be simplified to:</par>
<prog>
prefixes = xsc.Prefixes(html, svg=svg)
</prog>
<par>The three arguments <arg>elementmode</arg>, <arg>entitymode</arg> and
<arg>procinstmode</arg> for the publishing methods have been combined into
<arg>prefixmode</arg>, which is used for elements only.</par>
</section>

<section><title>Changed namespaces</title>
<par>The character reference classes from <module>ll.xist.ns.html</module>
have been moved to a separate namespace <module>ll.xist.ns.chars</module>.</par>
<par>The processing instructions <class>eval_</class> and <class>exec_</class>
from the <module>ll.xist.ns.code</module> module have been renamed to
<class>pyeval</class> and <class>pyexec</class>.</par>
</section>

<section><title>Changed method names</title>
<par>The method names <method>beginPublication</method>, <method>endPublication</method>
and <method>doPublication</method> have been lowercased.</par>
</section>
</section>


<section><title>Migrating to version 2.2</title>

<section><title>Attribute methods</title>

<par>The <class>Element</class> methods for accessing attributes
have been deprecated. So instead of <lit><rep>node</rep>.hasattr("<rep>attr</rep>")</lit>,
you should use:</par>

<prog>
"<rep>attr</rep>" in <rep>node</rep>.attrs
</prog>

<par>The same holds for checking whether an attribute is allowed. You can use the following code:</par>

<prog>
"<rep>attr</rep>" in <rep>node</rep>.Attrs
</prog>

<par>or:</par>

<prog>
"<rep>attr</rep>" in <rep>NodeClass</rep>.Attrs
</prog>

<par>or:</par>

<prog>
<rep>NodeClass</rep>.isallowed("<rep>attr</rep>")
</prog>

<par>Many <class>Attrs</class> methods have gained an additional parameter
<arg>xml</arg>, which specifies whether an attribute name should be
treated as the &xml; or the Python name of the attribute. Make sure
that you're not mixing up your arguments in the function call. The
safest method for this is using keyword arguments, e.g.:</par>

<prog>
<rep>node</rep>.attr.get("<rep>attr</rep>", default=42)
</prog>

</section>

<section><title>JSP directive page element</title>

<par>A <lit>contentType</lit> attribute is no longer generated for the
<class>ll.xist.ns.jsp.directive_page</class>. You have to explicitely use an attribute
<lit>contentType="<rep>text/html</rep>"</lit> to get a <lit>contentType</lit> attribute
in the resulting &jsp;. The <lit>charset</lit> option is generated automatically
from the encoding specified in the publisher.</par>

</section>

<section><title><class>autoimg</class> changes</title>

<par><class>ll.xist.htmlspecials.autoimg</class> will no longer touches existing <lit>width</lit>
or <lit>height</lit> attributes, so e.g. setting the width to twice the image size via
<lit>width="2*%(width)s"</lit> no longer works. You have to implement your own
version of <class>autoimg</class> if you need this.</par>

</section>

<section><title><method>find</method> changes</title>

<par><method>find</method> has been completely rewritten to use the new tree traversal filters.
For backwards compatibility a filter functor <class>ll.xist.xsc.FindOld</class> exists that
takes the same arguments as the old <method>find</method> method. I.e. you can replace:</par>
<prog>
node.find(
	type=html.a,
	attr={"href": None},
	searchchildren=True
)
</prog>
<par>with:</par>
<prog>
node.find(
	xsc.FindOld(
		type=html.a,
		attr={"href": None},
		searchchildren=True
	),
	skiproot=True
)
</prog>
<par>But one minor difference remains: when <arg>skiproot</arg> is set to true in the new
<method>find</method> method, the attributes of the root element will <em>not</em> be traversed.
With the old method they would be traversed.</par>

</section>

<section><title><class>doc</class> changes</title>

<par><class>programlisting</class> has been renamed to <class>prog</class>.</par>

</section>

<section><title>Namespace changes</title>

<par>Namespaces can no longer be instantiated. Instead you have to derive a class
from <class>Namespace</class>. The <arg>xmlprefix</arg> argument from the constructor
becomes a class attribute <lit>xmlname</lit> and the argument <arg>xmlname</arg>
becomes <lit>xmlurl</lit>.</par>

<par>Adding element classes to the namespace is now done with the
<class>Namespace</class> classmethod <method>update</method>.
If you want the turn a namespace into a module, you can use the classmethod
<method>makemod</method> instead of <method>update</method>.</par>

<example><title>Old method</title>
<prog>
xmlns = xsc.Namespace("foo", "http://www.foo.com/", vars()
</prog>
</example>

<example><title>New method</title>
<prog>
class xmlns(xsc.Namespace):
	xmlname = "foo"
	xmlurl = "http://www.foo.com/"
xmlns.makemod(vars())
</prog>
</example>

</section>

</section>


<section><title>Migrating to version 2.1</title>

<ulist>
<item>The method <method>withSep</method> has been renamed
to <method>withsep</method>.</item>

<item>The argument <arg>defaultEncoding</arg> for the various
parsing functions has been renamed to <arg>encoding</arg>.</item>
</ulist>

</section>


<section><title>Migrating to version 2.0</title>

<section><title>Attribute handling</title>

<par>The biggest change is in the way attributes are defined. In older
versions you had to define a class attribute <lit>attrHandlers</lit>
that mapped attribute names to attribute classes. This created problems
with <z>illegal</z> attribute names (e.g. <lit>class</lit> and <lit>http-equiv</lit>
in &html;), so for them an ugly workaround was implemented. With 2.0
this is no longer neccessary. Defining attributes is done via a
class <class>Attrs</class> nested inside the element class like this:</par>

<example>
<prog>
class foo(xsc.Element):
	class Attrs(xsc.Element.Attrs):
		class bar(xsc.TextAttr)
			"The bar attribute"
			default = "spam"
			values = ("spam", "eggs")
			required = True
		class baz(xsc.URLAttr):
			"The baz attribute"
</prog>
</example>

<par>Default values, set of allowed attributes values and
whether the attribute is required can be defined via
class attributes as shown above. You should (directly
or indirecty) inherit from <class>xsc.Element.Attrs</class>,
because this class implements handling of global attributes.
If you want to inherit some attributes (e.g. from your
base class), you can derive from the appropriate
<class>Attrs</class> class. Removing an attribute you inherited
can be done like this:</par>

<example>
<prog>
class bar(foo):
	class Attrs(foo.Attrs):
		baz = None
</prog>
</example>

<par>This removes the attribute <lit>baz</lit> inherited
from <class>foo</class>.</par>

<par>For attribute names that are no legal Python identifiers,
the same method can be used as for element classes: Define
the real &xml; name via a class attribute. This class attribute
has been renamed from <lit>name</lit> to <lit>xmlname</lit>.</par>

<par>This also means that you always have to use the Python
name when using attributes now. The &xml; name will only
be used for parsing and publishing.</par>

<par>&xist; 2.0 tries to be as backwards compatible as
possible: An existing <lit>attrHandlers</lit> attribute
will be converted to an <class>Attrs</class> class on the
fly (and will generate a <class>DeprecationWarning</class> when
the class is created). An <class>Attrs</class> class will
automatically generate an <lit>attrHandlers</lit> attribute,
so it's possible to derive from new element classes in the old way.
The only situation where this won't work, is with
attributes where the Python and &xml; name differ, you
have to use <z>new style</z> attributes there.</par>
</section>

<section><title>Namespace support</title>

<par>&xist; supports &xml; namespaces now and for parsing it's
possible to configure which namespaces should be available
for instantiating classes from. For more info about this
refer to the documentation for the class <pyref module="ll.xist.xsc" class="Prefixes"><class>Prefixes</class></pyref>.</par>

<par>Before 2.0 the &xml; name for a namespace object
was pretty useless, now it can be used as the namespace
name in <lit>xmlns</lit> attributes and it will be used
for that when publishing and specifying an <lit>elementmode</lit>
of <lit>2</lit> in the call to the publishing method or the constructor
of the publisher.</par>

<par>Namespace objects should now be named <lit>xmlns</lit>
instead of <lit>namespace</lit> as before.</par>

</section>

<section><title>Global attributes</title>

<par>Global attributes are supported now, e.g. the attributes
<lit>xml:lang</lit> and <lit>xml:space</lit> can be specified
in an element constructor like this:</par>

<example>
<prog>
from ll.xist import xsc
from ll.xist.ns import html, xml

node = html.html(
	<rep>content</rep>,
	{(xml, "lang"): "en", (xml, "space"): "preserve"},
	lang="en"
)
</prog>
</example>

<par>Instead of the module object (which must contain a
namespace object named <lit>xmlns</lit>), you can also
pass the namespace object itself (i.e. <lit>xml.xmlns</lit>)
or the namespace name (i.e. <lit>"http://www.w3.org/XML/1998/namespace"</lit>).</par>

</section>

<section><title>Namespace changes</title>

<par>The classes <class>XML</class> and <class>XML10</class>
have been moved from <module>ll.xist.xsc</module> to
<module>ll.xist.ns.xml</module>.</par>

<par>All the classes in <module>ll.xist.ns.specials</module>
that are specific to &html; generation have been moved
to the new module <module>ll.xist.ns.htmlspecials</module>.</par>

<par>The module <module>ll.xist.ns.html</module> has been updated
to the &xhtml; specification, so there might be some changes.
The new feature for specifying attribute restrictions has
been used, so e.g. you'll get warnings for missing <lit>alt</lit>
attributes in <class>img</class> elements. These warnings
are issued via the warning framework. Refer to the documentation
for the <module>warnings</module> module to find out how to
configure the handling of these warnings.</par>

</section>

<section><title>Miscellaneous</title>

<par>&xist; now requires at least Python 2.2.1 because
the integer constants <lit>True</lit> and <lit>False</lit>
are used throughout the code wherever appropriate. These
constants will become instances of the new class <class>bool</class>
in Python 2.3. You might want to change your code too, to
use these new constant (e.g. when setting the element
class attribute <lit>empty</lit>).</par>

<par>Using mixed case method names was a bad idea, because
this conflicts with Python's convention of using
all lowercase names (without underscores). These method
names will be fixed in the next few &xist; versions.
The first names that where changed were the element methods
<method>getAttr</method> and <method>hasAttr</method>, which
have been renamed to <method>getattr</method> and
<method>hasattr</method> respectively. <method>getAttr</method>
and <method>hasAttr</method> are still there and can be called
without generating <class>DeprecationWarning</class>s, but they
will start to generate warnings in the upcoming versions.</par>

</section>
