&kapp; is a TDE-based source-editing environment for C and C-style languages. 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, multiple query result windows, call trees and graphs, and more.
&tdeApp; is a TDE-based source-editing environment for C and C-style languages. 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. &tdeApp; extends the feature-set of <application>Cscope</application> with a contemporary user interface, editor integration, project management capabilities, multiple query result windows, call trees and graphs, and more.
</para>
<para>
&kapp; implements (almost) all of <application>Cscope</application>'s query types. Among these are:
&tdeApp; 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>
@ -17,15 +17,15 @@
</para>
<para>
The main purpose of &kapp; is to provide developers with a rich environment for code editing and analysis. It is specifically geared towards large projects, with thousands of source files and millions of lines of code. Many traditional C/C++ IDEs do not scale well to handle projects of this magnitude, either because they do not provide adequate tools for understanding the code base, or because they are unable to efficiently digest that much information. By using <application>Cscope</application> as its underlying engine, &kapp; can easily handle projects such as the <ulink url="http://www.kernel.org">Linux kernel</ulink>, <ulink url="http://www.winehq.org">WINE</ulink>, <ulink url="http://www.postgresql.org">PostgreSQL</ulink>, etc.
The main purpose of &tdeApp; is to provide developers with a rich environment for code editing and analysis. It is specifically geared towards large projects, with thousands of source files and millions of lines of code. Many traditional C/C++ IDEs do not scale well to handle projects of this magnitude, either because they do not provide adequate tools for understanding the code base, or because they are unable to efficiently digest that much information. By using <application>Cscope</application> as its underlying engine, &tdeApp; can easily handle projects such as the <ulink url="http://www.kernel.org">Linux kernel</ulink>, <ulink url="http://www.winehq.org">WINE</ulink>, <ulink url="http://www.postgresql.org">PostgreSQL</ulink>, etc.
</para>
<note><para>
It has been reported by some users that &kapp; can be successfully used for C++ development. Nonetheless, &kapp; is mainly a tool for developing in pure C (either ANSI or K&R style). Most C++ features will not be recognised by the cross-reference generator.
It has been reported by some users that &tdeApp; can be successfully used for C++ development. Nonetheless, &tdeApp; is mainly a tool for developing in pure C (either ANSI or K&R style). Most C++ features will not be recognised by the cross-reference generator.
</para></note>
<para>
&kapp; is a part of an ongoing effort to expand the range of open source applications. 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.
&tdeApp; is a part of an ongoing effort to expand the range of open source applications. It could not have been created without the previous work of many devoted developers. &tdeApp; 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.
Bookmarks provide an easy way to navigate through a defined set of positions in the source code. Most editors support the concept of bookmarks as tags attached to lines in a source file. &kapp; can enhance the usablity of per-file markers by enabling users to access the bookmarks currently defined in all open files. &kapp; also saves and restores these bookmarks as part of its session-management services.
Bookmarks provide an easy way to navigate through a defined set of positions in the source code. Most editors support the concept of bookmarks as tags attached to lines in a source file. &tdeApp; can enhance the usablity of per-file markers by enabling users to access the bookmarks currently defined in all open files. &tdeApp; also saves and restores these bookmarks as part of its session-management services.
</para>
<para>
The <guilabel>Bookmarks</guilabel> dialogue is invoked by the <menuchoice><guimenu>Go</guimenu><guimenuitem>Global Bookmarks</guimenuitem></menuchoice> menu command. Once open, it displays the set bookmarks among all currently-open files. This includes the file path, the source line and the line's text (similar to other source views available in &kapp;).
The <guilabel>Bookmarks</guilabel> dialogue is invoked by the <menuchoice><guimenu>Go</guimenu><guimenuitem>Global Bookmarks</guimenuitem></menuchoice> menu command. Once open, it displays the set bookmarks among all currently-open files. This includes the file path, the source line and the line's text (similar to other source views available in &tdeApp;).
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.
The configuration dialogue is the main tool for setting parameters required by &tdeApp;, or adjusting the user's preferences. The dialogue is displayed the first time &tdeApp; is run, and can be invoked later by using the <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure KScope...</guimenuitem></menuchoice> menu command.
</para>
<para>
@ -13,11 +13,11 @@ The dialogue is composed of several pages, each of which handles a different set
<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.
&tdeApp; 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 &tdeApp; invokes these programmes directly, without using a shell, it cannot determine their paths. Therefore, it is required to inform &tdeApp; of the paths where the relevant executable files reside. Note that &tdeApp; 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.
Another parameter required by &tdeApp; 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 &tdeApp; 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 &tdeApp; 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>
@ -25,7 +25,7 @@ You can determine whether your version of <application>Cscope</application> supp
</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.
The easiest way to configure programme paths is by using the automated script provided with &tdeApp;. 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 &tdeApp; (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). &tdeApp; uses the results of the script to adjust the values in the dialogue's controls.
</para>
<note>
@ -88,7 +88,7 @@ If the file names on your system do not conform to the limitations described abo
</mediaobject>
</screenshot>
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:
The Colours page allows you to configure &tdeApp; to look the way you want it to, by changing the foreground and background colours of some of &tdeApp;'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>
@ -102,7 +102,7 @@ To change the colour of a GUI element, double-click over the element's entry in
</para>
<note>
<para>The editor's own colours are determined by the settings of the embedded editor, and are not controlled by &kapp;.</para>
<para>The editor's own colours are determined by the settings of the embedded editor, and are not controlled by &tdeApp;.</para>
</note>
</sect2>
@ -123,7 +123,7 @@ To change the colour of a GUI element, double-click over the element's entry in
</mediaobject>
</screenshot>
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.)
The Fonts page allows you to determine the fonts used by any of &tdeApp;'s windows (see <link linkend="config-clrs">The Colours Page</link> section for a description of these windows.)
</para>
<para>
@ -131,7 +131,7 @@ To change the colour of a GUI element, double-click over the element's entry in
</para>
<note>
<para>As with the colour scheme, the fonts used by the embedded editor are not determined by &kapp;.</para>
<para>As with the colour scheme, the fonts used by the embedded editor are not determined by &tdeApp;.</para>
</note>
</sect2>
@ -140,7 +140,7 @@ To change the colour of a GUI element, double-click over the element's entry in
<title>The Options Page</title>
<para>
This page allows the user to configure certain parameters that affect the behaviour of &kapp;.
This page allows the user to configure certain parameters that affect the behaviour of &tdeApp;.
</para>
<para>
@ -158,42 +158,42 @@ This page allows the user to configure certain parameters that affect the behavi
<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>
<listitem><para>Specifies a command line for invoking an external editor application. &tdeApp; 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>
<listitem><para>If set, the embedded editor will be work in read-only mode, i.e., &tdeApp; 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>
<listitem><para>Determines whether &tdeApp; 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>
<listitem><para>If set, &tdeApp; will highlight tags in the tag list based on the current position of the text cursor.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Brief Tab Captions for Query Pages</guilabel></term>
<listitem><para>This option allows some space to be saved by using shortcuts for the page titles in the query window.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Warn When a File is Modified Outside &kapp;</guilabel></term>
<listitem><para>If set, &kapp; will issue a warning whenever a file is changed on the hard drive, while it is open for editing in &kapp;. This option will only work in conjunction with the Kate text editor).</para></listitem>
<term><guilabel>Warn When a File is Modified Outside &tdeApp;</guilabel></term>
<listitem><para>If set, &tdeApp; will issue a warning whenever a file is changed on the hard drive, while it is open for editing in &tdeApp;. This option will only work in conjunction with the Kate text editor).</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Automatically Sort Files in the File List</guilabel></term>
<listitem><para>By default, &kapp; will sort the files in the project's file list whenever a project is loaded. However, such behaviour may not be suitable for large projects on older machines, causing &kapp; to hang for long periods when loading such projects. Uncheck this option to avoid automatic sorting.</para></listitem>
<listitem><para>By default, &tdeApp; will sort the files in the project's file list whenever a project is loaded. However, such behaviour may not be suitable for large projects on older machines, causing &tdeApp; to hang for long periods when loading such projects. Uncheck this option to avoid automatic sorting.</para></listitem>
</varlistentry>
<varlistentry>
<term><guilabel>System Profile</guilabel></term>
<listitem><para>Allows the choice between a fast and a slow system configuration. The fast profile will take certain actions automatically which are not appropriate for a slower system (for example, automatic database rebuilds and auto-completion are enabled by default for fast systems and disabled for slow systems). Note that the terms "fast" and "slow" do not necessarily refer to the particular machine which runs &kapp;, but rather to the complete environment (e.g., a fast machine may still be using a relatively slow file server).</para></listitem>
<listitem><para>Allows the choice between a fast and a slow system configuration. The fast profile will take certain actions automatically which are not appropriate for a slower system (for example, automatic database rebuilds and auto-completion are enabled by default for fast systems and disabled for slow systems). Note that the terms "fast" and "slow" do not necessarily refer to the particular machine which runs &tdeApp;, but rather to the complete environment (e.g., a fast machine may still be using a relatively slow file server).</para></listitem>
&kapp; does not provide its own editor. Instead, it utilises TDE'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 TDE's control centre.
&tdeApp; does not provide its own editor. Instead, it utilises TDE'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 &tdeApp;. The editor is defined in TDE's control centre.
</para>
<para>
In any matter related to operating or configuring the editor, please refer to the manual of the editor itself.
@ -17,7 +17,7 @@ In any matter related to operating or configuring the editor, please refer to th
<title>Opening Files for Editing</title>
<para>
Files are usually opened for editing as 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.
Files are usually opened for editing as part of a project. However, &tdeApp; 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>
@ -35,11 +35,11 @@ To decrease the loading time of projects, files and directories are only added t
</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.
For each file opened, &tdeApp; creates a separate editor window, inside the editing area. Each editor is associated with a tab, displaying the name of the edited file. Thus &tdeApp; 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.
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, &tdeApp; 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>
@ -48,7 +48,7 @@ To work on a new file, the user first needs to create it using the <menuchoice><
<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.
In addition to being a front-end to <application>Cscope</application>, &tdeApp; 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>
@ -65,7 +65,7 @@ By default, tags are sorted by to their name in ascending order. Click on a colu
<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.)
&tdeApp;'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>
@ -76,14 +76,14 @@ By default, tags are sorted by to their name in ascending order. Click on a colu
<para>
Symbol completion is a convenient 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 conveniently, 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.
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 conveniently, by pressing <keycombo><keycap>Ctrl</keycap><keycap>Space</keycap></keycombo>). Once a completion request has been issued, &tdeApp; 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="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.
In addition to manual symbol completion, &tdeApp; can also provide automatic completion based on changes made by the user to the edited source code. Specifically, &tdeApp; 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>
@ -97,7 +97,7 @@ For performance reasons, it is highly recommended that automatic symbol completi
</note>
<para>
As mentioned above, &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.
As mentioned above, &tdeApp; 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.
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.
This section describes the menu entries declared by &tdeApp; 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>
@ -48,12 +48,12 @@ This section describes the menu entries declared by &kapp; only. Additional entr
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.
Other file operations such as <guimenuitem>Save</guimenuitem> and <guimenuitem>Print</guimenuitem> are not integral &tdeApp; actions, but are rather defined by the type of editor used.
</para>
</sect2>
@ -445,14 +445,14 @@ file name will make its editor window active.
<guimenu>Settings</guimenu>
<guimenuitem>Configure Shortcuts...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Allows the user to assign different shortcuts to &kapp; commands.</action></para></listitem>
<listitem><para><action>Allows the user to assign different shortcuts to &tdeApp; commands.</action></para></listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu>Settings</guimenu>
<guimenuitem>Configure KScope...</guimenuitem>
</menuchoice></term>
<listitem><para><action>Displays the &kapp; configuration dialogue</action></para></listitem>
<listitem><para><action>Displays the &tdeApp; configuration dialogue</action></para></listitem>
&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 source file being viewed or edited. 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.
&tdeApp;'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 source file being viewed or edited. 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.
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.
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 &tdeApp; is closed.
In its capacity as a source code browser, &kapp; allows the user to quickly browse through different lines in the code base. We refer to a combination of a source file and a line number as a "position" in the project. While browsing the code, it is often required to go back to a position visited in the past, e.g., to return to the caller after visiting the callee. To achieve this task, &kapp; provides a sophisticated position history mechanism, which not only allows the user to go back and forth between visited locations, but also to save and restore snapshots of "tours" through the code, as well as other manipulations of the position history. For the sake of both consistency and ease of use, recorded position history is viewed and handled in a way similar to the query results system.
In its capacity as a source code browser, &tdeApp; allows the user to quickly browse through different lines in the code base. We refer to a combination of a source file and a line number as a "position" in the project. While browsing the code, it is often required to go back to a position visited in the past, e.g., to return to the caller after visiting the callee. To achieve this task, &tdeApp; provides a sophisticated position history mechanism, which not only allows the user to go back and forth between visited locations, but also to save and restore snapshots of "tours" through the code, as well as other manipulations of the position history. For the sake of both consistency and ease of use, recorded position history is viewed and handled in a way similar to the query results system.
</para>
<note>
<para>
In the context of this section, a "jump" is defined as the action taken by &kapp; after a query result record is selected for viewing (either by the user from a query page or a call-tree window, or automatically).
In the context of this section, a "jump" is defined as the action taken by &tdeApp; after a query result record is selected for viewing (either by the user from a query page or a call-tree window, or automatically).
</para>
</note>
@ -77,7 +77,7 @@ Selecting a history record from a non-active list will add the selected item to
<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.
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. &tdeApp; provides this feature through the availability of multiple history pages.
</para>
<para>
@ -85,7 +85,7 @@ As mentioned earlier, a history page is created automatically for a project when
</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.
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, &tdeApp; 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.
Before any significant work can be done with &kapp;, the user needs 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 environments, &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.
Before any significant work can be done with &tdeApp;, the user needs to define a project. A &tdeApp; project is a set of source files, which <application>Cscope</application> uses to create its cross-reference database. Unlike many other project-based environments, &tdeApp; 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, &tdeApp; 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:
The files used by a &tdeApp; project are:
<variablelist>
<varlistentry>
<term><filename>cscope.proj</filename></term>
@ -31,7 +31,7 @@ The files used by a &kapp; project are:
</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 her 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.
The only limitation imposed by &tdeApp; 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 her 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="project-create">
@ -66,11 +66,11 @@ Note that this dialogue is intended for creating an empty project only, and has
</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>
<listitem><para>The full path of the directory under which the new project will be created. &tdeApp; 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>
<listitem><para>The top-level directory that contains the source files to be included in the project. This path only serves as a hint to &kapp;, as files may later be added from different directories as well By default, this value is set to the root directory.</para></listitem>
<listitem><para>The top-level directory that contains the source files to be included in the project. This path only serves as a hint to &tdeApp;, as files may later be added from different directories as well By default, this value is set to the root directory.</para></listitem>
</varlistentry>
</variablelist>
</sect3>
@ -144,7 +144,7 @@ Note that this dialogue is intended for creating an empty project only, and has
<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>
<listitem><para>&tdeApp; 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>
@ -260,7 +260,7 @@ The project's list of source files is maintained by the <guilabel>Project Files<
<para>
Once the list of project files changes (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.
Once the list of project files changes (either when files are first added to the project, or upon any subsequent modification), &tdeApp; informs <application>Cscope</application> to rebuild the cross-reference database.
</para>
</sect2>
@ -312,7 +312,7 @@ When a project is closed, it saves session information, such as source files bei
</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 changed, <application>Cscope</application> will rebuild the cross-reference database.
After the project has been opened, &tdeApp; 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 changed, <application>Cscope</application> will rebuild the cross-reference database.
</para>
</sect2>
@ -338,11 +338,11 @@ Temporary projects are created when a user opens a cscope.out file directly. Thi
</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.
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, &tdeApp; 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 &tdeApp;'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>.
Note, however, that most project management options provided by &tdeApp; 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. &tdeApp;'s rebuild command assumes the database has been updated, and only re-runs <application>Cscope</application>.
</para>
</sect2>
@ -351,7 +351,7 @@ Note, however, that most project management options provided by &kapp; will not
<title>Building Projects</title>
<para>
While &kapp; was not designed as an IDE with a complete write-build-debug cycle, it does provide a simple GUI for building projects. The command <menuchoice><guimenu>Project</guimenu><guimenuitem>Make Project</guimenuitem></menuchoice> displays a dialogue, which can be used to invoke any external tool on a given directory. By default, it runs <command>make</command> on the project's source root. The output of the command will be displayed in the dialogue's <guilabel>Output</guilabel> pane, with any errors or warnings marked-up, similar to links in a browser. Clicking on a link will jump to an editor page showing the source file and line responsible for the message. A list of all abnormal messages also appears in the dialogue's <guilabel>Errors and Warnings</guilabel> pane.
While &tdeApp; was not designed as an IDE with a complete write-build-debug cycle, it does provide a simple GUI for building projects. The command <menuchoice><guimenu>Project</guimenu><guimenuitem>Make Project</guimenuitem></menuchoice> displays a dialogue, which can be used to invoke any external tool on a given directory. By default, it runs <command>make</command> on the project's source root. The output of the command will be displayed in the dialogue's <guilabel>Output</guilabel> pane, with any errors or warnings marked-up, similar to links in a browser. Clicking on a link will jump to an editor page showing the source file and line responsible for the message. A list of all abnormal messages also appears in the dialogue's <guilabel>Errors and Warnings</guilabel> pane.
The most important task of &kapp; is to execute <application>Cscope</application> queries and display their results. Queries are always performed on the cross-reference database of the active project.
The most important task of &tdeApp; is to execute <application>Cscope</application> queries and display their results. Queries are always performed on the cross-reference database of the active project.
</para>
<para>
&kapp; currently supports the following query types:
&tdeApp; 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>
@ -22,11 +22,11 @@ A symbol, as referred to in the above list, may be a function, a global variable
</para>
<para>
The cross-reference database may become obsolete when source files are modified, resulting in inaccurate (or simply wrong) query results. &kapp; has two ways for refreshing the database, manual and automatic. Manual database rebuilds are available through the <menuchoice><guimenu>Cscope</guimenu><guimenuitem>Rebuild Database</guimenuitem></menuchoice> menu command. Selecting this command will instruct Cscope to immediately rebuild the cross-reference database.
The cross-reference database may become obsolete when source files are modified, resulting in inaccurate (or simply wrong) query results. &tdeApp; has two ways for refreshing the database, manual and automatic. Manual database rebuilds are available through the <menuchoice><guimenu>Cscope</guimenu><guimenuitem>Rebuild Database</guimenuitem></menuchoice> menu command. Selecting this command will instruct Cscope to immediately rebuild the cross-reference database.
</para>
<para>
Automatic database rebuilds are enabled per-project, an option controlled by the <guilabel>Project Properties</guilabel> dialogue. Since a database rebuild may be a time and resource-consuming operation, &kapp; does not invoke this procedure after every change to the source code. Instead, changes to the code initiate a timer (whose value is determined by the user in the <guilabel>Project Properties</guilabel> dialogue). Once this timer elapses, &kapp; instructs Cscope to rebuild the database. Code modifications that occur while the timer is running reset its value.
Automatic database rebuilds are enabled per-project, an option controlled by the <guilabel>Project Properties</guilabel> dialogue. Since a database rebuild may be a time and resource-consuming operation, &tdeApp; does not invoke this procedure after every change to the source code. Instead, changes to the code initiate a timer (whose value is determined by the user in the <guilabel>Project Properties</guilabel> dialogue). Once this timer elapses, &tdeApp; instructs Cscope to rebuild the database. Code modifications that occur while the timer is running reset its value.
</para>
<para>
@ -108,7 +108,7 @@ Any text selected in the editor when a query is requested will be automatically
</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.
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 &tdeApp;). 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>
@ -122,7 +122,7 @@ The third way of starting a query is by right-clicking inside an editor window.
</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="configuration">Configuring &kapp;</link> for more information.
A query may take some time to complete, depending on its type and the size of the project. &tdeApp; 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), &tdeApp; will present a dummy progress bar, used simply to indicate that a query is running, and that &tdeApp; has not frozen. Please refer to the section <link linkend="configuration">Configuring &tdeApp;</link> for more information.
</para>
</sect2>
@ -131,7 +131,7 @@ A query may take some time to complete, depending on its type and the size of th
<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.
When a query has terminated, its output is displayed in the query window, at the bottom of &tdeApp;'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>
@ -157,7 +157,7 @@ By default, results are sorted according to the file name. This can be changed b
</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.
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, &tdeApp; 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>
@ -237,7 +237,7 @@ Right-clicking a query result in either a query window or a call-tree dialogue d
<title>Filtering Query Results</title>
<para>
It is often the case the a query results in an abundance of information. &kapp; allows the user to filter query results in order to show only those results that the user finds interesting, an action referred to as "Filtering". Filtering is done by matching patterns on any of the query record fields (file name, function, line number and line text).
It is often the case the a query results in an abundance of information. &tdeApp; allows the user to filter query results in order to show only those results that the user finds interesting, an action referred to as "Filtering". Filtering is done by matching patterns on any of the query record fields (file name, function, line number and line text).
</para>
<para>
@ -300,7 +300,7 @@ The Filter Query Results dialogue is invoked from the query context menu (see <l
<title>Displaying Call-Trees and Graphs</title>
<para>
Tracing a sequence of calls in the code base is a common task in code analysis. To facilitate this task, &kapp; offers two mechanisms for visualising the relationships between different functions in a project: the Call-Tree and the Call-Graph. Both of these mechanisms are provided through the <guilabel>Call Graph Dialogue</guilabel> which can be invoked on a function name in a similar way to a regular <application>Cscope</application> query.
Tracing a sequence of calls in the code base is a common task in code analysis. To facilitate this task, &tdeApp; offers two mechanisms for visualising the relationships between different functions in a project: the Call-Tree and the Call-Graph. Both of these mechanisms are provided through the <guilabel>Call Graph Dialogue</guilabel> which can be invoked on a function name in a similar way to a regular <application>Cscope</application> query.
This section provides information for the impatient user who would like to start using &kapp; right away. While using &kapp; should be straight-forward for anyone who has ever used similar tools in the past, and is familiar with TDE applications, there are, nonetheless, some points that require attention. Even if you do not have the time or patience to browse through this entire manual, please make sure to read at least this section.
This section provides information for the impatient user who would like to start using &tdeApp; right away. While using &tdeApp; should be straight-forward for anyone who has ever used similar tools in the past, and is familiar with TDE applications, there are, nonetheless, some points that require attention. Even if you do not have the time or patience to browse through this entire manual, please make sure to read at least this section.
</para>
<sect2>
<title>Configure Paths</title>
<para>
&kapp; needs to be informed of the absolute paths to several executables, including <application>Cscope</application>, <application>Ctags</application> and (optionally) <application>Dot</application>. These can be configured in the <guilabel>Programmes</guilabel> page of the main configuration dialogue. See <link linkend="config-dlg">The Configuration Dialogue</link> section for more information.
<warning><para>&kapp; will not work properly if these paths are not configured correctly!</para></warning>
&tdeApp; needs to be informed of the absolute paths to several executables, including <application>Cscope</application>, <application>Ctags</application> and (optionally) <application>Dot</application>. These can be configured in the <guilabel>Programmes</guilabel> page of the main configuration dialogue. See <link linkend="config-dlg">The Configuration Dialogue</link> section for more information.
<warning><para>&tdeApp; will not work properly if these paths are not configured correctly!</para></warning>
</para>
</sect2>
@ -18,7 +18,7 @@ This section provides information for the impatient user who would like to start
<title>Create a Project</title>
<para>
While &kapp; can be used to edit individual files, most of its browsing, analysis and editing features will not be available outside of a project. A project is a set of source files for which &kapp; creates a cross-reference database, the key to most of &kapp;'s capabilities. See <link linkend="project-create">Creating a New Project</link> for detailed instructions.
While &tdeApp; can be used to edit individual files, most of its browsing, analysis and editing features will not be available outside of a project. A project is a set of source files for which &tdeApp; creates a cross-reference database, the key to most of &tdeApp;'s capabilities. See <link linkend="project-create">Creating a New Project</link> for detailed instructions.
</para>
</sect2>
@ -34,7 +34,7 @@ As mentioned above, a project is associated with a set of source files. These ne
<title>Browse and Edit Files</title>
<para>
Once a project has been defined, &kapp; is ready for use. You can now open files for viewing and editing, and use the query system for browsing and analysing the project's code base. See the rest of this manual for more information.
Once a project has been defined, &tdeApp; is ready for use. You can now open files for viewing and editing, and use the query system for browsing and analysing the project's code base. See the rest of this manual for more information.
