Document most options for the user + more

termux.properties

@@ -1,6 +1,6 @@
-### After making changes and saving you need to run `termux-reload-settings`
-### to update the terminal.  All information here can also be found on the
-### wiki: https://wiki.termux.com/wiki/Terminal_Settings
+### After making changes and saving you need to run
+### `termux-reload-settings`
+### to update the terminal.
 
 ###############
 # General
@@ -20,17 +20,20 @@
 ### Uncomment to not show soft keyboard on application start.
 # hide-soft-keyboard-on-startup = true
 
-### Uncomment to let keyboard toggle button to enable or disable software
-### keyboard instead of showing/hiding it.
+### Uncomment to let keyboard toggle button to enable or
+### disable software keyboard instead of showing/hiding it.
 # soft-keyboard-toggle-behaviour = enable/disable
 
-### Adjust terminal scrollback buffer. Max is 50000. May have negative
-### impact on performance.
+### Adjust terminal scrollback buffer. Max is 50000.
+### May have negative impact on performance.
 # terminal-transcript-rows = 2000
 
-### Uncomment to use volume keys for adjusting volume and not for the
-### extra keys functionality.
-# volume-keys = volume
+### Uncomment to automatically open links on click.
+# terminal-onclick-url-open = true 
+
+### Adjust margin on left and right in dp units.
+### Valid range is 0 - 100
+# terminal-margin-horizontal = 3
 
 ###############
 # Fullscreen mode
@@ -39,41 +42,66 @@
 ### Uncomment to let Termux start in full screen mode.
 # fullscreen = true
 
-### Uncomment to attempt workaround layout issues when running in
-### full screen mode.
+### Uncomment to attempt workaround layout issues
+### when running in full screen mode.
 # use-fullscreen-workaround = true
 
 ###############
 # Cursor
 ###############
 
-### Cursor blink rate. Values 0, 100 - 2000.
+### Cursor blink rate. Values: 0, 100 - 2000
+### Set it to 0 for no blinking. (default)
 # terminal-cursor-blink-rate = 0
 
 ### Cursor style: block, bar, underline.
 # terminal-cursor-style = block
 
 ###############
-# Extra keys
+# Visibility
+###############
+
+### Force black colors for drawer and dialogs.
+# use-black-ui = true
+
+### Adjust terminal bell behaviour.
+### Choose between: ignore, beep, vibrate (default)
+# bell-character = vibrate
+
+### Select if Termux should follow system night-mode or not.
+### Choose between: true, false, system (default) 
+# night-mode = true
+
+###############
+# Extra keys - options
 ###############
 
 ### Settings for choosing which set of symbols to use for illustrating keys.
-### Choose between default, arrows-only, arrows-all, all and none
+### Choose between: default, arrows-only, arrows-all, all, none
 # extra-keys-style = default
 
-### Force capitalize all text in extra keys row button labels.
-# extra-keys-text-all-caps = true
+###  Uncomment to disable capitalization of extra keys row button labels.
+# extra-keys-text-all-caps = false
+
+### Adjust height of extra keys toolbar.
+### Valid range is 0.4 - 3 (default: 1 )
+# terminal-toolbar-height 1
+
+###############
+# Extra keys - button configuration
+###############
 
-### Default extra-key configuration
+### Default extra-key configuration.
 # extra-keys = [[ESC, TAB, CTRL, ALT, {key: '-', popup: '|'}, DOWN, UP]]
 
-### Two rows with more keys
-# extra-keys = [['ESC','/','-','HOME','UP','END','PGUP'], \
-#               ['TAB','CTRL','ALT','LEFT','DOWN','RIGHT','PGDN']]
+### Two rows with more keys with few handy macro.
+### Swipe up from an extra key to access the macro included.
+# extra-keys = [['ESC', popup:'KEYBOARD','/','-','HOME','UP','END','PGUP'], \
+#               ['TAB', popup:'SHIFT TAB','CTRL','ALT','LEFT','DOWN','RIGHT','PGDN']]
 
-### Configuration with additional popup keys (swipe up from an extra key)
+### Configuration with additional popup keys
 # extra-keys = [[ \
-#   {key: ESC, popup: {macro: "CTRL f d", display: "tmux exit"}}, \
+#   {key: ESC, display: 👁, popup: {macro: "CTRL f d", display: "tmux exit"}}, \
 #   {key: CTRL, popup: {macro: "CTRL f BKSP", display: "tmux ←"}}, \
 #   {key: ALT, popup: {macro: "CTRL f TAB", display: "tmux →"}}, \
 #   {key: TAB, popup: {macro: "ALT a", display: A-a}}, \
@@ -85,15 +113,15 @@
 #   {key: KEYBOARD, popup: {macro: "CTRL d", display: exit}} \
 # ]]
 
-###############
-# Colors/themes
-###############
-
-### Force black colors for drawer and dialogs
-# use-black-ui = true
+### Special keys which are recognised as valid key/macro:
+### ESC, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, HOME, END,
+### TAB, QUOTE, APOSTROPHE, BACKSLASH, DEL, BKSP, ENTER, PGUP, PGDN, 
+### CTRL, SHIFT, ALT, FN, SPACE, UP, LEFT, RIGHT, DOWN, INS,
+### PASTE (Paste from Android clipboard), KEYBOARD (Hide the keyboard),
+### DRAWER (Open app drawer), SCROLL (Enable/Disable scrolling)
 
 ###############
-# HW keyboard shortcuts
+# External hardware keyboard shortcuts
 ###############
 
 ### Disable hardware keyboard shortcuts.
@@ -112,21 +140,12 @@
 # shortcut.rename-session = ctrl + n
 
 ###############
-# Bell key
+# Phone Buttons
 ###############
 
-### Vibrate device (default).
-# bell-character = vibrate
-
-### Beep with a sound.
-# bell-character = beep
-
-### Ignore bell character.
-# bell-character = ignore
-
-###############
-# Back key
-###############
+### Uncomment to use volume keys for adjusting volume 
+### and disable their Termux extra keys functionality.
+# volume-keys = volume
 
 ### Send the Escape key.
 # back-key=escape
@@ -138,8 +157,26 @@
 # Keyboard issue workarounds
 ###############
 
-### Letters might not appear until enter is pressed on Samsung devices
+### Letters might not appear until enter is pressed on Samsung devices.
 # enforce-char-based-input = true
 
-### ctrl+space (for marking text in emacs) does not work on some devices
+### ctrl+space (for marking text in emacs) does not work on some devices.
 # ctrl-space-workaround = true
+
+###############
+# Additional Resources:
+###############
+
+### Wiki page to learn more about some terminal settings:
+### DISCLAIMER: Some information might be outdated!
+# https://wiki.termux.com/wiki/Terminal_Settings
+
+### Touch Keyboard & Extra-Keys wiki page:
+### DISCLAIMER: Some information might be outdated!
+# https://wiki.termux.com/wiki/Touch_Keyboard
+
+### "termux-app" Source code files where those values are defined:
+# ExtraKeysView.java, TermuxPropertyConstants.java
+
+### "termux-properties" documentation page (SOON)
+# https://termux.dev/en/docs/apps/termux/properties/index.html