Kate: added documentation for sessions panel. This relates to bug 2491.

Signed-off-by: Michele Calgaro <michele.calgaro@yahoo.it>

4 files changed, 165 insertions, 82 deletions

diff --git a/doc/kate/configuring.docbook b/doc/kate/configuring.docbook
index 7cac74751..51ad5ee97 100644
--- a/doc/kate/configuring.docbook
+++ b/doc/kate/configuring.docbook
@@ -341,11 +341,11 @@ filter over sessions.</para>
 
 <variablelist>
 <varlistentry>
-<term><guilabel>Backgound Shading</guilabel></term>
+<term><guilabel>Background Shading</guilabel></term>
 <listitem><para>This section allows you to enable or disable the background
 shading visualization of your recent activity, and chose which colors to use if
 enabled. See the section about <link
-linkend="kate-mdi-tools-document-list">The Document List</link> for more about
+linkend="kate-mdi-tools-documents-list">The Document List</link> for more about
 this feature.</para></listitem>
 </varlistentry>
 <varlistentry>
diff --git a/doc/kate/fundamentals.docbook b/doc/kate/fundamentals.docbook
index 05a56eac6..221e35450 100644
--- a/doc/kate/fundamentals.docbook
+++ b/doc/kate/fundamentals.docbook
@@ -258,7 +258,7 @@ site opened in one of &konqueror;'s windows.
 <title>Working with &kate;</title>
 <para>
 <link linkend="quick-start">Quick Start</link> will show you how to
-toggle four simple options that will let you configure some of &kate;'s
+toggle simple options that will let you configure some of &kate;'s
 more powerful features right away. <link linkend="keystroke-commands">
 Shortcuts</link> lays out some of the default keystroke
 shortcuts for those who can't or don't want to use a mouse.
@@ -279,8 +279,8 @@ usual labeled icons. And above that, a menubar.
 </para>
 
 <para>
-The left-hand window is a side bar. It combines the Documents
-and Filesystem Browser windows. Switch between the two by clicking on the tabs
+The left-hand window is a side bar. It combines the Documents panel,
+Filesystem Browser and Sessions panel. Switch among the three by clicking on the tabs
 to the left of the window.</para>
 
 <para>
@@ -290,10 +290,10 @@ name of the file. Use the Filesystem Browser window to open files.
 </para>
 
 <para>
-You can toggle the Documents and Filesystem Browser window on and off in
+You can toggle the Documents, Filesystem Browser and Sessions window on and off in
 <menuchoice><guimenu>Window</guimenu><guimenu>Tool Views</guimenu></menuchoice>
 menu. This menu offers you your first glimpse into &kate;'s power and
-flexibility.  In this section we'll look at three items:
+flexibility.  In this section we'll look at four items:
 </para>
 
 <variablelist>
@@ -306,19 +306,30 @@ flexibility.  In this section we'll look at three items:
 </term>
 <listitem>
 <para>
-Toggles the Documents on and off. If the Documents/Filesystem Browser side bar
-window is not open, &kate; will open the side bar window.</para>
-
+Toggles the Documents panel on and off. It will display the Documents panel in the side bar
+if another panel was shown or will toggle the side bar open or closed otherwise.
+</para>
 </listitem>
 </varlistentry>
+
 <varlistentry>
 <term><menuchoice><guimenuitem>Show/Hide
 Filesystem Browser</guimenuitem></menuchoice></term>
 <listitem>
 <para>
-Toggles the Filesystem Browser on and off. This menu item is the same as
-<guimenuitem>Show Documents</guimenuitem> with one difference.  Toggling
-it on launches the window with the Filesystem Browser on top.
+Toggles the Filesystem Browser on and off. It will display the Filesystem Browser in the side bar
+if another panel was shown or will toggle the side bar open or closed otherwise.
+</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice><guimenuitem>Show/Hide
+Sessions</guimenuitem></menuchoice></term>
+<listitem>
+<para>
+Toggles the Sessions panel on and off.  It will display the Sessions panel in the side bar
+if another panel was shown or will toggle the side bar open or closed otherwise.
 </para>
 </listitem>
 </varlistentry>
@@ -529,28 +540,6 @@ exported to the environment variable <envar>KATE_PID</envar>. When opening files
 from the built in terminal, Kate will automatically select the current instance
 if nothing else is indicated on the command line.</para>
 
-<sect2 id="old-behavior">
-<title>Restoring old style &kate; behavior</title>
-
-<para>When you get used to using sessions you will hopefully see that they
-provide a very simple and efficient tool for working in different areas.
-However, if you prefer the old &kate; behavior (one instance opens all files),
-you can easily achieve that by following this simple strategy:
-
-<itemizedlist>
-<listitem><para>Make &kate; always start with the <option>--use</option>
-parameter by adding that to the command in the application preferences,
-and additionally using a shell alias.</para></listitem>
-<listitem><para>Configure &kate; to load the last used session at startup.</para>
-</listitem>
-<listitem><para>Configure &kate; to save the file list when closing a session.
-</para></listitem>
-<listitem><para>Load the default session once</para></listitem>
-</itemizedlist>
-</para>
-
-</sect2>
-
 </sect1>
 
 <sect1 id="fundamentals-getting-help">
diff --git a/doc/kate/mdi.docbook b/doc/kate/mdi.docbook
index 6a8020747..6920adfa3 100644
--- a/doc/kate/mdi.docbook
+++ b/doc/kate/mdi.docbook
@@ -33,9 +33,10 @@ work with your documents.</para>
 windows:</para>
 
 <itemizedlist>
-<listitem><para><link linkend="kate-mdi-tools-document-list">The Document List</link></para></listitem>
+<listitem><para><link linkend="kate-mdi-tools-documents-list">The Document List</link></para></listitem>
 <listitem><para><link linkend="kate-mdi-tools-file-selector">The Filesystem
 Browser</link></para></listitem>
+<listitem><para><link linkend="kate-mdi-tools-sessions">The Sessions panel</link></para></listitem>
 <listitem><para><link linkend="kate-mdi-tools-konsole">The Built in Terminal Emulator</link></para></listitem>
 </itemizedlist>
 
@@ -94,11 +95,11 @@ for instructions on how to split the current editor.</para>
 
 </sect1>
 
-<sect1 id="kate-mdi-tools-document-list">
+<sect1 id="kate-mdi-tools-documents-list">
 <title>The Document List</title>
 
-<para><indexterm><primary>Document list</primary></indexterm>
-The document list displays a list of all documents currently open in
+<para><indexterm><primary>Documents list</primary></indexterm>
+The Documents list displays a list of all documents currently open in
 &kate;. Modified files will have a small <guiicon>floppy
 disk</guiicon> icon on their left to indicate that state.</para>
 
@@ -262,6 +263,81 @@ editing area.</para>
 
 </sect1>
 
+<sect1 id="kate-mdi-tools-sessions">
+<title>The Sessions panel</title>
+
+<para><indexterm><primary>Sessions Panel</primary></indexterm>
+The Sessions panel displays a list of all existing &kate; sessions and
+allows to manage them easily.</para>
+
+<para>The Sessions panel consists of a toolbar at the top followed by the list of known sessions.
+The active session is marked by an icon on its right.</para>
+<para>Please note that the active session and the currently selected session in the list may not be the same.
+The difference is important because most of the session commands work on the currently selected session
+and not on the active session.</para>
+
+<variablelist>
+<varlistentry>
+<term>The session toolbar</term>
+<listitem>
+<para>It contains the following toolbar buttons:</para>
+<variablelist>
+<varlistentry>
+<term><guibutton>New</guibutton></term>
+<listitem><para>Creates a new session and switch to it.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guibutton>Save</guibutton></term>
+<listitem><para>Save the current session.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guibutton>Save as</guibutton></term>
+<listitem><para>Save the selected session as a new session. A checkbox allows to choose whether to switch
+to the new session after saving or not.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guibutton>Rename</guibutton></term>
+<listitem><para>Rename the selected session.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guibutton>Delete</guibutton></term>
+<listitem><para>Delete the selected session. If the active session is deleted, a new session will
+be automatically created.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guibutton>Reload</guibutton></term>
+<listitem><para>Reload the active session from the last saved state.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guibutton>Activate</guibutton></term>
+<listitem><para>Close the active session and switch to the selected one. The same action can be
+performed by activating the selected session entry in the list using the mouse of the Enter key.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guibutton>Toggle read only</guibutton></term>
+<listitem><para>Allows to set whether the selected session is read only or not. A read only session will not change
+its properties and can't be saved, although documents can be edited and saved as normal. This option is great for
+creating template sessions.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guibutton>Move up</guibutton></term>
+<listitem><para>Move the selected session one position up in the list.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guibutton>Move down</guibutton></term>
+<listitem><para>Move the selected session one position down in the list.</para></listitem>
+</varlistentry>
+</variablelist>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>The session list</term>
+<listitem><para>A list of all existing sessions.</para></listitem>
+</varlistentry>
+</variablelist>
+
+</sect1>
 
 <sect1 id="kate-mdi-tools-konsole">
 <title>The Built in Terminal Emulator</title>
diff --git a/doc/kate/menus.docbook b/doc/kate/menus.docbook
index c25ef6d04..e238bc380 100644
--- a/doc/kate/menus.docbook
+++ b/doc/kate/menus.docbook
@@ -1126,55 +1126,60 @@ Editor...</guimenuitem></menuchoice></para></listitem>
 <title>The <guimenu>Sessions</guimenu> Menu</title>
 
 <para>This menu contains entries for using and managing &kate; sessions.
-For more information, read <link
-linkend="fundamentals-using-sessions">Using Sessions</link>.</para>
+For more information, read
+<link linkend="fundamentals-using-sessions">Using Sessions</link> and the
+<link linkend="kate-mdi-tools-sessions">Sessions panel</link>.</para>
 
 <variablelist>
-
-<varlistentry id="sessions-new">
-<term><menuchoice><guimenu>Sessions</guimenu>
-<guimenuitem>New</guimenuitem></menuchoice></term>
-<listitem><para>Creates a new empty session. All currently open files will
-be closed.</para></listitem>
-
+<varlistentry>
+<term><menuchoice><guimenu>Sessions</guimenu><guimenuitem>Select session</guimenuitem></menuchoice></term>
+<listitem><para>This submenu allows to select and switch to a given session.</para></listitem>
 </varlistentry>
-
-<varlistentry id="sessions-open">
-<term><menuchoice><guimenu>Sessions</guimenu><guimenuitem>Open...</guimenuitem>
-</menuchoice></term>
-<listitem><para>Open an existing session. The Session Chooser dialog is
-displayed to let you choose one.</para></listitem>
+<varlistentry>
+<term><menuchoice><guimenu>Sessions</guimenu><guimenuitem>New</guimenuitem></menuchoice></term>
+<listitem><para>Creates a new session and switch to it.</para></listitem>
 </varlistentry>
-
-<varlistentry id="sessions-quick-open">
-<term><menuchoice><guimenu>Sessions</guimenu><guisubmenu>Quick Open</guisubmenu>
-</menuchoice></term>
-<listitem><para>This submenu lets you open an existing session.</para>
-</listitem>
+<varlistentry>
+<term><menuchoice><guimenu>Sessions</guimenu><guimenuitem>Save</guimenuitem></menuchoice></term>
+<listitem><para>Save the current session.</para></listitem>
 </varlistentry>
-
-<varlistentry id="sessions-save">
-<term><menuchoice><guimenu>Sessions</guimenu><guimenuitem>Save</guimenuitem>
-</menuchoice></term>
-<listitem><para>Save the current session. If the session is anonymous, you will
-be prompted for a session name.</para></listitem>
+<varlistentry>
+<term><menuchoice><guimenu>Sessions</guimenu><guimenuitem>Save as</guimenuitem></menuchoice></term>
+<listitem><para>Save the selected session as a new session. A checkbox allows to choose whether to switch
+to the new session after saving or not.</para></listitem>
 </varlistentry>
-
-<varlistentry id="sessions-save-as">
-<term><menuchoice><guimenu>Sessions</guimenu><guimenuitem>Save
-As...</guimenuitem></menuchoice></term>
-<listitem><para>Save the current session under a new name. You are prompted for
-a name to use.</para></listitem>
+<varlistentry>
+<term><menuchoice><guimenu>Sessions</guimenu><guimenuitem>Rename</guimenuitem></menuchoice></term>
+<listitem><para>Rename the selected session.</para></listitem>
 </varlistentry>
-
-<varlistentry id="sessions-manage">
-<term><menuchoice><guimenu>Sessions</guimenu><guimenuitem>Manage...</guimenuitem>
-</menuchoice></term>
-<listitem><para>Displays the Session Manager dialog which allows you to rename
-and delete sessions.</para></listitem>
+<varlistentry>
+<term><menuchoice><guimenu>Sessions</guimenu><guimenuitem>Delete</guimenuitem></menuchoice></term>
+<listitem><para>Delete the selected session. If the active session is deleted, a new session will
+be automatically created.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice><guimenu>Sessions</guimenu><guimenuitem>Reload</guimenuitem></menuchoice></term>
+<listitem><para>Reload the active session from the last saved state.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice><guimenu>Sessions</guimenu><guimenuitem>Activate</guimenuitem></menuchoice></term>
+<listitem><para>Close the active session and switch to the selected one. The same action can be
+performed by activating the selected session entry in the list using the mouse of the Enter key.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice><guimenu>Sessions</guimenu><guimenuitem>Toggle read only</guimenuitem></menuchoice></term>
+<listitem><para>Allows to set whether the selected session is read only or not. A read only session will not change
+its properties and can't be saved, although documents can be edited and saved as normal. This option is great for
+creating template sessions.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice><guimenu>Sessions</guimenu><guimenuitem>Move up</guimenuitem></menuchoice></term>
+<listitem><para>Move the selected session one position up in the list.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><menuchoice><guimenu>Sessions</guimenu><guimenuitem>Move down</guimenuitem></menuchoice></term>
+<listitem><para>Move the selected session one position down in the list.</para></listitem>
 </varlistentry>
-
-
 </variablelist>
 
 </sect1>
@@ -1258,7 +1263,7 @@ Dialog.</para>
 </sect1>
 
 <sect1 id="window-menu">
-<title>the <guimenu>Window</guimenu> Menu</title>
+<title>The <guimenu>Window</guimenu> Menu</title>
 
 <variablelist>
 <varlistentry>
@@ -1366,7 +1371,7 @@ commands those will of course continue to work.</para></listitem>
 <anchor id="window-toolviews-show-filelist"/>
 <menuchoice>
 <guimenu>Window</guimenu><guisubmenu>Tool Views</guisubmenu>
-<guimenuitem>Show Documents</guimenuitem>
+<guimenuitem>Show/Hide Documents</guimenuitem>
 </menuchoice>
 </term>
 <listitem>
@@ -1389,6 +1394,19 @@ commands those will of course continue to work.</para></listitem>
 
 <varlistentry>
 <term>
+<anchor id="window-toolviews-show-sessions"/>
+<menuchoice>
+<guimenu>Window</guimenu><guisubmenu>Tool Views</guisubmenu>
+<guimenuitem>Show/Hide Sessions</guimenuitem>
+</menuchoice>
+</term>
+<listitem>
+<para>Toggle the display of &kate;'s Sessions panel</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term>
 <anchor id="window-toolviews-greptool"/>
 <menuchoice>
 <guimenu>Window</guimenu><guisubmenu>Tool Views</guisubmenu>