Various minor neatenings to manpage formatting

14 files changed, 22 insertions, 27 deletions

diff --git a/termkey_advisereadable.3 b/termkey_advisereadable.3
index ee434f6..8b4b6af 100644
--- a/termkey_advisereadable.3
+++ b/termkey_advisereadable.3
@@ -10,7 +10,7 @@ termkey_advisereadable \- read more bytes from the underlying terminal
 .sp
 Link with \fI-ltermkey\fP.
 .SH DESCRIPTION
-\fBtermkey_advisereadable\fP informs the instance that new input may be available on the underlying file descriptor and so it should call \fBread\fP(2) to obtain it. If at least one more byte was read it will return \fBTERMKEY_RES_AGAIN\fP to indicate it may be useful to call \fBtermkey_getkey\fP(3) again. If no more input was read then \fBTERMKEY_RES_NONE\fP is returned.
+\fBtermkey_advisereadable\fP() informs the instance that new input may be available on the underlying file descriptor and so it should call \fBread\fP(2) to obtain it. If at least one more byte was read it will return \fBTERMKEY_RES_AGAIN\fP to indicate it may be useful to call \fBtermkey_getkey\fP(3) again. If no more input was read then \fBTERMKEY_RES_NONE\fP is returned.
 .PP
 This function, along with \fBtermkey_getkey\fP(3) make it possible to use the termkey instance in an asynchronous program.
 .PP
diff --git a/termkey_get_fd.3 b/termkey_get_fd.3
index 5e648d6..733f820 100644
--- a/termkey_get_fd.3
+++ b/termkey_get_fd.3
@@ -10,7 +10,7 @@ termkey_get_fd \- obtain the file descriptor for the terminal
 .sp
 Link with \fI-ltermkey\fP.
 .SH DESCRIPTION
-\fBtermkey_get_fd\fP returns the file descriptor that was passed as the \fIfd\fP argument to \fBtermkey_new\fP(3).
+\fBtermkey_get_fd\fP() returns the file descriptor that was passed as the \fIfd\fP argument to \fBtermkey_new\fP(3).
 .SH "RETURN VALUE"
 \fBtermkey_get_fd\fP() returns the current file descriptor.
 .SH "SEE ALSO"
diff --git a/termkey_get_keyname.3 b/termkey_get_keyname.3
index a55d218..5f0119f 100644
--- a/termkey_get_keyname.3
+++ b/termkey_get_keyname.3
@@ -10,7 +10,7 @@ termkey_get_keyname \- return a string name for a symbolic key
 .sp
 Link with \fI-ltermkey\fP.
 .SH DESCRIPTION
-\fBtermkey_get_keyname\fP returns a human-readable string name for the symbolic key value given by \fBsym\fP. The returned string is owned by the termkey instance \fItk\fP so should not be modified or freed. The returned pointer is guaranteed to be valid until the termkey instance is released using \fBtermkey_destroy\fP(3). This function is the inverse of \fBtermkey_keyname2sym\fP(3).
+\fBtermkey_get_keyname\fP() returns a human-readable string name for the symbolic key value given by \fBsym\fP. The returned string is owned by the termkey instance \fItk\fP so should not be modified or freed. The returned pointer is guaranteed to be valid until the termkey instance is released using \fBtermkey_destroy\fP(3). This function is the inverse of \fBtermkey_keyname2sym\fP(3).
 .SH "RETURN VALUE"
 \fBtermkey_get_key\fP() returns a pointer to a string.
 .SH "SEE ALSO"
diff --git a/termkey_getkey.3.sh b/termkey_getkey.3.sh
index a940906..ffc6d0e 100644
--- a/termkey_getkey.3.sh
+++ b/termkey_getkey.3.sh
@@ -8,20 +8,19 @@ termkey_getkey, termkey_getkey_force \- retrieve the next key event
 .B #include <termkey.h>
 .sp
 .BI "TermKeyResult termkey_getkey(TermKey *" tk ", TermKeyKey *" key );
-.br
 .BI "TermKeyResult termkey_getkey_force(TermKey *" tk ", TermKeyKey *" key );
 .fi
 .sp
 Link with \fI-ltermkey\fP.
 .SH DESCRIPTION
-\fBtermkey_getkey\fP attempts to retrieve a single keypress event from the buffer, and put it in the structure referred to by \fIkey\fP. It returns one of the following values:
+\fBtermkey_getkey\fP() attempts to retrieve a single keypress event from the buffer, and put it in the structure referred to by \fIkey\fP. It returns one of the following values:
 .in
 .TP
 .B TERMKEY_RES_KEY
 a complete keypress was removed from the buffer, and has been placed in the \fIkey\fP structure.
 .TP
 .B TERMKEY_RES_AGAIN
-a partial keypress event was found in the buffer, but it does not yet contain all the bytes required. An indication of what \fBtermkey_getkey_force(3)\fP would return has been placed in the \fIKey\fP structure.
+a partial keypress event was found in the buffer, but it does not yet contain all the bytes required. An indication of what \fBtermkey_getkey_force\fP(3) would return has been placed in the \fIkey\fP structure.
 .TP
 .B TERMKEY_RES_NONE
 no bytes are waiting in the buffer.
@@ -29,7 +28,7 @@ no bytes are waiting in the buffer.
 .B TERMKEY_RES_EOF
  no bytes are ready and the input stream is now closed.
 .PP
-\fBtermkey_getkey_force\fP is similar to \fBtermkey_getkey\fP but will not return \fBTERMKEY_RES_AGAIN\fP if a partial match is found. Instead, it will force an interpretation of the bytes, even if this means interpreting the start of an Escape-prefixed multi-byte sequence as a literal "Escape" key followed by normal letters.
+\fBtermkey_getkey_force\fP() is similar to \fBtermkey_getkey\fP() but will not return \fBTERMKEY_RES_AGAIN\fP if a partial match is found. Instead, it will force an interpretation of the bytes, even if this means interpreting the start of an Escape-prefixed multi-byte sequence as a literal "Escape" key followed by normal letters.
 .PP
 Neither of these functions will block or perform any IO operations on the underlying filehandle. To use the instance in an asynchronous program, see \fBtermkey_advisereadable\fP(3). For a blocking call suitable for use in a synchronous program, use \fBtermkey_waitkey\fP(3) instead of \fBtermkey_getkey\fP().
 .PP
diff --git a/termkey_interpret_mouse.3 b/termkey_interpret_mouse.3
index 50f3353..6963054 100644
--- a/termkey_interpret_mouse.3
+++ b/termkey_interpret_mouse.3
@@ -11,7 +11,7 @@ termkey_interpret_mouse \- interpret opaque mouse event data
 .sp
 Link with \fI-ltermkey\fP.
 .SH DESCRIPTION
-\fBtermkey_interpret_mouse\fP fills in variables in the passed pointers according to the mouse event found in \fIkey\fP. It should be called if \fBtermkey_getkey(3)\fP or similar have returned a key event with the type of \fBTERMKEY_TYPE_MOUSE\fP.
+\fBtermkey_interpret_mouse\fP() fills in variables in the passed pointers according to the mouse event found in \fIkey\fP. It should be called if \fBtermkey_getkey\fP(3) or similar have returned a key event with the type of \fBTERMKEY_TYPE_MOUSE\fP.
 .PP
 Any pointer may instead be given as \fBNULL\fP to not return that value.
 .PP
diff --git a/termkey_keycmp.3 b/termkey_keycmp.3
index 519752b..bd0fb26 100644
--- a/termkey_keycmp.3
+++ b/termkey_keycmp.3
@@ -11,7 +11,7 @@ termkey_keycmp \- compare two key events
 .sp
 Link with \fI-ltermkey\fP.
 .SH DESCRIPTION
-\fBtermkey_keycmp\fP compares two key structures and applies a total ordering, returning a value that is positive, zero, or negative, to indicate if the given structures are increasing, identical, or decreasing.
+\fBtermkey_keycmp\fP() compares two key structures and applies a total ordering, returning a value that is positive, zero, or negative, to indicate if the given structures are increasing, identical, or decreasing.
 .PP
 Two structures of differing type are ordered \fBTERMKEY_TYPE_UNICODE\fP, \fBTERMKEY_TYPE_KEYSYM\fP, \fBTERMKEY_TYPE_FUNCTION\fP, \fBTERMKEY_TYPE_MOUSE\fP. Unicode structures are ordered by codepoint, keysym structures are ordered by keysym number, function structures are ordered by function key number, and mouse structures are ordered opaquely by an unspecified but consistent ordering. Within these values, keys different in modifier bits are ordered by the modifiers.
 .SH "RETURN VALUE"
diff --git a/termkey_keyname2sym.3 b/termkey_keyname2sym.3
index c9224bc..095a465 100644
--- a/termkey_keyname2sym.3
+++ b/termkey_keyname2sym.3
@@ -10,7 +10,7 @@ termkey_keyname2sym \- look up a symbolic key value for a string name
 .sp
 Link with \fI-ltermkey\fP.
 .SH DESCRIPTION
-\fBtermkey_keyname2sym\fP looks up the symbolic key value represented by the given string name. This is a case-sensitive comparison. If the given name is not found, \fBTERMKEY_SYM_UNKNOWN\fP is returned instead. This function is the inverse of \fBtermkey_get_keyname\fP(3), and is a more specific form of \fBtermkey_lookup_keyname\fP(3) which only recognises names as complete strings.
+\fBtermkey_keyname2sym\fP() looks up the symbolic key value represented by the given string name. This is a case-sensitive comparison. If the given name is not found, \fBTERMKEY_SYM_UNKNOWN\fP is returned instead. This function is the inverse of \fBtermkey_get_keyname\fP(3), and is a more specific form of \fBtermkey_lookup_keyname\fP(3) which only recognises names as complete strings.
 .PP
 Because the key names are stored in an array indexed by the symbol number, this function has to perform a linear search of the names. Use of this function should be restricted to converting key names into symbolic values during a program's initialisation, so that efficient comparisons can be done while it is running.
 .SH "RETURN VALUE"
diff --git a/termkey_lookup_keyname.3 b/termkey_lookup_keyname.3
index 4d763ff..bd44411 100644
--- a/termkey_lookup_keyname.3
+++ b/termkey_lookup_keyname.3
@@ -11,7 +11,7 @@ termkey_lookup_keyname \- look up a symbolic key value for a string name
 .sp
 Link with \fI-ltermkey\fP.
 .SH DESCRIPTION
-\fBtermkey_lookup_keyname\fP looks up the symbolic key value represented by the given string name. This is a case-sensitive comparison. The symbolic value is written to the variable addressed by \fIsym\fP. This function is a more general form of \fBtermkey_keyname2sym\fP(3) because it can recognise a symbolic key name within a longer string, returning a pointer to the remainder of the input after the key name.
+\fBtermkey_lookup_keyname\fP() looks up the symbolic key value represented by the given string name. This is a case-sensitive comparison. The symbolic value is written to the variable addressed by \fIsym\fP. This function is a more general form of \fBtermkey_keyname2sym\fP(3) because it can recognise a symbolic key name within a longer string, returning a pointer to the remainder of the input after the key name.
 .PP
 Because the key names are stored in an array indexed by the symbol number, this function has to perform a linear search of the names. Use of this function should be restricted to converting key names into symbolic values during a program's initialisation, so that efficient comparisons can be done while it is running.
 .SH "RETURN VALUE"
diff --git a/termkey_new.3 b/termkey_new.3
index 38e23b8..3cb24ce 100644
--- a/termkey_new.3
+++ b/termkey_new.3
@@ -6,15 +6,13 @@ termkey_new, termkey_destroy \- create or destroy new termkey instance
 .B #include <termkey.h>
 .sp
 .BI "TERMKEY_CHECK_VERSION;"
-.br
 .BI "TermKey *termkey_new(int " fd ", int " flags );
-.br
 .BI "void termkey_destroy(TermKey *" tk );
 .fi
 .sp
 Link with \fI\-ltermkey\fP.
 .SH DESCRIPTION
-\fBtermkey_new\fP() creates a new termkey instance connected to the file handle opened by \fIfd\fP using the \fIflags\fP. The \fBTermKey\fP structure should be considered opaque; its contents are not intended for use outside of the library.
+\fBtermkey_new\fP() creates a new termkey instance connected to the file handle opened by \fIfd\fP using the \fIflags\fP. The \fITermKey\fP structure should be considered opaque; its contents are not intended for use outside of the library.
 .PP
 \fBtermkey_destroy\fP() destroys the given instance and releases any resources controlled by it. It will not close the underlying filehandle given as the \fIfd\fP argument to \fBtermkey_new\fP().
 .PP
@@ -37,7 +35,7 @@ Ignore locale settings; force UTF-8 recombining on. This flag overrides \fBTERMK
 .B TERMKEY_FLAG_NOTERMIOS
 Even if the terminal file descriptor \fIfd\fP represents a
 .SM TTY
-device, do not call the \fBtcsetattr\fP() \fBtermios\fP function on it to set it to canonical input mode.
+device, do not call the \fBtcsetattr\fP(3) \fBtermios\fP function on it to set it to canonical input mode.
 .TP
 .B TERMKEY_FLAG_SPACESYMBOL
 Report space as being a symbolic key rather than a Unicode codepoint.
@@ -45,7 +43,7 @@ Report space as being a symbolic key rather than a Unicode codepoint.
 .B TERMKEY_FLAG_CTRLC
 Disable the \fBSIGINT\fP behaviour of \fICtrl-C\fP. If this flag is provided, then \fICtrl-C\fP will be available as a normal keypress, rather than sending the process group a \fBSIGINT\fP. This flag only takes effect without \fBTERMKEY_FLAG_NOTERMIOS\fP; with it, none of the signal keys are disabled anyway.
 .PP
-When the constructor is invoked, it attempts to detect if the current locale is UTF-8 aware or not, and sets either the \fBTERMKEY_FLAG_UTF8\fP or \fBTERMKEY_FLAG_RAW\fP flag. One of these two bits will always be in effect. The current flags in effect can be obtained by \fBtermkey_get_flags\fP().
+When the constructor is invoked, it attempts to detect if the current locale is UTF-8 aware or not, and sets either the \fBTERMKEY_FLAG_UTF8\fP or \fBTERMKEY_FLAG_RAW\fP flag. One of these two bits will always be in effect. The current flags in effect can be obtained by \fBtermkey_get_flags\fP(3).
 .SH VERSION CHECK MACRO
 Before calling any functions in the \fItermkey\fP library, an application should use the \fBTERMKEY_CHECK_VERSION\fP macro to check that the loaded version of the library is compatible with the version it was compiled against. This should be done early on, ideally just after entering its \fBmain()\fP function.
 .SH "RETURN VALUE"
diff --git a/termkey_set_flags.3 b/termkey_set_flags.3
index c6f47a6..1d8f4e8 100644
--- a/termkey_set_flags.3
+++ b/termkey_set_flags.3
@@ -6,18 +6,17 @@ termkey_set_flags, termkey_get_flags \- control the operational flags
 .B #include <termkey.h>
 .sp
 .BI "void termkey_set_flags(TermKey *" tk ", int " newflags );
-.br
 .BI "int termkey_get_flags(TermKey *" tk );
 .fi
 .sp
 Link with \fI-ltermkey\fP.
 .SH DESCRIPTION
-\fBtermkey_set_flags\fP changes the set of operation flags in the termkey instance to those given by \fInewflags\fP.
+\fBtermkey_set_flags\fP() changes the set of operation flags in the termkey instance to those given by \fInewflags\fP.
 .PP
-\fBtermkey_get_flags\fP returns the value set by the last call to \fBtermkey_set_flags\fP(), or the value given to the constructor.
+\fBtermkey_get_flags\fP() returns the value set by the last call to \fBtermkey_set_flags\fP(), or the value given to the constructor.
 .PP
 When the constructor is invoked, it attempts to detect if the current locale is UTF-8 aware or not, and sets either the \fBTERMKEY_FLAG_UTF8\fP or \fBTERMKEY_FLAG_RAW\fP flag. One of these two bits will always be returned by \fBtermkey_get_flags\fP().
 .SH "RETURN VALUE"
 \fBtermkey_set_flags\fP() returns no value. \fBtermkey_get_flags\fP() returns the current operational flags.
 .SH "SEE ALSO"
-.BR termkey_new (3),
+.BR termkey_new (3)
diff --git a/termkey_set_waittime.3 b/termkey_set_waittime.3
index da2d013..67aa6ad 100644
--- a/termkey_set_waittime.3
+++ b/termkey_set_waittime.3
@@ -6,15 +6,14 @@ termkey_set_waittime, termkey_get_waittime \- control the wait time for multibyt
 .B #include <termkey.h>
 .sp
 .BI "void termkey_set_waittime(TermKey *" tk ", int " msec );
-.br
 .BI "int termkey_get_waittime(TermKey *" tk );
 .fi
 .sp
 Link with \fI-ltermkey\fP.
 .SH DESCRIPTION
-\fBtermkey_set_waittime\fP sets the number of miliseconds that \fBtermkey_wait\fP(3) will wait for the remaining bytes of a multibyte sequence if it detects the start of a partially-complete one.
+\fBtermkey_set_waittime\fP() sets the number of miliseconds that \fBtermkey_wait\fP(3) will wait for the remaining bytes of a multibyte sequence if it detects the start of a partially-complete one.
 .PP
-\fBtermkey_get_waittime\fP returns the value set by the last call to \fBtermkey_set_waittime\fP(), or the default value if a different has not been set.
+\fBtermkey_get_waittime\fP() returns the value set by the last call to \fBtermkey_set_waittime\fP(), or the default value if a different has not been set.
 .SH "RETURN VALUE"
 \fBtermkey_set_waittime\fP() returns no value. \fBtermkey_get_waittime\fP() returns the current wait time in miliseconds.
 .SH "SEE ALSO"
diff --git a/termkey_strfkey.3 b/termkey_strfkey.3
index 10c29b4..7767952 100644
--- a/termkey_strfkey.3
+++ b/termkey_strfkey.3
@@ -11,7 +11,7 @@ termkey_strfkey \- format a string representing a key event
 .sp
 Link with \fI-ltermkey\fP.
 .SH DESCRIPTION
-\fBtermkey_strfkey\fP formats a string buffer to contain a human-readable representation of a key event. It fills the \fIbuffer\fP in a way analogous to the \fBsnprintf\fP(3) or \fBstrftime\fP(3) standard library functions. This function used to be called \fBtermkey_snprint_key\fP but was renamed after version 0.6.
+\fBtermkey_strfkey\fP() formats a string buffer to contain a human-readable representation of a key event. It fills the \fIbuffer\fP in a way analogous to the \fBsnprintf\fP(3) or \fBstrftime\fP(3) standard library functions. This function used to be called \fBtermkey_snprint_key\fP() but was renamed after version 0.6.
 .PP
 The \fIformat\fP argument specifies the format of the output, as a bitmask of the following constants:
 .TP
diff --git a/termkey_strpkey.3 b/termkey_strpkey.3
index e8544f9..5d51ccf 100644
--- a/termkey_strpkey.3
+++ b/termkey_strpkey.3
@@ -11,7 +11,7 @@ termkey_strpkey \- parse a string representing a key event
 .sp
 Link with \fI-ltermkey\fP.
 .SH DESCRIPTION
-\fBtermkey_strpkey\fP parses a string buffer containing a human-readable representation of a key event. It fills the \fIkey\fP structure from the results of this parsing, similar to the \fBstrptime\fP(3) standard library function.
+\fBtermkey_strpkey\fP(3) parses a string buffer containing a human-readable representation of a key event. It fills the \fIkey\fP structure from the results of this parsing, similar to the \fBstrptime\fP(3) standard library function.
 .PP
 The \fIformat\fP argument specifies the format expected in the string, as a bitmask of the following constants:
 .TP
diff --git a/termkey_waitkey.3.sh b/termkey_waitkey.3.sh
index 812bb1d..54c532e 100644
--- a/termkey_waitkey.3.sh
+++ b/termkey_waitkey.3.sh
@@ -12,9 +12,9 @@ termkey_waitkey \- wait for and retrieve the next key event
 .sp
 Link with \fI-ltermkey\fP.
 .SH DESCRIPTION
-\fBtermkey_waitkey\fP attempts to retrieve a single keypress event from the buffer, and put it in the structure referred to by \fIkey\fP. If successful it will return \fBTERMKEY_RES_KEY\fP to indicate that the structure now contains a new keypress event. If nothing is in the buffer it will block until one is available. If no events are ready and the input stream is now closed, will return \fBTERMKEY_RES_EOF\fP.
+\fBtermkey_waitkey\fP(3) attempts to retrieve a single keypress event from the buffer, and put it in the structure referred to by \fIkey\fP. If successful it will return \fBTERMKEY_RES_KEY\fP to indicate that the structure now contains a new keypress event. If nothing is in the buffer it will block until one is available. If no events are ready and the input stream is now closed, will return \fBTERMKEY_RES_EOF\fP.
 .PP
-For details of the \fBTermKeyKey\fP structure, see \fBtermkey_getkey\fP(3).
+For details of the \fITermKeyKey\fP structure, see \fBtermkey_getkey\fP(3).
 .PP
 Some keypresses generate multiple bytes from the terminal. Because there may be network or other delays between the terminal and an application using termkey, \fBtermkey_waitkey\fP() will attempt to wait for the remaining bytes to arrive if it detects the start of a multibyte sequence. If no more bytes arrive within a certain time, then the bytes will be reported as they stand, even if this results in interpreting a partially-complete Escape sequence as a literal Escape key followed by some normal letters or other symbols. The amount of time to wait can be set by \fBtermkey_set_waittime\fP(3).
 .SH "RETURN VALUE"