Small updates.

* `_Xmodmap`: add comment about `setxkbmap`
* `_ncmpcpp/bindings`: add back syntax documentation
* `_notmuch-config`: avoid use absolute/explicit home path
* `_offlineimap/offlineimap.py`: add comment on password file creation

1 files changed, 141 insertions, 0 deletions

diff --git a/_ncmpcpp/bindings b/_ncmpcpp/bindings
index 9934aa3..eb37e8c 100644
--- a/_ncmpcpp/bindings
+++ b/_ncmpcpp/bindings
@@ -10,12 +10,153 @@
 ## 2016-01-08
 ##
 
+##### General rules ##### {{{
+##
+## 1) Because each action has runtime checks whether it's
+##    ok to run it, a few actions can be bound to one key.
+##    Actions will be bound in order given in configuration
+##    file. When a key is pressed, first action in order
+##    will test itself whether it's possible to run it. If
+##    test succeeds, action is executed and other actions
+##    bound to this key are ignored. If it doesn't, next
+##    action in order tests itself etc.
+##
+## 2) It's possible to bind more that one action at once
+##    to a key. It can be done using the following syntax:
+##
+##    def_key "key"
+##      action1
+##      action2
+##      ...
+##
+##    This creates a chain of actions. When such chain is
+##    executed, each action in chain is run until the end of
+##    chain is reached or one of its actions fails to execute
+##    due to its requirements not being met. If multiple actions
+##    and/or chains are bound to the same key, they will be
+##    consecutively run until one of them gets fully executed.
+##
+## 3) When ncmpcpp starts, bindings configuration file is
+##    parsed and then ncmpcpp provides "missing pieces"
+##    of default keybindings. If you want to disable some
+##    bindings, there is a special action called 'dummy'
+##    for that purpose. Eg. if you want to disable ability
+##    to crop playlists, you need to put the following
+##    into configuration file:
+##
+##    def_key "C"
+##      dummy
+##
+##    After that ncmpcpp will not bind any default action
+##    to this key.
+##
+## 4) To let you write simple macros, the following special
+##    actions are provided:
+##
+##    - push_character "character" - pushes given special
+##      character into input queue, so it will be immediately
+##      picked by ncmpcpp upon next call to readKey function.
+##      Accepted values: mouse, up, down, page_up, page_down,
+##      home, end, space, enter, insert, delete, left, right,
+##      tab, shift_tab, ctrl_a, ctrl_b, ..., ctrl_z, f1, f2,
+##      ..., f12, backspace, backspace_2.
+##
+##    - push_characters "string" - pushes given string into
+##      input queue.
+##
+##    - require_runnable "action" - checks whether given action
+##      is runnable and fails if it isn't. This is especially
+##      useful when mixed with previous two functions. Consider
+##      the following macro definition:
+##
+##      def_key "key"
+##        push_characters "custom_filter"
+##        apply_filter
+##
+##      If apply_filter can't be currently run, we end up with
+##      sequence of characters in input queue which will be
+##      treated just as we typed them. This may lead to unexpected
+##      results (in this case 'c' will most likely clear current
+##      playlist, 'u' will trigger database update, 's' will stop
+##      playback etc.). To prevent such thing from happening, we
+##      need to change above definition to this one:
+##
+##      def_key "key"
+##        require_runnable "apply_filter"
+##        push_characters "custom_filter"
+##        apply_filter
+##
+##      Here, first we test whether apply_filter can be actually run
+##      before we stuff characters into input queue, so if condition
+##      is not met, whole chain is aborted and we're fine.
+##
+##    - require_screen "screen" - checks whether given screen is
+##      currently active. accepted values: browser, clock, help,
+##      media_library, outputs, playlist, playlist_editor,
+##      search_engine, tag_editor, visualizer, last_fm, lyrics,
+##      selected_items_adder, server_info, song_info,
+##      sort_playlist_dialog, tiny_tag_editor.
+##
+##    - run_external_command "command" - runs given command using
+##      system() function.
+##
+## 5) In addition to binding to a key, you can also bind actions
+##    or chains of actions to a command. If it comes to commands,
+##    syntax is very similar to defining keys. Here goes example
+##    definition of a command:
+##
+##      def_command "quit" [deferred]
+##        stop
+##        quit
+##
+##    If you execute the above command (which can be done by
+##    invoking action execute_command, typing 'quit' and pressing
+##    enter), ncmpcpp will stop the player and then quit. Note the
+##    presence of word 'deferred' enclosed in square brackets. It
+##    tells ncmpcpp to wait for confirmation (ie. pressing enter)
+##    after you typed quit. Instead of 'deferred', 'immediate'
+##    could be used. Then ncmpcpp will not wait for confirmation
+##    (enter) and will execute the command the moment it sees it.
+##
+## Note: Both 'backspace' and 'backspace_2' are used because some
+##       terminals interpret backspace using keycode of 'backspace'
+##       and some the one of 'backspace_2'. You can get away with
+##       binding once if all your terminal emulators use the same
+##       value.
+##
+## Note: There is a difference between:
+##
+##         def_key "key"
+##           action1
+##
+##         def_key "key"
+##           action2
+##
+##       and
+##
+##         def_key "key"
+##           action1
+##           action2
+##
+##      First one binds two single actions to the same key whilst
+##      second one defines a chain of actions. The behavior of
+##      these two is different and is described in (1) and (2).
+##
+## Note: Function def_key accepts non-ascii characters.
+## }}}
+
 def_key "j"
   scroll_down
 
 def_key "k"
   scroll_up
 
+def_key "ctrl_u"
+  page_up
+
+def_key "ctrl_d"
+  page_down
+
 def_key "ctrl_j"
   move_selected_items_down