Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdevelop@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 433 insertions, 0 deletions

diff --git a/doc/kdevelop/plugin-tools.docbook b/doc/kdevelop/plugin-tools.docbook
new file mode 100644
index 00000000..1c07cb7a
--- /dev/null
+++ b/doc/kdevelop/plugin-tools.docbook
@@ -0,0 +1,433 @@
+<appendix id="plugin-tools">
+<title>Plugin Tools</title>
+
+<indexterm zone="plugin-tools">
+  <primary>plugins</primary></indexterm>
+
+<para>
+&kdevelop; contains a large number of little tools that help you to perform
+certain task. Most of them are realized as plugins. That means, if you do not
+need a plugin, you can disable it.</para>
+<para>That also means, if you are looking for a functionality that should be there
+and isn't, then maybe it's implemented in a plugin and that plugin is disabled.
+For example, in the file menu there is a Quick Open feature, but only if
+it's enabled in the Project - Project Options dialog.
+</para>
+ 
+<para>Technically, plugins are based on the KDevPlugin class defined in 
+lib/interfaces/kdevplugin.h. The following is taken from a comment from there.</para>
+
+<para> 
+KDevPlugin is the base class for all KDevelop plugins.
+A plugin is a component which is loaded into KDevelop shell at startup or by request.
+A plugin has a scope that can be either:
+<itemizedlist>
+<listitem><simpara>Core</simpara></listitem>
+<listitem><simpara>Global</simpara></listitem>
+<listitem><simpara>Project</simpara></listitem>
+</itemizedlist>
+</para>
+
+<para>Core plugins are global plugins which offer some important "core" functionality and thus
+are not selectable by user in plugin configuration pages.</para>
+
+<para>Global plugins are plugins which require only shell to be loaded and do not operate on 
+KDevProject interface and/or do not use project wide information.
+For example, the uimode plugin allows a developer to select which user interface they wish to use. 
+</para>
+
+<para>Project plugins require a project to be loaded and are usually loaded/unloaded along with the project.
+If a plugin operates on project-related information then it is a project plugin.
+The Automake Manager, for example, only needs to be active when an Automake based project is currently loaded. 
+</para>
+
+<para>As stated above, core plugins cannot be disabled. Global plugins can be
+enabled/disabled in <menuchoice><guimenu>Settings</guimenu>
+<guimenuitem>Configure KDevelop...</guimenuitem></menuchoice>
+under <guibutton>Plugins</guibutton>.
+Project plugins can be
+enabled/disabled in <menuchoice><guimenu>Project</guimenu>
+<guimenuitem>Project Options...</guimenuitem></menuchoice>
+under <guibutton>Plugins</guibutton>.
+Active plugins can have many effects on KDevelop. 
+Depending on their function, they may add extra menus, extra menu items, extra tool buttons, etc. 
+</para>
+
+<para>Plugins which are disabled do not clutter your menus and are not loaded
+into memory.
+</para>
+
+
+<para>The following plugin list is generated by a small script
+(listplugins.sh) written by Volker Paul. All plugins have a .desktop file
+where information such as name and comments are written.
+If in the following these comments are not very useful,
+it is because the plugin authors made them this way.</para>
+<para>The plugins are grouped by scope (Core, Global, Project).</para>
+
+<para>Scope: Core</para>
+<itemizedlist>
+<listitem><formalpara id="KDevAppWizard">
+<title>Application Wizard</title>
+<para>Application Wizard</para></formalpara></listitem>
+<listitem><formalpara id="KDevDiff">
+<title>Difference Viewer</title>
+<para>Difference Viewer</para></formalpara></listitem>
+<listitem><formalpara id="KDevFileCreate">
+<title>FileCreate</title>
+<para>FileCreate</para></formalpara></listitem>
+<listitem><formalpara id="KDevFullScreen">
+<title>FullScreen</title>
+<para>FullScreen</para></formalpara></listitem>
+<listitem><formalpara id="KDevTipOfDay">
+<title>Tip of the Day</title>
+<para>Tip of the Day</para></formalpara></listitem>
+<listitem><formalpara id="KDevUIChooser">
+<title>User-Interface Selection</title>
+<para>Provides a dialog for UI-mode selection.</para></formalpara></listitem>
+<listitem><formalpara id="KDevVCSManager">
+<title>VCSManager</title>
+<para>Version Control System Manager </para></formalpara></listitem>
+</itemizedlist>
+
+<para>Scope: Global</para>
+<itemizedlist>
+<listitem><formalpara id="KDevAbbrev">
+<title>Abbreviation Expansion</title>
+<para>Provides support for customizable abbreviations - short words which expand into commonly needed code structures.</para></formalpara></listitem>
+<listitem><formalpara id="KDevDocumentation">
+<title>Documentation</title>
+<para>The Documentation plugin offers browsing and searching in local and online documentation with support for multiple documentation systems.</para></formalpara></listitem>
+<listitem><formalpara id="KDevfilelist">
+<title>FileList</title>
+<para>Provides a list of all currently open files. (Handy when the tab bar is not quite wide enough.)</para></formalpara></listitem>
+<listitem><formalpara id="KDevFileSelector">
+<title>File Selector</title>
+<para>Powerful network transparent file browser utility.</para></formalpara></listitem>
+<listitem><formalpara>
+<title>Shell Filtering and Insertion</title>
+<para>Provides a way of manipulating editor text using commandline tools. Appears in the Tools menu.</para></formalpara></listitem>
+<listitem><formalpara id="KDevGrepView">
+<title>Grep Frontend</title>
+<para>Integrates "find|grep" in KDevelop - allows fast searching of multiple files using patterns or regular expressions.</para></formalpara></listitem>
+<listitem><formalpara id="KDevKonsoleView">
+<title>Embedded Konsole</title>
+<para>This plugin gives KDevelop an embedded konsole for quick and easy command line access.</para></formalpara></listitem>
+<listitem><formalpara id="KDevOpenWith">
+<title>"Open with" Menu Addon</title>
+<para>This plugin provides additional "open" alternatives for various context menus in KDevelop.</para></formalpara></listitem>
+<listitem><formalpara id="KDevPartExplorer">
+<title>Part Explorer Tool</title>
+<para>A Graphical tool for performing KTrader-like queries about registered services</para></formalpara></listitem>
+<listitem><formalpara id="KDevRegexpTest">
+<title>Regular Expression Tester</title>
+<para>Tool to design and test regular expressions against common regexp syntaxes.</para></formalpara></listitem>
+<listitem><formalpara id="KDevReplace">
+<title>Replace Part</title>
+<para>This plugin is an interactive projectwide "Search and Replace" tool. Search using string or regexp matching, and select the replacements to be made from a preview before the action is finalized. When loaded it appears in the Edit menu.</para></formalpara></listitem>
+<listitem><formalpara id="KDevscripting">
+<title>Scripting</title>
+<para>The Scripting plugin offers KScript based scripting of the KDevelop application</para></formalpara></listitem>
+<listitem><formalpara id="Code_Snippets">
+<title>Code Snippets</title>
+<para>This plugin allows you to store code snippets and add them to your code</para></formalpara></listitem>
+<listitem><formalpara id="KDevTextTools">
+<title>Text Structure</title>
+<para>Provides a structure overview and navigation for HTML and TEX files</para></formalpara></listitem>
+<listitem><formalpara id="KDevTools">
+<title>Tools Menu Addition</title>
+<para>This plugin provides an easy way to add external applications to the Tools menu and toolbar.</para></formalpara></listitem>
+<listitem><formalpara id="KDevvalgrind">
+<title>Valgrind Frontend</title>
+<para>Valgrind is a tool that helps you find memory management problems in programs. http://developer.kde.org/~sewardj/</para></formalpara></listitem>
+</itemizedlist>
+
+<para>Scope: Project</para>
+<itemizedlist>
+<listitem><formalpara id="KDevannotation">
+<title>annotation Plugin</title>
+<para>annotation Description</para></formalpara></listitem>
+<listitem><formalpara id="KDevAStyle">
+<title>Source Code Formatter</title>
+<para>A plugin for formatting of sourcecode according to a specified set of rules. When loaded it is found in the Tools menu.</para></formalpara></listitem>
+<listitem><formalpara id="KDevBookmarks">
+<title>Bookmarks</title>
+<para>Plugin that provides navigation and overview of active source bookmarks and persists them between sessions.</para></formalpara></listitem>
+<listitem><formalpara id="KDevClassView">
+<title>Class View</title>
+<para>This plugin displays a graphical view of all the classes in the project, complete with methods and attributes, and provides a way of direct source navigation.</para></formalpara></listitem>
+<listitem><formalpara id="KDevcopyto">
+<title>CopyTo</title>
+<para>Simple file uploader plugin. It does a file copy over any KIO supported protocol.</para></formalpara></listitem>
+<listitem><formalpara id="KDevCTags2">
+<title>CTags Frontend</title>
+<para>CTags is a source navigation tool with support for many languages. When loaded it provides a context menu for finding type declarations/definitions and also a query dialog. http://ctags.sourceforge.net/</para></formalpara></listitem>
+<listitem><formalpara id="KDevdistpart">
+<title>Final Packaging Support</title>
+<para>Aids in building and publishing the final project. Only RPM package format is supported for now.</para></formalpara></listitem>
+<listitem><formalpara id="KDevDoxygen">
+<title>Doxygen Support</title>
+<para>The doxygen plugin provides a way to specify and control generation of documentation for a project, based on source code content. You need to have doxygen installed to be able to use this. For more info goto http://www.doxygen.org</para></formalpara></listitem>
+<listitem><formalpara id="KDevQuickOpen">
+<title>QuickOpen</title>
+<para>Provides an efficient way of finding/opening files, classes and methods in a large project. Appears in the File and Tools menus when loaded.</para></formalpara></listitem>
+<listitem><formalpara id="KDevSecurity">
+<title>Security Checker</title>
+<para>Code security checker</para></formalpara></listitem>
+</itemizedlist>
+<para>So far the generated plugin list.</para>
+
+
+<table id="table-project-parts">
+<title>Project Management Plugins in &kdevelop;</title>
+<tgroup cols="2"><tbody>
+<row>
+  <entry>antproject</entry>
+  <entry>ANT Project Manager (&Java; applications)</entry>
+</row>
+<row>
+  <entry>autoproject</entry>
+  <entry>Automake Project Manager</entry>
+</row>
+<row>
+  <entry>customproject</entry>
+  <entry>Custom Project Manager</entry>
+</row>
+<row>
+  <entry>trollproject</entry>
+  <entry>QMake based Project Manager</entry>
+</row>
+</tbody></tgroup>
+</table>
+<para>The above plugins are currently (May 2005) empty. Maybe 
+project management support will be implemented as plugins
+in the future.</para>
+
+
+<table>
+<title>Language Support Plugins in &kdevelop;</title>
+<tgroup cols="2">
+<tbody>
+<row><entry>cppsupport</entry><entry>Support for C/C++</entry></row>
+<row><entry>fortransupport</entry><entry>Support for Fortran</entry></row>
+<row><entry>javasupport</entry><entry>Support for &Java;</entry></row>
+<row><entry>perlsupport</entry><entry>Support for Perl</entry></row>
+<row><entry>phpsupport</entry><entry>Support for PHP</entry></row>
+<row><entry>pythonsupport</entry><entry>Support for Python</entry></row>
+</tbody></tgroup>
+</table>
+
+
+<para>In the following, some of the plugins will be discussed in detail.</para>
+
+<itemizedlist>
+<listitem>
+<formalpara>
+<title>The <command>abbrev</command> Plugin</title>
+<indexterm zone="plugin-tools"><primary><command>abbrev</command></primary></indexterm>
+
+<para>
+This plugin expands abbreviations into frequently used code snippets. It is
+activated by pressing <keycombo><keycap>Ctrl</keycap>
+<keycap>Space</keycap></keycombo>. For example, when you enter
+<literal>"ife"</literal> into a C++ in the editor and press
+<keycombo><keycap>Ctrl</keycap><keycap>Space</keycap></keycombo>, you obtain
+an <literal>if-else</literal> code template and save some key strokes. The set
+of supported abbreviations depends on the programming language of the edited
+file. For example, for PHP you will obviously be interested in other code
+templates than for &Java;.
+</para>
+</formalpara>
+
+<para>
+The set of code templates is configurable. If the plugin is enabled, you can see
+which ones are available in the <menuchoice><guimenu>Settings</guimenu>
+<guimenuitem>Configure KDevelop...</guimenuitem></menuchoice>
+dialog under <guibutton>Abbreviations</guibutton>.
+</para>
+</listitem>
+
+<listitem>
+<formalpara id="KDevFilter">
+<title>The <command>filter</command> Plugin</title>
+<indexterm zone="plugin-tools"><primary><command>filter</command></primary></indexterm>
+
+<para>
+This offers two features. If you select <menuchoice><guimenu>Tools</guimenu>
+<guimenuitem>Execute command</guimenuitem></menuchoice>, you can enter a shell
+command. The output of this command is inserted into the editor buffer when
+you hit the <guibutton>Start</guibutton> button.
+</para>
+</formalpara>
+
+<para>
+A related feature is available under
+<menuchoice><guimenu>Tools</guimenu><guimenuitem>Filter selection through
+command...</guimenuitem></menuchoice>.  In order to use this, you must
+select a text area in the editor. If you now enter a shell command and hit
+the <guibutton>Start</guibutton> button, the command is started and the
+selection used as the standard input for it. The standard output of the
+command is then inserted into the editor, replacing the selection.
+</para>
+
+<para>
+For example, if you write documentation, you frequently have to refer
+to menu items. To do this correctly for e.g. the Copy command in the 
+Edit menu, you have to write:
+<programlisting>&lt;menuchoice&gt;&lt;guimenu&gt;Edit&lt;/guimenu&gt;&lt;guimenuitem&gt;Copy&lt;/guimenuitem&gt;&lt;/menuchoice&gt;</programlisting>
+This is cumbersome, so you'd rather just write "Edit - Copy"
+and let the computer do the tagging.
+Here is how you can do it.
+You write a little shell script called mef you put e.g. in your home's bin directory:
+<programlisting>sed s/"^\(.*\) - \(.*\)\$"/"&lt;menuchoice&gt;&lt;guimenu&gt;\1&lt;\/guimenu&gt;&lt;guimenuitem&gt;\2&lt;\/guimenuitem&gt;&lt;\/menuchoice&gt;"/</programlisting>
+Don't forget to make it executable.
+That's all. Now, in your documentation .docbook source, you write "Edit - Copy".
+You select this text you just wrote, choose
+<menuchoice><guimenu>Tools</guimenu><guimenuitem>Filter selection through
+command...</guimenuitem></menuchoice> and call ~/bin/mef.
+Instantly "Edit - Copy" is replaced by
+<programlisting>&lt;menuchoice&gt;&lt;guimenu&gt;Edit&lt;/guimenu&gt;&lt;guimenuitem&gt;Copy&lt;/guimenuitem&gt;&lt;/menuchoice&gt;</programlisting>
+</para>
+
+
+</listitem>
+
+<listitem>
+<formalpara>
+<title>The &doxygen; Plugin</title>
+<indexterm zone="plugin-tools"><primary>&doxygen;</primary></indexterm>
+<indexterm zone="plugin-tools"><primary>documentation tool</primary></indexterm>
+<indexterm zone="plugin-tools"><primary>API documentation</primary></indexterm>
+
+<para>
+This one helps you to use the &doxygen; API documentation tool
+(<ulink url="http://www.doxygen.org"/>). You can select
+<menuchoice><guimenu>Project</guimenu>
+<guimenuitem>Run Doxygen</guimenuitem></menuchoice> to generate API
+documentation for your current project, based on the configuration given by
+the file <filename>Doxyfile</filename> in your project directory.
+</para>
+</formalpara>
+
+<para>
+Furthermore, you can configure &doxygen; in the
+<menuchoice><guimenu>Project</guimenu>
+<guimenuitem>Project options...</guimenuitem></menuchoice> dialog. This dialog
+is very similar to the &doxywizard; tool.
+</para>
+</listitem>
+
+<listitem>
+<formalpara>
+<title>The &ctags; Plugin</title>
+<indexterm zone="plugin-tools"><primary>&ctags;</primary></indexterm>
+
+<para>
+Although the class browser gives you extensive insight into the symbols and
+classes of your project, you may also want to use the ctags tool. In particular,
+this one supports a lot more language than the class browser.
+</para>
+</formalpara>
+
+<para>
+You activate this plugin under <menuchoice><guimenu>Tools</guimenu>
+<guimenuitem>CTags...</guimenuitem></menuchoice>. When you start it the first
+time, you will be asked to generate a search database first. When you accept
+this, the &ctags; program will be started and will create a file named
+<filename>tags</filename> in your project directory. This is a text file containing
+all symbols of your source files.
+</para>
+
+<para>
+You can search in the symbol database in two ways: when the
+<guilabel>Regular expression match</guilabel> box is checked, the text you
+enter will be interpreted as a regular expression (POSIX flavor) and matched
+with the existing symbols. For example, the text <literal>.*Widget</literal>
+will search for all symbols ending with <literal>Widget</literal>. If the
+box is not checked, the search will be verbatim.
+</para>
+
+<para>
+When searching, you will get a list of the matched symbols, accompanied with
+the line numbers where they are defined. You jump to the respective point by
+clicking on the list.
+</para>
+
+<para>
+For some languages, &ctags; distinguishes different kinds of symbols. For
+example, Python has classes and functions. You can selectively search only
+for classes by checking the respecting kinds in the dialog.
+</para>
+
+<para>
+The symbol database is normally not updated when your sources change.
+Consequently, after a while the line numbers will not be correct anymore
+and newly added classes and functions will be missing. Therefore you should
+update the <filename>tags</filename> file in regular intervals by pressing
+the button <guibutton>Regenerate</guibutton>.
+</para>
+</listitem>
+
+<listitem>
+<formalpara>
+<title>The <command>astyle</command> Plugin</title>
+<indexterm zone="plugin-tools"><primary><command>astyle</command></primary></indexterm>
+<indexterm zone="plugin-tools"><primary><application>Artistic Style</application></primary></indexterm>
+<indexterm zone="plugin-tools"><primary>indentation</primary></indexterm>
+
+<para>
+Astyle is a plugin for formatting of sourcecode according to a specified set of rules.
+</para>
+</formalpara>
+</listitem>
+
+<listitem>
+<formalpara>
+<title>The <command>regexptest</command> Plugin</title>
+<indexterm zone="plugin-tools"><primary><command>regexptest</command></primary></indexterm>
+<indexterm zone="plugin-tools"><primary>debugging</primary><secondary>regular expressions</secondary></indexterm>
+<indexterm zone="plugin-tools"><primary>regular expressions</primary><secondary>debugging</secondary></indexterm>
+
+<para>
+Designing with regular expressions can be hard work. Often the first try at an
+expression matches too many strings. In particular, when working with a
+compiled language, the turnaround times when debugging a regular expression
+can be awkward. The regexptest plugin allows you to directly explore the
+changes in a regular expression. It is activated by choosing
+<menuchoice><guimenu>Tools</guimenu>
+<guimenuitem>Debug Regular Expression...</guimenuitem></menuchoice>.
+</para>
+</formalpara>
+
+<para>
+In the flavor group box, you can choose the flavor of the regular expression
+engine used. Currently supported is the flavor defined in the POSIX standard,
+which is used by the &grep; program, and the extended POSIX syntax used by the
+program &egrep;.
+</para>
+
+<para>
+When you enter an expression, you get immediate feedback about any syntax
+errors in it. By entering a text under <guilabel>Test string</guilabel>,
+you can see whether the expression matches this string. In particular, if
+your regular expression includes groups, such as <literal>([a-z])</literal>,
+the content of the matched subgroups will be shown in a list box.
+</para>
+</listitem>
+
+<!--
+<listitem>
+<formalpara>
+<title>The <command>konsole</command> Plugin</title>
+<indexterm zone="plugin-tools"><primary><command>konsole</command></primary></indexterm>
+<indexterm zone="plugin-tools"><primary>terminal</primary><secondary>embedded</secondary></indexterm>
+<para></para>
+</formalpara>
+</listitem>
+-->
+
+</itemizedlist>
+
+</appendix> <!-- plugin-tools -->
+
+<!-- ====================================================================== -->