Add message handling man pages.

Note that we're also no longer overriding the source formatter or
the icons for new pages, since we can supply that on the command
line in the script that generates output.

1 files changed, 46 insertions, 39 deletions

diff --git a/docs/libnng.adoc b/docs/libnng.adoc
index e5fd24ec..179b9a0e 100644
--- a/docs/libnng.adoc
+++ b/docs/libnng.adoc
@@ -1,9 +1,7 @@
-libnng(3)
-=========
+= libnng(3)
 :doctype: manpage
 :manmanual: nng
 :mansource: nng
-:icons: font
 :copyright: 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 \
@@ -11,28 +9,26 @@ libnng(3)
             file was obtained (LICENSE.txt).  A copy of the license may also \
             be found online at https://opensource.org/licenses/MIT.
 
-NAME
-----
+== NAME
+
 libnng - nanomsg next generation library
 
-SYNOPSIS
---------
+== SYNOPSIS
+
 *cc* ['flags'] 'files' *-lnng* ['libraries']
 
 
-DESCRIPTION
------------
+== DESCRIPTION
 
 The <<nng#,nng(7)>> library provides a common messaging framework
 intended to solve common communication problems in distributed applications.
 
 It provides a C language API.
 
-Common Functions
-~~~~~~~~~~~~~~~~
+=== Common Functions
+
 The following common functions exist in _libnng_.
 
-[cols="1,4"]
 |===
 |<<nng_alloc#,nng_alloc(3)>>|allocate memory
 |<<nng_dial#,nng_dial(3)>>|create and start a dialer
@@ -40,12 +36,10 @@ The following common functions exist in _libnng_.
 |<<nng_strerror#,nng_strerror(3)>>|return an error description
 |===
 
-Socket Functions
-~~~~~~~~~~~~~~~~
+=== Socket Functions
 
 The following functions operate on sockets.
 
-[cols="1,4"]
 |===
 |<<nng_close#,nng_close(3)>>|close a socket
 |<<nng_closeall#,nng_closeall(3)>>|close all open sockets
@@ -57,8 +51,7 @@ The following functions operate on sockets.
 |<<nng_setopt#,nng_setopt(3)>>|set a socket option
 |===
 
-Message Functions
-~~~~~~~~~~~~~~~~~
+=== Message Handling Functions
 
 Applications desiring to use the richest part of _libnng_ will want to
 use the message API, where a message structure is passed between functions.
@@ -68,21 +61,39 @@ Messages are divided into a header and body, where the body generally carries
 user-payload and the header carries protocol specific header information.
 Most applications will only interact with the body.
 
-[cols="1,4"]
 |===
 |<<nng_msg_alloc#,nng_msg_alloc(3)>>|allocate a message
-|<<nng_msg_body#,nng_msg_body(3)>>|return the message body
+|<<nng_msg_append#,nng_msg_append(3)>>|append to message body
+|<<nng_msg_body#,nng_msg_body(3)>>|return message body
+|<<nng_msg_chop#,nng_msg_chop(3)>>|remove data from end of message body
+|<<nng_msg_clear#,nng_msg_clear(3)>>|clear message body
+|<<nng_msg_dup#,nng_msg_len(3)>>|duplicate a message
 |<<nng_msg_free#,nng_msg_free(3)>>|free a message
-|<<nng_msg_header#,nng_msg_header(3)>>|return the message header
-|<<nng_msg_header_len#,nng_msg_header_len(3)>>|return the message header length
+|<<nng_msg_insert#,nng_msg_insert(3)>>|prepend to message body
 |<<nng_msg_len#,nng_msg_len(3)>>|return the message body length
 |<<nng_msg_realloc#,nng_msg_realloc(3)>>|reallocate a message
+|<<nng_msg_trim#,nng_msg_trim(3)>>|remove data from start of message body
 |<<nng_recv_msg#,nng_recvmsg(3)>>|receive a message
 |<<nng_sendmsg#,nng_sendmsg(3)>>|send a message
 |===
 
-Asynchronous Operations
-~~~~~~~~~~~~~~~~~~~~~~~
+==== Message Header Handling
+
+TIP: Few applications will need these functions, as message headers are only
+used to carry protocol-specific content.  However, applications which use raw
+mode may need to access the header of messages.
+
+|===
+|<<nng_msg_header#,nng_msg_header(3)>>|return message header
+|<<nng_msg_header_append#,nng_msg_header_append(3)>>|append to message header
+|<<nng_msg_header_chop#,nng_msg_header_chop(3)>>|remove data from end of message header
+|<<nng_msg_header_clear#,nng_msg_header_clear(3)>>|clear message header
+|<<nng_msg_header_insert#,nng_msg_header_insert(3)>>|prepend to message header
+|<<nng_msg_header_len#,nng_msg_header_len(3)>>|return the message header length
+|<<nng_msg_header_trim#,nng_msg_header_trim(3)>>|remove data from start of message header
+|===
+
+=== Asynchronous Operations
 
 Most applications will interact with _nng_ synchronously; that is that
 functions such as <<nng_send#,nng_send()>> will block the calling
@@ -105,7 +116,6 @@ be associated with an _aio_ at any time.
 
 The following functions are used in the asynchronous model:
 
-[cols="1,4"]
 |===
 |<<nng_aio_alloc#,nng_aio_alloc(3)>>|allocate asynchronous I/O context
 |<<nng_aio_cancel#,nng_aio_cancel(3)>>|cancel asynchronous I/O operation
@@ -120,13 +130,11 @@ The following functions are used in the asynchronous model:
 |<<nng_send_aio#,nng_send_aio(3)>>|send a message asynchronously
 |===
 
-Protocols
-~~~~~~~~~
+=== Protocols
 
 The following functions are used to construct a socket with a specific
 protocol:
 
-[cols="1,4"]
 |===
 | <<nng_bus#,nng_bus_open(3)>>|open a bus socket
 | <<nng_pair#,nng_pair_open(3)>>|open a pair socket
@@ -138,12 +146,10 @@ protocol:
 | <<nng_surveyor#,nng_surveyor_open(3)>>|open a surveyor socket
 |===
 
-Transports
-~~~~~~~~~~
+=== Transports
 
 The following functions are used to register a transport for use.
 
-[cols="1,4"]
 |===
 | <<nng_inproc#,nng_inproc_register(3)>>|register inproc transport
 | <<nng_ipc#,nng_ipc_register(3)>>|register IPC transport
@@ -154,12 +160,14 @@ The following functions are used to register a transport for use.
 | <<nng_zerotier#,nng_zerotier_register(3)>>|register ZeroTier transport
 |===
 
-TLS Configuration Objects
-~~~~~~~~~~~~~~~~~~~~~~~~
+=== TLS Configuration Objects
+
+The following functions are used to manipulate transport layer security
+(TLS) configuration objects.
 
-The following functions are used to manipulate TLS configuration objects.
+NOTE: These functions will only be present if the library has been built
+with TLS support.
 
-[cols="1,4"]
 |===
 | <<nng_tls_config_auth_alloc#,nng_tls_config_alloc(3)>>|allocate TLS configuration
 | <<nng_tls_config_auth_mode#,nng_tls_config_auth_mode(3)>>|set authentication mode
@@ -167,18 +175,17 @@ The following functions are used to manipulate TLS configuration objects.
 | <<nng_tls_config_ca_file#,nng_tls_config_ca_file(3)>>|load certificate authority from file
 | <<nng_tls_config_cert_key_file#,nng_tls_config_cert_key_file_cert(3)>>|load own certificate and key from file
 | <<nng_tls_config_own_cert#,nng_tls_config_own_cert(3)>>|set own certificate and key
-| <<nng_tls_config_free#,nng_tls_config_free(3)>>}free TLS configuration
+| <<nng_tls_config_free#,nng_tls_config_free(3)>>|free TLS configuration
 | <<nng_tls_config_server_name#,nng_tls_config_server_name(3)>>|set remote server name
 |===
 
 
-SEE ALSO
---------
+== SEE ALSO
+
 <<nng#,nng(7)>>,
 <<nng_compat#,nng_compat(3)>>
 
-COPYRIGHT
----------
+== COPYRIGHT
 
 Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] +
 Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV]