Tweak README-KeyTab and README.keyboard a bit

Summary:
Rename README.KeyTab to README-KeyTab to prevent Konsole from trying to
load it as a keyboard translator file, and fix references to that file
name in other files.

Flesh out README-KeyTab and README.keyboard and reformat them.

Also copy the the original README-KeyTab to README-KeyTab-original,
just in case there's some concept that I misinterpretted/misunderstood.

Reviewers: #konsole, hindenburg

Reviewed By: #konsole, hindenburg

Subscribers: #konsole

Tags: #konsole

Differential Revision: https://phabricator.kde.org/D12032

data/keyboard-layouts/README-KeyTab

@@ -0,0 +1,78 @@
+[README-KeyTab]
+
+The keytabs shown in the Edit Profile dialog -> Keyboard tab are taken from
+*.keytab configuration files located in the system-wide location (typically
+/usr/share/applications/konsole on Linux) or the writable location in the
+user's home directory (typically ~/.local/share/applications/konsole on Linux).
+
+Keytabs allow users to configure the behavior of konsole on keyboard events,
+especially functions keys. Have a look at doc/user/README.keyboard.
+
+The syntax of each entry/rule follows the pattern:
+
+  "key" Keyname { ("+"|"-") Modename } ":" (String|Operation)
+
+Key names are those defined in <qnamespace.h> with the "Qt::Key_" prefix
+removed. For a list of key names check the Qt::Key enum at:
+https://doc.qt.io/qt-5/qt.html#Key-enum
+
+Mode names are:
+
+  - Shift   : Shift Key pressed
+  - Alt     : Alt Key pressed
+  - Control : Control Key pressed
+
+  ( The VT100 emulation has modes that can affect the sequences emitted
+    by certain keys. Those modes are under control of the client program.
+
+    - Newline     : affects Return and Enter keys, when set makes them send
+                    both \r and \n control characters; when reset makes them
+                    send \r only.
+
+    - Application : affects applications that use the Alternate Screen buffer.
+
+    - Ansi        : send ANSI escape and control sequences (v.s. sending VT52
+                    escape and control sequences).
+
+    Since sending a state to a program that has set the state itself is
+    positivly wrong and obsolete design, better forget about this nasty
+    detail. I may well remove this "feature" in a future clean up round. )
+
+  A "+" preceding a Modename means the Key/mode is pressed/active respectively.
+
+  A "-" preceding a Modename means the Key/mode isn't pressed/active respectively.
+
+  If a mode isn't present in a key combination, its state is ignored.
+
+  Note that the combination of Key and Modes (set/reset) has to be unique.
+  This means, that
+
+    key A + Shift : "A"
+    key A : "a"
+
+  will not accept the small letter "a" rule as you'd exepct, you'll have
+  to add a "- Shift" to the latter rule to make it work.
+  Use the stdout/stderr dianostics of konsole when modifying keytabs to
+  find problems like these.
+
+Supported operations are
+
+- scrollUpLine       : scroll up   one line in the history log
+- scrollUpPage       : scroll up   one page in the history log
+- scrollDownLine     : scroll down one line in the history log
+- scrollDownPage     : scroll down one page in the history log
+- scrollUpToTop      : scroll up to the begining of the history log
+- scrollDownToBottom : scroll down to the end of the history log
+
+
+Strings have the syntax of C strings,
+one may use the following escapes:
+
+  - \E - Escape
+  - \\ - Backslash
+  - \" - Double quote
+  - \t - Tab
+  - \r - Carriage Return
+  - \n - New Line
+  - \b - Backspace
+  - \xHH - where HH are two hex digits (e.g. \x00 (the NUL character))

data/keyboard-layouts/default.keytab

@@ -1,8 +1,9 @@
 # [README.default.Keytab] Default Keyboard Table
 #
-# To customize your keyboard, copy this file to something
+# To customize your keyboard, copy this file to something ending with
-# ending with .keytab and change it to meet you needs.
+# .keytab and change it to meet you needs.
-# Please read the README.KeyTab and the README.keyboard
+#
+# Please read the README-KeyTab and the doc/user/README.keyboard files
 # in this case.
 #
 # --------------------------------------------------------------

doc/user/README.keyboard

@@ -1,16 +1,17 @@
 [README.keyboard]
 
-The *.keytab files (located in $KDEDIR/share/apps/konsole) allow
+The *.keytab files (located in /usr/share/applications/konsole and
-to configure the keyboard due to your specific environment.
+~/.local/share/applications/konsole) allow you to configure the keyboard
+to suit your specific environment/requirements.
 
-Beside that you can use them to make the keyboard emit virtually
+Beside that you can use them to make the keyboard emit virtually any
-any escape sequence you want, here a probe of more typical problems
+escape sequence you want, here are some notes about the more typical
-related to keyboards, that can be coped with this way:
+problems related to keyboards, that can be coped with this way:
 
 - BS Hack
 
-  While one would expect, that the Backspace key send ASCII
+  While one would expect, that the Backspace key send ASCII Backspace,
-  Backspace, this is not the case in many Linux installations.
+  this is not the case in many Linux installations.
 
   The idea behind this hack is to preserve the CTRL-H.
 
@@ -36,9 +37,8 @@ Consult your terminfo or termcap database for the expected values.
 Note that your system is not unlikely to have other keyboard databases
 which have to be in sync, too (e.g. /etc/inputrc for readline(3)).
 
-If you want to adjust things to your needs, copy one of the
+If you want to adjust things to your needs you can copy one of the *.keytab
-*.keytab files and edit it. When restarted, konsole offers
+files and edit it. The changes will take effect after restarting konsole.
-you this new entry on it's menu.
 
-In case your new keytab is likely to suit common needs,
+In case your new keytab is likely to suit common needs, please contribute
-please contribute to konsole by sending me the file.
+to konsole by sending us the file.