Noissue - Improve CMS usage documentation

README.md

 # CMS #
 
 We use this CMS for [adblockplus.org](https://github.com/adblockplus/web.adblockplus.org/)
 and related websites. It converts a directory with content data into static
 files. You are free to use it for other projects but please keep in mind that we
 make no stability guarantees whatsoever and might change functionality any time.
 
 ## How to use ##
 
 ### Running the test server ###
@@ skipping 247 matching lines @@
 
 * `page`: The page name
 * `config`: Contents of the `settings.ini` file in this repository (a
   [configparser object](http://docs.python.org/2/library/configparser.html))
 * `locale`: Locale code of the page language
 * `available_locales`: Locale codes of all languages available for this page
 
 Following custom filters can be used:
 
 * `translate(default, name, comment=None)`: translates the given default string
-   for the given page name into the current language. Optionally a comment or
-   description can be specified as well.

[Wladimir Palant, 2015/09/03 13:37:37]

What's the difference between comment and description? As above, it should be
explicitly noted that a comment is only something for translators. And maybe you
should just call it "comment" everywhere (also in the Markdown section above)?

[kzar, 2015/09/03 14:04:14]

Well we seem to use both "comment" and "description" in different places. For
example the JSON structure (that we're stuck with) uses "description" and for
the parameter here we use "comment". I thought it would be nice to clarify here
that they're one in the same. I've adjusted the wording again, what do you
think?

+   and string name for the current page and locale. The string name should be
+   unique for the page but otherwise is only seen by the translators. Optionally
+   a comment (description) can be specified to help provide the translators with
+   additional context.
 * `linkify(url)`: generates an `<a href="...">` tag for the URL. If the URL is
   a page name it will be converted into a link to the most appropriate page
   language.
 * `toclist(html)`: extracts a list of headings from HTML code, this can be used
   to generate a table of contents.
 
 The following global functions can be used:
 
 * `get_string(name, page=None)`: retrieves a string from a locale file.
   Unless a page is specified the locale file matching the name of the current
   page is used.
 * `get_page_content(page, locale=None)`: returns a dictionary of the content
   and params for the given page and locale. Locale defaults to the current one
-  if not specified. Provided keys include:
-
-```
-['head', 'body', 'available_locales', 'translation_ratio']
-```

[Wladimir Palant, 2015/09/03 13:37:37]

Why have this as a Python list? "Provided keys include: `head`, `body`,
`available_locales`, `translation_ratio`."

[kzar, 2015/09/03 14:04:14]

Done.

+  if not specified. Provided keys include `head`, `body`, `available_locales`
+  and `translation_ratio`.
 
 ### Static files ###
 
 Any files located in the `static` directory will be available on the server
 unchanged. The file `static/css/foo.css` will be available under the URL
 `/css/foo.css`.
 
 ### Templates ###
 
 The templates specified in the `templates` directory specify the overall
@@ skipping 17 matching lines @@
 filter is invoked. For more information on Jinja2 filters see
 [official documentation](http://jinja.pocoo.org/docs/dev/api/#writing-filters).
 
 ### Custom functions and variables ###
 
 The `globals` directory can define custom Jinja2 globals which will be available
 in all Jinja2 templates. Typically, this is used for custom functions. The file
 name should match the name of the function or variable to be defined, and export
 a variable with that name. E.g. `globals/myfunction.py` can define a function
 called `myfunction` that will become available to all Jinja2 templates.