From: Georg Brandl Date: Mon, 12 Mar 2007 20:49:50 +0000 (+0100) Subject: [svn] Proofread the rest of the docs. X-Git-Tag: 2.0rc1~444 X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=2d53a8657f1c845d712dc6f32f224eb5272bd73d;p=jinja2.git [svn] Proofread the rest of the docs. --HG-- branch : trunk --- diff --git a/docs/src/devintro.txt b/docs/src/devintro.txt index 157301c..74d6dd0 100644 --- a/docs/src/devintro.txt +++ b/docs/src/devintro.txt @@ -2,7 +2,7 @@ Developer Quickstart ==================== -This part of the documentation shows you how to embedd Jinja into your +This part of the documentation shows you how to embed Jinja into your application. Starting Up @@ -21,52 +21,52 @@ This example should output the following string after execution:: Hello John Doe! -If you receive an error check if you have a typo in your code. If not have +If you receive an error, check if you have a typo in your code. If not, have a look at the `installation`_ page for troubleshooting. The Environment =============== -The core component of Jinja is the `Environment`. It helds important shared +The core component of Jinja is the `Environment`. It contains important shared variables like configuration, filters, tests, globals and other stuff. -Here the possible initialisation parameters: - -=========================== ================================================== -``block_start_string`` * the string marking the begin of a block. this - defaults to ``'{%'``. -``block_end_string`` * the string marking the end of a block. defaults - to ``'%}'``. -``variable_start_string`` * the string marking the begin of a print - statement. defaults to ``'{{'``. -``comment_start_string`` * the string marking the begin of a - comment. defaults to ``'{#'``. -``comment_end_string`` * the string marking the end of a comment. - defaults to ``'#}'``. -``trim_blocks`` * If this is set to ``True`` the first newline - after a block is removed (block, not - variable tag!). Defaults to ``False``. -``auto_escape`` If this is set to ``True`` Jinja will - automatically escape all variables using xml - escaping methods. If you don't want to escape a - string you have to wrap it in a ``Markup`` - object from the ``jinja.datastructure`` module. -``template_charset`` The charset of the templates. Defaults - to ``'utf-8'``. -``charset`` Charset of all string input data. Defaults - to ``'utf-8'``. -``namespace`` Global namespace for all templates. -``loader`` Specify a template loader. -``filters`` dict of filters or the default filters if not - defined. -``tests`` dict of tests of the default tests if not defined. -=========================== ================================================== - -All of this variables except those marked with a star(*) are modifyable after -environment initialisation. - -The environment provides the following useful functions and properties -additional to the initialisation values: +Here the possible initialization parameters: + +========================= ================================================== +`block_start_string` * the string marking the begin of a block. this + defaults to ``'{%'``. +`block_end_string` * the string marking the end of a block. defaults + to ``'%}'``. +`variable_start_string` * the string marking the begin of a print + statement. defaults to ``'{{'``. +`comment_start_string` * the string marking the begin of a + comment. defaults to ``'{#'``. +`comment_end_string` * the string marking the end of a comment. + defaults to ``'#}'``. +`trim_blocks` * If this is set to ``True`` the first newline + after a block is removed (block, not + variable tag!). Defaults to ``False``. +`auto_escape` If this is set to ``True`` Jinja will + automatically escape all variables using xml + escaping methods. If you don't want to escape a + string you have to wrap it in a ``Markup`` + object from the ``jinja.datastructure`` module. +`template_charset` The charset of the templates. Defaults + to ``'utf-8'``. +`charset` Charset of all string input data. Defaults + to ``'utf-8'``. +`namespace` Global namespace for all templates. +`loader` Specify a template loader. +`filters` dict of filters or the default filters if not + defined. +`tests` dict of tests of the default tests if not defined. +========================= ================================================== + +All of these variables except those marked with a star (*) are modifiable after +environment initialization. + +The environment provides the following useful functions and properties in +addition to the initialization values: =========================== ================================================== ``parse(source, filename)`` Parse the sourcecode and return the abstract @@ -74,11 +74,11 @@ additional to the initialisation values: `translators`_ to convert the template into executable source- or bytecode. ``from_string(source)`` Load and parse a template source and translate it - into evaluable python code. This code is wrapped - with in a `Template` class that allows you to + into eval-able Python code. This code is wrapped + within a `Template` class that allows you to render it. -``get_template(name)`` load a template from a loader. If the template - does not exist you will get a `TemplateNotFound` +``get_template(name)`` Load a template from a loader. If the template + does not exist, you will get a `TemplateNotFound` exception. =========================== ================================================== @@ -108,7 +108,7 @@ loaders or how to write your own, head over to the `loader`_ documentation. Adding Filters ============== -If you want to add additional filters to the environment the best way is to +If you want to add additional filters to the environment, the best way is to modify the ``filters`` attribute and not to pass a dict to the environment. If you pass it a dict it will not include the default filters! @@ -122,7 +122,7 @@ Writing filter functions is explained in the `filter development`_ section. Adding Tests ============ -Adding additional tests works analog to filters: +Adding additional tests works analogous to filters: .. sourcecode:: python diff --git a/docs/src/filters.txt b/docs/src/filters.txt index 9bd3497..fd07e28 100644 --- a/docs/src/filters.txt +++ b/docs/src/filters.txt @@ -12,8 +12,8 @@ Jinja comes with some builtin filters explained in the `designer documentation`_ Writing Filters =============== -A filter basically is a factory function. Thus a function that returns another -function. We do this because filters can get an unlimited amount of position +A filter basically is a factory function, a function that returns another +function. We do this because filters can get an unlimited amount of positional arguments and aditionally should gain access to the environment, context and piped value. A simple filter looks like this: @@ -33,13 +33,13 @@ Now you have to register that filter on an environment: env.filters['join'] = do_join -In fact this filter is already bundled so you won't see any effect. But its +In fact this filter is already bundled so you won't see any effect. But it should explain how such a filter looks like. The template designer can just -trigger the outer code (eg: call do_join with or without arguments). The +trigger the outer code (i.e. call `join` with or without arguments). The returned function is then processed by the jinja template engine once all filters are created. -If you want to create filters that just operate on string (in fact unicode +If you want to create filters that just operate on a string (in fact unicode objects) you can use the `stringfilter` decorator: .. sourcecode:: python diff --git a/docs/src/frameworks.txt b/docs/src/frameworks.txt index 7a389b2..d0d3af9 100644 --- a/docs/src/frameworks.txt +++ b/docs/src/frameworks.txt @@ -4,7 +4,7 @@ Framework Integration Jinja registers itself in the baker template plugin system. If your framework supports baker (currently `TurboGears`_ and `pylons`_) you can add it very -easy. +easily. Pylons ------ diff --git a/docs/src/fromdjango.txt b/docs/src/fromdjango.txt index 71b2068..23d0b78 100644 --- a/docs/src/fromdjango.txt +++ b/docs/src/fromdjango.txt @@ -2,17 +2,17 @@ Differences To Django Templates =============================== -If you have previously worked with Django templates you should feel very -familiar. In fact most of the syntax elements look and work the same. +If you have previously worked with Django templates, you should find Jinja very +familiar. In fact, most of the syntax elements look and work the same. -However Jinja provides some more syntax elements covered in the documentation +However, Jinja provides some more syntax elements covered in the documentation and some work a bit different. Method Calls ============ -In Django method calls work implicit. With Jinja you have to tell it that you -want to call it. Thus this Django code: +In Django method calls work implicitly. With Jinja you have to specify that you +want to call an object. Thus this Django code: .. sourcecode:: django @@ -72,7 +72,7 @@ You can also have multiple ``elif`` branches in your template: Filter Arguments ================ -Jinja provides more than one argument for a filter. Also the syntax for argument +Jinja provides more than one argument for filters. Also the syntax for argument passing is different. A template that looks like this in Django: .. sourcecode:: django @@ -85,14 +85,14 @@ looks like this in jinja: {{ items|join(', ') }} -In fact it's a bit more to write but it allows different type of arguments including -variables and more then one of them. +In fact it's a bit more verbose but it allows different types of arguments - including +variables - and more than one of them. Tests ===== -Additionally to filters there also exists tests you can perform using the `is` -operator. Here some examples: +In addition to filters there also are tests you can perform using the `is` operator. +Here are some examples: .. sourcecode:: jinja diff --git a/docs/src/loaders.txt b/docs/src/loaders.txt index e733a03..42359dd 100644 --- a/docs/src/loaders.txt +++ b/docs/src/loaders.txt @@ -12,9 +12,9 @@ Builtin Loaders Developing Loaders ================== -Template loaders are just normal python classes that have to provide some -functions used to load and translate templates. Here a simple loader implementation -you can use as base for your own loader: +Template loaders are just normal Python classes that have to provide some +functions used to load and translate templates. Here is a simple loader implementation +you can use as the base for your own loader: .. sourcecode:: python @@ -32,7 +32,7 @@ you can use as base for your own loader: def get_source(self, environment, name, parent): """ - The get_source function is unused at the moment. However future + The get_source function is unused at the moment. However, future versions of jinja will use this function for the debugging system. It also works as helper functions for `parse` and `load`. @@ -56,7 +56,7 @@ you can use as base for your own loader: def load(self, environment, name, translator): """ Parse and translate a template. Currently only translation to - python code is possible, later jinja versions however will + python code is possible, later Jinja versions however will support translating templates to javascript too. """ return translator.process(environment, self.parse(environment, name, None)) @@ -64,5 +64,5 @@ you can use as base for your own loader: .. admonition:: Note - Once a loader is bound to an environment you have to omit the environment + Once a loader is bound to an environment, you have to omit the environment argument for the public functions `get_source`, `parse` and `load`. diff --git a/docs/src/tests.txt b/docs/src/tests.txt index 2eb5578..e2231d6 100644 --- a/docs/src/tests.txt +++ b/docs/src/tests.txt @@ -2,7 +2,7 @@ Test Functions ============== -Additionally to filters Jinja also supports test functions. Test functions +In addition to filters, Jinja also supports test functions. Test functions always return either ``True`` or ``False``. Inside the template they are available using the `is` operator. diff --git a/docs/src/translators.txt b/docs/src/translators.txt index 9bebb03..2522152 100644 --- a/docs/src/translators.txt +++ b/docs/src/translators.txt @@ -5,6 +5,6 @@ Translators Jinja translates the template sourcecode into executable python code behind the secenes. This is done by the python translator which is currently the only shipped translator. Because the interface isn't stable it's also not -recommended to write other translators. However for the next Jinja version +recommended yet to write other translators. However for the next Jinja version a JavaScript translator is planned which allows you to translate Jinja templates into executable JavaScript code.