fixes #458 Improve man page section descriptions.

8 files changed, 68 insertions, 9 deletions

diff --git a/docs/man/man3.desc b/docs/man/man3.desc
index 5a0aa91c..8daa876a 100644
--- a/docs/man/man3.desc
+++ b/docs/man/man3.desc
@@ -1,2 +1,6 @@
-This section documents core libary functions that are
-callable by applications.
+This section documents core libary functions supporting Scalability
+Protocols.
+
+Most Scalability Protocols applications can be written using just
+the functions documented in this section, as this represents the
+primary API for building such applications.
diff --git a/docs/man/man3compat.desc b/docs/man/man3compat.desc
index a1141850..a35173c0 100644
--- a/docs/man/man3compat.desc
+++ b/docs/man/man3compat.desc
@@ -1,3 +1,13 @@
 This section documents the _nanomsg_ 1.0 libary compatible functions.
-The functions in this section not be used except to aid in transitioning
-from the older _libnanomsg_ library.
\ No newline at end of file
+
+These functions are provided as a transition aid, for application
+developers coming to _NNG_ from _libnanomsg_, and are discouraged
+from use in new applications.
+
+TIP: While this is discouraged for long term use, as a transition aid
+applications may use the value returned by the
+<<nng_socket_id.3#,nng_socket_id()>> in these functions just like a
+socket descriptor (as if the socket were opened
+via <<nn_socket.3compat#,nn_socket()>>).
+This sort of API intermixing should only be used during transition from
+the legacy API to the new API.
diff --git a/docs/man/man3http.desc b/docs/man/man3http.desc
index 18ee52d1..97323e40 100644
--- a/docs/man/man3http.desc
+++ b/docs/man/man3http.desc
@@ -1,2 +1,11 @@
-This section documents supplemental HTTP support functions
-that are available.
+This section documents supplemental HTTP (HyperText Transport Protocol)
+support functions that are available.
+
+These functions can be used in conjunction with the
+<<nng_ws.7#,WebSocket>> transport for Scalability Protocols, or they
+may be used to construct other types of applications that communicate
+using HTTP.
+
+It is also possible to combine the two, such that an HTTP server providing
+static or dynamic content can also be used to host one or more Scalability
+Protocols sockets.
diff --git a/docs/man/man3supp.desc b/docs/man/man3supp.desc
index ebd48b85..caea4f94 100644
--- a/docs/man/man3supp.desc
+++ b/docs/man/man3supp.desc
@@ -1,3 +1,7 @@
 This section documents supplemental functions that are available.
-These functions are not intrinsic to building applications with
-this library, but their presence may facilitate writing portable applications.
+These functions are not intrinsic to building Scalability Protocols
+applications with this library.
+
+However, their use may facilitate writing portable applications by
+providing uniform functions for common application needs such as
+mutual exclusion locks, threading, time keeping, and similar needs.
diff --git a/docs/man/man3tls.desc b/docs/man/man3tls.desc
index a9cf7b79..225c94cc 100644
--- a/docs/man/man3tls.desc
+++ b/docs/man/man3tls.desc
@@ -1 +1,13 @@
-This section documents supplemental TLS functions that are available.
+This section documents supplemental TLS (Transport Layer Security)
+functions that are available.
+TLS support is available when using Scalability Protocols with
+the <<nng_tls.7#,TLS>> transport, or when using WebSocket, either
+with the <<nng_ws.7#,WebSocket>> transport for Scalability Protocols,
+or combined with other HTTP capabilities.
+
+These functions depend on library support that is not included directly
+with _NNG_ however, so their presence will depend on whether this
+additional support was present and enabled with _libnng_ was built.
+
+Currently, this extra support can be provided by the
+https://tls.mbed.org[mbedTLS library].
diff --git a/docs/man/man5.desc b/docs/man/man5.desc
index 3ed7d259..f99b91f5 100644
--- a/docs/man/man5.desc
+++ b/docs/man/man5.desc
@@ -1 +1,4 @@
 This section documents core macros and types that are available.
+
+These are the core types and macros that most Scalabilty Protocols
+applications need will use.
diff --git a/docs/man/man7.desc b/docs/man/man7.desc
index 0596209b..46977870 100644
--- a/docs/man/man7.desc
+++ b/docs/man/man7.desc
@@ -1,2 +1,14 @@
 This sections documents various protocols and transports that are
 available in the distribution.
+
+(((protocol)))
+Protocols represent "`patterns`" of communication, such as
+request/reply, publish/subscribe, and so forth.
+A given <<nng_socket.5#,socket>> is created with exactly one protocol, and that
+protocol defines the key behavior of the socket.
+
+(((transport)))
+Conversely, transports are the underlying mechansims by which messages
+are moved between participants, such as TCP/IP or UNIX domain IPC.
+A given <<nng_socket.5#,socket>> may be using several transports at the same
+time.
diff --git a/docs/man/nng_compat.3compat.adoc b/docs/man/nng_compat.3compat.adoc
index 77e55313..a282b4a9 100644
--- a/docs/man/nng_compat.3compat.adoc
+++ b/docs/man/nng_compat.3compat.adoc
@@ -32,6 +32,11 @@ New applications should use the newer <<nng.7#,_nng_>> API instead.
 Applications making use of this ((compatibility layer)) must take care
 to link with <<libnng.3#,_libnng_>> instead of _libnn_.
 
+TIP: While not recommended for long term use, the value returned by
+<<nng_socket_id.3#,nng_socket_id()>> can be used with these functions
+just like a value returned by <<nn_socket.3compat#,nn_socket()>>.
+This can be way to facilitate incremental transition to the new API.
+
 NOTE: Some capabilities, protocols, and transports, will not be accessible
 using this API, as the compatible API has no provision for expression
 of certain concepts introduced in the newer <<nng.7#,_nng_>> API.