From 3af5832abe7c802a384cd58d34f7cc4433595ced Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sl=C3=A1vek=20Banko?= Date: Mon, 7 Oct 2013 23:28:24 +0200 Subject: Initial import of kscope 1.6.2 --- doc/Makefile.am | 6 + doc/en/Makefile.am | 5 + doc/en/about.docbook | 31 +++ doc/en/autocomp_dlg.png | Bin 0 -> 12457 bytes doc/en/bookmarks.docbook | 28 +++ doc/en/bookmarks.png | Bin 0 -> 23860 bytes doc/en/call_graph.png | Bin 0 -> 23525 bytes doc/en/call_tree.png | Bin 0 -> 94329 bytes doc/en/config_dlg.docbook | 206 ++++++++++++++++++++ doc/en/editing.docbook | 138 +++++++++++++ doc/en/index.docbook | 174 +++++++++++++++++ doc/en/main_menu.docbook | 465 ++++++++++++++++++++++++++++++++++++++++++++ doc/en/main_window.docbook | 24 +++ doc/en/main_window.png | Bin 0 -> 719478 bytes doc/en/pos_history.docbook | 101 ++++++++++ doc/en/pref_clrs.png | Bin 0 -> 43746 bytes doc/en/pref_fonts.png | Bin 0 -> 30787 bytes doc/en/pref_opts.png | Bin 0 -> 41987 bytes doc/en/pref_progs.png | Bin 0 -> 47959 bytes doc/en/project_details.png | Bin 0 -> 31041 bytes doc/en/project_files.png | Bin 0 -> 72430 bytes doc/en/project_make.png | Bin 0 -> 106302 bytes doc/en/project_open.png | Bin 0 -> 22418 bytes doc/en/project_opts.png | Bin 0 -> 28292 bytes doc/en/project_types.png | Bin 0 -> 20111 bytes doc/en/projects.docbook | 394 +++++++++++++++++++++++++++++++++++++ doc/en/query_dlg.png | Bin 0 -> 24116 bytes doc/en/query_filter.png | Bin 0 -> 16118 bytes doc/en/query_system.docbook | 434 +++++++++++++++++++++++++++++++++++++++++ doc/en/quick_start.docbook | 41 ++++ 30 files changed, 2047 insertions(+) create mode 100644 doc/Makefile.am create mode 100644 doc/en/Makefile.am create mode 100644 doc/en/about.docbook create mode 100644 doc/en/autocomp_dlg.png create mode 100644 doc/en/bookmarks.docbook create mode 100644 doc/en/bookmarks.png create mode 100644 doc/en/call_graph.png create mode 100644 doc/en/call_tree.png create mode 100644 doc/en/config_dlg.docbook create mode 100644 doc/en/editing.docbook create mode 100644 doc/en/index.docbook create mode 100644 doc/en/main_menu.docbook create mode 100644 doc/en/main_window.docbook create mode 100644 doc/en/main_window.png create mode 100644 doc/en/pos_history.docbook create mode 100644 doc/en/pref_clrs.png create mode 100644 doc/en/pref_fonts.png create mode 100644 doc/en/pref_opts.png create mode 100644 doc/en/pref_progs.png create mode 100644 doc/en/project_details.png create mode 100644 doc/en/project_files.png create mode 100644 doc/en/project_make.png create mode 100644 doc/en/project_open.png create mode 100644 doc/en/project_opts.png create mode 100644 doc/en/project_types.png create mode 100644 doc/en/projects.docbook create mode 100644 doc/en/query_dlg.png create mode 100644 doc/en/query_filter.png create mode 100644 doc/en/query_system.docbook create mode 100644 doc/en/quick_start.docbook (limited to 'doc') 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 @@ + +About &kapp; + + +&kapp; is a KDE-based source-editing environment for C and C-style languages. Primarily, it is a front-end to the veteran Cscope, a source-code browser originally developed at Bell Labs. Cscope 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 Cscope with a contemporary user interface, editor integration, project management capabilities, multiple query result windows, call trees and graphs, and more. + + + +&kapp; implements (almost) all of Cscope's query types. Among these are: + +Browse for all references to a symbol; +Get the global definition of a symbol; +Find all functions calling to or called by a function; +Find a text string or an EGrep pattern; +and more. + + + + +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 Cscope as its underlying engine, &kapp; can easily handle projects such as the Linux kernel, WINE, PostgreSQL, etc. + + + +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. + + + +&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. + + + diff --git a/doc/en/autocomp_dlg.png b/doc/en/autocomp_dlg.png new file mode 100644 index 0000000..21d39e4 Binary files /dev/null and b/doc/en/autocomp_dlg.png differ 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 @@ + +Bookmarks + + +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. + + + +The Bookmarks dialogue is invoked by the GoGlobal Bookmarks menu command. Once open, it displays the set bookmarks among all currently-open files. This includes the file path, the source line and the line's text (similar to other source views available in &kapp;). + + + +The Bookmarks dialogue + + + + + +The Bookmarks dialogue + + + + + +Navigating to a defined bookmark can be done by either double-clicking an entry in the dialogue, or by choosing the View Source item from the context menu (available by right-clicking over a bookmark entry). Other choices presented by the context menu include Copy [FIELD] for copying the contents of the current field to the clipboard, Filter... for selecting entries based on some criteria, Show All for removing all filters and Remove Item for deleting the bookmark. + + + \ No newline at end of file diff --git a/doc/en/bookmarks.png b/doc/en/bookmarks.png new file mode 100644 index 0000000..2f20be7 Binary files /dev/null and b/doc/en/bookmarks.png differ diff --git a/doc/en/call_graph.png b/doc/en/call_graph.png new file mode 100644 index 0000000..719f3f7 Binary files /dev/null and b/doc/en/call_graph.png differ diff --git a/doc/en/call_tree.png b/doc/en/call_tree.png new file mode 100644 index 0000000..010be6c Binary files /dev/null and b/doc/en/call_tree.png differ 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 @@ + +The Configuration Dialogue + + +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 SettingsConfigure KScope... menu command. + + + +The dialogue is composed of several pages, each of which handles a different set of parameters. + + + +The Programmes Page + + +&kapp; serves as a front-end to several console-based programmes: Cscope, Ctags and Dot (which is part of the Graphviz 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. + + + +Another parameter required by &kapp; is whether Cscope supports the command line option. This is a relatively new feature, added to Cscope 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 Cscope to a version that supports the option, as the user experience of &kapp; is much improved with it. However, if you choose to use an older version of Cscope, make sure the check-box for using the option is cleared. + + + +You can determine whether your version of Cscope supports this option by running . + + + +The easiest way to configure programme paths is by using the automated script provided with &kapp;. This script can be activated by clicking the Guess... button. Once invoked, the script looks for the required programmes (using the shell's which utility). The script also makes sure that the found executables adhere to the standards required by &kapp; (e.g., that Ctags is the one provided by Exuberant-Ctags and that Dot supports the command-line option). &kapp; uses the results of the script to adjust the values in the dialogue's controls. + + + +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. + + + + +The Programmes page + + + + + +The Programmes page + + + + + + +Cscope Path +The full path of the Cscope executable. The name of this executable must be cscope. + + +Use verbose mode (-v) +Instructs Cscope to produce verbose progress output, by appending to the command line. + + +Ctags Path +The full path of the Ctags executable. The name of this executable must contain the string ctags. + + +Dot Path +The full path of the Dot executable. The name of this executable must be dot. + + +Guess +Runs a script which attempts to determine the previous values automatically. This script should work in most cases, by may fail to correctly obtain some or all of the values. + + +If the file names on your system do not conform to the limitations described above, please create symbolic links to the executables. + + + + + +The Colours Page + + + +The Colours page + + + + + +The Colours page + + + + +The Colours page allows you to configure &kapp; to look the way you want it to, by changing the foreground and background colours of some of &kapp;'s GUI elements. The elements that can be modified are: + +The project's file list (to the right of the editing area) +The editor's symbol (or tag) list (to the left of each editor window) +The query results window +The call graph's background and nodes + + + + +To change the colour of a GUI element, double-click over the element's entry in the list (or select this element and click Enter). + + + +The editor's own colours are determined by the settings of the embedded editor, and are not controlled by &kapp;. + + + + + +The Fonts Page + + + +The Fonts page + + + + + +The Fonts page + + + + +The Fonts page allows you to determine the fonts used by any of &kapp;'s windows (see The Colours Page section for a description of these windows.) + + + +To change the colour of a GUI element, double-click over the element's entry in the list (or select this element and click Enter). + + + +As with the colour scheme, the fonts used by the embedded editor are not determined by &kapp;. + + + + + +The Options Page + + +This page allows the user to configure certain parameters that affect the behaviour of &kapp;. + + + + +The Options page + + + + + +The Options page + + + + + +External Editor +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. + + +Read-Only Mode +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). + + +Open Last Project on Start-Up +Determines whether &kapp; should automatically attempt to load the last active project when started. + + +Automatic Tag Highlighting +If set, &kapp; will highlight tags in the tag list based on the current position of the text cursor. + + +Brief Tab Captions for Query Pages +This option allows some space to be saved by using shortcuts for the page titles in the query window. + + +Warn When a File is Modified Outside &kapp; +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). + + +Automatically Sort Files in the File List +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. + + +System Profile +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). + + +Editor Popup Menu +Provides two choices for the embedded editor's context menu: + +Embedded: A menu with Cscope actions is included as a sub-menu of the editor's own context menu. +&kapp; Only: Only Cscope actions are available through the context menu. + +The second choice provides quicker access to Cscope commands, but the editor's menu is discarded. + + + + + + + + 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 @@ + +Editing Source Files + + +The Editor + + +&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;, KVim) can be used with &kapp;. The editor is defined in KDE's control centre. + + +In any matter related to operating or configuring the editor, please refer to the manual of the editor itself. + + + + + +Opening Files for Editing + + +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 FileOpen... menu command. Note, however, that query results on files outside a project are meaningless. + + + +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 Enter 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. + + + +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 Set Root... button. The file tree also sports a Find File... button for launching the file search Cscope query. + + + + +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. + + + + +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 Window menu. + + + +To work on a new file, the user first needs to create it using the FileNew... 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 Project Files dialogue and add the new file to an open project. + + + + + +File Tags + + +In addition to being a front-end to Cscope, &kapp; also uses Ctags 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 Enter key, sets the cursor to the beginning of this symbol's definition line. The list of symbols is refreshed whenever a file is saved. + + + +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. + + + +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.) + + + + + +Other File Options + + +&kapp;'s File menu includes further options, such as saving, printing and closing files. In addition, specific editors can offer extended features under the Tools menu (e.g., syntax highlighting, indentation, etc.) + + + + + +Symbol Completion + + +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 EditComplete Symbol menu command (or, more conveniently, by pressing CtrlSpace). 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 Enter replaces the prefix with the selected symbol. The Esc key hides the list without completing the symbol. + + + +Automatic Symbol Completion + + +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. + + + +Automatic symbol completion is configured on a per-project basis. This feature is enabled or disabled via the Use Symbol Auto-Completion check-box in the New Project dialogue (this option can also be changed after a project has been created by invoking the Project Properties dialogue). + + + + +For performance reasons, it is highly recommended that automatic symbol completion will be used in conjunction with the inverted-index option. + + + + +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 Options... button in the New Project dialogue (or, later, in the Project Properties dialogue). Clicking this button invokes the Auto-Completion Properties dialogue. + + +The auto-completion properties dialogue + + + + + +The auto-completion properties dialogue + + + + + + +Minimum Characters +The minimal length of a symbol for which completion is provided. + + +Delay (ms) +Specifies a time interval that should elapse after the last change to the edited text and before the symbol completion query is executed. + + +Maximum Entries +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). + + + + + +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. + + + + + + + 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 @@ + +KScope'> + + + + + + + + + + + + + + + + +]> + + + + + + + + +The &kapp; Handbook + + + +Elad + +Lahav + +
elad_lahav@users.sourceforge.net
+ + + + + + + +2003-2007 +Elad Lahav + + + +&FDLNotice; + + + +08/07/2007 +1.6.0 + + + + + +&kapp; is a source-editing environment for KDE, based on Cscope. + + + + + + +KDE +KScope +Cscope +source +editor +browser + + + + + + + +Introduction + +&about; +&quick-start; + + + + +Using &kapp; + +&main-window; +&projects; +&editing; +&query-system; +&position-history; +&bookmarks; + + + + +Configuring &kapp; + +&config-dlg; + + + + +Command Reference + +&main-menu; + + + + + + + +Credits and License + + +&kapp; + + +Programme copyright 2003-2007 Elad Lahav elad_lahav@users.sourceforge.net + + +I would like to thank: + +The KDE team +The KDevelop team +Hans-Bernhard Broker, who maintains Cscope + + + + +Documentation copyright 2007-2006 Elad Lahav elad_lahav@users.sourceforge.net + + + + +&underFDL; + + + + +&underBSDLicense; + + + + 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 @@ + +&kapp;'s Main Menu + + +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., Edit, View or Tools.) Please refer to the editor's manual for a description of the commands under these sub-menus. + + + +The File Menu + + + + + + +CtrlN + +File +New + +Opens an empty editor window. + + + + +CtrlO + +File +Open... + +Opens a file for editing. + + + + +CtrlW + +File +Close + +Closes the active editor window + + + + +CtrlQ + +File +Quit + +Quits &kapp; + + + + +Other file operations such as Save and Print are not integral &kapp; actions, but are rather defined by the type of editor used. + + + + + +The Edit Menu + + + + + + +CtrlE + +Edit +Edit in External Editor + +Launches an editor application for the current file and line number + + + + +CtrlShiftT + +Edit +Go To Tag + +Moves the cursor to the tag list, used for browsing through the file's tags + + + + +CtrlSpace + +Edit +Complete Symbol + +Generates a list of possible symbol completions for the text to the left of the cursor. Note that this option is available even if automatic completion is disabled. + + + + + + + +The View Menu + + + + + + +Ctrl/ + +View +Toggle File List + +Shows or hides the project's file list window. + + + + +Ctrl. + +View +Toggle Query Window + +Shows or hides the query window. + + + + +Ctrl. + +View +Toggle Tag List + +Shows or hides the tag lists attached to the editor windows. + + + + + + + +The Project Menu + + + + + +Project +New... + +Displays the New Project dialogue box.Use this dialogue to create a new project. + + + +Project +Open... + +Displays the Open Project dialogue box, which lets you search for an existing project to open. + + + +Project +Open Cscope.out... + +Prompts for an existing Cscope.out, which can be opened as a temporary project. + + + +Project +Add/Remove Files... + +Displays the Project Files dialogue box, which allows you to add source files to the current project, or remove files from it. + + + +Project +Properties... + +Displays the Project Properties dialogue box. + + + + +CtrlM + +Project +Make Project... + +Displays the Build dialogue. + + + + +CtrlShiftM + +Project +Remake Project + +Displays the Build dialogue and executes the last build command. + + + +Project +Close + +Closes the active project, along with all open editor windows. + + + + + + + +The Cscope Menu + + + + + +Cscope +Rebuild Database + +Updates the cross-reference database for the current project + + + + +Ctrl0 + +Cscope +References... + +Finds all references to a given symbol + + + + +Ctrl1 + +Cscope +Definition... + +Finds the global definition of a symbol + + + + +Ctrl2 + +Cscope +Called Functions... + +Finds all functions called by a given function + + + + +Ctrl3 + +Cscope +Calling Functions... + +Finds all functions calling a given function + + + + +Ctrl4 + +Cscope +Find Text... + +Finds all occurrences of a text string + + + + +Ctrl5 + +Cscope +Find EGrep Pattern... + +Finds all text strings matching a regular expression + + + + +Ctrl8 + +Cscope +Find Including Files... + +Finds all files #including a given file + + + + +Ctrl] + +Cscope +Quick Definition + +Finds the global definition of the symbol currently under the cursor. The symbol dialogue appears only if a symbol cannot be determined automatically. + + + + +Ctrl\ + +Cscope +Call Graph... + +Displays a call-graph and/or a call-tree for a given function + + + + + + + +The Go Menu + + + + + + +AltUp Arrow + +Go +Previous Result + +Selects the previous result in the current query window. + + + + +AltDown Arrow + +Go +Next Result + +Selects the next result in the current query window. + + + + +AltLeft Arrow + +Go +Previous Position + +Jumps to the previous stored position in the active history list. + + + + +AltRight Arrow + +Go +Next Position + +Jumps to the next stored position in the active history list. + + + + +CtrlH + +Go +Position History... + +Selects the active position history page in the query window. If the query window is hidden, it becomes visible. + + + + +CtrlShiftG + +Go +Global Bookmarks... + +Displays the Bookmarks dialogue. + + + + + + + +The Window Menu + + + + + +Window +Close All + +Closes all open editor windows + + + + +AltShiftLeft Arrow + +Window +Go Left + +Selects the editor window to the left of the current one. + + + + +AltShiftRight Arrow + +Window +Go Right + +Selects the editor window to the right of the current one. + + + + +This menu displays the full path of each file edited in an open window. Clicking a +file name will make its editor window active. + + + + + +The Settings Menu + + + + + +Settings +Toolbars + +Toggles the different toolbars. + + + +Settings +Configure Shortcuts... + +Allows the user to assign different shortcuts to &kapp; commands. + + + +Settings +Configure KScope... + +Displays the &kapp; configuration dialogue + + + + +A menu item to configure the embedded editor may also appear under this menu. + + + + + 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 @@ + +The Main Window + + +&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 Cscope queries, and the history pages that display locations in the source code visited by the user. + + +The Main Window + + + + + +&kapp;'s main window + + + + +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. + + +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 View 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. + + diff --git a/doc/en/main_window.png b/doc/en/main_window.png new file mode 100644 index 0000000..b5842af Binary files /dev/null and b/doc/en/main_window.png differ 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 @@ + +Position History + + +Introduction + + +In its capacity as a source code browser, &kapp; allows the user to quickly browse through different lines in the code base. We refer to a combination of a source file and a line number as a "position" in the project. While browsing the code, it is often required to go back to a position visited in the past, e.g., to return to the caller after visiting the callee. To achieve this task, &kapp; provides a sophisticated position history mechanism, which not only allows the user to go back and forth between visited locations, but also to save and restore snapshots of "tours" through the code, as well as other manipulations of the position history. For the sake of both consistency and ease of use, recorded position history is viewed and handled in a way similar to the query results system. + + + + +In 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). + + + + +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: + +File +Line +Text + + + + +Note that the "Function" field is not provided for position history records. + + + +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"). + + + +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 Using Multiple Histories for a detailed description of the active page concept. + + + +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. + + + +Each jump may add up to two entries to the active history list: + +The current position of the cursor (before the cursor jumps to the requested position), and +The new position of the cursor. + +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. + + + + + +Navigation + + +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. + + + +To go back to the last position visited, select the GoPrevious Position 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 GoNext Position selects the position record immediately above the current one in the active history page, and moves the editing cursor to the appropriate location. + + + +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 Enter key. This action can be applied to any history list, and not just to the active one. + + + + +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. + + + + + + +Using Multiple Histories + + +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. + + + +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. + + + +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 The Query Window). 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. + + + +Navigational commands (GoNext Position and GoPrevious Position) 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. + + + +As with query pages, locked history pages are saved when a project is closed, and restored when it is opened. + + + + + diff --git a/doc/en/pref_clrs.png b/doc/en/pref_clrs.png new file mode 100644 index 0000000..31e2f24 Binary files /dev/null and b/doc/en/pref_clrs.png differ diff --git a/doc/en/pref_fonts.png b/doc/en/pref_fonts.png new file mode 100644 index 0000000..c2272d3 Binary files /dev/null and b/doc/en/pref_fonts.png differ diff --git a/doc/en/pref_opts.png b/doc/en/pref_opts.png new file mode 100644 index 0000000..8dcf3c9 Binary files /dev/null and b/doc/en/pref_opts.png differ diff --git a/doc/en/pref_progs.png b/doc/en/pref_progs.png new file mode 100644 index 0000000..7ea262a Binary files /dev/null and b/doc/en/pref_progs.png differ diff --git a/doc/en/project_details.png b/doc/en/project_details.png new file mode 100644 index 0000000..33d60cd Binary files /dev/null and b/doc/en/project_details.png differ diff --git a/doc/en/project_files.png b/doc/en/project_files.png new file mode 100644 index 0000000..94fdb32 Binary files /dev/null and b/doc/en/project_files.png differ diff --git a/doc/en/project_make.png b/doc/en/project_make.png new file mode 100644 index 0000000..1db4500 Binary files /dev/null and b/doc/en/project_make.png differ diff --git a/doc/en/project_open.png b/doc/en/project_open.png new file mode 100644 index 0000000..e6f26f8 Binary files /dev/null and b/doc/en/project_open.png differ diff --git a/doc/en/project_opts.png b/doc/en/project_opts.png new file mode 100644 index 0000000..9500b67 Binary files /dev/null and b/doc/en/project_opts.png differ diff --git a/doc/en/project_types.png b/doc/en/project_types.png new file mode 100644 index 0000000..8998f03 Binary files /dev/null and b/doc/en/project_types.png differ 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 @@ + +Working with Projects + + +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 Cscope 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. + + +The files used by a &kapp; project are: + + +cscope.proj +The project's configuration file + + +cscope.files +A list of all source files included in the project + + +cscope.out +Cscope's cross-reference database + + +cscope.in.out +An inverted index file (optional) + + +cscope.po.out +An inverted index file (optional) + + + + + +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 projects 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. + + + +Creating a New Project + + +The first step in working with projects is to create a new one. This is done by choosing the ProjectsNew... command from the main menu. Issuing this command opens the New Project dialogue. The dialogue consists of three pages: Details, File Types and Options. + + +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 Project Files dialogue. + + + +Details + + +The Project Details page + + + + + +The Project Details page + + + + + + +Name +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). + + +Path +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 projects directory, the project's name should be set to "my_project" and the path to /home/my_username/projects. This will set the project's directory to /home/my_username/projects/my_project. + + +Source Root (Optional) +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. + + + + + +File Types + + +The File Types page + + + + + +The File Types page + + + + + + +This Project +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 (.c) and C header files (.h) are included, but other types (including Lex's .l files and Yacc's .y files) can be added. + + +Available Types +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 Add button. Custom types can also be added, by typing in shell-style patterns in the edit-box at the top of the list. + + +Add +Adds the currently selected file type to the project. + + +Remove +Removes the currently selected file types from the project. The file type is added to the list of available types. + + + + + +Options + + +The Project Options page + + + + + +The Project Options page + + + + + + +Kernel project +Mark this check-box if the project is designated to be a kernel-style project. For kernel projects, Cscope ignores the system's include files when building the cross-reference database (i.e., printf will not be found in /usr/include/stdio.h). + + +Build inverted index +Cscope 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). + + +Do not compress the database +Builds cross-reference database without compression. This will create a larger, but human-readable database. + + +Slower, but more accurate, function definition detection +Applies a huristic that can overcome Cscope's inability to detect function declarations with function pointers as parameters. Requires a patch to Cscope. + + +Refresh database automatically +&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. + + +Use symbol auto-completion +Enables automatic "as-you-type" symbol completion. Note that manual symbol completion is always available, regardless of whether this option is selected. +If you choose to enable this option, it is recommended that you also select the inverted index option. + + +Options... +Displays the symbol auto-completion configuration dialogue. This button is only enabled if the symbol auto-completion is selected (see Automatic Symbol Completion for a description of this dialogue). + + +Override default tab width (Kate only) +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. + + + + + +Common Buttons + + +OK +Accepts the values entered in the dialogue, and creates a new project. If any mandatory values were omitted, or not entered correctly, the user is prompted. + + +Cancel +Closes the dialogue without creating a new project. + + + + + + +Adding and Removing Project Files + + +The project's list of source files is maintained by the Project Files 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 ProjectAdd/Remove Files... command from the main menu. + + + +The Project Files dialogue + + + + + +The Project Files dialogue + + + + + + + +File Path +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 OK button is clicked. + + +Filter +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). + + +Show All +Reveals any files formerly hidden with the Filter button. + + +Add +All buttons in this group add files to the current project. + + +Files... +Adds user-selected files to the current project. + + +Directory... +Adds all source files in a directory to the current project. Source files are scanned according to the file-types associated with the project. Note that sub-directories are not scanned for files. + + +Tree... +Adds all source files in a selected directory and its sub-directories to the current project. Source files are scanned according to the file-types associated with the project. + + + + + +Remove +All buttons in this group remove files from the current project. + + +Selected +Removes all selected files from the current project. Files can be selected for removal by clicking their path name in the file list. The Ctrl key can be used to select multiple files, and the Shift key can be used to select ranges of files. + + +Directory... +Removes all source files in a directory from the current project. Note that sub-directories are not included. + + +Tree... +Removes all source files in a directory and any of its sub-directories from the current project. + + + + + +OK +Accepts the new list of source files, and updates the project. + + +Cancel +Closes the dialogue without modifying the list of project files. + + + + + +Once the list of project files changes (either when files are first added to the project, or upon any subsequent modification), &kapp; informs Cscope to rebuild the cross-reference database. + + + + + +Opening an Existing Project + + +Existing projects can be opened using the ProjectOpen... menu command. Choosing this command invokes the Open Project dialogue, which allows the user to select the project to open. + + + +The Open Project dialogue + + + + + +The Open Project dialogue + + + + + + +Project Path +The full path of the project directory. Use the browser button to locate a project by its configuration file (cscope.proj). + + +Recent Projects +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. + + +Remove +Removes an entry from the list of recently-opened projects. + + +Open +Opens the project whose directory is set in the Project Path edit-box. + + +Cancel +Closes the dialogue without opening a project. + + + + +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. + + + +After the project has been opened, &kapp; will invoke Cscope, 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, Cscope will rebuild the cross-reference database. + + + + + +Changing Project Properties + + +The properties of an open project can be changed by choosing the ProjectProperties... menu command. This command invokes the Project Properties dialogue, which is similar to the New Project dialogue, except that the name and path of the project cannot be changed. + + + +See the New Project dialogue for a description of the available project options. + + + + + +Temporary Projects + + +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 Cscope front-end (Cscope's ncurses interface, Vi, >Emacs, etc.), or simply using Cscope's command-line parameter. + + + +To open a database file, use the ProjectOpen Cscope.out... menu command. If the file is a valid Cscope cross-reference database, &kapp; will invoke Cscope 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. + + + +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 Cscope. + + + + + +Building Projects + + +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 ProjectMake Project displays a dialogue, which can be used to invoke any external tool on a given directory. By default, it runs make on the project's source root. The output of the command will be displayed in the dialogue's Output 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 Errors and Warnings pane. + + + +The Make Project dialogue + + + + + +The Make Project dialogue + + + + + + +Root Directory +The directory in which to run the build command. + + +Command +The command to execute. + + +Make +Executes the build command. + + +Stop +Halts an executing build process. + + +Close +Closes the dialogue. + + + + + + diff --git a/doc/en/query_dlg.png b/doc/en/query_dlg.png new file mode 100644 index 0000000..120ddb7 Binary files /dev/null and b/doc/en/query_dlg.png differ diff --git a/doc/en/query_filter.png b/doc/en/query_filter.png new file mode 100644 index 0000000..de3a69c Binary files /dev/null and b/doc/en/query_filter.png differ 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 @@ + + +The Query System + + +The most important task of &kapp; is to execute Cscope queries and display their results. Queries are always performed on the cross-reference database of the active project. + + +&kapp; currently supports the following query types: + +Find all references to a symbol +Find a symbol's global definition +Find all functions called by a given function +Find all functions calling a given function +Find a text string +Find an EGrep pattern (regular expression) +Find a file's path by its name +Find all files including a given file +Display a call-tree for a given function + +A symbol, as referred to in the above list, may be a function, a global variable, a structure, a union or a type definition. + + + +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 CscopeRebuild Database menu command. Selecting this command will instruct Cscope to immediately rebuild the cross-reference database. + + + +Automatic database rebuilds are enabled per-project, an option controlled by the Project Properties 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 Project Properties dialogue). Once this timer elapses, &kapp; instructs Cscope to rebuild the database. Code modifications that occur while the timer is running reset its value. + + + +A project's database is also updated whenever that project is opened. + + + +Running a Query + + +A query can be started in one of three ways: + +The main menu +Keyboard shortcuts +The editor's context-menu + + + + +To start a query from the main menu, select the desired query type from the Cscope menu. This will display a dialogue box prompting you for the query's text. The text to enter depends upon the query's type. + +The query dialogue + + + + + +The query dialogue + + + + + + + +Type +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. + + +Symbol +Enter the symbol to query in this box. The default value is the symbol currently under the editor's cursor (if any). + + +Search for a Sub-String +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). + + +OK +Runs the query. + + +Hint +Provides a list of possible matches to the entered symbol. + + +Cancel +Closes the dialogue without running the query. + + +Suggested Symbols +A list of known symbols matching the text in the symbol box. + + +Hint Options +These buttons affect the way text in the symbol box is matched to fill the suggested symbols list. + + +Symbols Beginning With... +Choose this option to match symbols starting with the given text. + + +Symbols Containing... +Choose this option to match symbols containing the given text. + + + + +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. + + + +Each menu item is associated with a keyboard shortcut. These shortcuts follow the convention of using the Ctrl key, together with the numeric query index used by Cscope (this should allow experienced Cscope users to get quickly acquainted with &kapp;). For example, use Ctrl1 to look-up a symbol's definition. The call-tree is an exception to this convention (as it is not a native Cscope query). See the Command Reference for a complete listing of all menu and shortcut options. + + + + +The EGrep query is invoked using Ctrl5, as Ctrl6 is already used by &kate;. + + + + +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 Cscope 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. + + + +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 Cscope's 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 Cscope 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 Configuring &kapp; for more information. + + + + + +The Query Results Window + + +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. + + + +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 Lock/Unlock Query 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. + + + +New query pages can also be created explicitly, by using either the New Query button to the right of the query window, or the context menu available by right-clicking the tab area of the query window. + + + +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: + +The path of the file in which the symbol or string were found +The name of the function containing the symbol or text string +The line number in this file +The text of this line + + + + +By default, results are sorted according to the file name. This can be changed by clicking the column headers of the results list. + + + +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 Enter 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. + + + +If a query results in a single entry, this entry is automatically selected for display. + + + +The results of a query can be refreshed by clicking the Refresh Query 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 Rebuild Database command had been issued). + + + +Query results pages can be closed by either clicking the icon on their tab, by clicking on the Close Query 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 CscopeClose Query main-menu command. + + + +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. + + + + + +Query Results Options + + +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. + + + + + + +Copy File + +Copies the file path part of a result record to the clipboard (the copy commands are available depending on the position of the mouse cursor). + + + +Copy Function + +Copies the function name part of a result record to the clipboard. + + + +Copy Line + +Copies the line number part of a result record. + + + +Copy Text + +Copies the function name part of a result record to the clipboard. + + + +Filter... + +Displays the Filter Query Results dialogue. See the section Filtering Query Results for a detailed description of this option. + + + +Show All + +Displays all query results. This option reverts the effects of any filters previously applied. + + + +Remove Item + +Permanently removes a record from a query results window. This action can only be undone by rerunning the query. + + + + + + +Filtering Query Results + + +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). + + + +The Filter Query Results dialogue is invoked from the query context menu (see Query Result Options). + +The Filter Query Results dialogue + + + + + +The Filter Query Results dialogue + + + + + + + +Search For +Enter the pattern to match in the query result records. This pattern is interpreted based on the Search Type selection. + + +Search In +The record field in which to look for the search pattern. By default, this is the field over which the context menu was invoked. + + +Search Type +Defines the way in which the pattern should be interpreted. + + +Plain Text +Choose this option to treat the pattern as a simple text string to search for. + + +RegExp +Choose this option to treat the pattern as a regular expression. + + +Simplified RegExp +Choose this option to treat the pattern as a simplified regular expression (a-la file expressions in a Unix shell). + + +Case Sensitive +Check for a case sensitive search, uncheck for a case insensitive one. + + +OK +Filters the query results based on the given information. + + +Cancel +Closes the dialogue without filtering the results. + + + + + + +Displaying Call-Trees and Graphs + + +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 Call Graph Dialogue which can be invoked on a function name in a similar way to a regular Cscope query. + + + +Call Trees + + +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. + + + +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 Enter) 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 Query Result Options). + + + + +A Call-Tree + + + + + +A Call-Tree in "Called Functions" mode + + + + + + + + +Call Graphs + + +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. + + + + +A Call-Graph + + + + + +A Call-Graph + + + + + + +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: + + + + +Called Functions +Show + +Shows all functions called by this one. + + + +Called Functions +List/Filter... + +Displays a detailed list of called functions. This list can also be used to select which calling functions to show. + + + +Called Functions +Hide + +Removes any functions called by this one. This will also remove any unconnected graph components resulting from the removal of the corresponding nodes. + + + +Calling Functions +Show + +Shows all functions calling this one. + + + +Calling Functions +List/Filter... + +Displays a detailed list of calling functions. This list can also be used to select which calling functions to show. + + + +Calling Functions +Hide + +Removes any functions calling this one. This will also remove any unconnected graph components resulting from the removal of the corresponding nodes. + + + +This Function +Find Definition + +Queries the database for the definition of the selected function. + + + +This Function +Remove + +Deletes the selected node from the graph. + + + + + +Another popup menu is displayed when an arrow head is right-clicked: + + + + +Open Call + +Opens an editor page at the location of the call represented by this edge. + + + + + + + + + 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 @@ + +Quick Start + + +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. + + + +Configure Paths + + +&kapp; needs to be informed of the absolute paths to several executables, including Cscope, Ctags and (optionally) Dot. These can be configured in the Programmes page of the main configuration dialogue. See The Configuration Dialogue section for more information. +&kapp; will not work properly if these paths are not configured correctly! + + + + +Create a Project + + +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 Creating a New Project for detailed instructions. + + + + +Populate the Project + + +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 Project Files dialogue. + + + + +Browse and Edit Files + + +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. + + + + -- cgit v1.2.1