/usr/share/doc/rest2web/html/reference/uservalues.html is in rest2web-doc 0.5.2~alpha+svn-r248-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<title>The User Values</title>
<link rel="stylesheet" href="../stylesheets/rest2web.css" type="text/css" />
<link rel="stylesheet" href="../stylesheets/voidspace_docutils2.css" type="text/css" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="description" content="rest2web - build websites with Python and docutils." />
<meta name="author" content="Michael Foord" />
<meta name="copyright" content="© 2003-2006 Michael Foord, subject to BSD License" />
<meta name="keywords" content="rest2web - build websites with Python and docutils,
rest, restructured text, text, website, internet, web, net, web builder, site,
site builder, docutils, i18n, internationalization, templates, templating,
python, " />
</head>
<body style="background: url(../images/logos/img_background.gif) top center repeat-y;">
<div id="wrap">
<div id="header-section">
<a href="http://www.voidspace.org.uk/python/index.shtml" title="Voidspace"><img src="../images/logos/header760.gif" alt="Voidspace"/></a>
<p align="center" class="headertitle"><span style="font-size:130%">rest2web:</span> Building Websites Across the Known Universe</p>
</div>
<div id="header">
<ul>
<li><a href="../index.html">rest2web</a></li>
<li>></li>
<li><a href="index.html">Reference</a></li>
<li>></li>
<li>uservalues</li>
</ul>
</div>
<table>
<tr>
<td><img src="../images/logos/1.gif" width="1" height="1" alt="" /></td>
<!-- main content cell first, with rowspan=2 -->
<td valign="top" align="left" rowspan="2">
<div id="middle-column">
<a name="startcontent" id="startcontent"></a>
<div id="gallery">
<div class="document" id="the-user-values">
<h1 class="title">The User Values</h1>
<h2 class="subtitle" id="extra-values-in-your-templates">Extra Values in Your Templates</h2>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#introduction" id="id7">Introduction</a></li>
<li><a class="reference internal" href="#uservalues" id="id8">uservalues</a><ul>
<li><a class="reference internal" href="#uservalues-in-pages" id="id9">uservalues in Pages</a></li>
<li><a class="reference internal" href="#uservalues-at-the-command-line" id="id10">uservalues at the Command Line</a></li>
<li><a class="reference internal" href="#uservalues-in-the-config-file" id="id11">uservalues in the config file</a></li>
<li><a class="reference internal" href="#reserved-names" id="id12">Reserved Names</a></li>
</ul>
</li>
<li><a class="reference internal" href="#the-body-value" id="id13">The body Value</a><ul>
<li><a class="reference internal" href="#translations" id="id14">Translations</a></li>
</ul>
</li>
<li><a class="reference internal" href="#the-order-of-processing" id="id15">The Order of Processing</a></li>
<li><a class="reference internal" href="#footnotes" id="id16">Footnotes</a></li>
</ul>
</div>
<div class="section" id="introduction">
<h1><a class="toc-backref" href="#id7">Introduction</a></h1>
<p><strong>rest2web</strong> generates pages by inserting special values into your web page
templates. These values include the body of the page, the title and so on. You can
see from the <a class="reference external" href="../templating.html">templates</a> page, all the values that you can use in your templates.
<em>uservalues</em> are a way of inserting extra values into your template. As you
might guess, you specify the names and values.</p>
<p>One obvious use of this is to provide several different translations <a class="footnote-reference" href="#id4" id="id1">[1]</a> of
your website.</p>
<p>The uservalues can be in HTML <em>or</em> in ReST format. They use two slightly
different syntaxes so that rest2web knows whether to render the uservalue into
HTML or not.</p>
<p>Uservalues can be put into your pages (via your content or your templates),
using the <a class="reference external" href="../templating.html">templating system</a>.</p>
</div>
<div class="section" id="uservalues">
<h1><a class="toc-backref" href="#id8">uservalues</a></h1>
<p><em>uservalues</em> can be specified in three ways :</p>
<ol class="arabic simple">
<li>In each page. These <em>uservalues</em> are local to the page.</li>
<li>At the <a class="reference external" href="../command_line.html">command line</a>.</li>
<li>In the <a class="reference external" href="../config_file.html">config file</a>.</li>
</ol>
<p>Uservalues are effectively new variables (or names) you can use in your templates.
For example, if you create a uservalue 'site_wide_title', you can use it in your
templates like this :</p>
<blockquote>
<tt class="docutils literal"><span class="pre"><%</span> <span class="pre">site_wide_title</span> <span class="pre">%></span></tt></blockquote>
<p>or :</p>
<blockquote>
<tt class="docutils literal"><span class="pre"><#</span> <span class="pre">print</span> <span class="pre">site_wide_title</span> <span class="pre">#></span></tt></blockquote>
<p>For global values (available to every page), the most convenient thing to do is
to define them in your config file.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">Changes to uservalues (in embedded code, through <tt class="docutils literal"><span class="pre"><$</span> <span class="pre">...</span> <span class="pre">$></span></tt> tags)
are <em>not</em> propagated to the main namespace.</p>
</div>
<div class="section" id="uservalues-in-pages">
<h2><a class="toc-backref" href="#id9">uservalues in Pages</a></h2>
<p><em>uservalues</em> can be specified in each page in a similar way to the restindex.
uservalues are specified <em>immediately after</em> the restindex. :</p>
<pre class="literal-block">
restindex
crumb: A Page
/restindex
uservalues
value1: Some Value
heading: <h1>A Heading</h1>
long_value: """
A multi line value
which spreads across
several lines.
"""
another_long_value:"""
This one
has a big indent
in front of it ! """
/uservalues
</pre>
<p>An addition to the restindex syntax, is that multiline values use triple quotes.</p>
<div class="caution">
<p class="first admonition-title">Caution!</p>
<p class="last">Indentation is not removed from multi line values. The text between the
triple quotes is inserted literally wherever you use the value. You can use
single or double quote marks.</p>
</div>
<p>There is one special value, the <tt class="docutils literal"><span class="pre">body</span></tt> value discussed below.</p>
</div>
<div class="section" id="uservalues-at-the-command-line">
<h2><a class="toc-backref" href="#id10">uservalues at the Command Line</a></h2>
<p>It is also possible to pass uservalues to <strong>rest2web</strong> at the command line.
These will be available in <em>every</em> page.</p>
</div>
<div class="section" id="uservalues-in-the-config-file">
<h2><a class="toc-backref" href="#id11">uservalues in the config file</a></h2>
<p>You can specify uservalues in the <tt class="docutils literal"><span class="pre">uservalues</span></tt> section of the config file.
These are also available in every page.</p>
<p>To do this, you need to add something like the following to the bottom of
your site config (<tt class="docutils literal"><span class="pre">r2w.ini</span></tt>) file :</p>
<pre class="literal-block">
[uservalues]
site_wide_title = 'Some Title'
site_wide_subtitle = 'Some Subtitle'
</pre>
</div>
<div class="section" id="reserved-names">
<h2><a class="toc-backref" href="#id12">Reserved Names</a></h2>
<p>You can't use any name that shadows a name already used by the templating
system. This means that the following names are all reserved. Trying to use
them will cause a <tt class="docutils literal"><span class="pre">SyntaxError</span></tt>. :</p>
<div class="pysrc"><span class="pytext">reserved_names</span> <span class="pyoperator">=</span> <span class="pyoperator">[</span><br />
<span class="pystring">'title'</span><span class="pyoperator">,</span> <span class="pystring">'breadcrumbs'</span><span class="pyoperator">,</span> <span class="pystring">'sections'</span><span class="pyoperator">,</span> <span class="pystring">'pagename'</span><span class="pyoperator">,</span> <span class="pystring">'pagepath'</span><span class="pyoperator">,</span><br />
<span class="pystring">'encoding'</span><span class="pyoperator">,</span> <span class="pystring">'output_encoding'</span><span class="pyoperator">,</span> <span class="pystring">'final_encoding'</span><span class="pyoperator">,</span> <span class="pystring">'path_to_root'</span><span class="pyoperator">,</span><br />
<span class="pystring">'sectionlist'</span><span class="pyoperator">,</span> <span class="pystring">'rest_dict'</span><span class="pyoperator">,</span> <span class="pystring">'doc'</span><span class="pyoperator">,</span> <span class="pystring">'stdout'</span><span class="pyoperator">,</span> <span class="pystring">'modified'</span><span class="pyoperator">,</span> <span class="pystring">'modtime'</span><span class="pyoperator">,</span><br />
<span class="pystring">'template_file'</span><span class="pyoperator">,</span> <span class="pystring">'template_encoding'</span><span class="pyoperator">,</span> <span class="pystring">'indexpage'</span><span class="pyoperator">,</span> <span class="pystring">'indextree'</span><span class="pyoperator">,</span><br />
<span class="pystring">'thispage'</span><span class="pyoperator">,</span> <span class="pystring">'sidebar'</span><span class="pyoperator">,</span> <span class="pystring">'minibar'</span><span class="pyoperator">,</span> <span class="pystring">'print_crumbs'</span><span class="pyoperator">,</span> <span class="pystring">'Processor'</span><span class="pyoperator">,</span> <span class="pystring">'tags'</span><span class="pyoperator">,</span><br />
<span class="pystring">'default_section'</span><span class="pyoperator">,</span> <span class="pystring">'modtime'</span><span class="pyoperator">,</span> <span class="pystring">'modtimeiso'</span><br />
<span class="pyoperator">]</span><span class="pytext"></span></div><div class="note">
<p class="first admonition-title">Note</p>
<p class="last">See that <tt class="docutils literal"><span class="pre">title</span></tt> is a reserved name. If you want to set the page title, you should use the <tt class="docutils literal"><span class="pre">page-title</span></tt> keyword in your <em>restindex</em>.</p>
</div>
</div>
</div>
<div class="section" id="the-body-value">
<h1><a class="toc-backref" href="#id13">The body Value</a></h1>
<p>The <em>body</em> value is special. This lets you specify a file that is the content for this page. Any content following the uservalues is ignored - and the specified file is used instead.</p>
<p>If that file has template tags that use the uservalues - then they will be substituted when the template is processed.</p>
<p>The file specified can be an absolute path, or a path relative to the page it is bein used in.</p>
<p>For example, say we have the following for our uservalues :</p>
<pre class="literal-block">
uservalues
body: ../templates/a_page.txt
greeting: <h1>Howdy</h1>
/uservalues
</pre>
<p><strong>rest2web</strong> will use the file <tt class="docutils literal"><span class="pre">../templates/a_page.txt</span></tt> as the body of this page. If it contains a tag that looks like <tt class="docutils literal"><span class="pre"><%</span> <span class="pre">greeting</span> <span class="pre">%></span></tt>, then it will be replaced with <tt class="docutils literal"><span class="pre"><h1>Howdy</h1></span></tt> when the template is processed.</p>
<div class="warning">
<p class="first admonition-title">Warning</p>
<p class="last">Using the <em>body</em> value you separate your content from your file containing the restindex/uservalues. You <strong>must</strong> store them with the <em>same</em> encoding.</p>
</div>
<div class="section" id="translations">
<h2><a class="toc-backref" href="#id14">Translations</a></h2>
<p>A good example of using the <em>body</em> value is for multiple translations of websites. A typical example is where you have several pages of content that you want to mirror in different languages. That is, you want the same pages, with the same structure, just key sections swapping over.</p>
<p>The <em>body</em> value lets you keep your page frameworks all in one place. The framework should use the uservalues - and then just have several directories of pages which point to the framework... but have the right values set for the uservalues.</p>
<p>There is an example in the example site - the <a class="reference external" href="../translation/index.html">translation</a> pages. See the <em>source</em> of these pages for a clear illustration how of how it works.</p>
<p>Now I'll attempt to explain it in words <img src="../images/smilies/razz.gif" alt="Razz" /> .</p>
<p>Suppose you want three translations for your site. You'll put the english files in a directory called <strong>en</strong>, the French ones in a directory called <strong>fr</strong>, and the German ones in a directory called <strong>de</strong>. The HTML framework of each page is going to be identical in each directory - it's just the viewable words that will be different.</p>
<p>To achieve this we add a fourth directory called templates. It's in here that we are going to put our HTML frameworks. Everywhere we want some text to appear we will put a uservalue placeholder instead.</p>
<p>We have our usual <em>template.txt</em> which contains the outline of the page. We'll create a file in the <tt class="docutils literal"><span class="pre">template</span></tt> directory called <tt class="docutils literal"><span class="pre">index_page.txt</span></tt> <a class="footnote-reference" href="#id5" id="id2">[2]</a>. It might look something like :</p>
<pre class="literal-block">
<div class="someClass">
<h1><% greeting %></h1>
</div>
<div class="para">
<p><% para1 %></p>
</div>
</pre>
<p>This page body has a placeholder for the headline and the paragraph.</p>
<p>In <em>index.txt</em> in your <tt class="docutils literal"><span class="pre">en</span></tt> folder you would then put :</p>
<pre class="literal-block">
restindex
format: html
crumb: English Index
page-title: English Index
/restindex
uservalues
body: ../templates/index_page.txt
greeting: Hello and Welcome
para1: """This is the body text,
with <em>some HTML</em> in it."""
/uservalues
</pre>
<p>When rendered, it fetches the <tt class="docutils literal"><span class="pre">index_page.txt</span></tt> as the body, and inserts the English values into it.</p>
<p>In <em>index.txt</em> in your <tt class="docutils literal"><span class="pre">fr</span></tt> folder you would then put :</p>
<pre class="literal-block">
restindex
format: html
crumb: French Index
page-title: French Index
/restindex
uservalues
body: ../templates/index_page.txt
greeting: Bonjour et Bienvenue
para1: """Du Francais ici,
avec <em>du HTML</em>."""
/uservalues
</pre>
<p>When rendered, this creates the French page.</p>
<p>You create your basic directory structure in the <tt class="docutils literal"><span class="pre">templates</span></tt> directory. You mirror this in your other directories; but your files are all basically identical and you only need to edit the uservalues.</p>
<p>With a little trickery in the body or the templates it ought to be simple to include links between pages in one language and the other ones.</p>
</div>
</div>
<div class="section" id="the-order-of-processing">
<h1><a class="toc-backref" href="#id15">The Order of Processing</a></h1>
<p>There are two ways of inserting values into pages using the template system.</p>
<p>The first way allows you to put <em>ReST</em> values into your pages before they are
turned into HTML. The second way puts html into your pages when the template is
processed.</p>
<p>If your pages are in HTML, then the difference doesn't matter.</p>
<p>If your page is in ReST format, then it allows you to have uservalues in ReST;
which then get rendered along with the rest of your page.</p>
<p>For the full details, see the <a class="reference external" href="../templating.html">templating system</a>.</p>
<p>It basically boils down to this, the following template tags will be resolved
<em>before</em> the ReST is processed :</p>
<blockquote>
<p><tt class="docutils literal"><span class="pre"><$</span> <span class="pre">...</span> <span class="pre">$></span></tt></p>
<p><tt class="docutils literal"><span class="pre"><*</span> <span class="pre">...</span> <span class="pre">*></span></tt></p>
</blockquote>
<p>and the following template tags will be resolved <em>after</em> the ReST is processed
(and so should contain html values) :</p>
<blockquote>
<p><tt class="docutils literal"><span class="pre"><#</span> <span class="pre">...</span> <span class="pre">#></span></tt></p>
<p><tt class="docutils literal"><span class="pre"><%</span> <span class="pre">...</span> <span class="pre">%></span></tt></p>
</blockquote>
<p>Don't forget that in order to put HTML tags inside a ReST document, you will
need to use the raw directive <a class="footnote-reference" href="#id6" id="id3">[3]</a> :</p>
<pre class="literal-block">
.. raw:: html
<# print '<strong>hello</strong>' #>
</pre>
</div>
<hr class="docutils" />
<div class="section" id="footnotes">
<h1><a class="toc-backref" href="#id16">Footnotes</a></h1>
<table class="docutils footnote" frame="void" id="id4" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>This footnote is just so that the words internationalization (i18n), and localization (l10n) appear somewhere on this page <img src="../images/smilies/smile.gif" alt="Smile" /> .</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id5" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id2">[2]</a></td><td>We won't call it <em>index.txt</em>, which is a <a class="reference external" href="../special_files.html">special file</a> in <strong>rest2web</strong>. The example site uses <em>_index.txt</em>.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id6" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id3">[3]</a></td><td><tt class="docutils literal"><span class="pre"><%</span> <span class="pre">value</span> <span class="pre">%></span></tt> will become <tt class="docutils literal"><span class="pre">&lt;%</span> <span class="pre">value</span> <span class="pre">%&gt;</span></tt>; which doesn't work <img src="../images/smilies/sad.gif" alt="Sad" /> . If you do need to do this (by the way) you could also use the raw role.</td></tr>
</tbody>
</table>
</div>
</div>
</div>
<div id="end">
<p><a href="#startcontent">Return to Top</a><br />
<small>Part of the <a href="http://www.voidspace.org.uk/python/rest2web/">rest2web Docs</a></small><br />
<small>Page last modified <strong>Thu Oct 12 22:24:09 2006</strong>.</small>
</p>
</div>
</div></td>
</tr>
<tr>
<td valign="top" align="left" width="25%">
<div id="left-column">
<div id="sidie">
<ul>
<li class="left-navheader-first">
<a href="index.html" class="left-navheader">Index Page</a>
</li>
<li class="left-navheader">Pages</li>
<li><a href="todo.html">TODO/ISSUES</a></li>
<li><a href="uservalues.html">uservalues</a></li>
<li><a href="encodings.html">Encodings</a></li>
<li><a href="indextree.html">indextree</a></li>
<li><a href="changelog.html">changelog</a></li>
<li><a href="smilies.html">Smilies</a></li>
<li><a href="plugins.html">Plugins</a></li>
<li><a href="gallery.html">Gallery</a></li>
</ul>
</div>
<p class="sidieimg">
<a href="http://www.python.org">
<img src="../images/logos/new_python.gif" width="88"
height="103" border="0" alt="Powered by Python" />
</a>
</p>
<p class="sidieimg">
<a href="http://sourceforge.net/donate/index.php?group_id=138579">
<img src="http://images.sourceforge.net/images/project-support.jpg" width="100"
height="32" border="0" alt="Support This Project" />
</a>
</p>
<p class="sidieimg">
<a href="http://www.voidspace.org.uk/python/rest2web/"><img
src="../images/logos/rest2web140x62.gif" width="142" height="62"
alt="Site Built with rest2web" /></a><br />
</p>
</div>
</td>
</tr>
</table>
<hr />
<p class="sidieimg">
<a href="http://www.voidspace.org.uk/python/rest2web/"><img src="../images/logos/rest2web200x80.gif" width="200" height="80" alt="Site Built with rest2web" /></a>
<a href="http://sourceforge.net"><img src="http://sourceforge.net/sflogo.php?group_id=138579&type=5" width="210" height="62" alt="SourceForge.net Logo" /></a>
<a href="http://www.opensource.org"><img src="../images/logos/osi-certified-120x100.gif" width="120" height="100" alt="Certified Open Source" border="1" /></a>
</p>
<p class="sidieimg">
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
_uacct = "UA-203625-1";
urchinTracker();
</script>
</p>
<p class="sidieimg">
<a href="http://www.voidspace.org.uk/python/index.shtml"><img
src="../images/logos/pythonbanner.gif" width="468" height="60"
alt="Python on Voidspace" /></a>
</p>
<div id="footer">
Copyright © Voidspace<br />Design by <a href="http://www.fuchsiashockz.co.uk">Fuchsiashockz</a> | <a href="http://validator.w3.org/check?uri=referer" title="Validate code as W3C XHTML 1.1 Strict Compliant">W3C XHTML 1.1</a> | <a href="http://jigsaw.w3.org/css-validator/check?uri=referer" title="Validate Style Sheet as W3C CSS 2.0 Compliant">W3C CSS 2.0</a>
</div>
</div>
</body>
</html>
|