From 98f23e10cc1d65da6a7f6c7e4f5665d7afc27a86 Mon Sep 17 00:00:00 2001
From: Garrett D'Amore <garrett@damore.org>
Date: Thu, 15 Mar 2018 08:40:17 -0700
Subject: fixes #286 nng_pair0_open (and all others) need man page fixes #279
 consider restructuring man sections

This represents a rather significant rework, and major editing
effort, for the entire set of manual pages.

All of the pages now have a section number in their filename;
this assists in some other tooling, particularly ebook generation
as every link needs to be programmatically modified when combined
into an ebook.

Section 5 is introduced, and populated with pages for the main
types, and all options are now documented.

Numerous errors have been corrected, including rewriting certain
portions such as the header section of the surveyor protocol.

Much work has been done to facilitate index generation, although
certainly more work remains here.

Every internal link within these pages now resolves; there are no
more dead links.  (This is required to generate Kindle format books.)
---
 docs/man/nng_bus.7.adoc | 74 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 74 insertions(+)
 create mode 100644 docs/man/nng_bus.7.adoc

(limited to 'docs/man/nng_bus.7.adoc')

diff --git a/docs/man/nng_bus.7.adoc b/docs/man/nng_bus.7.adoc
new file mode 100644
index 00000000..a05a9d04
--- /dev/null
+++ b/docs/man/nng_bus.7.adoc
@@ -0,0 +1,74 @@
+= nng_bus(7)
+//
+// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2018 Capitar IT Group BV <info@capitar.com>
+//
+// This document 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.
+//
+
+== NAME
+
+nng_bus - bus protocol
+
+== SYNOPSIS
+
+[source,c]
+----
+#include <nng/protocol/bus0/bus.h>
+
+int nng_bus0_open(nng_socket *s);
+----
+
+== DESCRIPTION
+
+(((protocol, _bus_)))
+The ((_bus_ protocol)) provides for building mesh networks where
+every peer is connected to every other peer.
+In this protocol, each message sent by a node is sent to every one of
+its directly connected peers.
+
+TIP: Messages are only sent to directly connected peers.
+This means that in the event that a peer is connected indirectly, it will not
+receive messages.
+When using this protocol to build mesh networks, it
+is therefore important that a _fully-connected_ mesh network be constructed.
+
+All message delivery in this pattern is ((best-effort)), which means that
+peers may not receive messages.
+Furthermore, delivery may occur to some,
+all, or none of the directly connected peers.
+(Messages are not delivered when peer nodes are unable to receive.)
+Hence, send operations will never block; instead if the
+message cannot be delivered for any reason it is discarded.
+
+TIP: In order to minimize the likelihood of message loss, this protocol
+should not be used for high throughput communications.
+Furthermore, the more traffic _in aggregate_ that occurs across the topology,
+the more likely that message loss is to occur.
+
+=== Socket Operations
+
+The <<nng_bus_open.3#,`nng_bus0_open()`>> call creates a bus socket.
+This socket may be used to send and receive messages.
+Sending messages will attempt to deliver to each directly connected peer.
+
+=== Protocol Versions
+
+Only version 0 of this protocol is supported.
+(At the time of writing, no other versions of this protocol have been defined.)
+
+=== Protocol Options
+
+The _bus_ protocol has no protocol-specific options.
+
+=== Protocol Headers
+
+The _bus_ protocol has no protocol-specific headers.
+    
+== SEE ALSO
+
+<<nng_bus_open.3#,nng_bus_open(3)>>,
+<<nng.7#,nng(7)>>
-- 
cgit v1.2.3-70-g09d2

