diff options
Diffstat (limited to 'doc')
30 files changed, 2047 insertions, 0 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 0000000..7e7a4a8 --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,6 @@ +# the SUBDIRS is filled automatically by am_edit. If files are +# in this directory they are installed into the english dir + +KDE_LANG = en +KDE_DOCS = kscope +SUBDIRS = $(AUTODIRS) diff --git a/doc/en/Makefile.am b/doc/en/Makefile.am new file mode 100644 index 0000000..fef2a0a --- /dev/null +++ b/doc/en/Makefile.am @@ -0,0 +1,5 @@ +KDE_DOCS = kscope +KDE_LANG = en +kde_docs_KDEDOCS = call_tree.png main_window.png pref.png project_files.png \ + project_new.png project_open.png query_dlg.png autocomp_dlg.png query_filter.png \ + call_graph.png diff --git a/doc/en/about.docbook b/doc/en/about.docbook new file mode 100644 index 0000000..1bb7173 --- /dev/null +++ b/doc/en/about.docbook @@ -0,0 +1,31 @@ +<sect1 id="about"> +<title>About &kapp;</title> + +<para> +&kapp; is a KDE-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. +</para> + +<para> +&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> +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. +</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. +</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. +</para> + +</sect1> diff --git a/doc/en/autocomp_dlg.png b/doc/en/autocomp_dlg.png Binary files differnew file mode 100644 index 0000000..21d39e4 --- /dev/null +++ b/doc/en/autocomp_dlg.png diff --git a/doc/en/bookmarks.docbook b/doc/en/bookmarks.docbook new file mode 100644 index 0000000..8607645 --- /dev/null +++ b/doc/en/bookmarks.docbook @@ -0,0 +1,28 @@ +<sect1 id="bookmarks"> +<title>Bookmarks</title> + +<para> +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. +</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;). +</para> + +<screenshot> +<screeninfo>The Bookmarks dialogue</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="bookmarks.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The Bookmarks dialogue</phrase> +</textobject> +</mediaobject> +</screenshot> + +<para> +Navigating to a defined bookmark can be done by either double-clicking an entry in the dialogue, or by choosing the <menuchoice><guimenuitem>View Source</guimenuitem></menuchoice> item from the context menu (available by right-clicking over a bookmark entry). Other choices presented by the context menu include <menuchoice><guimenuitem>Copy [FIELD]</guimenuitem></menuchoice> for copying the contents of the current field to the clipboard, <menuchoice><guimenuitem>Filter...</guimenuitem></menuchoice> for selecting entries based on some criteria, <menuchoice><guimenuitem>Show All</guimenuitem></menuchoice> for removing all filters and <menuchoice><guimenuitem>Remove Item</guimenuitem></menuchoice> for deleting the bookmark. +</para> + +</sect1>
\ No newline at end of file diff --git a/doc/en/bookmarks.png b/doc/en/bookmarks.png Binary files differnew file mode 100644 index 0000000..2f20be7 --- /dev/null +++ b/doc/en/bookmarks.png diff --git a/doc/en/call_graph.png b/doc/en/call_graph.png Binary files differnew file mode 100644 index 0000000..719f3f7 --- /dev/null +++ b/doc/en/call_graph.png diff --git a/doc/en/call_tree.png b/doc/en/call_tree.png Binary files differnew file mode 100644 index 0000000..010be6c --- /dev/null +++ b/doc/en/call_tree.png diff --git a/doc/en/config_dlg.docbook b/doc/en/config_dlg.docbook new file mode 100644 index 0000000..ba2fed3 --- /dev/null +++ b/doc/en/config_dlg.docbook @@ -0,0 +1,206 @@ +<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="pref_progs.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 of 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> +<screenshot> +<screeninfo>The Colours page</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="pref_clrs.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The Colours page</phrase> +</textobject> +</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: +<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> +<screenshot> +<screeninfo>The Fonts page</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="pref_fonts.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The Fonts page</phrase> +</textobject> +</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.) +</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="pref_opts.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>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> +</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> +</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> +</varlistentry> +<varlistentry> +<term><guilabel>Editor Popup Menu</guilabel></term> +<listitem><para>Provides two choices for the embedded editor's context menu: +<itemizedlist> +<listitem><para>Embedded: A menu with Cscope actions is included as a sub-menu of the editor's own context menu.</para></listitem> +<listitem><para>&kapp; Only: Only Cscope actions are available through the context menu.</para></listitem> +</itemizedlist> +The second choice provides quicker access to Cscope commands, but the editor's menu is discarded. +</para></listitem> +</varlistentry> +</variablelist> +</para> + +</sect2> + +</sect1> diff --git a/doc/en/editing.docbook b/doc/en/editing.docbook new file mode 100644 index 0000000..2aeeece --- /dev/null +++ b/doc/en/editing.docbook @@ -0,0 +1,138 @@ +<sect1 id="editing"> +<title>Editing Source Files</title> + +<sect2 id="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. +</para> +<para> +In any matter related to operating or configuring the editor, please refer to the manual of the editor itself. +</para> + +</sect2> + +<sect2 id="open-file"> +<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. +</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="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="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="symbol-completion"> +<title>Symbol Completion</title> + +<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. +</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. +</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 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. + +<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> diff --git a/doc/en/index.docbook b/doc/en/index.docbook new file mode 100644 index 0000000..705988d --- /dev/null +++ b/doc/en/index.docbook @@ -0,0 +1,174 @@ +<?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 about SYSTEM "about.docbook"> + <!ENTITY quick-start SYSTEM "quick_start.docbook"> + <!ENTITY main-window SYSTEM "main_window.docbook"> + <!ENTITY projects SYSTEM "projects.docbook"> + <!ENTITY editing SYSTEM "editing.docbook"> + <!ENTITY query-system SYSTEM "query_system.docbook"> + <!ENTITY position-history SYSTEM "pos_history.docbook"> + <!ENTITY bookmarks SYSTEM "bookmarks.docbook"> + <!ENTITY config-dlg SYSTEM "config_dlg.docbook"> + <!ENTITY main-menu SYSTEM "main_menu.docbook"> + <!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>[email protected]</email></address> +</affiliation> +</author> +</authorgroup> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> + +<copyright> +<year>2003-2007</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>08/07/2007</date> +<releaseinfo>1.6.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> + +&about; +&quick-start; + +</chapter> + +<chapter id="using-kscope"> +<title>Using &kapp;</title> + +&main-window; +&projects; +&editing; +&query-system; +&position-history; +&bookmarks; + +</chapter> + +<chapter id="configuration"> +<title>Configuring &kapp;</title> + +&config-dlg; + +</chapter> + +<chapter id="commands"> +<title>Command Reference</title> + +&main-menu; + +</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-2007 Elad Lahav <email>[email protected]</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 2007-2006 Elad Lahav <email>[email protected]</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) --> + +&underBSDLicense; <!-- BSD License --> + +</chapter> + +</book> diff --git a/doc/en/main_menu.docbook b/doc/en/main_menu.docbook new file mode 100644 index 0000000..18a4d2b --- /dev/null +++ b/doc/en/main_menu.docbook @@ -0,0 +1,465 @@ +<sect1 id="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> </para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo><keycap>Ctrl</keycap><keycap>Shift</keycap><keycap>T</keycap></keycombo> +</shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Go To Tag</guimenuitem> +</menuchoice></term> +<listitem><para><action>Moves the cursor to the tag list</action>, used for browsing through the file's tags</para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo><keycap>Ctrl</keycap><keycap>Space</keycap></keycombo> +</shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Complete Symbol</guimenuitem> +</menuchoice></term> +<listitem><para><action>Generates a list of possible symbol completions for the text to the left of the cursor.</action> Note that this option is available even if automatic completion is disabled.</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>Toggle 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>Toggle Query Window</guimenuitem> +</menuchoice></term> +<listitem><para><action>Shows or hides the query window.</action></para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo><keycap>Ctrl</keycap><keycap>.</keycap></keycombo> +</shortcut> +<guimenu>View</guimenu> +<guimenuitem>Toggle Tag List</guimenuitem> +</menuchoice></term> +<listitem><para><action>Shows or hides the tag lists attached to the editor windows.</action></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>Open Cscope.out...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Prompts for an existing Cscope.out</action>, which can be opened as a temporary project.</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> +<shortcut> +<keycombo><keycap>Ctrl</keycap><keycap>M</keycap></keycombo> +</shortcut> +<guimenu>Project</guimenu> +<guimenuitem>Make Project...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Displays the Build dialogue.</action></para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo><keycap>Ctrl</keycap><keycap>Shift</keycap><keycap>M</keycap></keycombo> +</shortcut> +<guimenu>Project</guimenu> +<guimenuitem>Remake Project</guimenuitem> +</menuchoice></term> +<listitem><para><action>Displays the Build dialogue and executes the last build command.</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> +<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> +<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>Finds the global definition of the symbol currently under the cursor.</action> The symbol dialogue appears only if a symbol cannot be determined automatically.</para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo><keycap>Ctrl</keycap><keycap>\</keycap></keycombo> +</shortcut> +<guimenu>Cscope</guimenu> +<guimenuitem>Call Graph...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Displays a call-graph and/or a call-tree for a given function</action></para></listitem> +</varlistentry> +</variablelist> +</para> + +</sect2> + +<sect2> +<title>The Go Menu</title> + +<para> +<variablelist> +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo><keycap>Alt</keycap><keycap>Up Arrow</keycap></keycombo> +</shortcut> +<guimenu>Go</guimenu> +<guimenuitem>Previous Result</guimenuitem> +</menuchoice></term> +<listitem><para><action>Selects the previous result in the current query window.</action></para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo><keycap>Alt</keycap><keycap>Down Arrow</keycap></keycombo> +</shortcut> +<guimenu>Go</guimenu> +<guimenuitem>Next Result</guimenuitem> +</menuchoice></term> +<listitem><para><action>Selects the next result in the current query window.</action></para></listitem> +</varlistentry> +<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>Jumps to the previous stored position in the active 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>Jumps to the next stored position in the active history list.</action></para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo><keycap>Ctrl</keycap><keycap>H</keycap></keycombo> +</shortcut> +<guimenu>Go</guimenu> +<guimenuitem>Position History...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Selects the active position history page in the query window.</action> If the query window is hidden, it becomes visible. </para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo><keycap>Ctrl</keycap><keycap>Shift</keycap><keycap>G</keycap></keycombo> +</shortcut> +<guimenu>Go</guimenu> +<guimenuitem>Global Bookmarks...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Displays the Bookmarks dialogue.</action></para></listitem> +</varlistentry> +</variablelist> +</para> + +</sect2> + +<sect2> +<title>The Window Menu</title> + +<para> +<variablelist> +<varlistentry> +<term><menuchoice> +<guimenu>Window</guimenu> +<guimenuitem>Close All</guimenuitem> +</menuchoice></term> +<listitem><para><action>Closes all open editor windows</action></para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo><keycap>Alt</keycap><keycap>Shift</keycap><keycap>Left Arrow</keycap></keycombo> +</shortcut> +<guimenu>Window</guimenu> +<guimenuitem>Go Left</guimenuitem> +</menuchoice></term> +<listitem><para><action>Selects the editor window to the left of the current one.</action></para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo><keycap>Alt</keycap><keycap>Shift</keycap><keycap>Right Arrow</keycap></keycombo> +</shortcut> +<guimenu>Window</guimenu> +<guimenuitem>Go Right</guimenuitem> +</menuchoice></term> +<listitem><para><action>Selects the editor window to the right of the current one.</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> +<guisubmenu>Toolbars</guisubmenu> +</menuchoice></term> +<listitem><para><action>Toggles the different toolbars.</action></para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice> +<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> +</varlistentry> +<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 menu. +</para> + +</sect2> + +</sect1> diff --git a/doc/en/main_window.docbook b/doc/en/main_window.docbook new file mode 100644 index 0000000..ada3fd8 --- /dev/null +++ b/doc/en/main_window.docbook @@ -0,0 +1,24 @@ +<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 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. +</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> diff --git a/doc/en/main_window.png b/doc/en/main_window.png Binary files differnew file mode 100644 index 0000000..b5842af --- /dev/null +++ b/doc/en/main_window.png diff --git a/doc/en/pos_history.docbook b/doc/en/pos_history.docbook new file mode 100644 index 0000000..7bd6f74 --- /dev/null +++ b/doc/en/pos_history.docbook @@ -0,0 +1,101 @@ +<sect1 id="position-history"> +<title>Position History</title> + +<sect2 id="pos-hist-intro"> +<title>Introduction</title> + +<para> +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. +</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). +</para> +</note> + +<para> +Position history records appear in pages incorporated into the Query Results window. These pages can be immediately distinguished from query results by their tab labels, which always read "History X" (where X is a unique number that identifies the page). Other than that the two types of pages look very much the same: a history page is composed of a list of records, each comprised of the following fields: +<itemizedlist> +<listitem><para>File</para></listitem> +<listitem><para>Line</para></listitem> +<listitem><para>Text</para></listitem> +</itemizedlist> +</para> + +<para> +Note that the "Function" field is not provided for position history records. +</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 positions. 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> diff --git a/doc/en/pref_clrs.png b/doc/en/pref_clrs.png Binary files differnew file mode 100644 index 0000000..31e2f24 --- /dev/null +++ b/doc/en/pref_clrs.png diff --git a/doc/en/pref_fonts.png b/doc/en/pref_fonts.png Binary files differnew file mode 100644 index 0000000..c2272d3 --- /dev/null +++ b/doc/en/pref_fonts.png diff --git a/doc/en/pref_opts.png b/doc/en/pref_opts.png Binary files differnew file mode 100644 index 0000000..8dcf3c9 --- /dev/null +++ b/doc/en/pref_opts.png diff --git a/doc/en/pref_progs.png b/doc/en/pref_progs.png Binary files differnew file mode 100644 index 0000000..7ea262a --- /dev/null +++ b/doc/en/pref_progs.png diff --git a/doc/en/project_details.png b/doc/en/project_details.png Binary files differnew file mode 100644 index 0000000..33d60cd --- /dev/null +++ b/doc/en/project_details.png diff --git a/doc/en/project_files.png b/doc/en/project_files.png Binary files differnew file mode 100644 index 0000000..94fdb32 --- /dev/null +++ b/doc/en/project_files.png diff --git a/doc/en/project_make.png b/doc/en/project_make.png Binary files differnew file mode 100644 index 0000000..1db4500 --- /dev/null +++ b/doc/en/project_make.png diff --git a/doc/en/project_open.png b/doc/en/project_open.png Binary files differnew file mode 100644 index 0000000..e6f26f8 --- /dev/null +++ b/doc/en/project_open.png diff --git a/doc/en/project_opts.png b/doc/en/project_opts.png Binary files differnew file mode 100644 index 0000000..9500b67 --- /dev/null +++ b/doc/en/project_opts.png diff --git a/doc/en/project_types.png b/doc/en/project_types.png Binary files differnew file mode 100644 index 0000000..8998f03 --- /dev/null +++ b/doc/en/project_types.png diff --git a/doc/en/projects.docbook b/doc/en/projects.docbook new file mode 100644 index 0000000..c39e3aa --- /dev/null +++ b/doc/en/projects.docbook @@ -0,0 +1,394 @@ +<sect1 id="projects"> +<title>Working with Projects</title> + +<para> +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. +</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. The dialogue consists of three pages: <guilabel>Details</guilabel>, <guilabel>File Types</guilabel> and <guilabel>Options</guilabel>. +</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> + +<sect3> +<title>Details</title> + +<screenshot> +<screeninfo>The Project Details page</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="project_details.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The Project Details page</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><guilabel>Source Root (Optional)</guilabel></term> +<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> +</varlistentry> +</variablelist> +</sect3> + +<sect3> +<title>File Types</title> + +<screenshot> +<screeninfo>The File Types page</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="project_types.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The File Types page</phrase> +</textobject> +</mediaobject> +</screenshot> + +<variablelist> +<varlistentry> +<term><guilabel>This Project</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><guilabel>Available Types</guilabel></term> +<listitem><para>A list of standard file types that can be included in a project. To add a type, highlight its entry in the list, and click the <guibutton>Add</guibutton> button. Custom types can also be added, by typing in shell-style patterns in the edit-box at the top of the list.</para></listitem> +</varlistentry> +<varlistentry> +<term><guibutton>Add</guibutton></term> +<listitem><para><action>Adds the currently selected file type to the project.</action></para></listitem> +</varlistentry> +<varlistentry> +<term><guibutton>Remove</guibutton></term> +<listitem><para><action>Removes the currently selected file types from the project.</action> The file type is added to the list of available types.</para></listitem> +</varlistentry> +</variablelist> +</sect3> + +<sect3> +<title>Options</title> + +<screenshot> +<screeninfo>The Project Options page</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="project_opts.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The Project Options page</phrase> +</textobject> +</mediaobject> +</screenshot> + +<variablelist> +<varlistentry> +<term><guilabel>Kernel project</guilabel></term> +<listitem><para>Mark this check-box if the project is designated to be a kernel-style 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>Do not compress the database</guilabel></term> +<listitem><para>Builds cross-reference database without compression. This will create a larger, but human-readable database.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Slower, but more accurate, function definition detection</guilabel></term> +<listitem><para>Applies a huristic that can overcome <application>Cscope</application>'s inability to detect function declarations with function pointers as parameters. Requires a patch to <application>Cscope</application>.</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> +<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="auto-symbol-completion">Automatic Symbol Completion</link> for a description of this dialogue).</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Override default tab width (Kate only)</guilabel></term> +<listitem><para>Use a per-project tab-width (overriding the editor's settings). Helps when browsing code bases that use different styles than the user's preferred one.</para></listitem> +</varlistentry> +</variablelist> +</sect3> + +<sect3> +<title>Common Buttons</title> +<variablelist> +<varlistentry> +<term><guibutton>OK</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> +</sect3> +</sect2> + +<sect2 id="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 left 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 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. +</para> + +</sect2> + +<sect2 id="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. Use the browser button to locate a project by its configuration file (<filename>cscope.proj</filename>).</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 that project is opened again. +</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. +</para> + +</sect2> + +<sect2 id="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="project-create">New Project dialogue</link> for a description of the available project options. +</para> + +</sect2> + +<sect2 id="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, <application>Vi</application>, <application>>Emacs</application>, 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> + +<sect2 id="projects-build"> +<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. +</para> + +<screenshot> +<screeninfo>The Make Project dialogue</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="project_make.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The Make Project dialogue</phrase> +</textobject> +</mediaobject> +</screenshot> + +<variablelist> +<varlistentry> +<term><guilabel>Root Directory</guilabel></term> +<listitem><para>The directory in which to run the build command.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Command</guilabel></term> +<listitem><para>The command to execute.</para></listitem> +</varlistentry> +<varlistentry> +<term><guibutton>Make</guibutton></term> +<listitem><para><action>Executes the build command.</action></para></listitem> +</varlistentry> +<varlistentry> +<term><guibutton>Stop</guibutton></term> +<listitem><para><action>Halts an executing build process.</action></para></listitem> +</varlistentry> +<varlistentry> +<term><guibutton>Close</guibutton></term> +<listitem><para><action>Closes the dialogue.</action></para></listitem> +</varlistentry> +</variablelist> + +</sect2> + +</sect1> diff --git a/doc/en/query_dlg.png b/doc/en/query_dlg.png Binary files differnew file mode 100644 index 0000000..120ddb7 --- /dev/null +++ b/doc/en/query_dlg.png diff --git a/doc/en/query_filter.png b/doc/en/query_filter.png Binary files differnew file mode 100644 index 0000000..de3a69c --- /dev/null +++ b/doc/en/query_filter.png diff --git a/doc/en/query_system.docbook b/doc/en/query_system.docbook new file mode 100644 index 0000000..6f637cf --- /dev/null +++ b/doc/en/query_system.docbook @@ -0,0 +1,434 @@ + +<sect1 id="queries"> +<title>The Query System</title> + +<para> +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. +</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> + +<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. +</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. +</para> + +<para> +A project's database is also updated whenever that project is opened. +</para> + +<sect2 id="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> + +<variablelist> +<varlistentry> +<term><guilabel>Type</guilabel></term> +<listitem><para>The type of query to perform. This value defaults to the requested type, by can be changed by selecting a different entry in the list.</para></listitem> +</varlistentry> +<varlistentry> +<term><guibutton>Symbol</guibutton></term> +<listitem><para>Enter the symbol to query in this box. The default value is the symbol currently under the editor's cursor (if any).</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Search for a Sub-String</guilabel></term> +<listitem><para>Mark this check-box to treat the entered text as part of a symbol (will query all symbols containing the entered text as a sub-string).</para></listitem> +</varlistentry> +<varlistentry> +<term><guibutton>OK</guibutton></term> +<listitem><para><action>Runs the query.</action></para></listitem> +</varlistentry> +<varlistentry> +<term><guibutton>Hint</guibutton></term> +<listitem><para><action>Provides a list of possible matches to the entered symbol.</action></para></listitem> +</varlistentry> +<varlistentry> +<term><guibutton>Cancel</guibutton></term> +<listitem><para><action>Closes the dialogue without running the query.</action></para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Suggested Symbols</guilabel></term> +<listitem><para>A list of known symbols matching the text in the symbol box.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Hint Options</guilabel></term> +<listitem><para>These buttons affect the way text in the symbol box is matched to fill the suggested symbols list.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Symbols Beginning With...</guilabel></term> +<listitem><para>Choose this option to match symbols starting with the given text.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Symbols Containing...</guilabel></term> +<listitem><para>Choose this option to match symbols containing the given text.</para></listitem> +</varlistentry> +</variablelist> + +<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> +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. +</para> + +</sect2> + +<sect2 id="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="result-options"> +<title>Query Results Options</title> + +<para> +Right-clicking a query result in either a query window or a call-tree dialogue displays a context menu. This menu includes several actions that can be used to either extract information or fine tune these results. +</para> + +<para> +<variablelist> +<varlistentry> +<term><menuchoice> +<guimenuitem>Copy File</guimenuitem> +</menuchoice></term> +<listitem><para><action>Copies the file path part of a result record to the clipboard</action> (the copy commands are available depending on the position of the mouse cursor).</para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice> +<guimenuitem>Copy Function</guimenuitem> +</menuchoice></term> +<listitem><para><action>Copies the function name part of a result record to the clipboard.</action></para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice> +<guimenuitem>Copy Line</guimenuitem> +</menuchoice></term> +<listitem><para><action>Copies the line number part of a result record.</action></para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice> +<guimenuitem>Copy Text</guimenuitem> +</menuchoice></term> +<listitem><para><action>Copies the function name part of a result record to the clipboard.</action></para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice> +<guimenuitem>Filter...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Displays the Filter Query Results dialogue.</action> See the section <link linkend="filter-results">Filtering Query Results</link> for a detailed description of this option.</para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice> +<guimenuitem>Show All</guimenuitem> +</menuchoice></term> +<listitem><para><action>Displays all query results.</action> This option reverts the effects of any filters previously applied.</para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice> +<guimenuitem>Remove Item</guimenuitem> +</menuchoice></term> +<listitem><para><action>Permanently removes a record from a query results window.</action> This action can only be undone by rerunning the query.</para></listitem> +</varlistentry> +</variablelist> +</para> +</sect2> + +<sect2 id="filter-results"> +<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). +</para> + +<para> +The Filter Query Results dialogue is invoked from the query context menu (see <link linkend="result-options">Query Result Options</link>). +<screenshot> +<screeninfo>The Filter Query Results dialogue</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="query_filter.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The Filter Query Results dialogue</phrase> +</textobject> +</mediaobject> +</screenshot> +</para> + +<variablelist> +<varlistentry> +<term><guilabel>Search For</guilabel></term> +<listitem><para>Enter the pattern to match in the query result records. This pattern is interpreted based on the Search Type selection.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Search In</guilabel></term> +<listitem><para>The record field in which to look for the search pattern. By default, this is the field over which the context menu was invoked.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Search Type</guilabel></term> +<listitem><para>Defines the way in which the pattern should be interpreted.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Plain Text</guilabel></term> +<listitem><para>Choose this option to treat the pattern as a simple text string to search for.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>RegExp</guilabel></term> +<listitem><para>Choose this option to treat the pattern as a regular expression.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Simplified RegExp</guilabel></term> +<listitem><para>Choose this option to treat the pattern as a simplified regular expression (a-la file expressions in a Unix shell).</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Case Sensitive</guilabel></term> +<listitem><para>Check for a case sensitive search, uncheck for a case insensitive one.</para></listitem> +</varlistentry> +<varlistentry> +<term><guibutton>OK</guibutton></term> +<listitem><para><action>Filters the query results based on the given information.</action></para></listitem> +</varlistentry> +<varlistentry> +<term><guibutton>Cancel</guibutton></term> +<listitem><para><action>Closes the dialogue without filtering the results.</action></para></listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2 id="call-tree-graph"> +<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. +</para> + +<sect3 id="call-tree"> +<title>Call Trees</title> + +<para> +The Call-Tree has two modes, "Called Functions" and "Calling Functions". In the first case, the call chain starts with a root function, and goes on to display all the functions it references. The second mode shows all functions calling the root function. In both modes each function in the second level can be further expanded to show functions calling it (or functions it calls). This process can be further applied to functions in the third level, an so on. +</para> + +<para> +Both modes use a standard tree widget to display the call chain. Expanding a function to the next level is performed by clicking the plus sign to the left of the function's name. Double-clicking a function (or selecting it and then hitting <keycap>Enter</keycap>) points the editor to the call's actual text. Right-clicking an entry provides a popup-menu with further options, similar to the query results menu (see <link linkend="result-options">Query Result Options</link>). +</para> + +<para> +<screenshot> +<screeninfo>A Call-Tree</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="call_tree.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>A Call-Tree in "Called Functions" mode</phrase> +</textobject> +</mediaobject> +</screenshot> +</para> + +</sect3> + +<sect3 id="call-graph"> +<title>Call Graphs</title> + +<para> +A Call-Tree often misses the true nature of a call sequence, since many such sequences contain loops, that is, functions calling back functions that precede them in the sequence. (Recursive calls provide a natural example for such a state of affairs.) A Call-Graph provides a more accurate description of the relationships between functions by depicting calls using a directed graph. Each node in the graph represents a function and each edge a function call. An edge is directed from the caller to the callee. +</para> + +<para> +<screenshot> +<screeninfo>A Call-Graph</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="call_graph.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>A Call-Graph</phrase> +</textobject> +</mediaobject> +</screenshot> +</para> + +<para> +When a Call-Graph is created, it only displays a single function. Right-clicking on this function opens a popup menu that allows the user to display or hide either the functions called by or calling to this one. This menu consists of the following entries: + +<variablelist> +<varlistentry> +<term><menuchoice> +<guimenu>Called Functions</guimenu> +<guimenuitem>Show</guimenuitem> +</menuchoice></term> +<listitem><para>Shows all functions called by this one.</para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice> +<guimenu>Called Functions</guimenu> +<guimenuitem>List/Filter...</guimenuitem> +</menuchoice></term> +<listitem><para>Displays a detailed list of called functions. This list can also be used to select which calling functions to show.</para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice> +<guimenu>Called Functions</guimenu> +<guimenuitem>Hide</guimenuitem> +</menuchoice></term> +<listitem><para>Removes any functions called by this one. This will also remove any unconnected graph components resulting from the removal of the corresponding nodes.</para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice> +<guimenu>Calling Functions</guimenu> +<guimenuitem>Show</guimenuitem> +</menuchoice></term> +<listitem><para>Shows all functions calling this one.</para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice> +<guimenu>Calling Functions</guimenu> +<guimenuitem>List/Filter...</guimenuitem> +</menuchoice></term> +<listitem><para>Displays a detailed list of calling functions. This list can also be used to select which calling functions to show.</para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice> +<guimenu>Calling Functions</guimenu> +<guimenuitem>Hide</guimenuitem> +</menuchoice></term> +<listitem><para>Removes any functions calling this one. This will also remove any unconnected graph components resulting from the removal of the corresponding nodes.</para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice> +<guimenu>This Function</guimenu> +<guimenuitem>Find Definition</guimenuitem> +</menuchoice></term> +<listitem><para>Queries the database for the definition of the selected function.</para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice> +<guimenu>This Function</guimenu> +<guimenuitem>Remove</guimenuitem> +</menuchoice></term> +<listitem><para>Deletes the selected node from the graph.</para></listitem> +</varlistentry> +</variablelist> +</para> + +<para> +Another popup menu is displayed when an arrow head is right-clicked: + +<variablelist> +<varlistentry> +<term><menuchoice> +<guimenuitem>Open Call</guimenuitem> +</menuchoice></term> +<listitem><para>Opens an editor page at the location of the call represented by this edge.</para></listitem> +</varlistentry> +</variablelist> +</para> + +</sect3> + +</sect2> + +</sect1> diff --git a/doc/en/quick_start.docbook b/doc/en/quick_start.docbook new file mode 100644 index 0000000..02ff501 --- /dev/null +++ b/doc/en/quick_start.docbook @@ -0,0 +1,41 @@ +<sect1 id="quick-start"> +<title>Quick Start</title> + +<para> +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 KDE 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> +</para> +</sect2> + +<sect2> +<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. +</para> +</sect2> + +<sect2> +<title>Populate the Project</title> + +<para> +As mentioned above, a project is associated with a set of source files. These need to be added to the project, before any useful work can be done. Files can be added (or removed) using the <link linkend="project-files">Project Files</link> dialogue. +</para> +</sect2> + +<sect2> +<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. +</para> +</sect2> + +</sect1> |
