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

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>

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> = &quot;&quot;</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>
 

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>