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">
