Describe the new library behaviour (fixes #149)

NEWS.md

@@ -15,7 +15,8 @@ Standards](http://www.gnu.org/prep/standards/html_node/NEWS-File.html#NEWS-File)
 
 ## 0.9.1 (2014-03-02)
 
-This release brings a row of major internal improvements and also a few new and improved features.
+This release brings a row of major internal improvements and also a
+few new and improved features.
 
 * Replaced most of `erl_syntax` use for merl (#123).
 * Refactored compiler and test suite (#134, #136).
@@ -51,7 +52,9 @@ Happy templating!
 
 ## 0.9.0 (2014-02-17)
 
-After some fluctuating stability around *0.8.1*, this release brings a set of improvements that has been tested not only by the test suite, but also in a couple of projects.
+After some fluctuating stability around *0.8.1*, this release brings a
+set of improvements that has been tested not only by the test suite,
+but also in a couple of projects.
 
 * API changes. Added `_file` and `_template` suffixes to the compile
   functions to explicitly convey what is to be compiled.

README.markdown

@@ -178,7 +178,7 @@ Options is a proplist possibly containing:
 
 * `libraries` - A list of `{Name, Module}` libraries implementing
   custom tags and filters. `Module` should implement the
-  `erlydtl_library` behaviour.
+  `erlydtl_library` behaviour (see [Custom tags and filters] below).
 
 * `locale` **deprecated** - The same as {blocktrans_locales, [Val]}.
 
@@ -343,6 +343,36 @@ can be used for determining which variable bindings need to be passed
 to the `render/3` function.
 
 
+Custom tags and filters
+-----------------------
+
+Starting with release *0.9.1*, the recommended way to add custom tags
+and filters are to register a module implementing the
+`erlydtl_library` behaviour. There are two functions needed to
+implement a custom library: `version/0` and `inventory/1`.
+
+The `version/0` function is to be able to keep backwards compatibility
+in face of an evolving library behaviour, and should return the
+version of the behaviour the library supports. The valid range of
+versions is in the spec for the `version/0` callback in
+`erlydtl_library.erl`.
+
+### Library version 1
+
+The `inventory/1` function is called with either `filters` or `tags`
+as argument, and should return a list of all filters or tags available
+in that library, respectively (see spec in `erlydtl_library.erl` for
+details on syntax for this list).
+
+Tag functions must take a list of arguments, and may take a list of
+render options, and should return an `iolist()` as result value (see
+`custom_tags_modules` compile option).
+
+Filter functions must take an `iolist()` value to filter, and may take
+an argument, and should return an `iolist()` as result value (see
+`custom_filters_modules` compile option).
+
+
 Differences from standard Django Template Language
 --------------------------------------------------