flux_send_new(3): add new manpage stub

Problem: there is no man page for flux_send_new().

Add it to flux_send.rst and configure a stub to be produced for
flux_send_new().

The previous synopsis function prototypes were not within a literal
block and had to be escaped.  Fix that while adding the new function.

doc/Makefile.am

@@ -166,6 +166,7 @@ MAN3_FILES_SECONDARY = \
 	man3/flux_shell_task_info_unpack.3 \
 	man3/flux_shell_task_cmd.3 \
 	man3/flux_service_unregister.3 \
+	man3/flux_send_new.3 \
 	man3/flux_clone.3 \
 	man3/flux_close.3 \
 	man3/flux_reconnect.3 \

doc/man3/flux_send.rst

@@ -6,9 +6,13 @@ flux_send(3)
 SYNOPSIS
 ========
 
-#include <flux/core.h>
+::
 
-int flux_send (flux_t \*h, const flux_msg_t \*msg, int flags);
+   #include <flux/core.h>
+
+   int flux_send (flux_t *h, const flux_msg_t *msg, int flags);
+
+   int flux_send_new (flux_t *h, flux_msg_t **msg, int flags);
 
 
 DESCRIPTION
@@ -31,6 +35,11 @@ to ``flux_open()`` when the handle was created.
 The message type, topic string, and nodeid affect how the message
 will be routed by the broker. These attributes are pre-set in the message.
 
+``flux_send_new()`` is the same, except message ownership is transferred
+to the handle *h*.  The double pointer *msg* points to a NULL value if
+the message is successfully transferred.  The send fails if the message
+reference count is greater than one.
+
 
 RETURN VALUE
 ============

doc/manpages.py

@@ -215,6 +215,7 @@
     ('man3/flux_rpc', 'flux_rpc_get_matchtag', 'perform a remote procedure call to a Flux service', [author], 3),
     ('man3/flux_rpc', 'flux_rpc_get_nodeid', 'perform a remote procedure call to a Flux service', [author], 3),
     ('man3/flux_send', 'flux_send', 'send message using Flux Message Broker', [author], 3),
+    ('man3/flux_send', 'flux_send_new', 'send message using Flux Message Broker', [author], 3),
     ('man3/flux_service_register', 'flux_service_register', 'Register service with flux broker', [author], 3),
     ('man3/flux_service_register', 'flux_service_unregister', 'Unregister service with flux broker', [author], 3),
     ('man3/flux_shell_add_completion_ref', 'flux_shell_remove_completion_ref', 'Manipulate conditions for job completion.', [author], 3),