[utilities/kate] doc/kate: Kate Snippets: add examples for working with selections

[Thomas Friedrichsmeier]

Git commit a8b4c0f44d9bc3dab48ae21fb4974a2b305b5747 by Thomas Friedrichsmeier, on behalf of Beluga Whale.
Committed on 28/07/2022 at 20:06.
Pushed by tfry into branch 'master'.

Kate Snippets: add examples for working with selections

Based on what Thomas Friedrichsmeier shared in https://bugs.kde.org/show_bug.cgi?id=456846

M  +19   -0    doc/kate/plugins.docbook

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

diff --git a/doc/kate/plugins.docbook b/doc/kate/plugins.docbook
index ee987b9e3..b4fb29caf 100644
--- a/doc/kate/plugins.docbook
+++ b/doc/kate/plugins.docbook
@@ -3440,6 +3440,25 @@ documentation for more information.</para>
 functions are being evaluated. E.g., if a function retrieves the text on the
 line where the snippet is being inserted, that text will also contain
 <userinput>${functionCall()}</userinput>.</para>
+<para>As an example of working with selections using the scripting API, a simple way
+to wrap selected text inside tags is this snippet:
+<userinput><strong>${view.selectedText()}</strong></userinput>
+</para>
+<para>The following example invokes a script that inserts a default text in case
+there is no selection. Snippet:</para>
+<para>
+<userinput>${rangeCommand("<strong>%%1</strong>", "Bold")}</userinput></para>
+<para>Script:
+<programlisting>
+function rangeCommand(command, def) {
+    if (view.selectedText().length > 0) {
+        return command.replace("%%1", view.selectedText());
+    } else {
+        return command.replace("%%1", def);
+    }
+}
+</programlisting>
+</para>
 </listitem>
 </varlistentry>