From 37167ce58aa08d15fc75afc6d3a93f77becd6e16 Mon Sep 17 00:00:00 2001
From: "Yichun Zhang (agentzh)" <agentzh@gmail.com>
Date: Tue, 27 Oct 2015 11:24:50 +0800
Subject: [PATCH] documented the content_by_lua_block {} directive.

---
 README.markdown        | 31 +++++++++++++++++++++++++++++++
 doc/HttpLuaModule.wiki | 26 ++++++++++++++++++++++++++
 2 files changed, 57 insertions(+)

diff --git a/README.markdown b/README.markdown
index 4a444690..3954e179 100644
--- a/README.markdown
+++ b/README.markdown
@@ -1076,6 +1076,7 @@ Directives
 * [set_by_lua_block](#set_by_lua_block)
 * [set_by_lua_file](#set_by_lua_file)
 * [content_by_lua](#content_by_lua)
+* [content_by_lua_block](#content_by_lua_block)
 * [content_by_lua_file](#content_by_lua_file)
 * [rewrite_by_lua](#rewrite_by_lua)
 * [rewrite_by_lua_file](#rewrite_by_lua_file)
@@ -1566,6 +1567,9 @@ content_by_lua
 
 **phase:** *content*
 
+**WARNING** Since the `v0.9.17` release, use of this directive is *discouraged*;
+use the new [content_by_lua_block](#content_by_lua_block) directive instead.
+
 Acts as a "content handler" and executes Lua code string specified in `<lua-script-str>` for every request. 
 The Lua code may make [API calls](#nginx-api-for-lua) and is executed as a new spawned coroutine in an independent global environment (i.e. a sandbox).
 
@@ -1573,6 +1577,33 @@ Do not use this directive and other content handler directives in the same locat
 
 [Back to TOC](#directives)
 
+content_by_lua_block
+--------------------
+
+**syntax:** *content_by_lua_block { lua-script }*
+
+**context:** *location, location if*
+
+**phase:** *content*
+
+Similar to the [content_by_lua](#content_by_lua) directive except that this directive inlines
+the Lua source directly
+inside a pair of curly braces (`{}`) instead of in an NGINX string literal (which requires
+special character escaping).
+
+For instance,
+
+```nginx
+
+ content_by_lua_block {
+     ngx.say("I need no extra escaping here, for example: \r\nblah")
+ }
+```
+
+This directive was first introduced in the `v0.9.17` release.
+
+[Back to TOC](#directives)
+
 content_by_lua_file
 -------------------
 
diff --git a/doc/HttpLuaModule.wiki b/doc/HttpLuaModule.wiki
index a20c20cf..3549e1ec 100644
--- a/doc/HttpLuaModule.wiki
+++ b/doc/HttpLuaModule.wiki
@@ -1282,11 +1282,37 @@ This directive requires the [https://github.com/simpl/ngx_devel_kit ngx_devel_ki
 
 '''phase:''' ''content''
 
+'''WARNING''' Since the <code>v0.9.17</code> release, use of this directive is ''discouraged'';
+use the new [[#content_by_lua_block|content_by_lua_block]] directive instead.
+
 Acts as a "content handler" and executes Lua code string specified in <code><lua-script-str></code> for every request. 
 The Lua code may make [[#Nginx API for Lua|API calls]] and is executed as a new spawned coroutine in an independent global environment (i.e. a sandbox).
 
 Do not use this directive and other content handler directives in the same location. For example, this directive and the [[HttpProxyModule#proxy_pass|proxy_pass]] directive should not be used in the same location.
 
+== content_by_lua_block ==
+
+'''syntax:''' ''content_by_lua_block { lua-script }''
+
+'''context:''' ''location, location if''
+
+'''phase:''' ''content''
+
+Similar to the [[#content_by_lua|content_by_lua]] directive except that this directive inlines
+the Lua source directly
+inside a pair of curly braces (`{}`) instead of in an NGINX string literal (which requires
+special character escaping).
+
+For instance,
+
+<geshi lang="nginx">
+    content_by_lua_block {
+        ngx.say("I need no extra escaping here, for example: \r\nblah")
+    }
+</geshi>
+
+This directive was first introduced in the <code>v0.9.17</code> release.
+
 == content_by_lua_file ==
 
 '''syntax:''' ''content_by_lua_file <path-to-lua-script-file>''