doc/kate/plugins.docbook

<chapter id="plugins">

<chapterinfo>
<authorgroup>
<author>&Anders.Lund; &Anders.Lund.mail;</author>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>
</chapterinfo>

<title>Working with Plugins</title>

<para>You can enable the individual plugins in the <link
linkend="configuring-kate-configdialog">configuration dialog</link>, which also
provides access to additional configuration options for plugins that require
it.</para>

<sect1 id="kate-application-plugins">
<title>&kate; Application Plugins</title>

<!-- from doc/kate-addons/index.docbook -->
<para>
&kate; plugins are additional functions for the &kate; editor.  They can
add extra menus and shortcuts, and extend &kate;'s features.  You can
install as many or as few as you like, from within &kate;.
Open &kate;'s configuration dialog with
<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &kate;...</guimenuitem></menuchoice>
Select <menuchoice><guimenu>Application</guimenu><guimenuitem>Plugins</guimenuitem></menuchoice> to
choose the wanted plugins.
</para>

<para>
The available application plugins are:
</para>
<itemizedlist>
<listitem>
<para><link linkend="kate-application-plugin-external-tools">External Tools</link>
- Run external tools and applications</para>
</listitem>
<listitem>
<para><link linkend="kate-application-plugin-backtracebrowser">Backtrace Browser</link>
- C/C++ Backtrace navigation tool view</para>
</listitem>
<listitem>
<para><link linkend="kate-application-plugin-build">Build Plugin</link> - Compile or Make and parse error messages</para>
</listitem>
<listitem>
<para><link linkend="kate-application-plugin-closeexceptlike">Close Except/Like</link>
- Close group of documents based on a common path or file extension</para>
</listitem>
<listitem>
<para><link linkend="kate-application-plugin-colorpicker">Color Picker</link>
- Show preview for known color names</para>
</listitem>
<listitem>
<para><link linkend="kate-application-plugin-ctags">CTags</link> -
Look up definitions/declarations with CTags</para>
</listitem>
<listitem>
<para><link linkend="kate-application-plugin-preview">Document preview</link> -
Preview the document in the target format.</para>
</listitem>
<listitem>
<para><link linkend="kate-application-plugin-documentswitcher">Document switcher</link> -
Quick document switching with <keycombo action="simul">&Alt;&Tab;</keycombo> behavior</para>
</listitem>
<listitem>
<para><link linkend="kate-application-plugin-fsbrowser">File System Browser</link> -
  File system browser tool view</para>
</listitem>
<listitem>
<para><link linkend="kate-application-plugin-documents">Document Tree View</link> - Displays the open files in a file tree</para>
</listitem>
<listitem>
<para><link linkend="kate-application-plugin-gdb">&gdb;</link> - Provides a
simple &gdb; frontend</para>
</listitem>
<!--from workspace/plasma-sdk, why picked up here?
<listitem>
<para>Icon picker - Invokes Cuttlefish icon picker</para>
</listitem>
-->
<listitem>
<para><link linkend="kate-application-plugin-projects">Project Plugin</link> - Integration with &git; and other source control systems</para>
</listitem>
<listitem>
<para>Replicode - Constructivist AI language and runtime</para>
</listitem>
<listitem>
<para><link linkend="kate-application-plugin-lspclient">LSP Client</link>
- LSP client providing code navigation and code completion for many languages</para>
</listitem>
<listitem>
<para><link linkend="kate-application-plugin-searchinfiles">Search &amp; Replace</link> -
Search and replace in documents, folders, or projects</para>
</listitem>
<listitem>
<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
query on SQL databases</para>
</listitem>
<listitem>
<para><link linkend="kate-application-plugin-symbolviewer">Symbol Viewer</link>
- Extract and show reference symbols from source</para>
</listitem>
<listitem>
<para><link linkend="kate-application-plugin-konsole">Terminal tool view</link> - Have a terminal at the ready, using &kde;'s &konsole; widget</para>
</listitem>
<listitem>
<para><link linkend="kate-application-plugin-textfilter">Text Filter</link> - Process text using terminal commands</para>
</listitem>
<listitem>
<para><link linkend="kate-application-plugin-xmltools">&XML;Completetion</link> - Lists &XML; elements,
attributes, attribute values and entities allowed by DTD</para>
</listitem>
<listitem>
<para><link linkend="kate-application-plugin-xmlcheck">&XML; Validation</link>- Validates &XML; files using xmllint</para>
</listitem>
</itemizedlist>
</sect1>

<sect1 id="kate-application-plugin-external-tools">
<title>External Tools</title>

<para>The <guilabel>External Tools</guilabel> plugin allows to invoke
external applications with data related to the current document, for example
its URL, directory, text or selection. Once enabled, a config page appears
as depicted below that allows to change or remove existing tools. Similarly,
new tools can be added to your liking. The tools will then appear in the
<guisubmenu>External Tools</guisubmenu> submenu of the <guimenu>Tools</guimenu>
menu of the application.
</para>

<mediaobject>
<imageobject>
<imagedata format="PNG" fileref="kateexternaltools.png"/>
</imageobject>
</mediaobject>

<para>
The config page allows to add new external tools by clicking on the
<guilabel>Add</guilabel> button. In this case, a popup menu appears where one
can either add a new external tool, add an existing tool from a predefined list,
or add a new category to organize the external tools into categories. Similarly,
the existing tools can be modified either by double-click or by invoking
<guilabel>Edit...</guilabel>, and <guilabel>Remove</guilabel> removes the
selected tools.
</para>

<sect2 id="kate-application-plugin-external-tools-edit">
<title>Configuring External Tools</title>

<para>Editing a tool opens a config dialog that allows fine-grained
configuration of the tool:</para>

<mediaobject>
<imageobject>
<imagedata format="PNG" fileref="kateeditexternaltool.png"/>
</imageobject>
</mediaobject>

<variablelist>
<varlistentry>
<term>As can be seen, many details can be defined, namely:</term>
<listitem>
<para><userinput>Name</userinput>, the name of the tool, which will later appear in the menu.</para>
<para><userinput>Icon</userinput>, optional icon that is visible in the menu.</para>
<para><userinput>Executable</userinput>, executable including either a full path, or your executable must be in the <envar>PATH</envar> environment variable.</para>
<para><userinput>Arguments</userinput>, optional arguments that are passed to the executable.</para>
<para><userinput>Input</userinput>, optional input that is passed to the process via stdin.</para>
<para><userinput>Working directory</userinput>, the working directory the tool will be started in. If empty, the working directory is set to the current document’s path.</para>
<para><userinput>Mime types</userinput>, if set, the tool is active only if the current document’s mime type matches.</para>
<para><userinput>Save</userinput>, when invoked, saves none, the current document, or all documents.</para>
<para><userinput>Reload current document after execution</userinput>, useful when the current file is modified on disk.</para>
<para><userinput>Output</userinput>, the output defines the target of stdout. It is either set to <userinput>Ignored</userinput>, <userinput>Insert at Cursor Position</userinput>, <userinput>Replace Selected Text</userinput>, <userinput>Replace Current Document</userinput>, <userinput>Append to Current Document</userinput>, <userinput>Insert in New Document</userinput>, <userinput>Copy to Clipboard</userinput>, or <userinput>Display in Pane</userinput>.</para>
<para><userinput>Editor command</userinput>, optional command that can be used to invoke the external tool via the built-in <ulink url="help:/katepart/advanced.html#advanced-editing-tools-commandline">command line</ulink>.</para>
</listitem>
</varlistentry>
</variablelist>

<para>The button <guilabel>Defaults</guilabel> is visible only for tools that
are shipped with Kate. When clicked, all tool’s settings reverted to default
(aka factory) values.
</para>

</sect2>

<sect2 id="kate-application-plugin-external-tools-variables">
<title>Variable Expansion</title>

<para>
Some editing fields such as the <guilabel>Executable</guilabel>, the
<guilabel>Arguments</guilabel>, the <guilabel>Input</guilabel> and the
<guilabel>Working Directory</guilabel> support variables that are expanded
on tool invocation. This is indicated by the icon <guilabel>{}</guilabel>
that appears once one of these text input fields has focus (see red circle):
</para>

<mediaobject>
<imageobject>
<imagedata format="PNG" fileref="katevariableexpansion.png"/>
</imageobject>
</mediaobject>

<para>
Hovering over one of these text input fields also shows a tooltip with the
current expanded text. Further, clicking on the <guilabel>{}</guilabel>
action will open a dialog that lists all available variables:
</para>

<mediaobject>
<imageobject>
<imagedata format="PNG" fileref="kateexternaltoolvariablechooser.png"/>
</imageobject>
</mediaobject>

<para>
This feature provides a lot of flexibility when defining an external tool since
all variables of the form <userinput>%{...}</userinput> are expanded when the tool
gets invoked. There are two kind of variables supported:

<itemizedlist>
<listitem><para><userinput>%{variable-name}</userinput></para></listitem>
<listitem><para><userinput>%{variable-name:&lt;value&gt;}</userinput></para></listitem>
</itemizedlist>
The first form <userinput>%{variable-name}</userinput> simply replaces the
variable with its contents. For instance, the variable <userinput>%{Document:FileName}</userinput>
is replaced by the current document’s filename without its path.
The second form <userinput>%{variable-name:&lt;value&gt;}</userinput> gets the
<userinput>&lt;value&gt;</userinput> as contents. For example, this can be used
to expand an environment variable with <userinput>%{ENV:HOME}</userinput>,
or one can obtain the current date in the preferred format like
<userinput>%{Date:yyyy-MM-dd}</userinput>.
</para>

<variablelist>
<varlistentry>
<term>Supported variables include:</term>
<listitem>
<para><userinput>Document:FileBaseName</userinput>: File base name without path and suffix of the current document.</para>
<para><userinput>Document:FileExtension</userinput>: File extension of the current document.</para>
<para><userinput>Document:FileName</userinput>: File name without path of the current document.</para>
<para><userinput>Document:FilePath</userinput>: Full path of the current document including the file name</para>
<para><userinput>Document:Text</userinput>: Contents of the current document.</para>
<para><userinput>Document:Path</userinput>: Full path of the current document excluding the file name.</para>
<para><userinput>Document:NativeFilePath</userinput>: Full document path including file name, with native path separator (backslash on Windows).</para>
<para><userinput>Document:NativePath</userinput>: Full document path excluding file name, with native path separator (backslash on Windows).</para>
<para><userinput>Document:Cursor:Line</userinput>: Line number of the text cursor position in current document (starts with 0).</para>
<para><userinput>Document:Cursor:Column</userinput>: Column number of the text cursor position in current document (starts with 0).</para>
<para><userinput>Document:Cursor:XPos</userinput>: X component in global screen coordinates of the cursor position.</para>
<para><userinput>Document:Cursor:YPos</userinput>: Y component in global screen coordinates of the cursor position.</para>
<para><userinput>Document:Selection:Text</userinput>: Text selection of the current document.</para>
<para><userinput>Document:Selection:StartLine</userinput>: Start line of selected text of the current document.</para>
<para><userinput>Document:Selection:StartColumn</userinput>: Start column of selected text of the current document.</para>
<para><userinput>Document:Selection:EndLine</userinput>: End line of selected text of the current document.</para>
<para><userinput>Document:Selection:EndColumn</userinput>: End column of selected text of the current document.</para>
<para><userinput>Document:RowCount</userinput>: Number of rows of the current document.</para>
<para><userinput>Document:Variable:&lt;variable&gt;</userinput>: Expand arbitrary <ulink url="help:/katepart/config-variables.html">document variables</ulink>.</para>
<para><userinput>Date:Locale</userinput>: The current date in current locale format.</para>
<para><userinput>Date:ISO</userinput>: The current date (ISO).</para>
<para><userinput>Date:&lt;value&gt;</userinput>: The current date (<ulink url="https://doc.qt.io/qt-5/qdate.html#toString">QDate formatstring</ulink>).</para>
<para><userinput>Time:Locale</userinput>: The current time in current locale format.</para>
<para><userinput>Time:ISO</userinput>: The current time (ISO).</para>
<para><userinput>Time:&lt;value&gt;</userinput>: The current time (<ulink url="https://doc.qt.io/qt-5/qtime.html#toString">QTime formatstring</ulink>).</para>
<para><userinput>ENV:&lt;value&gt;</userinput>: Access to environment variables.</para>
<para><userinput>JS:&lt;expression&gt;</userinput>: Evaluate simple JavaScript statements.</para>
<para><userinput>PercentEncoded:&lt;text&gt;</userinput>: Percent encoded text.</para>
<para><userinput>UUID</userinput>: Generate a new UUID.</para>
</listitem>
</varlistentry>
</variablelist>

<para>
</para>

</sect2>

<sect2 id="kate-application-plugin-external-tools-defaults">
<title>List of Default Tools</title>

<para>
Several tools are shipped by default. However, if you have more useful tools
please contribute those to <email>kwrite-devel@kde.org</email> so that we can add them to this list.
All default tools are visible in the list view by default. However, all tools can be
changed to your liking, including the category or even deleting tools.
Deleted tools can be added back again by clicking on the <guibutton>Add</guibutton>
button in the config page as described above.
</para>

<variablelist>
<title>git-cola</title>

<varlistentry>
<term>git-cola is a graphical git client that enables you to easily stage and commit changes.
If installed, it is available also through the command line by typing <userinput>git-cola</userinput></term>
<listitem>
<para><userinput>Name</userinput>: git-cola</para>
<para><userinput>Icon</userinput>: git-cola</para>
<para><userinput>Executable</userinput>: git-cola</para>
<para><userinput>Arguments</userinput>: -r %{Document:Path}</para>
<para><userinput>Editor command</userinput>: git-cola</para>
</listitem>
</varlistentry>

</variablelist>


<variablelist>
<title>gitk</title>

<varlistentry>
<term>gitk is a git client as well that allows to nicely visualize the git history.</term>
<listitem>
<para><userinput>Name</userinput>: gitk</para>
<para><userinput>Icon</userinput>: git-gui</para>
<para><userinput>Executable</userinput>: gitk</para>
<para><userinput>Working directory</userinput>: %{Document:Path}</para>
<para><userinput>Editor command</userinput>: gitk</para>
</listitem>
</varlistentry>

</variablelist>


<variablelist>
<title>git blame</title>

<varlistentry>
<term>Starts git blame to easily follow git changes in the current file.</term>
<listitem>
<para><userinput>Name</userinput>: git blame</para>
<para><userinput>Executable</userinput>: git</para>
<para><userinput>Arguments</userinput>: gui blame %{Document:FileName}</para>
<para><userinput>Save</userinput>: Current Document</para>
<para><userinput>Working directory</userinput>: %{Document:Path}</para>
<para><userinput>Editor command</userinput>: git-blame</para>
</listitem>
</varlistentry>

</variablelist>


<variablelist>
<title>Run Shell Script</title>

<varlistentry>
<term>Starts an external konsole in which the current document is executed.
The script needs to state the interpreter in the first line via a shebang <userinput>#!/path/interpreter</userinput>.</term>
<listitem>
<para><userinput>Name</userinput>: Run Shell Script</para>
<para><userinput>Icon</userinput>: system-run</para>
<para><userinput>Executable</userinput>: konsole</para>
<para><userinput>Arguments</userinput>: -e sh -c &quot;cd %{Document:Path} &amp;&amp; pwd &amp;&amp; chmod -vc a+x %{Document:FileName} &amp;&amp; ./%{Document:FileName} ; echo Press any key to continue. &amp;&amp; read -n 1&quot;</para>
<para><userinput>Save</userinput>: Current Document</para>
<para><userinput>Working directory</userinput>: %{Document:Path}</para>
<para><userinput>Editor command</userinput>: run-script</para>
</listitem>
</varlistentry>

</variablelist>


<variablelist>
<title>Google Selected Text</title>

<varlistentry>
<term>Search in google for the selected text.</term>
<listitem>
<para><userinput>Name</userinput>: Google Selected Text</para>
<para><userinput>Icon</userinput>: globe</para>
<para><userinput>Executable</userinput>: xdg-open</para>
<para><userinput>Arguments</userinput>: &quot;https://www.google.com/search?q=%{Document:Selection:Text}&quot;</para>
<para><userinput>Editor command</userinput>: google</para>
</listitem>
</varlistentry>

</variablelist>


<variablelist>
<title>Insert UUID</title>

<varlistentry>
<term>Inserts a new UUID each time this action is invoked.</term>
<listitem>
<para><userinput>Name</userinput>: Insert UUID</para>
<para><userinput>Executable</userinput>: echo</para>
<para><userinput>Arguments</userinput>: %{UUID}</para>
<para><userinput>Output</userinput>: Insert at Cursor Position</para>
<para><userinput>Editor command</userinput>: uuid</para>
</listitem>
</varlistentry>

</variablelist>


<variablelist>
<title>Clang Format Full File</title>

<varlistentry>
<term>Runs clang-format on the current file on disk. The document is reloaded afterwards.</term>
<listitem>
<para><userinput>Name</userinput>: Clang Format Full File</para>
<para><userinput>Executable</userinput>: clang-format</para>
<para><userinput>Arguments</userinput>: -i %{Document:FileName}</para>
<para><userinput>Working directory</userinput>: %{Document:Path}</para>
<para><userinput>Save</userinput>: Current Document</para>
<para><userinput>Reload</userinput>: Yes</para>
<para><userinput>Editor command</userinput>: clang-format-file</para>
</listitem>
</varlistentry>

</variablelist>


<variablelist>
<title>Clang Format Selected Text</title>

<varlistentry>
<term>Runs clang-format just on the selected text in the current document.</term>
<listitem>
<para><userinput>Name</userinput>: Clang Format Selected Text</para>
<para><userinput>Executable</userinput>: clang-format</para>
<para><userinput>Arguments</userinput>: -assume-fileName: %{Document:FileName}</para>
<para><userinput>Working directory</userinput>: %{Document:Path}</para>
<para><userinput>Input</userinput>: %{Document:Selection:Text}</para>
<para><userinput>Output</userinput>: Replace Selected Text</para>
<para><userinput>Editor command</userinput>: clang-format-selection</para>
</listitem>
</varlistentry>

</variablelist>


<variablelist>
<title>Qt Quick 2 Preview (qmlscene)</title>

<varlistentry>
<term>Previews the current qml file in qmlscene.</term>
<listitem>
<para><userinput>Name</userinput>: Qt Quick 2 Preview (qmlscene)</para>
<para><userinput>Executable</userinput>: qmlscene</para>
<para><userinput>Arguments</userinput>: %{Document:FileName}</para>
<para><userinput>Save</userinput>: Current Document</para>
<para><userinput>Working directory</userinput>: %{Document:Path}</para>
<para><userinput>Editor command</userinput>: qml-preview</para>
</listitem>
</varlistentry>

</variablelist>


<variablelist>
<title>JSON Format Full File</title>

<varlistentry>
<term>Format the entire JSON file.</term>
<listitem>
<para><userinput>Name</userinput>: JSON Format Full File</para>
<para><userinput>Icon</userinput>: application-json</para>
<para><userinput>Executable</userinput>: jq</para>
<para><userinput>Arguments</userinput>: %{Document:FileName}</para>
<para><userinput>Save</userinput>: Current Document</para>
<para><userinput>Working directory</userinput>: %{Document:Path}</para>
<para><userinput>Output</userinput>: Replace Current Document</para>
<para><userinput>Editor command</userinput>: json-format-file</para>
</listitem>
</varlistentry>

</variablelist>


<variablelist>
<title>XML Format Full File</title>

<varlistentry>
<term>Format the entire XML file.</term>
<listitem>
<para><userinput>Name</userinput>: JSON Format Full File</para>
<para><userinput>Icon</userinput>: application-xml</para>
<para><userinput>Executable</userinput>: xmllint</para>
<para><userinput>Arguments</userinput>: --format %{Document:FileName}</para>
<para><userinput>Save</userinput>: Current Document</para>
<para><userinput>Working directory</userinput>: %{Document:Path}</para>
<para><userinput>Output</userinput>: Replace Current Document</para>
<para><userinput>Editor command</userinput>: xml-format-file</para>
</listitem>
</varlistentry>

</variablelist>

</sect2>
</sect1>

<sect1 id="kate-application-plugin-backtracebrowser">
<!--https://kate-editor.org/2008/08/12/kate-fast-backtrace-navigation/-->
<title>Backtrace Browser Plugin</title>

<sect2 id="backtracebrowser-using">
<title>Using the Backtrace Browser Plugin</title>

<para>This plugin is meant for developers and probably of little use for users.
It shows a backtrace delivered by gdb in a listview in a &kate; toolview.
Clicking on an item opens the selected file and jumps to the correct line number.
It works for backtraces generated on your own machine, but it will also work for
backtraces from other people, &ie; with <filename>/home/dummy/qt-copy/…/qwidget.cpp</filename>
will still be found on other machines. For that to work, you have to index the
directories where the source code is located.
</para>

<para>Sometimes there are several files with the same name, &eg;</para>

<simplelist>
<member><filename>kdegraphics/okular/generators/dvi/config.h</filename></member>
<member><filename>kdepim-runtime/resources/gmail/saslplugin/config.h</filename></member>
</simplelist>

<para>To pick the right choice, the plugin picks the last two parts of the &URL;,
in this case this would be</para>

<simplelist>
<member><filename>dvi/config.h</filename></member>
<member><filename>saslplugin/config.h</filename></member>
</simplelist>

<para>And then usually the plugin finds the correct one.</para>

<para>Indexing master and a branches of course will lead to a clash.</para>

</sect2>

<sect2 id="backtracebrowser-config">
<title>Configuration</title>

<para>On the configuration page add the directories containing the source code.</para>

<screenshot id="screenshot-backtrace-settings">
<screeninfo>Backtrace Browser</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="backtrace-settings.png" format="PNG"/></imageobject>
<caption>Configure Paths in Backtrace browser tool view</caption>
</mediaobject>
</screenshot>

<para>Clicking <guibutton>OK</guibutton> will start indexing.
When indexing is finished, open the toolview <guilabel>Backtrace Browser</guilabel>.</para>
<para>Now you can load a backtrace from the clipboard (&eg;, when you clicked
<guibutton>Copy to Clipboard</guibutton> in &drkonqi;) or from a file.</para>

</sect2>

</sect1>

<sect1 id="kate-application-plugin-build">
<!--https://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>The Build plugin allows you to run actions like build, clean and compile
on a project.</para>

</sect2>

<sect2 id="build-using">
<title>Using the Build Plugin</title>

<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>

<screenshot id="screenshot-build-output">
<screeninfo>Build Output</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="build-output.png" format="PNG"/></imageobject>
</mediaobject>
</screenshot>

<para>The <guilabel>Build Output</guilabel> tool view has two tabs:</para>

<itemizedlist>
<listitem><para><guilabel>Target Settings</guilabel></para></listitem>
<listitem><para><guilabel>Output</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 and define targets sets.</para>

<para>To change the names or commands double click on the entries in the table and use the
dropdown box to select the active target set. Use the checkbox in front of each target to define a default.</para>

<para>A new target set contains several configuration options:</para>

<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>
</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>
</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>
</varlistentry>

<varlistentry>
<term><guilabel>Config</guilabel></term>
<listitem><para>This option lets you define the config command. It is set
to <command>cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_INSTALL_PREFIX=/usr/local ../</command>
by default.</para></listitem>
</varlistentry>
</variablelist>

<para>On the top this plugin has a toolbar with the following buttons :</para>

<simplelist>
<member>
<guiicon><inlinemediaobject><imageobject><imagedata fileref="dialog-ok-22.png" format="PNG"/></imageobject></inlinemediaobject></guiicon>
Build the selected target</member>
<member>
<guiicon><inlinemediaobject><imageobject><imagedata fileref="list-add-22.png" format="PNG"/></imageobject></inlinemediaobject></guiicon>
Add a new build target</member>
<member>
<guiicon><inlinemediaobject><imageobject><imagedata fileref="document-new-22.png" format="PNG"/></imageobject></inlinemediaobject></guiicon>
Create a new build target set</member>
<member>
<guiicon><inlinemediaobject><imageobject><imagedata fileref="edit-copy-22.png" format="PNG"/></imageobject></inlinemediaobject></guiicon>
Copy a command or target set</member>
<member>
<guiicon><inlinemediaobject><imageobject><imagedata fileref="edit-delete-22.png" format="PNG"/></imageobject></inlinemediaobject></guiicon>
Delete the current command or target set</member>
</simplelist>

</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>

<para>Use the slider at the top to show or hide categories of output:</para>

<para><guilabel>Full Output</guilabel>, <guilabel>Parsed Output</guilabel>,
<guilabel>Errors and Warnings</guilabel> or <guilabel>Only Errors</guilabel>
</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>To navigate to the previous error, press
<keycombo action="simul">&Alt;&Shift;&Left;</keycombo>.
To navigate to the next error, press
<keycombo action="simul">&Alt;&Shift;&Right;</keycombo>.</para>

</sect3>
</sect2>

<sect2 id="build-menu">
<title>Menu Structure</title>

<variablelist id="build-build">
<varlistentry>
<term><menuchoice id="build-targets">
<guimenu>Build</guimenu><guisubmenu>Select Target</guisubmenu>
</menuchoice></term>
<listitem><para>Select from a list of targets configured by the user.</para></listitem>
</varlistentry>

<varlistentry id="build-default">
<term><menuchoice>
<guimenu>Build</guimenu><guimenuitem>Build Default Target</guimenuitem>
</menuchoice></term>
<listitem><para>Builds the target defined as default in the active target set.</para></listitem>
</varlistentry>

<varlistentry id="build-previous">
<term><menuchoice>
<guimenu>Build</guimenu><guimenuitem>Build Previous Target</guimenuitem>
</menuchoice></term>
<listitem><para>Switch to the previous target configured by the user.</para></listitem>
</varlistentry>

<varlistentry id="build-stop">
<term><menuchoice>
<guimenu>Build</guimenu><guimenuitem>Stop</guimenuitem>
</menuchoice></term>
<listitem><para>Stop building a target.</para></listitem>
</varlistentry>

<varlistentry id="build-previous-error">
<term><menuchoice>
<shortcut><keycombo action="simul">&Ctrl;&Alt;&Left;</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>

<varlistentry id="build-next-error">
<term><menuchoice>
<shortcut><keycombo action="simul">&Ctrl;&Alt;&Right;</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>

</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-closeexceptlike">

<title>Close Except/Like Plugin</title>

<sect2 id="closeexceptlike-intro">
<title>Introduction</title>

<para>This plugin allows you to close a group of documents based on their extension and path.</para>

</sect2>

<sect2 id="closeexceptlike-using">
<title>Using the Close Except/Like Plugin</title>

<para>Assumed you have these documents opened in &kate;:</para>

<simplelist>
<member>/tmp/subfolder/test.h</member>
<member>/tmp/test.cpp</member>
<member>/tmp/test.txt</member>
</simplelist>

<para>Then you have the following options to close documents as displayed in the screenshot:</para>

<screenshot id="screenshot-closeexceptlike">
<screeninfo>Close Except</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="close-except-like.png" format="PNG"/></imageobject>
</mediaobject>
</screenshot>

<para>Use the checkbox in the last item of the list to enable or disable a confirmation dialog.
The selected option will be applied to both close actions.
</para>

</sect2>

<sect2 id="closeexceptlike-menu">
<title>Menu Structure</title>

<variablelist>
<varlistentry id="file-close-except">
<term><menuchoice>
<guimenu>File</guimenu>
<guisubmenu>Close Except</guisubmenu>
</menuchoice></term>
<listitem>
<para><action>Close</action> all open documents, <emphasis>except</emphasis>
those which match the path or file extension selected from the submenu.</para>
</listitem>
</varlistentry>

<varlistentry id="file-close-like">
<term><menuchoice>
<guimenu>File</guimenu>
<guisubmenu>Close Like</guisubmenu>
</menuchoice></term>
<listitem>
<para><action>Close</action> all open documents
which match the path or file extension selected from the submenu.</para>
</listitem>
</varlistentry>

</variablelist>

</sect2>

</sect1>

<sect1 id="kate-application-plugin-colorpicker">

<title>Color Picker Plugin</title>

<sect2 id="colorpicker-intro">
<title>Introduction</title>

<para>This plugin adds an inline color preview/picker to colors in the text (&eg;, <literal>#FFFFFF</literal>,
<literal>white</literal>).</para>

<para>To load this plugin open &kate;'s configuration dialog under <menuchoice><guimenu>Settings</guimenu>
<guimenuitem>Configure &kate;...</guimenuitem></menuchoice>.
Then select <guilabel>Color Picker</guilabel> and close the dialog.
</para>
</sect2>

<sect2 id="colorpicker-config">
<title>Configuration</title>

<para>On the Color Picker settings page in &kate;'s configuration, you can configure the following options of the plugin behavior.</para>

<variablelist>

<varlistentry>
<term><guilabel>Show preview for known color names</guilabel></term>
<listitem>
<para>Whether to show the color picker for known color names (&eg;, <literal>skyblue</literal>). See <ulink url="https://www.w3.org/TR/SVG11/types.html#ColorKeywords">this page</ulink> for the list of colors.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Place preview after text color</guilabel></term>
<listitem>
<para>Whether to place the inline preview after text color in the text.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Hex color matching</guilabel></term>
<listitem>
<para>Here, you can choose the best matching option for the colors used in your code.</para>
</listitem>
</varlistentry>

</variablelist>

</sect2>

</sect1>

<sect1 id="kate-application-plugin-ctags">
<!--https://kate-editor.org/2012/11/02/using-the-projects-plugin-in-kate/-->
<title>CTags Plugin</title>

<sect2 id="ctags-intro">
<title>Introduction</title>

<para><ulink url="https://en.wikipedia.org/wiki/Ctags">CTags</ulink> generates an
index (or tag) file of language objects found in source files that allows these
items to be quickly and easily located using this plugin in &kate;.
</para>
<para>A tag signifies a language object for which an index entry is available
(or, alternatively, the index entry created for that object).</para>

<para>Tag generation is supported for these
<ulink url="http://ctags.sourceforge.net/languages.html">programming languages</ulink>.
</para>
</sect2>

<sect2 id="ctags-config">
<title>Configuration</title>

<para>The CTags plugin uses two different database files for the index.</para>

<para>On the CTags settings page in &kate;'s configuration you can add or remove
directories containing the source code and regenerate the common CTags database.</para>

<sect3 id="ctags-config-common">
<title>Common Index</title>

<screenshot id="screenshot-ctags-global-settings">
<screeninfo>CTags Settings</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="ctags-global-setting.png" format="PNG"/></imageobject>
<caption>Configure CTags Global Database</caption>
</mediaobject>
</screenshot>

<para>At the bottom of the settings page you can adapt the <guilabel>CTags command</guilabel>.
</para>

<para>For more information about all available options please read the CTags man page. This man page
is available in &khelpcenter; and you can also enter the &URL; <emphasis>man:/ctags</emphasis>
directly into &konqueror;
</para>

<para>Clicking <guibutton>Update</guibutton> will start indexing.
When indexing is finished, close the dialog.</para>
</sect3>

<sect3 id="ctags-config-session">
<title>Session Index</title>

<para>To configure the session index open the <guilabel>CTags</guilabel> view.</para>

<variablelist>
<varlistentry>
<term><menuchoice>
<guimenu>Index Targets</guimenu>
</menuchoice></term>
<listitem>
<para>On this tab you can add or remove directories containing the source code and manually
regenerate the session specific CTags database.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>Database</guimenu>
</menuchoice></term>
<listitem>
<screenshot id="screenshot-ctags-session-settings">
<screeninfo>Database Settings</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="ctags-session-setting.png" format="PNG"/></imageobject>
<caption>Configure CTags Session Database</caption>
</mediaobject>
</screenshot>
<para>Select another CTags database file, configure the CTags command or revert
to the default command.</para>
</listitem>
</varlistentry>

</variablelist>

</sect3>

</sect2>

<sect2 id="ctags-using">
<title>Using the CTags Plugin</title>

<para>
You place the mouse cursor on the language object like function, symbol &etc;
that you are interested in and then select one of the actions in the
<guimenu>CTags</guimenu> menu to jump to the line and file where the object is
defined or declared.</para>
<para>By default the actions in the <guimenu>CTags</guimenu> menu have no shortcuts assigned.
Use the <ulink url="help:/fundamentals/shortcuts.html">keyboard shortcut editor</ulink>
to configure your own shortcuts.</para>

<para>Alternatively use the search field on the <guilabel>Lookup</guilabel> tab of the
CTags view.</para>
<para>Entering characters into the search field will start the search and display matching names
of language objects like functions, classes, symbols &etc; together with type and filename.</para>
<para>Select an item in the list to jump to the corresponding line in the source file.</para>
<!--FIXME why Tag Type here but Name Kind in Project plugin, is there really any difference?-->

<!--FIXME completion as in Project plugin? -->

</sect2>

<sect2 id="ctags-menu">
<title>Menu Structure</title>

<variablelist>

<varlistentry id="ctags-jumpback">
<term><menuchoice>
<guimenu>CTags</guimenu>
<guisubmenu>Jump back one step</guisubmenu>
</menuchoice></term>
<listitem>
<para>Navigate back in the history to the last visited tag.</para>
</listitem>
</varlistentry>

<varlistentry id="ctags-lookup">
<term><menuchoice>
<guimenu>CTags</guimenu>
<guisubmenu>Lookup Current Text</guisubmenu>
</menuchoice></term>
<listitem>
<para>Opens the <guilabel>Lookup</guilabel> tab of the CTags view and displays all
language objects matching the current text selection in the list.</para>
</listitem>
</varlistentry>

<varlistentry id="ctags-gotodeclaration">
<term><menuchoice>
<guimenu>CTags</guimenu>
<guisubmenu>Go to Declaration</guisubmenu>
</menuchoice></term>
<listitem>
<para>If the cursor is in a definition object this will open the document
containing the corresponding declaration if needed, activate its view and
place the cursor at the start of the declaration.</para>
</listitem>
</varlistentry>

<varlistentry id="ctags-gotodefinition">
<term><menuchoice>
<guimenu>CTags</guimenu>
<guisubmenu>Go to Definition</guisubmenu>
</menuchoice></term>
<listitem>
<para>If the cursor is in a declaration object this will open the document
containing the corresponding definition if needed, activate its view and
place the cursor at the start of the definition.</para>
</listitem>
</varlistentry>

</variablelist>

<!--context menu with Lookup Current Text, Goto Declaration, Goto Definition -->

</sect2>

</sect1>
<!--https://frinring.wordpress.com/2017/11/07/ktexteditorpreviewplugin-0-2-1-last-stand-alone/-->
<!-- https://frinring.wordpress.com/2017/08/21/look-what-you-have-donewwdo/-->
<sect1 id="kate-application-plugin-preview">
<title>Document Preview Plugin</title>

<sect2 id="preview-introduction">
<title>Introduction</title>
<para>
The plugin enables a live preview of the currently edited text document in the
final format in the sidebar. So when editing &eg; a &Markdown; text or an &SVG; image,
the result is instantly visible next to the source text.
</para>

<para>For the display the plugin uses that &kparts; plugin which is currently selected
as the preferred one for the &MIME; type of the document.
If there is no &kparts; plugin for that type, no preview is possible.
</para>

<para>To change the preferred plugin open the <guilabel>File Associations</guilabel>
module in the &systemsettings; and edit the <guilabel>Services Preference Order</guilabel>
on the <guilabel>Embedding</guilabel> tab.
</para>

<table>
<title>Some available &kparts; plugins</title>
<tgroup cols="2">
<tbody>
<row>
<entry>&MIME; type</entry><entry>&kparts; plugin</entry>
</row>
<row>
<entry>&Markdown; text</entry><entry>KMarkdownWebViewPart or OkularPart</entry>
</row>
<row>
<entry>&SVG; image</entry><entry>SVGPart</entry>
</row>
<row>
<entry>&Qt; UI files</entry><entry>KUIViewerPart</entry>
</row>
<row>
<entry>&DOT; graph files</entry><entry>KGraphviewerPart</entry>
</row>
</tbody>
</tgroup>
</table>
</sect2>

<sect2 id="preview-menu">
<title>Menu Structure</title>
<variablelist>

<varlistentry id="view-toolviews-show-preview">
<term><menuchoice>
<guimenu>View</guimenu><guisubmenu>Tool Views</guisubmenu>
<guimenuitem>Show Preview</guimenuitem>
</menuchoice></term>
<listitem>
<para>Toggle the display of &kate;'s Document preview in a sidebar.</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>

<sect2 id="preview-interface">
<title>Interface</title>
<para>The buttons at the top of the preview window provide these actions:
</para>
<itemizedlist>
<listitem>
<para>Lock the preview to a given document. Selecting this option ensures
that if switching the focus to the view of another document in the same &kate;
window, the preview will not follow to that document, but keep previewing
this document.</para>
</listitem>
<listitem>
<para>Enable or disable updates of the preview of the current document content</para>
</listitem>
<listitem>
<para>Manually update the preview of the current document content</para>
</listitem>
<listitem>
<para>A dropdown menu with actions from the &kparts; plugin</para>
</listitem>
</itemizedlist>
</sect2>

</sect1>

<sect1 id="kate-application-plugin-documentswitcher">

<title>Document Switcher Plugin</title>

<sect2 id="documentswitcher-menu">
<title>Menu Structure</title>

<variablelist>

<varlistentry id="view-documentswitcher">
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;&Tab;</keycombo>
</shortcut>
<guimenu>View</guimenu>
<guisubmenu>Last Used Views</guisubmenu>
</menuchoice></term>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;&Shift;&Tab;</keycombo>
</shortcut>
<guimenu>View</guimenu>
<guisubmenu>Last Used Views (Reverse)</guisubmenu>
</menuchoice></term>
<listitem>

<para><action>Opens</action> a list with the last viewed documents:</para>

<screenshot id="screenshot-documentswitcher">
<screeninfo>Last viewed documents</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="documentswitcher.png" format="PNG"/></imageobject>
</mediaobject>
</screenshot>

<para>Keep the &Ctrl; key pressed and use the &Tab; key to cycle forward through the list.
Additionally press the &Shift; key to reverse the direction.
</para>

<para>Keep the shortcut <keycombo action="simul">&Ctrl;&Tab;</keycombo> pressed and
can use the &Up;, &Down;, &Home; or
&End; keys to navigate in the list. Pressing a char key consecutively
will cycle through all items with the first matching in the list.
If you release the shortcut keys the view will switch to the selected document in the list.
</para>
</listitem>
</varlistentry>

</variablelist>

</sect2>

</sect1>


<sect1 id="kate-application-plugin-fsbrowser">

<title>File System Browser</title>

<para>The File System Browser is a folder viewer, allowing you to open
files from a displayed folder in the current frame.</para>

<sect2 id="fsbrowser-menu">
<title>Menu Structure</title>
<variablelist>

<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>

</variablelist>
</sect2>

<sect2 id="fsbrowser-interface">
<title>Interface</title>

<para>From the top down, the Filesystem Browser consists of the following
elements:</para>

<variablelist>
<varlistentry>
<term>A Toolbar</term>
<listitem>
<para>This contains standard navigations tool buttons:</para>
<variablelist>
<varlistentry>
<term><guiicon><inlinemediaobject><imageobject><imagedata fileref="go-previous-22.png" format="PNG"/></imageobject></inlinemediaobject> Back</guiicon></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><guiicon><inlinemediaobject><imageobject><imagedata fileref="go-next-22.png" format="PNG"/></imageobject></inlinemediaobject> Forward</guiicon></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><guiicon><inlinemediaobject><imageobject><imagedata fileref="bookmarks-22.png" format="PNG"/></imageobject></inlinemediaobject> Bookmarks</guiicon></term>
<listitem><para>Opens a submenu to edit or add bookmarks and to add a new bookmark folder.</para></listitem>
</varlistentry>
<varlistentry>
<term><guiicon><inlinemediaobject><imageobject><imagedata fileref="system-switch-user-22.png" format="PNG"/></imageobject></inlinemediaobject> Current Document Folder</guiicon></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><guiicon><inlinemediaobject><imageobject><imagedata fileref="games-config-options-22.png" format="PNG"/></imageobject></inlinemediaobject> Options</guiicon></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> and
<guilabel>Size</guilabel> of the files.</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>
</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>
</varlistentry>
<varlistentry>
<term><guimenuitem>Show Hidden Files</guimenuitem></term>
<listitem><para>Displays files normally hidden by your &OS;.</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>
</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>

<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>
<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>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>
</sect2>
</sect1>

<sect1 id="kate-application-plugin-documents">
<title>The Documents List</title>
<!-- https://kate-editor.org/2010/09/12/kate-tree-view-plugin-update/-->
<sect2 id="documents-intro">
<title>Introduction</title>

<para><indexterm><primary>Documents list</primary></indexterm>
The documents list displays a list of all documents currently open in
&kate;. Modified files will have a small <guiicon>floppy
disk</guiicon> icon on their left to indicate that state.</para>

<para>On the top the Documents list has a toolbar with the following buttons:</para>

<simplelist>
<member>
<guiicon><inlinemediaobject><imageobject><imagedata fileref="document-new-22.png" format="PNG"/></imageobject></inlinemediaobject></guiicon>
Create new document</member>
<member>
<guiicon><inlinemediaobject><imageobject><imagedata fileref="document-open-22.png" format="PNG"/></imageobject></inlinemediaobject></guiicon>
Open an existing document</member>
<member>
<guiicon><inlinemediaobject><imageobject><imagedata fileref="go-up-22.png" format="PNG"/></imageobject></inlinemediaobject></guiicon>
Previous Document</member>
<member>
<guiicon><inlinemediaobject><imageobject><imagedata fileref="go-down-22.png" format="PNG"/></imageobject></inlinemediaobject></guiicon>
Next Document</member>
<member>
<guiicon><inlinemediaobject><imageobject><imagedata fileref="document-save-22.png" format="PNG"/></imageobject></inlinemediaobject></guiicon>
Save the current document</member>
<member>
<guiicon><inlinemediaobject><imageobject><imagedata fileref="document-save-as-22.png" format="PNG"/></imageobject></inlinemediaobject></guiicon>
Save the current document under a new name</member>
</simplelist>

<para>By default, the Documents list appears in
<guimenuitem>Tree Mode</guimenuitem>, which displays the folder structure
surrounding all currently open documents. Also available is
<guimenuitem>List Mode</guimenuitem>, which displays a simple list of all
open documents. You can switch modes by right-clicking on the list and selecting
from the <guisubmenu>View Mode</guisubmenu> menu.</para>

<para>If two or more files with the same name (located in different
folders) are open in <guimenuitem>List Mode</guimenuitem>, the names of the second will be prepended
<quote>(2)</quote> and so on. The tool-tip for the file will
display its full name including the path, allowing you to choose the
desired one.</para> <para>To display a document in the currently
active frame, click the document name in the list.</para>

<para>The context menu has some common actions from the <guimenu>File</guimenu> menu.</para>

<para>Additionally there are filemanager actions to rename or delete the file. With
<guimenuitem>Copy File Path</guimenuitem> you can copy the full path of the document
to the clipboard.</para>

<para>You can sort the list in a few different ways by right clicking the
list and selecting from the <guisubmenu>Sort By</guisubmenu> menu.

The options are:
<variablelist>

<varlistentry>
<term><guimenuitem>Document Name</guimenuitem></term>
<listitem><para>Lists the documents alphabetically by their name.</para></listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>Document Path</guimenuitem></term>
<listitem><para>Lists the documents alphabetically by the path to them.</para></listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>Opening Order</guimenuitem></term>
<listitem><para>Lists the documents in the order of opening.</para></listitem>
</varlistentry>

</variablelist>

</para>

<para>The document list will per default visualize your history by shading the
entries for the most recent documents with a background color. If the document
was edited, an extra color is blended in. The most recent document has the
strongest color, so that you can easily find the documents you are working on.
This feature can be disabled in the
<link linkend="config-dialog-documents">Documents</link> page
of the configuration dialog.</para>
<para>The default location of the document list in the &kate; window is to the left of the
editing area.</para>

</sect2>

<sect2 id="documents-menus">
<title>Menu Structure</title>

<variablelist>

<varlistentry id="view-document-previous">
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Alt;&Up;</keycombo>
</shortcut>
<guimenu>View</guimenu>
<guimenuitem>Previous Document</guimenuitem>
</menuchoice></term>
<listitem>
<para>Opens the document displayed above the currently open document in the Documents list.</para>
</listitem>
</varlistentry>

<varlistentry id="view-document-next">
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Alt;&Down;</keycombo>
</shortcut>
<guimenu>View</guimenu>
<guimenuitem>Next Document</guimenuitem>
</menuchoice></term>
<listitem>
<para>Opens the document displayed below the currently open document in the Documents list.</para>
</listitem>
</varlistentry>

<varlistentry id="view-active">
<term><menuchoice>
<guimenu>View</guimenu>
<guimenuitem>Show Active</guimenuitem>
</menuchoice></term>
<listitem>
<para>Displays the currently open document in the Documents list.</para>
</listitem>
</varlistentry>

</variablelist>

</sect2>

<sect2 id="config-dialog-documents">
<title>Configuration</title>

<variablelist>
<varlistentry>
<term><guilabel>Background Shading</guilabel></term>
<listitem><para>This section allows you to enable or disable the background
shading visualization of your recent activity, and choose which colors to use if
enabled.</para></listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Sort By</guilabel></term>
<listitem><para>Set how you want the document list sorted. This can be set
from the &RMB; menu in the document list as well.</para></listitem>
</varlistentry>

<varlistentry>
<term><guilabel>View Mode</guilabel></term>
<listitem><para>This provides two options that effect the display of the
Documents tool view.  The <guilabel>Tree View</guilabel> option will display
the documents in a tree underneath the folders they are in, while the
<guilabel>List View</guilabel> option will display a flat list of documents.
</para></listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Show Full Path</guilabel></term>
<listitem><para>When Tree View and this option are enabled, the folder entries
displayed in the Documents tool view will display the full filesystem path to
the folder in addition to the name of the folder.  It has no effect in List
View.</para></listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Show Toolbar</guilabel></term>
<listitem><para>When Tree View and this option are enabled, a toolbar with
actions like <guibutton>Save</guibutton> is displayed above the
list of documents. Uncheck this option if the toolbar should be
hidden.</para></listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Show Close Button</guilabel></term>
<listitem><para>When this option is enabled, &kate; will show a close button
for opened documents on hover.</para></listitem>
</varlistentry>

</variablelist>

</sect2>

</sect1>

<sect1 id="kate-application-plugin-gdb">
<!--https://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>

<sect2 id="gdb-intro">
<title>Introduction</title>

<para>&kate;'s &gdb; plugin provides a simple frontend to the popular &GNU;
Project Debugger.</para>

<important>
<para>Previous experience with &gdb; is strongly recommended.  For more
information on using &gdb;, visit <ulink url="https://www.gnu.org/software/gdb/">the
&gdb; website</ulink>.</para>
</important>

<para>You can enable the &gdb; plugin in
<link linkend="config-dialog-plugins">the Plugins section of &kate;'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 &kate;,
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>

</sect2>

<sect2 id="gdb-menus">
<title>Menu and Toolbar Structure</title>

<para>All of these options are available in &kate;'s menus, and many are
available on the Debug toolbar as well.</para>

<variablelist>

<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>

<varlistentry id="gdb-menus-show-locals-and-stack">
<term><menuchoice>
<guimenu>View</guimenu><guisubmenu>Tool View</guisubmenu><guimenuitem>Show Locals and Stack</guimenuitem>
</menuchoice></term>
<listitem><para>Shows a list of all currently loaded variables and their values and a &gdb; backtrace.
</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>

<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>

<varlistentry id="gdb-menus-kill">
<term><menuchoice>
<guimenu>Debug</guimenu><guimenuitem>Kill / Stop Debugging</guimenuitem>
</menuchoice></term>
<listitem><para>Stops &gdb;.</para></listitem>
</varlistentry>

<varlistentry id="gdb-menus-restart">
<term><menuchoice>
<guimenu>Debug</guimenu><guimenuitem>Restart Debugging</guimenuitem>
</menuchoice></term>
<listitem><para>Restarts &gdb;.</para></listitem>
</varlistentry>

<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>

<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="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>

<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="gdb-debug-view">
<title>Debug View</title>

<para>The <guilabel>Debug View</guilabel> tool view consists of several tabs:
</para>

<variablelist>

<varlistentry>
<term><guilabel>&gdb; Output</guilabel></term>
<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><guilabel>Settings</guilabel></term>
<listitem>
<variablelist>

<varlistentry>
<term><guilabel>Executable</guilabel></term>
<listitem><para>Path to the target (executable) for debugging.</para></listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Working Directory</guilabel></term>
<listitem><para>The current working directory provided to the target.
</para></listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Arguments</guilabel></term>
<listitem><para>Arguments passed to the program.</para></listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Keep focus</guilabel></term>
<listitem><para>Keeps focus on the &gdb; command line.</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>
</varlistentry>

</variablelist>

<screenshot id="screenshot-gdb-settings">
<screeninfo>The Settings dialog</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="gdb-settings.png" format="PNG"/></imageobject>
<textobject><phrase>The Settings dialog</phrase></textobject>
<caption><para>The <guilabel>Settings</guilabel> dialog displaying the configuration
of a debugging session.</para></caption>
</mediaobject>
</screenshot>

</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>
</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">
<title>Thanks and Acknowledgments</title>

<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-projects">
<!--https://kate-editor.org/2012/11/02/using-the-projects-plugin-in-kate -->

<title>Project Plugin</title>

<sect2 id="project-intro">
<title>Introduction</title>

<para>The basic idea of the Project plugin is to have a structured list of
files belonging to the project with the following properties:</para>

<orderedlist>
<listitem><para>Provide a structured view of the files</para></listitem>
<listitem><para>Make it easy and very fast to open and switch projects</para></listitem>
<listitem><para>Support search and replace for a project</para></listitem>
<listitem><para>Provide simple auto completion</para></listitem>
<listitem><para>Make it simple to quickly open files in the project</para></listitem>
<listitem><para>Support for building the project</para></listitem>
</orderedlist>
</sect2>

<sect2 id="project-view">
<title>Structured View of the Files</title>

<para>Once the Project plugin is loaded in the &kate; configuration page, open a file
in a project and a sidebar
appears that lists all projects as well as the project files as follows:</para>

<screenshot id="screenshot-project-view">
<screeninfo>Project View</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="project-view.png" format="PNG"/></imageobject>
</mediaobject>
</screenshot>

<para>As you can see, the currently active project is <quote>Kate</quote>, and its contents is
listed in the tree view. Clicking on files in the tree view opens the file in the
editor. Further, a context menu is provided with which you can open files with
other applications, such as a <filename class="extension">.ui</filename> file with Qt Designer.</para>
<para>You can filter the items by typing parts of the file name you are looking for into the search bar
at the bottom of the list.</para>
</sect2>

<sect2 id="project-switch">
<title>Switching Projects</title>

<para>The idea is that you never have to open a project manually, this is even not
supported at all. Hence, what happens if you open a file, the Project plugin quickly
scans the folder and its parent folders for a <filename>.kateproject</filename> file. If found, the project
is automatically loaded.</para>

<para>Furthermore, if you open another document in &kate;, that belongs to another project,
the Project plugin automatically switches the current project. So intuitively, always the
correct project is active. Of course, you can also switch the currently active project
using the combo box.</para>

</sect2>

<sect2 id="project-search-replace">
<title>Search and Replace in Projects</title>

<para>&kate; has a Search and Replace plugin that shows up in the
bottom sidebar. If a project is loaded, open the Search and Replace sidebar,
and switch to the mode to search and replace in the current project:</para>

<screenshot id="screenshot-projects-search">
<screeninfo>Search in Projects</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="project-search.png" format="PNG"/></imageobject>
</mediaobject>
</screenshot>

</sect2>

<sect2 id="project-autocompletition">
<title>Simple Auto Completion</title>

<para>With the knowledge of all files belonging to a project, the Project plugin provides
simple auto completion facilities based on CTags. If a project is initially opened, CTags
parses all project files in a background thread and saves the CTags information to
<filename class="directory">/tmp</filename>. This file then is used to populate the auto
completion popup in &kate;.</para>

<para>In contrast, without this auto completion, &kate; is only capable of showing auto
completion items based on the words in the current file. So the auto completion provided
by the Project plugin is much more powerful.</para>

<screenshot id="screenshot-completion-search">
<screeninfo>Completion in Projects</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="project-completition.png" format="PNG"/></imageobject>
</mediaobject>
</screenshot>

<para>If CTags is missing, a passive popup warns you about this issue. It is also noteworthy,
that the CTags file in <filename class="directory">/tmp</filename> is cleaned up when &kate;
exits, so the plugin does not pollute any folder with unwanted files.</para>

</sect2>

<sect2 id="project-quickopen">
<title>Quick Opening Files</title>

<para>As clicking on files in the tree view is not the fastest way to open a file, &kate;
provides a built-in quick open mechanism you can activate with
<keycombo action="simul">&Ctrl;&Alt;<keycap>O</keycap></keycombo>.
What you the get is a list like this:</para>

<screenshot id="screenshot-project-quickopen">
<screeninfo>Quick Open</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="project-quickopen.png" format="PNG"/></imageobject>
</mediaobject>
</screenshot>

<para>You can filter by typing parts of the file name you are looking for, and you can
also navigate with the arrow keys and page up/down through the list.
Hitting &Enter; activates the selected file, while &Esc; hides the quick open view again.</para>

<para>Further, the quick open remembers the previous file. So when you change to the
quick open view the previously activated file is automatically selected and you just
need to hit &Enter;, which comes very handy at times.</para>

</sect2>

<sect2 id="project-build">
<title>Support for Building the Project</title>

<para>Another feature is to have support for the <link linkend="projects-build-support">Build Plugin</link>,
so that it automatically is configured correctly.</para>

</sect2>

<sect2 id="project-create">
<title>Creating Projects</title>

<sect3 id="project-autoload">
<!--https://kate-editor.org/2014/10/12/autoloading-projects-plugin-kate-5/-->
<title>Loading Projects Automatically</title>

<para>The Project plugin has an auto-loading feature. You can read the file list from
the version control system. To this end, auto-loading for the respective version control
system needs to be enabled in the settings (enabled by default):
</para>

<screenshot id="screenshot-project-configure">
<screeninfo>Project Plugin Configuration</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="project-configure.png" format="PNG"/></imageobject>
</mediaobject>
</screenshot>

</sect3>

<sect3 id="project-manual">
<title>Creating Projects Manually</title>
<para>
You just have to create a <filename>.kateproject</filename> file in the root folder of the project.
For instance, the <quote>Kate</quote> <filename>.kateproject</filename> file looks like this:
</para>

<screen>
{
  "name": "Kate"
, "files": [ { "git": 1 } ]
}
</screen>

<para>The file content is written in &JSON; syntax. The project name is <quote>Kate</quote>, and
the files contained in should be read from &git;.
</para>

<para>
Also supported instead of <literal>git</literal> is subversion through <literal>svn</literal> and
mercurial through <literal>hg</literal>.
If you do not want to read from a version control system, you can tell it to recursively
load files from directories as follows:
</para>

<screen>
{
  "name": "Kate"
, "files": [ { "directory": "kate", "filters": ["*.cpp", "*.h", "*.ui", "CMakeLists.txt", "Find*.cmake"], "recursive": 1 } ]
}
</screen>

<para>
Here, subfolders and filters define what’s part of the project.
You can also mix version control and files based on filters.
</para>

<para id="projects-build-support">If you want to add support for the Build plugin, you could write a
<filename>.kateproject</filename> like this:</para>

<screen>
{
  "name": "Kate"
, "files": [ { "git": 1 } ]
, "build": {
    "directory": "build"
  , "build": "make all"
  , "clean": "make clean"
  , "install": "make install"
  }
}
</screen>

<para>
In case you have a <filename>.kateproject</filename> file tracked by a control
version system, but you need to tweak the configuration for a particular
workspace, you can save those changes to a separated file named
<filename>.kateproject.local</filename>. The content of this file will take
precedence over <filename>.kateproject</filename>.
</para>

</sect3>

</sect2>

<sect2 id="project-current">
<title>Current Project</title>

<para>Using <menuchoice><shortcut><keycombo action="simul">&Alt;<keycap>1</keycap></keycombo></shortcut>
<guimenu>Projects</guimenu><guimenuitem>Go To</guimenuitem></menuchoice> you can open the
<guilabel>Current Project</guilabel> view at the bottom of the editor window with four tabs:</para>

<screenshot id="screenshot-project-current">
<screeninfo>Current Project</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="project-current-analysis.png" format="PNG"/></imageobject>
</mediaobject>
</screenshot>

<variablelist>

<varlistentry>
<term>
<guimenu>Terminal Panel</guimenu>
</term>
<listitem>
<para>A <link linkend="kate-application-plugin-konsole">Terminal emulator</link> starting in the
root folder of the project.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<guimenu>Code Index</guimenu>
</term>
<listitem>
<para>Entering characters into the search bar will start the search and display matching names
of functions, classes, symbols &etc; together with kind, filename and line number.</para>
<para>Select an item in the list to jump to the corresponding line in the source file.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>
<guimenu>Code Analysis</guimenu>
</term>
<listitem>
<para>Click <guilabel>Start Analysis</guilabel> to run a static code analysis for the C and C++
using <command>cppcheck</command> and to generate a report showing filename, line number, severity
(style, warning &etc;) and the issue found.</para>
<para>Select an item in the list to jump to the corresponding line in the source file.</para>
</listitem>
</varlistentry>
<!--FIXME options for cppcheck? configurable?-->
<varlistentry>
<term>
<guimenu>Notes</guimenu>
</term>
<listitem>
<para>Text entered in this tab will be saved in the file
<filename>.kateproject.notes</filename>.</para>
</listitem>
</varlistentry>

</variablelist>

</sect2>

<sect2 id="projects-menu">
<title>The Projects Menu</title>

<para>The <guimenu>Projects</guimenu> menu allows you to switch between
currently open projects.  It is displayed by the Project plugin.</para>

<variablelist>

<varlistentry id="projects-back">
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;&Alt;&Left;</keycombo>
</shortcut>
<guimenu>Projects</guimenu>
<guimenuitem>Back</guimenuitem>
</menuchoice></term>
<listitem>
<para>Switch to the previous project.</para>
</listitem>
</varlistentry>

<varlistentry id="projects-forward">
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;&Alt;&Right;</keycombo>
</shortcut>
<guimenu>Projects</guimenu>
<guimenuitem>Forward</guimenuitem>
</menuchoice></term>
<listitem>
<para>Switch to the next project.</para>
</listitem>
</varlistentry>

<varlistentry id="projects-goto">
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Alt;<keycap>1</keycap></keycombo>
</shortcut>
<guimenu>Projects</guimenu><guimenuitem>Go To</guimenuitem>
</menuchoice></term>
<listitem>
<para>Open the <guilabel>Current Project</guilabel> view at the bottom of the editor window.</para>
</listitem>
</varlistentry>

</variablelist>

</sect2>
<!--
context menu Project->Lookup:xxx
-->

</sect1>

<!--FIXME Replicode
Projects Replicode run / stop-->

<sect1 id="kate-application-plugin-lspclient">
<title>LSP Client Plugin</title>

<para>The LSP Client plugin provides many language features such as code completion, code navigation or finding references
based on the <ulink url="https://microsoft.github.io/language-server-protocol/">Language Server Protocol</ulink>.</para>

<para>Once you have enabled the LSP Client in the plugin page, a new
page called LSP Client will appear in your &kate; configuration dialog.
</para>

<sect2 id="lspclient-menu">
<title>Menu Structure</title>

<para>
If appropriate, a corresponding LSP command is also mentioned in the
explanation below, the documentation of which may then provide additional
background and interpretation, though it may vary depending on the actual
language. The phrase 'current symbol' refers to the symbol corresponding to the
current cursor position, as so determined by the language and server
implementation.
</para>

<variablelist>

<varlistentry id="lspclient-definition">
<term><menuchoice>
<guimenu>LSP Client</guimenu>
<guisubmenu>Go to Definition</guisubmenu>
</menuchoice></term>
<listitem>
<para>[textDocument/definition] Go to current symbol definition.</para>
</listitem>
</varlistentry>

<varlistentry id="lspclient-declaration">
<term><menuchoice>
<guimenu>LSP Client</guimenu>
<guisubmenu>Go to Declaration</guisubmenu>
</menuchoice></term>
<listitem>
<para>[textDocument/declaration] Go to current symbol declaration.</para>
</listitem>
</varlistentry>

<varlistentry id="lspclient-typedefinition">
<term><menuchoice>
<guimenu>LSP Client</guimenu>
<guisubmenu>Go to Type Definition</guisubmenu>
</menuchoice></term>
<listitem>
<para>[textDocument/typeDefinition] Go to current symbol type definition.</para>
</listitem>
</varlistentry>

<varlistentry id="lspclient-references">
<term><menuchoice>
<guimenu>LSP Client</guimenu>
<guisubmenu>Find References</guisubmenu>
</menuchoice></term>
<listitem>
<para>[textDocument/references] Find references to current symbol.</para>
</listitem>
</varlistentry>

<varlistentry id="lspclient-implementation">
<term><menuchoice>
<guimenu>LSP Client</guimenu>
<guisubmenu>Find Implementations</guisubmenu>
</menuchoice></term>
<listitem>
<para>[textDocument/implementation] Find implementations of current symbol.</para>
</listitem>
</varlistentry>

<varlistentry id="lspclient-highlight">
<term><menuchoice>
<guimenu>LSP Client</guimenu>
<guisubmenu>Highlight</guisubmenu>
</menuchoice></term>
<listitem>
<para>[textDocument/documentHighlight] Highlight current symbol references in current document.</para>
</listitem>
</varlistentry>

<varlistentry id="lspclient-hover">
<term><menuchoice>
<guimenu>LSP Client</guimenu>
<guisubmenu>Hover</guisubmenu>
</menuchoice></term>
<listitem>
<para>[textDocument/hover] Hover info for current symbol.</para>
</listitem>
</varlistentry>

<varlistentry id="lspclient-format">
<term><menuchoice>
<guimenu>LSP Client</guimenu>
<guisubmenu>Format</guisubmenu>
</menuchoice></term>
<listitem>
<para>[textDocument/formatting] [textDocument/rangeFormatting]
Format the current document or current selection.</para>
</listitem>
</varlistentry>

<varlistentry id="lspclient-rename">
<term><menuchoice>
<guimenu>LSP Client</guimenu>
<guisubmenu>Rename</guisubmenu>
</menuchoice></term>
<listitem>
<para>[textDocument/rename] Rename current symbol.</para>
</listitem>
</varlistentry>

<varlistentry id="lspclient-quick-fix">
<term><menuchoice>
<guimenu>LSP Client</guimenu>
<guisubmenu>Quick Fix</guisubmenu>
</menuchoice></term>
<listitem>
<para>[textDocument/codeAction, workspace/executeCommand]
Computes and applies a quick fix for a diagnostic on current position (or line).</para>
</listitem>
</varlistentry>

<varlistentry id="lspclient-completion-documentation">
<term><menuchoice>
<guimenu>LSP Client</guimenu>
<guisubmenu>Show selected completion documentation</guisubmenu>
</menuchoice></term>
<listitem>
<para>Show documentation for a selected item in the completion list.</para>
</listitem>
</varlistentry>

<varlistentry id="lspclient-signature-help">
<term><menuchoice>
<guimenu>LSP Client</guimenu>
<guisubmenu>Enable signature help with auto completion</guisubmenu>
</menuchoice></term>
<listitem>
<para>Also show signature help in the completion list.</para>
</listitem>
</varlistentry>

<varlistentry id="lspclient-declaration-references">
<term><menuchoice>
<guimenu>LSP Client</guimenu>
<guisubmenu>Include declaration in references</guisubmenu>
</menuchoice></term>
<listitem>
<para>Request to include a symbol's declaration when requesting references.</para>
</listitem>
</varlistentry>

<varlistentry id="lspclient-completion-parens">
<term><menuchoice>
<guimenu>LSP Client</guimenu>
<guisubmenu>Add parentheses upon function completion</guisubmenu>
</menuchoice></term>
<listitem>
<para>Automatically add a pair of parentheses after completion of a function.</para>
</listitem>
</varlistentry>

<varlistentry id="lspclient-show-hover">
<term><menuchoice>
<guimenu>LSP Client</guimenu>
<guisubmenu>Show hover information</guisubmenu>
</menuchoice></term>
<listitem>
<para>Show hover information upon (mouse cursor) hover.
Regardless of this setting, the request can always be manually initiated.
</para>
</listitem>
</varlistentry>

<varlistentry id="lspclient-format-typing">
<term><menuchoice>
<guimenu>LSP Client</guimenu>
<guisubmenu>Format on typing</guisubmenu>
</menuchoice></term>
<listitem>
<para>[document/onTypeFormatting] Format parts of document when typing certain trigger characters.
For example, this might apply indentation upon newline, or as otherwise determined by LSP Server.
Note that editor indentation scripts might be trying to do the same (depending on the mode)
and so it may not be advisable to have both enabled at the same time.
</para>
</listitem>
</varlistentry>

<varlistentry id="lspclient-incremental-sync">
<term><menuchoice>
<guimenu>LSP Client</guimenu>
<guisubmenu>Incremental document synchronization</guisubmenu>
</menuchoice></term>
<listitem>
<para>Send partial document edits to update the server rather than whole document text (if supported).</para>
</listitem>
</varlistentry>

<varlistentry id="lspclient-highlight-goto">
<term><menuchoice>
<guimenu>LSP Client</guimenu>
<guisubmenu>Highlight goto location</guisubmenu>
</menuchoice></term>
<listitem>
<para>Provide a transient visual cue after performing a goto to a location (of definition, declaration, etc).</para>
</listitem>
</varlistentry>

<varlistentry id="lspclient-diagnostics">
<term><menuchoice>
<guimenu>LSP Client</guimenu>
<guisubmenu>Show diagnostics notifications</guisubmenu>
</menuchoice></term>
<listitem>
<para>[textDocument/publishDiagnostics] Process and show diagnostics notifications sent by server.</para>
</listitem>
</varlistentry>

<varlistentry id="lspclient-diagnostics-highlight">
<term><menuchoice>
<guimenu>LSP Client</guimenu>
<guisubmenu>Show diagnostics highlights</guisubmenu>
</menuchoice></term>
<listitem>
<para>Add text highlights for ranges indicated in diagnostics.</para>
</listitem>
</varlistentry>

<varlistentry id="lspclient-diagnostics-marks">
<term><menuchoice>
<guimenu>LSP Client</guimenu>
<guisubmenu>Show diagnostics marks</guisubmenu>
</menuchoice></term>
<listitem>
<para>Add document marks for lines indicated in diagnostics.</para>
</listitem>
</varlistentry>

<varlistentry id="lspclient-diagnostics-tab">
<term><menuchoice>
<guimenu>LSP Client</guimenu>
<guisubmenu>Switch to diagnostic tab</guisubmenu>
</menuchoice></term>
<listitem>
<para>Switch to the diagnostic tab in the plugin toolview.</para>
</listitem>
</varlistentry>

<varlistentry id="lspclient-close-non-diagnostics">
<term><menuchoice>
<guimenu>LSP Client</guimenu>
<guisubmenu>Close all non-diagnostics tabs</guisubmenu>
</menuchoice></term>
<listitem>
<para>Close all non-diagnostics (&eg; references) tabs in plugin toolview.</para>
</listitem>
</varlistentry>

<varlistentry id="lspclient-restart">
<term><menuchoice>
<guimenu>LSP Client</guimenu>
<guisubmenu>Restart LSP Server</guisubmenu>
</menuchoice></term>
<listitem>
<para>Restart current document's LSP Server.</para>
</listitem>
</varlistentry>

<varlistentry id="lspclient-restart-all">
<term><menuchoice>
<guimenu>LSP Client</guimenu>
<guisubmenu>Restart all LSP Servers</guisubmenu>
</menuchoice></term>
<listitem>
<para>Stop all LSP Servers which will then be (re)started as needed.</para>
</listitem>
</varlistentry>

</variablelist>

</sect2>


<sect2 id="lspclient-configuration">
<title>Configuration</title>

<para>
The plugin's configuration page mostly allows for persistent configuration of
some of the above menu items.  However, there is one additional entry
to specify the Server Configuration file.  This is a &JSON; file that
can be used to specify the LSP server to start (and then to communicate
with over stdin/stdout).  For convenience, some default configuration
is included, which can be inspected in the plugin's configuration page.
To aid in the explanation below, an excerpt of that configuration is given here:
</para>

<screen>
{
    "servers": {
        "bibtex": {
            "use": "latex",
            "highlightingModeRegex": "^BibTeX$"
        },
        "c": {
            "command": ["clangd", "-log=error", "--background-index"],
            "commandDebug": ["clangd", "-log=verbose", "--background-index"],
            "url": "https://clang.llvm.org/extra/clangd/",
            "highlightingModeRegex": "^(C|ANSI C89|Objective-C)$"
        },
        "cpp": {
            "use": "c",
            "highlightingModeRegex": "^(C\\+\\+|ISO C\\+\\+|Objective-C\\+\\+)$"
        },
        "d": {
            "command": ["dls", "--stdio"],
            "url": "https://github.com/d-language-server/dls",
            "highlightingModeRegex": "^D$"
        },
        "fortran": {
            "command": ["fortls"],
            "rootIndicationFileNames": [".fortls"],
            "url": "https://github.com/hansec/fortran-language-server",
            "highlightingModeRegex": "^Fortran.*$"
        },
        "javascript": {
            "command": ["typescript-language-server", "--stdio"],
            "rootIndicationFileNames": ["package.json", "package-lock.json"],
            "url": "https://github.com/theia-ide/typescript-language-server",
            "highlightingModeRegex": "^JavaScript.*$",
            "documentLanguageId": false
        },
        "latex": {
            "command": ["texlab"],
            "url": "https://texlab.netlify.com/",
            "highlightingModeRegex": "^LaTeX$"
        },
        "go": {
            "command": ["go-langserver"],
            "commandDebug": ["go-langserver", "-trace"],
            "url": "https://github.com/sourcegraph/go-langserver",
            "highlightingModeRegex": "^Go$"
        },
        "python": {
            "command": ["python3", "-m", "pyls", "--check-parent-process"],
            "url": "https://github.com/palantir/python-language-server",
            "highlightingModeRegex": "^Python$"
        },
        "rust": {
            "command": ["rls"],
            "path": ["%{ENV:HOME}/.cargo/bin", "%{ENV:USERPROFILE}/.cargo/bin"],
            "rootIndicationFileNames": ["Cargo.lock", "Cargo.toml"],
            "url": "https://github.com/rust-lang/rls",
            "highlightingModeRegex": "^Rust$"
        },
        "ocaml": {
            "command": ["ocamlmerlin-lsp"],
            "url": "https://github.com/ocaml/merlin",
            "highlightingModeRegex": "^Objective Caml.*$"
        }
    }
}
</screen>

<para>
Note that each "command" may be an array or a string (in which case it is
split into an array). Also, a top-level "global" entry (next to "server") is
considered as well (see further below).
The specified binary is searched for in the usual way, e.g. using <literal>PATH</literal>.
If it is installed in some custom location, then the latter may have to be
extended.  Or alternatively, a (sym)link or wrapper script may be used in a location
that is within the usual <literal>PATH</literal>.  As illustrated above,
one may also specify a "path" that will be searched for after the standard locations.
</para>

<para>
All of the entries in "command", "root" and "path" are subject to variable expansion.
</para>

<para>
The "highlightingModeRegex" is used to map the highlighting mode as used by &kate;
to the language id of the server. If no regular expression is given, the language id
itself is used.  If a "documentLanguageId" entry is set to false, then no
language id is provided to the server when opening the document.  This may
have better results for some servers that are more precise in determining
the document type than doing so based on a kate mode.
</para>

<para>
From the above example, the gist is presumably clear.  In addition, each server
entry object may also have an "initializationOptions" entry, which is passed
along to the server as part of the 'initialize' method.
If present, a "settings" entry is passed to the server by means of the
'workspace/didChangeConfiguration' notification.
</para>

<para>
Various stages of override/merge are applied;
<itemizedlist>
<listitem>
<para>user configuration (loaded from file) overrides (internal) default configuration</para>
</listitem>
<listitem>
<para>"lspclient" entry in <filename>.kateproject</filename> project configuration overrides the above</para>
</listitem>
<listitem>
<para>the resulting "global" entry is used to supplement (not override) any server entry</para>
</listitem>
</itemizedlist>
</para>

<para> One server instance is used per (root, servertype) combination. If "root"
is specified as an absolute path, then it used as-is, otherwise it is relative
to the <quote>projectBase</quote> (as determined by the <link
linkend="kate-application-plugin-projects">Project plugin</link>) if applicable,
or otherwise relative to the document's directory. If not specified and
"rootIndicationFileNames" is an array as filenames, then a parent directory of
current document containing such a file is selected. As a last fallback, the
home directory is selected as "root". For any document, the resulting "root"
then determines whether or not a separate instance is needed. If so, the "root"
is passed as rootUri/rootPath. </para>

<para>
In general, it is recommended to leave root unspecified, as it is not that
important for a server (your mileage may vary though).  Fewer server instances
are obviously more efficient, and they also have a 'wider' view than
the view of many separate instances.
</para>

<sect3 id="lspclient-customization">
<title>LSP Server Configuration</title>

<para>

Each particular LSP server has its own way of customization and may use
language/tool specific means for configuration, &eg;
<filename>tox.ini</filename> (a.o. for python),
<filename>.clang-format</filename> for C++ style format. Such configuration may
then also be used by other (non-LSP) tools (such as then
<application>tox</application> or <application>clang-format</application>). On
top of that, some LSP servers also load configuration from custom files (&eg;
<filename>.ccls</filename>). Furthermore, custom server configuration can also
be passed through LSP (protocol), see the aforementioned
"initializationOptions" and "settings" entries in server configuration.

</para>

<para>
Since various level of override/merge are applied, the following example
of user specified client configuration tweaks some python-language-server
configuration.
</para>

<screen>
{
    "servers": {
        "python": {
            "settings": {
                "pyls": {
                    "plugins": {
                        "pylint": {
                            "enable": true
                        }
                    }
                }
            }
        }
    }
}
</screen>

<para>
Unfortunately, LSP server configuration/customization is often not so well
documented, in ways that only examining the source code shows configuration
approaches and the set of available configuration options.  In particular,
the above example's server supports many more options in "settings".
See <ulink url="https://github.com/neoclide/coc.nvim/wiki/Language-servers">
another LSP client's documentation</ulink> for various other language server
examples and corresponding settings, which can easily and readily be
transformed to the &JSON; configuration that is used here and outlined above.
</para>

</sect3>

<sect3 id="lspclient-diagnostics-suppression">
<title>LSP Server Diagnostic Suppression</title>

<para>
It may happen that diagnostics are reported which are not quite useful.
This can be quite cumbersome, especially if there are many (often of the same
kind). In some cases, this may be tweaked by language (server) specific means.
For example, the <ulink url="https://clangd.llvm.org/config.html">clangd
configuration  mechanism</ulink> allows tweaking of some diagnostics aspects. In
general, however, it may not always be evident how to do so, or it may not even
be possible at all in desired ways due to server limitations or bug.
</para>

<para>
As such, the plugin supports diagnostics suppression similar to e.g. valgrind
suppressions. The most fine-grained configuration can be supplied in a
"suppressions" key in the (merged) &JSON; configuration.
</para>

<screen>
{
    "servers": {
        "c": {
            "suppressions": {
                "rulename": ["filename", "foo"],
                "clang_pointer": ["", "clang-tidy", "clear_pointer"],
            }
        }
    }
}
</screen>

<para>
Each (valid) rule has an arbitrary name and is defined by an array of length
2 or 3 which provides a regex to match against the (full) filename, a regex
to match against the diagnostic (text) and an optional regex matched against
the (source code range of) text to which the diagnostic applies.
</para>

<para>
In addition to the above fine-grained configuration, the context menu in the
diagnostics tab also supports add/remove of suppressions that match a particular
diagnostic (text) exactly, either globally (any file) or locally (the specific
file in question).  These suppression are stored in and loaded from session config.
</para>

</sect3>

<sect3 id="lspclient-troubleshooting">
<title>LSP Server Troubleshooting</title>

<para>
It is one thing to describe how to configure a (custom) LSP server for
any particular language, it is another to end up with the server running
smoothly. Usually, the latter is fortunately the case.  Sometimes, however,
problems may arise due to either some "silly" misconfiguration or a more
fundamental problem with the server itself.  The latter might typically manifest
itself as a couple of attempts at starting the server, as so reported in &kate;
Output tab. The latter, however, is only meant to convey high-level messages or
progress rather than to provide detailed diagnostics, and even less so for what
is in fact another process (the LSP server).
</para>

<para>
The usual way to diagnose this is to add some flag(s) to the startup
command (of the language server) that enables (additional) logging (to
some file or standard error), in as far as it does not do so by default. If
&kate; is then started on the command line, then one might be able to obtain
more (in)sight in what might be going wrong.
</para>

<para>
It may also be informative to examine the protocol exchange between &kate;'s
LSP client and the LSP server.  Again, the latter usually has ways to trace
that.  The LSP client also provides additional debug tracing (to stderr)
when &kate; is invoked with the following
<literal>QT_LOGGING_RULES=katelspclientplugin=true</literal> suitably
<literal>export</literal>'ed.
</para>

</sect3>

</sect2>

<!--TODO: Supported languages, describe features and actions a bit -->

<!--<screenshot id="screenshot-rust-configuration">
<screeninfo>Rust Configuration</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="rust-configuration.png" format="PNG"/></imageobject>
</mediaobject>
</screenshot>

<para>Edit the command to run <ulink url="https://github.com/phildawes/racer">Racer</ulink>,
an utility intended to provide Rust code completion for editors.</para>

<para>You also need the Rust source code and have to provide the path to the source tree.
</para>

<para>While typing code a popup list appears with items for completion:
</para>

<screenshot id="screenshot-rust-completion">
<screeninfo>Rust Completion</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="rust-completion.png" format="PNG"/></imageobject>
</mediaobject>
</screenshot>

<para>In addition to code completion popups, the plugin also installs
a <guimenuitem>Go to Definition</guimenuitem> action in the <guimenu>Edit</guimenu> menu and
in the context menu. You can configure a keyboard shortcut for it as well.
</para>

<para>This action will open the document containing the definition if needed, activate
its view and place the cursor at the start of the definition.
</para>-->

</sect1>

<sect1 id="kate-application-plugin-searchinfiles">
<sect1info>
<authorgroup><author>
&TC.Hollingsworth; &TC.Hollingsworth.mail;
</author></authorgroup>
</sect1info>
<title>Search &amp; Replace</title>

<sect2 id="searchinfiles-intro">
<title>Introduction</title>
<para>&kate;'s Search &amp; 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 in the active file.
You can even filter by filename, for instance searching only files
that end with a particular file extension.</para>

</sect2>

<sect2 id="searchinfiles-ui">
<title>Interface</title>

<sect3 id="searchinfiles-ui-query">
<title>Search Query</title>

<para>The following options are always displayed at the top of the Search in
Files tool view:</para>

<variablelist>

<varlistentry>
<term><guiicon><inlinemediaobject><imageobject><imagedata fileref="tab-new-22.png" format="PNG"/>
</imageobject></inlinemediaobject></guiicon></term>
<listitem><para>
You can have as many searches as you want open at the same time.  Simply click
the new tab 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><guiicon><inlinemediaobject><imageobject><imagedata fileref="games-config-options-22.png" format="PNG"/>
</imageobject></inlinemediaobject></guiicon></term>
<listitem><para>
The button 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><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><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><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><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><guibutton>Next</guibutton></term>
<listitem><para>
Go to the next match of your search query, switching files if necessary.
</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>
</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><inlinemediaobject><imageobject>
<imagedata fileref="games-config-options-22.png" format="PNG"/></imageobject></inlinemediaobject></guiicon>
button to display them.</para>

<variablelist>

<varlistentry>
<term><guilabel>Search in</guilabel></term>
<listitem><para>
This has three options.  Select <guilabel>Open Files</guilabel> to search all
files currently open in &kate;.  Select <guilabel>Folder</guilabel> to
search inside a folder and optionally its subfolders.  Select <guilabel>Current
File</guilabel> to search only in the active file.
</para>
<para>If the <guilabel>Projects</guilabel> plugin is loaded, you can also search in
the <guilabel>Current Project</guilabel> or in <guilabel>All Open Projects</guilabel>.
</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>
</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>
</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>

<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>

<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>Folder</guilabel> mode.
</para></listitem>
</varlistentry>

<varlistentry>
<term><guiicon><inlinemediaobject><imageobject><imagedata fileref="go-up-22.png" format="PNG"/>
</imageobject></inlinemediaobject></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>Folder</guilabel> mode.
</para></listitem>
</varlistentry>

<varlistentry>
<term><guiicon><inlinemediaobject><imageobject><imagedata fileref="view-refresh-22.png" format="PNG"/>
</imageobject></inlinemediaobject></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>Folder</guilabel> mode.
</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>Open files</guilabel> mode.
</para></listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Exclude</guilabel></term>
<listitem><para>
The opposite of <guilabel>Filter</guilabel>, this prevents &kate; 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>Open files</guilabel> mode.
</para></listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Recursive</guilabel></term>
<listitem><para>
If this option is enabled, &kate; will also search in all subfolders of the
selected folder. This option is only available when using
<guilabel>Folder</guilabel> mode.
</para></listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Include hidden</guilabel></term>
<listitem><para>
If this option is enabled, &kate; will also search in files or folders that
are typically hidden by your &OS;. This option is only available when using
<guilabel>Folder</guilabel> mode.
</para></listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Follow symbolic links</guilabel></term>
<listitem><para>
The Search in Files plugin typically does not follow
<ulink url="https://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>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, &kate; will repeatedly follow the link
and search the folder, and the search will never complete.</para></warning>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Include binary files</guilabel></term>
<listitem><para>
If enabled, &kate; will also search in files that do not appear to be text
files.
</para></listitem>
</varlistentry>

</variablelist>
</sect3>

<sect3 id="searchinfiles-ui-results">
<title>Search Results</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><inlinemediaobject><imageobject><imagedata fileref="games-config-options-22.png" format="PNG"/>
</imageobject></inlinemediaobject></guiicon>
button to display them.  They will also
automatically be displayed as soon as a search is performed.</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>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>

<para>To open the file your result was found in, simply double-click it.  &kate;
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="searchinfiles-menu">
<title>Menu Structure</title>

<variablelist>

<varlistentry id="edit-searchinfiles">
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;&Alt;<keycap>F</keycap></keycombo>
</shortcut>
<guimenu>Edit</guimenu>
<guimenuitem>Search in Files</guimenuitem>
</menuchoice></term>
<listitem>
<para>Launches the Search and Replace tool view.</para>
</listitem>
</varlistentry>

<varlistentry id="edit-next-match">
<term><menuchoice>
<guimenu>Edit</guimenu>
<guimenuitem>Go to Next Match</guimenuitem>
</menuchoice></term>
<listitem>
<para>Go to the next match in a search performed by the Search and Replace
plugin.</para>
</listitem>
</varlistentry>

<varlistentry id="edit-previous-match">
<term><menuchoice>
<guimenu>Edit</guimenu>
<guimenuitem>Go to Previous Match</guimenuitem>
</menuchoice></term>
<listitem>
<para>Go to the previous match in a search performed by the Search and Replace
plugin.</para>
</listitem>
</varlistentry>

<varlistentry id="view-toolviews-searchandreplace">
<term><menuchoice>
<guimenu>View</guimenu><guisubmenu>Tool Views</guisubmenu>
<guimenuitem>Show Search and Replace</guimenuitem>
</menuchoice></term>
<listitem>
<para>Toggle the display of &kate;'s <guilabel>Search and Replace</guilabel> tool.
</para>
</listitem>
</varlistentry>

</variablelist>

</sect2>
</sect1>

<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>

<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 &javascript;.</para>
</sect2>

<sect2 id="snippets-menu">
<title>Menu Structure</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>

<varlistentry id="tools-create-snippet">
<term><menuchoice>
<guimenu>Tools</guimenu>
<guimenuitem>Create Snippet</guimenuitem>
</menuchoice></term>
<listitem>
<para>Create a new snippet, which is a reusable chunk of text you
may insert in any part of any document.</para>
</listitem>
</varlistentry>

</variablelist>

</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>

<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>

<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>

<sect3 id="snippets-repo-editor">
<title>Creating and Editing Repositories</title>

<para>To create a new snippet repository, click <guibutton>Add Repository</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>OK</guibutton>.</para>

<screenshot id="screenshot-snippets-repository">
<screeninfo>Snippet Editor</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="snippets-repository.png" format="PNG"/></imageobject>
<textobject><phrase>The repository editor.</phrase></textobject>
<caption><para>The repository editor interface.</para></caption>
</mediaobject>
</screenshot>

<para>The snippet repository editor contains the following options:</para>

<variablelist>

<varlistentry>
<term><guilabel>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><guilabel>Namespace</guilabel></term>
<listitem><para>Prefix used while using code completion.</para></listitem>
</varlistentry>

<varlistentry>
<term><guilabel>License</guilabel></term>
<listitem><para>Select the license for you snippet repository.</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>
</varlistentry>

<varlistentry>
<term><guilabel>File types</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 clicking on the items.  You can specify more
than one file type pressing the &Shift; while adding types.</para></listitem>
</varlistentry>

</variablelist>

</sect3>

<sect3 id="snippets-editor">
<title>Creating and Editing Snippets</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>

<variablelist>

<varlistentry>
<term><guilabel>Name</guilabel></term>
<listitem><para>The name will be shown in the completion list.</para></listitem>
</varlistentry>

<varlistentry>
<term>Shortcut</term>
<listitem><para>Pressing this shortcut will insert the snippet into the document.</para></listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Snippets</guilabel></term>
<listitem><para>The text your snippet will insert into the document.</para>
<para>A snippet can contain editable fields. They can be cycled by
pressing &Tab;. The following expressions can be used in the template
text to create fields:</para>
<para><userinput>${<replaceable>field_name</replaceable>}</userinput> creates a
simple, editable field. All subsequent occurrences of the same
<replaceable>field_name</replaceable> create fields which mirror the contents
of the first during editing.</para>
<para><userinput>${<replaceable>field_name=default</replaceable>}</userinput>
can be used to specify a default value for the field.
<replaceable>default</replaceable> can be any &javascript; expression.</para>
<para>Use <userinput>${<replaceable>field_name</replaceable>=<replaceable>text</replaceable>}</userinput>
to specify a fixed string as default value.</para>
<para><userinput>${func(<replaceable>other_field1</replaceable>,
<replaceable>other_field2</replaceable>, ...)}</userinput> can be used to create a
field which evaluates a &javascript; function on each edit and contains its
contents. See the <guilabel>Scripts</guilabel> tab for more information.</para>
<para><userinput>${cursor}</userinput> can be used to mark the end position
of the cursor after everything else was filled in.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Scripts</guilabel></term>
<listitem><para>&javascript; helper functions to use in your snippets.</para>
<para>All &javascript; functions should return the contents you want to place in a
template field as a string.</para>
<para>Functions are called in a scope which contains the contents of all
editable template fields as local variables. For example in a snippet
containing <userinput>${<replaceable>field</replaceable>}</userinput>,
a variable called <userinput>field</userinput> will be present which contains
the up-to-date contents of the template field. Those variables can either
be used in the function statically or passed as arguments, by using the
<userinput>${func(field)}</userinput> or <userinput>${<replaceable>field2=func(field)</replaceable>}</userinput>
syntax in the snippet string.</para>
<para>You can use
the <ulink url="help:/katepart/dev-scripting.html#dev-scripting-api">&kate; scripting API</ulink>
to get the selected text, full text, file name and
more by using the appropriate methods of the <userinput>document</userinput>
and <userinput>view</userinput> objects. Refer to the scripting API
documentation for more information</para>
</listitem>
</varlistentry>

</variablelist>
</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;
&Space;</keycombo>, which will display all the snippets in a
convenient window from which you can choose.  This key combination 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 &Tab; 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>


<sect1 id="kate-application-plugin-sql">
<sect1info>
<authorgroup>
<author><firstname>Ömer</firstname> <othername>Faruk</othername> <surname>ORUÇ</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>

</sect2>

<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>

<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>Finally, give a name to your connection, and press <guibutton>Finish</guibutton>.</para>

</sect2>

<sect2 id="sql-querying">
<title>Running Queries</title>

<sect3 id="sql-querying-insert-delete-update">
<title>INSERT/DELETE/UPDATE</title>

<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> button in the toolbar or
use <menuchoice><guimenu>SQL</guimenu><guimenuitem>Run query</guimenuitem></menuchoice>
(<keycombo action="simul">&Ctrl;<keycap>E</keycap></keycombo>).</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>
</varlistentry>

<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>
<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>

</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 &kate;, 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>
</varlistentry>

<varlistentry>
<term><guibutton>Resize rows to contents</guibutton></term>
<listitem><para>Changes the size of rows to fit their contents.</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>
</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>
</varlistentry>

<varlistentry>
<term><guibutton>Clear</guibutton></term>
<listitem><para>Removes everything from the table view.</para></listitem>
</varlistentry>

<!--FIXME Use system locale -->

</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>

</sect3>
</sect2>

<sect2 id="sql-browsing">
<title>Browsing</title>

<para>You can browse your database using the <guilabel>Database schema</guilabel> browser
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>

<varlistentry>
<term><menuchoice>
<guimenu>SQL</guimenu><guimenuitem>Remove connection</guimenuitem>
</menuchoice></term>
<listitem><para>
Removes the selected connection.
</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<guimenu>SQL</guimenu><guimenuitem>Edit connection...</guimenuitem>
</menuchoice></term>
<listitem><para>
Edits the current connection's settings.
</para></listitem>
</varlistentry>

<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><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="sql-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
writing much of this section.</para>

</sect2>

</sect1>

<sect1 id="kate-application-plugin-symbolviewer">
<!--https://kate-editor.org/2010/10/27/php-treeview-improvements-in-kate/?-->
<title>Symbol Viewer Plugin</title>

<sect2 id="symbolviewer-using">
<title>Using the Close Except/Like Plugin</title>

<para>It allows developers to view symbols (functions, macros and structures) from source code.</para>
<para>By clicking the parsed information you can easily browse the code.</para>
<para>At the moment the following languages are supported:</para>
<para>C/C++, &Java;, Perl, PHP, Python, Ruby, XSLT, Tcl/Tk, Fortran</para>

<para>Feature list:</para>
<simplelist>
<member>List/Tree mode</member>
<member>Enable/disable sorting</member>
<member>Hide/Show Functions Parameters</member>
<member>Expand/collapse tree mode</member>
<member>Auto-update on document change</member>
<member>Code parsing is based on the Syntax-Highlighting framework from &kde-frameworks;</member>
</simplelist>

</sect2>

<sect2 id="symbolviewer-menu">
<title>Menu Structure</title>
<variablelist>

<varlistentry id="tools-symbolviewer">
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>\</keycap></keycombo>
</shortcut>
<guimenu>View</guimenu>
<guisubmenu>Tool Views</guisubmenu>
<guimenuitem>Show Symbol List</guimenuitem>
</menuchoice></term>
<listitem>
<para>Toggle the display of &kate;'s Symbol List displaying Functions, Macros and
Structures of the source code in the active document.</para>
</listitem>
</varlistentry>

</variablelist>

</sect2>

<sect2 id="symbolviewer-config">
<title>Configuration</title>

<screenshot id="screenshot-symbolviewer-settings">
<screeninfo>Symbol Viewer</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="symbolviewer-settings.png" format="PNG"/></imageobject>
<caption><para>Choose the default parser options</para></caption>
</mediaobject>
</screenshot>

</sect2>

</sect1>


<sect1 id="kate-application-plugin-konsole">
<title>Terminal Tool View Plugin</title>

<para><indexterm><primary>Terminal emulator</primary></indexterm>
The built in Terminal Emulator is a copy of the &kde; &konsole;
terminal application, for your convenience. It is available from the
<menuchoice><guimenu>View</guimenu><guisubmenu>Tool Views</guisubmenu>
<guimenuitem>Show Terminal Panel</guimenuitem></menuchoice> menu item and will get the focus
whenever displayed. Additionally, if the <link
linkend="konsole-config">Automatically synchronize
the terminal with the current document when possible</link> option is enabled, it will
change to the directory of the current document if
possible when it is displayed, or when the current document
changes.</para>

<para>The default location in the &kate; window is at the bottom,
below the editing area.</para>

<para>You can configure the &konsole; using its &RMB; menu, for more
information, see the <ulink url="help:/konsole/index.html">&konsole; manual</ulink>.</para>

<para>The built-in terminal emulator is provided by the Terminal Tool View plugin.</para>

<sect2 id="konsole-menus">
<title>Menu Structure</title>

<variablelist>

<varlistentry id="view-toolviews-show-terminal">
<term><menuchoice>
<guimenu>View</guimenu><guisubmenu>Tool Views</guisubmenu>
<guimenuitem>Show Terminal Panel</guimenuitem>
</menuchoice></term>
<listitem>
<para>Toggles the display of the built-in terminal emulator.</para>
<para>When activated for the first time, the terminal will be created.</para>
<para>When the terminal emulator is displayed, it will get the focus, so that
you can start typing in commands immediately. If the <link
linkend="konsole-config">Automatically synchronize the terminal
with the current document when possible</link> option is enabled in the
<guilabel>Terminal</guilabel> page of the <link
linkend="config-dialog">Main configuration dialog</link> the shell session will
change to the directory of the active document, if it is a local file.</para>
</listitem>
</varlistentry>

<varlistentry id="view-toolviews-pipe-to-terminal">
<term><menuchoice><guimenu>Tools</guimenu><guimenuitem>Pipe to
Terminal</guimenuitem></menuchoice></term>
<listitem><para>Feed the currently selected text into the built-in terminal
emulator. No newline is added after the text.</para></listitem>
</varlistentry>

<varlistentry id="tools-sync-terminal-document">
<term><menuchoice>
<guimenu>Tools</guimenu>
<guimenuitem>Synchronize Terminal with Current Document</guimenuitem></menuchoice></term>
<listitem>
<para>This will cause the built-in Terminal to <command>cd</command> into the
directory of the active document.</para>

<para>Alternatively, you can configure &kate; to always keep the terminal in
sync with the current document.  See
<xref linkend="konsole-config"/> for more information.</para>
</listitem>
</varlistentry>

<varlistentry id="tools-focus-terminal">
<term><menuchoice>
<guimenu>Tools</guimenu>
<guimenuitem>Focus/Defocus Terminal Panel</guimenuitem>
</menuchoice></term>
<listitem>
<para>Switch the focus from the current document to the terminal and vice versa.
</para>
</listitem>
</varlistentry>

</variablelist>
</sect2>

<sect2 id="konsole-config">
<title>Configuration</title>

<para>You can configure the Terminal Tool View plugin on the
<guilabel>Terminal</guilabel> page of the
<link linkend="configuring-kate">configuration dialog</link>.</para>

<para>The following options are available:</para>

<variablelist>
<varlistentry>
<term>
<guilabel>Automatically synchronize the terminal with the current document when possible</guilabel></term>
<listitem><para>This will cause the built-in terminal to
<command>cd</command> into the directory of the active document when
launched and when a new document gets the focus. If not enabled, you
have to do all your navigation in the terminal on your own.
</para></listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Set EDITOR environment variable to 'kate -b'</guilabel></term>
<listitem><para>This sets the <envar>EDITOR</envar> environment variable so programs
run in the built-in terminal that automatically open a file in an editor will open
them in &kate; instead of the default editor configured in your shell.  You will
not be able to continue using the terminal until you have closed the file in &kate;,
so the calling program is aware you have finished editing the file.</para></listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Hide &konsole; on pressing 'Esc'</guilabel></term>
<listitem><para>This allows closing the built-in terminal by pressing the &Esc; key. May cause issues with terminal applications
that use &Esc; key, &eg; <application>vim</application>. Add such applications in the text input box below.
The items in the list should be separated with comma.</para></listitem>
</varlistentry>

</variablelist>
</sect2>

</sect1>

<sect1 id="kate-application-plugin-textfilter">

<title>Text Filter Plugin</title>

<sect2 id="textfilter-using">
<title>Using the Text Filter Plugin</title>

<para>You can use this plugin to process selected text using terminal commands.
The selection will be used as input for the command, and the output will either
replace the selection or be copied to the clipboard, depending on the user's preference.
</para>

<itemizedlist>
<title>Examples:</title>
<listitem><para>
<command>less /etc/fstab</command> - paste the contents of this file or copy it to the clipboard
</para></listitem>
<listitem><para>
<command>wc</command> - count lines, words and characters of the selection and
paste this into the document or copy it to the clipboard
</para></listitem>
<listitem><para>
<command>sort</command> - sort lines of the selection and paste the result into
the document or copy it to the clipboard
</para></listitem>
</itemizedlist>

</sect2>

<sect2 id="textfilter-menu">
<title>Menu Structure</title>

<variablelist>

<varlistentry id="tools-textfilter">
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>\</keycap></keycombo><!--FIXME shortcut does not work with a german keyboard \ = AltGr+\-->
</shortcut>
<guimenu>Tools</guimenu>
<guisubmenu>Filter Text</guisubmenu>
</menuchoice></term>
<listitem>

<para><action>Opens</action> the Text Filter dialog:</para>

<screenshot id="screenshot-filtertext">
<screeninfo>Text Filter dialog</screeninfo>
<mediaobject>
<imageobject><imagedata fileref="textfilter.png" format="PNG"/></imageobject>
</mediaobject>
</screenshot>

<para>Enter the shell command into the combobox or select a previous command from the history.</para>

<variablelist>

<varlistentry>
<term><guilabel>Copy the result instead of pasting it</guilabel></term>
<listitem>
<para>Copy the result to clipboard leaving a document unchanged.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Merge STDOUT and STDERR</guilabel></term>
<listitem>
<para>
If checked, an output from STDOUT and STDERR will be merged and no errors will be reported.
Otherwise, STDERR will be displayed as a passive message.</para>
</listitem>
</varlistentry>

</variablelist>

</listitem>
</varlistentry>

</variablelist>

</sect2>

</sect1>

<sect1 id="kate-application-plugin-xmlcheck">
<!-- from doc/kate-addons/xmlcheck.docbook -->
<sect1info>
<authorgroup><author>
&Daniel.Naber; &Daniel.Naber.mail;
</author></authorgroup>
</sect1info>

<title>&XML; Validation</title>

<para>This plugin checks &XML; files for validity and being well-formed.</para>
<para>This plugin checks the current file. A list of warnings and errors
will appear at the bottom of &kate;'s main window. You can click on an error message
to jump to the corresponding place in the file. If the file has a <quote>DOCTYPE</quote>
the DTD given with this doctype will be used to check the file for validity. The
DTD is expected at a position relative to the current file, &eg; if the doctype
refers to <quote>DTD/xhtml1-transitional.dtd</quote> and the file is <filename>/home/peter/test.xml</filename>
the DTD is expected to be located at <filename>/home/peter/DTD/xhtml1-transitional.dtd</filename>.
However, remote DTDs specified via http are supported.</para>

<para>If the file has no doctype it will be checked for being well-formed.</para>

<para>To learn more about &XML; check out the <ulink url="https://www.w3.org/XML/"> official W3C &XML; pages</ulink>.</para>

<para>Internally this plugin calls the external command <command>xmllint</command>, which
is part of libxml2. If this command is not correctly installed on your system, the plugin
will not work.</para>

<para>To load this plugin open &kate;'s configuration dialog under <menuchoice><guimenu>Settings</guimenu>
<guimenuitem>Configure &kate;...</guimenuitem></menuchoice>.
Then select <guilabel>&XML; Validation</guilabel> which will appear
in the <guilabel>Application</guilabel> / <guilabel>Plugins</guilabel> section and close the dialog.
</para>

<sect2 id="xmlcheck-menu">
<title>Menu Structure</title>

<variablelist>
<varlistentry>
<term>
<menuchoice>
<guimenu>&XML;</guimenu>
<guimenuitem>Validate &XML;</guimenuitem>
</menuchoice>
</term>
<listitem><para>This will start the check, as described above.</para></listitem>
</varlistentry>
</variablelist>

</sect2>

<sect2 id="xmlcheck-thanks-and-acknowledgements">
<title>Thanks and Acknowledgments</title>
<para>
&kate; Plugin <quote>&XML; Validation</quote> copyright 2002 &Daniel.Naber;
&Daniel.Naber.mail;.
</para>
<para>Documentation copyright 2002 &Daniel.Naber;</para>

</sect2>
</sect1>

<sect1 id="kate-application-plugin-xmltools">
<!-- from doc/kate-addons/xmlcheck.docbook -->
<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 (&eg; all entities are listed if the character on the left
of the cursor is <quote>&amp;</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">katexmltools/</filename> in
<userinput><command>qtpaths</command> <option>--paths GenericDataLocation </option></userinput>,
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>&lt;</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 (&eg; <quote>&lt;html&gt;</quote>).</para></listitem>
</varlistentry>

<varlistentry>
<term><keycap>&lt;</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>&nbsp;</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>&amp;</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>katexmltools/testcases.xml</filename> in
<userinput><command>qtpaths</command> <option>--paths GenericDataLocation </option></userinput>
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;&Enter;</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 &lt;, &gt; 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>&lt;</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>


</chapter>