Some text and ' @@ -43,7 +43,7 @@ * ``pos`` is a ``(filename, lineno, column)`` tuple that describes where the event “comes from”. -.. code-block:: python +.. code-block:: pycon >>> for kind, data, pos in stream: ... print kind, `data`, pos @@ -139,7 +139,7 @@ Here's the output from ``serialize()``: -.. code-block:: python +.. code-block:: pycon >>> for output in stream.serialize(): ... print `output` @@ -155,7 +155,7 @@ And here's the output from ``render()``: -.. code-block:: python +.. code-block:: pycon >>> print stream.render()

-This will produce the following output:: +This will produce the following output: + +.. code-block:: genshi

Hello, world! @@ -229,7 +249,9 @@ ============== By default, Genshi allows you to access variables that are not defined, without -raising a ``NameError`` exception as regular Python code would:: +raising a ``NameError`` exception as regular Python code would: + +.. code-block:: pycon >>> from genshi.template import MarkupTemplate >>> tmpl = MarkupTemplate('

${doh}

') @@ -237,7 +259,9 @@

You *will* however get an exception if you try to call an undefined variable, or -do anything else with it, such as accessing its attributes:: +do anything else with it, such as accessing its attributes: + +.. code-block:: pycon >>> from genshi.template import MarkupTemplate >>> tmpl = MarkupTemplate('

${doh.oops}

') @@ -247,7 +271,9 @@ UndefinedError: "doh" not defined If you need to know whether a variable is defined, you can check its type -against the ``Undefined`` class, for example in a conditional directive:: +against the ``Undefined`` class, for example in a conditional directive: + +.. code-block:: pycon >>> from genshi.template import MarkupTemplate >>> tmpl = MarkupTemplate('

${type(doh) is not Undefined}

') @@ -266,7 +292,9 @@ This mode can be chosen by passing the ``lookup='strict'`` keyword argument to the template initializer, or by passing the ``variable_lookup='strict'`` keyword -argument to the ``TemplateLoader`` initializer:: +argument to the ``TemplateLoader`` initializer: + +.. code-block:: pycon >>> from genshi.template import MarkupTemplate >>> tmpl = MarkupTemplate('

${doh}

', lookup='strict') diff --git a/doc/text-templates.txt b/doc/text-templates.txt --- a/doc/text-templates.txt +++ b/doc/text-templates.txt @@ -57,7 +57,9 @@ ``#if`` --------- -The content is only rendered if the expression evaluates to a truth value:: +The content is only rendered if the expression evaluates to a truth value: + +.. code-block:: genshitext #if foo ${bar} @@ -82,7 +84,9 @@ no ``#when`` branch matches, the ``#otherwise`` branch is be rendered. If the ``#choose`` directive has no argument the nested ``#when`` directives -will be tested for truth:: +will be tested for truth: + +.. code-block:: genshitext The answer is: #choose @@ -103,7 +107,9 @@ 1 If the ``#choose`` does have an argument, the nested ``#when`` directives will -be tested for equality to the parent ``#choose`` value:: +be tested for equality to the parent ``#choose`` value: + +.. code-block:: genshitext The answer is: #choose 1 @@ -132,7 +138,9 @@ ``#for`` ---------- -The content is repeated for every item in an iterable:: +The content is repeated for every item in an iterable: + +.. code-block:: genshitext Your items: #for item in items @@ -158,7 +166,9 @@ The ``#def`` directive can be used to create macros, i.e. snippets of template text that have a name and optionally some parameters, and that can be inserted -in other places:: +in other places: + +.. code-block:: genshitext #def greeting(name) Hello, ${name}! @@ -172,7 +182,9 @@ Hello, everyone else! If a macro doesn't require parameters, it can be defined as well as called -without the parenthesis. For example:: +without the parenthesis. For example: + +.. code-block:: genshitext #def greeting Hello, world! @@ -191,7 +203,9 @@ ------------ To reuse common parts of template text across template files, you can include -other files using the ``#include`` directive:: +other files using the ``#include`` directive: + +.. code-block:: genshitext #include "base.txt" @@ -208,7 +222,9 @@ Just like other directives, the argument to the ``#include`` directive accepts any Python expression, so the path to the included template can be determined -dynamically:: +dynamically: + +.. code-block:: genshitext #include '%s.txt' % filename @@ -232,7 +248,9 @@ than once, and that actually results in a database query, assigning the results to a variable using this directive would probably help. -For example:: +For example: + +.. code-block:: genshitext Magic numbers! #with y=7; z=x+10 diff --git a/doc/xml-templates.txt b/doc/xml-templates.txt --- a/doc/xml-templates.txt +++ b/doc/xml-templates.txt @@ -42,7 +42,9 @@ conditionals and looping, among others. To use directives in a template, the namespace must be declared, which is -usually done on the root element:: +usually done on the root element: + +.. code-block:: genshi -This is basically equivalent to the following:: +This is basically equivalent to the following: + +.. code-block:: genshi ${bar}

Given the data ``foo=True`` and ``bar='Hello'`` in the template context, this -would produce:: +would produce: + +.. code-block:: html

Hello

-This directive can also be used as an element:: +This directive can also be used as an element: + +.. code-block:: genshi

@@ -129,7 +141,9 @@ if no ``py:when`` branch matches, the ``py:otherwise`` branch is rendered. If the ``py:choose`` directive is empty the nested ``py:when`` directives will -be tested for truth:: +be tested for truth: + +.. code-block:: genshi

0 @@ -137,14 +151,18 @@ 2

-This would produce the following output:: +This would produce the following output: + +.. code-block:: html

If the ``py:choose`` directive contains an expression the nested ``py:when`` -directives will be tested for equality to the parent ``py:choose`` value:: +directives will be tested for equality to the parent ``py:choose`` value: + +.. code-block:: genshi

0 @@ -152,7 +170,9 @@ 2

-This would produce the following output:: +This would produce the following output: + +.. code-block:: html

1 @@ -167,19 +187,25 @@ ``py:for`` ---------- -The element is repeated for every item in an iterable:: +The element is repeated for every item in an iterable: + +.. code-block:: genshi

${item}

-Given ``items=[1, 2, 3]`` in the context data, this would produce:: +Given ``items=[1, 2, 3]`` in the context data, this would produce: + +.. code-block:: html

-This directive can also be used as an element:: +This directive can also be used as an element: + +.. code-block:: genshi

@@ -199,7 +225,9 @@ The ``py:def`` directive can be used to create macros, i.e. snippets of template code that have a name and optionally some parameters, and that can be -inserted in other places:: +inserted in other places: + +.. code-block:: genshi

@@ -209,7 +237,9 @@ ${greeting('everyone else')}

-The above would be rendered to:: +The above would be rendered to: + +.. code-block:: html

@@ -221,7 +251,9 @@

If a macro doesn't require parameters, it can be defined without the -parenthesis. For example:: +parenthesis. For example: + +.. code-block:: genshi

@@ -230,7 +262,9 @@ ${greeting()}

-The above would be rendered to:: +The above would be rendered to: + +.. code-block:: html

@@ -238,7 +272,9 @@

-This directive can also be used as an element:: +This directive can also be used as an element: + +.. code-block:: genshi

@@ -258,7 +294,9 @@ content. For example, the match template defined in the following template matches any -element with the tag name “greeting”:: +element with the tag name “greeting”: + +.. code-block:: genshi

@@ -267,7 +305,9 @@

-This would result in the following output:: +This would result in the following output: + +.. code-block:: html

@@ -282,7 +322,9 @@ .. _`Using XPath`: streams.html#using-xpath -This directive can also be used as an element:: +This directive can also be used as an element: + +.. code-block:: genshi

@@ -306,19 +348,25 @@ than once, and that actually results in a database query, assigning the results to a variable using this directive would probably help. -For example:: +For example: + +.. code-block:: genshi

$x $y $z

-Given ``x=42`` in the context data, this would produce:: +Given ``x=42`` in the context data, this would produce: + +.. code-block:: html

42 7 52

-This directive can also be used as an element:: +This directive can also be used as an element: + +.. code-block:: genshi

$x $y $z @@ -338,21 +386,27 @@ ``py:attrs`` ------------ -This directive adds, modifies or removes attributes from the element:: +This directive adds, modifies or removes attributes from the element: + +.. code-block:: genshi

Given ``foo={'class': 'collapse'}`` in the template context, this would -produce:: +produce: + +.. code-block:: html

Attributes with the value ``None`` are omitted, so given ``foo={'class': None}`` -in the context for the same template this would produce:: +in the context for the same template this would produce: + +.. code-block:: html

Hello

Hello

Bye @@ -410,13 +472,17 @@ This directive conditionally strips the top-level element from the output. When the value of the ``py:strip`` attribute evaluates to ``True``, the element is -stripped from the output:: +stripped from the output: + +.. code-block:: genshi

foo

-This would be rendered as:: +This would be rendered as: + +.. code-block:: html

foo @@ -462,7 +528,9 @@ For this, you need to declare the XInclude namespace (commonly bound to the prefix “xi”) and use the ```` element where you want the external -file to be pulled in:: +file to be pulled in: + +.. code-block:: genshi @@ -497,7 +567,9 @@ Incudes in Genshi are fully dynamic: Just like normal attributes, the `href` attribute accepts expressions, and directives_ can be used on the ```` element just as on any other element, meaning you can do -things like conditional includes:: +things like conditional includes: + +.. code-block:: genshi @@ -509,17 +581,23 @@ Comments -------- -Normal XML/HTML comment syntax can be used in templates:: +Normal XML/HTML comment syntax can be used in templates: + +.. code-block:: genshi However, such comments get passed through the processing pipeline and are by default included in the final output. If that's not desired, prefix the comment -text with an exclamation mark:: +text with an exclamation mark: + +.. code-block:: genshi Note that it does not matter whether there's whitespace before or after the -exclamation mark, so the above could also be written as follows:: +exclamation mark, so the above could also be written as follows: + +.. code-block:: genshi diff --git a/doc/xpath.txt b/doc/xpath.txt --- a/doc/xpath.txt +++ b/doc/xpath.txt @@ -62,24 +62,25 @@ Querying Streams ---------------- -:: - - from genshi.input import XML +The ``Stream`` class provides a ``select(path)`` function that can be used to +retrieve subsets of the stream: - doc = XML(''' - - -

Foo

- - -

Bar

- - - ''') - print doc.select('items/item[@status="closed"]/summary/text()') +.. code-block:: pycon -This would result in the following output:: - + >>> from genshi.input import XML + + >>> doc = XML(''' + ... + ... + ...

Foo

+ ... + ... + ...

Bar

+ ... + ... + ... ''') + + >>> print doc.select('items/item[@status="closed"]/summary/text()') Bar

Hello, $name!

Hello, world!