diff options
| -rw-r--r-- | .version | 1 | ||||
| -rw-r--r-- | docs/nng.adoc | 22 | ||||
| -rw-r--r-- | docs/nng_close.adoc | 3 | ||||
| -rw-r--r-- | docs/nng_inproc.adoc | 3 | ||||
| -rw-r--r-- | docs/nng_pub.adoc | 93 | ||||
| -rw-r--r-- | docs/nng_sub.adoc | 110 | ||||
| -rw-r--r-- | docs/nng_zerotier.adoc | 4 | ||||
| -rwxr-xr-x | docs/preview.sh | 81 | ||||
| -rwxr-xr-x | docs/publish.sh | 106 |
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) |