Mercurial > genshi > genshi-test

annotate doc/xml-templates.txt @ 525:b5116a918e70

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Updated overview diagram to include new transformation filter.
author cmlenz
date Mon, 18 Jun 2007 20:59:26 +0000
parents ca7d707d51b0
children 509b3a5e765e f725e48c9a5f f0bb2c5ea0ff
rev   line source
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
1 .. -*- mode: rst; encoding: utf-8 -*-
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
2
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
3 ============================
230
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
4 Genshi XML Template Language
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
5 ============================
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
6
241
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents: 237
diff changeset
7 Genshi provides a XML-based template language that is heavily inspired by Kid_,
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents: 237
diff changeset
8 which in turn was inspired by a number of existing template languages, namely
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents: 237
diff changeset
9 XSLT_, TAL_, and PHP_.
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
10
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
11 .. _kid: http://kid-templating.org/
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
12 .. _python: http://www.python.org/
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
13 .. _xslt: http://www.w3.org/TR/xslt
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
14 .. _tal: http://www.zope.org/Wikis/DevSite/Projects/ZPT/TAL
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
15 .. _php: http://www.php.net/
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
16
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
17 This document describes the template language and will be most useful as
241
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents: 237
diff changeset
18 reference to those developing Genshi XML templates. Templates are XML files of
bbed6d426678 * Added basic documentation for the text-based template language.
cmlenz
parents: 237
diff changeset
19 some kind (such as XHTML) that include processing directives_ (elements or
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
20 attributes identified by a separate namespace) that affect how the template is
442
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents: 429
diff changeset
21 rendered, and template expressions that are dynamically substituted by
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
22 variable data.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
23
442
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents: 429
diff changeset
24 See `Genshi Templating Basics <templates.html>`_ for general information on
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents: 429
diff changeset
25 embedding Python code in templates.
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents: 429
diff changeset
26
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
27
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
28 .. contents:: Contents
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
29 :depth: 3
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
30 .. sectnum::
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
31
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
32
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
33 .. _`directives`:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
34
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
35 -------------------
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
36 Template Directives
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
37 -------------------
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
38
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
39 Directives are elements and/or attributes in the template that are identified
230
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
40 by the namespace ``http://genshi.edgewall.org/``. They can affect how the
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
41 template is rendered in a number of ways: Genshi provides directives for
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
42 conditionals and looping, among others.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
43
394
ebc7c1a3bc4d Minor doc fixes.
cmlenz
parents: 354
diff changeset
44 To use directives in a template, the namespace must be declared, which is
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
45 usually done on the root element:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
46
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
47 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
48
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
49 <html xmlns="http://www.w3.org/1999/xhtml"
230
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
50 xmlns:py="http://genshi.edgewall.org/"
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
51 lang="en">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
52 ...
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
53 </html>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
54
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
55 In this example, the default namespace is set to the XHTML namespace, and the
230
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
56 namespace for Genshi directives is bound to the prefix “py”.
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
57
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
58 All directives can be applied as attributes, and some can also be used as
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
59 elements. The ``if`` directives for conditionals, for example, can be used in
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
60 both ways:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
61
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
62 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
63
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
64 <html xmlns="http://www.w3.org/1999/xhtml"
230
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
65 xmlns:py="http://genshi.edgewall.org/"
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
66 lang="en">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
67 ...
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
68 <div py:if="foo">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
69 <p>Bar</p>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
70 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
71 ...
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
72 </html>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
73
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
74 This is basically equivalent to the following:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
75
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
76 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
77
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
78 <html xmlns="http://www.w3.org/1999/xhtml"
230
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
79 xmlns:py="http://genshi.edgewall.org/"
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
80 lang="en">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
81 ...
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
82 <py:if test="foo">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
83 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
84 <p>Bar</p>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
85 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
86 </py:if>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
87 ...
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
88 </html>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
89
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
90 The rationale behind the second form is that directives do not always map
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
91 naturally to elements in the template. In such cases, the ``py:strip``
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
92 directive can be used to strip off the unwanted element, or the directive can
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
93 simply be used as an element.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
94
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
95
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
96 Conditional Sections
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
97 ====================
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
98
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
99 .. _`py:if`:
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
100
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
101 ``py:if``
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
102 ---------
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
103
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
104 The element is only rendered if the expression evaluates to a truth value:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
105
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
106 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
107
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
108 <div>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
109 <b py:if="foo">${bar}</b>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
110 </div>
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
111
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
112 Given the data ``foo=True`` and ``bar='Hello'`` in the template context, this
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
113 would produce:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
114
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
115 .. code-block:: html
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
116
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
117 <div>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
118 <b>Hello</b>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
119 </div>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
120
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
121 This directive can also be used as an element:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
122
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
123 .. code-block:: genshi
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
124
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
125 <div>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
126 <py:if test="foo">
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
127 <b>${bar}</b>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
128 </py:if>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
129 </div>
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
130
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
131 .. _`py:choose`:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
132 .. _`py:when`:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
133 .. _`py:otherwise`:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
134
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
135 ``py:choose``
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
136 -------------
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
137
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
138 The ``py:choose`` directive, in combination with the directives ``py:when``
404
ec05506d1bda Fix a couple of typos in the docs. Closes #99.
cmlenz
parents: 394
diff changeset
139 and ``py:otherwise`` provides advanced conditional processing for rendering one
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
140 of several alternatives. The first matching ``py:when`` branch is rendered, or,
404
ec05506d1bda Fix a couple of typos in the docs. Closes #99.
cmlenz
parents: 394
diff changeset
141 if no ``py:when`` branch matches, the ``py:otherwise`` branch is rendered.
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
142
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
143 If the ``py:choose`` directive is empty the nested ``py:when`` directives will
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
144 be tested for truth:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
145
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
146 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
147
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
148 <div py:choose="">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
149 <span py:when="0 == 1">0</span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
150 <span py:when="1 == 1">1</span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
151 <span py:otherwise="">2</span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
152 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
153
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
154 This would produce the following output:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
155
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
156 .. code-block:: html
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
157
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
158 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
159 <span>1</span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
160 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
161
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
162 If the ``py:choose`` directive contains an expression the nested ``py:when``
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
163 directives will be tested for equality to the parent ``py:choose`` value:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
164
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
165 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
166
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
167 <div py:choose="1">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
168 <span py:when="0">0</span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
169 <span py:when="1">1</span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
170 <span py:otherwise="">2</span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
171 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
172
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
173 This would produce the following output:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
174
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
175 .. code-block:: html
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
176
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
177 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
178 <span>1</span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
179 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
180
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
181
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
182 Looping
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
183 =======
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
184
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
185 .. _`py:for`:
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
186
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
187 ``py:for``
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
188 ----------
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
189
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
190 The element is repeated for every item in an iterable:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
191
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
192 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
193
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
194 <ul>
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
195 <li py:for="item in items">${item}</li>
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
196 </ul>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
197
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
198 Given ``items=[1, 2, 3]`` in the context data, this would produce:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
199
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
200 .. code-block:: html
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
201
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
202 <ul>
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
203 <li>1</li><li>2</li><li>3</li>
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
204 </ul>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
205
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
206 This directive can also be used as an element:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
207
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
208 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
209
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
210 <ul>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
211 <py:for each="item in items">
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
212 <li>${item}</li>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
213 </py:for>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
214 </ul>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
215
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
216
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
217 Snippet Reuse
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
218 =============
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
219
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
220 .. _`py:def`:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
221 .. _`macros`:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
222
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
223 ``py:def``
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
224 ----------
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
225
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
226 The ``py:def`` directive can be used to create macros, i.e. snippets of
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
227 template code that have a name and optionally some parameters, and that can be
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
228 inserted in other places:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
229
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
230 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
231
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
232 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
233 <p py:def="greeting(name)" class="greeting">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
234 Hello, ${name}!
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
235 </p>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
236 ${greeting('world')}
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
237 ${greeting('everyone else')}
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
238 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
239
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
240 The above would be rendered to:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
241
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
242 .. code-block:: html
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
243
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
244 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
245 <p class="greeting">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
246 Hello, world!
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
247 </p>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
248 <p class="greeting">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
249 Hello, everyone else!
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
250 </p>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
251 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
252
394
ebc7c1a3bc4d Minor doc fixes.
cmlenz
parents: 354
diff changeset
253 If a macro doesn't require parameters, it can be defined without the
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
254 parenthesis. For example:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
255
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
256 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
257
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
258 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
259 <p py:def="greeting" class="greeting">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
260 Hello, world!
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
261 </p>
394
ebc7c1a3bc4d Minor doc fixes.
cmlenz
parents: 354
diff changeset
262 ${greeting()}
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
263 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
264
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
265 The above would be rendered to:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
266
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
267 .. code-block:: html
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
268
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
269 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
270 <p class="greeting">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
271 Hello, world!
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
272 </p>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
273 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
274
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
275 This directive can also be used as an element:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
276
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
277 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
278
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
279 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
280 <py:def function="greeting(name)">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
281 <p class="greeting">Hello, ${name}!</p>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
282 </py:def>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
283 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
284
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
285
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
286 .. _Match Templates:
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
287 .. _`py:match`:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
288
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
289 ``py:match``
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
290 ------------
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
291
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
292 This directive defines a *match template*: given an XPath expression, it
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
293 replaces any element in the template that matches the expression with its own
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
294 content.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
295
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
296 For example, the match template defined in the following template matches any
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
297 element with the tag name “greeting”:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
298
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
299 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
300
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
301 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
302 <span py:match="greeting">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
303 Hello ${select('@name')}
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
304 </span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
305 <greeting name="Dude" />
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
306 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
307
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
308 This would result in the following output:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
309
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
310 .. code-block:: html
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
311
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
312 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
313 <span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
314 Hello Dude
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
315 </span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
316 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
317
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
318 Inside the body of a ``py:match`` directive, the ``select(path)`` function is
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
319 made available so that parts or all of the original element can be incorporated
451
bcc1d6c67a2f Fix broken link in documentation.
cmlenz
parents: 442
diff changeset
320 in the output of the match template. See `Using XPath`_ for more information
bcc1d6c67a2f Fix broken link in documentation.
cmlenz
parents: 442
diff changeset
321 about this function.
bcc1d6c67a2f Fix broken link in documentation.
cmlenz
parents: 442
diff changeset
322
bcc1d6c67a2f Fix broken link in documentation.
cmlenz
parents: 442
diff changeset
323 .. _`Using XPath`: streams.html#using-xpath
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
324
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
325 This directive can also be used as an element:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
326
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
327 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
328
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
329 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
330 <py:match path="greeting">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
331 <span>Hello ${select('@name')}</span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
332 </py:match>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
333 <greeting name="Dude" />
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
334 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
335
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
336
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
337 Variable Binding
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
338 ================
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
339
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
340 .. _`with`:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
341
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
342 ``py:with``
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
343 -----------
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
344
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
345 The ``py:with`` directive lets you assign expressions to variables, which can
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
346 be used to make expressions inside the directive less verbose and more
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
347 efficient. For example, if you need use the expression ``author.posts`` more
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
348 than once, and that actually results in a database query, assigning the results
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
349 to a variable using this directive would probably help.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
350
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
351 For example:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
352
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
353 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
354
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
355 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
356 <span py:with="y=7; z=x+10">$x $y $z</span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
357 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
358
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
359 Given ``x=42`` in the context data, this would produce:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
360
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
361 .. code-block:: html
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
362
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
363 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
364 <span>42 7 52</span>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
365 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
366
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
367 This directive can also be used as an element:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
368
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
369 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
370
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
371 <div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
372 <py:with vars="y=7; z=x+10">$x $y $z</py:with>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
373 </div>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
374
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
375 Note that if a variable of the same name already existed outside of the scope
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
376 of the ``py:with`` directive, it will **not** be overwritten. Instead, it
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
377 will have the same value it had prior to the ``py:with`` assignment.
230
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
378 Effectively, this means that variables are immutable in Genshi.
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
379
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
380
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
381 Structure Manipulation
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
382 ======================
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
383
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
384 .. _`py:attrs`:
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
385
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
386 ``py:attrs``
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
387 ------------
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
388
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
389 This directive adds, modifies or removes attributes from the element:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
390
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
391 .. code-block:: genshi
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
392
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
393 <ul>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
394 <li py:attrs="foo">Bar</li>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
395 </ul>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
396
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
397 Given ``foo={'class': 'collapse'}`` in the template context, this would
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
398 produce:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
399
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
400 .. code-block:: html
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
401
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
402 <ul>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
403 <li class="collapse">Bar</li>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
404 </ul>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
405
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
406 Attributes with the value ``None`` are omitted, so given ``foo={'class': None}``
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
407 in the context for the same template this would produce:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
408
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
409 .. code-block:: html
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
410
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
411 <ul>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
412 <li>Bar</li>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
413 </ul>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
414
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
415 This directive can only be used as an attribute.
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
416
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
417
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
418 .. _`py:content`:
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
419
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
420 ``py:content``
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
421 --------------
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
422
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
423 This directive replaces any nested content with the result of evaluating the
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
424 expression:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
425
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
426 .. code-block:: genshi
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
427
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
428 <ul>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
429 <li py:content="bar">Hello</li>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
430 </ul>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
431
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
432 Given ``bar='Bye'`` in the context data, this would produce:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
433
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
434 .. code-block:: html
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
435
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
436 <ul>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
437 <li>Bye</li>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
438 </ul>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
439
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
440 This directive can only be used as an attribute.
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
441
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
442
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
443 .. _`py:replace`:
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
444
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
445 ``py:replace``
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
446 --------------
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
447
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
448 This directive replaces the element itself with the result of evaluating the
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
449 expression:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
450
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
451 .. code-block:: genshi
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
452
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
453 <div>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
454 <span py:replace="bar">Hello</span>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
455 </div>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
456
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
457 Given ``bar='Bye'`` in the context data, this would produce:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
458
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
459 .. code-block:: html
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
460
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
461 <div>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
462 Bye
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
463 </div>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
464
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
465 This directive can only be used as an attribute.
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
466
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
467
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
468 .. _`py:strip`:
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
469
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
470 ``py:strip``
237
ad52b350e132 Flatten outline of XML templating documentation.
cmlenz
parents: 235
diff changeset
471 ------------
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
472
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
473 This directive conditionally strips the top-level element from the output. When
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
474 the value of the ``py:strip`` attribute evaluates to ``True``, the element is
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
475 stripped from the output:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
476
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
477 .. code-block:: genshi
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
478
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
479 <div>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
480 <div py:strip="True"><b>foo</b></div>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
481 </div>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
482
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
483 This would be rendered as:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
484
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
485 .. code-block:: html
235
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
486
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
487 <div>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
488 <b>foo</b>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
489 </div>
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
490
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
491 As a shorthand, if the value of the ``py:strip`` attribute is empty, that has
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
492 the same effect as using a truth value (i.e. the element is stripped).
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
493
b3cabd49de75 Beautified the HTML docs a bit.
cmlenz
parents: 230
diff changeset
494
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
495 .. _order:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
496
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
497 Processing Order
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
498 ================
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
499
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
500 It is possible to attach multiple directives to a single element, although not
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
501 all combinations make sense. When multiple directives are encountered, they are
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
502 processed in the following order:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
503
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
504 #. `py:def`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
505 #. `py:match`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
506 #. `py:when`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
507 #. `py:otherwise`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
508 #. `py:for`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
509 #. `py:if`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
510 #. `py:choose`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
511 #. `py:with`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
512 #. `py:replace`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
513 #. `py:content`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
514 #. `py:attrs`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
515 #. `py:strip`_
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
516
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
517
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
518 .. _includes:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
519
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
520 --------
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
521 Includes
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
522 --------
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
523
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
524 To reuse common snippets of template code, you can include other files using
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
525 XInclude_.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
526
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
527 .. _xinclude: http://www.w3.org/TR/xinclude/
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
528
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
529 For this, you need to declare the XInclude namespace (commonly bound to the
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
530 prefix “xi”) and use the ``<xi:include>`` element where you want the external
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
531 file to be pulled in:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
532
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
533 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
534
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
535 <html xmlns="http://www.w3.org/1999/xhtml"
230
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
536 xmlns:py="http://genshi.edgewall.org/"
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
537 xmlns:xi="http://www.w3.org/2001/XInclude">
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
538 <xi:include href="base.html" />
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
539 ...
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
540 </html>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
541
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
542 Include paths are relative to the filename of the template currently being
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
543 processed. So if the example above was in the file "``myapp/index.html``"
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
544 (relative to the template search path), the XInclude processor would look for
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
545 the included file at "``myapp/base.html``". You can also use Unix-style
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
546 relative paths, for example "``../base.html``" to look in the parent directory.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
547
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
548 Any content included this way is inserted into the generated output instead of
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
549 the ``<xi:include>`` element. The included template sees the same context data.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
550 `Match templates`_ and `macros`_ in the included template are also available to
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
551 the including template after the point it was included.
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
552
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
553 By default, an error will be raised if an included file is not found. If that's
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
554 not what you want, you can specify fallback content that should be used if the
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
555 include fails. For example, to to make the include above fail silently, you'd
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
556 write:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
557
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
558 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
559
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
560 <xi:include href="base.html"><xi:fallback /></xi:include>
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
561
273
4afa86e2ad83 Small doc fix.
cmlenz
parents: 244
diff changeset
562 See the `XInclude specification`_ for more about fallback content. Note though
4afa86e2ad83 Small doc fix.
cmlenz
parents: 244
diff changeset
563 that Genshi currently only supports a small subset of XInclude.
4afa86e2ad83 Small doc fix.
cmlenz
parents: 244
diff changeset
564
4afa86e2ad83 Small doc fix.
cmlenz
parents: 244
diff changeset
565 .. _`xinclude specification`: http://www.w3.org/TR/xinclude/
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
566
230
24757b771651 Renamed Markup to Genshi in repository.
cmlenz
parents: 226
diff changeset
567 Incudes in Genshi are fully dynamic: Just like normal attributes, the `href`
442
ff7c72b52fb2 Back out [510] and instead implement configurable error handling modes. The default is the old 0.3.x behaviour, but more strict error handling is available as an option.
cmlenz
parents: 429
diff changeset
568 attribute accepts expressions, and directives_ can be used on the
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
569 ``<xi:include />`` element just as on any other element, meaning you can do
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
570 things like conditional includes:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
571
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
572 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
573
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
574 <xi:include href="${name}.html" py:if="not in_popup"
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
575 py:for="name in ('foo', 'bar', 'baz')" />
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
576
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
577
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
578 .. _comments:
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
579
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
580 --------
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
581 Comments
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
582 --------
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
583
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
584 Normal XML/HTML comment syntax can be used in templates:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
585
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
586 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
587
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
588 <!-- this is a comment -->
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
589
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
590 However, such comments get passed through the processing pipeline and are by
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
591 default included in the final output. If that's not desired, prefix the comment
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
592 text with an exclamation mark:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
593
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
594 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
595
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
596 <!-- !this is a comment too, but one that will be stripped from the output -->
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
597
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
598 Note that it does not matter whether there's whitespace before or after the
510
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
599 exclamation mark, so the above could also be written as follows:
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
600
ca7d707d51b0 Use syntax highlighting on all the other doc pages, too.
cmlenz
parents: 451
diff changeset
601 .. code-block:: genshi
226
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
602
09f869a98149 Add reStructuredText documentation files.
cmlenz
parents:
diff changeset
603 <!--! this is a comment too, but one that will be stripped from the output -->
Copyright (C) 2012-2017 Edgewall Software