README.md - Issue 29325800: Noissue - Improve CMS usage documentation

Delta Between Two Patch Sets: README.md

Issue 29325800: Noissue - Improve CMS usage documentation (Closed)

Left Patch Set: Created Sept. 3, 2015, 11:54 a.m.

Right Patch Set: Addressed further feedback Created Sept. 3, 2015, 2:01 p.m.

Left:
Right:

Use n/p to move between diff chunks; N/P to move between comments.

Jump to:

Left: Side by side diff | Download
Right: Side by side diff | Download

LEFT	RIGHT
1 # CMS #	1 # CMS #

2	2

3 We use this CMS for [adblockplus.org](https://github.com/adblockplus/web.adblock plus.org/)	3 We use this CMS for [adblockplus.org](https://github.com/adblockplus/web.adblock plus.org/)

4 and related websites. It converts a directory with content data into static	4 and related websites. It converts a directory with content data into static

5 files. You are free to use it for other projects but please keep in mind that we	5 files. You are free to use it for other projects but please keep in mind that we

6 make no stability guarantees whatsoever and might change functionality any time.	6 make no stability guarantees whatsoever and might change functionality any time.

7	7

8 ## How to use ##	8 ## How to use ##

9	9

10 ### Running the test server ###	10 ### Running the test server ###

(...skipping 183 matching lines...) Expand 10 before \| Expand all \| Expand 10 after Loading...
194	194

195 The following tag inserts an include file into the page (can be in a different	195 The following tag inserts an include file into the page (can be in a different

196 format):	196 format):

197	197

198 <? include foo ?>	198 <? include foo ?>

199	199

200 Include files should be placed into the `includes` directory of the repository.	200 Include files should be placed into the `includes` directory of the repository.

201 In the case above the contents of `includes/foo.md` or `includes/foo.tmpl` will	201 In the case above the contents of `includes/foo.md` or `includes/foo.tmpl` will

202 be inserted (whichever is present).	202 be inserted (whichever is present).

203	203

204 When writing content that needs to be translated into the different supported

205 languages you can use the following syntax:

206

207 {{string_name String contents in default language}}

208

209 Try to give the string a descriptive name as it will help translators.

210 Optionally you can add a description for strings as well to provide even more

211 context:

212

213 {{string_name[The string description] String contents}}
Wladimir Palant 2015/09/03 12:15:26 You need to point out explicitly that neither the You need to point out explicitly that neither the string name nor description have any effect on the generated markup - they are merely context information visible to translators. kzar 2015/09/03 13:05:33 Done. Show quoted text On 2015/09/03 12:15:26, Wladimir Palant wrote: > You need to point out explicitly that neither the string name nor description > have any effect on the generated markup - they are merely context information > visible to translators. Done.
214

215 Finally if you find yourself using the same string multiple times in a page

216 you can reduce duplication by simply omitting the description and contents

217 after the first use. For example:

218

219 {{title[Title of the page] Adblock Plus - Home}}

220 {{title}}

221

222 _Note: For Jinja2 templates this syntax does not work, you will need to use the

223 custom Jinja2 filters and global functions as documented below._
Wladimir Palant 2015/09/03 12:15:26 This section belongs under "Markdown format" - tha This section belongs under "Markdown format" - that's how Markdown files are being localized. You can add a note under "Raw html" saying that the localization approach there is identical to Markdown (it sort of says so already). kzar 2015/09/03 13:05:33 Done. Show quoted text On 2015/09/03 12:15:26, Wladimir Palant wrote: > This section belongs under "Markdown format" - that's how Markdown files are > being localized. You can add a note under "Raw html" saying that the > localization approach there is identical to Markdown (it sort of says so > already). Done.
224

225 #### Markdown format (md) ####	204 #### Markdown format (md) ####

226	205

227 This format should normally be used, it allows the pages to be defined using the	206 This format should normally be used, it allows the pages to be defined using the

228 [Markdown](http://daringfireball.net/projects/markdown/syntax) syntax. Raw HTML	207 [Markdown](http://daringfireball.net/projects/markdown/syntax) syntax. Raw HTML

229 tags are allowed and can be used where Markdown syntax isn't sufficient. The	208 tags are allowed and can be used where Markdown syntax isn't sufficient. The

230 [Attribute Lists](http://pythonhosted.org/Markdown/extensions/attr_list.html)	209 [Attribute Lists](http://pythonhosted.org/Markdown/extensions/attr_list.html)

231 extension is active and allows specifying custom attributes for the generated	210 extension is active and allows specifying custom attributes for the generated

232 HTML tags.	211 HTML tags.

233	212

234 Localizable strings are retrieved from the locale file with the name matching

235 the page name. The following syntax can be used: `$foo$` inserts a string named

236 `foo` from the locale (no HTML code or Markdown syntax allowed in the string).

237 The syntax `$foo(foopage, http://example.com/)$` will work similarly but will

238 look for `<a>...</a>` blocks in the string: the first will be turned into a link

239 to the page `foopage`, the second will become a link to `http://example.com/`.
Wladimir Palant 2015/09/03 12:15:26 This section is outdated and needs to be merged wi This section is outdated and needs to be merged with the text above. kzar 2015/09/03 13:05:33 Done. Show quoted text On 2015/09/03 12:15:26, Wladimir Palant wrote: > This section is outdated and needs to be merged with the text above. Done.
240

241 Any content between `<head>` and `</head>` tags will be inserted into the head	213 Any content between `<head>` and `</head>` tags will be inserted into the head

242 of the generated web page, this is meant for styles, scripts and the like.	214 of the generated web page, this is meant for styles, scripts and the like.

243 Other pages should be linked by using their name as link target (relative links) ,	215 Other pages should be linked by using their name as link target (relative links) ,

244 these links will be resolved to point to the most appropriate page language.	216 these links will be resolved to point to the most appropriate page language.

245 Embedding localizable images works the same, use the image name as image source.	217 Embedding localizable images works the same, use the image name as image source.

246	218

	219 Localizable strings can be specified inline with the following syntax:

	220

	221 {{string_name String contents in default language}}

	222

	223 Try to give the string a descriptive name as it will help translators.

	224 Optionally you can add a description for strings as well to provide even more

	225 context:

	226

	227 {{string_name[The string description] String contents}}

	228

	229 _Note: String names and descriptions have no effect on the generated page,

	230 assuming string name is unique to the page. The name and description are just

	231 used to provide translators with additional context about the string._

	232

	233 Finally if you find yourself using the same string multiple times in a page

	234 you can reduce duplication by simply omitting the description and contents

	235 after the first use. For example:

	236

	237 {{title[Title of the page] Adblock Plus - Home}}

	238 {{title}}

	239

247 #### Raw HTML format (html) ####	240 #### Raw HTML format (html) ####

248	241

249 This format is similar to the Markdown format but uses regular HTML syntax.	242 This format is similar to the Markdown format but uses regular HTML syntax.

250 No processing is performed beyond inserting localized strings and resolving	243 No processing is performed beyond inserting localized strings and resolving

251 links to pages and images. This format is mainly meant for legacy content.	244 links to pages and images. This format is mainly meant for legacy content.

	245 The syntax for localizable strings documented above can be used as with

	246 Markdown.

252	247

253 #### Jinja2 format (tmpl) ####	248 #### Jinja2 format (tmpl) ####

254	249

255 Complicated pages can be defined using the	250 Complicated pages can be defined using the

256 [Jinja2 template format](http://jinja.pocoo.org/docs/templates/). Automatic	251 [Jinja2 template format](http://jinja.pocoo.org/docs/templates/). Automatic

257 escaping is active so by default values inserted into the page cannot contain	252 escaping is active so by default values inserted into the page cannot contain

258 any HTML code. Any content between `<head>` and `</head>` tags will be inserted	253 any HTML code. Any content between `<head>` and `</head>` tags will be inserted

259 into the head of the generated web page, everything else defined the content of	254 into the head of the generated web page, everything else defined the content of

260 the page.	255 the page.

261	256

262 The following variables can be used:	257 The following variables can be used:

263	258

264 * `page`: The page name	259 * `page`: The page name

265 * `config`: Contents of the `settings.ini` file in this repository (a	260 * `config`: Contents of the `settings.ini` file in this repository (a

266 [configparser object](http://docs.python.org/2/library/configparser.html))	261 [configparser object](http://docs.python.org/2/library/configparser.html))

267 * `locale`: Locale code of the page language	262 * `locale`: Locale code of the page language

268 * `available_locales`: Locale codes of all languages available for this page	263 * `available_locales`: Locale codes of all languages available for this page

269	264

270 Following custom filters can be used:	265 Following custom filters can be used:

271	266

272 * `translate(string, name, comment=None)`: retrieves a string from a locale file	267 * `translate(default, name, comment=None)`: translates the given default string

273 for the given page name in the current language. Optionally a comment or	268 and string name for the current page and locale. The string name should be

274 description can be specified as well.	269 unique for the page but otherwise is only seen by the translators. Optionally
Wladimir Palant 2015/09/03 12:15:26 First parameter isn't string any more, it's defaul First parameter isn't string any more, it's default - you should point out what it means. kzar 2015/09/03 13:05:33 Done. Show quoted text On 2015/09/03 12:15:26, Wladimir Palant wrote: > First parameter isn't string any more, it's default - you should point out what > it means. Done.
	270 a comment (description) can be specified to help provide the translators with

	271 additional context.

275 * `linkify(url)`: generates an `<a href="...">` tag for the URL. If the URL is	272 * `linkify(url)`: generates an `<a href="...">` tag for the URL. If the URL is

276 a page name it will be converted into a link to the most appropriate page	273 a page name it will be converted into a link to the most appropriate page

277 language.	274 language.

278 * `toclist(html)`: extracts a list of headings from HTML code, this can be used	275 * `toclist(html)`: extracts a list of headings from HTML code, this can be used

279 to generate a table of contents.	276 to generate a table of contents.

280	277

281 The following global functions can be used:	278 The following global functions can be used:

282	279

283 * `get_string(name, page=None)`: retrieves a string from a locale file.	280 * `get_string(name, page=None)`: retrieves a string from a locale file.

284 Unless a locale is specified the locale file matching the page name is used.	281 Unless a page is specified the locale file matching the name of the current
Wladimir Palant 2015/09/03 12:15:26 I think you meant: "Unless a page is specified the I think you meant: "Unless a page is specified the locale file matching the name of the current page is used." kzar 2015/09/03 13:05:32 Done. Show quoted text On 2015/09/03 12:15:26, Wladimir Palant wrote: > I think you meant: "Unless a page is specified the locale file matching the name > of the current page is used." Done.
	282 page is used.

285 * `get_page_content(page, locale=None)`: returns a dictionary of the content	283 * `get_page_content(page, locale=None)`: returns a dictionary of the content

286 and params for the given page and locale. Locale defaults to the current one	284 and params for the given page and locale. Locale defaults to the current one

287 if not specified. Provided keys include:	285 if not specified. Provided keys include `head`, `body`, `available_locales`

288	286 and `translation_ratio`.

289 ```

290 ['localized_string_callback', 'body', 'templatedata', 'available_locales',

291 'title', 'locale', 'head', 'source', 'localedata', 'template', 'defaultlocale',

292 'pagedata', 'translation_ratio', 'config', 'page']
Wladimir Palant 2015/09/03 12:15:26 Please don't list everything returned. In particul Please don't list everything returned. In particular, things meant for internal use and the ones identical to the current page are irrelevant. It's really: head, body, available_locales, translation_ratio. kzar 2015/09/03 13:05:33 Done. Show quoted text On 2015/09/03 12:15:26, Wladimir Palant wrote: > Please don't list everything returned. In particular, things meant for internal > use and the ones identical to the current page are irrelevant. It's really: > head, body, available_locales, translation_ratio. Done.
293 ```

294	287

295 ### Static files ###	288 ### Static files ###

296	289

297 Any files located in the `static` directory will be available on the server	290 Any files located in the `static` directory will be available on the server

298 unchanged. The file `static/css/foo.css` will be available under the URL	291 unchanged. The file `static/css/foo.css` will be available under the URL

299 `/css/foo.css`.	292 `/css/foo.css`.

300	293

301 ### Templates ###	294 ### Templates ###

302	295

303 The templates specified in the `templates` directory specify the overall	296 The templates specified in the `templates` directory specify the overall

(...skipping 17 matching lines...) Expand all Loading...
321 filter is invoked. For more information on Jinja2 filters see	314 filter is invoked. For more information on Jinja2 filters see

322 [official documentation](http://jinja.pocoo.org/docs/dev/api/#writing-filters).	315 [official documentation](http://jinja.pocoo.org/docs/dev/api/#writing-filters).

323	316

324 ### Custom functions and variables ###	317 ### Custom functions and variables ###

325	318

326 The `globals` directory can define custom Jinja2 globals which will be available	319 The `globals` directory can define custom Jinja2 globals which will be available

327 in all Jinja2 templates. Typically, this is used for custom functions. The file	320 in all Jinja2 templates. Typically, this is used for custom functions. The file

328 name should match the name of the function or variable to be defined, and export	321 name should match the name of the function or variable to be defined, and export

329 a variable with that name. E.g. `globals/myfunction.py` can define a function	322 a variable with that name. E.g. `globals/myfunction.py` can define a function

330 called `myfunction` that will become available to all Jinja2 templates.	323 called `myfunction` that will become available to all Jinja2 templates.

LEFT	RIGHT