[kde-doc-english] [kate] doc/kate: sort sects about plugins to follow the order in plugin page in the settings dialog, add missing links
Burkhard Lück
lueck at hube-lueck.de
Sat May 7 20:41:27 UTC 2016
Git commit 77b575a6f9e310aa6feb91e535721bd670182023 by Burkhard Lück.
Committed on 07/05/2016 at 20:40.
Pushed by lueck into branch 'master'.
sort sects about plugins to follow the order in plugin page in the settings dialog, add missing links
M +1147 -1146 doc/kate/plugins.docbook
http://commits.kde.org/kate/77b575a6f9e310aa6feb91e535721bd670182023
diff --git a/doc/kate/plugins.docbook b/doc/kate/plugins.docbook
index 9021614..2a83a00 100644
--- a/doc/kate/plugins.docbook
+++ b/doc/kate/plugins.docbook
@@ -85,7 +85,7 @@ simple &gdb; frontend</para>
Search or replace patterns in opened documents or in files on disk</para>
</listitem>
<listitem>
-<para>Snippets tool view - Tool view embedding the snippets management</para>
+<para><link linkend="kate-application-plugin-snippets">Snippets tool view</link> - Tool view embedding the snippets management</para>
</listitem>
<listitem>
<para><link linkend="kate-application-plugin-sql">SQL Plugin</link> - Execute
@@ -95,7 +95,7 @@ query on SQL databases</para>
<para>Symbol Viewer - Extract and show reference symbols from source</para>
</listitem>
<listitem>
-<para>Terminal tool view - Tool view embedding a terminal widget</para>
+<para><link linkend="kate-application-plugin-konsole">Terminal tool view</link> - Tool view embedding a terminal widget</para>
</listitem>
<listitem>
<para>Text Filter - Easy text filtering</para>
@@ -107,1559 +107,1411 @@ attributes, attribute values and entities allowed by DTD</para>
</itemizedlist>
</sect1>
-<!-- from doc/kate-addons/xmlcheck.docbook -->
-<sect1 id="kate-application-plugin-xmltools">
+<sect1 id="kate-application-plugin-build">
+<!--http://kate-editor.org/2011/06/21/kate-plugin-updates-part-1/ -->
<sect1info>
-<authorgroup><author>
-&Daniel.Naber; &Daniel.Naber.mail;
-</author></authorgroup>
+<authorgroup>
+<author><firstname>Salma</firstname> <surname>Sultana</surname></author>
+<author>&TC.Hollingsworth; &TC.Hollingsworth.mail;</author>
+</authorgroup>
</sect1info>
-<title>&XML; Completion</title>
+<title>Build Plugin</title>
-<para>This plugin gives hints about what is allowed at a certain position in
-an &XML; file, according to the file's DTD. It will list possible
-elements, attributes, attribute values or entities, depending on the
-cursor position (⪚ all entities are listed if the character on the left
-of the cursor is <quote>&</quote>). It's also possible to close the nearest
-open tag on the left.</para>
+<sect2 id="build-intro">
+<title>Introduction</title>
-<para>The <acronym>DTD</acronym> must exist in &XML; format, as produced by the Perl program
-<command>dtdparse</command>. We will call a DTD in this format <quote>meta DTD</quote>.
-Some meta DTDs are supplied. They are installed in
-<filename class="directory">$KDEDIR/share/apps/katexmltools/</filename>,
-which is also the default folder when you choose
-<guimenuitem>Assign Meta DTD...</guimenuitem>.
-To produce your own meta DTDs, get <command>dtdparse</command> from
-<ulink url="http://dtdparse.sourceforge.net">http://dtdparse.sourceforge.net</ulink>.</para>
+<para>The Build plugin allows you to run actions like build, clean and compile
+on a project.</para>
-<sect2 id="xmltools-how-to-use">
-<title>How to Use</title>
+</sect2>
-<para>Start &kate; and open the configuration dialog under <menuchoice><guimenu>Settings</guimenu>
-<guimenuitem>Configure &kate;...</guimenuitem></menuchoice>.
-Then select <guilabel>&XML; Completion</guilabel> which will appear
-in the <menuchoice><guimenu>Application</guimenu>
-<guimenuitem>Plugins</guimenuitem></menuchoice> page and close the dialog. After
-that, select <menuchoice><guimenu>&XML;</guimenu><guimenuitem>Assign Meta DTD...</guimenuitem></menuchoice>.
-If your document contains no <quote>DOCTYPE</quote> or the doctype is unknown, you will have to
-select a meta DTD from the file system. Otherwise the meta DTD that
-matches the current document's DOCTYPE will be loaded automatically.</para>
+<sect2 id="build-using">
+<title>Using the Build Plugin</title>
-<para>You can now use the plugin while typing your text:</para>
+<para>The Build plugin adds a <guilabel>Build Output</guilabel> tool view at the
+bottom and a <guimenu>Build</guimenu> menu on the menubar. The tool view can be used to configure
+build target settings, while the menu can be used to perform build, clean and
+compile actions.</para>
-<variablelist>
-<varlistentry>
-<term><keycap><</keycap> (less than key)</term>
-<listitem><para>This will trigger a list of possible elements unless the
-cursor is inside a tag already. Note that you currently cannot use
-this to insert the top level element (⪚ <quote><html></quote>).</para></listitem>
-</varlistentry>
+<para>The <guilabel>Build Output</guilabel> tool view has three tabs:</para>
+
+<itemizedlist>
+<listitem><para><guilabel>Target Settings</guilabel></para></listitem>
+<listitem><para><guilabel>Output</guilabel></para></listitem>
+<listitem><para><guilabel>Errors & Warnings</guilabel></para></listitem>
+</itemizedlist>
+<sect3 id="build-using-target-settings">
+<title>Target Settings tab</title>
+
+<para>The target settings tab can be used to configure various build targets.</para>
+
+<para>Each target contains four configuration options:</para>
+
+<variablelist>
<varlistentry>
-<term><keycap><</keycap><keycap>/</keycap>(less than key + slash)</term>
-<listitem><para>Entering these characters will offer to close the current element
-(nearest open one to the left of the cursor). Press &Enter; to accept the suggestion.
-Unlike the <guimenuitem>Close Element</guimenuitem> menu item, this works only with
-a DTD assigned.</para></listitem>
+<term><guilabel>Working Directory</guilabel></term>
+<listitem><para>You can set the path to the project here. Leave this empty to
+use the directory the current document is located in.</para></listitem>
</varlistentry>
<varlistentry>
-<term><keycap>"</keycap> (quote key)</term>
-<listitem><para>The quote key will trigger a list of possible attribute
-values (if there are any) if you are inside a tag.</para></listitem>
+<term><guilabel>Build</guilabel></term>
+<listitem><para>This option lets you define the build command. It is set to
+<command>make</command> by default.</para></listitem>
</varlistentry>
<varlistentry>
-<term><keycap> </keycap> (space key)</term>
-<listitem><para>This key will trigger a list of possible attributes for the
-current element if you are inside a tag.</para>
-</listitem>
+<term><guilabel>Clean</guilabel></term>
+<listitem><para>The option lets you define the clean command. It is set to
+<command>make clean</command> by default.</para></listitem>
</varlistentry>
<varlistentry>
-<term><keycap>&</keycap> (ampersand key)</term>
-<listitem><para>This key will trigger a list of named entities.</para></listitem>
+<term><guilabel>Quick Compile</guilabel></term>
+<listitem><para>This option lets you define the quick compile command. It is set
+to <command>gcc -Wall -g %f</command> by default.</para></listitem>
</varlistentry>
</variablelist>
-</sect2>
+<para>One can create a new target by using the <guibutton>New</guibutton> button.
+The <guibutton>Copy</guibutton> button can be used to make a copy of an existing
+target. To delete a target, use the <guibutton>Delete</guibutton> button.</para>
-<sect2 id="xmltools-features-and-limitations">
-<title>Features and Limitations</title>
+</sect3>
-<para>You can test all functions and limitations by loading
-<filename>$KDEDIR/share/apps/katexmltools/testcases.xml</filename><!--FIXME replacement for KDEDIRS-->
-into &kate; and following the instructions.</para>
+<sect3 id="build-using-output">
+<title>Output tab</title>
-</sect2>
+<para>The <guilabel>Output</guilabel> tab shows the console output generated by
+the last command.</para>
+</sect3>
-<sect2 id="xmltools-menu">
+<sect3 id="buiid-using-errors">
+<title>Errors & Warnings</title>
+
+<para>The <guilabel>Errors & Warnings</guilabel> tab lists the errors and
+warnings generated by the last command.</para>
+
+<para>Each line contains a message and the file name and line number if available.
+Clicking on the error or warning takes you to the appropriate file and places
+the cursor on the corresponding line number.</para>
+
+<para>There are <guibutton>Errors</guibutton>, <guibutton>Warnings</guibutton>,
+and <guibutton>Others</guibutton> buttons at the top that allow you to show
+or hide those categories of output.</para>
+
+<!--FIXME: These shortcuts now seem to be used by the Project plugin in 4.11.
+ https://bugs.kde.org/show_bug.cgi?id=328170 -->
+<para>To navigate to the previous error, press
+<keycombo action="simul">&Ctrl;&Alt;<keysym>Left</keysym></keycombo>.
+To navigate to the next error, press
+<keycombo action="simul">&Ctrl;&Alt;<keysym>Right</keysym></keycombo>.</para>
+
+</sect3>
+</sect2>
+
+<sect2 id="build-menu">
<title>Menu Structure</title>
-<variablelist id="xml-insert-element">
+<variablelist id="build-build">
<varlistentry>
<term><menuchoice>
-<shortcut>
-<keycombo action="simul">&Ctrl;<keycap>Return</keycap></keycombo>
-</shortcut>
-<guimenu>&XML;</guimenu>
-<guimenuitem>Insert Element...</guimenuitem>
+<guimenu>Build</guimenu><guimenuitem>Build</guimenuitem>
</menuchoice></term>
-<listitem><para>This will open a dialog that lets you insert an &XML; element.
-The <, > characters and the closing tag will be inserted automatically.
-If you have selected text when this menu item is selected, the selected
-text will be surrounded by the opening and the closing tag.
-The dialog also offers completion of all elements that may be inserted
-at the current cursor position if you have assigned a meta DTD by
-using <guimenuitem>Assign Meta DTD...</guimenuitem>.
-</para></listitem>
+<listitem><para>Runs the <guilabel>Build</guilabel> command for the currently
+selected target.</para></listitem>
</varlistentry>
-<varlistentry id="xml-close-element">
+<varlistentry id="build-clean">
<term><menuchoice>
-<shortcut>
-<keycombo action="simul">&Ctrl;<keycap><</keycap></keycombo>
-</shortcut>
-<guimenu>&XML;</guimenu>
-<guimenuitem>Close Element</guimenuitem>
+<guimenu>Build</guimenu><guimenuitem>Clean</guimenuitem>
</menuchoice></term>
-<listitem><para>This will search your text for a tag that is not yet closed
-and will close it by inserting the corresponding closing tag.
-The search starts at the cursor position and goes left. If
-it cannot find an open tag nothing will happen.</para></listitem>
+<listitem><para>Runs the <guilabel>Clean</guilabel> command for the currently
+selected target.</para></listitem>
</varlistentry>
-<varlistentry id="xml-assign-metadtd">
+<varlistentry id="build-compile">
<term><menuchoice>
-<guimenu>&XML;</guimenu>
-<guimenuitem>Assign Meta DTD...</guimenuitem>
+<guimenu>Build</guimenu><guimenuitem>Quick Compile</guimenuitem>
</menuchoice></term>
-<listitem><para>This will tell the plugin which meta DTD to use for the
-current document. Note that this assignment will not be saved.
-You will have to repeat it when you start &kate; the next time.</para></listitem>
+<listitem><para>Runs the <guilabel>Quick Compile</guilabel> command for the
+currently selected target.</para></listitem>
</varlistentry>
-</variablelist>
-</sect2>
+<varlistentry id="build-previous-error">
+<term><menuchoice>
+<shortcut><keycombo action="simul">&Ctrl;&Alt;<keysym>Left</keysym></keycombo></shortcut>
+<guimenu>Build</guimenu><guimenuitem>Previous Error</guimenuitem>
+</menuchoice></term>
+<listitem><para>Moves the cursor to the location of the previous error in the
+document.</para></listitem>
+</varlistentry>
-<sect2 id="xmltools-thanks-and-acknowledgements">
-<title>Thanks and Acknowledgments</title>
-<para>
-&kate; Plugin <quote>&XML; Completion</quote> copyright 2001,2002 &Daniel.Naber;
-&Daniel.Naber.mail;.
-</para>
-<para>KDE SC 4 version copyright 2010 Tomáš Trnka</para>
-<para>Documentation copyright 2001,2002 &Daniel.Naber;</para>
-</sect2>
-</sect1>
+<varlistentry id="build-next-error">
+<term><menuchoice>
+<shortcut><keycombo action="simul">&Ctrl;&Alt;<keysym>Right</keysym></keycombo></shortcut>
+<guimenu>Build</guimenu><guimenuitem>Next Error</guimenuitem>
+</menuchoice></term>
+<listitem><para>Moves the cursor to the location of the next error in the
+document.</para></listitem>
+</varlistentry>
-<sect1 id="kate-application-plugin-searchinfiles">
-<sect1info>
-<authorgroup><author>
-&TC.Hollingsworth; &TC.Hollingsworth.mail;
-</author></authorgroup>
-</sect1info>
-<title>Search & Replace</title>
+<varlistentry>
+<term><menuchoice id="build-targets">
+<guimenu>Build</guimenu><guisubmenu>Targets</guisubmenu>
+</menuchoice></term>
+<listitem><para>Select from a list of targets configured by the user.</para></listitem>
+</varlistentry>
-<sect2 id="searchinfiles-intro">
-<title>Introduction</title>
-<para>&kappname;'s Search & Replace plugin allows you to search for text or
-<ulink url="help:/katepart/regular-expressions.html">regular expressions</ulink>
-in many different files at once. You can search all open files, all the files
-in one directory and optionally its subdirectories, or all files in the current
-project. You can even filter by filename, for instance searching only files
-that end with a particular file extension.</para>
+<varlistentry>
+<term><menuchoice id="build-next-target">
+<guimenu>Build</guimenu><guimenuitem>Next Target</guimenuitem>
+</menuchoice></term>
+<listitem><para>Switch to the next target configured by the user.</para></listitem>
+</varlistentry>
+</variablelist>
</sect2>
-<sect2 id="searchinfiles-ui">
-<title>Interface</title>
+<sect2 id="build-ack">
+<title>Thanks and Acknowledgments</title>
+<para>The &kate; Build Plugin was written by Kåre Särs.</para>
+<para>Special thanks to Google Code-In 2011 participant Salma Sultana for
+writing much of this section.</para>
+</sect2>
+</sect1>
-<sect3 id="searchinfiles-ui-query">
-<title>Search Query</title>
+<sect1 id="kate-application-plugin-fsbrowser">
-<para>The following options are always displayed at the top of the Search in
-Files tool view:</para>
+<title>Filesystem Browser</title>
-<variablelist>
+<para>The Filesystem Browser is a folder viewer, allowing you to open
+files from a displayed folder in the current frame.</para>
-<varlistentry>
-<term><guiicon>New Tab</guiicon></term>
-<listitem><para>
-You can have as many searches as you want open at the same time. Simply click
-the <guibutton>New Tab</guibutton> button at the top-left corner of the Search
-tool view and a new results tab will open permitting you to perform another
-search.
-</para></listitem>
-</varlistentry>
+<sect2 id="fsbrowser-menu">
+<title>Menu Structure</title>
+<variablelist>
-<varlistentry>
-<term><guiicon>Toggle Results</guiicon></term>
-<listitem><para>
-The down arrow in the top right-corner of the Search in Files tool view will
-toggle the bottom half of the tool view between displaying additional options
-for the Search in Folder mode and the results of your search.
-</para></listitem>
+<varlistentry id="view-toolviews-show-filebrowser">
+<term><menuchoice>
+<guimenu>View</guimenu><guisubmenu>Tool Views</guisubmenu>
+<guimenuitem>Show Filesystem Browser</guimenuitem>
+</menuchoice></term>
+<listitem>
+<para>Toggle the display of &kate;'s Filesystem Browser.</para>
+</listitem>
</varlistentry>
-<varlistentry>
-<term><guilabel>Find</guilabel></term>
-<listitem><para>
-This is where you type in what you want to find. You may enter standard text,
-or a regular expression if enabled.
-</para></listitem>
-</varlistentry>
+</variablelist>
+</sect2>
-<varlistentry>
-<term><guilabel>Replace</guilabel> (text box)</term>
-<listitem><para>
-Replacement text that will be added to file(s) in place of the text in the
-<guilabel>Find</guilabel> text box.
-</para></listitem>
-</varlistentry>
+<sect2 id="fsbrowser-interface">
+<title>Interface</title>
-<varlistentry>
-<term><guibutton>Search</guibutton></term>
-<listitem><para>
-When you've finished configuring everything, just press the
-<guibutton>Search</guibutton> button to perform your search. You may also press
-&Enter; in the <guilabel>Find</guilabel> text box to do the same.
-</para></listitem>
-</varlistentry>
+<para>From the top down, the Filesystem Browser consists of the following
+elements:</para>
+<variablelist>
<varlistentry>
-<term><guibutton>Replace</guibutton></term>
-<listitem><para>
-When you've finished configuring everything, just press the
-<guibutton>Replace</guibutton> button to replace the text entered in the
-<guilabel>Find</guilabel> text box with that of the <guilabel>Replace</guilabel>
-text box. You may also press &Enter; in the <guilabel>Replace</guilabel> text
-box to do the same.
-</para></listitem>
-</varlistentry>
-
+<term>A Toolbar</term>
+<listitem>
+<para>This contains standard navigations tool buttons:</para>
+<variablelist>
<varlistentry>
-<term><guibutton>Next</guibutton></term>
-<listitem><para>
-Go to the next match of your search query, switching files if necessary.
-</para></listitem>
+<term><guibutton>Back</guibutton></term>
+<listitem><para>Causes the folder view to <command>cd</command> to the previously displayed folder in the history.
+This button is disabled, if there is no previous item.</para></listitem>
</varlistentry>
-
<varlistentry>
-<term><guibutton>Replace checked</guibutton></term>
-<listitem><para>
-The same as <guibutton>Replace</guibutton>, but will only perform replacements
-in files that are checked in the pane below.
-</para></listitem>
+<term><guibutton>Forward</guibutton></term>
+<listitem><para>Causes the folder view to <command>cd</command> to the next folder in the history.
+This button is disabled, if there is no next folder.</para></listitem>
</varlistentry>
-
-</variablelist>
-</sect3>
-
-<sect3 id="searchinfiles-ui-folder">
-<title>Search in Folder Options</title>
-
-<para>These options are displayed below the aforementioned query options. If search
-results are being displayed instead, press the <guiicon>Toggle Results</guiicon>
-button to display them.</para>
-
-<variablelist>
-
+<!--varlistentry>
+<term><guibutton>Parent Folder</guibutton></term>
+<listitem><para>This will cause the folder view to <command>cd</command> to the immediate parent of the currently displayed
+folder if possible.</para></listitem>
+</varlistentry-->
<varlistentry>
-<term><guilabel>Match case</guilabel></term>
-<listitem><para>
-Restricts search results to only those that have the exact same combination
-of upper and lower case letters as your search query.
-</para></listitem>
+<term><guibutton>Bookmarks</guibutton></term>
+<listitem><para>Opens a submenu to edit or add bookmarks and to add a new bookmark folder.</para></listitem>
</varlistentry>
-
<varlistentry>
-<term><guilabel>Regular expressions</guilabel></term>
-<listitem><para>
-Permits you to use <ulink url="help:/katepart/regular-expressions.html">regular
-expressions</ulink> instead of simple text as your search query.
-</para></listitem>
+<term><guibutton>Current Document Folder</guibutton></term>
+<listitem><para>This button will cause the folder view to
+<command>cd</command> to the folder of the currently active
+document if possible. This button is disabled, if the active document
+is a new, unsaved file, or the folder in which it resides can not
+be decided.</para></listitem>
</varlistentry>
-
<varlistentry>
-<term><guilabel>Expand results</guilabel></term>
-<listitem><para>
-Display all the results found in each file, instead of just a list of files
-that contain the search query.
-</para></listitem>
-</varlistentry>
-
+<term><guibutton>Options</guibutton></term>
+<listitem>
+<variablelist>
<varlistentry>
-<term><guilabel>Search</guilabel></term>
-<listitem><para>
-This has three options. Select <guilabel>in Open files</guilabel> to search all
-files currently open in &kappname;. Select <guilabel>in Folder</guilabel> to
-search inside a folder and optionally its subfolders. Select <guilabel>in
-Project</guilabel> to search all the files listed in the currently open project.
-</para></listitem>
+<term><guimenuitem>Short View</guimenuitem></term>
+<listitem><para>Displays only the filenames.</para></listitem>
</varlistentry>
-
<varlistentry>
-<term><guilabel>Folder</guilabel></term>
-<listitem><para>
-You may enter the path of the folder you wish to search. For instance, you might
-enter <userinput>~/development/kde/kate/</userinput> if you wished to search the
-&kate; source code. This option is only available when using
-<guilabel>in Folder</guilabel> mode.
-</para></listitem>
+<term><guimenuitem>Detailed View</guimenuitem></term>
+<listitem><para>Displays <guilabel>Name</guilabel>, <guilabel>Date</guilabel>,
+<guilabel>Size</guilabel> and <guilabel>Type</guilabel> of the files.</para></listitem>
</varlistentry>
-
<varlistentry>
-<term><guiicon>Open file dialog</guiicon></term>
-<listitem><para>
-Press this button to locate the folder in your desktop's folder browser. This
-button only works when using <guilabel>in Folder</guilabel> mode.
-</para></listitem>
+<term><guimenuitem>Tree View</guimenuitem></term>
+<listitem><para>Like Short View, but folders can be expanded to view their contents.</para></listitem>
</varlistentry>
-
<varlistentry>
-<term><guiicon>Up</guiicon></term>
-<listitem><para>
-Press this button to change <guilabel>Folder</guilabel> to the parent of the
-currently selected folder. This button only works when using
-<guilabel>in Folder</guilabel> mode.
-</para></listitem>
+<term><guimenuitem>Detailed Tree View</guimenuitem></term>
+<listitem><para>This also allows folders to be expanded, but displays the additional columns
+available in Detailed View.</para></listitem>
</varlistentry>
-
<varlistentry>
-<term><guiicon>Restore Current Folder</guiicon></term>
-<listitem><para>
-This button will set the <guilabel>Folder</guilabel> entry to the folder in which
-the currently open document is located. This button only works when using
-<guilabel>in Folder</guilabel> mode.
-</para></listitem>
+<term><guimenuitem>Show Hidden Files</guimenuitem></term>
+<listitem><para>Displays files normally hidden by your &OS;.</para></listitem>
</varlistentry>
-
<varlistentry>
-<term><guilabel>Filter</guilabel></term>
-<listitem><para>
-This permits you to only search filenames that match a particular pattern. For
-instance, to only search files written in C++, change it to
-<userinput>*.cpp</userinput>. To search only files beginning with
-<literal>kate</literal>, change it to <userinput>kate*</userinput>. You can
-enter multiple filters separated with a comma (<userinput>,</userinput>). This
-option is not available when using <guilabel>in Open files</guilabel> mode.
-</para></listitem>
+<term><guimenuitem>Automatically synchronize with current document</guimenuitem></term>
+<listitem><para>When this option is enabled the filesystem browser will automatically <command>cd</command>
+to the folder of the document currently open in the editing area every time it changes.</para></listitem>
</varlistentry>
-
-<varlistentry>
-<term><guilabel>Exclude</guilabel></term>
-<listitem><para>
-The opposite of <guilabel>Filter</guilabel>, this prevents &kappname; from
-searching files that match the specified patterns. As with
-<guilabel>Filter</guilabel>, you can enter multiple patterns separated with a
-comma (<userinput>,</userinput>). This option is not available when using
-<guilabel>in Open files</guilabel> mode.
-</para></listitem>
+</variablelist>
+</listitem>
+</varlistentry>
+</variablelist>
+</listitem>
</varlistentry>
<varlistentry>
-<term><guilabel>Recursive</guilabel></term>
-<listitem><para>
-If this option is enabled, &kappname; will also search in all subfolders of the
-selected folder. This option is only available when using
-<guilabel>in Folder</guilabel> mode.
-</para></listitem>
+<term>A Location Entry</term>
+<listitem>
+<para>This displays a breadcrumb navigation to the currently open folder, similarly to
+&dolphin;. You can click on a any folder to browse to it, or click on one of the
+arrows to the left of a folder to select any folders beneath it. You may also
+select from your list of Places by clicking the leftmost icon in the breadcrumb
+navigation, which displays an icon that represents your current Place.</para>
+
+<para>You can also click to the right of the breadcrumbs to change them to a text box
+where you can type the path of a folder to browse. The &URL;
+entry maintains a list of previously typed paths. To choose one, use
+the arrow button to the right of the entry.</para>
+<tip><para>The &URL; entry has folder auto-completion. The completion
+method can be set using the &RMB; menu of the text
+entry.</para></tip>
+</listitem>
</varlistentry>
<varlistentry>
-<term><guilabel>Include hidden</guilabel></term>
-<listitem><para>
-If this option is enabled, &kappname; will also search in files or folders that
-are typically hidden by your &OS;. This option is only available when using
-<guilabel>in Folder</guilabel> mode.
-</para></listitem>
+<term>A Folder View</term>
+<listitem><para>This is a standard &kde; folder view.</para></listitem>
</varlistentry>
<varlistentry>
-<term><guilabel>Follow symbolic links</guilabel></term>
-<listitem><para>
-The Search in Files plugin typically doesn't follow
-<ulink url="http://en.wikipedia.org/wiki/Symbolic_link">symbolic links</ulink>.
-When this option is enabled, the plugin will follow them instead and search inside
-the files or folders they reference. This option is only available when using
-<guilabel>in Folder</guilabel> mode.
-</para>
-<warning><para>It's possible for symbolic links to reference a folder that is the
-parent of the folder currently being searched, or other folders that contain
-symbolic links to their parent. If there is such a link in the folder being
-searched and this option is enabled, &kappname; will repeatedly follow the link
-and search the folder, and the search will never complete.</para></warning>
+<term>A Filter Entry</term>
+<listitem>
+<para>The Filter entry allows you to enter a filter for the files
+displayed in the folder view. The filter uses standard globs; patterns
+must be separated by white space. Example: <userinput>*.cpp *.h
+*.moc</userinput></para>
+<para>To display all files, enter a single asterisk
+<userinput>*</userinput>.</para>
+<para>The filter entry saves the last 10 filters entered between
+sessions. To use one, press the arrow button on the right of the entry
+and select the desired filter string. You can disable the filter by pressing
+the <guibutton>Clear text</guibutton> button to the left of the autocompletion
+arrow button.</para>
</listitem>
</varlistentry>
+</variablelist>
+</sect2>
+
+
+<sect2 id="fsbrowser-config">
+<title>Configuration</title>
+
+<para>This plugin can be configured on the <guilabel>Filesystem Browser</guilabel> page
+of <link linkend="configuring-kate-configdialog">&kate;'s configuration</link>.</para>
+
+<variablelist>
<varlistentry>
-<term><guilabel>Include binary files</guilabel></term>
-<listitem><para>
-If enabled, &kappname; will also search in files that do not appear to be text
-files.
-</para></listitem>
+<term><guilabel>Toolbar</guilabel></term>
+<listitem><para>Configure the buttons on the Filesystem Browser toolbar
+by moving the ones you want enabled to the <guilabel>Selected Actions</guilabel>
+list, and order them using the arrow buttons at the side of the list.</para>
+ </listitem>
</varlistentry>
</variablelist>
-</sect3>
+</sect2>
+</sect1>
-<sect3 id="searchinfiles-ui-results">
-<title>Search Results</title>
+<sect1 id="kate-application-plugin-gdb">
+<!--http://kate-editor.org/2011/06/23/kate-plugin-updates-part-2/-->
+<sect1info>
+<authorgroup>
+<author><firstname>Martin</firstname> <surname>Gergov</surname></author>
+<author>&TC.Hollingsworth; &TC.Hollingsworth.mail;</author>
+</authorgroup>
+</sect1info>
+<title>&gdb; Plugin</title>
-<para>The results of your search are displayed below the query options. If
-options for Search in Folder mode are displayed, simply press the
-<guiicon>Toggle Results</guiicon> button to display them. They will also
-automatically be displayed as soon as a search is performed.</para>
+<sect2 id="gdb-intro">
+<title>Introduction</title>
-<para>The search results display a list of files that contains text that matches
-your search query, followed by the number of matches found in that file.</para>
+<para>&kappname;'s &gdb; plugin provides a simple frontend to the popular &GNU;
+Project Debugger.</para>
-<para>To see a list of matches in that file, simply click the expansion arrow
-to the left of the file name. (If you selected the <guilabel>Expand
-results</guilabel> option, this will already be done for you.) The line number
-each match is found on will be displayed, followed by the contents of that line,
-with your search query indicated in bold text.</para>
+<important>
+<para>Previous experience with &gdb; is strongly recommended. For more
+information on using &gdb;, visit <ulink url="http://www.gnu.org/s/gdb/">the
+&gdb; website</ulink>.</para>
+</important>
-<para>To open the file your result was found in, simply double-click it. &kappname;
-will open the file if needed. You can also move the cursor to the location of
-a particular match by double-clicking on its listing instead of the file name.
+<para>You can enable the &gdb; plugin in
+<link linkend="config-dialog-plugins">the Plugins section of &kappname;'s
+configuration</link>.</para>
+
+<para>For the plugin to work properly, you must have a source file (of any type
+supported by &gdb;) and an executable.</para>
+
+<tip>
+<para>If you compile using &gcc;/<command>g++</command> you might want to use
+the <command><parameter>-ggdb</parameter></command> command line argument.
</para>
+</tip>
+
+<para>After these preparations are made, open the source file in &kappname;,
+enter the path to the executable in the <guilabel>Settings</guilabel> tab of the
+<guilabel>Debug View</guilabel> tool view, and select
+<menuchoice><guimenu>Debug</guimenu><guimenuitem>Start Debugging</guimenuitem></menuchoice>
+from the menu to get started.</para>
-</sect3>
</sect2>
-<sect2 id="searchinfiles-menu">
-<title>Menu Structure</title>
+<sect2 id="gdb-menus">
+<title>Menu and Toolbar Structure</title>
+
+<para>All of these options are available in &kappname;'s menus, and many are
+available on the Debug toolbar as well.</para>
<variablelist>
-<varlistentry id="edit-searchinfiles">
+<varlistentry id="gdb-menus-show-debug-view">
<term><menuchoice>
-<guimenu>Edit</guimenu>
-<guimenuitem>Search in Files</guimenuitem>
+<guimenu>View</guimenu><guisubmenu>Tool View</guisubmenu><guimenuitem>Show Debug View</guimenuitem>
</menuchoice></term>
-<listitem>
-<para>Launches the Search and Replace tool view.</para>
-</listitem>
+<listitem><para>Shows a tool view containing &gdb; output, the &gdb; command
+line used, and other settings.</para></listitem>
</varlistentry>
-<varlistentry id="edit-next-match">
+<varlistentry id="gdb-menus-show-locals">
<term><menuchoice>
-<guimenu>Edit</guimenu>
-<guimenuitem>Go to Next Match</guimenuitem>
+<guimenu>View</guimenu><guisubmenu>Tool View</guisubmenu><guimenuitem>Show Locals</guimenuitem>
</menuchoice></term>
-<listitem>
-<para>Go to the next match in a search performed by the Search and Replace
-plugin.</para>
-</listitem>
+<listitem><para>Shows a list of all currently loaded variables and their values.
+</para></listitem>
</varlistentry>
-<varlistentry id="edit-previous-match">
+<varlistentry id="gdb-menus-show-call-stack">
<term><menuchoice>
-<guimenu>Edit</guimenu>
-<guimenuitem>Go to Previous Match</guimenuitem>
+<guimenu>View</guimenu><guisubmenu>Tool View</guisubmenu><guimenuitem>Show Call Stack</guimenuitem>
</menuchoice></term>
-<listitem>
-<para>Go to the previous match in a search performed by the Search and Replace
-plugin.</para>
-</listitem>
+<listitem><para>Shows a &gdb; backtrace.</para></listitem>
</varlistentry>
-<varlistentry id="view-toolviews-searchandreplace">
+<varlistentry id="gdb-menus-targets">
<term><menuchoice>
-<guimenu>View</guimenu><guisubmenu>Tool Views</guisubmenu>
-<guimenuitem>Show Search and Replace</guimenuitem>
+<guimenu>Debug</guimenu><guisubmenu>Targets</guisubmenu>
</menuchoice></term>
-<listitem>
-<para>Toggle the display of &kappname;'s <guilabel>Search and Replace</guilabel> tool.
-</para>
-</listitem>
+<listitem><para>A submenu containing a list of targets (executables).
+</para></listitem>
</varlistentry>
-</variablelist>
+<varlistentry id="gdb-menus-arg-lists">
+<term><menuchoice>
+<guimenu>Debug</guimenu><guisubmenu>Arg Lists</guisubmenu>
+</menuchoice></term>
+<listitem><para>A submenu containing all argument lists.</para></listitem>
+</varlistentry>
-</sect2>
-</sect1>
+<varlistentry id="gdb-menus-start">
+<term><menuchoice>
+<guimenu>Debug</guimenu><guimenuitem>Start Debugging</guimenuitem>
+</menuchoice></term>
+<listitem><para>Starts &gdb; with a target.</para></listitem>
+</varlistentry>
-<sect1 id="kate-application-plugin-fsbrowser">
+<varlistentry id="gdb-menus-kill">
+<term><menuchoice>
+<guimenu>Debug</guimenu><guimenuitem>Kill / Stop Debugging</guimenuitem>
+</menuchoice></term>
+<listitem><para>Stops &gdb;.</para></listitem>
+</varlistentry>
-<title>Filesystem Browser</title>
+<varlistentry id="gdb-menus-restart">
+<term><menuchoice>
+<guimenu>Debug</guimenu><guimenuitem>Restart Debugging</guimenuitem>
+</menuchoice></term>
+<listitem><para>Restarts &gdb;.</para></listitem>
+</varlistentry>
-<para>The Filesystem Browser is a folder viewer, allowing you to open
-files from a displayed folder in the current frame.</para>
+<varlistentry id="gdb-menus-break">
+<term><menuchoice>
+<guimenu>Debug</guimenu><guimenuitem>Toggle Breakpoint / Break</guimenuitem>
+</menuchoice></term>
+<listitem><para>Set a breakpoint at the current cursor position.
+</para></listitem>
+</varlistentry>
-<sect2 id="fsbrowser-menu">
-<title>Menu Structure</title>
-<variablelist>
+<varlistentry id="gdb-menus-step-in">
+<term><menuchoice>
+<guimenu>Debug</guimenu><guimenuitem>Step In</guimenuitem>
+</menuchoice></term>
+<listitem><para>Execute the present statement (function call will be debugged).
+</para></listitem>
+</varlistentry>
-<varlistentry id="view-toolviews-show-filebrowser">
+<varlistentry id="gdb-menus-step-over">
<term><menuchoice>
-<guimenu>View</guimenu><guisubmenu>Tool Views</guisubmenu>
-<guimenuitem>Show Filesystem Browser</guimenuitem>
+<guimenu>Debug</guimenu><guimenuitem>Step Over</guimenuitem>
</menuchoice></term>
-<listitem>
-<para>Toggle the display of &kate;'s Filesystem Browser.</para>
-</listitem>
+<listitem><para>Execute the present statement (function call will not be
+debugged).</para></listitem>
+</varlistentry>
+
+<varlistentry id="gdb-menus-step-out">
+<term><menuchoice>
+<guimenu>Debug</guimenu><guimenuitem>Step Out</guimenuitem>
+</menuchoice></term>
+<listitem><para>Resumes execution until the program that is executing
+terminates.</para></listitem>
+</varlistentry>
+
+<varlistentry id="gdb-menus-move-pc">
+<term><menuchoice>
+<guimenu>Debug</guimenu><guimenuitem>Move PC</guimenuitem>
+</menuchoice></term>
+<listitem><para>Move program counter (next execution).</para></listitem>
+</varlistentry>
+
+<varlistentry id="gdb-menus-run-to-cursor">
+<term><menuchoice>
+<guimenu>Debug</guimenu><guimenuitem>Run To Cursor</guimenuitem>
+</menuchoice></term>
+<listitem><para>Runs the program until it reaches current cursor position.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="gdb-menus-continue">
+<term><menuchoice>
+<guimenu>Debug</guimenu><guimenuitem>Continue</guimenuitem>
+</menuchoice></term>
+<listitem><para>Ignores any breakpoints and executes program until it terminates
+(successfully or not).</para></listitem>
+</varlistentry>
+
+<varlistentry id="gdb-menus-print-value">
+<term><menuchoice>
+<guimenu>Debug</guimenu><guimenuitem>Print Value</guimenuitem>
+</menuchoice></term>
+<listitem><para>Prints the value of the variable that the cursor is currently
+pointing to.</para></listitem>
+</varlistentry>
+
+<varlistentry id="gdb-menus-toolbar">
+<term><menuchoice>
+<guimenu>Settings</guimenu><guisubmenu>Toolbars Shown</guisubmenu><guimenuitem>&gdb; Plugin</guimenuitem>
+</menuchoice></term>
+<listitem><para>Display the debugging toolbar.</para></listitem>
</varlistentry>
</variablelist>
+
</sect2>
-<sect2 id="fsbrowser-interface">
-<title>Interface</title>
+<sect2 id="gdb-debug-view">
+<title>Debug View</title>
-<para>From the top down, the Filesystem Browser consists of the following
-elements:</para>
+<para>The <guilabel>Debug View</guilabel> tool view consists of several tabs:
+</para>
<variablelist>
+
<varlistentry>
-<term>A Toolbar</term>
+<term><guilabel>&gdb; Output</guilabel></term>
<listitem>
-<para>This contains standard navigations tool buttons:</para>
-<variablelist>
-<varlistentry>
-<term><guibutton>Back</guibutton></term>
-<listitem><para>Causes the folder view to <command>cd</command> to the previously displayed folder in the history.
-This button is disabled, if there is no previous item.</para></listitem>
-</varlistentry>
-<varlistentry>
-<term><guibutton>Forward</guibutton></term>
-<listitem><para>Causes the folder view to <command>cd</command> to the next folder in the history.
-This button is disabled, if there is no next folder.</para></listitem>
-</varlistentry>
-<!--varlistentry>
-<term><guibutton>Parent Folder</guibutton></term>
-<listitem><para>This will cause the folder view to <command>cd</command> to the immediate parent of the currently displayed
-folder if possible.</para></listitem>
-</varlistentry-->
-<varlistentry>
-<term><guibutton>Bookmarks</guibutton></term>
-<listitem><para>Opens a submenu to edit or add bookmarks and to add a new bookmark folder.</para></listitem>
-</varlistentry>
-<varlistentry>
-<term><guibutton>Current Document Folder</guibutton></term>
-<listitem><para>This button will cause the folder view to
-<command>cd</command> to the folder of the currently active
-document if possible. This button is disabled, if the active document
-is a new, unsaved file, or the folder in which it resides can not
-be decided.</para></listitem>
+<para>Contains output from &gdb; and a &gdb; command line.</para>
+
+<screenshot id="screenshot-gdb-output">
+<screeninfo>The Output Tab</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="gdb-output.png" format="PNG"/></imageobject>
+<textobject><phrase>The Output tab.</phrase></textobject>
+<caption><para>The <guilabel>Output</guilabel> tab displaying the output from a
+debugging session.</para></caption>
+</mediaobject>
+</screenshot>
+
+</listitem>
</varlistentry>
+
<varlistentry>
-<term><guibutton>Options</guibutton></term>
+<term><guilabel>Settings</guilabel></term>
<listitem>
<variablelist>
+
<varlistentry>
-<term><guimenuitem>Short View</guimenuitem></term>
-<listitem><para>Displays only the filenames.</para></listitem>
-</varlistentry>
-<varlistentry>
-<term><guimenuitem>Detailed View</guimenuitem></term>
-<listitem><para>Displays <guilabel>Name</guilabel>, <guilabel>Date</guilabel>,
-<guilabel>Size</guilabel> and <guilabel>Type</guilabel> of the files.</para></listitem>
+<term><guilabel>Target</guilabel></term>
+<listitem><para>Path to the target (executable) for debugging.</para></listitem>
</varlistentry>
+
<varlistentry>
-<term><guimenuitem>Tree View</guimenuitem></term>
-<listitem><para>Like Short View, but folders can be expanded to view their contents.</para></listitem>
+<term><guilabel>Working Directory</guilabel></term>
+<listitem><para>The current working directory provided to the target.
+</para></listitem>
</varlistentry>
+
<varlistentry>
-<term><guimenuitem>Detailed Tree View</guimenuitem></term>
-<listitem><para>This also allows folders to be expanded, but displays the additional columns
-available in Detailed View.</para></listitem>
+<term><guilabel>Arg List</guilabel></term>
+<listitem><para>Arguments passed to the program.</para></listitem>
</varlistentry>
+
<varlistentry>
-<term><guimenuitem>Show Hidden Files</guimenuitem></term>
-<listitem><para>Displays files normally hidden by your &OS;.</para></listitem>
+<term><guilabel>Keep focus</guilabel></term>
+<listitem><para>Keeps focus on the &gdb; command line.</para></listitem>
</varlistentry>
+
<varlistentry>
-<term><guimenuitem>Automatically synchronize with current document</guimenuitem></term>
-<listitem><para>When this option is enabled the filesystem browser will automatically <command>cd</command>
-to the folder of the document currently open in the editing area every time it changes.</para></listitem>
-</varlistentry>
-</variablelist>
-</listitem>
+<term><guilabel>Redirect IO</guilabel></term>
+<listitem><para>Opens a new <guilabel>IO</guilabel> tab in the <guilabel>Debug
+View</guilabel> where you can view output and provide input to the running
+program.</para></listitem>
</varlistentry>
+
</variablelist>
-</listitem>
-</varlistentry>
-<varlistentry>
-<term>A Location Entry</term>
-<listitem>
-<para>This displays a breadcrumb navigation to the currently open folder, similarly to
-&dolphin;. You can click on a any folder to browse to it, or click on one of the
-arrows to the left of a folder to select any folders beneath it. You may also
-select from your list of Places by clicking the leftmost icon in the breadcrumb
-navigation, which displays an icon that represents your current Place.</para>
+<screenshot id="screenshot-gdb-settings">
+<screeninfo>The Settings Tab</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="gdb-settings.png" format="PNG"/></imageobject>
+<textobject><phrase>The Settings tab.</phrase></textobject>
+<caption><para>The <guilabel>Settings</guilabel> tab displaying the configuration
+of a debugging session.</para></caption>
+</mediaobject>
+</screenshot>
-<para>You can also click to the right of the breadcrumbs to change them to a text box
-where you can type the path of a folder to browse. The &URL;
-entry maintains a list of previously typed paths. To choose one, use
-the arrow button to the right of the entry.</para>
-<tip><para>The &URL; entry has folder auto-completion. The completion
-method can be set using the &RMB; menu of the text
-entry.</para></tip>
</listitem>
</varlistentry>
<varlistentry>
-<term>A Folder View</term>
-<listitem><para>This is a standard &kde; folder view.</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term>A Filter Entry</term>
+<term><guilabel>IO</guilabel></term>
<listitem>
-<para>The Filter entry allows you to enter a filter for the files
-displayed in the folder view. The filter uses standard globs; patterns
-must be separated by white space. Example: <userinput>*.cpp *.h
-*.moc</userinput></para>
-<para>To display all files, enter a single asterisk
-<userinput>*</userinput>.</para>
-<para>The filter entry saves the last 10 filters entered between
-sessions. To use one, press the arrow button on the right of the entry
-and select the desired filter string. You can disable the filter by pressing
-the <guibutton>Clear text</guibutton> button to the left of the autocompletion
-arrow button.</para>
+<para>Contains an area that displays output from the running program and a
+command line where you may provide input to it.</para>
+
+<screenshot id="screenshot-gdb-io">
+<screeninfo>The IO Tab</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="gdb-io.png" format="PNG"/></imageobject>
+<textobject><phrase>The IO tab.</phrase></textobject>
+<caption><para>The <guilabel>IO</guilabel> tab displaying output from a simple
+test program.</para></caption>
+</mediaobject>
+</screenshot>
+
</listitem>
</varlistentry>
</variablelist>
-</sect2>
+</sect2>
-<sect2 id="fsbrowser-config">
-<title>Configuration</title>
+<sect2 id="gdb-other">
+<title>Call Stack and Locals</title>
-<para>This plugin can be configured on the <guilabel>Filesystem Browser</guilabel> page
-of <link linkend="configuring-kate-configdialog">&kate;'s configuration</link>.</para>
+<para>The <guilabel>Call Stack</guilabel> tool view contains a list of the formatted
+backtrace returned from &gdb;.</para>
-<variablelist>
-<varlistentry>
-<term><guilabel>Toolbar</guilabel></term>
-<listitem><para>Configure the buttons on the Filesystem Browser toolbar
-by moving the ones you want enabled to the <guilabel>Selected Actions</guilabel>
-list, and order them using the arrow buttons at the side of the list.</para>
- </listitem>
-</varlistentry>
+<screenshot id="screenshot-gdb-call-stack">
+<screeninfo>The &gdb; Call Stack Tool View</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="gdb-call-stack.png" format="PNG"/></imageobject>
+<textobject><phrase>The Call Stack tool view.</phrase></textobject>
+<caption><para>The &gdb; Plugin's <guilabel>Call Stack</guilabel> tool view.
+</para></caption>
+</mediaobject>
+</screenshot>
-</variablelist>
-</sect2>
-</sect1>
+<para>The <guilabel>Locals</guilabel> tool view contains a list of all currently
+loaded variables from the program and their corresponding values.</para>
- <!--
- FIXME: replaced by built-in functionality in 4.12
- lots of this is wrong, other parts need to be moved somewhere else -->
-<sect1 id="kate-application-plugin-snippets">
-<sect1info>
-<authorgroup>
-<author><firstname>Martin</firstname> <surname>Gergov</surname></author>
-<author>&TC.Hollingsworth; &TC.Hollingsworth.mail;</author>
-</authorgroup>
-</sect1info>
-<title>Kate Snippets</title>
+<screenshot id="screenshot-gdb-locals">
+<screeninfo>The &gdb; Locals Tool View</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="gdb-locals.png" format="PNG"/></imageobject>
+<textobject><phrase>The Locals tool view.</phrase></textobject>
+<caption><para>The &gdb; Plugin's <guilabel>Locals</guilabel> tool view.
+</para></caption>
+</mediaobject>
+</screenshot>
-<sect2 id="snippets-intro">
-<title>Introduction</title>
-<para>Kate Snippets is a plugin used to save you some time by adding support for
-so-called <quote>snippets</quote> (re-usable source code, machine code or text). The plugin
-also supports code completion and QtScript.</para>
</sect2>
-<sect2 id="snippets-menu">
-<title>Menu Structure</title>
+<sect2 id="gdb-ack">
+<title>Thanks and Acknowledgments</title>
-<variablelist>
-<varlistentry>
-<term><menuchoice><guimenu>View</guimenu><guisubmenu>Tool Views</guisubmenu>
-<guimenuitem>Show Snippets</guimenuitem></menuchoice></term>
-<listitem><para>Shows snippets panel containing all snippets in your repository
-that are for the currently opened file type.</para></listitem>
-</varlistentry>
-</variablelist>
+<para>Special thanks to Google Code-In 2011 participant Martin Gergov for
+writing much of this section.</para>
</sect2>
-<sect2 id="snippets-panel">
-<title>Snippets panel</title>
-
-<screenshot id="screenshot-snippets-panel">
-<screeninfo>Kate Snippets Panel</screeninfo>
-<mediaobject>
-<imageobject><imagedata fileref="snippets-panel.png" format="PNG"/></imageobject>
-<textobject><phrase>The &kate; snippets panel.</phrase></textobject>
-<caption><para>The panel for &kate; Snippets.</para></caption>
-</mediaobject>
-</screenshot>
+</sect1>
-<para>In the panel you should see a list of snippet repositories,
-along with options to create your own, get them from the Internet or load
-them from a local file. Each repository has a checkbox that can be used to
-activate or deactivate it. There are also buttons to edit and delete existing
-repositories.</para>
+<sect1 id="kate-application-plugin-searchinfiles">
+<sect1info>
+<authorgroup><author>
+&TC.Hollingsworth; &TC.Hollingsworth.mail;
+</author></authorgroup>
+</sect1info>
+<title>Search & Replace</title>
-<sect3 id="snippets-repo-internet">
-<title>Loading Snippet Repository Files</title>
-<para>You can download snippet repositories from the Internet. Just click
-<guibutton>Get New Snippets</guibutton> and a window with a list of snippet
-repositories will open. After downloading the desired snippet, make sure that
-you have activated it.</para>
-<!--FIXME no way to load a local file ?-->
-<para>You can also load snippet repositories from a local file using the file
-browser at the bottom of the panel. Click <guibutton>Copy to repository</guibutton>
-when finished.</para>
-</sect3>
+<sect2 id="searchinfiles-intro">
+<title>Introduction</title>
+<para>&kappname;'s Search & Replace plugin allows you to search for text or
+<ulink url="help:/katepart/regular-expressions.html">regular expressions</ulink>
+in many different files at once. You can search all open files, all the files
+in one directory and optionally its subdirectories, or all files in the current
+project. You can even filter by filename, for instance searching only files
+that end with a particular file extension.</para>
-<sect3 id="snippets-repo-editor">
-<title>Creating and Editing Snippets</title>
+</sect2>
-<screenshot id="screenshot-snippets-form">
-<screeninfo>Snippet Editor</screeninfo>
-<mediaobject>
-<imageobject><imagedata fileref="snippets-form.png" format="PNG"/></imageobject>
-<textobject><phrase>The snippet editor.</phrase></textobject>
-<caption><para>The snippet editor interface.</para></caption>
-</mediaobject>
-</screenshot>
+<sect2 id="searchinfiles-ui">
+<title>Interface</title>
-<para>To create a new snippet repository, click <guibutton>New Snippet File</guibutton>.
-You should now see a dialog that asks for the name of the snippet file, license and
-author. After choosing the desired options, click <guibutton>Create</guibutton>,
-and the snippet editor will open.</para>
+<sect3 id="searchinfiles-ui-query">
+<title>Search Query</title>
-<para>The snippet editor contains the following options:</para>
+<para>The following options are always displayed at the top of the Search in
+Files tool view:</para>
<variablelist>
+
<varlistentry>
-<term><guilabel>File Type</guilabel></term>
-<listitem><para>Select the file type(s) you want the snippet repository to apply
-to. It is set to <quote>*</quote> by default, so the repository applies to all files. You
-can change it to something like <userinput>C++</userinput> for instance, or select
-from a list by hitting the <guibutton>Edit</guibutton>. You can specify more
-than one file type by separating them with <userinput>;</userinput>.</para></listitem>
+<term><guiicon>New Tab</guiicon></term>
+<listitem><para>
+You can have as many searches as you want open at the same time. Simply click
+the <guibutton>New Tab</guibutton> button at the top-left corner of the Search
+tool view and a new results tab will open permitting you to perform another
+search.
+</para></listitem>
</varlistentry>
<varlistentry>
-<term><guilabel>Authors</guilabel></term>
-<listitem><para>Enter the name(s) of the author(s) of the snippet file.</para></listitem>
+<term><guiicon>Toggle Results</guiicon></term>
+<listitem><para>
+The down arrow in the top right-corner of the Search in Files tool view will
+toggle the bottom half of the tool view between displaying additional options
+for the Search in Folder mode and the results of your search.
+</para></listitem>
</varlistentry>
<varlistentry>
-<term>Snippets List</term>
-<listitem><para>Contains all snippets defined in the snippet file. You can
-simply click on a snippet listed there to edit it.</para></listitem>
+<term><guilabel>Find</guilabel></term>
+<listitem><para>
+This is where you type in what you want to find. You may enter standard text,
+or a regular expression if enabled.
+</para></listitem>
</varlistentry>
-
+
<varlistentry>
-<term>Add (<guibutton>+</guibutton>)</term>
-<listitem><para>Used to add a new snippet.</para></listitem>
+<term><guilabel>Replace</guilabel> (text box)</term>
+<listitem><para>
+Replacement text that will be added to file(s) in place of the text in the
+<guilabel>Find</guilabel> text box.
+</para></listitem>
</varlistentry>
<varlistentry>
-<term>Delete (<guibutton>-</guibutton>)</term>
-<listitem><para>Used to delete a snippet.</para></listitem>
+<term><guibutton>Search</guibutton></term>
+<listitem><para>
+When you've finished configuring everything, just press the
+<guibutton>Search</guibutton> button to perform your search. You may also press
+&Enter; in the <guilabel>Find</guilabel> text box to do the same.
+</para></listitem>
</varlistentry>
<varlistentry>
-<term><guilabel>Match/Name</guilabel></term>
-<listitem><para>Appears in the list of snippets in the tool view and is also
-searched when using the code completion feature.</para></listitem>
+<term><guibutton>Replace</guibutton></term>
+<listitem><para>
+When you've finished configuring everything, just press the
+<guibutton>Replace</guibutton> button to replace the text entered in the
+<guilabel>Find</guilabel> text box with that of the <guilabel>Replace</guilabel>
+text box. You may also press &Enter; in the <guilabel>Replace</guilabel> text
+box to do the same.
+</para></listitem>
</varlistentry>
<varlistentry>
-<term><guilabel>Display Prefix</guilabel>, <guilabel>Display Postfix</guilabel>,
-and <guilabel>Display Arguments</guilabel></term>
-<listitem><para>Used to display helpful information while using code completion.
-The prefix and postfix are displayed before and after the name, while the arguments
-are displayed in parenthesis immediately after the name.</para></listitem>
+<term><guibutton>Next</guibutton></term>
+<listitem><para>
+Go to the next match of your search query, switching files if necessary.
+</para></listitem>
</varlistentry>
<varlistentry>
-<term><guilabel>Snippet Content</guilabel></term>
-<listitem><para>Reusable text or code. This is what appears in your document
-when the snippet is used.</para></listitem>
+<term><guibutton>Replace checked</guibutton></term>
+<listitem><para>
+The same as <guibutton>Replace</guibutton>, but will only perform replacements
+in files that are checked in the pane below.
+</para></listitem>
</varlistentry>
</variablelist>
-
-<para>In <guilabel>Snippet Content</guilabel> you can specify variables with
-<userinput>${<replaceable>name</replaceable>}</userinput> or
-<userinput>%{<replaceable>name</replaceable>}</userinput>. These can be filled
-by QtScript or when the snippet is used. There is a special variable -
-${cursor} or %{cursor} - which automatically sets the cursor to its first
-occurrence.</para>
-
</sect3>
-</sect2>
-
-<sect2 id="snippets-using">
-<title>Using Snippets</title>
-
-<screenshot id="screenshot-snippets-usage">
-<screeninfo>Kate Snippets in Action</screeninfo>
-<mediaobject>
-<imageobject><imagedata fileref="snippets-usage.png" format="PNG"/></imageobject>
-<textobject><phrase>Accessing &kate; Snippets from a tool view and a drop down menu.</phrase></textobject>
-<caption><para>Selecting from a list of snippets.</para></caption>
-</mediaobject>
-</screenshot>
-
-<para>You can call snippets in two ways:</para>
-
-<itemizedlist>
-<listitem><para>By choosing the snippet from the tool view.</para></listitem>
-<listitem><para>While writing, you can press <keycombo action="simul">&Ctrl;
-<keysym>Space</keysym></keycombo>, which will display all the snippets in a
-convenient window from which you can choose. You may enter the beginning
-of the snippets name before or after pressing this key combination, which provides
-functionality similar to code completion.</para></listitem>
-</itemizedlist>
-
-<para>If the snippet contains variables (besides <literal>${cursor}</literal>)
-the cursor will automatically go to the first occurrence of a variable and will
-wait for you to write something. When you are done, you can press to move
-to the next variable, and so on.</para>
-
-</sect2>
-
-<sect2 id="snippets-ack">
-<title>Thanks and Acknowledgments</title>
-<para>&kate; Snippets was written by Joseph Wenninger.</para>
-<para>Special thanks to Google Code-In 2011 participant Martin Gergov for
-writing much of this section.</para>
-</sect2>
-
-</sect1>
+<sect3 id="searchinfiles-ui-folder">
+<title>Search in Folder Options</title>
-<sect1 id="kate-application-plugin-build">
-<!--http://kate-editor.org/2011/06/21/kate-plugin-updates-part-1/ -->
-<sect1info>
-<authorgroup>
-<author><firstname>Salma</firstname> <surname>Sultana</surname></author>
-<author>&TC.Hollingsworth; &TC.Hollingsworth.mail;</author>
-</authorgroup>
-</sect1info>
-<title>Build Plugin</title>
-
-<sect2 id="build-intro">
-<title>Introduction</title>
+<para>These options are displayed below the aforementioned query options. If search
+results are being displayed instead, press the <guiicon>Toggle Results</guiicon>
+button to display them.</para>
-<para>The Build plugin allows you to run actions like build, clean and compile
-on a project.</para>
+<variablelist>
-</sect2>
+<varlistentry>
+<term><guilabel>Match case</guilabel></term>
+<listitem><para>
+Restricts search results to only those that have the exact same combination
+of upper and lower case letters as your search query.
+</para></listitem>
+</varlistentry>
-<sect2 id="build-using">
-<title>Using the Build Plugin</title>
+<varlistentry>
+<term><guilabel>Regular expressions</guilabel></term>
+<listitem><para>
+Permits you to use <ulink url="help:/katepart/regular-expressions.html">regular
+expressions</ulink> instead of simple text as your search query.
+</para></listitem>
+</varlistentry>
-<para>The Build plugin adds a <guilabel>Build Output</guilabel> tool view at the
-bottom and a <guimenu>Build</guimenu> menu on the menubar. The tool view can be used to configure
-build target settings, while the menu can be used to perform build, clean and
-compile actions.</para>
+<varlistentry>
+<term><guilabel>Expand results</guilabel></term>
+<listitem><para>
+Display all the results found in each file, instead of just a list of files
+that contain the search query.
+</para></listitem>
+</varlistentry>
+<varlistentry>
+<term><guilabel>Search</guilabel></term>
+<listitem><para>
+This has three options. Select <guilabel>in Open files</guilabel> to search all
+files currently open in &kappname;. Select <guilabel>in Folder</guilabel> to
+search inside a folder and optionally its subfolders. Select <guilabel>in
+Project</guilabel> to search all the files listed in the currently open project.
+</para></listitem>
+</varlistentry>
-<para>The <guilabel>Build Output</guilabel> tool view has three tabs:</para>
+<varlistentry>
+<term><guilabel>Folder</guilabel></term>
+<listitem><para>
+You may enter the path of the folder you wish to search. For instance, you might
+enter <userinput>~/development/kde/kate/</userinput> if you wished to search the
+&kate; source code. This option is only available when using
+<guilabel>in Folder</guilabel> mode.
+</para></listitem>
+</varlistentry>
-<itemizedlist>
-<listitem><para><guilabel>Target Settings</guilabel></para></listitem>
-<listitem><para><guilabel>Output</guilabel></para></listitem>
-<listitem><para><guilabel>Errors & Warnings</guilabel></para></listitem>
-</itemizedlist>
+<varlistentry>
+<term><guiicon>Open file dialog</guiicon></term>
+<listitem><para>
+Press this button to locate the folder in your desktop's folder browser. This
+button only works when using <guilabel>in Folder</guilabel> mode.
+</para></listitem>
+</varlistentry>
-<sect3 id="build-using-target-settings">
-<title>Target Settings tab</title>
+<varlistentry>
+<term><guiicon>Up</guiicon></term>
+<listitem><para>
+Press this button to change <guilabel>Folder</guilabel> to the parent of the
+currently selected folder. This button only works when using
+<guilabel>in Folder</guilabel> mode.
+</para></listitem>
+</varlistentry>
-<para>The target settings tab can be used to configure various build targets.</para>
+<varlistentry>
+<term><guiicon>Restore Current Folder</guiicon></term>
+<listitem><para>
+This button will set the <guilabel>Folder</guilabel> entry to the folder in which
+the currently open document is located. This button only works when using
+<guilabel>in Folder</guilabel> mode.
+</para></listitem>
+</varlistentry>
-<para>Each target contains four configuration options:</para>
+<varlistentry>
+<term><guilabel>Filter</guilabel></term>
+<listitem><para>
+This permits you to only search filenames that match a particular pattern. For
+instance, to only search files written in C++, change it to
+<userinput>*.cpp</userinput>. To search only files beginning with
+<literal>kate</literal>, change it to <userinput>kate*</userinput>. You can
+enter multiple filters separated with a comma (<userinput>,</userinput>). This
+option is not available when using <guilabel>in Open files</guilabel> mode.
+</para></listitem>
+</varlistentry>
-<variablelist>
<varlistentry>
-<term><guilabel>Working Directory</guilabel></term>
-<listitem><para>You can set the path to the project here. Leave this empty to
-use the directory the current document is located in.</para></listitem>
+<term><guilabel>Exclude</guilabel></term>
+<listitem><para>
+The opposite of <guilabel>Filter</guilabel>, this prevents &kappname; from
+searching files that match the specified patterns. As with
+<guilabel>Filter</guilabel>, you can enter multiple patterns separated with a
+comma (<userinput>,</userinput>). This option is not available when using
+<guilabel>in Open files</guilabel> mode.
+</para></listitem>
</varlistentry>
<varlistentry>
-<term><guilabel>Build</guilabel></term>
-<listitem><para>This option lets you define the build command. It is set to
-<command>make</command> by default.</para></listitem>
+<term><guilabel>Recursive</guilabel></term>
+<listitem><para>
+If this option is enabled, &kappname; will also search in all subfolders of the
+selected folder. This option is only available when using
+<guilabel>in Folder</guilabel> mode.
+</para></listitem>
</varlistentry>
<varlistentry>
-<term><guilabel>Clean</guilabel></term>
-<listitem><para>The option lets you define the clean command. It is set to
-<command>make clean</command> by default.</para></listitem>
+<term><guilabel>Include hidden</guilabel></term>
+<listitem><para>
+If this option is enabled, &kappname; will also search in files or folders that
+are typically hidden by your &OS;. This option is only available when using
+<guilabel>in Folder</guilabel> mode.
+</para></listitem>
</varlistentry>
<varlistentry>
-<term><guilabel>Quick Compile</guilabel></term>
-<listitem><para>This option lets you define the quick compile command. It is set
-to <command>gcc -Wall -g %f</command> by default.</para></listitem>
+<term><guilabel>Follow symbolic links</guilabel></term>
+<listitem><para>
+The Search in Files plugin typically doesn't follow
+<ulink url="http://en.wikipedia.org/wiki/Symbolic_link">symbolic links</ulink>.
+When this option is enabled, the plugin will follow them instead and search inside
+the files or folders they reference. This option is only available when using
+<guilabel>in Folder</guilabel> mode.
+</para>
+<warning><para>It's possible for symbolic links to reference a folder that is the
+parent of the folder currently being searched, or other folders that contain
+symbolic links to their parent. If there is such a link in the folder being
+searched and this option is enabled, &kappname; will repeatedly follow the link
+and search the folder, and the search will never complete.</para></warning>
+</listitem>
</varlistentry>
-</variablelist>
-
-<para>One can create a new target by using the <guibutton>New</guibutton> button.
-The <guibutton>Copy</guibutton> button can be used to make a copy of an existing
-target. To delete a target, use the <guibutton>Delete</guibutton> button.</para>
-
-</sect3>
-<sect3 id="build-using-output">
-<title>Output tab</title>
-
-<para>The <guilabel>Output</guilabel> tab shows the console output generated by
-the last command.</para>
+<varlistentry>
+<term><guilabel>Include binary files</guilabel></term>
+<listitem><para>
+If enabled, &kappname; will also search in files that do not appear to be text
+files.
+</para></listitem>
+</varlistentry>
+</variablelist>
</sect3>
-<sect3 id="buiid-using-errors">
-<title>Errors & Warnings</title>
+<sect3 id="searchinfiles-ui-results">
+<title>Search Results</title>
-<para>The <guilabel>Errors & Warnings</guilabel> tab lists the errors and
-warnings generated by the last command.</para>
+<para>The results of your search are displayed below the query options. If
+options for Search in Folder mode are displayed, simply press the
+<guiicon>Toggle Results</guiicon> button to display them. They will also
+automatically be displayed as soon as a search is performed.</para>
-<para>Each line contains a message and the file name and line number if available.
-Clicking on the error or warning takes you to the appropriate file and places
-the cursor on the corresponding line number.</para>
+<para>The search results display a list of files that contains text that matches
+your search query, followed by the number of matches found in that file.</para>
-<para>There are <guibutton>Errors</guibutton>, <guibutton>Warnings</guibutton>,
-and <guibutton>Others</guibutton> buttons at the top that allow you to show
-or hide those categories of output.</para>
+<para>To see a list of matches in that file, simply click the expansion arrow
+to the left of the file name. (If you selected the <guilabel>Expand
+results</guilabel> option, this will already be done for you.) The line number
+each match is found on will be displayed, followed by the contents of that line,
+with your search query indicated in bold text.</para>
-<!--FIXME: These shortcuts now seem to be used by the Project plugin in 4.11.
- https://bugs.kde.org/show_bug.cgi?id=328170 -->
-<para>To navigate to the previous error, press
-<keycombo action="simul">&Ctrl;&Alt;<keysym>Left</keysym></keycombo>.
-To navigate to the next error, press
-<keycombo action="simul">&Ctrl;&Alt;<keysym>Right</keysym></keycombo>.</para>
+<para>To open the file your result was found in, simply double-click it. &kappname;
+will open the file if needed. You can also move the cursor to the location of
+a particular match by double-clicking on its listing instead of the file name.
+</para>
</sect3>
</sect2>
-<sect2 id="build-menu">
+<sect2 id="searchinfiles-menu">
<title>Menu Structure</title>
-<variablelist id="build-build">
-<varlistentry>
-<term><menuchoice>
-<guimenu>Build</guimenu><guimenuitem>Build</guimenuitem>
-</menuchoice></term>
-<listitem><para>Runs the <guilabel>Build</guilabel> command for the currently
-selected target.</para></listitem>
-</varlistentry>
+<variablelist>
-<varlistentry id="build-clean">
+<varlistentry id="edit-searchinfiles">
<term><menuchoice>
-<guimenu>Build</guimenu><guimenuitem>Clean</guimenuitem>
+<guimenu>Edit</guimenu>
+<guimenuitem>Search in Files</guimenuitem>
</menuchoice></term>
-<listitem><para>Runs the <guilabel>Clean</guilabel> command for the currently
-selected target.</para></listitem>
+<listitem>
+<para>Launches the Search and Replace tool view.</para>
+</listitem>
</varlistentry>
-<varlistentry id="build-compile">
+<varlistentry id="edit-next-match">
<term><menuchoice>
-<guimenu>Build</guimenu><guimenuitem>Quick Compile</guimenuitem>
+<guimenu>Edit</guimenu>
+<guimenuitem>Go to Next Match</guimenuitem>
</menuchoice></term>
-<listitem><para>Runs the <guilabel>Quick Compile</guilabel> command for the
-currently selected target.</para></listitem>
+<listitem>
+<para>Go to the next match in a search performed by the Search and Replace
+plugin.</para>
+</listitem>
</varlistentry>
-<varlistentry id="build-previous-error">
+<varlistentry id="edit-previous-match">
<term><menuchoice>
-<shortcut><keycombo action="simul">&Ctrl;&Alt;<keysym>Left</keysym></keycombo></shortcut>
-<guimenu>Build</guimenu><guimenuitem>Previous Error</guimenuitem>
+<guimenu>Edit</guimenu>
+<guimenuitem>Go to Previous Match</guimenuitem>
</menuchoice></term>
-<listitem><para>Moves the cursor to the location of the previous error in the
-document.</para></listitem>
+<listitem>
+<para>Go to the previous match in a search performed by the Search and Replace
+plugin.</para>
+</listitem>
</varlistentry>
-<varlistentry id="build-next-error">
+<varlistentry id="view-toolviews-searchandreplace">
<term><menuchoice>
-<shortcut><keycombo action="simul">&Ctrl;&Alt;<keysym>Right</keysym></keycombo></shortcut>
-<guimenu>Build</guimenu><guimenuitem>Next Error</guimenuitem>
-</menuchoice></term>
-<listitem><para>Moves the cursor to the location of the next error in the
-document.</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><menuchoice id="build-targets">
-<guimenu>Build</guimenu><guisubmenu>Targets</guisubmenu>
-</menuchoice></term>
-<listitem><para>Select from a list of targets configured by the user.</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><menuchoice id="build-next-target">
-<guimenu>Build</guimenu><guimenuitem>Next Target</guimenuitem>
+<guimenu>View</guimenu><guisubmenu>Tool Views</guisubmenu>
+<guimenuitem>Show Search and Replace</guimenuitem>
</menuchoice></term>
-<listitem><para>Switch to the next target configured by the user.</para></listitem>
+<listitem>
+<para>Toggle the display of &kappname;'s <guilabel>Search and Replace</guilabel> tool.
+</para>
+</listitem>
</varlistentry>
</variablelist>
-</sect2>
-<sect2 id="build-ack">
-<title>Thanks and Acknowledgments</title>
-<para>The &kate; Build Plugin was written by Kåre Särs.</para>
-<para>Special thanks to Google Code-In 2011 participant Salma Sultana for
-writing much of this section.</para>
</sect2>
</sect1>
-<sect1 id="kate-application-plugin-sql">
+ <!--
+ FIXME: replaced by built-in functionality in 4.12
+ lots of this is wrong, other parts need to be moved somewhere else -->
+<sect1 id="kate-application-plugin-snippets">
<sect1info>
<authorgroup>
-<author><firstname>Ömer</firstname> <othername>Faruk</othername> <surname>ORUÇ</surname></author>
+<author><firstname>Martin</firstname> <surname>Gergov</surname></author>
<author>&TC.Hollingsworth; &TC.Hollingsworth.mail;</author>
</authorgroup>
</sect1info>
-<title>SQL Plugin</title>
-
-<sect2 id="sql-intro">
-<title>Introduction</title>
-
-<para>The Structured Query Language (SQL) is a specialized language for updating,
-deleting, and requesting information from databases.</para>
-
-<para>The &kate; SQL Plugin allows you to:</para>
-
-<itemizedlist>
-<listitem><para>Create a database</para></listitem>
-<listitem><para>Connect to existing databases</para></listitem>
-<listitem><para>Insert and delete data in the database</para></listitem>
-<listitem><para>Execute queries</para></listitem>
-<listitem><para>Display results in a table</para></listitem>
-</itemizedlist>
+<title>Kate Snippets</title>
-<!--FIXME If Kate is installed on your computer, at first open Kate.
-If Kate isn't installed on your computer, download and install it.
+<sect2 id="snippets-intro">
+<title>Introduction</title>
+<para>Kate Snippets is a plugin used to save you some time by adding support for
+so-called <quote>snippets</quote> (re-usable source code, machine code or text). The plugin
+also supports code completion and QtScript.</para>
+</sect2>
-Using SQL Plugin
-After opening the Kate;
-Click Settings→ Configure Kate
-and then;
-Click Application → Select Plugins in the tree widget
+<sect2 id="snippets-menu">
+<title>Menu Structure</title>
-In the Plugin Manager panel on the right, check SQL Plugin and click OK.
--->
+<variablelist>
+<varlistentry>
+<term><menuchoice><guimenu>View</guimenu><guisubmenu>Tool Views</guisubmenu>
+<guimenuitem>Show Snippets</guimenuitem></menuchoice></term>
+<listitem><para>Shows snippets panel containing all snippets in your repository
+that are for the currently opened file type.</para></listitem>
+</varlistentry>
+</variablelist>
</sect2>
-<sect2 id="sql-connecting">
-<title>Connecting to a Database</title>
+<sect2 id="snippets-panel">
+<title>Snippets panel</title>
-<para>Select <guibutton>Add Connection</guibutton> from the <guimenu>SQL</guimenu>
-menu or toolbar, and then select the Qt database driver you want to use (including
-QSQLITE, QMYSQL3, QMYSQL, QODBC3, QODBC, QPSQL7, and QPSQL). If you can't see
-the desired driver, you need to install it. Then, press <guibutton>Next</guibutton>.
-</para>
+<screenshot id="screenshot-snippets-panel">
+<screeninfo>Kate Snippets Panel</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="snippets-panel.png" format="PNG"/></imageobject>
+<textobject><phrase>The &kate; snippets panel.</phrase></textobject>
+<caption><para>The panel for &kate; Snippets.</para></caption>
+</mediaobject>
+</screenshot>
-<para>If the database you selected uses a file, simply indicate the database's
-location and press the <guibutton>Next</guibutton> button. If it requires connecting
-to a server, you must enter the hostname of the server, your username and password,
-and any other information that particular driver may require. Then press
-<guibutton>Next</guibutton>.</para>
+<para>In the panel you should see a list of snippet repositories,
+along with options to create your own, get them from the Internet or load
+them from a local file. Each repository has a checkbox that can be used to
+activate or deactivate it. There are also buttons to edit and delete existing
+repositories.</para>
-<para>Finally, give a name to your connection, and press <guibutton>Finish</guibutton>.</para>
+<sect3 id="snippets-repo-internet">
+<title>Loading Snippet Repository Files</title>
+<para>You can download snippet repositories from the Internet. Just click
+<guibutton>Get New Snippets</guibutton> and a window with a list of snippet
+repositories will open. After downloading the desired snippet, make sure that
+you have activated it.</para>
+<!--FIXME no way to load a local file ?-->
+<para>You can also load snippet repositories from a local file using the file
+browser at the bottom of the panel. Click <guibutton>Copy to repository</guibutton>
+when finished.</para>
+</sect3>
-</sect2>
+<sect3 id="snippets-repo-editor">
+<title>Creating and Editing Snippets</title>
-<sect2 id="sql-querying">
-<title>Running Queries</title>
+<screenshot id="screenshot-snippets-form">
+<screeninfo>Snippet Editor</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="snippets-form.png" format="PNG"/></imageobject>
+<textobject><phrase>The snippet editor.</phrase></textobject>
+<caption><para>The snippet editor interface.</para></caption>
+</mediaobject>
+</screenshot>
-<sect3 id="sql-querying-insert-delete-update">
-<title>INSERT/DELETE/UPDATE</title>
+<para>To create a new snippet repository, click <guibutton>New Snippet File</guibutton>.
+You should now see a dialog that asks for the name of the snippet file, license and
+author. After choosing the desired options, click <guibutton>Create</guibutton>,
+and the snippet editor will open.</para>
-<para>You can insert, delete, and update data using the SQL plugin just as
-you would from the command line or from within a program. Simply enter a query
-and press the <guibutton>Run query</guibutton>.</para>
+<para>The snippet editor contains the following options:</para>
-<example>
-<title>Some Example Queries</title>
<variablelist>
-
<varlistentry>
-<term><command>INSERT</command></term>
-<listitem><para><programlisting>
-INSERT INTO <replaceable>table_name</replaceable> ("<replaceable>feature1</replaceable>", "<replaceable>feature2</replaceable>", "<replaceable>feature3</replaceable>", "<replaceable>feature4</replaceable>", "<replaceable>feature5</replaceable>")
-VALUES ("<replaceable>value1</replaceable>", "<replaceable>value2</replaceable>", "<replaceable>value3</replaceable>", "<replaceable>value4</replaceable>", "<replaceable>value5</replaceable>" )
-</programlisting></para></listitem>
+<term><guilabel>File Type</guilabel></term>
+<listitem><para>Select the file type(s) you want the snippet repository to apply
+to. It is set to <quote>*</quote> by default, so the repository applies to all files. You
+can change it to something like <userinput>C++</userinput> for instance, or select
+from a list by hitting the <guibutton>Edit</guibutton>. You can specify more
+than one file type by separating them with <userinput>;</userinput>.</para></listitem>
</varlistentry>
<varlistentry>
-<term><command>DELETE</command></term>
-<listitem><para><programlisting>
-DELETE FROM <replaceable>table_name</replaceable> WHERE name = "<replaceable>text</replaceable>"
-</programlisting></para></listitem>
+<term><guilabel>Authors</guilabel></term>
+<listitem><para>Enter the name(s) of the author(s) of the snippet file.</para></listitem>
</varlistentry>
<varlistentry>
-<term><command>UPDATE</command></term>
-<listitem><para><programlisting>
-UPDATE <replaceable>table_name</replaceable> SET "<replaceable>feature1</replaceable>" = "<replaceable>text</replaceable>", "<replaceable>feature2</replaceable>" = "<replaceable>text</replaceable>", "<replaceable>feature3</replaceable>" = "<replaceable>text</replaceable>", "<replaceable>feature4</replaceable>" = "<replaceable>text</replaceable>", "<replaceable>feature5</replaceable>" = "<replaceable>text</replaceable>"
-</programlisting></para></listitem>
+<term>Snippets List</term>
+<listitem><para>Contains all snippets defined in the snippet file. You can
+simply click on a snippet listed there to edit it.</para></listitem>
</varlistentry>
-
-</variablelist>
-</example>
-
-</sect3>
-
-<sect3 id="sql-querying-select">
-<title>SELECT</title>
-
-<para>After running a <command>SELECT</command> query, you can view the results
-as a table that will appear in the <guilabel>SQL Data Output</guilabel> tool view at
-the bottom of &kappname;, or as text in the <guilabel>SQL Text Output</guilabel>.
-If there is an error, you can see it in the text output.</para>
-
-<example>
-<title>Example <command>SELECT</command> Query</title>
-<para><programlisting>
-SELECT * FROM <replaceable>table_name</replaceable>
-</programlisting></para>
-</example>
-
-<para>In the <guilabel>SQL Data Output</guilabel> tool view, there are several buttons:</para>
-
-<variablelist>
-
+
<varlistentry>
-<term><guibutton>Resize columns to contents</guibutton></term>
-<listitem><para>Changes the size of columns to fit their contents.</para></listitem>
+<term>Add (<guibutton>+</guibutton>)</term>
+<listitem><para>Used to add a new snippet.</para></listitem>
</varlistentry>
<varlistentry>
-<term><guibutton>Resize rows to contents</guibutton></term>
-<listitem><para>Changes the size of rows to fit their contents.</para></listitem>
+<term>Delete (<guibutton>-</guibutton>)</term>
+<listitem><para>Used to delete a snippet.</para></listitem>
</varlistentry>
<varlistentry>
-<term><guibutton>Copy</guibutton></term>
-<listitem><para>Selects all of the table contents and copies it to the clipboard buffer.</para></listitem>
+<term><guilabel>Match/Name</guilabel></term>
+<listitem><para>Appears in the list of snippets in the tool view and is also
+searched when using the code completion feature.</para></listitem>
</varlistentry>
<varlistentry>
-<term><guibutton>Export</guibutton></term>
-<listitem><para>Exports all of the table contents to a file, the clipboard, or the
-current document in the Comma Separated Values format.</para></listitem>
+<term><guilabel>Display Prefix</guilabel>, <guilabel>Display Postfix</guilabel>,
+and <guilabel>Display Arguments</guilabel></term>
+<listitem><para>Used to display helpful information while using code completion.
+The prefix and postfix are displayed before and after the name, while the arguments
+are displayed in parenthesis immediately after the name.</para></listitem>
</varlistentry>
<varlistentry>
-<term><guibutton>Clear</guibutton></term>
-<listitem><para>Removes everything from the table view</para></listitem>
+<term><guilabel>Snippet Content</guilabel></term>
+<listitem><para>Reusable text or code. This is what appears in your document
+when the snippet is used.</para></listitem>
</varlistentry>
</variablelist>
-<para>You can now change the colors displayed in the table in the <guilabel>SQL</guilabel>
-section of <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &kate;</guimenuitem>
-</menuchoice>.</para>
+<para>In <guilabel>Snippet Content</guilabel> you can specify variables with
+<userinput>${<replaceable>name</replaceable>}</userinput> or
+<userinput>%{<replaceable>name</replaceable>}</userinput>. These can be filled
+by QtScript or when the snippet is used. There is a special variable -
+${cursor} or %{cursor} - which automatically sets the cursor to its first
+occurrence.</para>
</sect3>
</sect2>
-<sect2 id="sql-browsing">
-<title>Browsing</title>
-
-<para>You can browse your database using the <guilabel>SQL Schema Browser</guilabel>
-tool view on the left. The information displayed varies depending on which
-database driver you are using.</para>
-
-<para>To refresh this list, right-click anywhere in the tool view and select
-<guimenuitem>Refresh</guimenuitem>. To generate a query on any entry in the list,
-right-click on an entry, select <guisubmenu>Generate</guisubmenu>, and select the
-query type (<guimenuitem>SELECT</guimenuitem>, <guimenuitem>UPDATE</guimenuitem>,
-<guimenuitem>INSERT</guimenuitem>, or <guimenuitem>DELETE</guimenuitem>) from
-the submenu that appears.</para>
-
-</sect2>
-
-<sect2 id="sql-menus">
-<title>Menu Structure</title>
-<variablelist>
-
-<varlistentry>
-<term><menuchoice>
-<guimenu>SQL</guimenu><guimenuitem>Add connection...</guimenuitem>
-</menuchoice></term>
-<listitem><para>
-Adds a new connection using any database driver.
-</para></listitem>
-</varlistentry>
+<sect2 id="snippets-using">
+<title>Using Snippets</title>
-<varlistentry>
-<term><menuchoice>
-<guimenu>SQL</guimenu><guimenuitem>Remove connection</guimenuitem>
-</menuchoice></term>
-<listitem><para>
-Removes the selected connection.
-</para></listitem>
-</varlistentry>
+<screenshot id="screenshot-snippets-usage">
+<screeninfo>Kate Snippets in Action</screeninfo>
+<mediaobject>
+<imageobject><imagedata fileref="snippets-usage.png" format="PNG"/></imageobject>
+<textobject><phrase>Accessing &kate; Snippets from a tool view and a drop down menu.</phrase></textobject>
+<caption><para>Selecting from a list of snippets.</para></caption>
+</mediaobject>
+</screenshot>
-<varlistentry>
-<term><menuchoice>
-<guimenu>SQL</guimenu><guimenuitem>Edit connection...</guimenuitem>
-</menuchoice></term>
-<listitem><para>
-Edits the current connection's settings.
-</para></listitem>
-</varlistentry>
+<para>You can call snippets in two ways:</para>
-<varlistentry>
-<term>Connections</term>
-<listitem><para>
-All database connections you have created are listed between the
-<guimenuitem>Edit connection</guimenuitem> and <guimenuitem>Run query</guimenuitem>
-menu items. Select one to run queries or make modifications to it.
-</para></listitem>
-</varlistentry>
+<itemizedlist>
+<listitem><para>By choosing the snippet from the tool view.</para></listitem>
+<listitem><para>While writing, you can press <keycombo action="simul">&Ctrl;
+<keysym>Space</keysym></keycombo>, which will display all the snippets in a
+convenient window from which you can choose. You may enter the beginning
+of the snippets name before or after pressing this key combination, which provides
+functionality similar to code completion.</para></listitem>
+</itemizedlist>
-<varlistentry>
-<term><menuchoice>
-<shortcut><keycombo action="simul">&Ctrl;<keycap>E</keycap></keycombo></shortcut>
-<guimenu>SQL</guimenu><guimenuitem>Run query</guimenuitem>
-</menuchoice></term>
-<listitem><para>
-Runs your query.
-</para></listitem>
-</varlistentry>
+<para>If the snippet contains variables (besides <literal>${cursor}</literal>)
+the cursor will automatically go to the first occurrence of a variable and will
+wait for you to write something. When you are done, you can press to move
+to the next variable, and so on.</para>
-</variablelist>
</sect2>
-<sect2 id="sql-ack">
+<sect2 id="snippets-ack">
<title>Thanks and Acknowledgments</title>
-
-<para>The SQL Plugin was written by Marco Mentasti.</para>
-<para>Special thanks to Google Code-In 2011 participant Ömer Faruk ORUÇ for
+<para>&kate; Snippets was written by Joseph Wenninger.</para>
+<para>Special thanks to Google Code-In 2011 participant Martin Gergov for
writing much of this section.</para>
-
</sect2>
</sect1>
-<sect1 id="kate-application-plugin-gdb">
-<!--http://kate-editor.org/2011/06/23/kate-plugin-updates-part-2/-->
+
+<sect1 id="kate-application-plugin-sql">
<sect1info>
<authorgroup>
-<author><firstname>Martin</firstname> <surname>Gergov</surname></author>
+<author><firstname>Ömer</firstname> <othername>Faruk</othername> <surname>ORUÇ</surname></author>
<author>&TC.Hollingsworth; &TC.Hollingsworth.mail;</author>
</authorgroup>
</sect1info>
-<title>&gdb; Plugin</title>
+<title>SQL Plugin</title>
-<sect2 id="gdb-intro">
+<sect2 id="sql-intro">
<title>Introduction</title>
-<para>&kappname;'s &gdb; plugin provides a simple frontend to the popular &GNU;
-Project Debugger.</para>
+<para>The Structured Query Language (SQL) is a specialized language for updating,
+deleting, and requesting information from databases.</para>
-<important>
-<para>Previous experience with &gdb; is strongly recommended. For more
-information on using &gdb;, visit <ulink url="http://www.gnu.org/s/gdb/">the
-&gdb; website</ulink>.</para>
-</important>
+<para>The &kate; SQL Plugin allows you to:</para>
+
+<itemizedlist>
+<listitem><para>Create a database</para></listitem>
+<listitem><para>Connect to existing databases</para></listitem>
+<listitem><para>Insert and delete data in the database</para></listitem>
+<listitem><para>Execute queries</para></listitem>
+<listitem><para>Display results in a table</para></listitem>
+</itemizedlist>
+
+<!--FIXME If Kate is installed on your computer, at first open Kate.
+If Kate isn't installed on your computer, download and install it.
+
+Using SQL Plugin
+After opening the Kate;
+Click Settings→ Configure Kate
+and then;
+Click Application → Select Plugins in the tree widget
-<para>You can enable the &gdb; plugin in
-<link linkend="config-dialog-plugins">the Plugins section of &kappname;'s
-configuration</link>.</para>
+In the Plugin Manager panel on the right, check SQL Plugin and click OK.
+-->
-<para>For the plugin to work properly, you must have a source file (of any type
-supported by &gdb;) and an executable.</para>
+</sect2>
-<tip>
-<para>If you compile using &gcc;/<command>g++</command> you might want to use
-the <command><parameter>-ggdb</parameter></command> command line argument.
+<sect2 id="sql-connecting">
+<title>Connecting to a Database</title>
+
+<para>Select <guibutton>Add Connection</guibutton> from the <guimenu>SQL</guimenu>
+menu or toolbar, and then select the Qt database driver you want to use (including
+QSQLITE, QMYSQL3, QMYSQL, QODBC3, QODBC, QPSQL7, and QPSQL). If you can't see
+the desired driver, you need to install it. Then, press <guibutton>Next</guibutton>.
</para>
-</tip>
-<para>After these preparations are made, open the source file in &kappname;,
-enter the path to the executable in the <guilabel>Settings</guilabel> tab of the
-<guilabel>Debug View</guilabel> tool view, and select
-<menuchoice><guimenu>Debug</guimenu><guimenuitem>Start Debugging</guimenuitem></menuchoice>
-from the menu to get started.</para>
+<para>If the database you selected uses a file, simply indicate the database's
+location and press the <guibutton>Next</guibutton> button. If it requires connecting
+to a server, you must enter the hostname of the server, your username and password,
+and any other information that particular driver may require. Then press
+<guibutton>Next</guibutton>.</para>
-</sect2>
+<para>Finally, give a name to your connection, and press <guibutton>Finish</guibutton>.</para>
-<sect2 id="gdb-menus">
-<title>Menu and Toolbar Structure</title>
+</sect2>
-<para>All of these options are available in &kappname;'s menus, and many are
-available on the Debug toolbar as well.</para>
+<sect2 id="sql-querying">
+<title>Running Queries</title>
-<variablelist>
+<sect3 id="sql-querying-insert-delete-update">
+<title>INSERT/DELETE/UPDATE</title>
-<varlistentry id="gdb-menus-show-debug-view">
-<term><menuchoice>
-<guimenu>View</guimenu><guisubmenu>Tool View</guisubmenu><guimenuitem>Show Debug View</guimenuitem>
-</menuchoice></term>
-<listitem><para>Shows a tool view containing &gdb; output, the &gdb; command
-line used, and other settings.</para></listitem>
-</varlistentry>
+<para>You can insert, delete, and update data using the SQL plugin just as
+you would from the command line or from within a program. Simply enter a query
+and press the <guibutton>Run query</guibutton>.</para>
-<varlistentry id="gdb-menus-show-locals">
-<term><menuchoice>
-<guimenu>View</guimenu><guisubmenu>Tool View</guisubmenu><guimenuitem>Show Locals</guimenuitem>
-</menuchoice></term>
-<listitem><para>Shows a list of all currently loaded variables and their values.
-</para></listitem>
-</varlistentry>
+<example>
+<title>Some Example Queries</title>
+<variablelist>
-<varlistentry id="gdb-menus-show-call-stack">
-<term><menuchoice>
-<guimenu>View</guimenu><guisubmenu>Tool View</guisubmenu><guimenuitem>Show Call Stack</guimenuitem>
-</menuchoice></term>
-<listitem><para>Shows a &gdb; backtrace.</para></listitem>
+<varlistentry>
+<term><command>INSERT</command></term>
+<listitem><para><programlisting>
+INSERT INTO <replaceable>table_name</replaceable> ("<replaceable>feature1</replaceable>", "<replaceable>feature2</replaceable>", "<replaceable>feature3</replaceable>", "<replaceable>feature4</replaceable>", "<replaceable>feature5</replaceable>")
+VALUES ("<replaceable>value1</replaceable>", "<replaceable>value2</replaceable>", "<replaceable>value3</replaceable>", "<replaceable>value4</replaceable>", "<replaceable>value5</replaceable>" )
+</programlisting></para></listitem>
</varlistentry>
-<varlistentry id="gdb-menus-targets">
-<term><menuchoice>
-<guimenu>Debug</guimenu><guisubmenu>Targets</guisubmenu>
-</menuchoice></term>
-<listitem><para>A submenu containing a list of targets (executables).
-</para></listitem>
+<varlistentry>
+<term><command>DELETE</command></term>
+<listitem><para><programlisting>
+DELETE FROM <replaceable>table_name</replaceable> WHERE name = "<replaceable>text</replaceable>"
+</programlisting></para></listitem>
</varlistentry>
-<varlistentry id="gdb-menus-arg-lists">
-<term><menuchoice>
-<guimenu>Debug</guimenu><guisubmenu>Arg Lists</guisubmenu>
-</menuchoice></term>
-<listitem><para>A submenu containing all argument lists.</para></listitem>
+<varlistentry>
+<term><command>UPDATE</command></term>
+<listitem><para><programlisting>
+UPDATE <replaceable>table_name</replaceable> SET "<replaceable>feature1</replaceable>" = "<replaceable>text</replaceable>", "<replaceable>feature2</replaceable>" = "<replaceable>text</replaceable>", "<replaceable>feature3</replaceable>" = "<replaceable>text</replaceable>", "<replaceable>feature4</replaceable>" = "<replaceable>text</replaceable>", "<replaceable>feature5</replaceable>" = "<replaceable>text</replaceable>"
+</programlisting></para></listitem>
</varlistentry>
-<varlistentry id="gdb-menus-start">
-<term><menuchoice>
-<guimenu>Debug</guimenu><guimenuitem>Start Debugging</guimenuitem>
-</menuchoice></term>
-<listitem><para>Starts &gdb; with a target.</para></listitem>
-</varlistentry>
+</variablelist>
+</example>
-<varlistentry id="gdb-menus-kill">
-<term><menuchoice>
-<guimenu>Debug</guimenu><guimenuitem>Kill / Stop Debugging</guimenuitem>
-</menuchoice></term>
-<listitem><para>Stops &gdb;.</para></listitem>
-</varlistentry>
+</sect3>
-<varlistentry id="gdb-menus-restart">
-<term><menuchoice>
-<guimenu>Debug</guimenu><guimenuitem>Restart Debugging</guimenuitem>
-</menuchoice></term>
-<listitem><para>Restarts &gdb;.</para></listitem>
-</varlistentry>
+<sect3 id="sql-querying-select">
+<title>SELECT</title>
-<varlistentry id="gdb-menus-break">
-<term><menuchoice>
-<guimenu>Debug</guimenu><guimenuitem>Toggle Breakpoint / Break</guimenuitem>
-</menuchoice></term>
-<listitem><para>Set a breakpoint at the current cursor position.
-</para></listitem>
-</varlistentry>
+<para>After running a <command>SELECT</command> query, you can view the results
+as a table that will appear in the <guilabel>SQL Data Output</guilabel> tool view at
+the bottom of &kappname;, or as text in the <guilabel>SQL Text Output</guilabel>.
+If there is an error, you can see it in the text output.</para>
-<varlistentry id="gdb-menus-step-in">
-<term><menuchoice>
-<guimenu>Debug</guimenu><guimenuitem>Step In</guimenuitem>
-</menuchoice></term>
-<listitem><para>Execute the present statement (function call will be debugged).
-</para></listitem>
-</varlistentry>
+<example>
+<title>Example <command>SELECT</command> Query</title>
+<para><programlisting>
+SELECT * FROM <replaceable>table_name</replaceable>
+</programlisting></para>
+</example>
-<varlistentry id="gdb-menus-step-over">
-<term><menuchoice>
-<guimenu>Debug</guimenu><guimenuitem>Step Over</guimenuitem>
-</menuchoice></term>
-<listitem><para>Execute the present statement (function call will not be
-debugged).</para></listitem>
-</varlistentry>
+<para>In the <guilabel>SQL Data Output</guilabel> tool view, there are several buttons:</para>
-<varlistentry id="gdb-menus-step-out">
-<term><menuchoice>
-<guimenu>Debug</guimenu><guimenuitem>Step Out</guimenuitem>
-</menuchoice></term>
-<listitem><para>Resumes execution until the program that is executing
-terminates.</para></listitem>
-</varlistentry>
+<variablelist>
-<varlistentry id="gdb-menus-move-pc">
-<term><menuchoice>
-<guimenu>Debug</guimenu><guimenuitem>Move PC</guimenuitem>
-</menuchoice></term>
-<listitem><para>Move program counter (next execution).</para></listitem>
+<varlistentry>
+<term><guibutton>Resize columns to contents</guibutton></term>
+<listitem><para>Changes the size of columns to fit their contents.</para></listitem>
</varlistentry>
-<varlistentry id="gdb-menus-run-to-cursor">
-<term><menuchoice>
-<guimenu>Debug</guimenu><guimenuitem>Run To Cursor</guimenuitem>
-</menuchoice></term>
-<listitem><para>Runs the program until it reaches current cursor position.
-</para></listitem>
+<varlistentry>
+<term><guibutton>Resize rows to contents</guibutton></term>
+<listitem><para>Changes the size of rows to fit their contents.</para></listitem>
</varlistentry>
-<varlistentry id="gdb-menus-continue">
-<term><menuchoice>
-<guimenu>Debug</guimenu><guimenuitem>Continue</guimenuitem>
-</menuchoice></term>
-<listitem><para>Ignores any breakpoints and executes program until it terminates
-(successfully or not).</para></listitem>
+<varlistentry>
+<term><guibutton>Copy</guibutton></term>
+<listitem><para>Selects all of the table contents and copies it to the clipboard buffer.</para></listitem>
</varlistentry>
-<varlistentry id="gdb-menus-print-value">
-<term><menuchoice>
-<guimenu>Debug</guimenu><guimenuitem>Print Value</guimenuitem>
-</menuchoice></term>
-<listitem><para>Prints the value of the variable that the cursor is currently
-pointing to.</para></listitem>
+<varlistentry>
+<term><guibutton>Export</guibutton></term>
+<listitem><para>Exports all of the table contents to a file, the clipboard, or the
+current document in the Comma Separated Values format.</para></listitem>
</varlistentry>
-<varlistentry id="gdb-menus-toolbar">
-<term><menuchoice>
-<guimenu>Settings</guimenu><guisubmenu>Toolbars Shown</guisubmenu><guimenuitem>&gdb; Plugin</guimenuitem>
-</menuchoice></term>
-<listitem><para>Display the debugging toolbar.</para></listitem>
+<varlistentry>
+<term><guibutton>Clear</guibutton></term>
+<listitem><para>Removes everything from the table view</para></listitem>
</varlistentry>
</variablelist>
-</sect2>
-
-<sect2 id="gdb-debug-view">
-<title>Debug View</title>
-
-<para>The <guilabel>Debug View</guilabel> tool view consists of several tabs:
-</para>
-
-<variablelist>
+<para>You can now change the colors displayed in the table in the <guilabel>SQL</guilabel>
+section of <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &kate;</guimenuitem>
+</menuchoice>.</para>
-<varlistentry>
-<term><guilabel>&gdb; Output</guilabel></term>
-<listitem>
-<para>Contains output from &gdb; and a &gdb; command line.</para>
+</sect3>
+</sect2>
-<screenshot id="screenshot-gdb-output">
-<screeninfo>The Output Tab</screeninfo>
-<mediaobject>
-<imageobject><imagedata fileref="gdb-output.png" format="PNG"/></imageobject>
-<textobject><phrase>The Output tab.</phrase></textobject>
-<caption><para>The <guilabel>Output</guilabel> tab displaying the output from a
-debugging session.</para></caption>
-</mediaobject>
-</screenshot>
+<sect2 id="sql-browsing">
+<title>Browsing</title>
-</listitem>
-</varlistentry>
+<para>You can browse your database using the <guilabel>SQL Schema Browser</guilabel>
+tool view on the left. The information displayed varies depending on which
+database driver you are using.</para>
-<varlistentry>
-<term><guilabel>Settings</guilabel></term>
-<listitem>
-<variablelist>
+<para>To refresh this list, right-click anywhere in the tool view and select
+<guimenuitem>Refresh</guimenuitem>. To generate a query on any entry in the list,
+right-click on an entry, select <guisubmenu>Generate</guisubmenu>, and select the
+query type (<guimenuitem>SELECT</guimenuitem>, <guimenuitem>UPDATE</guimenuitem>,
+<guimenuitem>INSERT</guimenuitem>, or <guimenuitem>DELETE</guimenuitem>) from
+the submenu that appears.</para>
-<varlistentry>
-<term><guilabel>Target</guilabel></term>
-<listitem><para>Path to the target (executable) for debugging.</para></listitem>
-</varlistentry>
+</sect2>
-<varlistentry>
-<term><guilabel>Working Directory</guilabel></term>
-<listitem><para>The current working directory provided to the target.
-</para></listitem>
-</varlistentry>
+<sect2 id="sql-menus">
+<title>Menu Structure</title>
+<variablelist>
<varlistentry>
-<term><guilabel>Arg List</guilabel></term>
-<listitem><para>Arguments passed to the program.</para></listitem>
+<term><menuchoice>
+<guimenu>SQL</guimenu><guimenuitem>Add connection...</guimenuitem>
+</menuchoice></term>
+<listitem><para>
+Adds a new connection using any database driver.
+</para></listitem>
</varlistentry>
<varlistentry>
-<term><guilabel>Keep focus</guilabel></term>
-<listitem><para>Keeps focus on the &gdb; command line.</para></listitem>
+<term><menuchoice>
+<guimenu>SQL</guimenu><guimenuitem>Remove connection</guimenuitem>
+</menuchoice></term>
+<listitem><para>
+Removes the selected connection.
+</para></listitem>
</varlistentry>
<varlistentry>
-<term><guilabel>Redirect IO</guilabel></term>
-<listitem><para>Opens a new <guilabel>IO</guilabel> tab in the <guilabel>Debug
-View</guilabel> where you can view output and provide input to the running
-program.</para></listitem>
+<term><menuchoice>
+<guimenu>SQL</guimenu><guimenuitem>Edit connection...</guimenuitem>
+</menuchoice></term>
+<listitem><para>
+Edits the current connection's settings.
+</para></listitem>
</varlistentry>
-</variablelist>
-
-<screenshot id="screenshot-gdb-settings">
-<screeninfo>The Settings Tab</screeninfo>
-<mediaobject>
-<imageobject><imagedata fileref="gdb-settings.png" format="PNG"/></imageobject>
-<textobject><phrase>The Settings tab.</phrase></textobject>
-<caption><para>The <guilabel>Settings</guilabel> tab displaying the configuration
-of a debugging session.</para></caption>
-</mediaobject>
-</screenshot>
-
-</listitem>
+<varlistentry>
+<term>Connections</term>
+<listitem><para>
+All database connections you have created are listed between the
+<guimenuitem>Edit connection</guimenuitem> and <guimenuitem>Run query</guimenuitem>
+menu items. Select one to run queries or make modifications to it.
+</para></listitem>
</varlistentry>
<varlistentry>
-<term><guilabel>IO</guilabel></term>
-<listitem>
-<para>Contains an area that displays output from the running program and a
-command line where you may provide input to it.</para>
-
-<screenshot id="screenshot-gdb-io">
-<screeninfo>The IO Tab</screeninfo>
-<mediaobject>
-<imageobject><imagedata fileref="gdb-io.png" format="PNG"/></imageobject>
-<textobject><phrase>The IO tab.</phrase></textobject>
-<caption><para>The <guilabel>IO</guilabel> tab displaying output from a simple
-test program.</para></caption>
-</mediaobject>
-</screenshot>
-
-</listitem>
+<term><menuchoice>
+<shortcut><keycombo action="simul">&Ctrl;<keycap>E</keycap></keycombo></shortcut>
+<guimenu>SQL</guimenu><guimenuitem>Run query</guimenuitem>
+</menuchoice></term>
+<listitem><para>
+Runs your query.
+</para></listitem>
</varlistentry>
</variablelist>
-
-</sect2>
-
-<sect2 id="gdb-other">
-<title>Call Stack and Locals</title>
-
-<para>The <guilabel>Call Stack</guilabel> tool view contains a list of the formatted
-backtrace returned from &gdb;.</para>
-
-<screenshot id="screenshot-gdb-call-stack">
-<screeninfo>The &gdb; Call Stack Tool View</screeninfo>
-<mediaobject>
-<imageobject><imagedata fileref="gdb-call-stack.png" format="PNG"/></imageobject>
-<textobject><phrase>The Call Stack tool view.</phrase></textobject>
-<caption><para>The &gdb; Plugin's <guilabel>Call Stack</guilabel> tool view.
-</para></caption>
-</mediaobject>
-</screenshot>
-
-<para>The <guilabel>Locals</guilabel> tool view contains a list of all currently
-loaded variables from the program and their corresponding values.</para>
-
-<screenshot id="screenshot-gdb-locals">
-<screeninfo>The &gdb; Locals Tool View</screeninfo>
-<mediaobject>
-<imageobject><imagedata fileref="gdb-locals.png" format="PNG"/></imageobject>
-<textobject><phrase>The Locals tool view.</phrase></textobject>
-<caption><para>The &gdb; Plugin's <guilabel>Locals</guilabel> tool view.
-</para></caption>
-</mediaobject>
-</screenshot>
-
</sect2>
-<sect2 id="gdb-ack">
+<sect2 id="sql-ack">
<title>Thanks and Acknowledgments</title>
-<para>Special thanks to Google Code-In 2011 participant Martin Gergov for
+<para>The SQL Plugin was written by Marco Mentasti.</para>
+<para>Special thanks to Google Code-In 2011 participant Ömer Faruk ORUÇ for
writing much of this section.</para>
</sect2>
@@ -1782,6 +1634,155 @@ so the calling program is aware you have finished editing the file.</para></list
</sect1>
+<!-- from doc/kate-addons/xmlcheck.docbook -->
+<sect1 id="kate-application-plugin-xmltools">
+<sect1info>
+<authorgroup><author>
+&Daniel.Naber; &Daniel.Naber.mail;
+</author></authorgroup>
+</sect1info>
+<title>&XML; Completion</title>
+
+<para>This plugin gives hints about what is allowed at a certain position in
+an &XML; file, according to the file's DTD. It will list possible
+elements, attributes, attribute values or entities, depending on the
+cursor position (⪚ all entities are listed if the character on the left
+of the cursor is <quote>&</quote>). It's also possible to close the nearest
+open tag on the left.</para>
+
+<para>The <acronym>DTD</acronym> must exist in &XML; format, as produced by the Perl program
+<command>dtdparse</command>. We will call a DTD in this format <quote>meta DTD</quote>.
+Some meta DTDs are supplied. They are installed in
+<filename class="directory">$KDEDIR/share/apps/katexmltools/</filename>,
+which is also the default folder when you choose
+<guimenuitem>Assign Meta DTD...</guimenuitem>.
+To produce your own meta DTDs, get <command>dtdparse</command> from
+<ulink url="http://dtdparse.sourceforge.net">http://dtdparse.sourceforge.net</ulink>.</para>
+
+<sect2 id="xmltools-how-to-use">
+<title>How to Use</title>
+
+<para>Start &kate; and open the configuration dialog under <menuchoice><guimenu>Settings</guimenu>
+<guimenuitem>Configure &kate;...</guimenuitem></menuchoice>.
+Then select <guilabel>&XML; Completion</guilabel> which will appear
+in the <menuchoice><guimenu>Application</guimenu>
+<guimenuitem>Plugins</guimenuitem></menuchoice> page and close the dialog. After
+that, select <menuchoice><guimenu>&XML;</guimenu><guimenuitem>Assign Meta DTD...</guimenuitem></menuchoice>.
+If your document contains no <quote>DOCTYPE</quote> or the doctype is unknown, you will have to
+select a meta DTD from the file system. Otherwise the meta DTD that
+matches the current document's DOCTYPE will be loaded automatically.</para>
+
+<para>You can now use the plugin while typing your text:</para>
+
+<variablelist>
+
+<varlistentry>
+<term><keycap><</keycap> (less than key)</term>
+<listitem><para>This will trigger a list of possible elements unless the
+cursor is inside a tag already. Note that you currently cannot use
+this to insert the top level element (⪚ <quote><html></quote>).</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><keycap><</keycap><keycap>/</keycap>(less than key + slash)</term>
+<listitem><para>Entering these characters will offer to close the current element
+(nearest open one to the left of the cursor). Press &Enter; to accept the suggestion.
+Unlike the <guimenuitem>Close Element</guimenuitem> menu item, this works only with
+a DTD assigned.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><keycap>"</keycap> (quote key)</term>
+<listitem><para>The quote key will trigger a list of possible attribute
+values (if there are any) if you are inside a tag.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><keycap> </keycap> (space key)</term>
+<listitem><para>This key will trigger a list of possible attributes for the
+current element if you are inside a tag.</para>
+</listitem>
+</varlistentry>
+
+<varlistentry>
+<term><keycap>&</keycap> (ampersand key)</term>
+<listitem><para>This key will trigger a list of named entities.</para></listitem>
+</varlistentry>
+</variablelist>
+
+</sect2>
+
+<sect2 id="xmltools-features-and-limitations">
+<title>Features and Limitations</title>
+
+<para>You can test all functions and limitations by loading
+<filename>$KDEDIR/share/apps/katexmltools/testcases.xml</filename><!--FIXME replacement for KDEDIRS-->
+into &kate; and following the instructions.</para>
+
+</sect2>
+
+
+<sect2 id="xmltools-menu">
+<title>Menu Structure</title>
+
+<variablelist id="xml-insert-element">
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap>Return</keycap></keycombo>
+</shortcut>
+<guimenu>&XML;</guimenu>
+<guimenuitem>Insert Element...</guimenuitem>
+</menuchoice></term>
+<listitem><para>This will open a dialog that lets you insert an &XML; element.
+The <, > characters and the closing tag will be inserted automatically.
+If you have selected text when this menu item is selected, the selected
+text will be surrounded by the opening and the closing tag.
+The dialog also offers completion of all elements that may be inserted
+at the current cursor position if you have assigned a meta DTD by
+using <guimenuitem>Assign Meta DTD...</guimenuitem>.
+</para></listitem>
+</varlistentry>
+
+<varlistentry id="xml-close-element">
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;<keycap><</keycap></keycombo>
+</shortcut>
+<guimenu>&XML;</guimenu>
+<guimenuitem>Close Element</guimenuitem>
+</menuchoice></term>
+<listitem><para>This will search your text for a tag that is not yet closed
+and will close it by inserting the corresponding closing tag.
+The search starts at the cursor position and goes left. If
+it cannot find an open tag nothing will happen.</para></listitem>
+</varlistentry>
+
+<varlistentry id="xml-assign-metadtd">
+<term><menuchoice>
+<guimenu>&XML;</guimenu>
+<guimenuitem>Assign Meta DTD...</guimenuitem>
+</menuchoice></term>
+<listitem><para>This will tell the plugin which meta DTD to use for the
+current document. Note that this assignment will not be saved.
+You will have to repeat it when you start &kate; the next time.</para></listitem>
+</varlistentry>
+</variablelist>
+
+</sect2>
+
+<sect2 id="xmltools-thanks-and-acknowledgements">
+<title>Thanks and Acknowledgments</title>
+<para>
+&kate; Plugin <quote>&XML; Completion</quote> copyright 2001,2002 &Daniel.Naber;
+&Daniel.Naber.mail;.
+</para>
+<para>KDE SC 4 version copyright 2010 Tomáš Trnka</para>
+<para>Documentation copyright 2001,2002 &Daniel.Naber;</para>
+</sect2>
+</sect1>
+
+
<!--FIXME
Missing (according to config docs)
Additional pages for enabled plugins:
More information about the kde-doc-english
mailing list