[utilities/kate] /: making Kate's documentation the source for the Keyboard Macros Plugin README.md to avoid having to maintain both

[Christoph Cullmann]

Git commit f8a1e2c215da18c03a26669ad937fa32bb44cf29 by Christoph Cullmann, on behalf of Pablo Rauzy.
Committed on 14/08/2022 at 14:20.
Pushed by cullmann into branch 'master'.

making Kate's documentation the source for the Keyboard Macros Plugin README.md to avoid having to maintain both

M  +65   -44   addons/keyboardmacros/README.md
A  +11   -0    addons/keyboardmacros/gen-README.md.sh
M  +4    -4    doc/kate/plugins.docbook

https://invent.kde.org/utilities/kate/commit/f8a1e2c215da18c03a26669ad937fa32bb44cf29

diff --git a/addons/keyboardmacros/README.md b/addons/keyboardmacros/README.md
index 8967d0026..3b561e672 100644
--- a/addons/keyboardmacros/README.md
+++ b/addons/keyboardmacros/README.md
@@ -1,89 +1,110 @@
-Keyboard Macros Plugin
+Keyboard Macros Plugin {#kate-application-plugin-keyboardmacros}
 ======================
 
+Introduction {#keyboardmacros-intro}
+------------
+
 Record and play keyboard macros (i.e., keyboard action sequences).
 
-## Basic usage
+Basic usage {#keyboardmacros-basicusage}
+-----------
 
-### To start recording a keyboard macro:
+### To start recording a keyboard macro: {#keyboardmacros-basicusage-record}
 
-Menu: `Tools > Keyboard Macros > Record Macro...`
+[Tools \> Keyboard Macros \> Record Macro\...]
+[`Ctrl+Shift+K`].
 
 The plugin will record every key presses until you end recording.
 
-Default shortcut: `Ctrl+Shift+K`.
-
-### To end recording:
-
-Menu: `Tools > Keyboard Macros > End Macro Recording`
+### To end recording: {#keyboardmacros-basicusage-record-end}
 
-The plugin will stop recording key presses and save the key presses sequences as the current macro.
+[Tools \> Keyboard Macros \> End Macro Recording]
+[`Ctrl+Shift+K`].
 
-Default shortcut: `Ctrl+Shift+K`.
+The plugin will stop recording key presses and save the key presses
+sequences as the current macro.
 
-### To cancel recording:
+### To cancel recording: {#keyboardmacros-basicusage-record-cancel}
 
-Menu: `Tools > Keyboard Macros > Cancel Macro Recording`
+[Tools \> Keyboard Macros \> Cancel Macro Recording]
+[`Ctrl+Alt+Shift+K`].
 
-The plugin will stop recording key presses but the current macro won't change.
+The plugin will stop recording key presses but the current macro won\'t
+change.
 
-Default shortcut: `Ctrl+Alt+Shift+K`.
+### To play the current macro: {#keyboardmacros-basicusage-play}
 
-### To play the current macro:
-
-Menu: `Tools > Keyboard Macros > Play Macro`
+[Tools \> Keyboard Macros \> Play Macro]
+[`Ctrl+Alt+K`].
 
 The plugin will play the current macro.
 
-Default shortcut: `Ctrl+Alt+K`.
-
-Command: `kmplay` will play the current macro.
+The `kmplay` command without any arguments will also play the current
+macro.
 
-## Named macros
+Named macros {#keyboardmacros-namedmacros}
+------------
 
 It is possible to save keyboard macros by giving them a name.
 
-Named macros are persistent between Kate's sessions, they're saved in the `keyboardmacros.json` file in Kate's user data directory (usually `~/.local/share/kate/`).
+Named macros are persistent between Kate\'s sessions, they\'re saved in
+the `keyboardmacros.json` file in Kate\'s user data directory (usually
+`~/.local/share/kate/`).
 
-### To save the current macro:
+### To save the current macro: {#keyboardmacros-namedmacros-save}
 
-Menu: `Tools > Keyboard Macros > Save Current Macro`
+[Tools \> Keyboard Macros \> Save Current Macro]
+[`Alt+Shift+K`].
 
 The plugin will prompt you for a name and save the macro under it.
 
-Default shortcut: `Alt+Shift+K`.
+The `kmsave name` command will save the current macro under the name
+`name`.
 
-Command: `kmsave <name>` will save the current macro under the name `<name>`.
+### To load a saved macro as the current one: {#keyboardmacros-namedmacros-load}
 
-### To load a saved macro as the current one:
+[Tools \> Keyboard Macros \> Load Named Macro\...].
 
-Menu: `Tools > Keyboard Macros > Load Named Macro... >`
+The plugin lists saved macros as items in this submenu, activating an
+item will load the corresponding macro as the current one.
 
-The plugin will list saved macros as items in this submenu, activating an item will load the corresponding macro as the current one.
+The `kmload name` command will load the macro saved under the name
+`name` as the current one.
 
-Command: `kmload <name>` will load the macro saved under the name `<name>` as the current one.
+### To play a saved macro without loading it: {#keyboardmacros-namedmacros-play}
 
-### To play a saved macro without loading it:
+[Tools \> Keyboard Macros \> Play Named Macro\...].
 
-Menu: `Tools > Keyboard Macros > Play Named Macro... >`
+The plugin lists saved macros as items in this submenu, activating an
+item will play the corresponding macro without loading it.
 
-The plugin will list saved macros as items in this submenu, activating an item will play the corresponding macro without loading it.
+Note that each saved macros is an action that is part of the current
+action collection so that a custom shortcut can be assigned to it
+through the [Settings \> Configure Keyboard Shortcuts\...]
+interface.
 
-Command: `kmplay <name>` will play the macro saved under the name `<name>` without loading it.
+The `kmplay name` command will play the macro saved under the name
+`name` without loading it.
 
-### To wipe (e.g., delete) a saved macro:
+### To wipe (e.g., delete) a saved macro: {#keyboardmacros-namedmacros-wipe}
 
-Menu: `Tools > Keyboard Macros > Wipe Named Macro... >`
+[Tools \> Keyboard Macros \> Wipe Named Macro\...].
 
-The plugin will list saved macros as items in this submenu, activating an item will wipe the corresponding macro.
+The plugin lists saved macros as items in this submenu, activating an
+item will wipe (i.e., delete) the corresponding macro.
 
-Command: `kmwipe <name>` will delete the macro saved under the name `<name>`.
+The `kmwipe name` command will wipe the macro saved under the name
+`name`.
 
-### Tips for commands 
+### Tips for commands: {#keyboardmacros-namedmacros-command-tips}
 
-Note that after the `km` prefix all these commands use a different letter so you can efficiently call them using tab-completion :).
+Note that after the `km` prefix, all these commands use a different
+letter so you can efficiently call them using tab-completion!
 
-## Limitations
+Limitations {#keyboardmacros-limitations}
+-----------
 
-As of now, keyboard macros fail to play properly if some types of GUI widgets are used: QMenu, QuickOpenLineEdit, or TabSwitcherTreeView, for example.
-I'm not sure why but my first guess would be that these widgets work in a non-standard way regarding keyboard events.
+As of now, keyboard macros fail to play properly if some types of GUI
+widgets are used: QMenu, QuickOpenLineEdit, or TabSwitcherTreeView, for
+example. I\'m not sure why but my first guess would be that these
+widgets work in a non-standard way regarding keyboard events.
diff --git a/addons/keyboardmacros/gen-README.md.sh b/addons/keyboardmacros/gen-README.md.sh
new file mode 100644
index 000000000..cd5bf1d2f
--- /dev/null
+++ b/addons/keyboardmacros/gen-README.md.sh
@@ -0,0 +1,11 @@
+#!/bin/bash
+# This scripts uses pandoc to update the README.md file from the documentation.
+
+cd $(dirname "$(readlink -f "$BASH_SOURCE")")
+
+sed -n '/^<sect1 id="kate-application-plugin-keyboardmacros">$/,/^<\/sect1>$/p' ../../doc/kate/plugins.docbook | \
+    pandoc -f docbook -t markdown -s - -o - | \
+    sed 's/{.\(menuchoice\|keycombo\)}//;s/+K/K/;s/CTRL/Ctrl+/;s/SHIFT/Shift+/;s/ALT/Alt+/;s/(\[/[`/;s/\])/`]/' | \
+    cat > README.md
+
+cd - >/dev/null
diff --git a/doc/kate/plugins.docbook b/doc/kate/plugins.docbook
index 80862feec..4740c8841 100644
--- a/doc/kate/plugins.docbook
+++ b/doc/kate/plugins.docbook
@@ -3576,7 +3576,7 @@ writing much of this section.</para>
 (<keycombo action="simul">&Alt;&Shift;<keycap>K</keycap></keycombo>).
 </para>
 <para>The plugin will prompt you for a name and save the macro under it.</para>
-<para>The <userinput>kmsave <replaceable>name</replaceable></userinput> command will save the current macro under the name <replaceable>name</replaceable>.</para>
+<para>The <userinput>kmsave <replaceable>name</replaceable></userinput> command will save the current macro under the name <userinput><replaceable>name</replaceable></userinput>.</para>
 </sect3>
 
 <sect3 id="keyboardmacros-namedmacros-load">
@@ -3585,7 +3585,7 @@ writing much of this section.</para>
 <menuchoice><guimenu>Tools</guimenu><guimenuitem>Keyboard Macros</guimenuitem><guimenuitem>Load Named Macro...</guimenuitem></menuchoice>.
 </para>
 <para>The plugin lists saved macros as items in this submenu, activating an item will load the corresponding macro as the current one.</para>
-<para>The <userinput>kmload <replaceable>name</replaceable></userinput> command will load the macro saved under the name <replaceable>name</replaceable> as the current one.</para>
+<para>The <userinput>kmload <replaceable>name</replaceable></userinput> command will load the macro saved under the name <userinput><replaceable>name</replaceable></userinput> as the current one.</para>
 </sect3>
 
 <sect3 id="keyboardmacros-namedmacros-play">
@@ -3595,7 +3595,7 @@ writing much of this section.</para>
 </para>
 <para>The plugin lists saved macros as items in this submenu, activating an item will play the corresponding macro without loading it.</para>
 <para>Note that each saved macros is an action that is part of the current action collection so that a custom shortcut can be assigned to it through the <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Keyboard Shortcuts...</guimenuitem></menuchoice> interface.</para>
-<para>The <userinput>kmplay <replaceable>name</replaceable></userinput> command will play the macro saved under the name <replaceable>name</replaceable> without loading it.</para>
+<para>The <userinput>kmplay <replaceable>name</replaceable></userinput> command will play the macro saved under the name <userinput><replaceable>name</replaceable></userinput> without loading it.</para>
 </sect3>
 
 <sect3 id="keyboardmacros-namedmacros-wipe">
@@ -3604,7 +3604,7 @@ writing much of this section.</para>
 <menuchoice><guimenu>Tools</guimenu><guimenuitem>Keyboard Macros</guimenuitem><guimenuitem>Wipe Named Macro...</guimenuitem></menuchoice>.
 </para>
 <para>The plugin lists saved macros as items in this submenu, activating an item will wipe (i.e., delete) the corresponding macro.</para>
-<para>The <userinput>kmwipe <replaceable>name</replaceable></userinput> command will wipe the macro saved under the name <replaceable>name</replaceable>.</para>
+<para>The <userinput>kmwipe <replaceable>name</replaceable></userinput> command will wipe the macro saved under the name <userinput><replaceable>name</replaceable></userinput>.</para>
 </sect3>
 
 <sect3 id="keyboardmacros-namedmacros-command-tips">