fixes #457 Create stub headers for compatibility

I actually made these real headers, not stubs
While here I made some improvements to the nng_compat man page,
to improve the language and also the presentation on some devices.
(We were going nuts with the icons, instead, I've made a single new
section, called Caveats, that lists a bunch of them.)

This should not have any impact on binary compatibility.

13 files changed, 389 insertions, 46 deletions

diff --git a/src/compat/nanomsg/CMakeLists.txt b/src/compat/nanomsg/CMakeLists.txt
index d1a692b7..9bac8ede 100644
--- a/src/compat/nanomsg/CMakeLists.txt
+++ b/src/compat/nanomsg/CMakeLists.txt
@@ -9,7 +9,18 @@
 #
 
 set(COMPAT_SOURCES compat/nanomsg/nn.c)
-set(COMPAT_HEADERS compat/nanomsg/nn.h)
+set(COMPAT_HEADERS compat/nanomsg/nn.h
+        compat/nanomsg/bus.h
+        compat/nanomsg/inproc.h
+        compat/nanomsg/ipc.h
+        compat/nanomsg/pair.h
+        compat/nanomsg/pipeline.h
+        compat/nanomsg/pubsub.h
+        compat/nanomsg/reqrep.h
+        compat/nanomsg/survey.h
+        compat/nanomsg/tcp.h
+        compat/nanomsg/ws.h
+)
 
 set(NNG_SOURCES ${NNG_SOURCES} ${COMPAT_SOURCES} PARENT_SCOPE)
 set(NNG_HEADERS ${NNG_HEADERS} ${COMPAT_HEADERS} PARENT_SCOPE)
diff --git a/src/compat/nanomsg/bus.h b/src/compat/nanomsg/bus.h
new file mode 100644
index 00000000..004a9ac6
--- /dev/null
+++ b/src/compat/nanomsg/bus.h
@@ -0,0 +1,33 @@
+//
+// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2018 Capitar IT Group BV <info@capitar.com>
+//
+// This software is supplied under the terms of the MIT License, a
+// copy of which should be located in the distribution where this
+// file was obtained (LICENSE.txt).  A copy of the license may also be
+// found online at https://opensource.org/licenses/MIT.
+//
+
+#ifndef NNG_COMPAT_BUS_H
+#define NNG_COMPAT_BUS_H
+
+// This header contains interfaces that are intended to offer compatibility
+// with nanomsg v1.0.  These are not the "preferred" interfaces for nng,
+// and consumers should only use these if they are porting software that
+// previously used nanomsg.  New programs should use the nng native APIs.
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// BUS sockopt level.
+#define NN_PROTO_BUS 7
+#define NN_BUS (NN_PROTO_BUS * 16 + 0)
+
+// BUS has no options.
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // NNG_COMPAT_BUS_H
diff --git a/src/compat/nanomsg/inproc.h b/src/compat/nanomsg/inproc.h
new file mode 100644
index 00000000..9c71a1ee
--- /dev/null
+++ b/src/compat/nanomsg/inproc.h
@@ -0,0 +1,31 @@
+//
+// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2018 Capitar IT Group BV <info@capitar.com>
+//
+// This software is supplied under the terms of the MIT License, a
+// copy of which should be located in the distribution where this
+// file was obtained (LICENSE.txt).  A copy of the license may also be
+// found online at https://opensource.org/licenses/MIT.
+//
+
+#ifndef NNG_COMPAT_INPROC_H
+#define NNG_COMPAT_INPROC_H
+
+// This header contains interfaces that are intended to offer compatibility
+// with nanomsg v1.0.  These are not the "preferred" interfaces for nng,
+// and consumers should only use these if they are porting software that
+// previously used nanomsg.  New programs should use the nng native APIs.
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// inproc sockopt level.
+// There are no inproc tunables.
+#define NN_INPROC (-1)
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // NNG_COMPAT_INPROC_H
diff --git a/src/compat/nanomsg/ipc.h b/src/compat/nanomsg/ipc.h
new file mode 100644
index 00000000..c935b50c
--- /dev/null
+++ b/src/compat/nanomsg/ipc.h
@@ -0,0 +1,39 @@
+//
+// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2018 Capitar IT Group BV <info@capitar.com>
+//
+// This software is supplied under the terms of the MIT License, a
+// copy of which should be located in the distribution where this
+// file was obtained (LICENSE.txt).  A copy of the license may also be
+// found online at https://opensource.org/licenses/MIT.
+//
+
+#ifndef NNG_COMPAT_IPC_H
+#define NNG_COMPAT_IPC_H
+
+// This header contains interfaces that are intended to offer compatibility
+// with nanomsg v1.0.  These are not the "preferred" interfaces for nng,
+// and consumers should only use these if they are porting software that
+// previously used nanomsg.  New programs should use the nng native APIs.
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// IPC sockopt level.
+#define NN_IPC (-2)
+
+// IPC options.  Note that these are not currently supported.
+// IPC_SEC_ATTR works quite differently in NNG, and must be
+// configured using the new API.  The buffer sizing options are
+// not supported at all.  None of these were ever documente, and
+// are offered here only for source compatibility.
+#define NN_IPC_SEC_ATTR 1
+#define NN_IPC_OUTBUFSZ 2
+#define NN_IPC_INBUFSZ 3
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // NNG_COMPAT_IPC_H
diff --git a/src/compat/nanomsg/nn.c b/src/compat/nanomsg/nn.c
index 6d23106c..6755a8ea 100644
--- a/src/compat/nanomsg/nn.c
+++ b/src/compat/nanomsg/nn.c
@@ -9,6 +9,22 @@
 //
 
 #include "nn.h"
+
+// transports
+#include "inproc.h"
+#include "ipc.h"
+#include "tcp.h"
+#include "ws.h"
+
+// protocols
+#include "bus.h"
+#include "pair.h"
+#include "pipeline.h"
+#include "pubsub.h"
+#include "reqrep.h"
+#include "survey.h"
+
+// underlying NNG headers
 #include "nng.h"
 #include "protocol/bus0/bus.h"
 #include "protocol/pair0/pair.h"
diff --git a/src/compat/nanomsg/nn.h b/src/compat/nanomsg/nn.h
index be98ec2f..789aed3e 100644
--- a/src/compat/nanomsg/nn.h
+++ b/src/compat/nanomsg/nn.h
@@ -8,12 +8,12 @@
 // found online at https://opensource.org/licenses/MIT.
 //
 
-#ifndef NNG_COMPAT_H
-#define NNG_COMPAT_H
+#ifndef NNG_COMPAT_NN_H
+#define NNG_COMPAT_NN_H
 
 // This header contains interfaces that are intended to offer compatibility
 // with nanomsg v1.0.  These are not the "preferred" interfaces for nng,
-// and consumers should only use thse if they are porting software that
+// and consumers should only use these if they are porting software that
 // previously used nanomsg.  New programs should use the nng native APIs.
 
 // Note that compatibility promises are limited to public portions of the
@@ -63,27 +63,6 @@ extern "C" {
 #define AF_SP			1
 #define AF_SP_RAW		2
 
-// Protocol stuff
-#define NN_PROTO_PAIR		1
-#define NN_PROTO_PUBSUB		2
-#define NN_PROTO_REQREP		3
-#define NN_PROTO_PIPELINE	5
-#define NN_PROTO_SURVEY		6
-#define NN_PROTO_BUS		7
-
-#define NN_PAIR			(NN_PROTO_PAIR * 16 + 0)
-#define NN_PAIR_v0		(NN_PROTO_PAIR * 16 + 0)
-#define NN_PAIR_V1		(NN_PROTO_PAIR * 16 + 1)
-#define NN_PUB			(NN_PROTO_PUBSUB * 16 + 0)
-#define NN_SUB			(NN_PROTO_PUBSUB * 16 + 1)
-#define NN_REQ			(NN_PROTO_REQREP * 16 + 0)
-#define NN_REP			(NN_PROTO_REQREP * 16 + 1)
-#define NN_PUSH			(NN_PROTO_PIPELINE * 16 + 0)
-#define NN_PULL			(NN_PROTO_PIPELINE * 16 + 1)
-#define NN_SURVEYOR		(NN_PROTO_SURVEY * 16 + 2)
-#define NN_RESPONDENT		(NN_PROTO_SURVEY * 16 + 3)
-#define NN_BUS			(NN_PROTO_BUS * 16 + 0)
-
 #define NN_SOCKADDR_MAX		128
 #define NN_SOL_SOCKET		0
 
@@ -223,26 +202,6 @@ extern "C" {
 #define NN_RCVMAXSIZE		16
 #define NN_MAXTTL		17
 
-// Protocol-specific options.  To simplify thins we encode the protocol
-// level in the option.
-#define NN_SUB_SUBSCRIBE		(NN_SUB * 16 + 1)
-#define NN_SUB_UNSUBSCRIBE		(NN_SUB * 16 + 2)
-#define NN_REQ_RESEND_IVL		(NN_REQ * 16 + 1)
-#define NN_SURVEYOR_DEADLINE		(NN_SURVEYOR * 16 + 1)
-
-// Level options for tranports
-#define NN_INPROC			(-1)
-#define NN_IPC				(-2)
-#define NN_IPC_SEC_ATTR			1
-#define NN_IPC_OUTBUFSZ			2
-#define NN_IPC_INBUFSZ			3
-#define NN_TCP				(-3)
-#define NN_TCP_NODELAY			1
-#define NN_WS				(-4)
-#define NN_WS_MSG_TYPE			1
-#define NN_WS_MSG_TYPE_TEXT		1
-#define NN_WS_MSG_TYPE_BINARY		2
-
 // from this point on formatting is fine
 // clang-format on
 
@@ -319,4 +278,4 @@ NN_DECL void        nn_term(void);
 }
 #endif
 
-#endif // NNG_COMPAT_H
+#endif // NNG_COMPAT_NN_H
diff --git a/src/compat/nanomsg/pair.h b/src/compat/nanomsg/pair.h
new file mode 100644
index 00000000..458aac8c
--- /dev/null
+++ b/src/compat/nanomsg/pair.h
@@ -0,0 +1,39 @@
+//
+// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2018 Capitar IT Group BV <info@capitar.com>
+//
+// This software is supplied under the terms of the MIT License, a
+// copy of which should be located in the distribution where this
+// file was obtained (LICENSE.txt).  A copy of the license may also be
+// found online at https://opensource.org/licenses/MIT.
+//
+
+#ifndef NNG_COMPAT_PAIR_H
+#define NNG_COMPAT_PAIR_H
+
+// This header contains interfaces that are intended to offer compatibility
+// with nanomsg v1.0.  These are not the "preferred" interfaces for nng,
+// and consumers should only use these if they are porting software that
+// previously used nanomsg.  New programs should use the nng native APIs.
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// PAIR sockopt level.
+#define NN_PROTO_PAIR 1
+#define NN_PAIR (NN_PROTO_PAIR * 16 + 0)
+
+// These are technically "new", and not available in nanomsg, but
+// offered here as a transition aid.  If you want to use the advanced
+// PAIRv1 options (POLYAMOROUS mode) you still need to use the new API.
+#define NN_PAIR_v0 (NN_PROTO_PAIR * 16 + 0)
+#define NN_PAIR_V1 (NN_PROTO_PAIR * 16 + 1)
+
+// PAIR has no options.
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // NNG_COMPAT_PAIR_H
diff --git a/src/compat/nanomsg/pipeline.h b/src/compat/nanomsg/pipeline.h
new file mode 100644
index 00000000..187a4b4e
--- /dev/null
+++ b/src/compat/nanomsg/pipeline.h
@@ -0,0 +1,34 @@
+//
+// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2018 Capitar IT Group BV <info@capitar.com>
+//
+// This software is supplied under the terms of the MIT License, a
+// copy of which should be located in the distribution where this
+// file was obtained (LICENSE.txt).  A copy of the license may also be
+// found online at https://opensource.org/licenses/MIT.
+//
+
+#ifndef NNG_COMPAT_PIPELINE_H
+#define NNG_COMPAT_PIPELINE_H
+
+// This header contains interfaces that are intended to offer compatibility
+// with nanomsg v1.0.  These are not the "preferred" interfaces for nng,
+// and consumers should only use these if they are porting software that
+// previously used nanomsg.  New programs should use the nng native APIs.
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// PUSH and PULL sockopt level.
+#define NN_PROTO_PIPELINE 5
+#define NN_PUSH (NN_PROTO_PIPELINE * 16 + 0)
+#define NN_PULL (NN_PROTO_PIPELINE * 16 + 1)
+
+// PUSH and PULL have no options.
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // NNG_COMPAT_PIPELINE_H
diff --git a/src/compat/nanomsg/pubsub.h b/src/compat/nanomsg/pubsub.h
new file mode 100644
index 00000000..43118f68
--- /dev/null
+++ b/src/compat/nanomsg/pubsub.h
@@ -0,0 +1,36 @@
+//
+// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2018 Capitar IT Group BV <info@capitar.com>
+//
+// This software is supplied under the terms of the MIT License, a
+// copy of which should be located in the distribution where this
+// file was obtained (LICENSE.txt).  A copy of the license may also be
+// found online at https://opensource.org/licenses/MIT.
+//
+
+#ifndef NNG_COMPAT_PUBSUB_H
+#define NNG_COMPAT_PUBSUB_H
+
+// This header contains interfaces that are intended to offer compatibility
+// with nanomsg v1.0.  These are not the "preferred" interfaces for nng,
+// and consumers should only use these if they are porting software that
+// previously used nanomsg.  New programs should use the nng native APIs.
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// PUB and SUB sockopt level.
+#define NN_PROTO_PUBSUB 2
+#define NN_PUB (NN_PROTO_PUBSUB * 16 + 0)
+#define NN_SUB (NN_PROTO_PUBSUB * 16 + 1)
+
+// SUB options.  (PUB has none.)
+#define NN_SUB_SUBSCRIBE (NN_SUB * 16 + 1)
+#define NN_SUB_UNSUBSCRIBE (NN_SUB * 16 + 2)
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // NNG_COMPAT_PUBSUB_H
diff --git a/src/compat/nanomsg/reqrep.h b/src/compat/nanomsg/reqrep.h
new file mode 100644
index 00000000..9490a8f1
--- /dev/null
+++ b/src/compat/nanomsg/reqrep.h
@@ -0,0 +1,35 @@
+//
+// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2018 Capitar IT Group BV <info@capitar.com>
+//
+// This software is supplied under the terms of the MIT License, a
+// copy of which should be located in the distribution where this
+// file was obtained (LICENSE.txt).  A copy of the license may also be
+// found online at https://opensource.org/licenses/MIT.
+//
+
+#ifndef NNG_COMPAT_REQREP_H
+#define NNG_COMPAT_REQREP_H
+
+// This header contains interfaces that are intended to offer compatibility
+// with nanomsg v1.0.  These are not the "preferred" interfaces for nng,
+// and consumers should only use these if they are porting software that
+// previously used nanomsg.  New programs should use the nng native APIs.
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// REQ and REP sockopt level.
+#define NN_PROTO_REQREP 3
+#define NN_REQ (NN_PROTO_REQREP * 16 + 0)
+#define NN_REP (NN_PROTO_REQREP * 16 + 1)
+
+// REQ options.  (REP has none.)
+#define NN_REQ_RESEND_IVL (NN_REQ * 16 + 1)
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // NNG_COMPAT_REQREP_H
diff --git a/src/compat/nanomsg/survey.h b/src/compat/nanomsg/survey.h
new file mode 100644
index 00000000..fdef10cb
--- /dev/null
+++ b/src/compat/nanomsg/survey.h
@@ -0,0 +1,36 @@
+//
+// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2018 Capitar IT Group BV <info@capitar.com>
+//
+// This software is supplied under the terms of the MIT License, a
+// copy of which should be located in the distribution where this
+// file was obtained (LICENSE.txt).  A copy of the license may also be
+// found online at https://opensource.org/licenses/MIT.
+//
+
+#ifndef NNG_COMPAT_SURVEY_H
+#define NNG_COMPAT_SURVEY_H
+
+// This header contains interfaces that are intended to offer compatibility
+// with nanomsg v1.0.  These are not the "preferred" interfaces for nng,
+// and consumers should only use these if they are porting software that
+// previously used nanomsg.  New programs should use the nng native APIs.
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// SURVEYOR and RESPONDENT sockopt level.
+#define NN_PROTO_SURVEY 6
+#define NN_SURVEYOR (NN_PROTO_SURVEY * 16 + 2)
+#define NN_RESPONDENT (NN_PROTO_SURVEY * 16 + 3)
+
+// SURVEYOR options.  (RESPONDENT has none.)
+
+#define NN_SURVEYOR_DEADLINE (NN_SURVEYOR * 16 + 1)
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // NNG_COMPAT_SURVEY_H
diff --git a/src/compat/nanomsg/tcp.h b/src/compat/nanomsg/tcp.h
new file mode 100644
index 00000000..5a305c49
--- /dev/null
+++ b/src/compat/nanomsg/tcp.h
@@ -0,0 +1,33 @@
+//
+// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2018 Capitar IT Group BV <info@capitar.com>
+//
+// This software is supplied under the terms of the MIT License, a
+// copy of which should be located in the distribution where this
+// file was obtained (LICENSE.txt).  A copy of the license may also be
+// found online at https://opensource.org/licenses/MIT.
+//
+
+#ifndef NNG_COMPAT_TCP_H
+#define NNG_COMPAT_TCP_H
+
+// This header contains interfaces that are intended to offer compatibility
+// with nanomsg v1.0.  These are not the "preferred" interfaces for nng,
+// and consumers should only use these if they are porting software that
+// previously used nanomsg.  New programs should use the nng native APIs.
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// TCP sockopt level.
+#define NN_TCP (-3)
+
+// TCP options.
+#define NN_TCP_NODELAY 1
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // NNG_COMPAT_TCP_H
diff --git a/src/compat/nanomsg/ws.h b/src/compat/nanomsg/ws.h
new file mode 100644
index 00000000..3072a3b5
--- /dev/null
+++ b/src/compat/nanomsg/ws.h
@@ -0,0 +1,41 @@
+//
+// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2018 Capitar IT Group BV <info@capitar.com>
+//
+// This software is supplied under the terms of the MIT License, a
+// copy of which should be located in the distribution where this
+// file was obtained (LICENSE.txt).  A copy of the license may also be
+// found online at https://opensource.org/licenses/MIT.
+//
+
+#ifndef NNG_COMPAT_WS_H
+#define NNG_COMPAT_WS_H
+
+// This header contains interfaces that are intended to offer compatibility
+// with nanomsg v1.0.  These are not the "preferred" interfaces for nng,
+// and consumers should only use these if they are porting software that
+// previously used nanomsg.  New programs should use the nng native APIs.
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// WS sockopt level.
+#define NN_WS (-4)
+
+// WS options.
+
+// Note that while legacy libnanomsg had *some* support for text messages,
+// NNG only supports binary.  Binary types are required to pass protocol
+// headers with NNG and nanomsg in any event.  This means that the NNG
+// WebSocket support will not be compatible with some very old browsers.
+#define NN_WS_MSG_TYPE 1
+
+#define NN_WS_MSG_TYPE_TEXT 0x1
+#define NN_WS_MSG_TYPE_BINARY 0x2
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // NNG_COMPAT_WS_H