Add man page for libterminput_set_flags and libterminput_clear_flags

Signed-off-by: Mattias Andrée <maandree@kth.se>

1 files changed, 131 insertions, 0 deletions

diff --git a/libterminput_set_flags.3 b/libterminput_set_flags.3
new file mode 100644
index 0000000..bce609d
--- /dev/null
+++ b/libterminput_set_flags.3
@@ -0,0 +1,131 @@
+.TH LIBTERMINPUT_SET_FLAGS 3 LIBTERMINPUT
+.SH NAME
+libterminput_set_flags \- Add input parsing flags
+.br
+libterminput_clear_flags \- Remove input parsing flags
+
+.SH SYNOPSIS
+.nf
+#include <libterminput.h>
+
+int libterminput_set_flags(struct libterminput_state *ctx *\fIctx\fP, enum libterminput_flags \fIflags\fP);
+int libterminput_clear_flags(struct libterminput_state *ctx *\fIctx\fP, enum libterminput_flags \fIflags\fP);
+.fi
+.PP
+Link with
+.IR \-lterminput .
+
+.SH DESCRIPTION
+The
+.BR libterminput_set_flags ()
+function sets the flags specified in the
+.I flags
+parameter on
+.IR ctx ,
+whereas the
+.BR libterminput_clear_flags ()
+function clears the flags.
+.PP
+Flags are used to change the behaviour parsing
+rules in order to support escape sequences that
+are incompatible with the default parsing rules.
+The available flags are
+.TP
+.B LIBTERMINPUT_DECSET_1005
+The sequence
+.B CSI M
+shall be parsed be parse as a DECSET 1005 sequence
+which is incompatible with legacy mouse tracking.
+This flag shall only be set if DECSET 1005 has sent
+to the terminal and the user is sure it is supported
+by the terminal.
+.TP
+.B LIBTERMINPUT_MACRO_ON_CSI_M
+The sequence
+.B CSI Pm M
+shall be parsed as a key press of the macro key.
+This is incompatible with all mouse tracking modes
+except
+.IR "DECSET 1006" .
+Applications that do not use mouse tracking, or
+know that their terminal supports
+.I DECSET 1006
+and therefore uses it, can safely use this flag.
+.TP
+.B LIBTERMINPUT_PAUSE_ON_CSI_P
+The sequence
+.B CSI Pm M
+shall be parsed as a key press of the pause key
+instead of the F1 key.
+.TP
+.B LIBTERMINPUT_INS_ON_CSI_AT
+The sequence
+.B CSI Pm @
+shall be parsed as a key press of the insert key
+instead of a number of possible special keys
+combined with the control and shift modifiers.
+.TP
+.B LIBTERMINPUT_SEPARATE_BACKTAB
+Backtab shall be treated as a separate key, and
+not be reported as tab with the shift modifier.
+This flag is just a usability issue. Keyboards
+put backtab on shift+tab, which is why the tab
+keycap has both a backward arrow (backtab) and
+a forward arrow (tab); but most users are unfamiliar
+with backtab, and just see it as shift+tab.
+.TP
+.B LIBTERMINPUT_ESC_ON_BLOCK
+If an ESC is received without anything after it,
+it shall be parsed as an ESC keypress. This is not
+always desirable behaviour as the user may manually
+press ESC to simulate a keypress that terminal does
+not support (yes, this is a real world issue).
+.PP
+.I ctx
+must have been zero-initialised, e.g. with
+.BR memset (3)
+function.
+
+.SH RETURN VALUE
+The
+.BR libterminput_set_flags ()
+and
+.BR libterminput_clear_flags ()
+functions returns 0 upon successful completion;
+otherwise the
+.BR libterminput_set_flags ()
+and
+.BR libterminput_clear_flags ()
+functions return
+.B -1
+and set
+.I errno
+it indicate the error.
+
+.SH ERRORS
+Currnet versions of the
+.BR libterminput_set_flags ()
+and
+.BR libterminput_clear_flags ()
+functions cannot fail.
+
+.SH EXAMPLES
+None.
+
+.SH APPLICATION USAGE
+None.
+
+.SH RATIONALE
+None.
+
+.SH FUTURE DIRECTIONS
+None.
+
+.SH NOTES
+None.
+
+.SH BUGS
+None.
+
+.SH SEE ALSO
+.BR libterminput_read (3)