rest2web-doc 0.5.2~alpha+svn-r248-2 / usr / share / doc / rest2web / html / reference / encodings.html

This file is indexed.

/usr/share/doc/rest2web/html/reference/encodings.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
<!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>Text Encodings</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="&copy; 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>&gt;</li>
<li><a href="index.html">Reference</a></li>
<li>&gt;</li>
<li>Encodings</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="text-encodings">
<h1 class="title">Text Encodings</h1>
<h2 class="subtitle" id="encodings-with-rest2web">Encodings with rest2web</h2>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#fun-with-encodings" id="id12">Fun With Encodings</a></li>
<li><a class="reference internal" href="#summary" id="id13">Summary</a></li>
<li><a class="reference internal" href="#input-encodings" id="id14">Input Encodings</a></li>
<li><a class="reference internal" href="#template-encodings" id="id15">Template Encodings</a></li>
<li><a class="reference internal" href="#output-encodings" id="id16">Output Encodings</a></li>
<li><a class="reference internal" href="#encodings-and-the-templating-system" id="id17">Encodings and the Templating System</a></li>
<li><a class="reference internal" href="#problem" id="id18">Problem</a></li>
<li><a class="reference internal" href="#footnotes" id="id19">Footnotes</a></li>
</ul>
</div>
<div class="section" id="fun-with-encodings">
<h1><a class="toc-backref" href="#id12">Fun With Encodings</a></h1>
<p><img src="../images/dove.gif" alt="emoticon:dove" /> <strong>rest2web</strong> handles text encodings in ways that are hopefully sensible and simple.</p>
<p>Whenever you are dealing with text you <strong>should</strong> <em>know and specify the encoding used</em> <a class="footnote-reference" href="#id6" id="id1">[1]</a>. If you disagree with me (or haven't a clue what I'm on about), read <a class="reference external" href="http://www.joelonsoftware.com/articles/Unicode.html">The Minimum Every Developer Must Know About Unicode</a>, by Joel Spolsky.</p>
<p><strong>rest2web</strong> allows you to specify what encodings your content is (source files) and what encoding to write the output as. In order to achieve this, <strong>rest2web</strong> is almost entirely <tt class="docutils literal"><span class="pre">Unicode</span></tt> internally.</p>
<p>If all of this is gobbledygook, then don't worry <strong>rest2web</strong> will guess what encoding your files are, and write them out using the same encoding. If you're not 'encoding aware', this is usually going to be what you want.</p>
</div>
<div class="section" id="summary">
<h1><a class="toc-backref" href="#id13">Summary</a></h1>
<p>In a nutshell you use <strong>'encoding'</strong> to specify the encoding of a contents, file <strong>'template-encoding'</strong> to specify the encoding of your templates, and <strong>'output-encoding'</strong> to specify the encoding the file should be saved with. 'output-encoding' used in an 'index file' sets the output encoding for all the files in that directory and below.</p>
</div>
<div class="section" id="input-encodings">
<h1><a class="toc-backref" href="#id14">Input Encodings</a></h1>
<p>As usual, the way we handle encodings is through the <a class="reference external" href="../restindex.html">restindex</a>.</p>
<p>The first thing we can specify is the encoding of a page of content. We do this with the <tt class="docutils literal"><span class="pre">encoding</span></tt> keyword. If this keyword is set for a file <a class="footnote-reference" href="#id7" id="id2">[2]</a>, it is used to read and decode the file. If no encoding is specified, <strong>rest2web</strong> will attempt to guess the encoding. It tries a few standard encodings <em>and</em> retrieves information from the <em>locale</em> <a class="footnote-reference" href="#id8" id="id3">[3]</a> about the standard encoding for the system. If the page is successfully decoded then it stores the encoding used <a class="footnote-reference" href="#id9" id="id4">[4]</a>, otherwise an error is raised.</p>
<p>From this point on the page content is stores as Unicode inside <strong>rest2web</strong>.</p>
<p>Whichever encoding was used to decode the page, it is available as the variable <tt class="docutils literal"><span class="pre">encoding</span></tt> inside the templates.</p>
</div>
<div class="section" id="template-encodings">
<h1><a class="toc-backref" href="#id15">Template Encodings</a></h1>
<p>In the restindex you can also specify the encoding of the template file. This is the value <tt class="docutils literal"><span class="pre">template-encoding</span></tt>. It is only used if you are also specifying a template file. If you specify a template file without specifying an encoding, our friend <tt class="docutils literal"><span class="pre">guess_encoding</span></tt> will be used to work out what it is.</p>
<p>This value is available as the variable <tt class="docutils literal"><span class="pre">template_encoding</span></tt>.</p>
</div>
<div class="section" id="output-encodings">
<h1><a class="toc-backref" href="#id16">Output Encodings</a></h1>
<p>When the page is rendered you can specify what encoding should be used. This is done with the <tt class="docutils literal"><span class="pre">output-encoding</span></tt> keyword. If you specify an 'output-encoding' in an 'index file' then that encoding will be used for all the files in that directory, and any sub-directories. That means you can specify it once, in your top level index file, and have it apply to the whole site.</p>
<p>The encoding you specify applies to <em>all values passed to the template</em>. This means the variables <tt class="docutils literal"><span class="pre">body</span></tt>, <tt class="docutils literal"><span class="pre">title</span></tt>, <tt class="docutils literal"><span class="pre">crumb</span></tt>, <tt class="docutils literal"><span class="pre">sectionlist</span></tt>, etc.</p>
<p>As well as the standard Python encodings, there are a couple of special values that <tt class="docutils literal"><span class="pre">output-encoding</span></tt> can have. These are <tt class="docutils literal"><span class="pre">Unicode</span></tt> and <tt class="docutils literal"><span class="pre">none</span></tt>.</p>
<p>If you specify a value of <strong>none</strong> for 'output-encoding', then all string are re-encoded using the original encoding.</p>
<p>If you specify a value of <strong>Unicode</strong> for 'output-encoding' then strings are <em>not encoded</em>, but are passed to the template as Unicode strings. Your template will also be decoded to Unicode. The output will be re-encoded using the 'template-encoding', but will be processed in the template as Unicode.</p>
<p>The value for 'output-encoding' is available in your template as the variable <tt class="docutils literal"><span class="pre">output_encoding</span></tt>. Because of the special values of 'output-encdoing' there is an additional variable called <tt class="docutils literal"><span class="pre">final_encoding</span></tt>. <tt class="docutils literal"><span class="pre">final_encoding</span></tt> contains the actual encoding used to encode the strings. If the value of <tt class="docutils literal"><span class="pre">output_encoding</span></tt> was <strong>none</strong>, then it will contain the original encoding. If the value of <tt class="docutils literal"><span class="pre">output_encoding</span></tt> was <strong>unicode</strong>, then it will contain the <tt class="docutils literal"><span class="pre">None</span></tt> object.</p>
</div>
<div class="section" id="encodings-and-the-templating-system">
<h1><a class="toc-backref" href="#id17">Encodings and the Templating System</a></h1>
<p>The templating system makes several variables available to you to use. These include <tt class="docutils literal"><span class="pre">indextree</span></tt>, <tt class="docutils literal"><span class="pre">thispage</span></tt>, and <tt class="docutils literal"><span class="pre">sections</span></tt>. These contain information about the current page - and other pages as well. The information contained in these data structures allows you to create simple or complex navigation aids for your website.</p>
<p>See the <a class="reference external" href="../templating.html">templating</a> page for the details of how these data structures are constructed.</p>
<p>Because these values contain information taken from other pages you can't be certain of their <em>original encoding</em>. This isn't a problem though, rest2web will convert these appropriately to the <tt class="docutils literal"><span class="pre">final_encoding</span></tt> of the current page. (It also converts all target URLs to be relative to the current page).</p>
<p>The slight exception to this is part of the <tt class="docutils literal"><span class="pre">sections</span></tt> value. This value is a dictionary containing all the pages in the current directory, divided into sections. Each section has information about the section, as well as a list of pages in the section. Each page is itself a dictionary with various members containing information about the page.</p>
<p>One of these members is <tt class="docutils literal"><span class="pre">namespace</span></tt>, which is the namespace the page will be rendered in. This means that the values in the namespace are encoding with the appropriate encoding for <em>that</em> page. You can always tell what encoding that is by looking at <tt class="docutils literal"><span class="pre">final_encoding</span></tt> in the namespace. To be fair you're unlikely to dig that far into <tt class="docutils literal"><span class="pre">sections</span></tt> from the template - but I thought you ought to know  <img src="../images/smilies/rolleyes.gif" alt="Rolling Eyes" /> </p>
</div>
<div class="section" id="problem">
<h1><a class="toc-backref" href="#id18">Problem</a></h1>
<p>Note the following <a class="reference external" href="todo.html#ISSUES">problem</a>.</p>
<ul class="simple">
<li>Unfortunately, the <tt class="docutils literal"><span class="pre">guess_encoding</span></tt> function can recognise <tt class="docutils literal"><span class="pre">cp1252</span></tt> <a class="footnote-reference" href="#id10" id="id5">[5]</a> as <tt class="docutils literal"><span class="pre">ISO-8859</span></tt>. In this case docutils can choke on some of the characters. We probably have to special case the <tt class="docutils literal"><span class="pre">cp1252</span></tt> and <tt class="docutils literal"><span class="pre">ISO-8859</span></tt> encodings - but I wonder if this problem applies to other encodings ?</li>
</ul>
</div>
<hr class="docutils" />
<div class="section" id="footnotes">
<h1><a class="toc-backref" href="#id19">Footnotes</a></h1>
<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="#id1">[1]</a></td><td>The bottom line being, that if you don't know what encoding is used - you don't have text, you have random binary data.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id7" 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>It must be an encoding that Python recognises. See the Python <a class="reference external" href="http://docs.python.org/lib/standard-encodings.html">Standard Encodings</a></td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id8" 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>See the python <a class="reference external" href="http://docs.python.org/lib/module-locale.html">Locale module</a> documentation.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id9" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id4">[4]</a></td><td>The only exception is if the page successfully decodes using the <tt class="docutils literal"><span class="pre">ascii</span></tt> codec. In this case we store <tt class="docutils literal"><span class="pre">ISO8859-1</span></tt> as the encoding. This is a more flexible ascii compatible encoding.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id10" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id5">[5]</a></td><td>The standard windows encoding.</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>Mon Apr  3 19:30:38 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&amp;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 &copy; 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>

APT Browse - Built by Thomas Orozco.