<?xml version='1.0' encoding='utf-8'?>
<spc:wrap xmlns="http://xmlns.livinglogic.de/xist/ns/doc" xmlns:spc="http://xmlns.livinglogic.de/xist/ns/specials">
<section><h>&url;s</h>

<p>For &url; handling &xist; uses the module
<pyref module="ll.url"><mod>ll.url</mod></pyref>. Refer to its documentation
for the basic functionality (especially regarding the methods
<pyref module="ll.url" class="URL" method="__div__"><meth>__div__</meth></pyref>
and <pyref module="ll.url" class="URL" method="relative"><meth>relative</meth></pyref>).</p>

<p>When &xist; parses an &xml; resource it uses a so called <z>base</z> &url;.
This base &url; can be passed to all parsing functions. If it isn't specified
it defaults to the &url; of the resource being parsed. This base &url; will
be prepended to all &url;s that are read during parsing:</p>
<tty>
<prompt>&gt;&gt;&gt; </prompt><input>from ll.xist import parse</input>
<prompt>&gt;&gt;&gt; </prompt><input>from ll.xist.ns import html</input>
<prompt>&gt;&gt;&gt; </prompt><input>node = parse.parsestring('&lt;img src="eggs.png"/&gt;', base="root:spam/index.html")</input>
<prompt>&gt;&gt;&gt; </prompt><input>print node.bytes()</input>
&lt;img src="root:spam/eggs.png" /&gt;
</tty>

<p>For publishing a base &url; can be specified too. &url;s will be published
relative to this base &url; with the exception of relative &url;s in the tree.
This means:</p>
<ul>
<li>When you have a relative &url; (e.g. <lit>#top</lit>) generated by a <meth>convert</meth>
call, this &url; will stay the same when publishing.</li>
<li>Base &url;s for parsing should never be relative: Relative base
&url;s will be prepended to all relative &url;s in the file, but this will not be
reverted for publishing. In most cases the base &url; should be a
<lit>root</lit> &url; when you parse local files.</li>
<li>When you parse remote web pages you can either
omit the <var>base</var> argument, so it will default to the
&url; being parsing, so that links, images, etc. on the page
will still point back to their original location, or you
might want to use the empty &url; <lit>URL()</lit> as the
base, so you'll get all &url;s in the page as they are.</li>
<li><p>When &xist; is used as a compiler for static pages, you're
going to read source &xml; files, do a conversion and write the
result to a new target file. In this case you should probably
use the &url; of the target file for both parsing and
publishing. Let's assume we have an &url; <lit>#top</lit>
in the source file. When we use the <z>real</z> file names
for parsing and publishing like this:</p>
<prog>
node = parse.parsefile("spam.htmlxsc", base="root:spam.htmlxsc")
node = node.conv()
node.write(open("spam.html", "wb"), base="root:spam.html")
</prog>
<p>the following will happen: The &url; <lit>#top</lit>
will be parsed as <lit>root:spam.htmlxsc#top</lit>. After
conversion this will be written to <file>spam.html</file>
relative to the &url; <lit>root:spam.html</lit>, which results
in <lit>spam.html#top</lit>, which works, but is not what you
want.</p>
<p>When you use <lit>root:spam.html</lit> both for parsing
and publishing, <lit>#top</lit> will be written to the target file
as expected.</p></li>
</ul>

</section>


<section><h>Pretty printing &xml;</h>
<p>The method <meth>pretty</meth> can be used for pretty printing &xml;.
It returns a new version of the node, with additional white space between the
elements:</p>
<example>
<prog>
from ll.xist.ns import html
node = html.html(
	html.head(
		html.title(u"foo"),
	),
	html.body(
		html.div(
			html.h1(u"The ", html.em(u"foo"), u" page!"),
			html.p(u"Welcome to the ", html.em(u"foo"), u" page."),
		),
	),
)

print node.pretty().bytes()
</prog>
</example>
<p>This will print:</p>
<example>
<tty><![CDATA[
<html>
	<head>
		<title>foo</title>
	</head>
	<body>
		<div>
			<h1>The <em>foo</em> page!</h1>
			<p>Welcome to the <em>foo</em> page.</p>
		</div>
	</body>
</html>
]]></tty>
</example>
<p>Element content will only be modified if it doesn't contain
<class>Text</class> nodes, so mixed content will not be touched.</p>
</section>


<section><h>Automatic generation of image size attributes</h>

<p>The module <pyref module="ll.xist.ns.htmlspecials"><mod>ll.xist.ns.htmlspecials</mod></pyref>
contains an element <pyref module="ll.xist.ns.htmlspecials" class="autoimg"><class>autoimg</class></pyref>
that extends <pyref module="ll.xist.ns.html" class="img"><class>ll.xist.ns.html.img</class></pyref>.
When converted to &html; via the <pyref module="ll.xist.ns" class="Node" method="convert"><meth>convert</meth></pyref>
method the size of the image will be determined and the <lit>height</lit>
and <lit>width</lit> attributes will be set accordingly (if those attributes
are not set already).</p>

</section>


<section><h>Embedding Python code</h>
<p>It's possible to embed Python code into &xist; &xml; files. For this
&xist; supports two new processing instructions:
<pyref module="ll.xist.ns.code" class="pyexec"><lit>pyexec</lit></pyref>
and <pyref module="ll.xist.ns.code" class="pyeval"><lit>pyeval</lit></pyref> (in the module
<pyref module="ll.xist.ns.code"><mod>ll.xist.ns.code</mod></pyref>). The content of
<pyref module="ll.xist.ns.code" class="pyexec"><lit>pyexec</lit></pyref> will be
executed when the processing instruction node is converted.</p>

<p>The result of a call to <pyref module="ll.xist.xsc" class="Node" method="convert"><meth>convert</meth></pyref>
for a <pyref module="ll.xist.ns.code" class="pyeval"><lit>pyeval</lit></pyref> processing instruction is whatever the
Python code in the content returns. The processing instruction content is treated as the body
of a function, so you can put multiple return statements there.
The converter is available as the parameter <var>converter</var> inside
the processing instruction. For example, consider the following &xml; file:</p>

<prog>
&lt;?pyexec
	# sum
	def gauss(top=100):
		sum = 0
		for i in xrange(top+1):
			sum += i
		return sum
?&gt;
&lt;b&gt;&lt;?pyeval return gauss()?&gt;&lt;/b&gt;
</prog>

<p>Parsing this file and calling
<pyref module="ll.xist.xsc" class="Node" method="convert"><meth>convert</meth></pyref>
results in the following:</p>

<tty>
&lt;b&gt;5050&lt;/b&gt;
</tty>

</section>
</spc:wrap>
