doc: readme: aligned with ngx_http_lua's README and removed mentions of PUC-Rio Lua.

Author: thibaultcha

README.md

@@ -4,15 +4,18 @@ Name
 
 ngx_stream_lua_module - Embed the power of Lua into Nginx stream/TCP Servers.
 
-This module is a core component of OpenResty. If you are using this module, then you are essentially using OpenResty :)
+This module is a core component of OpenResty. If you are using this module,
+then you are essentially using OpenResty.
 
-*This module is not distributed with the Nginx source.* See [the installation instructions](#installation).
+*This module is not distributed with the Nginx source.* See [the installation
+instructions](#installation).
 
 Table of Contents
 =================
 
 * [Name](#name)
 * [Status](#status)
+* [Version](#version)
 * [Synopsis](#synopsis)
 * [Description](#description)
     * [Directives](#directives)
@@ -34,6 +37,13 @@ Status
 
 Production ready.
 
+Version
+=======
+
+This document describes ngx_stream_lua
+[v0.0.8](https://github.com/openresty/stream-lua-nginx-module/tags), which is not
+released yet.
+
 Synopsis
 ========
 
@@ -99,23 +109,26 @@ stream {
 }
 ```
 
+[Back to TOC](#table-of-contents)
+
 Description
 ===========
 
-This module is a core component of OpenResty. If you are using this module, then you are essentially using OpenResty :)
+This is a port of the
+[ngx_http_lua_module](https://github.com/openresty/lua-nginx-module#readme) to
+the Nginx "stream" subsystem so as to support generic stream/TCP clients.
 
-This is a port of the [ngx_http_lua_module](https://github.com/openresty/lua-nginx-module#readme) to the NGINX "stream" subsystem so
-as to support generic stream/TCP clients in the downstream.
-
-Lua APIs and directive names remain the same as the `ngx_http_lua_module`.
+The available Lua APIs and Nginx directives remain the same as those of the
+ngx_http_lua module.
 
 [Back to TOC](#table-of-contents)
 
 Directives
 ----------
 
-The following directives are ported directly from `ngx_http_lua_module`. Please check the
-documentation of `ngx_http_lua_module` for more details about their usage and behavior.
+The following directives are ported directly from ngx_http_lua. Please check
+the documentation of ngx_http_lua for more details about their usage and
+behavior.
 
 * [lua_load_resty_core](https://github.com/openresty/lua-nginx-module#lua_load_resty_core)
 * [lua_code_cache](https://github.com/openresty/lua-nginx-module#lua_code_cache)
@@ -155,11 +168,14 @@ documentation of `ngx_http_lua_module` for more details about their usage and be
 * [lua_capture_error_log](https://github.com/openresty/lua-nginx-module#lua_capture_error_log)
 * [preread_by_lua_no_postpone](#preread_by_lua_no_postpone)
 
-The [send_timeout](http://nginx.org/r/send_timeout) directive in the Nginx "http" subsystem is missing in the "stream" subsystem.
-So `ngx_stream_lua_module` uses the `lua_socket_send_timeout` for this purpose.
+The [send_timeout](https://nginx.org/r/send_timeout) directive in the Nginx
+"http" subsystem is missing in the "stream" subsystem. As such,
+ngx_stream_lua_module uses the `lua_socket_send_timeout` directive for this
+purpose instead.
 
-**Note:** the lingering close directive that used to exist in older version of stream_lua_nginx_module has been removed and can
-now be simulated with the newly added [tcpsock:shutdown](#tcpsockshutdown) method if necessary.
+**Note:** the lingering close directive that used to exist in older version of
+`stream_lua_nginx_module` has been removed and can now be simulated with the
+newly added [tcpsock:shutdown](#tcpsockshutdown) API if necessary.
 
 [Back to TOC](#table-of-contents)
 
@@ -256,7 +272,7 @@ lua_add_variable
 
 **context:** *stream*
 
-Add the variable `$var` to the stream subsystem and makes it changeable. If `$var` already exists,
+Add the variable `$var` to the "stream" subsystem and makes it changeable. If `$var` already exists,
 this directive will do nothing.
 
 By default, variables added using this directive are considered "not found" and reading them
@@ -284,12 +300,12 @@ This directive was first introduced in the `v0.0.4` release.
 Nginx API for Lua
 -----------------
 
-Many Lua API functions are ported from the `ngx_http_lua_module`. Check out the official manual of
-`ngx_http_lua_module` for more details on these Lua API functions.
+Many Lua API functions are ported from ngx_http_lua. Check out the official
+manual of ngx_http_lua for more details on these Lua API functions.
 
 * [ngx.var.VARIABLE](https://github.com/openresty/lua-nginx-module#ngxvarvariable)
 
-This module fully supports the new variable subsystem inside the NGINX stream core. You may access any
+This module fully supports the new variable subsystem inside the Nginx stream core. You may access any
 [built-in variables](https://nginx.org/en/docs/stream/ngx_stream_core_module.html#variables) provided by the stream core or
 other stream modules.
 * [Core constants](https://github.com/openresty/lua-nginx-module#core-constants)
@@ -304,7 +320,7 @@ other stream modules.
 * [ngx.balancer](https://github.com/openresty/lua-resty-core/blob/master/lib/ngx/balancer.md)
 
 Only raw request sockets are supported, for obvious reasons. The `raw` argument value
-is ignored and the raw request socket is always returned. Unlike `ngx_http_lua_module`,
+is ignored and the raw request socket is always returned. Unlike ngx_http_lua,
 you can still call output API functions like `ngx.say`, `ngx.print`, and `ngx.flush`
 after acquiring the raw request socket via this function.
 
@@ -316,6 +332,8 @@ packets back to the client using the downstream socket.
 
 The raw TCP sockets returned by this module will contain the following extra method:
 
+[Back to TOC](#directives)
+
 tcpsock:shutdown
 ----------------
 
@@ -494,9 +512,7 @@ TODO
 ====
 
 * Add new directives `access_by_lua_block` and `access_by_lua_file`.
-* Add `ngx.semaphore` API.
-* Add support for [lua-resty-core](https://github.com/openresty/lua-resty-core).
-* Add `lua_postpone_output` to emulate the [postpone_output](http://nginx.org/r/postpone_output) directive.
+* Add `lua_postpone_output` to emulate the [postpone_output](https://nginx.org/r/postpone_output) directive.
 
 [Back to TOC](#table-of-contents)
 
@@ -509,34 +525,45 @@ The latest version of this module is compatible with the following versions of N
 * 1.15.x (last tested: 1.15.8)
 * 1.13.x (last tested: 1.13.6)
 
-Nginx cores older than 1.13.6 (exclusive) are *not* tested and may or may not work. Use at your own risk!
+Nginx cores older than 1.13.6 (exclusive) are *not* tested and may or may not
+work. Use at your own risk!
 
 [Back to TOC](#table-of-contents)
 
 Installation
 ============
 
-This module can be manually compiled into Nginx or OpenResty:
+It is *highly* recommended to use [OpenResty releases](https://openresty.org)
+which bundle Nginx, ngx_http_lua, ngx_stream_lua, (this module), LuaJIT, as
+well as other powerful companion Nginx modules and Lua libraries.
 
-1. Install LuaJIT 2.1 or Lua 5.1 (Lua 5.2+ are *not* supported yet). LuaJIT can be downloaded from the [the LuaJIT project website](http://luajit.org/download.html) and Lua 5.1, from the [Lua project website](http://www.lua.org/).  Some distribution package managers also distribute LuaJIT and/or Lua.
-1. Download the latest version of ngx_stream_lua [HERE](https://github.com/openresty/stream-lua-nginx-module/tags).
-1. Download the latest supported version of NGINX [HERE](http://nginx.org/) (See [Nginx Compatibility](#nginx-compatibility)) or the OpenResty bundle from [HERE](https://openresty.org/).
+It is discouraged to build this module with Nginx yourself since it is tricky
+to set up exactly right.
 
-Build the source of NGINX or OpenResty with this module, like below:
+Note that Nginx, LuaJIT, and OpenSSL official releases have various limitations
+and long standing bugs that can cause some of this module's features to be
+disabled, not work properly, or run slower. Official OpenResty releases are
+recommended because they bundle [OpenResty's optimized LuaJIT 2.1 fork](https://github.com/openresty/luajit2) and
+[Nginx/OpenSSL
+patches](https://github.com/openresty/openresty/tree/master/patches).
+
+Alternatively, ngx_stream_lua can be manually compiled into Nginx:
+
+1. LuaJIT can be downloaded from the [latest release of OpenResty's LuaJIT fork](https://github.com/openresty/luajit2/releases). The official LuaJIT 2.x releases are also supported, although performance will be significantly lower for reasons elaborated above
+1. Download the latest version of ngx_stream_lua [HERE](https://github.com/openresty/stream-lua-nginx-module/tags)
+1. Download the latest supported version of Nginx [HERE](https://nginx.org/) (See [Nginx Compatibility](#nginx-compatibility))
+
+Build the source with this module:
 
 ```bash
-wget 'http://nginx.org/download/nginx-1.13.6.tar.gz'
+wget 'https://nginx.org/download/nginx-1.13.6.tar.gz'
 tar -xzvf nginx-1.13.6.tar.gz
 cd nginx-1.13.6/
 
 # tell nginx's build system where to find LuaJIT 2.1:
 export LUAJIT_LIB=/path/to/luajit/lib
 export LUAJIT_INC=/path/to/luajit/include/luajit-2.1
 
-# or tell where to find Lua if using Lua instead:
-#export LUA_LIB=/path/to/lua/lib
-#export LUA_INC=/path/to/lua/include
-
 # Here we assume Nginx is to be installed under /opt/nginx/.
 ./configure --prefix=/opt/nginx \
         --with-ld-opt="-Wl,-rpath,/path/to/luajit-or-lua/lib" \
@@ -549,8 +576,9 @@ make -j4
 make install
 ```
 
-You may use `--without-http` if you do not wish to use this module with the HTTP subsystem.
-ngx_stream_lua will work perfectly fine without the presense of the HTTP subsystem.
+You may use `--without-http` if you do not wish to use this module with the
+"http" subsystem. ngx_stream_lua will work perfectly fine without the "http"
+subsystem.
 
 [Back to TOC](#table-of-contents)
 
@@ -576,7 +604,8 @@ The [openresty](https://groups.google.com/group/openresty) mailing list is for C
 Code Repository
 ===============
 
-The code repository of this project is hosted on github at [openresty/stream-lua-nginx-module](https://github.com/openresty/stream-lua-nginx-module).
+The code repository of this project is hosted on GitHub at
+[openresty/stream-lua-nginx-module](https://github.com/openresty/stream-lua-nginx-module).
 
 [Back to TOC](#table-of-contents)
 
@@ -601,6 +630,8 @@ to make code sharing between this module and [lua-nginx-module](https://github.c
 * `balancer_by_lua_*`, `preread_by_lua_*`, `log_by_lua_*` and `ssl_certby_lua*` phases support.
 * [`reqsock:peek`](#reqsockpeek) API support.
 
+[Back to TOC](#table-of-contents)
+
 Copyright and License
 =====================