docs: documented how relative paths are processed when *_by_lua_file directives are used; also documented the $prefix and ${prefix} notations in lua_package_path and lua_package_cpath directive values.

README

@@ -273,13 +273,18 @@ Directives
 
     Sets the Lua module search path used by scripts specified by set_by_lua,
     content_by_lua and others. The path string is in standard Lua path form,
-    and ";;" can be used to stand for the original path.
+    and ";;" can be used to stand for the original search paths.
+
+    Since the "v0.5.0rc29" release, the special notation $prefix or
+    "${prefix}" can be used in the search path string to indicate the path
+    of the "server prefix" usually determined by the "-p PATH" command-line
+    option while starting the Nginx server.
 
   lua_package_cpath
     syntax: *lua_package_cpath <lua-style-cpath-str>*
 
-    default: *The content of LUA_CPATH environ variable or Lua's compiled-in
-    defaults.*
+    default: *The content of LUA_CPATH environment variable or Lua's
+    compiled-in defaults.*
 
     context: *main*
 
@@ -287,6 +292,11 @@ Directives
     set_by_lua, content_by_lua and others. The cpath string is in standard
     Lua cpath form, and ";;" can be used to stand for the original cpath.
 
+    Since the "v0.5.0rc29" release, the special notation $prefix or
+    "${prefix}" can be used in the search path string to indicate the path
+    of the "server prefix" usually determined by the "-p PATH" command-line
+    option while starting the Nginx server.
+
   set_by_lua
     syntax: *set_by_lua $res <lua-script-str> [$arg1 $arg2 ...]*
 
@@ -356,6 +366,10 @@ Directives
     "<path-to-lua-script-file>" argument string of this directive. But
     special care must be taken for injection attacks.
 
+    When a relative path like "foo/bar.lua" is given, they will be turned
+    into the absoluate path relative to the "server prefix" path determined
+    by the "-p PATH" command-line option while starting the Nginx server.
+
     When the Lua code cache is turned on (by default), the user code is
     loaded once at the first request and cached and the Nginx config must be
     reloaded each time the Lua source file is modified. The Lua code cache
@@ -395,6 +409,10 @@ Directives
     provide flexibility. This however carries some risks and is not
     ordinarily recommended.
 
+    When a relative path like "foo/bar.lua" is given, they will be turned
+    into the absoluate path relative to the "server prefix" path determined
+    by the "-p PATH" command-line option while starting the Nginx server.
+
     When the Lua code cache is turned on (by default), the user code is
     loaded once at the first request and cached and the Nginx config must be
     reloaded each time the Lua source file is modified. The Lua code cache
@@ -534,6 +552,10 @@ Directives
     provide flexibility. This however carries some risks and is not
     ordinarily recommended.
 
+    When a relative path like "foo/bar.lua" is given, they will be turned
+    into the absoluate path relative to the "server prefix" path determined
+    by the "-p PATH" command-line option while starting the Nginx server.
+
     When the Lua code cache is turned on (by default), the user code is
     loaded once at the first request and cached and the Nginx config must be
     reloaded each time the Lua source file is modified. The Lua code cache
@@ -628,6 +650,10 @@ Directives
     provide flexibility. This however carries some risks and is not
     ordinarily recommended.
 
+    When a relative path like "foo/bar.lua" is given, they will be turned
+    into the absoluate path relative to the "server prefix" path determined
+    by the "-p PATH" command-line option while starting the Nginx server.
+
     When the Lua code cache is turned on (by default), the user code is
     loaded once at the first request and cached and the Nginx config must be
     reloaded each time the Lua source file is modified. The Lua code cache
@@ -673,6 +699,10 @@ Directives
     Equivalent to header_filter_by_lua, except that the file specified by
     "<path-to-lua-script-file>" contains the Lua code to be executed.
 
+    When a relative path like "foo/bar.lua" is given, they will be turned
+    into the absoluate path relative to the "server prefix" path determined
+    by the "-p PATH" command-line option while starting the Nginx server.
+
     This directive was first introduced in the "v0.2.1rc20" release.
 
   lua_need_request_body

README.markdown

@@ -270,14 +270,16 @@ lua_package_path
 
 Sets the Lua module search path used by scripts specified by [set_by_lua](http://wiki.nginx.org/HttpLuaModule#set_by_lua),
 [content_by_lua](http://wiki.nginx.org/HttpLuaModule#content_by_lua) and others. The path string is in standard Lua path form, and `;;`
-can be used to stand for the original path.
+can be used to stand for the original search paths.
+
+Since the `v0.5.0rc29` release, the special notation `$prefix` or `${prefix}` can be used in the search path string to indicate the path of the `server prefix` usually determined by the `-p PATH` command-line option while starting the Nginx server.
 
 lua_package_cpath
 -----------------
 
 **syntax:** *lua_package_cpath <lua-style-cpath-str>*
 
-**default:** *The content of LUA_CPATH environ variable or Lua's compiled-in defaults.*
+**default:** *The content of LUA_CPATH environment variable or Lua's compiled-in defaults.*
 
 **context:** *main*
 
@@ -285,6 +287,8 @@ Sets the Lua C-module search path used by scripts specified by [set_by_lua](http
 [content_by_lua](http://wiki.nginx.org/HttpLuaModule#content_by_lua) and others. The cpath string is in standard Lua cpath form, and `;;`
 can be used to stand for the original cpath.
 
+Since the `v0.5.0rc29` release, the special notation `$prefix` or `${prefix}` can be used in the search path string to indicate the path of the `server prefix` usually determined by the `-p PATH` command-line option while starting the Nginx server.
+
 set_by_lua
 ----------
 
@@ -344,6 +348,8 @@ Equivalent to [set_by_lua](http://wiki.nginx.org/HttpLuaModule#set_by_lua), exce
 
 Nginx variable interpolation is supported in the `<path-to-lua-script-file>` argument string of this directive. But special care must be taken for injection attacks.
 
+When a relative path like `foo/bar.lua` is given, they will be turned into the absoluate path relative to the `server prefix` path determined by the `-p PATH` command-line option while starting the Nginx server.
+
 When the Lua code cache is turned on (by default), the user code is loaded once at the first request and cached 
 and the Nginx config must be reloaded each time the Lua source file is modified.
 The Lua code cache can be temporarily disabled during development by 
@@ -378,6 +384,8 @@ Equivalent to [content_by_lua](http://wiki.nginx.org/HttpLuaModule#content_by_lu
 
 Nginx variables can be used in the `<path-to-lua-script-file>` string to provide flexibility. This however carries some risks and is not ordinarily recommended.
 
+When a relative path like `foo/bar.lua` is given, they will be turned into the absoluate path relative to the `server prefix` path determined by the `-p PATH` command-line option while starting the Nginx server.
+
 When the Lua code cache is turned on (by default), the user code is loaded once at the first request and cached 
 and the Nginx config must be reloaded each time the Lua source file is modified.
 The Lua code cache can be temporarily disabled during development by 
@@ -510,6 +518,8 @@ Equivalent to [rewrite_by_lua](http://wiki.nginx.org/HttpLuaModule#rewrite_by_lu
 
 Nginx variables can be used in the `<path-to-lua-script-file>` string to provide flexibility. This however carries some risks and is not ordinarily recommended.
 
+When a relative path like `foo/bar.lua` is given, they will be turned into the absoluate path relative to the `server prefix` path determined by the `-p PATH` command-line option while starting the Nginx server.
+
 When the Lua code cache is turned on (by default), the user code is loaded once at the first request and cached and the Nginx config must be reloaded each time the Lua source file is modified. The Lua code cache can be temporarily disabled during development by switching [lua_code_cache](http://wiki.nginx.org/HttpLuaModule#lua_code_cache) `off` in `nginx.conf` to avoid reloading Nginx.
 
 access_by_lua
@@ -593,6 +603,8 @@ Equivalent to [access_by_lua](http://wiki.nginx.org/HttpLuaModule#access_by_lua)
 
 Nginx variables can be used in the `<path-to-lua-script-file>` string to provide flexibility. This however carries some risks and is not ordinarily recommended.
 
+When a relative path like `foo/bar.lua` is given, they will be turned into the absoluate path relative to the `server prefix` path determined by the `-p PATH` command-line option while starting the Nginx server.
+
 When the Lua code cache is turned on (by default), the user code is loaded once at the first request and cached 
 and the Nginx config must be reloaded each time the Lua source file is modified.
 The Lua code cache can be temporarily disabled during development by switching [lua_code_cache](http://wiki.nginx.org/HttpLuaModule#lua_code_cache) `off` in `nginx.conf` to avoid repeatedly reloading Nginx.
@@ -634,6 +646,8 @@ header_filter_by_lua_file
 
 Equivalent to [header_filter_by_lua](http://wiki.nginx.org/HttpLuaModule#header_filter_by_lua), except that the file specified by `<path-to-lua-script-file>` contains the Lua code to be executed.
 
+When a relative path like `foo/bar.lua` is given, they will be turned into the absoluate path relative to the `server prefix` path determined by the `-p PATH` command-line option while starting the Nginx server.
+
 This directive was first introduced in the `v0.2.1rc20` release.
 
 lua_need_request_body

doc/HttpLuaModule.wiki

@@ -256,13 +256,15 @@ Do not activate the <code>o</code> option for regular expressions (and/or <code>
 
 Sets the Lua module search path used by scripts specified by [[#set_by_lua|set_by_lua]],
 [[#content_by_lua|content_by_lua]] and others. The path string is in standard Lua path form, and <code>;;</code>
-can be used to stand for the original path.
+can be used to stand for the original search paths.
+
+Since the <code>v0.5.0rc29</code> release, the special notation <code>$prefix</code> or <code>${prefix}</code> can be used in the search path string to indicate the path of the <code>server prefix</code> usually determined by the <code>-p PATH</code> command-line option while starting the Nginx server.
 
 == lua_package_cpath ==
 
 '''syntax:''' ''lua_package_cpath <lua-style-cpath-str>''
 
-'''default:''' ''The content of LUA_CPATH environ variable or Lua's compiled-in defaults.''
+'''default:''' ''The content of LUA_CPATH environment variable or Lua's compiled-in defaults.''
 
 '''context:''' ''main''
 
@@ -270,6 +272,8 @@ Sets the Lua C-module search path used by scripts specified by [[#set_by_lua|set
 [[#content_by_lua|content_by_lua]] and others. The cpath string is in standard Lua cpath form, and <code>;;</code>
 can be used to stand for the original cpath.
 
+Since the <code>v0.5.0rc29</code> release, the special notation <code>$prefix</code> or <code>${prefix}</code> can be used in the search path string to indicate the path of the <code>server prefix</code> usually determined by the <code>-p PATH</code> command-line option while starting the Nginx server.
+
 == set_by_lua ==
 
 '''syntax:''' ''set_by_lua $res <lua-script-str> [$arg1 $arg2 ...]''
@@ -327,6 +331,8 @@ Equivalent to [[#set_by_lua|set_by_lua]], except that the file specified by <cod
 
 Nginx variable interpolation is supported in the <code><path-to-lua-script-file></code> argument string of this directive. But special care must be taken for injection attacks.
 
+When a relative path like <code>foo/bar.lua</code> is given, they will be turned into the absoluate path relative to the <code>server prefix</code> path determined by the <code>-p PATH</code> command-line option while starting the Nginx server.
+
 When the Lua code cache is turned on (by default), the user code is loaded once at the first request and cached 
 and the Nginx config must be reloaded each time the Lua source file is modified.
 The Lua code cache can be temporarily disabled during development by 
@@ -359,6 +365,8 @@ Equivalent to [[#content_by_lua|content_by_lua]], except that the file specified
 
 Nginx variables can be used in the <code><path-to-lua-script-file></code> string to provide flexibility. This however carries some risks and is not ordinarily recommended.
 
+When a relative path like <code>foo/bar.lua</code> is given, they will be turned into the absoluate path relative to the <code>server prefix</code> path determined by the <code>-p PATH</code> command-line option while starting the Nginx server.
+
 When the Lua code cache is turned on (by default), the user code is loaded once at the first request and cached 
 and the Nginx config must be reloaded each time the Lua source file is modified.
 The Lua code cache can be temporarily disabled during development by 
@@ -489,6 +497,8 @@ Equivalent to [[#rewrite_by_lua|rewrite_by_lua]], except that the file specified
 
 Nginx variables can be used in the <code><path-to-lua-script-file></code> string to provide flexibility. This however carries some risks and is not ordinarily recommended.
 
+When a relative path like <code>foo/bar.lua</code> is given, they will be turned into the absoluate path relative to the <code>server prefix</code> path determined by the <code>-p PATH</code> command-line option while starting the Nginx server.
+
 When the Lua code cache is turned on (by default), the user code is loaded once at the first request and cached and the Nginx config must be reloaded each time the Lua source file is modified. The Lua code cache can be temporarily disabled during development by switching [[#lua_code_cache|lua_code_cache]] <code>off</code> in <code>nginx.conf</code> to avoid reloading Nginx.
 
 == access_by_lua ==
@@ -570,6 +580,8 @@ Equivalent to [[#access_by_lua|access_by_lua]], except that the file specified b
 
 Nginx variables can be used in the <code><path-to-lua-script-file></code> string to provide flexibility. This however carries some risks and is not ordinarily recommended.
 
+When a relative path like <code>foo/bar.lua</code> is given, they will be turned into the absoluate path relative to the <code>server prefix</code> path determined by the <code>-p PATH</code> command-line option while starting the Nginx server.
+
 When the Lua code cache is turned on (by default), the user code is loaded once at the first request and cached 
 and the Nginx config must be reloaded each time the Lua source file is modified.
 The Lua code cache can be temporarily disabled during development by switching [[#lua_code_cache|lua_code_cache]] <code>off</code> in <code>nginx.conf</code> to avoid repeatedly reloading Nginx.
@@ -609,6 +621,8 @@ This directive was first introduced in the <code>v0.2.1rc20</code> release.
 
 Equivalent to [[#header_filter_by_lua|header_filter_by_lua]], except that the file specified by <code><path-to-lua-script-file></code> contains the Lua code to be executed.
 
+When a relative path like <code>foo/bar.lua</code> is given, they will be turned into the absoluate path relative to the <code>server prefix</code> path determined by the <code>-p PATH</code> command-line option while starting the Nginx server.
+
 This directive was first introduced in the <code>v0.2.1rc20</code> release.
 
 == lua_need_request_body ==