index.docbook

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

<?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>[e-mail]</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>12/04/2006</date>
<releaseinfo>1.4.0</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 to or called by a function;</para></listitem>
<listitem><para>Find a text string or an 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="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="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 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.
</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 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">
<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-type" 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>