Keyboard Shortcuts: initial revision of the documentation (rebase conflict fix)

diff --git a/include/keyboard-shortcuts.html b/include/keyboard-shortcuts.html
new file mode 100644 (file)
index 0000000..35e2832
--- /dev/null
+++ b/include/keyboard-shortcuts.html
@@ -0,0 +1,99 @@
+<p>
+       The <kbd class="window">Keyboard Shortcuts</kbd> dialog allows easily
+       redefining existing keyboard shortcuts to operations and creating new ones.
+</p>
+
+<figure>
+  <img style="width:50%;" src="/images/keyboard-shortcuts-window.png" alt="Keyboard Shortcuts">
+  <figcaption>
+    Keyboard Shortcuts
+  </figcaption>
+</figure>
+
+<h2>Contexts and Subcontexts</h2>
+
+<p>
+       The important concept to understand here is that the same shortcut can be
+       used for different operations in different contexts. E.g. in the
+       <dfn>Editor</dfn> context, the <kbd class="button">T</kbd> key switches
+       on the <dfn>Stretch</dfn> mode to time-stretch clips on the canvas. However,
+       in the MIDI Step Entry context, <kbd class="button">T</kbd> inserts
+       an F-sharp note. The contexts are represented by tabs in this dialog, e.g.
+       Editor, MIDI, Recorder, etc.
+</p>
+
+<p>
+       Inside every tab, features are grouped into <dfn>subcontexts</dfn> that can
+       be expanded or collapsed by clicking the triangular-shaped button to the
+       left of the name of each subcontext. E.g. the 'Snap' subcontext lists all
+       snapping units, while the 'Region' subcontext lists all actions accessible
+       via the right-click menu.
+</p>
+
+<p>
+       The <dfn>Search</dfn> function at the bottom of the dialog works within
+       the currently selected context/tab only. If a search returned zero results,
+       switching to a different context is a viable solution to locating the action
+       of interest.
+</p>
+
+<h2>Setting New Shortcuts</h2>
+
+<p>
+       Once an action of interest is located in the list, all it takes to set
+       a keybinding to it is selecting the action in the list, then pressing
+       the sequence of keys. The newly defined keybinding will immediately show up
+       in the <dfn>Shortcut</dfn> column.
+</p>
+
+<h2>Redefining Existing Shortcuts</h2>
+
+<p>
+       An existing shortcut to an action can easily be replaced with a different
+       one by selecting the action and pressing a new sequence of keys. The newly
+       defined keybinding will immediately show up in the <dfn>Shortcut</dfn>
+       column.
+</p>
+
+<h2>Handling Collisions</h2>
+
+<p>
+       Once a keybinding is assigned to an action, that keybinding is considered
+       taken. Attempting to assign that same keybinding to a different action will
+       result in a collision. Ardour will notify the user that the keybinding is
+       already taken (and by what action) and will ask to either reconsider or
+       force-set the keybinding to a new action.
+</p>
+
+<figure>
+  <img style="width:50%;" src="/images/keyboard-shortcuts-collision.png" alt="A keyboard shortcut collision">
+  <figcaption>
+    A keyboard shortcut collision
+  </figcaption>
+</figure>
+
+<p>
+       Force-setting the keybinding of choice to a new action will remove
+       the keybinding from the action it was previously assigned to. A new
+       keybinding then can be assigned to that action.
+</p>
+
+<h2>Removing Existing Shortcuts</h2>
+
+<p>
+       In some cases it is desirable to remove a shortcuts entirely. Selecting an
+       action of interest, then pressing the
+       <kbd class="button">Remove shortcut</kbd> button at the bottom of the dialog
+       will do just that. The keybinding will immediately disappear from the
+       <dfn>Shortcut</dfn> column.
+</p>
+
+<h2>Reverting to Factory Settings</h2>
+
+<p>
+       If applied customizations to default keyboard shortcuts didn't work out,
+       it's possible to revert to "factory settings". Clicking
+       <kbd class="button">Reset Bindings to Defaults</kbd> will remove all
+       customizations and bring back default keybindings. Important: Ardour will not
+       ask for a confirmation!
+</p>

diff --git a/master-doc.txt b/master-doc.txt
index 0d37a6245cc13c210593b15f16da1073ead1c402..5d9678a5477421ef8f1a5c93a56c7ad78b5dc5dc 100644 (file)
--- a/master-doc.txt
+++ b/master-doc.txt
@@ -301,6 +301,30 @@ uri: setting-up-your-system/setting-up-midi
 part: chapter
 ---
 
+---
+title: MIDI on Linux
+include: midi-on-linux.html
+link: midi-on-linux
+uri: setting-up-your-system/setting-up-midi/midi-on-linux
+part: subchapter
+---
+
+---
+title: MIDI on OS X
+include: midi-on-os-x.html
+link: midi-on-os-x
+uri: setting-up-your-system/setting-up-midi/midi-on-os-x
+part: subchapter
+---
+
+---
+title: Keyboard Shortcuts
+include: keyboard-shortcuts.html
+link: keyboard-shortcuts
+uri: setting-up-your-system/keyboard-shortcuts
+part: chapter
+---
+
 ---
 title: Ardour's Interface
 uri: ardours-interface

diff --git a/source/images/keyboard-shortcuts-collision.png b/source/images/keyboard-shortcuts-collision.png
new file mode 100644 (file)
index 0000000..feb2a11
Binary files /dev/null and b/source/images/keyboard-shortcuts-collision.png differ

diff --git a/source/images/keyboard-shortcuts-window.png b/source/images/keyboard-shortcuts-window.png
new file mode 100644 (file)
index 0000000..d842edd
Binary files /dev/null and b/source/images/keyboard-shortcuts-window.png differ