docs: provide better man page references

When referring to another c-ares function use \fI function(3) \fP to let
the webpage rendering find and cross-link them appropriately.

SEE ALSO references should be ".BR name (3),", with a space before the
open parenthesis. This helps the manpage to HTML renderer.

Closes #565

docs/ares_dup.3

@@ -31,9 +31,9 @@ set the variable pointed to by \fIdest\fP to a handle used to identify the
 name service channel.  The caller should invoke \fIares_destroy(3)\fP on the
 handle when the channel is no longer needed.
 .SH SEE ALSO
-.BR ares_destroy(3),
-.BR ares_init(3),
-.BR ares_library_init(3)
+.BR ares_destroy (3),
+.BR ares_init (3),
+.BR ares_library_init (3)
 .SH AVAILABILITY
 \fIares_dup(3)\fP was added in c-ares 1.6.0
 .SH AUTHOR

docs/ares_expand_name.3

@@ -60,7 +60,8 @@ The encoded domain name was malformed and could not be expanded.
 .B ARES_ENOMEM
 Memory was exhausted.
 .SH SEE ALSO
-.BR ares_mkquery (3), ares_free_string (3)
+.BR ares_mkquery (3),
+.BR ares_free_string (3)
 .SH AUTHOR
 Greg Hudson, MIT Information Systems
 .br

docs/ares_free_data.3

@@ -27,53 +27,52 @@ void ares_free_data(void *\fIdataptr\fP)
 .fi
 .SH DESCRIPTION
 .PP
-The
-.B ares_free_data(3)
-function frees one or more data structures allocated and returned
-by several c-ares functions. Specifically the data returned by the
-following list of functions must be deallocated using this function.
+The \fBares_free_data(3)\fP function frees one or more data structures
+allocated and returned by several c-ares functions. Specifically the data
+returned by the following list of functions must be deallocated using this
+function.
 .TP 5
 .B ares_get_servers(3)
-When used to free the data returned by ares_get_servers(3) this
-will free the whole linked list of ares_addr_node structures returned
-by ares_get_servers(3).
+When used to free the data returned by \fIares_get_servers(3)\fP this will
+free the whole linked list of ares_addr_node structures returned by
+\fIares_get_servers(3)\fP.
 .TP
 .B ares_parse_srv_reply(3)
-When used to free the data returned by ares_parse_srv_reply(3) this
-will free the whole linked list of ares_srv_reply structures returned
-by ares_parse_srv_reply(3), along with any additional storage
-associated with those structures.
+When used to free the data returned by \fIares_parse_srv_reply(3)\fP this will
+free the whole linked list of ares_srv_reply structures returned by
+\fIares_parse_srv_reply(3)\fP, along with any additional storage associated
+with those structures.
 .TP
 .B ares_parse_mx_reply(3)
-When used to free the data returned by ares_parse_mx_reply(3) this
-will free the whole linked list of ares_mx_reply structures returned
-by ares_parse_mx_reply(3), along with any additional storage
-associated with those structures.
+When used to free the data returned by \fIares_parse_mx_reply(3)\fP this will
+free the whole linked list of ares_mx_reply structures returned by
+\fIares_parse_mx_reply(3)\fP, along with any additional storage associated
+with those structures.
 .TP
 .B ares_parse_txt_reply(3)
-When used to free the data returned by ares_parse_txt_reply(3) this
-will free the whole linked list of ares_txt_reply structures returned
-by ares_parse_txt_reply(3), along with any additional storage
-associated with those structures.
+When used to free the data returned by \fIares_parse_txt_reply(3)\fP this will
+free the whole linked list of ares_txt_reply structures returned by
+\fIares_parse_txt_reply(3)\fP, along with any additional storage associated
+with those structures.
 .TP
 .B ares_parse_soa_reply(3)
-When used to free the data returned by ares_parse_soa_reply(3) this
-will free the ares_soa_reply structure, along with any additional storage
+When used to free the data returned by \fIares_parse_soa_reply(3)\fP this will
+free the ares_soa_reply structure, along with any additional storage
 associated with those structure.
 .B ares_parse_uri_reply(3)
-When used to free the data returned by ares_parse_uri_reply(3) this
-will free list of ares_uri_reply structures, along with any additional
-storage associated with those structure.
+When used to free the data returned by \fIares_parse_uri_reply(3)\fP this will
+free list of ares_uri_reply structures, along with any additional storage
+associated with those structure.
 .SH RETURN VALUE
-The ares_free_data() function does not return a value.
+The \fIares_free_data(3)\fP function does not return a value.
 .SH AVAILABILITY
 This function was first introduced in c-ares version 1.7.0.
 .SH SEE ALSO
-.BR ares_get_servers(3),
-.BR ares_parse_srv_reply(3),
-.BR ares_parse_mx_reply(3),
-.BR ares_parse_txt_reply(3),
-.BR ares_parse_soa_reply(3)
+.BR ares_get_servers (3),
+.BR ares_parse_srv_reply (3),
+.BR ares_parse_mx_reply (3),
+.BR ares_parse_txt_reply (3),
+.BR ares_parse_soa_reply (3)
 .SH AUTHOR
 Yang Tse
 .PP

docs/ares_getaddrinfo.3

@@ -32,10 +32,8 @@ void ares_getaddrinfo(ares_channel \fIchannel\fP, const char *\fIname\fP,
                       ares_addrinfo_callback \fIcallback\fP, void *\fIarg\fP)
 .fi
 .SH DESCRIPTION
-The
-.B ares_getaddrinfo
-function initiates a host query by name on the name service channel
-identified by
+The \fBares_getaddrinfo(3)\fP function initiates a host query by name on the
+name service channel identified by
 .IR channel .
 The
 .I name
@@ -95,9 +93,7 @@ during a later call to \fIares_process(3)\fP, \fIares_destroy(3)\fP or
 .PP
 The callback argument
 .I arg
-is copied from the
-.B ares_getaddrinfo
-argument
+is copied from the \fBares_getaddrinfo(3)\fP argument
 .IR arg .
 The callback argument
 .I status
@@ -183,8 +179,7 @@ struct ares_addrinfo_cname {
 .EE
 .RE
 .PP
-The reserved memory has to be deleted by
-.B ares_freeaddrinfo.
+The reserved memory has to be deleted by \fBares_freeaddrinfo(3)\fP.
 
 The result is sorted according to RFC6724 except:
  - Rule 3 (Avoid deprecated addresses)

docs/ares_inet_ntop.3

@@ -40,8 +40,8 @@ the size of this buffer, which shall be large enough to hold the text string
 (INET_ADDRSTRLEN (16) characters for IPv4, INET6_ADDRSTRLEN (46) characters
 for IPv6).
 .SH SEE ALSO
-.BR ares_init(3),
-.BR ares_inet_pton(3)
+.BR ares_init (3),
+.BR ares_inet_pton (3)
 .SH AVAILABILITY
 made properly publicly available in c-ares for real in version 1.10.0
 .SH AUTHOR

docs/ares_inet_pton.3

@@ -36,8 +36,8 @@ in. The \fBdst\fP argument points to a buffer into which the function stores
 the numeric address; this shall be large enough to hold the numeric address
 (32 bits for AF_INET, 128 bits for AF_INET6).
 .SH SEE ALSO
-.BR ares_init(3),
-.BR ares_inet_ntop(3)
+.BR ares_init (3),
+.BR ares_inet_ntop (3)
 .SH AVAILABILITY
 made properly publicly available in c-ares for real in version 1.10.0
 .SH AUTHOR

docs/ares_init.3

@@ -70,11 +70,11 @@ please see the
 .BR resolv.conf (5)
 manual page.
 .SH SEE ALSO
-.BR ares_init_options(3),
-.BR ares_destroy(3),
-.BR ares_dup(3),
-.BR ares_library_init(3),
-.BR ares_set_servers(3)
+.BR ares_init_options (3),
+.BR ares_destroy (3),
+.BR ares_dup (3),
+.BR ares_library_init (3),
+.BR ares_set_servers (3)
 .SH AUTHOR
 Greg Hudson, MIT Information Systems
 .br

docs/ares_init_options.3

@@ -120,10 +120,9 @@ The default value is 53, the standard name service port.
 .B int \fInservers\fP;
 .br
 The list of IPv4 servers to contact, instead of the servers specified in
-resolv.conf or the local named. In order to allow specification of either
-IPv4 or IPv6 name servers, the
-.BR ares_set_servers(3)
-function must be used instead.
+resolv.conf or the local named. In order to allow specification of either IPv4
+or IPv6 name servers, the \Bares_set_servers(3)\fP function must be used
+instead.
 .TP 18
 .B ARES_OPT_DOMAINS
 .B char **\fIdomains\fP;
@@ -300,13 +299,13 @@ the last occurrence wins. For more information, please see the
 .BR resolv.conf (5)
 manual page.
 .SH SEE ALSO
-.BR ares_init(3),
-.BR ares_destroy(3),
-.BR ares_dup(3),
-.BR ares_library_init(3),
-.BR ares_save_options(3),
-.BR ares_set_servers(3),
-.BR ares_set_sortlist(3)
+.BR ares_init (3),
+.BR ares_destroy (3),
+.BR ares_dup (3),
+.BR ares_library_init (3),
+.BR ares_save_options (3),
+.BR ares_set_servers (3),
+.BR ares_set_sortlist (3)
 .SH AUTHOR
 Greg Hudson, MIT Information Systems
 .br

docs/ares_library_cleanup.3

@@ -63,11 +63,10 @@ the DllMain function. Doing so will produce deadlocks and other problems.
 This function was first introduced in c-ares version 1.7.0 along with the
 definition of preprocessor symbol \fICARES_HAVE_ARES_LIBRARY_CLEANUP\fP as an
 indication of the availability of this function. Reference counting in
-\fIares_library_init()\fP and \fIares_library_cleanup()\fP, which requires
+\fIares_library_init(3)\fP and \fIares_library_cleanup(3)\fP, which requires
 calls to the former function to match calls to the latter, is present since
-c-ares version 1.10.0.
-Earlier versions would deinitialize the library on the first call
-to \fIares_library_cleanup()\fP.
+c-ares version 1.10.0.  Earlier versions would deinitialize the library on the
+first call to \fIares_library_cleanup(3)\fP.
 .PP
 Since the introduction of this function, it is absolutely mandatory to call it
 for any Win32/64 program using c-ares.
@@ -76,8 +75,8 @@ Non-Win32/64 systems can still use c-ares version 1.7.0 without calling
 \fIares_library_cleanup(3)\fP due to the fact that \fIcurrently\fP it is nearly
 a do-nothing function on non-Win32/64 platforms.
 .SH SEE ALSO
-.BR ares_library_init(3),
-.BR ares_cancel(3)
+.BR ares_library_init (3),
+.BR ares_cancel (3)
 .SH AUTHOR
 Yang Tse
 .PP

docs/ares_library_init.3

@@ -87,18 +87,18 @@ as there are no currently dynamically loaded libraries.
 .B ARES_LIB_INIT_NONE
 Initialize nothing extra. This sets no bit.
 .SH RETURN VALUE
-Upon successful completion, ares_library_init() will return 0.  Otherwise, a
-non-zero error number will be returned to indicate the error. Except for
+Upon successful completion, \fIares_library_init(3)\fP returns 0.  Otherwise,
+a non-zero error number is returned to indicate the error. Except for
 \fIares_strerror(3)\fP, you shall not call any other c-ares function upon
 \fIares_library_init(3)\fP failure.
 .SH AVAILABILITY
 This function was first introduced in c-ares version 1.7.0 along with the
 definition of preprocessor symbol \fICARES_HAVE_ARES_LIBRARY_INIT\fP as an
-indication of the availability of this function. Its recursive behavior,
-which requires a matching number of calls to \fIares_library_cleanup()\fP
-in order to deinitialize the library, is present since c-ares version
-1.10.0. Earlier versions would deinitialize the library on the first call
-to \fIares_library_cleanup()\fP.
+indication of the availability of this function. Its recursive behavior, which
+requires a matching number of calls to \fIares_library_cleanup(3)\fP in order
+to deinitialize the library, is present since c-ares version 1.10.0. Earlier
+versions would deinitialize the library on the first call to
+\fIares_library_cleanup(3)\fP.
 .PP
 Since the introduction of this function it is absolutely mandatory to
 call it for any Win32/64 program using c-ares.
@@ -107,8 +107,8 @@ Non-Win32/64 systems can still use c-ares version 1.7.0 without calling
 \fIares_library_init(3)\fP due to the fact that \fIcurrently\fP it is nearly
 a do-nothing function on non-Win32/64 platforms at this point.
 .SH SEE ALSO
-.BR ares_library_cleanup(3),
-.BR ares_strerror(3)
+.BR ares_library_cleanup (3),
+.BR ares_strerror (3)
 .SH AUTHOR
 Yang Tse
 .PP

docs/ares_library_init_android.3

@@ -135,8 +135,8 @@ Context. It is assumed the JVM has aleady been registered through
 .SH AVAILABILITY
 This function was first introduced in c-ares version 1.15.0.
 .SH SEE ALSO
-.BR ares_library_init(3),
-.BR ares_library_cleanup(3),
+.BR ares_library_init (3),
+.BR ares_library_cleanup (3),
 .SH AUTHOR
 John Schember
 .PP

docs/ares_library_initialized.3

@@ -32,5 +32,5 @@ initialization is needed.
 .SH AVAILABILITY
 This function was first introduced in c-ares version 1.11.0
 .SH SEE ALSO
-.BR ares_library_init(3),
-.BR ares_library_cleanup(3)
+.BR ares_library_init (3),
+.BR ares_library_cleanup (3)

docs/ares_parse_mx_reply.3

@@ -40,7 +40,7 @@ memory and a pointer to it stored into the variable pointed to by
 It is the caller's responsibility to free the resulting
 .IR mx_out
 structure when it is no longer needed using the function
-.B ares_free_data
+\fBares_free_data(3)\fP.
 .PP
 The structure 
 .I ares_mx_reply

docs/ares_parse_naptr_reply.3

@@ -41,7 +41,7 @@ memory and a pointer to it stored into the variable pointed to by
 It is the caller's responsibility to free the resulting
 .IR naptr_out
 structure when it is no longer needed using the function
-.B ares_free_data
+\fBares_free_data(3)\fP.
 .PP
 The structure 
 .I ares_naptr_reply

docs/ares_parse_soa_reply.3

@@ -40,7 +40,7 @@ memory and a pointer to it stored into the variable pointed to by
 It is the caller's responsibility to free the resulting
 .IR soa_out
 structure when it is no longer needed using the function
-.B ares_free_data
+\fBares_free_data(3)\fP.
 .PP
 The structure 
 .I ares_soa_reply

docs/ares_parse_srv_reply.3

@@ -41,7 +41,7 @@ memory and a pointer to it stored into the variable pointed to by
 It is the caller's responsibility to free the resulting
 .IR srv_out
 structure when it is no longer needed using the function
-.B ares_free_data
+\fBares_free_data(3)\fP.
 .PP
 The structure 
 .I ares_srv_reply

docs/ares_parse_txt_reply.3

@@ -29,10 +29,9 @@ int ares_parse_txt_reply_ext(const unsigned char* \fIabuf\fP, int \fIalen\fP,
                              struct ares_txt_ext **\fItxt_out\fP);
 .fi
 .SH DESCRIPTION
-The
-.BR "ares_parse_txt_reply" " (" "ares_parse_txt_reply_ext" ")"
-function parses the response to a query of type TXT into a
-linked list (one element per sub-string) of
+The \fIares_parse_txt_reply(3)\fP and \fIares_parse_txt_reply_ext(3)\fP
+functions parse the response to a query of type TXT into a linked list (one
+element per sub-string) of
 .IR "struct ares_txt_reply" " (" "struct ares_txt_ext" ")"
 The parameters
 .I abuf
@@ -44,13 +43,11 @@ memory and a pointer to it stored into the variable pointed to by
 It is the caller's responsibility to free the resulting
 .IR txt_out
 structure when it is no longer needed using the function
-.B ares_free_data
-.PP
+\fBares_free_data(3)\fP.
+
 The structure 
 .I ares_txt_reply
 contains the following fields:
-.sp
-.in +4n
 .nf
 struct ares_txt_reply {
   struct ares_txt_reply  *next;
@@ -58,13 +55,10 @@ struct ares_txt_reply {
   unsigned char *txt;
 };
 .fi
-.in
-.PP
+
 The structure
 .I ares_txt_ext
 contains the following fields:
-.sp
-.in +4n
 .nf
 struct ares_txt_ext {
   struct ares_txt_ext  *next;
@@ -73,8 +67,6 @@ struct ares_txt_ext {
   unsigned char record_start;
 };
 .fi
-.in
-.PP
 The
 .I record_start
 field in
@@ -87,7 +79,7 @@ will have at least one item with
 equal to 1, and may have some items with
 .I record_start
 equal to 0 between them.
-.PP
+
 These sequences of
 .I struct ares_txt_ext
 (starting from the item with
@@ -95,7 +87,6 @@ These sequences of
 equal to 1, and ending right before the record start item) may be treated as
 either components of a single TXT record or as a multi-parted TXT record,
 depending on particular use case.
-.PP
 .SH RETURN VALUES
 .BR "ares_parse_txt_reply" " (" "ares_parse_txt_reply_ext" ")"
 can return any of the following values:

docs/ares_parse_uri_reply.3

@@ -26,10 +26,8 @@ int ares_parse_uri_reply(const unsigned char* \fIabuf\fP, int \fIalen\fP,
                          struct ares_uri_reply** \fIuri_out\fP);
 .fi
 .SH DESCRIPTION
-The
-.B ares_parse_uri_reply
-function parses the response to a query of type URI into a
-linked list of
+The \fIares_parse_uri_reply(3)\fP function parses the response to a query of
+type URI into a linked list of
 .I struct ares_uri_reply 
 The parameters
 .I abuf
@@ -41,13 +39,11 @@ memory and a pointer to it stored into the variable pointed to by
 It is the caller's responsibility to free the resulting
 .IR uri_out
 structure when it is no longer needed using the function
-.B ares_free_data
-.PP
+\fBares_free_data(3)\fP.
+
 The structure 
 .I ares_uri_reply
 contains the following fields:
-.sp
-.in +4n
 .nf
 struct ares_uri_reply {
     struct ares_uri_reply       *next;
@@ -57,8 +53,6 @@ struct ares_uri_reply {
     int                         ttl;
 };
 .fi
-.in
-.PP
 .SH RETURN VALUES
 .B ares_parse_uri_reply
 can return any of the following values:

docs/ares_set_servers.3

@@ -84,7 +84,7 @@ Changing name servers configuration while queries are outstanding is not impleme
 .BR ares_set_servers_csv (3),
 .BR ares_get_servers (3),
 .BR ares_init_options (3),
-.BR ares_dup(3)
+.BR ares_dup (3)
 .SH AVAILABILITY
 \fBares_set_servers(3)\fP was added in c-ares 1.7.1;
 \fBares_set_servers_ports(3)\fP was added in c-ares 1.11.0.

docs/ares_set_socket_callback.3

@@ -27,7 +27,8 @@ connected to the remote server. The callback must return ARES_SUCCESS if
 things are fine, or return -1 to signal an error. A returned error will
 abort the ares operation.
 .SH SEE ALSO
-.BR ares_init_options (3), ares_set_socket_configure_callback (3)
+.BR ares_init_options (3),
+.BR ares_set_socket_configure_callback (3)
 .SH AVAILABILITY
 ares_set_socket_callback(3) was added in c-ares 1.6.0
 .SH AUTHOR

docs/ares_set_socket_configure_callback.3

@@ -25,7 +25,8 @@ to configure various socket options.  The callback must return ARES_SUCCESS
 if things are fine, or return -1 to signal an error. A returned error will
 abort the ares operation.
 .SH SEE ALSO
-.BR ares_init_options (3), ares_set_socket_callback (3)
+.BR ares_init_options (3),
+.BR ares_set_socket_callback (3)
 .SH AVAILABILITY
 ares_set_socket_configure_callback(3) was added in c-ares 1.11.0
 .SH AUTHOR

docs/ares_set_socket_functions.3

@@ -90,12 +90,12 @@ and must thus remain valid through out the channels and any created socket's lif
 Added in c-ares 1.13.0
 .SH SEE ALSO
 .BR ares_init_options (3),
-.BR socket(2),
-.BR close(2),
-.BR connect(2),
-.BR recv(2),
-.BR recvfrom(2),
-.BR send(2),
-.BR writev(2)
+.BR socket (2),
+.BR close (2),
+.BR connect (2),
+.BR recv (2),
+.BR recvfrom (2),
+.BR send (2),
+.BR writev (2)
 .SH AUTHOR
 Carl Wilund

docs/ares_set_sortlist.3

@@ -56,6 +56,6 @@ was invalid.
 c-ares library initialization not yet performed.
 .SH SEE ALSO
 .BR ares_init_options (3),
-.BR ares_dup(3)
+.BR ares_dup (3)
 .SH AVAILABILITY
 ares_set_sortlist(3) was added in c-ares 1.11.0