Mercurial > genshi > genshi-test

annotate doc/xml-templates.txt @ 512:bdaf75981ec7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Fix for #125 (text template handling unicode source). Thanks to Christian Boos for the patch.
author cmlenz
date Wed, 06 Jun 2007 11:31:44 +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