From 5a54cccd3aee98caefb8f0977d65f49f9d57c5c3 Mon Sep 17 00:00:00 2001
From: Alexandre Prokoudine <alexandre.prokoudine@gmail.com>
Date: Wed, 23 Nov 2022 12:43:19 +0300
Subject: [PATCH] Restore the default keyboard bindings subchapter and move it
 to a better place

The entire Introduction part needs a review, let's keep the page around until then
---
 include/default-keyboard-bindings.html | 51 ++++++++++++++++++++++++++
 master-doc.txt                         |  9 +++++
 2 files changed, 60 insertions(+)
 create mode 100644 include/default-keyboard-bindings.html

diff --git a/include/default-keyboard-bindings.html b/include/default-keyboard-bindings.html
new file mode 100644
index 0000000..3f01864
--- /dev/null
+++ b/include/default-keyboard-bindings.html
@@ -0,0 +1,51 @@
+<p>
+  Almost every available function in Ardour can be bound to a keyboard
+  shortcut (and those few that cannot will usually respond to an <a
+  href="@@controlling-ardour-with-osc"><abbr
+  title="Open Sound Control">OSC</abbr> command</a>). Ardour comes with a
+  rich set of default <dfn>key bindings</dfn> for the most commonly used
+  functions.
+</p>
+
+<p>
+  These bindings strive to be <dfn>mnemonic</dfn>, that is, easy and intuitive
+  to remember, and follow widely accepted conventions. As a general rule, the
+  first letter of an operation will be used for as a shortcut, if available.
+  This does not necessarily lead to the best ergonomics for rapid
+  editing&mdash;there are alternative binding sets for that&mdash;but it does
+  make it simpler for newcomers to remember some of the most useful ones, for
+  example:
+</p>
+
+<p>
+  <kbd>S</kbd> for <kbd class="menu">Region &gt; Edit &gt; Split</kbd>
+  or
+  <kbd>P</kbd> for <kbd class="menu">Transport &gt; Playhead &gt; Playhead to
+  Mouse</kbd>.
+</p>
+
+<p>
+  Existing key bindings in menus are listed on the right side of the menu
+  items.
+</p>
+
+<p>
+  Almost every key binding in Ardour can be looked for and/or changed in
+  <kbd class="menu">Window &gt; Keyboard Shortcuts</kbd> (which is bound to <kbd
+  class="mod2">K</kbd>).
+</p>
+
+<p class="warning">
+  Ardour will warn you with a "Colliding Keybindings" message, if you try to
+  reassign the binding of a key combination that is already in use.
+  Nevertheless if you do so, consider, that
+  this might lead to confusion when asking for help&mdash;when the
+  explanation is given in terms of a standard key binding&mdash;which will have
+  a completely different effect on the system with the modified key bindings.
+</p>
+
+<p>
+  The conventions for using modifier keys (<kbd class="mod1n"></kbd>, <kbd
+  class="mod2n"></kbd>, <kbd class="mod3n"></kbd>, etc.) differ among
+  platforms, so different default bindings for each are provided.
+</p>
diff --git a/master-doc.txt b/master-doc.txt
index af010dc..44df5f6 100644
--- a/master-doc.txt
+++ b/master-doc.txt
@@ -100,6 +100,15 @@ uri: introducing-ardour/basic-gui-operations/using-the-mouse
 part: subchapter
 ---
 
+---
+title: Default Keyboard Bindings
+menu_title: Default Key Bindings
+include: default-keyboard-bindings.html
+link: default-keyboard-bindings
+uri: default-keyboard-bindings
+part: subchapter
+---
+
 ---
 title: Basic GUI Operations
 include: basic-gui-operations.html