Documentation updates for 1.0.1

Signed-off-by: Martin Lucina <martin@lucina.net>

5 files changed, 79 insertions, 32 deletions

diff --git a/NEWS b/NEWS
index 3ebe6b5..b484ba5 100644
--- a/NEWS
+++ b/NEWS
@@ -6,27 +6,55 @@ I/O. For a detailed list of changes please refer to Git history, or the
 ChangeLog file included with your distribution of Crossroads.
 
 
+Release 1.0.1 (29 March 2012)
+-----------------------------
+
+This is a bug fix release, with the only new addition being the XS_KEEPALIVE
+socket option for enabling TCP keepalives.
+
+New features::
+* XS_KEEPALIVE options added
+
+Bugfixes::
+* Fix race condition in find_endpoint
+* Small ommision in session creation mechanism
+* Reconnect test fixed
+* OpenVMS tests fixed
+* Send identities on reconnect
+* Make REQ session state machine aware of reconnections
+* Error handling during connect
+* Ignore distorted timeouts on Windows in debug mode
+* Add long comment about security problem on Windows platform
+* Signaler's global event is now accessible by everyone
+* Handle duplicate identities decently
+* wireformat test added
+* Fixed issue LIBZMQ-345 - race condition in ctx.socket/term allows segfault
+* Add missing <sys/types.h> header.
+* Use strncpy() instead of strcpy().
+* Documentation updates.
+
+
 Release 1.0.0 (15 March 2012)
 -----------------------------
 
 Initial release.  Changes listed here are as compared to libzmq release
 3.1.
 
-New features:
+New features::
 
 * The io_threads argument has been removed from xs_init(), and the default
   number of I/O threads per context is now 1.
 * Context options added - see xs_setctxopt(3):
-  * The XS_IO_THREADS context option allows the user to specify the size of
+  - The XS_IO_THREADS context option allows the user to specify the size of
     the worker thread pool.
-  * The XS_MAX_SOCKETS context option allows the user to specify the
+  - The XS_MAX_SOCKETS context option allows the user to specify the
     maximum number of sockets that can exist in parallel within a context.
 * Allow setting the source address for TCP connections - see xs_tcp(7).
 * ZeroMQ drop-in compatibility mode, enabled by the --enable-libzmq option
   to configure. This is a binary compatible emulation of the ZeroMQ 2.1.11
   API, for details see zmq(7).
 
-Bugfixes:
+Bugfixes::
 
 * Fix pgm_receiver.cpp: zmq_assert (pending_bytes == 0). (LIBZMQ-205)
 * Fix assertion in pgm_sender_t::plug(). (LIBZMQ-303)
@@ -39,18 +67,18 @@ Bugfixes:
 * Removal of pipe from dist_t fixed.
 * Only use AI_V4MAPPED if defined, and don't use it on FreeBSD.
 
-Optimisation:
+Optimisation::
 
 * Several optimisations to reduce the memory size of PUB/SUB subscription
   map.
 * Avoid one extra call to poll() when there are no more data to send.
 
-Build:
+Build::
 
 * MSVC build updated to use MSVC2010 instead of MSVC2008.
 * configure prints out a summary of XS configuration.
 
-Self tests:
+Self tests::
 
 * Many more tests have been added, see the tests/ subdirectory.
 * The self tests can now be run from a MSVC build, see the "tests" project.
diff --git a/README b/README
index 25f36ed..0f9afe7 100644
--- a/README
+++ b/README
@@ -59,15 +59,33 @@ NOTE: Enabling this option will *overwrite* any existing installation of
 Reporting Bugs
 --------------
 
-To report a bug, sign up to the Crossroads I/O development discussion group
-at <http://groups.crossroads.io> and post a topic or send an email
-describing your problem.
+To report a bug, send an email describing your problem to the Crossroads
+mailing list. To make sure your bug report won't be missed, you can file a
+report in the bug tracker at <https://github.com/crossroads-io/libxs/issues>.
 
-Prefix the subject of your post with `[BUG]` to catch the developers
-attention.
+To help Crossroads developers to fix the bug, please try to provide a minimal
+test program, ideally written in C, that reproduces the problem you are
+reporting.
 
-To ensure that your report is dealt with promptly, please attach a minimal
-test case reproducing the bug, ideally written in C.
+NOTE: The bug tracker exists primarily to track bugs and pertinent data (test
+cases, crash logs, etc.). You should not use it for _discussion_. In the bug
+tracker your audience will be very limited. Mailing list serves the purpose of
+discussing bugs much better.
+
+
+Contributing to the Project
+---------------------------
+
+Before contributing to the project make sure you understand the legal
+implications of doing so. These are outlined on the Crossroads I/O website at
+<http://www.crossroads.io/dev:legal>.
+
+To submit your contribution, send it as a patch (using git format-patch, diff,
+or similar) to the mailing list. Make sure to use your real name, and prefix
+the subject of your post with `[PATCH]`.
+
+All contributions will be reviewed and, if they pass review, accepted. For more
+details refer to the website at <http://www.crossroads.io/dev:code-review>.
 
 
 Resources
@@ -81,7 +99,8 @@ mailing list. Vist <http://groups.crossroads.io/> to join or view archives
 of previous discussion.
 
 Extensive documentation is provided with the distribution. Refer to
-doc/xs.html, or "man xs" after you have installed libxs on your system.
+`doc/xs.html`, or the 'xs(7)' manual page after you have installed libxs on
+your system.
 
 Further resources, language bindings, tutorials, and more can be found on
 the Crossroads website at <http://www.crossroads.io/>.
diff --git a/doc/xs_getsockopt.txt b/doc/xs_getsockopt.txt
index c113f16..99d9376 100644
--- a/doc/xs_getsockopt.txt
+++ b/doc/xs_getsockopt.txt
@@ -121,7 +121,7 @@ XS_IDENTITY: Set socket identity
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The 'XS_IDENTITY' option shall retrieve the identity of the specified 'socket'.
 Socket identity is used only by request/reply pattern. Namely, it can be used
-in tandem with ROUTER socket to route messages to the peer with specific
+in tandem with a 'XS_XREP' socket to route messages to the peer with specific
 identity.
 
 Identity should be at least one byte and at most 255 bytes long. Identities
@@ -338,7 +338,7 @@ hosts.
 Option value type:: int
 Option value unit:: boolean
 Default value:: 1 (true)
-Applicable socket types:: all, when using TCP transports.
+Applicable socket types:: all, when using TCP transport.
 
 
 XS_FD: Retrieve file descriptor associated with the socket
@@ -390,18 +390,18 @@ Option value unit:: N/A (flags)
 Default value:: N/A
 Applicable socket types:: all
 
-XS_KEEPALIVE: Use TCP keepalives
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-When set to `1` TCP keepalives are enabled. This option can be used to prevent
-the infrastructure (VPNs and similar) to terminate connections with no activity.
-The keepalive period as such is normally a global OS setting.
+XS_KEEPALIVE: Enable transport keepalives
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When set to `1`, this option enables use of protocol keepalives on the
+'socket', if supported by the underlying transport protocol.
 
 [horizontal]
 Option value type:: int
 Option value unit:: boolean
 Default value:: 0 (false)
-Applicable socket types:: all, when using TCP transports.
+Applicable socket types:: all, when using TCP transport.
 
 
 RETURN VALUE
diff --git a/doc/xs_setsockopt.txt b/doc/xs_setsockopt.txt
index e9a7050..e07d9dd 100644
--- a/doc/xs_setsockopt.txt
+++ b/doc/xs_setsockopt.txt
@@ -126,7 +126,7 @@ XS_IDENTITY: Set socket identity
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The 'XS_IDENTITY' option shall set the identity of the specified 'socket'.
 Socket identity is used only by request/reply pattern. Namely, it can be used
-in tandem with ROUTER socket to route messages to the peer with specific
+in tandem with a 'XS_XREP' socket to route messages to the peer with specific
 identity.
 
 Identity should be at least one byte and at most 255 bytes long. Identities
@@ -346,20 +346,19 @@ applications connect to and accept connections from both IPv4 and IPv6 hosts.
 Option value type:: int
 Option value unit:: boolean
 Default value:: 1 (true)
-Applicable socket types:: all, when using TCP transports.
+Applicable socket types:: all, when using TCP transport.
 
-XS_KEEPALIVE: Use TCP keepalives
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+XS_KEEPALIVE: Enable transport keepalives
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-When set to `1` TCP keepalives are enabled. This option can be used to prevent
-the infrastructure (VPNs and similar) to terminate connections with no activity.
-The keepalive period as such is normally a global OS setting.
+When set to `1`, this option enables use of protocol keepalives on the
+'socket', if supported by the underlying transport protocol.
 
 [horizontal]
 Option value type:: int
 Option value unit:: boolean
 Default value:: 0 (false)
-Applicable socket types:: all, when using TCP transports.
+Applicable socket types:: all, when using TCP transport.
 
 
 RETURN VALUE
diff --git a/include/xs.h b/include/xs.h
index b47358b..039d62f 100644
--- a/include/xs.h
+++ b/include/xs.h
@@ -158,7 +158,7 @@ XS_EXPORT int xs_setctxopt (void *context, int option, const void *optval,
 /*  Crossroads socket definition.                                             */
 /******************************************************************************/
 
-/*  Socket types.                                                             */ 
+/*  Socket types.                                                             */
 #define XS_PAIR 0
 #define XS_PUB 1
 #define XS_SUB 2
@@ -171,6 +171,7 @@ XS_EXPORT int xs_setctxopt (void *context, int option, const void *optval,
 #define XS_XPUB 9
 #define XS_XSUB 10
 
+/*  Legacy socket type aliases.                                               */
 #define XS_ROUTER XS_XREP
 #define XS_DEALER XS_XREQ