<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1.2-Based Variant V1.0//EN" "dtd/kdex.dtd" [
  <!ENTITY kscope '<application>KScope</application>'>
  <!ENTITY kapp "&kscope;"><!-- replace kscope here -->
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE"><!-- change language only here -->


  <!-- Do not define any other entities; instead, use the entities
       from kde-genent.entities and $LANG/user.entities. -->
]>

<!-- The language must NOT be changed here. -->

<book lang="&language;">

<!-- This header contains all of the meta-information for the document such
as Authors, publish date, the abstract, and Keywords -->

<bookinfo>
<title>The &kapp; Handbook</title>

<authorgroup>
<author>
<firstname>Elad</firstname>
<othername></othername>
<surname>Lahav</surname>
<affiliation>
<address><email>elad_lahav@users.sf.net</email></address>
</affiliation>
</author>
</authorgroup>

<!-- TRANS:ROLES_OF_TRANSLATORS -->

<copyright>
<year>2003-2005</year>
<holder>Elad Lahav</holder>
</copyright>
<!-- Translators: put here the copyright notice of the translation -->
<!-- Put here the FDL notice.  Read the explanation in fdl-notice.docbook
     and in the FDL itself on how to use it. -->
<legalnotice>&FDLNotice;</legalnotice>

<!-- Date and version information of the documentation
Don't forget to include this last date and this last revision number, we
need them for translation coordination !
Please respect the format of the date (DD/MM/YYYY) and of the version
(V.MM.LL), it could be used by automation scripts.
Do NOT change these in the translation. -->

<date>16/3/2005</date>
<releaseinfo>1.1.1</releaseinfo>

<!-- Abstract about this handbook -->

<abstract>
<para>
&kapp; is a source-editing environment for KDE, based on <application>Cscope</application>.
</para>
</abstract>

<!-- This is a set of Keywords for indexing by search engines.
Please at least include KDE, the KDE package it is in, the name
 of your application, and a few relevant keywords. -->

<keywordset>
<keyword>KDE</keyword>
<keyword>KScope</keyword>
<keyword>Cscope</keyword>
<keyword>source</keyword>
<keyword>editor</keyword>
<keyword>browser</keyword>
</keywordset>

</bookinfo>

<!-- The contents of the documentation begin here.  Label
each chapter so with the id attribute. This is necessary for two reasons: it
allows you to easily reference the chapter from other chapters of your
document, and if there is no ID, the name of the generated HTML files will vary
from time to time making it hard to manage for maintainers and for the CVS
system. Any chapter labelled (OPTIONAL) may be left out at the author's
discretion. Other chapters should not be left out in order to maintain a
consistent documentation style across all KDE apps. -->

<chapter id="introduction">
<title>Introduction</title>

<!-- The introduction chapter contains a brief introduction for the
application that explains what it does and where to report
problems. Basically a long version of the abstract.  Don't include a
revision history. (see installation appendix comment) -->

<para>
&kapp; is a source-editing environment for KDE. Primarily, it is a front-end to the veteran <ulink url="http://cscope.sourceforge.net">Cscope</ulink>, a source-code browser originally developed at Bell Labs. <application>Cscope</application> works by parsing a set of source files, creating a cross-reference database, and allowing the user to query this database. &kapp; extends the feature-set of <application>Cscope</application> with a contemporary user interface, editor integration, project management capabilities, and multiple query result windows.
</para>
<para>
&kapp; is not an IDE. It is not intended for building or debugging projects. Its primary objective is to simplify the development of large C projects, such as the Linux kernel, achieving this goal by allowing the user to run queries on the code. Unlike most modern IDEs, it does not have a window that displays a hierarchical tree of all project symbols. This is because such a display, adequate for C++ or Java projects, is meaningless in the functional world of C. Instead, &kapp;'s function-oriented queries allow the user to effectively browse the source code of the entire project. Query results are displayed in either a query window, or a function call-tree, giving the user a better understanding of the code's structure.
&kapp; implements (almost) all of <application>Cscope</application>'s query types. Among these are:
<itemizedlist>
<listitem><para>Browse for all references to a symbol;</para></listitem>
<listitem><para>Get the global definition of a symbol;</para></listitem>
<listitem><para>Find all functions calling or called by a function;</para></listitem>
<listitem><para>Find a text string or EGrep pattern;</para></listitem>
<listitem><para>and more.</para></listitem>
</itemizedlist>
</para>
<para>
&kapp; is a part of an ongoing effort to expand the range of open source solutions. It could not have been created without the previous work of many devoted developers. &kapp; is therefore freely distributed, along with its source code, for the benefit of the open source community. I hope it can be of use to others, and I would appreciate any help in the form of bug reports or improvement suggestions.
</para>
</chapter>

<chapter id="using-kscope">
<title>Using &kapp;</title>

<sect1 id="kscope-main-window">
<title>The Main Window</title>

<para>
&kapp;'s main window is divided into three. The central area is dedicated to source editing, and holds a set of editor windows, one for each open source file. This area is greyed-out if no files are open for editing. The window to the right is the file browser, comprised of a list of project files, and a tree-like view of the file system. The project file list will only display files after a project has been created and source files have been added to it. The bottom area contains the query windows, which hold the results of <application>Cscope</application> queries, and the history pages that display locations in the source code visited by the user.
</para>
<screenshot>
<screeninfo>The Main Window</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="main_window.png" format="PNG" />
</imageobject>
<textobject>
<phrase>&kapp;'s main window</phrase>
</textobject>
</mediaobject>
</screenshot>
<para>
The size of each of these sub-windows can be changed to meet the user's personal preferences. This is done by dragging the lines that separate one area from the other. The new sizes will be kept and used on the next sessions as well.
</para>
<para>
The file browser and the query window can be hidden in order to free up desktop space (especially on low resolution displays.) Hiding and showing these windows is done through the <guimenu>View</guimenu> menu. A window can also be hidden by clicking on its close button, at the upper right corner. As with window sizes, the visibility status will be saved when &kapp; is closed.
</para>
</sect1>

<sect1 id="kscope-projects">
<title>Working with Projects</title>

<para>
Before any significant work can be done with &kapp;, the user has to define a project. A &kapp; project is a set of source files, which <application>Cscope</application> uses to create its cross-reference database. Unlike many other project-based environment, &kapp; is not intrusive: it only uses three files to define the project (with additional two files if the inverted index option is used). These files reside on a user-specified folder that does not have to be related to the location of the source files. Thus, &kapp; does not require any source files to be moved, and does not affect the structure of the source tree.
</para>
<para>
The files used by a &kapp; project are:
<variablelist>
<varlistentry>
<term><filename>cscope.proj</filename></term>
<listitem><para>The project's configuration file</para></listitem>
</varlistentry>
<varlistentry>
<term><filename>cscope.files</filename></term>
<listitem><para>A list of all source files included in the project</para></listitem>
</varlistentry>
<varlistentry>
<term><filename>cscope.out</filename></term>
<listitem><para><application>Cscope</application>'s cross-reference database</para></listitem>
</varlistentry>
<varlistentry>
<term><filename>cscope.in.out</filename></term>
<listitem><para>An inverted index file (optional)</para></listitem>
</varlistentry>
<varlistentry>
<term><filename>cscope.po.out</filename></term>
<listitem><para>An inverted index file (optional)</para></listitem>
</varlistentry>
</variablelist>
</para>
<para>
The only limitation imposed by &kapp; is that these files have to reside in the same directory, referred to as the project's directory. The project's directory has the same name as the project (which means that project names should conform to the file-system conventions), and can be placed by the user under any directory. Normally, a user will create a <filename>projects</filename> sub-directory under his or hers home directory, and create all projects there. However, this is only a convention, and, as explained above, the user can choose any other method he or she prefers. Furthermore, the project's directory can later be moved to another parent directory, without any risk of data loss.
</para>

<sect2 id="kscope-project-create">
<title>Creating a New Project</title>

<para>
The first step in working with projects is to create a new one. This is done by choosing the <menuchoice><guimenu>Projects</guimenu><guimenuitem>New...</guimenuitem></menuchoice> command from the main menu. Issuing this command opens the <guilabel>New Project</guilabel> dialogue:
<screenshot>
<screeninfo>The New Project dialogue</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="project_new.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The New Project dialogue</phrase>
</textobject>
</mediaobject>
</screenshot>
<variablelist>
<varlistentry>
<term><guilabel>Name</guilabel></term>
<listitem><para>The name of the project. Note that this name will be given to the project's directory, and should therefore comply with the file-system convention for directory names (e.g., no spaces.)</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Path</guilabel></term>
<listitem><para>The full path of the directory under which the new project will be created. &kapp; will create a new directory under this one, and name it after the project. Thus this path does not need to point directly to the project's directory, but rather to the project's parent directory. For example, if a user wants to create a project called "my_project" under his local <filename>projects</filename> directory, the project's name should be set to "my_project" and the path to <filename>/home/my_username/projects</filename>. This will set the project's directory to <filename>/home/my_username/projects/my_project</filename>.</para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Find...</guibutton></term>
<listitem><para>This button can be used to <action>invoke a file-system directory browser</action> that assists the user in selecting the path.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>File Types</guilabel></term>
<listitem><para>A list of file name patterns that are used to define the type of source files to be included in the project. By default, C source files (<filename>.c</filename>) and C header files (<filename>.h</filename>) are included, but other types (including Lex's <filename>.l</filename> files and Yacc's <filename>.y</filename> files) can be added.</para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Add</guibutton></term>
<listitem><para><action>Adds the file name pattern, currently written in the edit-box to its right, to the list of file types.</action></para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Remove</guibutton></term>
<listitem><para><action>Removes the currently selected file name pattern (if any) from the list of file types.</action></para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Kernel Project</guilabel></term>
<listitem><para>Mark this check-box if the project is designated to be a kernel-type project. For kernel projects, <application>Cscope</application> ignores the system's include files when building the cross-reference database (i.e., <symbol>printf</symbol> will not be found in <filename>/usr/include/stdio.h</filename>.)</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Build Inverted Index</guilabel></term>
<listitem><para><application>Cscope</application> can build an inverted index for the project to speed up queries (though at the expense of more time spent on building and refreshing the database.)</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Refresh Database Automatically</guilabel></term>
<listitem><para>&kapp; can rebuild the cross-reference database automatically, a process which is triggered when a source file is saved. If this option is selected, the user needs to specify the time (in seconds) that should elapse after each file save operation and before the database is rebuilt.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Use Symbol Auto-Completion</guilabel></term>
<listitem><para>Enables automatic "as-you-write" symbol completion. Note that manual symbol completion is always available, regardless of whether this option is selected.</para>
<note><para>If you choose to enable this option, it is recommended that you also select the inverted index option.</para></note></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Options...</guibutton></term>
<listitem><para><action>Displays the symbol auto-completion configuration dialogue.</action> This button is only enabled if the symbol auto-completion is selected (see <link linkend="kscope-auto-symbol-completion">Automatic Symbol Completion</link> for a description of this dialogue).</para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Create</guibutton></term>
<listitem><para><action>Accepts the values entered in the dialogue, and creates a new project.</action> If any mandatory values were omitted, or not entered correctly, the user is prompted.</para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Cancel</guibutton></term>
<listitem><para><action>Closes the dialogue without creating a new project.</action></para></listitem>
</varlistentry>
</variablelist>
</para>
<para>
Note that this dialogue is intended for creating an empty project only, and has nothing to do with the actual source files of the project. This task is left to the <guilabel>Project Files</guilabel> dialogue.
</para>
</sect2>

<sect2 id="kscope-project-files">
<title>Adding and Removing Project Files</title>

<para>
The project's list of source files is maintained by the <guilabel>Project Files</guilabel> dialogue. This dialogue allows the user to add source files to a project, or remove files currently included in it. The dialogue is invoked automatically after a new project has been created, or manually by selecting the <menuchoice><guimenu>Project</guimenu><guimenuitem>Add/Remove Files...</guimenuitem></menuchoice> command from the main menu.
</para>
<screenshot>
<screeninfo>The Project Files dialogue</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="project_files.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The Project Files dialogue</phrase>
</textobject>
</mediaobject>
</screenshot>
<variablelist>
<varlistentry>
<term><guilabel>File Path</guilabel></term>
<listitem><para>Displays a list of all source files included in the project. Note that when adding and removing files, the project itself is not modified until the <guibutton>OK</guibutton> button is clicked.</para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Filter</guibutton></term>
<listitem><para>Hides all files whose path names do not include the text entered in the edit-box to the right of the button. This can simplify the task of finding files in the project. The filter text can be any simplified regular expression (as given to file commands in a shell).</para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Show All</guibutton></term>
<listitem><para>Reveals any files formerly hidden with the <guibutton>Filter</guibutton> button.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Add</guilabel></term>
<listitem><para>All buttons in this group add files to the current project.</para>
<variablelist>
<varlistentry>
<term><guibutton>Files...</guibutton></term>
<listitem><para><action>Adds user-selected files to the current project.</action></para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Directory...</guibutton></term>
<listitem><para><action>Adds all source files in a directory to the current project.</action> Source files are scanned according to the file-types associated with the project. Note that sub-directories are not scanned for files.</para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Tree...</guibutton></term>
<listitem><para><action>Adds all source files in a selected directory and its sub-directories to the current project.</action> Source files are scanned according to the file-types associated with the project.</para></listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Remove</guilabel></term>
<listitem><para>All buttons in this group remove files from the current project.</para>
<variablelist>
<varlistentry>
<term><guibutton>Selected</guibutton></term>
<listitem><para><action>Removes all selected files from the current project.</action> Files can be selected for removal by clicking their path name in the file list. The <keycap>Ctrl</keycap> key can be used to select multiple files, and the <keycap>Shift</keycap> key can be used to select ranges of files.</para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Directory...</guibutton></term>
<listitem><para><action>Removes all source files in a directory from the current project.</action> Note that sub-directories are not included.</para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Tree...</guibutton></term>
<listitem><para><action>Removes all source files in a directory and any of its sub-directories from the current project.</action></para></listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term><guibutton>OK</guibutton></term>
<listitem><para><action>Accepts the new list of source files, and updates the project.</action></para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Cancel</guibutton></term>
<listitem><para><action>Closes the dialogue without modifying the list of project files.</action></para></listitem>
</varlistentry>
</variablelist>
<para>
Once the project's file list has changed (either when files are first added to the project, or upon any subsequent modification), &kapp; informs <application>Cscope</application> to rebuild the cross-reference database.
</para>

</sect2>

<sect2 id="kscope-project-open">
<title>Opening an Existing Project</title>

<para>
Existing projects can be opened using the <menuchoice><guimenu>Project</guimenu><guimenuitem>Open...</guimenuitem></menuchoice> menu command. Choosing this command invokes the <guilabel>Open Project</guilabel> dialogue, which allows the user to select the project to open.
</para>
<screenshot>
<screeninfo>The Open Project dialogue</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="project_open.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The Open Project dialogue</phrase>
</textobject>
</mediaobject>
</screenshot>

<variablelist>
<varlistentry>
<term><guilabel>Project Path</guilabel></term>
<listitem><para>The full path of the project directory.</para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Find...</guibutton></term>
<listitem><para><action>Launches a file-system browser that helps the user locate the project's directory.</action> This is done by browsing for the project's configuration file (cscope.proj) which resides in the project's directory.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Recent Projects</guilabel></term>
<listitem><para>Displays a list of recently-opened projects. Clicking a list item copies its path to the Project Path edit-box, while double-clicking an item opens the project.</para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Remove</guibutton></term>
<listitem><para><action>Removes an entry from the list of recently-opened projects.</action></para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Open</guibutton></term>
<listitem><para><action>Opens the project whose directory is set in the Project Path edit-box.</action></para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Cancel</guibutton></term>
<listitem><para><action>Closes the dialogue without opening a project.</action></para></listitem>
</varlistentry>
</variablelist>

<para>
When a project is closed, it saves session information, such as source files being edited and the contents of locked queries. The session is restored when a project is opened.
</para>
<para>
After the project has been opened, &kapp; will invoke <application>Cscope</application>, which, in turn, will check whether any files have been modified since the last time the project had been closed. If any files have been changed, <application>Cscope</application> will rebuild the cross-reference database.
</para>

</sect2>

<sect2 id="kscope-project-prop">
<title>Changing Project Properties</title>

<para>
The properties of an open project can be changed by choosing the <menuchoice><guimenu>Project</guimenu><guimenuitem>Properties...</guimenuitem></menuchoice> menu command. This command invokes the <guilabel>Project Properties</guilabel> dialogue, which is similar to the <guilabel>New Project</guilabel> dialogue, except that the name and path of the project cannot be changed.
</para>

<para>
See the <link linkend="kscope-project-create">New Project dialogue</link> for a description of the available project options.
</para>

</sect2>

<sect2 id="kscope-projects-temp">
<title>Temporary Projects</title>

<para>
Temporary projects are created when a user opens a cscope.out file directly. This option is useful for working on projects created by some other <application>Cscope</application> front-end (<application>Cscope</application>'s ncurses interface, Vi, Emacs, etc.), or simply using <application>Cscope</application>'s <option>-b</option> command-line parameter.
</para>

<para>
To open a database file, use the <menuchoice><guimenu>Project</guimenu><guimenuitem>Open Cscope.out...</guimenuitem></menuchoice> menu command. If the file is a valid <application>Cscope</application> cross-reference database, &kapp; will invoke <application>Cscope</application> using this file, and will be ready to accept queries on the database. Cscope.out files can also be opened through the command line, which means that you can simply drag a Cscope.out file, and drop it over &kapp;'s programme icon.
</para>

<para>
Note, however, that most project management options provided by &kapp; will not be available for temporary projects: the file list for the project will be empty, users will not be able to add or remove files, and the project properties dialogue will not be available. You will also need to rebuild the database manually when making any changes. &kapp;'s rebuild command assumes the database has been updated, and only re-runs <application>Cscope</application>.
</para>

</sect2>

</sect1>

<sect1 id="kscope-edit">
<title>Editing Source Files</title>

<sect2 id="kscope-editor">
<title>The Editor</title>

<para>
&kapp; does not provide its own editor. Instead, it utilises KDE's KTextEditor infrastructure to embed the system's default editor. This means that any editor that supports the KTextEditor interface (e.g., &kate;, <application>KVim</application>) can be used with &kapp;. The editor is defined in KDE's control centre.
In any matter related to operating or configuring the editor, please refer to the manual of the editor itself.
</para>

</sect2>

<sect2 id="kscope-open-file">
<title>Opening Files for Editing</title>

<para>
Files are usually opened for editing as a part of a project. However, &kapp; enables the user to edit an occasional file that is not related to the project, through the <menuchoice><guimenu>File</guimenu><guimenuitem>Open...</guimenuitem></menuchoice> menu command. Note, however, that query results on files outside a project are meaningless.
</para>

<para>
Once a project has been opened, the list of all project files appears in the file list, to the right of the editing area. Each file entry in the list shows the file's type, its name, and its full path. Files are opened by either double-clicking their entry in the list, or by selecting the entry, and hitting the <keycap>Enter</keycap> key. The edit-box above the list can be used to quickly search for a file. Typing in this box selects the first list entry whose file name begins with the entered text.
</para>

<para>
Files can also be opened through the file tree, which shares its location with the project's file list (using a tabbed-window.) The file tree displays all files in the system, starting with a specific root directory. A root directory for the file tree is set on a per-project basis by using the <guibutton>Set Root...</guibutton> button. The file tree also sports a <guibutton>Find File...</guibutton> button for launching the file search <application>Cscope</application> query.
</para>

<note>
<para>
To decrease the loading time of projects, files and directories are only added to the tree when their parent directory is expanded. Therefore directories will not be marked as expandable by default, even if they are not empty.
</para>
</note>

<para>
For each file opened, &kapp; creates a separate editor window, inside the editing area. Each editor is associated with a tab, displaying the name of the edited file. Thus &kapp; provides a convenient multi-editor environment. You can switch between open files by selecting their respective tabs, or by using the <guimenu>Window</guimenu> menu.
</para>

<para>
To work on a new file, the user first needs to create it using the <menuchoice><guimenu>File</guimenu><guimenuitem>New...</guimenuitem></menuchoice> menu command. This opens an empty editor, that is not associated with a file name or path. Upon saving the work in this new editor, &kapp; will prompt the user for a file name and directory. Note that this does not add the file to the project. The user still needs to invoke the <guilabel>Project Files</guilabel> dialogue and add the new file to an open project.
</para>

</sect2>

<sect2 id="kscope-file-tags">
<title>File Tags</title>

<para>
In addition to being a front-end to <application>Cscope</application>, &kapp; also uses <application>Ctags</application> to display a list of symbols defined in the current file. Each editor window is added a list of these symbols to its left. This list displays the name of a symbol, its type (as a graphic shape), and the line where it is defined. Double-clicking a symbol, or selecting it and hitting the <keycap>Enter</keycap> key, sets the cursor to the beginning of this symbol's definition line. The list of symbols is refreshed whenever a file is saved.
</para>

<para>
The edit-box above the list of symbols can be used for quick symbol look-ups. Entering text in this box selects the first symbol whose name begins with this text.
</para>

<para>
By default, tags are sorted by to their name in ascending order. Click on a column header to sort the tags according to that column. A triangle to the side of a column name indicates this is the sorting column, and shows the sorting order (ascending or descending.) Once a sorting order is chosen, it becomes the default, and is used for all newly created lists (though not for currently open, unmodified, editor windows.)
</para>

</sect2>

<sect2 id="kscope-files-other">
<title>Other File Options</title>

<para>
&kapp;'s <guimenu>File</guimenu> menu includes further options, such as saving, printing and closing files. In addition, specific editors can offer extended features under the <guimenu>Tools</guimenu> menu (e.g., syntax highlighting, indentation, etc.)
</para>

</sect2>

<sect2 id="kscope-symbol-completion">
<title>Symbol Completion</title>

<para>
Symbol completion is a convinient feature that enables the user to enter previously declared symbols with fewer key strokes. Since the cross-reference database keeps record of all globally declared symbols, it can be queried for a complete symbol name based on a given prefix.

There are two types of symbol completion: manual and automatic. Manual symbol completion is always available, and can be invoked by the <menuchoice><guimenu>Edit</guimenu><guimenuitem>Complete Symbol</guimenuitem></menuchoice> menu command (or, more conviniently, by pressing <keycombo><keycap>Ctrl</keycap><keycap>Space</keycap></keycombo>). Once a completion request has been issued, &kapp; uses the characters immediately preceding the current cursor position as a prefix, and queries the database for possible completions. These completions are displayed in a list box, which can be browsed using the arrow keys. Pressing <keycap>Enter</keycap> replaces the prefix with the selected symbol. The <keycap>Esc</keycap> key hides the list without completing the symbol.
</para>

<sect3 id="kscope-auto-symbol-completion">
<title>Automatic Symbol Completion</title>

<para>
In addition to manual symbol completion, &kapp; can also provide automatic completion based on changes made by the user to the edited source code. Specifically, &kapp; tracks changes to the edited file, and if certain criteria are met, initiates a symbol completion query to the cross-reference database. Once a completion list is displayed, symbol completion behaves in the same way as in the manual case.
</para>

<para>
Automatic symbol completion is configured on a per-project basis. This feature is enabled or disabled via the <guilabel>Use Symbol Auto-Completion</guilabel> check-box in the <guilabel>New Project</guilabel> dialogue (this option can also be changed after a project has been created by invoking the <guilabel>Project Properties</guilabel> dialogue).
</para>

<note>
<para>
For performance reasons, it is highly recommended that automatic symbol completion will be used in conjunction with the inverted-index option.
</para>
</note>

<para>
As mentioned before, &kapp; uses several parameters to decide whether automatic symbol completion should be initiated. These parameters can be configured by clicking on the <guibutton>Options...</guibutton> button in the <guilabel>New Project</guilabel> dialogue (or, later, in the <guilabel>Project Properties</guilabel> dialogue). Clicking this button invokes the <guilabel>Auto-Completion Properties</guilabel> dialogue.

<screenshot>
<screeninfo>The auto-completion properties dialogue</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="autocomp_dlg.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The auto-completion properties dialogue</phrase>
</textobject>
</mediaobject>
</screenshot>

<variablelist>
<varlistentry>
<term><guilabel>Minimum Characters</guilabel></term>
<listitem><para>The minimal length of a symbol for which completion is provided.</para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Delay (ms)</guibutton></term>
<listitem><para>Specifies a time interval that should elapse after the last change to the edited text and before the symbol completion query is executed.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Maximum Entries</guilabel></term>
<listitem><para>The symbol completion list will display at most this number of possible completions. If the number of matched symbols in the database is greater, a message will be displayed (and no symbols will be available).</para></listitem>
</varlistentry>
</variablelist>
</para>

<para>
The main purpose of these parameters is to reduce the load on the system caused by frequent queries to the database. The default values have been tested in various scenarios, and are usually adequate.
</para>

</sect3>

</sect2>

</sect1>

<sect1 id="kscope-query">
<title>The Query System</title>

<para>
The heart of &kapp; is running <application>Cscope</application> queries. Queries are always performed on the cross-reference database of the active project.
</para>
<para>
&kapp; currently supports the following query types:
<itemizedlist>
<listitem><para>Find all references to a symbol</para></listitem>
<listitem><para>Find a symbol's global definition</para></listitem>
<listitem><para>Find all functions called by a given function</para></listitem>
<listitem><para>Find all functions calling a given function</para></listitem>
<listitem><para>Find a text string</para></listitem>
<listitem><para>Find an EGrep pattern (regular expression)</para></listitem>
<listitem><para>Find a file's path by its name</para></listitem>
<listitem><para>Find all files including a given file</para></listitem>
<listitem><para>Display a call-tree for a given function</para></listitem>
</itemizedlist>
A symbol, as referred to in the above list, may be a function, a global variable, a structure, a union or a type definition.
</para>

<important>
<para>
The cross-reference database is not updated automatically. The database may become obsolete whenever source files are modified, and queries on these files may yield incorrect results. Therefore it is important to update the database when query results are obviously wrong. This can be done by selecting the <menuchoice><guimenu>Cscope</guimenu><guimenuitem>Rebuild Database</guimenuitem></menuchoice> command from the main menu. <application>Cscope</application> will then scan all source files for any modifications done since the last update, and refresh its cross-reference database with the modified files only.
</para>
<para>
The database is updated automatically whenever the project is opened.
</para>
</important>

<sect2 id="kscope-query-run">
<title>Running a Query</title>

<para>
A query can be started in one of three ways:
<orderedlist>
<listitem><para>The main menu</para></listitem>
<listitem><para>Keyboard shortcuts</para></listitem>
<listitem><para>The editor's context-menu</para></listitem>
</orderedlist>
</para>

<para>
To start a query from the main menu, select the desired query type from the <guimenu>Cscope</guimenu> menu. This will display a dialogue box prompting you for the query's text. The text to enter depends upon the query's type.
<screenshot>
<screeninfo>The query dialogue</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="query_dlg.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The query dialogue</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>

<para>
Any text selected in the editor when a query is requested will be automatically copied to the query dialogue. If no text is selected, KScope attempts to guess the requested symbol from the current location of the cursor.
</para>

<para>
Each menu item is associated with a keyboard shortcut. These shortcuts follow the convention of using the <keycap>Ctrl</keycap> key, together with the numeric query index used by <application>Cscope</application> (this should allow experienced <application>Cscope</application> users to get quickly acquainted with &kapp;.) For example, use <keycombo><keycap>Ctrl</keycap><keycap>1</keycap></keycombo> to look-up a symbol's definition. The call-tree is an exception to this convention (as it is not a native <application>Cscope</application> query). See the <link linkend="commands">Command Reference</link> for a complete listing of all menu and shortcut options.
</para>

<note>
<para>
The EGrep query is invoked using <keycombo><keycap>Ctrl</keycap><keycap>5</keycap></keycombo>, as <keycombo><keycap>Ctrl</keycap><keycap>6</keycap></keycombo> is already used by &kate;.
</para>
</note>

<para>
The third way of starting a query is by right-clicking inside an editor window. This invokes the context-menu, that displays the same options as in the <guimenu>Cscope</guimenu> section of the main menu. Using a context-menu is easy when combined with a symbol selection in the editor: position the text cursor inside a symbol, and then right click to display the context-menu.
</para>

<para>
Both the keyboard shortcuts and the context-menu items result in the display of the query dialogue. Once the query's text is entered in this dialogue, use the <guibutton>OK</guibutton> button to actually run the query. Clicking <guibutton>Cancel</guibutton> closes the window without executing the query.
</para>

<para>
A query may take some time to complete, depending on its type and the size of the project. &kapp; displays a progress indicator during long queries. If <application>Cscope</application>'s <option>-v</option> command line option is used, this progress indication is accurate, and displays the percentage of files already searched in. In case this option was omitted (e.g., if working with a version of <application>Cscope</application> prior to 15.5), &kapp; will present a dummy progress bar, used simply to indicate that a query is running, and that &kapp; has not frozen. Please refer to the section <link linkend="kscope-config">Configuring KScope</link> for more information.
</para>

</sect2>

<sect2 id="kscope-query-window">
<title>The Query Results Window</title>

<para>
When a query has terminated, its output is displayed in the query window, at the bottom of &kapp;'s main window. This window can manage several result pages simultaneously, with each page holding the results of a different query. Each page is associated with a tab that displays a summary of the query that generated these results. This tab is used to bring the results page forward, and is also associated with several page operations through a close button and a context menu.
</para>

<para>
By default, query results are displayed in the currently active page, overriding any prior contents. To keep a results page unchanged, the page needs to be "locked". Locked query pages are never overridden. The contents of these pages are also saved when the project is closed, and are restored when the project is reopened. To lock a project, either click the <guibutton>Lock/Unlock Query</guibutton> toggle button to the right of the query window, or use the context menu (available by right-clicking the page's tab.) The same methods can also be used to unlock a query.
</para>

<para>
New query pages can also be created explicitly, by using either the <guibutton>New Query</guibutton> button to the right of the query window, or the context menu available by right-clicking the tab area of the query window.
</para>

<para>
Each entry in a query results page represents a symbol or text string that complies to the search criteria. The entry is composed of four sections:
<itemizedlist>
<listitem><para>The path of the file in which the symbol or string were found</para></listitem>
<listitem><para>The name of the function containing the symbol or text string</para></listitem>
<listitem><para>The line number in this file</para></listitem>
<listitem><para>The text of this line</para></listitem>
</itemizedlist>
</para>

<para>
By default, results are sorted according to the file name. This can be changed by clicking the column headers of the results list.
</para>

<para>
The entries in a query results page can be used as shortcuts to editing the line in which the symbol or text string were found (or lines in that vicinity.) This is done by either double-clicking a result entry, or by selecting this entry and hitting the <keycap>Enter</keycap> key. As a result, &kapp; will open an editor window displaying the file referred to in the selected entry, and set the cursor to the beginning of the appropriate line.
</para>

<para>
If a query results in a single entry, this entry is automatically selected for display.
</para>

<para>
The results of a query can be refreshed by clicking the <guibutton>Refresh Query</guibutton> button to the right of the query window, or by using the context menu. This command is useful to rerun queries after the database has changed (such as after a <guimenuitem>Rebuild Database</guimenuitem> command had been issued.)
</para>

<para>
Query results pages can be closed by either clicking the icon on their tab, by clicking on the <guibutton>Close Query</guibutton> button to the right of the query window, by using the context menu (available by right-clicking the page's tab), or by selecting the <menuchoice><guimenu>Cscope</guimenu><guimenuitem>Close Query</guimenuitem></menuchoice> main-menu command.
</para>

<para>
If the query window is not visible when a query is executed, it is temporarily displayed, and then re-hidden when the user selects an entry for viewing.
</para>

</sect2>

<sect2 id="kscope-call-tree">
<title>The Call-Tree</title>

<para>
The Call-Tree is a special type of query offered by &kapp;, though not by <application>Cscope</application>. When launched on a name of a function, the query searches for all functions calling it. However, instead of displaying the query's output in a query results window, &kapp; opens a special dialogue box, whose central widget is a tree-like display. The root of the tree is the function on which the query was originally run, and the leaves are the names of all functions calling it.
</para>

<para>
The Call-Tree dialogue can be further utilised to display a call-stack of functions. Each function name in the tree has a small plus sign to its left. Clicking this sign expands the tree by adding all functions calling the selected one, thus creating a chain of calls.
<screenshot>
<screeninfo>The Call-Tree dialogue</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="call_tree.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The Call-Tree dialogue</phrase>
</textobject>
</mediaobject>
</screenshot>
</para>

<para>
As with the entries in a query results window, double-clicking a function name (or selecting it and hitting the <keycap>Enter</keycap> key) in the Call-Tree opens an editor window for editing that function. The Call-Tree will, however, remain open, until it is discarded by clicking the <guibutton>Close</guibutton> button.
</para>

</sect2>

</sect1>

</chapter>

<chapter id="kscope-config">
<title>Configuring &kapp;</title>

<sect1 id="kscope-config-dlg">
<title>The Configuration Dialogue</title>

<para>
The configuration dialogue is the main tool for setting parameters required by &kapp;, or adjusting the user's preferences. The dialogue is displayed the first time &kapp; is run, and can be invoked later by using the <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure KScope...</guimenuitem></menuchoice> menu command.
</para>

<para>
The dialogue is composed of several pages, each of which handles a different set of parameters.
</para>

<sect2 id="kscope-config-progs">
<title>The Programmes Page</title>

<para>
&kapp; serves as a front-end to two console-based programmes: <application>Cscope</application> and <application>Ctags</application>. Since &kapp; invokes these programmes directly, without using a shell, it cannot determine their paths. Therefore, it is required to inform &kapp; of the paths where <application>Cscope</application> and <application>Ctags</application> reside. Note that &kapp; needs the full path to each programme, along with the name of the executable.
</para>

<para>
Another parameter required by &kapp; is whether <application>Cscope</application> supports the <option>-v</option> command line option. This is a relatively new feature, added to <application>Cscope</application> in version 15.5. It allows &kapp; to display accurate progress information during time-consuming operations, such as building the cross-reference database, or running a long query. It is highly recommended that you upgrade <application>Cscope</application> to a version that supports the <option>-v</option> option, as the user experience of &kapp; is much improved with it. However, if you choose to use an older version of <application>Cscope</application>, make sure the check-box for using the <option>-v</option> option is cleared.
</para>

<para>
You can determine whether your version of <application>Cscope</application> supports this option by running <userinput><option>cscope</option> <option>-h</option></userinput>.
</para>

<para>
<screenshot>
<screeninfo>The Programmes page</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="frontend.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The Programmes page</phrase>
</textobject>
</mediaobject>
</screenshot>
<variablelist>
<varlistentry>
<term><guilabel>Cscope Path</guilabel></term>
<listitem><para>The full path of the Cscope executable. The name of this executable must be <filename>cscope</filename>.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Use verbose mode (-v)</guilabel></term>
<listitem><para>Instructs Cscope to produce verbose progress output, by appending <option>-v</option> to the command line.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Ctags Path</guilabel></term>
<listitem><para>The full path of the Ctags executable. The name of this executable must contain the string <filename>ctags</filename>.</para></listitem>
</varlistentry>
</variablelist>
If the file names on your system do not conform to the limitations described above, please create symbolic links to the executables.
</para>

</sect2>

<sect2 id="kscope-config-clrs">
<title>The Colours Page</title>

<para>
The Colours page allows you to configure &kapp; to look the way you want it to, by changing the foreground and background colours of the &kapp; windows. The windows that can be modified are:
<itemizedlist>
<listitem><para>The project's file list (to the right of the editing area)</para></listitem>
<listitem><para>The editor's symbol (or tag) list (to the left of each editor window)</para></listitem>
<listitem><para>The query results window</para></listitem>
</itemizedlist>
</para>

<para>
Note that the editor's own colours are determined by the settings of the embedded editor, and are not controlled by &kapp;.
</para>

</sect2>

<sect2 id="kscope-config-fonts">
<title>The Fonts Page</title>

<para>
The Fonts page allows you to determine the fonts used by any of &kapp;'s windows (see <link linkend="kscope-config-clrs">The Colours Page</link> section for a description of these windows.)
</para>

<para>
As with the colour scheme, the fonts used by the embedded editor are not determined by &kapp;.
</para>

</sect2>

<sect2 id="kscope-config-opts">
<title>The Options Page</title>

<para>
This page allows the user to configure certain parameters that affect the behaviour of &kapp;.
</para>

<para>
<screenshot>
<screeninfo>The Options page</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="options.png" format="PNG" />
</imageobject>
<textobject>
<phrase>The Options page</phrase>
</textobject>
</mediaobject>
</screenshot>
<variablelist>
<varlistentry>
<term><guilabel>Read-Only Mode</guilabel></term>
<listitem><para>If set, the embedded editor will be work in read-only mode, i.e., &kapp; will not allow any changes to the displayed source files.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>External Editor</guilabel></term>
<listitem><para>Specifies a command line for invoking an external editor application. &kapp; will replace the escape sequence %F with the file path, and the sequence %L with the current line number. This option is only available when working in Read-Only mode.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Open Last Project on Startup</guilabel></term>
<listitem><para>Determines whether &kapp; should automatically attempt to load the last active project when started.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Automatic Tag Highlighting</guilabel></term>
<listitem><para>If set, &kapp; will highlight tags in the tag list based on the current position of the text cursor.</para></listitem>
</varlistentry>
</variablelist>
</para>

</sect2>

</sect1>

</chapter>

<chapter id="commands">
<title>Command Reference</title>

<!-- (OPTIONAL, BUT RECOMMENDED) This chapter should list all of the
application windows and their menubar and toolbar commands for easy reference.
Also include any keys that have a special function but have no equivalent in the
menus or toolbars. This may not be necessary for small apps or apps with no tool
or menu bars. -->

<sect1 id="kscope-mainmenu">
<title>&kapp;'s Main Menu</title>

<para>
This section describes the menu entries declared by &kapp; only. Additional entries may be added to the main menu by the embedded editor (e.g., <guimenu>Edit</guimenu>, <guimenu>View</guimenu> or <guimenu>Tools</guimenu>.) Please refer to the editor's manual for a description of the commands under these sub-menus.
</para>

<sect2>
<title>The File Menu</title>

<para>
<variablelist>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>N</keycap></keycombo>
</shortcut>
<guimenu>File</guimenu>
<guimenuitem>New</guimenuitem>
</menuchoice></term>
<listitem><para><action>Opens an empty editor window.</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>O</keycap></keycombo>
</shortcut>
<guimenu>File</guimenu>
<guimenuitem>Open...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Opens a file for editing.</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>W</keycap></keycombo>
</shortcut>
<guimenu>File</guimenu>
<guimenuitem>Close</guimenuitem>
</menuchoice></term>
<listitem><para><action>Closes the active editor window</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>Q</keycap></keycombo>
</shortcut>
<guimenu>File</guimenu>
<guimenuitem>Quit</guimenuitem>
</menuchoice></term>
<listitem><para><action>Quits</action> &kapp;</para></listitem>
</varlistentry>
</variablelist>
</para>
<para>
Other file operations such as <guimenuitem>Save</guimenuitem> and <guimenuitem>Print</guimenuitem> are not integral &kapp; actions, but are rather defined by the type of editor used.
</para>

</sect2>

<sect2>
<title>The Edit Menu</title>

<para>
<variablelist>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>E</keycap></keycombo>
</shortcut>
<guimenu>Edit</guimenu>
<guimenuitem>Edit in External Editor</guimenuitem>
</menuchoice></term>
<listitem><para><action>Launches an editor application for the current file and line number</action> (available in Read-Only mode only.)</para></listitem>
</varlistentry>
</variablelist>
</para>

</sect2>

<sect2>
<title>The View Menu</title>

<para>
<variablelist>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>/</keycap></keycombo>
</shortcut>
<guimenu>View</guimenu>
<guimenuitem>Show/Hide File List</guimenuitem>
</menuchoice></term>
<listitem><para><action>Shows or hides the project's file list window.</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>.</keycap></keycombo>
</shortcut>
<guimenu>View</guimenu>
<guimenuitem>Show/Hide Query Window</guimenuitem>
</menuchoice></term>
<listitem><para><action>Shows or hides the query window.</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu>View</guimenu>
<guimenuitem>Show/Hide Query Buttons</guimenuitem>
</menuchoice></term>
<listitem><para><action>Shows or hides the query buttons</action> (the buttons to the right of the query window.)</para></listitem>
</varlistentry>
</variablelist>
</para>

</sect2>

<sect2>
<title>The Project Menu</title>

<para>
<variablelist>
<varlistentry>
<term><menuchoice>
<guimenu>Project</guimenu>
<guimenuitem>New...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Displays the New Project dialogue box.</action>Use this dialogue to create a new project.</para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu>Project</guimenu>
<guimenuitem>Open...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Displays the Open Project dialogue box</action>, which lets you search for an existing project to open.</para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu>Project</guimenu>
<guimenuitem>Add/Remove Files...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Displays the Project Files dialogue box</action>, which allows you to add source files to the current project, or remove files from it.</para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu>Project</guimenu>
<guimenuitem>Properties...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Displays the Project Properties dialogue box.</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu>Project</guimenu>
<guimenuitem>Open Cscope.out...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Opens an existing Cscope database.</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu>Project</guimenu>
<guimenuitem>Close</guimenuitem>
</menuchoice></term>
<listitem><para><action>Closes the active project</action>, along with all open editor windows.</para></listitem>
</varlistentry>
</variablelist>
</para>

</sect2>

<sect2>
<title>The Cscope Menu</title>

<para>
<variablelist>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>0</keycap></keycombo>
</shortcut>
<guimenu>Cscope</guimenu>
<guimenuitem>References...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Finds all references to a given symbol</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>1</keycap></keycombo>
</shortcut>
<guimenu>Cscope</guimenu>
<guimenuitem>Definition...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Finds the global definition of a symbol</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>2</keycap></keycombo>
</shortcut>
<guimenu>Cscope</guimenu>
<guimenuitem>Called Functions...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Finds all functions called by a given function</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>3</keycap></keycombo>
</shortcut>
<guimenu>Cscope</guimenu>
<guimenuitem>Calling Functions...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Finds all functions calling a given function</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>4</keycap></keycombo>
</shortcut>
<guimenu>Cscope</guimenu>
<guimenuitem>Find Text...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Finds all occurrences of a text string</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>5</keycap></keycombo>
</shortcut>
<guimenu>Cscope</guimenu>
<guimenuitem>Find EGrep Pattern...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Finds all text strings matching a regular expression</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>8</keycap></keycombo>
</shortcut>
<guimenu>Cscope</guimenu>
<guimenuitem>Find Including Files...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Finds all files #including a given file</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>]</keycap></keycombo>
</shortcut>
<guimenu>Cscope</guimenu>
<guimenuitem>Quick Definition</guimenuitem>
</menuchoice></term>
<listitem><para><action>Runs a definition query for the currently selected symbol</action> (i.e., without prompting the user)</para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Ctrl</keycap><keycap>-</keycap></keycombo>
</shortcut>
<guimenu>Cscope</guimenu>
<guimenuitem>Call Tree...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Displays a call-tree for a given function</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu>Cscope</guimenu>
<guimenuitem>Rebuild Database</guimenuitem>
</menuchoice></term>
<listitem><para><action>Updates the cross-reference database for the current project</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu>Cscope</guimenu>
<guimenuitem>Close Query</guimenuitem>
</menuchoice></term>
<listitem><para><action>Closes the active query results window</action></para></listitem>
</varlistentry>
</variablelist>
</para>

</sect2>

<sect2>
<title>The Go Menu</title>

<para>
<variablelist>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Alt</keycap><keycap>Left Arrow</keycap></keycombo>
</shortcut>
<guimenu>Go</guimenu>
<guimenuitem>Previous Position</guimenuitem>
</menuchoice></term>
<listitem><para><action>Go to the previous stored position in the history list</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo><keycap>Alt</keycap><keycap>Right Arrow</keycap></keycombo>
</shortcut>
<guimenu>Go</guimenu>
<guimenuitem>Next Position</guimenuitem>
</menuchoice></term>
<listitem><para><action>Go to the next stored position in the history list</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu>Go</guimenu>
<guimenuitem>Position History...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Displays the position history list, and allows quick navigation to its entries.</action></para></listitem>
</varlistentry>
</variablelist>
</para>
<para>
This menu enables navigation through positions stored while browsing through source files. Positions are saved whenever a user selects a <application>Cscope</application> query result to view or edit, or jumps to a tag inside a file.
</para>

</sect2>

<sect2>
<title>The Window Menu</title>

<para>
<variablelist>
<varlistentry>
<term><menuchoice>
<guimenu>Window</guimenu>
<guimenuitem>Close All Windows</guimenuitem>
</menuchoice></term>
<listitem><para><action>Closes all open editor windows</action></para></listitem>
</varlistentry>
</variablelist>
</para>
<para>
This menu displays the full path of each file edited in an open window. Clicking a
file name will make its editor window active.
</para>

</sect2>

<sect2>
<title>The Settings Menu</title>

<para>
<variablelist>
<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Configure KScope...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Displays the &kapp; configuration dialogue</action></para></listitem>
</varlistentry>
</variablelist>
</para>
<para>
A menu item to configure the embedded editor may also appear under this sub-menu.
</para>

</sect2>

</sect1>

</chapter>

<chapter id="credits">

<!-- Include credits for the programmers, documentation writers, and
contributors here. The license for your software should then be included below
the credits with a reference to the appropriate license file included in the KDE
distribution. -->

<title>Credits and License</title>

<para>
&kapp;
</para>
<para>
Programme copyright 2003-2004 Elad Lahav <email>elad_lahav@users.sf.net</email>
</para>
<para>
I would like to thank:
<itemizedlist>
<listitem><para>The <ulink url="http://www.kde.org">KDE</ulink> team</para></listitem>
<listitem><para>The <ulink url="http://www.kdevelop.org">KDevelop</ulink> team</para></listitem>
<listitem><para>Hans-Bernhard Broker, who maintains <ulink url="http://cscope.sourceforge.net">Cscope</ulink></para></listitem>
</itemizedlist>
</para>

<para>
Documentation copyright 2003-2004 Elad Lahav <email>elad_lahav@users.sf.net</email>
</para>

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

&underFDL;               <!-- FDL: do not remove. Commercial development should -->
<!-- replace this with their copyright and either remove it or re-set this.-->

<!-- Determine which license your application is licensed under,
     and delete all the remaining licenses below:

     (NOTE:  All documentation are licensed under the FDL,
     regardless of what license the application uses) -->

&underGPL;        	 <!-- GPL License -->

</chapter>

</book>