index.docbook

This a source insight software in Linux. It s is similar to the source insight software for windows.

</itemizedlist>
Note, however, that for position history records the "Function" field will always be empty.
</para>

<para>
A history page behaves like a stack: entries are always added at the top of the list, and represent the most recently visited locations. The user can then go backwards in time, by moving the lower records, or forward, by moving to upper records. If the current record in the list is not the top one, all records above it are removed before new records are added at the top (the future history is thus "forgotten").
</para>

<para>
At any given moment, at most one history page is considered as "active". This is the page to which history position records are added as the user browses through the code, and to which position navigation commands apply. See <link linkend="pos-hist-multi">Using Multiple Histories</link> for a detailed description of the active page concept.
</para>

<para>
A newly created project contains no position history pages. An initial page is created and set as active automatically when the first jump is made to a location in the code.
</para>

<para>
Each jump may add up to two entries to the active history list:
<orderedlist>
<listitem><para>The current position of the cursor (before the cursor jumps to the requested position), and</para></listitem>
<listitem><para>The new position of the cursor.</para></listitem>
</orderedlist>
Duplicates never occur in the list. If the location of the cursor is the same as the location that appears at the top of the history list, only the new position of the cursor will be added.
</para>

</sect2>

<sect2 id="pos-hist-nav">
<title>Navigation</title>

<para>
The key feature of the position history mechanism is the ability to navigate through the recorded locations in the source code. There are two ways to navigate through a history list: moving back and forth through the list, and jumping directly to a specific position.
</para>

<para>
To go back to the last position visited, select the <menuchoice><guimenu>Go</guimenu><guimenuitem>Previous Position</guimenuitem></menuchoice> menu item. This command selects the item immediately below the current one in the active history list (and moves the cursor to that position). Similarly, the menu command <menuchoice><guimenu>Go</guimenu><guimenuitem>Next Position</guimenuitem></menuchoice> selects the position record immediately above the current one in the active history page, and moves the editing cursor to the appropriate location.
</para>

<para>
In addition to these commands, any position recorded in a history list can be accessed directly, by selecting the relevant item in the list (either by double-clicking the item, or by highlighting it and pressing the <keycap>Enter</keycap> key. This action can be applied to any history list, and not just to the active one.
</para>

<note>
<para>
Selecting a history record from a non-active list will add the selected item to the top of the active list, similar to a jump from a query result page.
</para>
</note>

</sect2>

<sect2 id="pos-hist-multi">
<title>Using Multiple Histories</title>

<para>
The position history is a dynamic object, which changes as the user navigates through the code. In some cases, however, it is convenient to create a snapshot of a tour through the code, and keep it for later reference. &kapp; provides this feature through the availability of multiple history pages.
</para>

<para>
As mentioned earlier, a history page is created automatically for a project when the first jump through the code is made. This page is considered as the active history page, which means that locations are added to this page, and that all navigational commands apply to the list contained in it.
</para>

<para>
The user can decide to freeze the contents of the history recorded by the current page. This is done by locking the page, in a way similar to locking query results (see <link linkend="query-window">The Query Window</link>). Once the page is locked, its contents remain the same, even if jumps are made to other locations in the code. To record any successive jumps, &kapp; creates a new history page, which becomes the active one. A locked history page can also be activated by unlocking it. However, there can only be one unlocked history page at any given time (the active one), which means that unlocking one history page locks the previously unlocked one.
</para>

<para>
Navigational commands (<menuchoice><guimenu>Go</guimenu><guimenuitem>Next Position</guimenuitem></menuchoice> and <menuchoice><guimenu>Go</guimenu><guimenuitem>Previous Position</guimenuitem></menuchoice>) always apply to the active history page. This is usually the unlocked history page, but may also be a locked one. This happens after the active page is locked, and before a new page is created due to a jump in the code. Other locked pages can still be used by manually selecting location records from these pages. Such a selection will move the editing cursor to the appropriate location, and hence add an entry in the active history page.
</para>

<para>
As with query pages, locked history pages are saved when a project is closed, and restored when it is opened.
</para>

</sect2>

</sect1>

</chapter>

<chapter id="configuration">
<title>Configuring &kapp;</title>

<sect1 id="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="config-progs">
<title>The Programmes Page</title>

<para>
&kapp; serves as a front-end to several console-based programmes: <application>Cscope</application>, <application>Ctags</application> and <application>Dot</application> (which is part of the <application>Graphviz</application> suite). 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 the relevant executable files 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>
The easiest way to configure programme paths is by using the automated script provided with &kapp;. This script can be activated by clicking the <guibutton>Guess...</guibutton> button. Once invoked, the script looks for the required programmes (using the shell's <filename>which</filename> utility). The script also makes sure that the found executables adhere to the standards required by &kapp; (e.g., that <application>Ctags</application> is the one provided by <application>Exuberant-Ctags</application> and that <application>Dot</application> supports the <option>-Tplain</option> command-line option). &kapp; uses the results of the script to adjust the values in the dialogue's controls.
</para>

<note>
<para>The script will not override paths already set by the user. Instead, it will only verify the validity of these paths. For the script to determine paths automatically, the relevant text fields in the dialogue need to be cleared.</para>
</note>

<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>
<varlistentry>
<term><guilabel>Dot Path</guilabel></term>
<listitem><para>The full path of the Dot executable. The name of this executable must be <filename>dot</filename>.</para></listitem>
</varlistentry>
<varlistentry>
<term><guibutton>Guess</guibutton></term>
<listitem><para><action>Runs a script which attempts to determine the previous values automatically.</action> This script should work in most cases, by may fail to correctly obtain some or all the values.</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="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 some of &kapp;'s GUI elements. The elements 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>
<listitem><para>The call graph's background and nodes</para></listitem>
</itemizedlist>
</para>

<para>
To change the colour of a GUI element, double-click over the element's entry in the list (or select this element and click <keycap>Enter</keycap>).
</para>

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

</sect2>

<sect2 id="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="config-clrs">The Colours Page</link> section for a description of these windows.)
</para>

<para>
To change the colour of a GUI element, double-click over the element's entry in the list (or select this element and click <keycap>Enter</keycap>).
</para>

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

</sect2>

<sect2 id="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>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.</para></listitem>
</varlistentry>
<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 (but you can still use the external editor).</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Open Last Project on Start-Up</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>
<varlistentry>
<term><guilabel>B