[utilities/kate] doc/katepart: add documentation for the new "Align On" action, command, and JS function

[Pablo Rauzy]

Git commit 7463207656a9142e1949aea56b65c628b5f568a6 by Pablo Rauzy.
Committed on 07/08/2022 at 01:46.
Pushed by cullmann into branch 'master'.

add documentation for the new "Align On" action, command, and JS function

M  +12   -0    doc/katepart/advanced.docbook
M  +24   -0    doc/katepart/development.docbook
M  +17   -2    doc/katepart/menus.docbook

https://invent.kde.org/utilities/kate/commit/7463207656a9142e1949aea56b65c628b5f568a6

diff --git a/doc/katepart/advanced.docbook b/doc/katepart/advanced.docbook
index 4b765da5f..191e29956 100644
--- a/doc/katepart/advanced.docbook
+++ b/doc/katepart/advanced.docbook
@@ -591,6 +591,18 @@ defining a separator, for example:  <userinput><command>join</command> ', '</use
 document.</para></listitem>
 </varlistentry>
 
+<varlistentry>
+<term><cmdsynopsis><command>alignon</command></cmdsynopsis></term>
+<listitem>
+<para>This command aligns lines in the selected block or whole document on the column given by a regular expression given as an argument.</para>
+<para>If you give an empty pattern it will align on the first non-blank character by default.</para>
+<para>If the pattern has a capture it will indent on the captured match.</para>
+<para><emphasis>Examples:</emphasis></para>
+<para><userinput>alignon -</userinput> will insert spaces before the first '-' of each lines to align them all on the same column.</para>
+<para><userinput>alignon :\\s+(.)</userinput> will insert spaces before the first non-blank character that occurs after a colon to align them all on the same column.</para>
+</listitem>
+</varlistentry>
+
 <varlistentry>
 <term><cmdsynopsis><command>unwrap</command></cmdsynopsis></term>
 <listitem><para>Unwrap the selected text or the whole document.</para></listitem>
diff --git a/doc/katepart/development.docbook b/doc/katepart/development.docbook
index 9cfd2774f..34ee8a475 100644
--- a/doc/katepart/development.docbook
+++ b/doc/katepart/development.docbook
@@ -4397,6 +4397,30 @@ bool document.isOthers(<parameter>Cursor <replaceable>cursor</replaceable></para
 </para></listitem>
 </varlistentry>
 
+<varlistentry>
+<term><synopsis>
+void document.indent(<parameter>Range <replaceable>range</replaceable></parameter>, <parameter>int <replaceable>change</replaceable></parameter>);
+</synopsis></term>
+<listitem><para>
+Indents all lines in <replaceable>range</replaceable> by <replaceable>change</replaceable> tabs or <replaceable>change</replaceable> times <literal>tabSize</literal> spaces depending on the users preferences. The <replaceable>change</replaceable> parameter can be negative.
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><synopsis>
+void document.alignOn(<parameter>Range <replaceable>range</replaceable></parameter>, <parameter>String <replaceable>pattern</replaceable> = ""</parameter>);
+</synopsis></term>
+<listitem><para>
+Aligns lines in <replaceable>range</replaceable> on the column given by the regular expression <replaceable>pattern</replaceable>.
+With an empty <replaceable>pattern</replaceable> it will align on the first non-blank character by default.
+If the pattern has a capture it will indent on the captured match.
+</para>
+<para><emphasis>Examples:</emphasis></para>
+<para><literal>document.alignOn(document.documentRange(), '-');</literal> will insert spaces before the first <literal>-</literal> of each lines to align them all on the same column.</para>
+<para><literal>document.alignOn(document.documentRange(), ':\\s+(.)');</literal> will insert spaces before the first non-blank character that occurs after a colon to align them all on the same column.</para>
+</listitem>
+</varlistentry>
+
 </variablelist>
 </para>
 
diff --git a/doc/katepart/menus.docbook b/doc/katepart/menus.docbook
index bded28594..4b26efd13 100644
--- a/doc/katepart/menus.docbook
+++ b/doc/katepart/menus.docbook
@@ -674,10 +674,10 @@ all your selected text follows the indentation mode you choose.</para>
 </listitem>
 </varlistentry>
 
-<varlistentry id="selection-align">
+<varlistentry id="selection-formatindent">
 <term><menuchoice>
 <guimenu>Selection</guimenu>
-<guimenuitem>Align</guimenuitem>
+<guimenuitem>Format Indent</guimenuitem>
 </menuchoice></term>
 <listitem>
 <para>Causes a realign of the current line or selected lines using the
@@ -685,6 +685,21 @@ indentation mode and indentation settings in the document.</para>
 </listitem>
 </varlistentry>
 
+<varlistentry id="selection-alignon">
+<term><menuchoice>
+<guimenu>Selection</guimenu>
+<guimenuitem>Align On...</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>This command aligns lines in the selected block or whole document on the column given by a regular expression that you will be prompted for.</para>
+<para>If you give an empty pattern it will align on the first non-blank character by default.</para>
+<para>If the pattern has a capture it will indent on the captured match.</para>
+<para><emphasis>Examples:</emphasis></para>
+<para>With '<userinput>-</userinput>' it will insert spaces before the first '-' of each lines to align them all on the same column.</para>
+<para>With '<userinput>alignon :\\s+(.)</userinput>' it will insert spaces before the first non-blank character that occurs after a colon to align them all on the same column.</para>
+</listitem>
+</varlistentry>
+
 <varlistentry id="selection-word-wrap-document">
 <term><menuchoice>
 <guimenu>Selection</guimenu>