Documentation updates.

This adds a few man pages, fixes the content and formatting on a few
others.

It also adds two utility scripts for me to use, publish.sh, which I
use to publish updates to the gh-pages branch, and preview.sh, which
I use to look at markup without cluttering my work directory.

9 files changed, 408 insertions, 15 deletions

diff --git a/.version b/.version
new file mode 100644
index 00000000..77d6f4ca
--- /dev/null
+++ b/.version
@@ -0,0 +1 @@
+0.0.0
diff --git a/docs/nng.adoc b/docs/nng.adoc
index 2ffc6e5b..e09cd014 100644
--- a/docs/nng.adoc
+++ b/docs/nng.adoc
@@ -3,7 +3,6 @@ nng(7)
 :doctype: manpage
 :manmanual: nng
 :mansource: nng
-:manvolnum: 7
 :icons:font
 :copyright: Copyright 2017 Garrett D'Amore <garrett@damore.org> \
             Copyright 2017 Capitar IT Group BV <info@capitar.com> \
@@ -39,9 +38,10 @@ The _nng_ library is designed to permit easy creation of new _transports_ and,
 to a lesser extent, new _protocols_.
 
 The _nng_ library is wire compatible with the SP protocols described in
-the nanomsg project; projects using _libnanomsg_ can inter-operate with
+the nanomsg project; projects using
+https://github.com/nanomsg/nanomsg[_libnanomsg_] can inter-operate with
 nng as well as other conforming implementations.  (One such implementation
-is the https://github.com/go-mangos/mangos[mangos].  Applications using _nng_
+is https://github.com/go-mangos/mangos[_mangos_].)  Applications using _nng_
 which wish to communicate with older libraries must ensure that they only
 use protocols or transports offered by the earlier library.
 
@@ -56,11 +56,17 @@ other languages please check the http://nanomsg.org/[website].
 Protocols
 ~~~~~~~~~
 
-* <<nng_bus.adoc,nng_bus(7)>> - Bus protocol
-* <<nng_pair.adoc,nng_pair(7)>> - Pair protocol
-* <<nng_pubsub.adoc,nng_pubsub(7)>> - Publish/Subscribe protocol
-* <<nng_reqrep.adoc,nng_reqrep(7)>> - Request/Reply protocol
-* <<nng_survey.adoc,nng_survey(7)>> - Survey/Respond protocol
+* <<nng_bus.adoc#,nng_bus(7)>> - Bus protocol
+* <<nng_pair.adoc#,nng_pair(7)>> - Pair protocol
+* <<nng_pub.adoc#,nng_pub(7)>> - Publisher side of publish/subscribe protocol
+* <<nng_sub.adoc#,nng_sub(7)>> - Subscriber side of publish/subscribe protocol
+* <<nng_rep.adoc#,nng_rep(7)>> - Reply side of request/reply protocol
+* <<nng_req.adoc#,nng_req(7)>> - Request side of request/reply protocol
+* <<nng_respondent.adoc#,nng_respondent(7)>> - Respondent side of survey protocol
+* <<nng_surveyor.adoc#,nng_surveyor(7)>> - Surveyor side of survey protocol
+
+
+* <<nng_surveyor.adoc,nng_surveyor(7)>> - Survey/Respond protocol
 
 Transports
 ~~~~~~~~~~
diff --git a/docs/nng_close.adoc b/docs/nng_close.adoc
index b767b2ef..3484ef99 100644
--- a/docs/nng_close.adoc
+++ b/docs/nng_close.adoc
@@ -24,8 +24,7 @@ SYNOPSIS
 -----------
 #include <nng/nng.h>
 
-int
-nng_close (int s);
+int nng_close (int s);
 -----------
 
 
diff --git a/docs/nng_inproc.adoc b/docs/nng_inproc.adoc
index 97649f35..4eb3263c 100644
--- a/docs/nng_inproc.adoc
+++ b/docs/nng_inproc.adoc
@@ -24,8 +24,7 @@ SYNOPSIS
 ----------
 #include <nng/transport/inproc/inproc.h>
 
-int
-nng_inproc_register(void);
+int nng_inproc_register(void);
 ----------
 
 DESCRIPTION
diff --git a/docs/nng_pub.adoc b/docs/nng_pub.adoc
new file mode 100644
index 00000000..b50c2768
--- /dev/null
+++ b/docs/nng_pub.adoc
@@ -0,0 +1,93 @@
+nng_pub(7)
+==========
+:doctype: manpage
+:manmanual: nng
+:mansource: nng
+:icons: font
+:source-highlighter: pygments
+:copyright: Copyright 2017 Garrett D'Amore <garrett@damore.org> \
+            Copyright 2017 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.
+
+NAME
+----
+nng_pub - publisher protocol
+
+SYNOPSIS
+--------
+
+[source,c]
+----------
+#include <nng/protocol/pubsub/pubsub.h>
+
+#define NNG_PROTO_PUB_V0 32
+#define NNG_PROTO_PUB NNG_PROTO_PUB_V0
+
+int nng_pub_open(nng_socket *s);
+int nng_pub0_open (nng_socket *s);
+
+----------
+
+DESCRIPTION
+-----------
+
+The _nng_pub_ protocol is one half of a publisher/subscriber pattern.
+In this pattern, a publisher sends data, which is broadcast to all
+subscribers.  The subscribing applications only see the data to which
+they have subscribed.
+
+The _nng_pub_ protocol is the publisher side, and the
+<<nng_sub.adoc#,nng_sub(7)>> protocol is the subscriber side.
+
+NOTE: In this implementation, the publisher delivers all messages to all
+subscribers. The subscribers maintain their own subscriptions, and filter
+them locally.  Thus, this pattern should not be used in an attempt to
+reduce bandwidth consumption.
+
+The topics that subscribers subscribe to is just the first part of
+the message body.  Applications should construct their messages
+accordingly.
+
+Socket Operations
+~~~~~~~~~~~~~~~~~
+
+The `nng_pub_open()` call creates a publisher socket.  This socket
+may be used to send messages, but is unable to receive them.  Attempts
+to receive messages will result in `NNG_ENOTSUP`.
+
+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 _nng_pub_ protocol has no protocol-specific options.
+
+Protocol Headers
+~~~~~~~~~~~~~~~~
+
+The _nng_pub_ protocol has no protocol-specific headers.
+    
+AUTHORS
+-------
+link:mailto:garrett@damore.org[Garrett D'Amore]
+
+SEE ALSO
+--------
+<<nng.adoc#,nng(7)>>
+<<nng_sub.adoc#,nng_sub(7)>>
+
+COPYRIGHT
+---------
+
+Copyright 2017 mailto:garrett@damore.org[Garrett D'Amore] +
+Copyright 2017 mailto:info@capitar.com[Capitar IT Group BV]
+
+This document is supplied under the terms of the
+https://opensource.org/licenses/LICENSE.txt[MIT License].
diff --git a/docs/nng_sub.adoc b/docs/nng_sub.adoc
new file mode 100644
index 00000000..9aa00bdb
--- /dev/null
+++ b/docs/nng_sub.adoc
@@ -0,0 +1,110 @@
+nng_sub(7)
+==========
+:doctype: manpage
+:manmanual: nng
+:mansource: nng
+:icons: font
+:source-highlighter: pygments
+:copyright: Copyright 2017 Garrett D'Amore <garrett@damore.org> \
+            Copyright 2017 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.
+
+NAME
+----
+nng_sub - subscriber protocol
+
+SYNOPSIS
+--------
+
+[source,c]
+----------
+#include <nng/protocol/pubsub/pubsub.h>
+
+#define NNG_PROTO_SUB_V0 33
+#define NNG_PROTO_SUB NNG_PROTO_SUB_V0
+
+int nng_sub_open(nng_socket *s);
+int nng_sub0_open (nng_socket *s);
+
+----------
+
+DESCRIPTION
+-----------
+
+The _nng_sub_ protocol is one half of a publisher/subscriber pattern.
+In this pattern, a publisher sends data, which is broadcast to all
+subscribers.  The subscribing applications only see the data to which
+they have subscribed.
+
+The _nng_sub_ protocol is the subscriber side, and the
+<<nng_pub.adoc#,nng_pub(7)>> protocol is the publisher side.
+
+NOTE: In this implementation, the publisher delivers all messages to all
+subscribers. The subscribers maintain their own subscriptions, and filter
+them locally.  Thus, this pattern should not be used in an attempt to
+reduce bandwidth consumption.
+
+The topics that subscribers subscribe to is just the first part of
+the message body.  Applications should construct their messages
+accordingly.
+
+Socket Operations
+~~~~~~~~~~~~~~~~~
+
+The `nng_sub_open()` call creates a subscriber socket.  This socket
+may be used to receive messages, but is unable to send them.  Attempts
+to send messages will result in `NNG_ENOTSUP`.
+
+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 following protocol-specific options are available.
+
+`NNG_OPT_SUB_SUBSCRIBE`::
+
+   This option registers a topic that the subscriber is interested in.
+   The option is write-only, and takes an array of bytes, of arbitrary size.
+   Each incoming message is checked against the list of subscribed topics.
+   If the body begins with the entire set of bytes in the topic, then the
+   message is accepted.  If no topic matches, then the message is
+   discarded.
++
+TIP: To receive all messages, an empty topic (zero length) can be used.
+
+`NNG_OPT_SUB_UNSUBSCRIBE`::
+
+   This option, also read-only, removes a topic from the subscription list.
+   Note that if the topic was not previously subscribed to with
+   `NNG_OPT_SUB_SUBSCRIBE` then an `NNG_ENOENT` error will result.
+
+Protocol Headers
+~~~~~~~~~~~~~~~~
+
+The _nng_sub_ protocol has no protocol-specific headers.
+    
+AUTHORS
+-------
+link:mailto:garrett@damore.org[Garrett D'Amore]
+
+SEE ALSO
+--------
+<<nng.adoc#,nng(7)>>
+<<nng_pub.adoc#,nng_pub(7)>>
+
+COPYRIGHT
+---------
+
+Copyright 2017 mailto:garrett@damore.org[Garrett D'Amore] +
+Copyright 2017 mailto:info@capitar.com[Capitar IT Group BV]
+
+This document is supplied under the terms of the
+https://opensource.org/licenses/LICENSE.txt[MIT License].
diff --git a/docs/nng_zerotier.adoc b/docs/nng_zerotier.adoc
index b30b0a0e..4b0c1f51 100644
--- a/docs/nng_zerotier.adoc
+++ b/docs/nng_zerotier.adoc
@@ -3,7 +3,6 @@ nng_zerotier(7)
 :doctype: manpage
 :manmanual: nng
 :mansource: nng
-:manvolnum: 7
 :icons: font
 :source-highlighter: pygments
 :copyright: Copyright 2017 Garrett D'Amore <garrett@damore.org> \
@@ -24,8 +23,7 @@ SYNOPSIS
 ----------
 #include <nng/transport/zerotier/zerotier.h>
 
-int
-nng_zt_register(void);
+int nng_zt_register(void);
 ----------
 
 DESCRIPTION
diff --git a/docs/preview.sh b/docs/preview.sh
new file mode 100755
index 00000000..8814f1b6
--- /dev/null
+++ b/docs/preview.sh
@@ -0,0 +1,81 @@
+#!/bin/bash
+#
+# Copyright 2017 Garrett D'Amore <garrett@damore.org>
+# Copyright 2017 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.
+#
+
+# This script is used to preview in HTML or man format, the documentation.
+# I use it during development, YMMV.  It is probably completely useless
+# on Windows.
+
+case $(uname -s) in
+Darwin)
+	OPEN=open
+	MAN=man
+	;;
+Linux)
+	OPEN=xdg-open
+	MAN=man
+	;;
+*)
+	echo "No idea how to preview on this system."
+	exit 2
+esac
+
+if [[ -n "$DISPLAY" ]]
+then
+	style=html
+else
+	style=man
+fi
+
+while getopts hmc arg
+do
+	case "${arg}" in
+	h)	style=html;;
+	m)	style=man;;
+	c)	cleanup=yes;;
+	?)	echo "Usage: $0 [-h|-m] <files...>"; exit 1 ;;
+	esac
+done
+shift $(( $OPTIND - 1 ))
+
+open_man=${MAN}
+open_html=${OPEN}
+suffix_html=".html"
+suffix_man=".man"
+backend_html="html5"
+backend_man="manpage"
+version=$(cat $(dirname $0)/../.version)
+name=nng
+
+if [ -n "${cleanup}" ]
+then
+	tempdir=$(mktemp -d)
+	clean() {
+		rm -rf ${tempdir}
+	}
+	trap clean 0
+	mkdir -p ${tempdir}
+else
+	tempdir=/tmp/${LOGNAME}.${name}.preview
+	mkdir -p ${tempdir}
+fi
+
+eval backend=\$backend_${style}
+eval suffix=\$suffix_${style}
+eval view=\$open_${style}
+
+for input in "$@"; do
+	base=$(basename $input)
+	base=${base%.adoc}
+	output=${tempdir}/${base}${suffix}
+	asciidoctor -aversion-label=${name} -arevnumber=${version} \
+		-b ${backend} -o ${output} $input
+	$view $output
+	sleep 1
+done
diff --git a/docs/publish.sh b/docs/publish.sh
new file mode 100755
index 00000000..b122838a
--- /dev/null
+++ b/docs/publish.sh
@@ -0,0 +1,106 @@
+#!/bin/bash
+#
+# Copyright 2017 Garrett D'Amore <garrett@damore.org>
+# Copyright 2017 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.
+#
+# 
+# This program attempts to publish updated documentation to our gh-pages
+# branch.
+# 
+# We read the .version file from ../.version.
+# 
+# The docs are published into the gh-pages branch, in a directory
+# called man/v<version>.
+# 
+# This script requires asciidoctor, pygments, git, and a UNIX shell.
+# 
+
+tmpdir=$(mktemp -d)
+srcdir=$(dirname $0)
+dstdir=${tmpdir}/pages
+cd ${srcdir}
+vers=$(cat ../.version)
+dstman=${dstdir}/man/v${vers}
+name=nng
+
+giturl="${GITURL:-git@github.com:nanomsg/nng}"
+
+cleanup() {
+	echo "DELETING ${tmpdir}"
+	rm -rf ${tmpdir}
+}
+
+mkdir -p ${tmpdir}
+
+trap cleanup 0
+
+echo git clone ${giturl} ${dstdir} || exit 1
+git clone ${giturl} ${dstdir} || exit 1
+
+(cd ${dstdir}; git checkout gh-pages)
+
+[ -d ${dstman} ] || mkdir -p ${dstman}
+
+dirty=
+for input in $(find . -name '*.adoc'); do
+	adoc=${input#./}
+	html=${adoc%.adoc}.html
+	output=${dstman}/${html}
+
+	status=$(git status -s $input )
+	when=$(git log -n1 --format='%ad' '--date=format-local:%s' $input )
+	frontmatter="version: ${vers}\nlayout: default"
+
+	echo "---" > ${output}
+	echo "$frontmatter" >> ${output}
+	echo "---" >> ${output}
+
+	if [ -n "$when" ]
+	then
+		epoch="SOURCE_DATE_EPOCH=${when}"
+	else
+		epoch=
+		dirty=yes
+	fi
+	if [ -n "$status" ]
+	then
+		echo "File $adoc is not checked in!"
+		dirty=yes
+	fi
+
+
+	env ${epoch} asciidoctor \
+		-aversion-label=${name} \
+		-arevnumber=${vers}  \
+		-askip-front-matter \
+		-bhtml5 \
+		-o - ${adoc} >> ${output}
+	chmod 0644 ${output}
+
+	if [ $? -ne 0 ]
+	then
+		echo "Failed to process $adoc !"
+		fails=yes
+	fi
+		
+
+	(cd ${dstman}; git add ${html})
+done
+
+if [ -n "$dirty" ]
+then
+	echo "Repository has uncommited documentation.  Aborting."
+	exit 1
+fi
+
+if [ -n "$fails" ]
+then
+	echo "Failures formatting documentation. Aborting."
+	exit 1
+fi
+
+(cd ${dstman}; git commit -m "man page updates for ${vers}"; git push origin gh-pages)