Add some advice about template parameters in PLUGINS.

diff --git a/NEWS b/NEWS
index 29c9c5ebe4052e8860d5694df0b6f9a23c71fb3e..673063e0689f9ac2d358a9dd28b273b0cd891dd4 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -3,6 +3,10 @@
 Be consistent about catching AttributeError when looking for attributes
 that were added to Rawdog during the 2.x series (spotted by Jakub Wilk).
 
+Add some advice in PLUGINS about escaping template parameters. Willem
+reported that the enclosure plugin didn't do this, and having had a look
+at the others it seems to be a common problem.
+
 - rawdog 2.17
 
 Add a one-paragraph description of rawdog to the README file, for use by

diff --git a/PLUGINS b/PLUGINS
index 65f18edc322231e1d6a9150bcae56d79561fc905..57fc3ec339607e0795fca21014f286973bfae8bd 100644 (file)
--- a/PLUGINS
+++ b/PLUGINS
@@ -169,9 +169,20 @@ Called after all items are written.
 
 * bits: a dictionary of template parameters
 
-Called before expanding the main template. This hook can be used to add
+Called before expanding the page template. This hook can be used to add
 extra template parameters.
 
+Note that template parameters should be valid HTML, with entities
+escaped, even if they're URLs or similar. You can use rawdog's
+`rawdoglib.rawdog.string_to_html` function to do this for you:
+
+       the_thing = "This can contain arbitary text & stuff"
+       bits["thing"] = string_to_html(the_thing, config)
+
+It's also good idea for template parameter names to be valid Python
+identifiers, so that plugins that replace the template system with
+something smarter can make them into local variables.
+
 ### output_item_bits(rawdog, config, feed, article, bits)
 
 * feed: the Feed containing this article
@@ -181,6 +192,9 @@ extra template parameters.
 Called before expanding the item template for an article. This hook can
 be used to add extra template parameters.
 
+(See the documentation for `output_bits` for some advice on adding
+template parameters.)
+
 ### pre_update_feed(rawdog, config, feed)
 
 * feed: the Feed about to be updated