docs: Move template section from translating.md to html-templates.

Fixes #1649.

docs/architecture-overview.md

@@ -128,7 +128,8 @@ live-rendering HTML from JavaScript for things like the main message
 feed.
 
 For more details on the frontend, see our documentation on
-[templates and translation](translating.html),
+[translation](translating.html),
+[templates](html-templates.html),
 [directory structure](directory-structure.html), and
 [the static asset pipeline](front-end-build-process.html).
 

docs/directory-structure.md

@@ -41,7 +41,7 @@ paths will be familiar to Django developers.
 
 ### HTML Templates
 
-See [our translating docs](translating.html) for details on Zulip's
+See [our docs](html-templates.html) for details on Zulip's
 templating systems.
 
 * `templates/zerver/` For [Jinja2](http://jinja.pocoo.org/) templates

docs/html-templates.md

@@ -0,0 +1,91 @@
+# HTML templates
+
+### Behavior
+
+* Templates are automatically recompiled in development when the file
+is saved; a refresh of the page should be enough to display the latest
+version. You might need to do a hard refresh, as some browsers cache
+webpages.
+
+* Variables can be used in templates. The variables available to the
+template are called the **context**. Passing the context to the HTML
+template sets the values of those variables to the value they were
+given in the context. The sections below contain specifics on how the
+context is defined and where it can be found.
+
+## Backend
+
+For text generated in the backend, including logged-out ("portico")
+pages and the webapp's base content, we use the [Jinja2][] template
+engine (files in `templates/zerver`).
+
+The syntax for using conditionals and other common structures can be
+found [here][jconditionals].
+
+The context for Jinja2 templates is assembled from a few places:
+
+* `zulip_default_context` in `zerver/context_processors.py`.  This is
+the default context available to all Jinja2 templates.
+
+* As an argument in the `render` call in the relevant function that
+renders the template. For example, if you want to find the context
+passed to `index.html`, you can do:
+
+```
+$ git grep zerver/index.html '*.py'
+zerver/views/home.py:    response = render(request, 'zerver/index.html',
+```
+
+The next line in the code being the context definition.
+
+* `zproject/urls.py` for some fairly static pages that are rendered
+using `TemplateView`, for example:
+
+```
+url(r'^config-error/google$', TemplateView.as_view(
+    template_name='zerver/config_error.html',),
+    {'google_error': True},),
+```
+
+## Frontend
+
+For text generated in the frontend, live-rendering HTML from
+JavaScript for things like the main message feed, we use the
+[Handlebars][] template engine (files in `static/templates/`) and
+sometimes work directly from JavaScript code (though as a policy
+matter, we try to avoid generating HTML directly in JavaScript
+wherever possible).
+
+The syntax for using conditionals and other common structures can be
+found [here][hconditionals].
+
+There's no equivalent of `zulip_default_context` for the Handlebars
+templates.
+
+In order to find the context definition, you should grep without using
+the file extension. For example, to find where
+`invite_subscription.handlebars` is rendered, you should run something
+like this:
+
+```
+$ git grep "render('invite_subscription" 'static/js'
+frontend_tests/node_tests/templates.js:    var html = render('invite_subscription', args);
+static/js/invite.js:    $('#streams_to_add').html(templates.render('invite_subscription', {streams: streams}));
+```
+
+The second argument to `templates.render` is the context.
+
+### Translation
+
+All user-facing strings (excluding pages only visible to sysadmins or
+developers) should be tagged for [translation][].
+
+[Jinja2]: http://jinja.pocoo.org/
+[Handlebars]: http://handlebarsjs.com/
+[trans]: http://jinja.pocoo.org/docs/dev/templates/#i18n
+[i18next]: http://i18next.com
+[official]: http://i18next.com/translate/pluralSimple/
+[helpers]: http://handlebarsjs.com/block_helpers.html
+[jconditionals]: http://jinja.pocoo.org/docs/2.9/templates/#list-of-control-structures
+[hconditionals]: http://handlebarsjs.com/block_helpers.html
+[translation]: translating.html

docs/index.rst

@@ -147,6 +147,7 @@ Contents:
    email
    analytics
    translating
+   html-templates
    client
    logging
    release-checklist

docs/translating.md

@@ -205,12 +205,17 @@ resource files are located at
 
 These files are uploaded to [Transifex][], where they can be translated.
 
+## HTML Templates
+
+Zulip makes use of the [Jinja2][] templating system for the backend
+and [Handlebars][] for the frontend. Our [HTML templates][html-templates]
+documentation includes useful information on the syntax and
+behavior of these systems.
+
 ## Backend translations
 
-All user-facing text in the Zulip UI should be generated by an HTML
-template so that it can be translated.  For text generated in the
-backend, including logged-out ("portico") pages and the webapp's base
-content, we use the [Jinja2][] template engine.
+All user-facing text in the Zulip UI should be generated by an Jinja2 HTML
+template so that it can be translated.
 
 To mark a string for translation in a Jinja2 template, you
 can use the `_()` function in the templates like this:
@@ -258,11 +263,8 @@ Zulip linter (`tools/lint`) checks for correct usage.
 
 ## Frontend translations
 
-For text generated in the frontend, live-rendering HTML from
-JavaScript for things like the main message feed, we use the
-[Handlebars][] template engine and sometimes work directly from
-JavaScript code.  In both cases, we use the [i18next][] library
-for translations.
+We use the [i18next][] library for frontend translations when dealing
+with [Handlebars][] templates or JavaScript.
 
 To mark a string translatable in JavaScript files, pass it to the
 `i18n.t` function.
@@ -355,7 +357,6 @@ The rules for plurals are same as for JavaScript files. You just have
 to declare the appropriate keys in the resource file and then include
 the `count` in the context.
 
-
 ## Transifex config
 
 The config file that maps the resources from Zulip to Transifex is
@@ -392,3 +393,4 @@ organizations from the command line.
 [resource]: http://i18next.com/translate/
 [Transifex]: https://transifex.com
 [transifexrc]: https://docs.transifex.com/client/client-configuration#transifexrc
+[html-templates]: html-templates.html