Many small manpage markup fixes

This commit is contained in:
Paul LeoNerd Evans 2012-04-25 00:59:13 +01:00
parent cd57c39191
commit af3c0bf378
6 changed files with 43 additions and 21 deletions

View File

@ -2,7 +2,9 @@
.SH NAME
termkey \- terminal keypress reading library
.SH DESCRIPTION
\fBtermkey\fP is a library that allows programs to read and interpret keypress and other events from a terminal. It understands encoding schemes used by terminals to encode keypresses, and UTF-8, allowing it to return events representing key events.
\fBtermkey\fP is a library that allows programs to read and interpret keypress and other events from a terminal. It understands encoding schemes used by terminals to encode keypresses, and
.SM UTF-8 ,
allowing it to return events representing key events.
.PP
\fBtermkey\fP operates in a pseudo object-oriented fashion. It provides one function, \fBtermkey_new\fP(3), that returns a pointer to a newly-allocated structure. All other functions take this pointer as their first argument. A typical use of this library would consist of a call to \fBtermkey_new\fP() to construct a new instance to represent the \fIstdin\fP stream, then use the \fBtermkey_waitkey\fP(3) function to wait for and interpret key press events. The \fBtermkey_destroy\fP(3) function can be used to deallocate resources used by the instance if the program has finished using it.
.SS Reading Events
@ -66,7 +68,7 @@ Details of the behaviour of a \fBtermkey\fP instance are controlled by two bitma
The following control flags are recognised.
.TP
.B TERMKEY_FLAG_NOINTERPRET
Do not attempt to interpret \fBC0\fP codes into keysyms. Instead report them as plain "Ctrl-letter" events.
Do not attempt to interpret \fIC0\fP codes into keysyms. Instead report them as plain \fICtrl-letter\fP events.
.TP
.B TERMKEY_FLAG_CONVERTKP
Convert xterm's alternative keypad symbols into the plain
@ -74,10 +76,14 @@ Convert xterm's alternative keypad symbols into the plain
codes they would represent.
.TP
.B TERMKEY_FLAG_RAW
Ignore locale settings; do not attempt to recombine UTF-8 sequences. Instead report only raw values.
Ignore locale settings; do not attempt to recombine
.SM UTF-8
sequences. Instead report only raw values.
.TP
.B TERMKEY_FLAG_UTF8
Ignore locale settings; force UTF-8 recombining on. This flag overrides \fBTERMKEY_FLAG_RAW\fP.
Ignore locale settings; force
.SM UTF-8
recombining on. This flag overrides \fBTERMKEY_FLAG_RAW\fP.
.TP
.B TERMKEY_FLAG_NOTERMIOS
Even if the terminal file descriptor \fIfd\fP represents a
@ -96,20 +102,34 @@ Without this flag, IO operations are retried when interrupted by a signal (\fBEI
The following canonicalisation flags are recognised.
.TP
.B TERMKEY_CANON_SPACESYMBOL
If this flag is set then a Unicode space character is represented using the \fBTERMKEY_SYM_SPACE\fP symbol. If this flag is not set, it is represented by the U+0020 Unicode codepoint.
If this flag is set then a Unicode space character is represented using the \fBTERMKEY_SYM_SPACE\fP symbol. If this flag is not set, it is represented by the \f(CWU+0020\fP Unicode codepoint.
.TP
.B TERMKEY_CANON_DELBS
If this flag is set then an ASCII DEL character is represented by the \fBTERMKEY_SYM_BACKSPACE\fP symbol. If not, it is represented by \fBTERMKEY_SYM_DEL\fP. An ASCII BS character is always represented by \fBTERMKEY_SYM_BACKSPACE\fP, regardless of this flag.
If this flag is set then an
.SM ASCII
.SM DEL
character is represented by the \fBTERMKEY_SYM_BACKSPACE\fP symbol. If not, it is represented by \fBTERMKEY_SYM_DEL\fP. An
.SM ASCII
.SM BS
character is always represented by \fBTERMKEY_SYM_BACKSPACE\fP, regardless of this flag.
.SS Multi-byte Events
Special keys, mouse events, and UTF-8 encoded Unicode text, are all represented by more than one byte. If the start of a multi-byte sequence is seen by \fBtermkey_waitkey\fP() it will wait a short time to see if the remainder of the sequence arrives. If the sequence remains unfinished after this timeout, it will be returned in its incomplete state. Partial escape sequences are returned as an Escape key (\fBTERMKEY_SYM_ESCAPE\fP) followed by the text contained in the sequence. Partial UTF-8 sequences are returned as the Unicode replacement character, U+FFFD.
Special keys, mouse events, and
.SM UTF-8
encoded Unicode text, are all represented by more than one byte. If the start of a multi-byte sequence is seen by \fBtermkey_waitkey\fP() it will wait a short time to see if the remainder of the sequence arrives. If the sequence remains unfinished after this timeout, it will be returned in its incomplete state. Partial escape sequences are returned as an Escape key (\fBTERMKEY_SYM_ESCAPE\fP) followed by the text contained in the sequence. Partial
.SM UTF-8
sequences are returned as the Unicode replacement character, \f(CWU+FFFD\fP.
.PP
The amount of time that the \fBtermkey\fP instance will wait is set by \fBtermkey_set_waittime\fP(3), and is returned by \fBtermkey_get_waittime\fP(3). Initially it will be set to 50 miliseconds.
.SS Mouse Events
The \fBTERMKEY_TYPE_MOUSE\fP event type indicates a mouse event. The \fIcode\fP field of the event structure should be considered opaque, though \fImodifiers\fP will be valid. In order to obtain the details of the mouse event, call \fBtermkey_interpret_mouse\fP(3) passing the event structure and pointers to integers to store the result in.
.PP
\fBtermkey\fP recognises three mouse protocols: the original X10 protocol (\f(CWCSI M\fP followed by three bytes), SGR encoding (\f(CWCSI < ... M\fP, as requested by \f(CWCSI ? 1006 h\fP), and rxvt encoding (\f(CWCSI ... M\fP, as requested by \f(CWCSI ? 1015 h\fP). Which encoding is in use is inferred automatically by \fBtermkey\fP, and does not need to be specified explicitly.
\fBtermkey\fP recognises three mouse protocols: the original
.SM X10
protocol (\f(CWCSI M\fP followed by three bytes),
.SM SGR
encoding (\f(CWCSI < ... M\fP, as requested by \f(CWCSI ? 1006 h\fP), and rxvt encoding (\f(CWCSI ... M\fP, as requested by \f(CWCSI ? 1015 h\fP). Which encoding is in use is inferred automatically by \fBtermkey\fP, and does not need to be specified explicitly.
.SS Position Events
The \fBTERMKEY_TYPE_POSITION\fP event type indicates a cursor position report. This is typically sent by a terminal in response to the Report Cursor Position command (\f(CWCSI 6n\fP). The event bytes are opaque, but can be obtained by calling \fBtermkey_interpret_position\fP(3) passing the event structure and pointers to integers to store the result in.
The \fBTERMKEY_TYPE_POSITION\fP event type indicates a cursor position report. This is typically sent by a terminal in response to the Report Cursor Position command (\f(CWCSI 6 n\fP). The event bytes are opaque, but can be obtained by calling \fBtermkey_interpret_position\fP(3) passing the event structure and pointers to integers to store the result in.
.SH "SEE ALSO"
.BR termkey_new (3),
.BR termkey_waitkey (3),

View File

@ -31,7 +31,7 @@ no bytes are waiting in the buffer.
.B TERMKEY_RES_ERROR
called with terminal IO stopped, due to \fBtermkey_stop\fP(3). In this case \fIerrno\fP will be set to \fBEINVAL\fP.
.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 \fIEscape\fP 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(). For providing input without a readable filehandle, use \fBtermkey_push_bytes\fP(3).
.PP
@ -39,7 +39,7 @@ Before returning, this function canonicalises the \fIkey\fP structure according
.SH "RETURN VALUE"
\fBtermkey_getkey\fP() returns an enumeration of one of \fBTERMKEY_RES_KEY\fP, \fBTEMRKEY_RES_AGAIN\fP, \fBTERMKEY_RES_NONE\fP, \fBTERMKEY_RES_EOF\fP or \fBTERMKEY_RES_ERROR\fP. \fBtermkey_getkey_force\fP() returns one of the above, except for \fBTERMKEY_RES_AGAIN\fP.
.SH EXAMPLE
The following example program prints details of every keypress until the user presses "Ctrl-C". It demonstrates how to use the \fBtermkey\fP instance in a typical \fBpoll\fP(2)-driven asynchronous program, which may include mixed IO with other file handles.
The following example program prints details of every keypress until the user presses \fICtrl-C\fP. It demonstrates how to use the \fBtermkey\fP instance in a typical \fBpoll\fP(2)-driven asynchronous program, which may include mixed IO with other file handles.
.PP
.in +4n
.nf

View File

@ -19,7 +19,9 @@ Link with \fI\-ltermkey\fP.
.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
The constructor 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).
The constructor attempts to detect if the current locale is
.SM 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).
.PP
If a file handle is provided, the terminfo driver may send a string to initialise or set the state of the terminal before \fBtermkey_new\fP() returns. This will not be done if no file handle is provided, or if the file handle is a pipe (\fBS_ISFIFO\fP()). In this case it will be the caller's responsibility to ensure the terminal is in the correct mode. Once initialised, the terminal can be stopped by \fBtermkey_stop\fP(3), and started again by \fBtermkey_start\fP(3).
.SH VERSION CHECK MACRO

View File

@ -16,19 +16,19 @@ Link with \fI-ltermkey\fP.
The \fIformat\fP argument specifies the format of the output, as a bitmask of the following constants:
.TP
.B TERMKEY_FORMAT_LONGMOD
Print full modifier names e.g. "Shift-" instead of abbreviating to "S-".
Print full modifier names e.g. "\f(CWShift-\fP" instead of abbreviating to "\f(CWS-\fP".
.TP
.B TERMKEY_FORMAT_CARETCTRL
If the only modifier is \fBTERMKEY_MOD_CTRL\fP on a plain letter, render it as "^X" rather than "Ctrl-X".
If the only modifier is \fBTERMKEY_MOD_CTRL\fP on a plain letter, render it as "\f(CW^X\fP" rather than "\f(CWCtrl-X\fP".
.TP
.B TERMKEY_FORMAT_ALTISMETA
Use the name "Meta" or the letter "M" instead of "Alt" or "A".
Use the name "\f(CWMeta\fP" or the letter "\f(CWM\fP" instead of "\f(CWAlt\fP" or "\f(CWA\fP".
.TP
.B TERMKEY_FORMAT_WRAPBRACKET
If the key event is a special key instead of unmodified Unicode, wrap it in "<brackets>".
If the key event is a special key instead of unmodified Unicode, wrap it in "\f(CW<brackets>\fP".
.TP
.B TERMKEY_FORMAT_MOUSE_POS
If the event is a mouse event, include the position rendered as "@ (col,line)".
If the event is a mouse event, include the position rendered as "\f(CW@ (col,line)\fP".
.PP
The following shortcuts are provided for common combinations of format bits:
.TP

View File

@ -16,13 +16,13 @@ Link with \fI-ltermkey\fP.
The \fIformat\fP argument specifies the format expected in the string, as a bitmask of the following constants:
.TP
.B TERMKEY_FORMAT_LONGMOD
Expect full modifier names e.g. "Shift-" instead of abbreviating to "S-".
Expect full modifier names e.g. "\f(CWShift-\fP" instead of abbreviating to "\f(CWS-\fP".
.TP
.B TERMKEY_FORMAT_CARETCTRL
If the only modifier is \fBTERMKEY_MOD_CTRL\fP on a plain letter, accept it as "^X" rather than "Ctrl-X".
If the only modifier is \fBTERMKEY_MOD_CTRL\fP on a plain letter, accept it as "\f(CW^X\fP" rather than "\f(CWCtrl-X\fP".
.TP
.B TERMKEY_FORMAT_ALTISMETA
Use the name "Meta" or the letter "M" instead of "Alt" or "A".
Use the name "\f(CWMeta\fP" or the letter "\f(CWM\fP" instead of "\f(CWAlt\fP" or "\f(CWA\fP".
.PP
Before returning, this function canonicalises the \fIkey\fP structure according to the rules given for \fBtermkey_canonicalise\fP(3).
.PP

View File

@ -29,7 +29,7 @@ No key events are ready and the terminal has been closed, so no more will arrive
.B TERMKEY_RES_ERROR
An IO error occured. \fIerrno\fP will be preserved. If the error is \fBEINTR\fP then this will only be returned if \fBTERMKEY_FLAG_EINTR\fP flag is not set; if it is then the IO operation will be retried instead. If this is called with terminal IO stopped, due to \fBtermkey_stop\fP(3) then \fIerrno\fP will be set to \fBEINVAL\fP.
.SH EXAMPLE
The following example program prints details of every keypress until the user presses "Ctrl-C".
The following example program prints details of every keypress until the user presses \fICtrl-C\fP.
.PP
.in +4n
.nf