Add man page for libterminput_set_flags and libterminput_clear_flags

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

3 files changed, 138 insertions, 2 deletions

diff --git a/Makefile b/Makefile
index 59cd5b4..e4d37da 100644
--- a/Makefile
+++ b/Makefile
@@ -51,11 +51,14 @@ interactive-test: interactive-test.o libterminput.a
 install: libterminput.a libterminput.$(LIBEXT)
 	mkdir -p -- "$(DESTDIR)$(PREFIX)/lib"
 	mkdir -p -- "$(DESTDIR)$(PREFIX)/include"
+	mkdir -p -- "$(DESTDIR)$(MANPREFIX)/man3"
 	cp -- libterminput.a "$(DESTDIR)$(PREFIX)/lib/"
 	cp -- libterminput.h "$(DESTDIR)$(PREFIX)/include/"
 	cp -- libterminput.$(LIBEXT) "$(DESTDIR)$(PREFIX)/lib/libterminput.$(LIBMINOREXT)"
 	ln -sf -- libterminput.$(LIBMINOREXT) "$(DESTDIR)$(PREFIX)/lib/libterminput.$(LIBMAJOREXT)"
 	ln -sf -- libterminput.$(LIBMAJOREXT) "$(DESTDIR)$(PREFIX)/lib/libterminput.$(LIBEXT)"
+	cp -- libterminput_set_flags.3 "$(DESTDIR)$(MANPREFIX)/man3"
+	ln -sf -- libterminput_set_flags.3 "$(DESTDIR)$(MANPREFIX)/man3/libterminput_clear_flags.3"
 
 uninstall:
 	-rm -f -- "$(DESTDIR)$(PREFIX)/lib/libterminput.$(LIBMAJOREXT)"
@@ -63,6 +66,8 @@ uninstall:
 	-rm -f -- "$(DESTDIR)$(PREFIX)/lib/libterminput.$(LIBEXT)"
 	-rm -rf -- "$(DESTDIR)$(PREFIX)/lib/libterminput.a"
 	-rm -rf -- "$(DESTDIR)$(PREFIX)/include/libterminput.h"
+	-rm -rf -- "$(DESTDIR)$(MANPREFIX)/man3/libterminput_set_flags.3"
+	-rm -rf -- "$(DESTDIR)$(MANPREFIX)/man3/libterminput_clear_flags.3"
 
 clean:
 	-rm -f -- *.o *.a *.lo *.so *.su *.dll *.dylib interactive-test
diff --git a/libterminput.h b/libterminput.h
index 8318dff..45ac2a4 100644
--- a/libterminput.h
+++ b/libterminput.h
@@ -8,7 +8,7 @@
 /**
  * Flags for supporting incompatible input; the user must
  * set or clear his flag after setting or clearing it on
- * the terminal, and the use must make sure that the
+ * the terminal, and the user must make sure that the
  * terminal support this flag if set.
  */
 enum libterminput_flags {
@@ -21,7 +21,7 @@ enum libterminput_flags {
 	/**
 	 * If an ESC is received without anything after it,
 	 * return ESC keypress. This is not always desirable
-	 * behaviour as the use may manually press ESC to
+	 * behaviour as the user may manually press ESC to
 	 * simulate a keypress that terminal does not support
 	 * (yes, this is a real world issue).
 	 */
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)