genshi/genshi-test: doc/templates.txt comparison

comparison doc/templates.txt @ 902:09cc3627654c experimental-inline

Sync `experimental/inline` branch with [source:trunk@1126].

author	cmlenz
date	Fri, 23 Apr 2010 21:08:26 +0000
parents	1837f39efd6f
children

comparison

equal deleted inserted replaced

-:de82830f8816
+:09cc3627654c
 Synopsis
 --------
 A Genshi *markup template* is a well-formed XML document with embedded Python
 used for control flow and variable substitution. Markup templates should be
-used to generate any kind of HTML or XML output, as they provide many advantages
+used to generate any kind of HTML or XML output, as they provide a number of
-over simple text-based templates (such as automatic escaping of strings).
+advantages over simple text-based templates (such as automatic escaping of
+variable data).
-The following illustrates a very basic Genshi markup template:
+The following is a simple Genshi markup template:
 .. code-block:: genshi
 <?python
 title = "A Genshi Template"
 </body>
 </html>
 This example shows:
-(a) a Python code block, using a processing instruction
+(a) a Python code block in a processing instruction
 (b) the Genshi namespace declaration
 (c) usage of templates directives (``py:content`` and ``py:for``)
 (d) an inline Python expression (``${fruit}``).
 The template would generate output similar to this:
 <li>I like kiwis</li>
 </ul>
 </body>
 </html>
-A *text template* is a simple plain text document that can also contain embedded
+A *text template* is a simple plain text document that can also contain
-Python code. Text templates can be used to generate simple *non-markup* text
+embedded Python code. Text templates are intended to be used for simple
-formats, such as the body of an plain text email. For example:
+*non-markup* text formats, such as the body of an plain text email. For
+example:
 .. code-block:: genshitext
 Dear $name,
 .. code-block:: pycon
 >>> from genshi.template import MarkupTemplate
 >>> tmpl = MarkupTemplate('<h1>Hello, $name!</h1>')
 >>> stream = tmpl.generate(name='world')
->>> print stream.render('xhtml')
+>>> print(stream.render('xhtml'))
 <h1>Hello, world!</h1>
 .. note:: See the Serialization_ section of the `Markup Streams`_ page for
 information on configuring template output options.
 .. code-block:: pycon
 >>> from genshi.template import TextTemplate
 >>> tmpl = TextTemplate('Hello, $name!')
 >>> stream = tmpl.generate(name='world')
->>> print stream
+>>> print(stream)
 Hello, world!
 .. note:: If you want to use text templates, you should consider using the
 ``NewTextTemplate`` class instead of simply ``TextTemplate``. See
 the `Text Template Language`_ page.
 .. _serialization: streams.html#serialization
 .. _`Text Template Language`: text-templates.html
 .. _`Markup Streams`: streams.html
-Using a template loader provides the advantage that “compiled” templates are
+Using a `template loader`_ provides the advantage that “compiled” templates are
 automatically cached, and only parsed again when the template file changes. In
 addition, it enables the use of a *template search path*, allowing template
 directories to be spread across different file-system locations. Using a
 template loader would generally look as follows:
 from genshi.template import TemplateLoader
 loader = TemplateLoader([templates_dir1, templates_dir2])
 tmpl = loader.load('test.html')
 stream = tmpl.generate(title='Hello, world!')
-print stream.render()
+print(stream.render())
 See the `API documentation <api/index.html>`_ for details on using Genshi via
 the Python API.
+.. _`template loader`: loader.html
 .. _`expressions`:
 ------------------------------------
 Template Expressions and Code Blocks
 .. code-block:: pycon
 >>> from genshi.template import MarkupTemplate
 >>> tmpl = MarkupTemplate('<em>${items[0].capitalize()} item</em>')
->>> print tmpl.generate(items=['first', 'second'])
+>>> print(tmpl.generate(items=['first', 'second']))
 <em>First item</em>
 Expressions support the full power of Python. In addition, it is possible to
 access items in a dictionary using “dotted notation” (i.e. as if they were
 attributes), and vice-versa (i.e. access attributes as if they were items in a
 .. code-block:: pycon
 >>> from genshi.template import MarkupTemplate
 >>> tmpl = MarkupTemplate('<em>${dict.foo}</em>')
->>> print tmpl.generate(dict={'foo': 'bar'})
+>>> print(tmpl.generate(dict={'foo': 'bar'}))
 <em>bar</em>
 Because there are two ways to access either attributes or items, expressions
 do not raise the standard ``AttributeError`` or ``IndexError`` exceptions, but
 rather an exception of the type ``UndefinedError``. The same kind of error is
 .. code-block:: pycon
 >>> from genshi.template import MarkupTemplate
 >>> tmpl = MarkupTemplate('<em>$foo</em>') # Wanted "$foo" as literal output
->>> print tmpl.generate()
+>>> print(tmpl.generate())
 Traceback (most recent call last):
 ...
 UndefinedError: "foo" not defined
 >>> tmpl = MarkupTemplate('<em>$$foo</em>')
->>> print tmpl.generate()
+>>> print(tmpl.generate())
 <em>$foo</em>
 But note that this is not necessary if the characters following the dollar sign
 do not qualify as an expression. For example, the following needs no escaping:
 .. code-block:: pycon
 >>> tmpl = MarkupTemplate('<script>$(function() {})</script>')
->>> print tmpl.generate()
+>>> print(tmpl.generate())
 <script>$(function() {})</script>
 On the other hand, Genshi will always replace two dollar signs in text with a
 single dollar sign, so you'll need to use three dollar signs to get two in the
 output:
 .. code-block:: pycon
 >>> tmpl = MarkupTemplate('<script>$$$("div")</script>')
->>> print tmpl.generate()
+>>> print(tmpl.generate())
 <script>$$("div")</script>
 .. _`code blocks`:
 ``getattr()`` or ``get()`` functions, or the ``in`` operator, just as you would
 in regular Python code:
 >>> from genshi.template import MarkupTemplate
 >>> tmpl = MarkupTemplate('<p>${defined("doh")}</p>')
->>> print tmpl.generate().render('xhtml')
+>>> print(tmpl.generate().render('xhtml'))
 <p>False</p>
 .. note:: Lenient error handling was the default in Genshi prior to version 0.5.
 Strict mode was introduced in version 0.4, and became the default in
 0.5. The reason for this change was that the lenient error handling
 .. code-block:: pycon
 >>> from genshi.template import MarkupTemplate
 >>> tmpl = MarkupTemplate('<p>${doh}</p>', lookup='lenient')
->>> print tmpl.generate().render('xhtml')
+>>> print(tmpl.generate().render('xhtml'))
 <p></p>
 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:
 .. code-block:: pycon
 >>> from genshi.template import MarkupTemplate
 >>> tmpl = MarkupTemplate('<p>${doh.oops}</p>', lookup='lenient')
->>> print tmpl.generate().render('xhtml')
+>>> print(tmpl.generate().render('xhtml'))
 Traceback (most recent call last):
 ...
 UndefinedError: "doh" not defined
 If you need to know whether a variable is defined, you can check its type
 .. code-block:: pycon
 >>> from genshi.template import MarkupTemplate
 >>> tmpl = MarkupTemplate('<p>${type(doh) is not Undefined}</p>',
 ...                       lookup='lenient')
->>> print tmpl.generate().render('xhtml')
+>>> print(tmpl.generate().render('xhtml'))
 <p>False</p>
 Alternatively, the built-in functions defined_ or value_of_ can be used in this
 case.

Mercurial > genshi > genshi-test

comparison doc/templates.txt @ 902:09cc3627654c experimental-inline