fixes nanomsg#495 SEE ALSO should use [align=left]

fixes nanomsg#494 ERRORS section should use [horizontal] These changes address some basic formatting consistency things, and ultimately (when combined with other tooling changes that are not part of this repo) lead to vastly improved layout in the printed documentation. While here we removed trailing whitespace, and did certain other minor markup tweaks.
XiongJinQi · May 30, 2018 · 0ddaee4 · 0ddaee4
1 parent 33dc5d6
commit 0ddaee4
Show file tree

Hide file tree

Showing 243 changed files with 493 additions and 128 deletions.
diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc
@@ -368,5 +368,6 @@ with TLS support.
 
 == SEE ALSO
 
+[.text-left]
 <<nng_compat.3compat#,nng_compat(3compat)>>,
 <<nng.7#,nng(7)>>
diff --git a/docs/man/nn_allocmsg.3compat.adoc b/docs/man/nn_allocmsg.3compat.adoc
@@ -58,6 +58,7 @@ on failure.
 
 == SEE ALSO
 
+[.text-left]
 <<nn_errno.3compat#,nn_errno(3compat)>>,
 <<nn_freemsg.3compat#,nn_freemsg(3compat)>>,
 <<nn_reallocmsg.3compat#,nn_reallocmsg(3compat)>>,

diff --git a/docs/man/nn_bind.3compat.adoc b/docs/man/nn_bind.3compat.adoc
@@ -58,6 +58,7 @@ This function returns a positive identifier on success, and -1 on error.
 
 == SEE ALSO
 
+[.text-left]
 <<nn_connect.3compat#,nn_connect(3compat)>>,
 <<nn_errno.3compat#,nn_errno(3compat)>>,
 <<nn_shutdown.3compat#,nn_shutdown(3compat)>>,

diff --git a/docs/man/nn_close.3compat.adoc b/docs/man/nn_close.3compat.adoc
@@ -44,6 +44,7 @@ This function returns zero on success, and -1 on failure.
 
 == SEE ALSO
 
+[.text-left]
 <<nn_errno.3compat#,nn_errno(3compat)>>,
 <<nn_socket.3compat#,nn_socket(3compat)>>,
 <<nng_compat.3compat#,nng_compat(3compat)>>,

diff --git a/docs/man/nn_cmsg.3compat.adoc b/docs/man/nn_cmsg.3compat.adoc
@@ -71,6 +71,7 @@ to align for another header.
 
 == SEE ALSO
 
+[.text-left]
 <<nn_recvmsg.3compat#,nn_recvmsg(3compat)>>,
 <<nn_sendmsg.3compat#,nn_sendmsg(3compat)>>,
 <<nng_compat.3compat#,nng_compat(3compat)>>,

diff --git a/docs/man/nn_connect.3compat.adoc b/docs/man/nn_connect.3compat.adoc
@@ -57,6 +57,7 @@ This function returns a positive identifier success, and -1 on error.
 
 == SEE ALSO
 
+[.text-left]
 <<nn_bind.3compat#,nn_bind(3compat)>>,
 <<nn_errno.3compat#,nn_errno(3compat)>>,
 <<nn_shutdown.3compat#,nn_shutdown(3compat)>>,

diff --git a/docs/man/nn_device.3compat.adoc b/docs/man/nn_device.3compat.adoc
@@ -51,6 +51,7 @@ one of the sockets is closed or an error occurs.
 
 == SEE ALSO
 
+[.text-left]
 <<nn_errno.3compat#,nn_errno(3compat)>>,
 <<nn_socket.3compat#,nn_socket(3compat)>>,
 <<nng_compat.3compat#,nng_compat(3compat)>>,

diff --git a/docs/man/nn_errno.3compat.adoc b/docs/man/nn_errno.3compat.adoc
@@ -33,7 +33,7 @@ Consider using the relevant <<libnng.3#,modern API>> instead.
 
 IMPORTANT: The error numbers returned from this function may include
 errors caused by system functions, which overlap the usual `errno` variable,
-and this function simply returns the value of `errno`. 
+and this function simply returns the value of `errno`.
 However, the values returned may include numeric values that are not
 defined by the system, but are unique to _libnanomsg_, such as `EFSM`.
 
@@ -73,6 +73,7 @@ If no operation has failed, then this will be zero.
 
 == SEE ALSO
 
+[.text-left]
 <<nn_strerror.3compat#,nn_strerror(3compat)>>,
 <<nng_compat.3compat#,nng_compat(3compat)>>,
 <<nng.7#,nng(7)>>
diff --git a/docs/man/nn_freemsg.3compat.adoc b/docs/man/nn_freemsg.3compat.adoc
@@ -41,6 +41,7 @@ None.
 
 == SEE ALSO
 
+[.text-left]
 <<nn_allocmsg.3compat#,nn_allocmsg(3compat)>>,
 <<nn_freemsg.3compat#,nn_freemsg(3compat)>>,
 <<nn_errno.3compat#,nn_errno(3compat)>>,

diff --git a/docs/man/nn_get_statistic.3compat.adoc b/docs/man/nn_get_statistic.3compat.adoc
@@ -41,5 +41,6 @@ None.
 
 == SEE ALSO
 
+[.text-left]
 <<nng_compat.3compat#,nng_compat(3compat)>>,
 <<nng.7#,nng(7)>>
diff --git a/docs/man/nn_getsockopt.3compat.adoc b/docs/man/nn_getsockopt.3compat.adoc
@@ -114,7 +114,7 @@ explicit notification (automatic with the `NN_REQ` protocol) or allow
 sufficient time for the socket to drain before closing the socket or exiting.
 
 
-`NN_SNDPRIO`:: 
+`NN_SNDPRIO`::
 This option is not implemented at this time.
 
 `NN_RCVPRIO`::
@@ -219,6 +219,7 @@ This function returns zero on success, and -1 on failure.
 
 == SEE ALSO
 
+[.text-left]
 <<nng_socket.5#,nng_socket(5)>>,
 <<nn_close.3compat#,nn_close(3compat)>>,
 <<nn_errno.3compat#,nn_errno(3compat)>>,

diff --git a/docs/man/nn_poll.3compat.adoc b/docs/man/nn_poll.3compat.adoc
@@ -93,6 +93,7 @@ This function returns the number of sockets with events on success, or -1 on err
 
 == SEE ALSO
 
+[.text-left]
 <<nn_errno.3compat#,nn_errno(3compat)>>,
 <<nn_recv.3compat#,nn_recv(3compat)>>,
 <<nn_send.3compat#,nn_send(3compat)>>,

diff --git a/docs/man/nn_reallocmsg.3compat.adoc b/docs/man/nn_reallocmsg.3compat.adoc
@@ -51,6 +51,7 @@ on failure.
 
 == SEE ALSO
 
+[.text-left]
 <<nn_allocmsg.3compat#,nn_allocmsg(3compat)>>,
 <<nn_freemsg.3compat#,nn_freemsg(3compat)>>,
 <<nn_errno.3compat#,nn_errno(3compat)>>,

diff --git a/docs/man/nn_recv.3compat.adoc b/docs/man/nn_recv.3compat.adoc
@@ -66,6 +66,7 @@ This function returns the number of bytes sent on success, and -1 on error.
 
 == SEE ALSO
 
+[.text-left]
 <<nn_errno.3compat#,nn_errno(3compat)>>,
 <<nn_recvmsg.3compat#,nn_recvmsg(3compat)>>,
 <<nn_send.3compat#,nn_send(3compat)>>,

diff --git a/docs/man/nn_recvmsg.3compat.adoc b/docs/man/nn_recvmsg.3compat.adoc
@@ -89,6 +89,7 @@ This function returns the number of bytes received on success, and -1 on error.
 
 == SEE ALSO
 
+[.text-left]
 <<nn_cmsg.3compat#,nn_cmsg(3compat)>>,
 <<nn_errno.3compat#,nn_errno(3compat)>>,
 <<nn_recv.3compat#,nn_recv(3compat)>>,

diff --git a/docs/man/nn_send.3compat.adoc b/docs/man/nn_send.3compat.adoc
@@ -65,6 +65,7 @@ This function returns the number of bytes sent on success, and -1 on error.
 
 == SEE ALSO
 
+[.text-left]
 <<nn_errno.3compat#,nn_errno(3compat)>>,
 <<nn_recv.3compat#,nn_recv(3compat)>>,
 <<nn_sendmsg.3compat#,nn_sendmsg(3compat)>>,

diff --git a/docs/man/nn_sendmsg.3compat.adoc b/docs/man/nn_sendmsg.3compat.adoc
@@ -61,7 +61,7 @@ has the base address (`iov_base`) and length (`iov_len`) indicated.
 For buffers allocated for zero copy
 (such as by `<<nn_allocmsg.3compat#,nn_allocmsg()>>`), the value
 of `iov_base` should be the address of the pointer to the buffer,
-rather than the address of the buffer itself. 
+rather than the address of the buffer itself.
 In this case, the value of `iov_len` should be `NN_MSG`,
 as the length is inferred from the allocated message.
 If the `msg_iovlen` field is `NN_MSG`, then this function will free
@@ -97,6 +97,7 @@ This function returns the number of bytes sent on success, and -1 on error.
 
 == SEE ALSO
 
+[.text-left]
 <<nn_cmsg.3compat#,nn_cmsg(3compat)>>,
 <<nn_errno.3compat#,nn_errno(3compat)>>,
 <<nn_recv.3compat#,nn_recv(3compat)>>,

diff --git a/docs/man/nn_setsockopt.3compat.adoc b/docs/man/nn_setsockopt.3compat.adoc
@@ -108,7 +108,7 @@ Applications needing assurance of message delivery should either include an
 explicit notification (automatic with the `NN_REQ` protocol) or allow
 sufficient time for the socket to drain before closing the socket or exiting.
 
-`NN_SNDPRIO`:: 
+`NN_SNDPRIO`::
 This option is not implemented at this time.
 
 `NN_RCVPRIO`::
@@ -197,6 +197,7 @@ This function returns zero on success, and -1 on failure.
 
 == SEE ALSO
 
+[.text-left]
 <<nng_socket.5#,nng_socket(5)>>,
 <<nn_close.3compat#,nn_close(3compat)>>,
 <<nn_errno.3compat#,nn_errno(3compat)>>,

diff --git a/docs/man/nn_shutdown.3compat.adoc b/docs/man/nn_shutdown.3compat.adoc
@@ -46,6 +46,7 @@ This function returns zero on success, and -1 on error.
 
 == SEE ALSO
 
+[.text-left]
 <<nn_bind.3compat#,nn_bind(3compat)>>,
 <<nn_connect.3compat#,nn_connect(3compat)>>,
 <<nn_errno.3compat#,nn_errno(3compat)>>,

diff --git a/docs/man/nn_socket.3compat.adoc b/docs/man/nn_socket.3compat.adoc
@@ -70,6 +70,7 @@ This function returns a valid socket number on success, and -1 on failure.
 
 == SEE ALSO
 
+[.text-left]
 <<nng_socket.5#,nng_socket(5)>>,
 <<nn_close.3compat#,nn_close(3compat)>>,
 <<nn_errno.3compat#,nn_errno(3compat)>>,

diff --git a/docs/man/nn_strerror.3compat.adoc b/docs/man/nn_strerror.3compat.adoc
@@ -41,6 +41,7 @@ None.
 
 == SEE ALSO
 
+[.text-left]
 <<nn_errno.3compat#,nn_errno(3compat)>>,
 <<nng_compat.3compat#,nng_compat(3compat)>>,
 <<nng.7#,nng(7)>>
diff --git a/docs/man/nn_term.3compat.adoc b/docs/man/nn_term.3compat.adoc
@@ -52,6 +52,7 @@ None.
 
 == SEE ALSO
 
+[.text-left]
 <<nn_errno.3compat#,nn_errno(3compat)>>,
 <<nn_socket.3compat#,nn_socket(3compat)>>,
 <<nng_compat.3compat#,nng_compat(3compat)>>,

diff --git a/docs/man/nng.7.adoc b/docs/man/nng.7.adoc
@@ -51,25 +51,38 @@ other languages please check the http://nanomsg.org/[website].
 
 == Protocols
 
-* <<nng_bus.7#,nng_bus(7)>> - Bus protocol
-* <<nng_pair.7#,nng_pair(7)>> - Pair protocol
-* <<nng_pub.7#,nng_pub(7)>> - Publisher side of publish/subscribe protocol
-* <<nng_pull.7#,nng_pull(7)>> - Pull side of pipeline protocol
-* <<nng_push.7#,nng_push(7)>> - Push side of pipeline protocol
-* <<nng_sub.7#,nng_sub(7)>> - Subscriber side of publish/subscribe protocol
-* <<nng_rep.7#,nng_rep(7)>> - Reply side of request/reply protocol
-* <<nng_req.7#,nng_req(7)>> - Request side of request/reply protocol
-* <<nng_respondent.7#,nng_respondent(7)>> - Respondent side of survey protocol
-* <<nng_surveyor.7#,nng_surveyor(7)>> - Surveyor side of survey protocol
+[horizontal]
+<<nng_bus.7#,nng_bus(7)>>:: Bus protocol
+<<nng_pair.7#,nng_pair(7)>>:: Pair protocol
+<<nng_pub.7#,nng_pub(7)>>:: Publisher side of publish/subscribe protocol
+<<nng_pull.7#,nng_pull(7)>>:: Pull side of pipeline protocol
+<<nng_push.7#,nng_push(7)>>:: Push side of pipeline protocol
+<<nng_sub.7#,nng_sub(7)>>:: Subscriber side of publish/subscribe protocol
+<<nng_rep.7#,nng_rep(7)>>:: Reply side of request/reply protocol
+<<nng_req.7#,nng_req(7)>>:: Request side of request/reply protocol
+<<nng_respondent.7#,nng_respondent(7)>>:: Respondent side of survey protocol
+<<nng_surveyor.7#,nng_surveyor(7)>>:: Surveyor side of survey protocol
+
+//* <<nng_bus.7#,nng_bus(7)>> - Bus protocol
+//* <<nng_pair.7#,nng_pair(7)>> - Pair protocol
+//* <<nng_pub.7#,nng_pub(7)>> - Publisher side of publish/subscribe protocol
+//* <<nng_pull.7#,nng_pull(7)>> - Pull side of pipeline protocol
+//* <<nng_push.7#,nng_push(7)>> - Push side of pipeline protocol
+//* <<nng_sub.7#,nng_sub(7)>> - Subscriber side of publish/subscribe protocol
+//* <<nng_rep.7#,nng_rep(7)>> - Reply side of request/reply protocol
+//* <<nng_req.7#,nng_req(7)>> - Request side of request/reply protocol
+//* <<nng_respondent.7#,nng_respondent(7)>> - Respondent side of survey protocol
+//* <<nng_surveyor.7#,nng_surveyor(7)>> - Surveyor side of survey protocol
 
 == Transports
 
-* <<nng_inproc.7#,nng_inproc(7)>> - Intra-process transport
-* <<nng_ipc.7#,nng_ipc(7)>> - Inter-process transport
-* <<nng_tls.7#,nng_tls(7)>> - TLSv1.2 over TCP transport
-* <<nng_tcp.7#,nng_tcp(7)>> - TCP (and TCPv6) transport
-* <<nng_ws.7#,nng_ws(7)>> - WebSocket transport
-* <<nng_zerotier.7#,nng_zerotier(7)>> - ZeroTier transport
+[horizontal]
+<<nng_inproc.7#,nng_inproc(7)>>:: Intra-process transport
+<<nng_ipc.7#,nng_ipc(7)>>:: Inter-process transport
+<<nng_tls.7#,nng_tls(7)>>:: TLSv1.2 over TCP transport
+<<nng_tcp.7#,nng_tcp(7)>>:: TCP (and TCPv6) transport
+<<nng_ws.7#,nng_ws(7)>>:: WebSocket transport
+<<nng_zerotier.7#,nng_zerotier(7)>>:: ZeroTier transport
 
 == Conceptual Overview
 
@@ -118,7 +131,7 @@ other than in a few specific circumstances.
 === Raw Mode
 
 (((cooked mode)))(((raw mode)))
-Most applications will use _nng_ sockets in "`cooked`" mode. 
+Most applications will use _nng_ sockets in "`cooked`" mode.
 This mode provides the full semantics of the protocol.
 For example, <<nng_req.7#,_req_>> sockets will automatically
 match a reply to a request, and resend requests periodically if no reply
@@ -144,7 +157,7 @@ processing is needed.
 
 (((URL)))
 The _nng_ library uses ((universal resource locators)) (URLs)
-following the format specified in 
+following the format specified in
 https://tools.ietf.org/html/rfc3986[RFC 3986],
 including some schemes that are unique
 to SP.
@@ -164,7 +177,7 @@ https://tools.ietf.org/html/rfc3986#section-6.2.2[RFC 3986 6.2.2]:
   . The resulting path is checked for invalid UTF-8 sequences, consisting
     of surrogate pairs, illegal byte sequences, or overlong encodings.
     If this check fails, then the entire URL is considered invalid.
-  . Path segments consisting of `.` and `..` are resolved as per 
+  . Path segments consisting of `.` and `..` are resolved as per
     https://tools.ietf.org/html/rfc3986#section-6.2.2.3[RFC 3986 6.2.2.3].
   . Further, empty path segments are removed, meaning that duplicate
     slash (`/`) separators are removed from the path.
@@ -186,5 +199,6 @@ The library API is documented at <<libnng.3#,libnng(3)>>.
 
 == SEE ALSO
 
+[.text-left]
 <<libnng.3#,libnng(3)>>,
 <<nng_compat.3compat#,nng_compat(3compat)>>
diff --git a/docs/man/nng_aio.5.adoc b/docs/man/nng_aio.5.adoc
@@ -49,6 +49,7 @@ and destroyed using `<<nng_aio_free.3#,nng_aio_free()>>`.
 
 == SEE ALSO
 
+[.text-left]
 <<nng_aio_abort.3#,nng_aio_abort(3)>>,
 <<nng_aio_alloc.3#,nng_aio_alloc(3)>>,
 <<nng_aio_cancel.3#,nng_aio_cancel(3)>>,

diff --git a/docs/man/nng_aio_abort.3.adoc b/docs/man/nng_aio_abort.3.adoc
@@ -47,6 +47,7 @@ None.
 
 == SEE ALSO
 
+[.text-left]
 <<nng_aio_alloc.3#,nng_aio_alloc(3)>>,
 <<nng_aio_cancel.3#,nng_aio_cancel(3)>>,
 <<nng_aio_result.3#,nng_aio_result(3)>>,

diff --git a/docs/man/nng_aio_alloc.3.adoc b/docs/man/nng_aio_alloc.3.adoc
@@ -57,10 +57,12 @@ This function returns 0 on success, and non-zero otherwise.
 
 == ERRORS
 
+[horizontal]
 `NNG_ENOMEM`:: Insufficient free memory to perform the operation.
 
 == SEE ALSO
 
+[.text-left]
 <<nng_aio_abort.3#,nng_aio_abort(3)>>,
 <<nng_aio_cancel.3#,nng_aio_cancel(3)>>,
 <<nng_aio_count.3#,nng_aio_count(3)>>,

diff --git a/docs/man/nng_aio_cancel.3.adoc b/docs/man/nng_aio_cancel.3.adoc
@@ -50,6 +50,7 @@ None.
 
 == SEE ALSO
 
+[.text-left]
 <<nng_aio_abort.3#,nng_aio_abort(3)>>,
 <<nng_aio_alloc.3#,nng_aio_alloc(3)>>,
 <<nng_aio_result.3#,nng_aio_result(3)>>,

diff --git a/docs/man/nng_aio_count.3.adoc b/docs/man/nng_aio_count.3.adoc
@@ -25,7 +25,7 @@ size_t nng_aio_count(nng_aio *aio);
 == DESCRIPTION
 
 The `nng_aio_count()` returns the number of bytes transferred by the
-asynchronous operation associated with the handle _aio_. 
+asynchronous operation associated with the handle _aio_.
 
 Some asynchronous operations do not provide meaningful data for this
 function; for example operations that establish connections do not
@@ -51,6 +51,7 @@ None.
 
 == SEE ALSO
 
+[.text-left]
 <<nng_aio_alloc.3#,nng_aio_alloc(3)>>,
 <<nng_aio_result.3#,nng_aio_result(3)>>,
 <<nng_aio_set_iov.3#,nng_aio_set_iov(3)>>,

diff --git a/docs/man/nng_aio_finish.3.adoc b/docs/man/nng_aio_finish.3.adoc
@@ -50,6 +50,7 @@ None.
 
 == SEE ALSO
 
+[.text-left]
 <<nng_aio_alloc.3#,nng_aio_alloc(3)>>,
 <<nng_aio_cancel.3#,nng_aio_cancel(3)>>,
 <<nng_aio_result.3#,nng_aio_result(3)>>,

diff --git a/docs/man/nng_aio_free.3.adoc b/docs/man/nng_aio_free.3.adoc
@@ -40,6 +40,7 @@ None.
 
 == SEE ALSO
 
+[.text-left]
 <<nng_aio_alloc.3#,nng_aio_alloc(3)>>,
 <<nng_aio_stop.3#,nng_aio_stop(3)>>,
 <<nng_aio.5#,nng_aio(5)>>,

diff --git a/docs/man/nng_aio_get_input.3.adoc b/docs/man/nng_aio_get_input.3.adoc
@@ -44,6 +44,7 @@ None.
 
 == SEE ALSO
 
+[.text-left]
 <<nng_aio_alloc.3#,nng_aio_alloc(3)>>,
 <<nng_aio_get_output.3#,nng_aio_get_output(3)>>,
 <<nng_aio_set_input.3#,nng_aio_set_input(3)>>,

diff --git a/docs/man/nng_aio_get_msg.3.adoc b/docs/man/nng_aio_get_msg.3.adoc
@@ -41,6 +41,7 @@ None.
 
 == SEE ALSO
 
+[.text-left]
 <<nng_aio_set_msg.3#,nng_aio_set_msg(3)>>,
 <<nng_recv_aio.3#,nng_recv_aio(3)>>,
 <<nng_aio.5#,nng_aio(5)>>,

diff --git a/docs/man/nng_aio_get_output.3.adoc b/docs/man/nng_aio_get_output.3.adoc
@@ -47,6 +47,7 @@ None.
 
 == SEE ALSO
 
+[.text-left]
 <<nng_aio_alloc.3#,nng_aio_alloc(3)>>,
 <<nng_aio_get_output.3#,nng_aio_get_output(3)>>,
 <<nng_aio_set_input.3#,nng_aio_set_input(3)>>,