Emacs doesn't recognize "utf8" as a valid coding system. The correct
name is "utf-8". This is in line with the UTF-8 FAQ:

  http://www.cl.cam.ac.uk/~mgk25/unicode.html#utf-8

  The official name and spelling of this encoding is UTF-8, where UTF
  stands for UCS Transformation Format. Please do not write UTF-8 in
  any documentation text in other ways (such as utf8 or UTF_8), unless
  of course you refer to a variable name and not the encoding itself.

Using "-*- encoding:utf-8 -*-" doesn't really set the file encoding
for Emacs. It will even prompt the user when opening a compiled file:

  The local variables list in foo.mak.py
  contains values that may not be safe (*).

  Do you want to apply it?  You can type
  y  -- to apply the local variables list.
  n  -- to ignore the local variables list.

  !  -- to apply the local variables list, and permanently mark these
        values (*) as safe (in the future, they will be set automatically.)

    * encoding: utf-8

The problem is that Emacs looks for a file variable named "coding" and
it doesn't know about "encoding":

  http://www.gnu.org/software/emacs/manual/html_node/emacs/Specify-Coding.html

This is no doubt why Python recognizes "coding:" by itself:

  http://www.python.org/dev/peps/pep-0263/

This change makes the code generator output "# -*- coding:%s -*-" and
updates the documentation and examples to match this style.

- other 2.4 ism

  method, as this method has a specific internal use. The purpose
  of Context.kwargs has been clarified, in that it only delivers
  top level keyword arguments originally passed to template.render().
  [ticket:219]

  interpreted correctly within a template tag.  [ticket:190]

  skips over module elements that are not explcitly callable,
  avoiding TypeError when trying to produce partials.
  [ticket:207]

- guess this is 0.9.0

- add more of a test

Without this change, when running setup.py extract_messages, we would get
error:

    TokenError: ('EOF in multi-line statement', (2, 0))

Looking at the unit test, it seems like a literal string argument in the form
of "_('xxx')" is supposed to be picked up by Babel. However, that contradicts
with the documentation, which states:

> When using tags, the values of the arguments are taken as literal strings by
> default. To embed Python expressions as arguments, use the embedded
> expression format

So, as a side effect of this commit, the convenience of "_('xxx')" has been
removed. Probably can add it back if necessary for backward compatibility.

  converted for py3k properly (added tests.)
  [ticket:214]

  file warnings when running the tests under
  various Pythons with warnings turned on.
  [ticket:213]

  against a module compiled to the filesystem would
  fail trying to produce a RichTraceback due to the
  content being in bytes. [ticket:209]

- fix test_exceptions to always call non-pygments tests
- update test for py3k transition

  TemplateLookup, allows alternate Lexer classes
  to be used.

having some weird unicode issues I can't debug; the meaning of
str.encode() seems to be changing globally somehow

Changed keyword argument from futures to future_imports for clarity.
Added docstring describing use.

Provide a list of names to import from __future__ to Template or
TemplateLookup, and it will render the import from __future__
statement at the top of the generated code so that it actually works.

  raise exception when non-existent plugin
  is specified.

  <%text> tag so that it pulls locally specified
  identifiers from the context the same
  way as that of <%block> and <%filter>.

  function arguments inside pure-python def
  or lambda expressions.  [ticket:201]

  involving variables declared in defs and such,
  which only became apparent when
  the strict_undefined flag was turned on.
  [ticket:192]

  same time args passed to def() are used
  by other elements of the <%def> tag.
  [ticket:191]

- add conditionals to pygments-dependent tests that ensure
pygments 1.4, separate check for no pygments.

  now succeed, as "pass" is added for these
  when no statements are otherwise present.
  Courtesy Ben Trofatter [ticket:146]

- fix up links, formatting in docs
- remove some repetition in the _compile logic