Git commit 77b575a6f9e310aa6feb91e535721bd670182023 by Burkhard Lück. Committed on 07/05/2016 at 20:40. Pushed by lueck into branch 'master'.
sort sects about plugins to follow the order in plugin page in the settings dialog, add missing links M +1147 -1146 doc/kate/plugins.docbook http://commits.kde.org/kate/77b575a6f9e310aa6feb91e535721bd670182023 diff --git a/doc/kate/plugins.docbook b/doc/kate/plugins.docbook index 9021614..2a83a00 100644 --- a/doc/kate/plugins.docbook +++ b/doc/kate/plugins.docbook @@ -85,7 +85,7 @@ simple &gdb; frontend</para> Search or replace patterns in opened documents or in files on disk</para> </listitem> <listitem> -<para>Snippets tool view - Tool view embedding the snippets management</para> +<para><link linkend="kate-application-plugin-snippets">Snippets tool view</link> - Tool view embedding the snippets management</para> </listitem> <listitem> <para><link linkend="kate-application-plugin-sql">SQL Plugin</link> - Execute @@ -95,7 +95,7 @@ query on SQL databases</para> <para>Symbol Viewer - Extract and show reference symbols from source</para> </listitem> <listitem> -<para>Terminal tool view - Tool view embedding a terminal widget</para> +<para><link linkend="kate-application-plugin-konsole">Terminal tool view</link> - Tool view embedding a terminal widget</para> </listitem> <listitem> <para>Text Filter - Easy text filtering</para> @@ -107,1559 +107,1411 @@ attributes, attribute values and entities allowed by DTD</para> </itemizedlist> </sect1> -<!-- from doc/kate-addons/xmlcheck.docbook --> -<sect1 id="kate-application-plugin-xmltools"> +<sect1 id="kate-application-plugin-build"> +<!--http://kate-editor.org/2011/06/21/kate-plugin-updates-part-1/ --> <sect1info> -<authorgroup><author> -&Daniel.Naber; &Daniel.Naber.mail; -</author></authorgroup> +<authorgroup> +<author><firstname>Salma</firstname> <surname>Sultana</surname></author> +<author>&TC.Hollingsworth; &TC.Hollingsworth.mail;</author> +</authorgroup> </sect1info> -<title>&XML; Completion</title> +<title>Build Plugin</title> -<para>This plugin gives hints about what is allowed at a certain position in -an &XML; file, according to the file's DTD. It will list possible -elements, attributes, attribute values or entities, depending on the -cursor position (⪚ all entities are listed if the character on the left -of the cursor is <quote>&</quote>). It's also possible to close the nearest -open tag on the left.</para> +<sect2 id="build-intro"> +<title>Introduction</title> -<para>The <acronym>DTD</acronym> must exist in &XML; format, as produced by the Perl program -<command>dtdparse</command>. We will call a DTD in this format <quote>meta DTD</quote>. -Some meta DTDs are supplied. They are installed in -<filename class="directory">$KDEDIR/share/apps/katexmltools/</filename>, -which is also the default folder when you choose -<guimenuitem>Assign Meta DTD...</guimenuitem>. -To produce your own meta DTDs, get <command>dtdparse</command> from -<ulink url="http://dtdparse.sourceforge.net";>http://dtdparse.sourceforge.net</ulink>.</para> +<para>The Build plugin allows you to run actions like build, clean and compile +on a project.</para> -<sect2 id="xmltools-how-to-use"> -<title>How to Use</title> +</sect2> -<para>Start &kate; and open the configuration dialog under <menuchoice><guimenu>Settings</guimenu> -<guimenuitem>Configure &kate;...</guimenuitem></menuchoice>. -Then select <guilabel>&XML; Completion</guilabel> which will appear -in the <menuchoice><guimenu>Application</guimenu> -<guimenuitem>Plugins</guimenuitem></menuchoice> page and close the dialog. After -that, select <menuchoice><guimenu>&XML;</guimenu><guimenuitem>Assign Meta DTD...</guimenuitem></menuchoice>. -If your document contains no <quote>DOCTYPE</quote> or the doctype is unknown, you will have to -select a meta DTD from the file system. Otherwise the meta DTD that -matches the current document's DOCTYPE will be loaded automatically.</para> +<sect2 id="build-using"> +<title>Using the Build Plugin</title> -<para>You can now use the plugin while typing your text:</para> +<para>The Build plugin adds a <guilabel>Build Output</guilabel> tool view at the +bottom and a <guimenu>Build</guimenu> menu on the menubar. The tool view can be used to configure +build target settings, while the menu can be used to perform build, clean and +compile actions.</para> -<variablelist> -<varlistentry> -<term><keycap><</keycap> (less than key)</term> -<listitem><para>This will trigger a list of possible elements unless the -cursor is inside a tag already. Note that you currently cannot use -this to insert the top level element (⪚ <quote><html></quote>).</para></listitem> -</varlistentry> +<para>The <guilabel>Build Output</guilabel> tool view has three tabs:</para> + +<itemizedlist> +<listitem><para><guilabel>Target Settings</guilabel></para></listitem> +<listitem><para><guilabel>Output</guilabel></para></listitem> +<listitem><para><guilabel>Errors & Warnings</guilabel></para></listitem> +</itemizedlist> +<sect3 id="build-using-target-settings"> +<title>Target Settings tab</title> + +<para>The target settings tab can be used to configure various build targets.</para> + +<para>Each target contains four configuration options:</para> + +<variablelist> <varlistentry> -<term><keycap><</keycap><keycap>/</keycap>(less than key + slash)</term> -<listitem><para>Entering these characters will offer to close the current element -(nearest open one to the left of the cursor). Press &Enter; to accept the suggestion. -Unlike the <guimenuitem>Close Element</guimenuitem> menu item, this works only with -a DTD assigned.</para></listitem> +<term><guilabel>Working Directory</guilabel></term> +<listitem><para>You can set the path to the project here. Leave this empty to +use the directory the current document is located in.</para></listitem> </varlistentry> <varlistentry> -<term><keycap>"</keycap> (quote key)</term> -<listitem><para>The quote key will trigger a list of possible attribute -values (if there are any) if you are inside a tag.</para></listitem> +<term><guilabel>Build</guilabel></term> +<listitem><para>This option lets you define the build command. It is set to +<command>make</command> by default.</para></listitem> </varlistentry> <varlistentry> -<term><keycap> </keycap> (space key)</term> -<listitem><para>This key will trigger a list of possible attributes for the -current element if you are inside a tag.</para> -</listitem> +<term><guilabel>Clean</guilabel></term> +<listitem><para>The option lets you define the clean command. It is set to +<command>make clean</command> by default.</para></listitem> </varlistentry> <varlistentry> -<term><keycap>&</keycap> (ampersand key)</term> -<listitem><para>This key will trigger a list of named entities.</para></listitem> +<term><guilabel>Quick Compile</guilabel></term> +<listitem><para>This option lets you define the quick compile command. It is set +to <command>gcc -Wall -g %f</command> by default.</para></listitem> </varlistentry> </variablelist> -</sect2> +<para>One can create a new target by using the <guibutton>New</guibutton> button. +The <guibutton>Copy</guibutton> button can be used to make a copy of an existing +target. To delete a target, use the <guibutton>Delete</guibutton> button.</para> -<sect2 id="xmltools-features-and-limitations"> -<title>Features and Limitations</title> +</sect3> -<para>You can test all functions and limitations by loading -<filename>$KDEDIR/share/apps/katexmltools/testcases.xml</filename><!--FIXME replacement for KDEDIRS--> -into &kate; and following the instructions.</para> +<sect3 id="build-using-output"> +<title>Output tab</title> -</sect2> +<para>The <guilabel>Output</guilabel> tab shows the console output generated by +the last command.</para> +</sect3> -<sect2 id="xmltools-menu"> +<sect3 id="buiid-using-errors"> +<title>Errors & Warnings</title> + +<para>The <guilabel>Errors & Warnings</guilabel> tab lists the errors and +warnings generated by the last command.</para> + +<para>Each line contains a message and the file name and line number if available. +Clicking on the error or warning takes you to the appropriate file and places +the cursor on the corresponding line number.</para> + +<para>There are <guibutton>Errors</guibutton>, <guibutton>Warnings</guibutton>, +and <guibutton>Others</guibutton> buttons at the top that allow you to show +or hide those categories of output.</para> + +<!--FIXME: These shortcuts now seem to be used by the Project plugin in 4.11. + https://bugs.kde.org/show_bug.cgi?id=328170 --> +<para>To navigate to the previous error, press +<keycombo action="simul">&Ctrl;&Alt;<keysym>Left</keysym></keycombo>. +To navigate to the next error, press +<keycombo action="simul">&Ctrl;&Alt;<keysym>Right</keysym></keycombo>.</para> + +</sect3> +</sect2> + +<sect2 id="build-menu"> <title>Menu Structure</title> -<variablelist id="xml-insert-element"> +<variablelist id="build-build"> <varlistentry> <term><menuchoice> -<shortcut> -<keycombo action="simul">&Ctrl;<keycap>Return</keycap></keycombo> -</shortcut> -<guimenu>&XML;</guimenu> -<guimenuitem>Insert Element...</guimenuitem> +<guimenu>Build</guimenu><guimenuitem>Build</guimenuitem> </menuchoice></term> -<listitem><para>This will open a dialog that lets you insert an &XML; element. -The <, > characters and the closing tag will be inserted automatically. -If you have selected text when this menu item is selected, the selected -text will be surrounded by the opening and the closing tag. -The dialog also offers completion of all elements that may be inserted -at the current cursor position if you have assigned a meta DTD by -using <guimenuitem>Assign Meta DTD...</guimenuitem>. -</para></listitem> +<listitem><para>Runs the <guilabel>Build</guilabel> command for the currently +selected target.</para></listitem> </varlistentry> -<varlistentry id="xml-close-element"> +<varlistentry id="build-clean"> <term><menuchoice> -<shortcut> -<keycombo action="simul">&Ctrl;<keycap><</keycap></keycombo> -</shortcut> -<guimenu>&XML;</guimenu> -<guimenuitem>Close Element</guimenuitem> +<guimenu>Build</guimenu><guimenuitem>Clean</guimenuitem> </menuchoice></term> -<listitem><para>This will search your text for a tag that is not yet closed -and will close it by inserting the corresponding closing tag. -The search starts at the cursor position and goes left. If -it cannot find an open tag nothing will happen.</para></listitem> +<listitem><para>Runs the <guilabel>Clean</guilabel> command for the currently +selected target.</para></listitem> </varlistentry> -<varlistentry id="xml-assign-metadtd"> +<varlistentry id="build-compile"> <term><menuchoice> -<guimenu>&XML;</guimenu> -<guimenuitem>Assign Meta DTD...</guimenuitem> +<guimenu>Build</guimenu><guimenuitem>Quick Compile</guimenuitem> </menuchoice></term> -<listitem><para>This will tell the plugin which meta DTD to use for the -current document. Note that this assignment will not be saved. -You will have to repeat it when you start &kate; the next time.</para></listitem> +<listitem><para>Runs the <guilabel>Quick Compile</guilabel> command for the +currently selected target.</para></listitem> </varlistentry> -</variablelist> -</sect2> +<varlistentry id="build-previous-error"> +<term><menuchoice> +<shortcut><keycombo action="simul">&Ctrl;&Alt;<keysym>Left</keysym></keycombo></shortcut> +<guimenu>Build</guimenu><guimenuitem>Previous Error</guimenuitem> +</menuchoice></term> +<listitem><para>Moves the cursor to the location of the previous error in the +document.</para></listitem> +</varlistentry> -<sect2 id="xmltools-thanks-and-acknowledgements"> -<title>Thanks and Acknowledgments</title> -<para> -&kate; Plugin <quote>&XML; Completion</quote> copyright 2001,2002 &Daniel.Naber; -&Daniel.Naber.mail;. -</para> -<para>KDE SC 4 version copyright 2010 Tomáš Trnka</para> -<para>Documentation copyright 2001,2002 &Daniel.Naber;</para> -</sect2> -</sect1> +<varlistentry id="build-next-error"> +<term><menuchoice> +<shortcut><keycombo action="simul">&Ctrl;&Alt;<keysym>Right</keysym></keycombo></shortcut> +<guimenu>Build</guimenu><guimenuitem>Next Error</guimenuitem> +</menuchoice></term> +<listitem><para>Moves the cursor to the location of the next error in the +document.</para></listitem> +</varlistentry> -<sect1 id="kate-application-plugin-searchinfiles"> -<sect1info> -<authorgroup><author> -&TC.Hollingsworth; &TC.Hollingsworth.mail; -</author></authorgroup> -</sect1info> -<title>Search & Replace</title> +<varlistentry> +<term><menuchoice id="build-targets"> +<guimenu>Build</guimenu><guisubmenu>Targets</guisubmenu> +</menuchoice></term> +<listitem><para>Select from a list of targets configured by the user.</para></listitem> +</varlistentry> -<sect2 id="searchinfiles-intro"> -<title>Introduction</title> -<para>&kappname;'s Search & Replace plugin allows you to search for text or -<ulink url="help:/katepart/regular-expressions.html">regular expressions</ulink> -in many different files at once. You can search all open files, all the files -in one directory and optionally its subdirectories, or all files in the current -project. You can even filter by filename, for instance searching only files -that end with a particular file extension.</para> +<varlistentry> +<term><menuchoice id="build-next-target"> +<guimenu>Build</guimenu><guimenuitem>Next Target</guimenuitem> +</menuchoice></term> +<listitem><para>Switch to the next target configured by the user.</para></listitem> +</varlistentry> +</variablelist> </sect2> -<sect2 id="searchinfiles-ui"> -<title>Interface</title> +<sect2 id="build-ack"> +<title>Thanks and Acknowledgments</title> +<para>The &kate; Build Plugin was written by Kåre Särs.</para> +<para>Special thanks to Google Code-In 2011 participant Salma Sultana for +writing much of this section.</para> +</sect2> +</sect1> -<sect3 id="searchinfiles-ui-query"> -<title>Search Query</title> +<sect1 id="kate-application-plugin-fsbrowser"> -<para>The following options are always displayed at the top of the Search in -Files tool view:</para> +<title>Filesystem Browser</title> -<variablelist> +<para>The Filesystem Browser is a folder viewer, allowing you to open +files from a displayed folder in the current frame.</para> -<varlistentry> -<term><guiicon>New Tab</guiicon></term> -<listitem><para> -You can have as many searches as you want open at the same time. Simply click -the <guibutton>New Tab</guibutton> button at the top-left corner of the Search -tool view and a new results tab will open permitting you to perform another -search. -</para></listitem> -</varlistentry> +<sect2 id="fsbrowser-menu"> +<title>Menu Structure</title> +<variablelist> -<varlistentry> -<term><guiicon>Toggle Results</guiicon></term> -<listitem><para> -The down arrow in the top right-corner of the Search in Files tool view will -toggle the bottom half of the tool view between displaying additional options -for the Search in Folder mode and the results of your search. -</para></listitem> +<varlistentry id="view-toolviews-show-filebrowser"> +<term><menuchoice> +<guimenu>View</guimenu><guisubmenu>Tool Views</guisubmenu> +<guimenuitem>Show Filesystem Browser</guimenuitem> +</menuchoice></term> +<listitem> +<para>Toggle the display of &kate;'s Filesystem Browser.</para> +</listitem> </varlistentry> -<varlistentry> -<term><guilabel>Find</guilabel></term> -<listitem><para> -This is where you type in what you want to find. You may enter standard text, -or a regular expression if enabled. -</para></listitem> -</varlistentry> +</variablelist> +</sect2> -<varlistentry> -<term><guilabel>Replace</guilabel> (text box)</term> -<listitem><para> -Replacement text that will be added to file(s) in place of the text in the -<guilabel>Find</guilabel> text box. -</para></listitem> -</varlistentry> +<sect2 id="fsbrowser-interface"> +<title>Interface</title> -<varlistentry> -<term><guibutton>Search</guibutton></term> -<listitem><para> -When you've finished configuring everything, just press the -<guibutton>Search</guibutton> button to perform your search. You may also press -&Enter; in the <guilabel>Find</guilabel> text box to do the same. -</para></listitem> -</varlistentry> +<para>From the top down, the Filesystem Browser consists of the following +elements:</para> +<variablelist> <varlistentry> -<term><guibutton>Replace</guibutton></term> -<listitem><para> -When you've finished configuring everything, just press the -<guibutton>Replace</guibutton> button to replace the text entered in the -<guilabel>Find</guilabel> text box with that of the <guilabel>Replace</guilabel> -text box. You may also press &Enter; in the <guilabel>Replace</guilabel> text -box to do the same. -</para></listitem> -</varlistentry> - +<term>A Toolbar</term> +<listitem> +<para>This contains standard navigations tool buttons:</para> +<variablelist> <varlistentry> -<term><guibutton>Next</guibutton></term> -<listitem><para> -Go to the next match of your search query, switching files if necessary. -</para></listitem> +<term><guibutton>Back</guibutton></term> +<listitem><para>Causes the folder view to <command>cd</command> to the previously displayed folder in the history. +This button is disabled, if there is no previous item.</para></listitem> </varlistentry> - <varlistentry> -<term><guibutton>Replace checked</guibutton></term> -<listitem><para> -The same as <guibutton>Replace</guibutton>, but will only perform replacements -in files that are checked in the pane below. -</para></listitem> +<term><guibutton>Forward</guibutton></term> +<listitem><para>Causes the folder view to <command>cd</command> to the next folder in the history. +This button is disabled, if there is no next folder.</para></listitem> </varlistentry> - -</variablelist> -</sect3> - -<sect3 id="searchinfiles-ui-folder"> -<title>Search in Folder Options</title> - -<para>These options are displayed below the aforementioned query options. If search -results are being displayed instead, press the <guiicon>Toggle Results</guiicon> -button to display them.</para> - -<variablelist> - +<!--varlistentry> +<term><guibutton>Parent Folder</guibutton></term> +<listitem><para>This will cause the folder view to <command>cd</command> to the immediate parent of the currently displayed +folder if possible.</para></listitem> +</varlistentry--> <varlistentry> -<term><guilabel>Match case</guilabel></term> -<listitem><para> -Restricts search results to only those that have the exact same combination -of upper and lower case letters as your search query. -</para></listitem> +<term><guibutton>Bookmarks</guibutton></term> +<listitem><para>Opens a submenu to edit or add bookmarks and to add a new bookmark folder.</para></listitem> </varlistentry> - <varlistentry> -<term><guilabel>Regular expressions</guilabel></term> -<listitem><para> -Permits you to use <ulink url="help:/katepart/regular-expressions.html">regular -expressions</ulink> instead of simple text as your search query. -</para></listitem> +<term><guibutton>Current Document Folder</guibutton></term> +<listitem><para>This button will cause the folder view to +<command>cd</command> to the folder of the currently active +document if possible. This button is disabled, if the active document +is a new, unsaved file, or the folder in which it resides can not +be decided.</para></listitem> </varlistentry> - <varlistentry> -<term><guilabel>Expand results</guilabel></term> -<listitem><para> -Display all the results found in each file, instead of just a list of files -that contain the search query. -</para></listitem> -</varlistentry> - +<term><guibutton>Options</guibutton></term> +<listitem> +<variablelist> <varlistentry> -<term><guilabel>Search</guilabel></term> -<listitem><para> -This has three options. Select <guilabel>in Open files</guilabel> to search all -files currently open in &kappname;. Select <guilabel>in Folder</guilabel> to -search inside a folder and optionally its subfolders. Select <guilabel>in -Project</guilabel> to search all the files listed in the currently open project. -</para></listitem> +<term><guimenuitem>Short View</guimenuitem></term> +<listitem><para>Displays only the filenames.</para></listitem> </varlistentry> - <varlistentry> -<term><guilabel>Folder</guilabel></term> -<listitem><para> -You may enter the path of the folder you wish to search. For instance, you might -enter <userinput>~/development/kde/kate/</userinput> if you wished to search the -&kate; source code. This option is only available when using -<guilabel>in Folder</guilabel> mode. -</para></listitem> +<term><guimenuitem>Detailed View</guimenuitem></term> +<listitem><para>Displays <guilabel>Name</guilabel>, <guilabel>Date</guilabel>, +<guilabel>Size</guilabel> and <guilabel>Type</guilabel> of the files.</para></listitem> </varlistentry> - <varlistentry> -<term><guiicon>Open file dialog</guiicon></term> -<listitem><para> -Press this button to locate the folder in your desktop's folder browser. This -button only works when using <guilabel>in Folder</guilabel> mode. -</para></listitem> +<term><guimenuitem>Tree View</guimenuitem></term> +<listitem><para>Like Short View, but folders can be expanded to view their contents.</para></listitem> </varlistentry> - <varlistentry> -<term><guiicon>Up</guiicon></term> -<listitem><para> -Press this button to change <guilabel>Folder</guilabel> to the parent of the -currently selected folder. This button only works when using -<guilabel>in Folder</guilabel> mode. -</para></listitem> +<term><guimenuitem>Detailed Tree View</guimenuitem></term> +<listitem><para>This also allows folders to be expanded, but displays the additional columns +available in Detailed View.</para></listitem> </varlistentry> - <varlistentry> -<term><guiicon>Restore Current Folder</guiicon></term> -<listitem><para> -This button will set the <guilabel>Folder</guilabel> entry to the folder in which -the currently open document is located. This button only works when using -<guilabel>in Folder</guilabel> mode. -</para></listitem> +<term><guimenuitem>Show Hidden Files</guimenuitem></term> +<listitem><para>Displays files normally hidden by your &OS;.</para></listitem> </varlistentry> - <varlistentry> -<term><guilabel>Filter</guilabel></term> -<listitem><para> -This permits you to only search filenames that match a particular pattern. For -instance, to only search files written in C++, change it to -<userinput>*.cpp</userinput>. To search only files beginning with -<literal>kate</literal>, change it to <userinput>kate*</userinput>. You can -enter multiple filters separated with a comma (<userinput>,</userinput>). This -option is not available when using <guilabel>in Open files</guilabel> mode. -</para></listitem> +<term><guimenuitem>Automatically synchronize with current document</guimenuitem></term> +<listitem><para>When this option is enabled the filesystem browser will automatically <command>cd</command> +to the folder of the document currently open in the editing area every time it changes.</para></listitem> </varlistentry> - -<varlistentry> -<term><guilabel>Exclude</guilabel></term> -<listitem><para> -The opposite of <guilabel>Filter</guilabel>, this prevents &kappname; from -searching files that match the specified patterns. As with -<guilabel>Filter</guilabel>, you can enter multiple patterns separated with a -comma (<userinput>,</userinput>). This option is not available when using -<guilabel>in Open files</guilabel> mode. -</para></listitem> +</variablelist> +</listitem> +</varlistentry> +</variablelist> +</listitem> </varlistentry> <varlistentry> -<term><guilabel>Recursive</guilabel></term> -<listitem><para> -If this option is enabled, &kappname; will also search in all subfolders of the -selected folder. This option is only available when using -<guilabel>in Folder</guilabel> mode. -</para></listitem> +<term>A Location Entry</term> +<listitem> +<para>This displays a breadcrumb navigation to the currently open folder, similarly to +&dolphin;. You can click on a any folder to browse to it, or click on one of the +arrows to the left of a folder to select any folders beneath it. You may also +select from your list of Places by clicking the leftmost icon in the breadcrumb +navigation, which displays an icon that represents your current Place.</para> + +<para>You can also click to the right of the breadcrumbs to change them to a text box +where you can type the path of a folder to browse. The &URL; +entry maintains a list of previously typed paths. To choose one, use +the arrow button to the right of the entry.</para> +<tip><para>The &URL; entry has folder auto-completion. The completion +method can be set using the &RMB; menu of the text +entry.</para></tip> +</listitem> </varlistentry> <varlistentry> -<term><guilabel>Include hidden</guilabel></term> -<listitem><para> -If this option is enabled, &kappname; will also search in files or folders that -are typically hidden by your &OS;. This option is only available when using -<guilabel>in Folder</guilabel> mode. -</para></listitem> +<term>A Folder View</term> +<listitem><para>This is a standard &kde; folder view.</para></listitem> </varlistentry> <varlistentry> -<term><guilabel>Follow symbolic links</guilabel></term> -<listitem><para> -The Search in Files plugin typically doesn't follow -<ulink url="http://en.wikipedia.org/wiki/Symbolic_link";>symbolic links</ulink>. -When this option is enabled, the plugin will follow them instead and search inside -the files or folders they reference. This option is only available when using -<guilabel>in Folder</guilabel> mode. -</para> -<warning><para>It's possible for symbolic links to reference a folder that is the -parent of the folder currently being searched, or other folders that contain -symbolic links to their parent. If there is such a link in the folder being -searched and this option is enabled, &kappname; will repeatedly follow the link -and search the folder, and the search will never complete.</para></warning> +<term>A Filter Entry</term> +<listitem> +<para>The Filter entry allows you to enter a filter for the files +displayed in the folder view. The filter uses standard globs; patterns +must be separated by white space. Example: <userinput>*.cpp *.h +*.moc</userinput></para> +<para>To display all files, enter a single asterisk +<userinput>*</userinput>.</para> +<para>The filter entry saves the last 10 filters entered between +sessions. To use one, press the arrow button on the right of the entry +and select the desired filter string. You can disable the filter by pressing +the <guibutton>Clear text</guibutton> button to the left of the autocompletion +arrow button.</para> </listitem> </varlistentry> +</variablelist> +</sect2> + + +<sect2 id="fsbrowser-config"> +<title>Configuration</title> + +<para>This plugin can be configured on the <guilabel>Filesystem Browser</guilabel> page +of <link linkend="configuring-kate-configdialog">&kate;'s configuration</link>.</para> + +<variablelist> <varlistentry> -<term><guilabel>Include binary files</guilabel></term> -<listitem><para> -If enabled, &kappname; will also search in files that do not appear to be text -files. -</para></listitem> +<term><guilabel>Toolbar</guilabel></term> +<listitem><para>Configure the buttons on the Filesystem Browser toolbar +by moving the ones you want enabled to the <guilabel>Selected Actions</guilabel> +list, and order them using the arrow buttons at the side of the list.</para> + </listitem> </varlistentry> </variablelist> -</sect3> +</sect2> +</sect1> -<sect3 id="searchinfiles-ui-results"> -<title>Search Results</title> +<sect1 id="kate-application-plugin-gdb"> +<!--http://kate-editor.org/2011/06/23/kate-plugin-updates-part-2/--> +<sect1info> +<authorgroup> +<author><firstname>Martin</firstname> <surname>Gergov</surname></author> +<author>&TC.Hollingsworth; &TC.Hollingsworth.mail;</author> +</authorgroup> +</sect1info> +<title>&gdb; Plugin</title> -<para>The results of your search are displayed below the query options. If -options for Search in Folder mode are displayed, simply press the -<guiicon>Toggle Results</guiicon> button to display them. They will also -automatically be displayed as soon as a search is performed.</para> +<sect2 id="gdb-intro"> +<title>Introduction</title> -<para>The search results display a list of files that contains text that matches -your search query, followed by the number of matches found in that file.</para> +<para>&kappname;'s &gdb; plugin provides a simple frontend to the popular &GNU; +Project Debugger.</para> -<para>To see a list of matches in that file, simply click the expansion arrow -to the left of the file name. (If you selected the <guilabel>Expand -results</guilabel> option, this will already be done for you.) The line number -each match is found on will be displayed, followed by the contents of that line, -with your search query indicated in bold text.</para> +<important> +<para>Previous experience with &gdb; is strongly recommended. For more +information on using &gdb;, visit <ulink url="http://www.gnu.org/s/gdb/";>the +&gdb; website</ulink>.</para> +</important> -<para>To open the file your result was found in, simply double-click it. &kappname; -will open the file if needed. You can also move the cursor to the location of -a particular match by double-clicking on its listing instead of the file name. +<para>You can enable the &gdb; plugin in +<link linkend="config-dialog-plugins">the Plugins section of &kappname;'s +configuration</link>.</para> + +<para>For the plugin to work properly, you must have a source file (of any type +supported by &gdb;) and an executable.</para> + +<tip> +<para>If you compile using &gcc;/<command>g++</command> you might want to use +the <command><parameter>-ggdb</parameter></command> command line argument. </para> +</tip> + +<para>After these preparations are made, open the source file in &kappname;, +enter the path to the executable in the <guilabel>Settings</guilabel> tab of the +<guilabel>Debug View</guilabel> tool view, and select +<menuchoice><guimenu>Debug</guimenu><guimenuitem>Start Debugging</guimenuitem></menuchoice> +from the menu to get started.</para> -</sect3> </sect2> -<sect2 id="searchinfiles-menu"> -<title>Menu Structure</title> +<sect2 id="gdb-menus"> +<title>Menu and Toolbar Structure</title> + +<para>All of these options are available in &kappname;'s menus, and many are +available on the Debug toolbar as well.</para> <variablelist> -<varlistentry id="edit-searchinfiles"> +<varlistentry id="gdb-menus-show-debug-view"> <term><menuchoice> -<guimenu>Edit</guimenu> -<guimenuitem>Search in Files</guimenuitem> +<guimenu>View</guimenu><guisubmenu>Tool View</guisubmenu><guimenuitem>Show Debug View</guimenuitem> </menuchoice></term> -<listitem> -<para>Launches the Search and Replace tool view.</para> -</listitem> +<listitem><para>Shows a tool view containing &gdb; output, the &gdb; command +line used, and other settings.</para></listitem> </varlistentry> -<varlistentry id="edit-next-match"> +<varlistentry id="gdb-menus-show-locals"> <term><menuchoice> -<guimenu>Edit</guimenu> -<guimenuitem>Go to Next Match</guimenuitem> +<guimenu>View</guimenu><guisubmenu>Tool View</guisubmenu><guimenuitem>Show Locals</guimenuitem> </menuchoice></term> -<listitem> -<para>Go to the next match in a search performed by the Search and Replace -plugin.</para> -</listitem> +<listitem><para>Shows a list of all currently loaded variables and their values. +</para></listitem> </varlistentry> -<varlistentry id="edit-previous-match"> +<varlistentry id="gdb-menus-show-call-stack"> <term><menuchoice> -<guimenu>Edit</guimenu> -<guimenuitem>Go to Previous Match</guimenuitem> +<guimenu>View</guimenu><guisubmenu>Tool View</guisubmenu><guimenuitem>Show Call Stack</guimenuitem> </menuchoice></term> -<listitem> -<para>Go to the previous match in a search performed by the Search and Replace -plugin.</para> -</listitem> +<listitem><para>Shows a &gdb; backtrace.</para></listitem> </varlistentry> -<varlistentry id="view-toolviews-searchandreplace"> +<varlistentry id="gdb-menus-targets"> <term><menuchoice> -<guimenu>View</guimenu><guisubmenu>Tool Views</guisubmenu> -<guimenuitem>Show Search and Replace</guimenuitem> +<guimenu>Debug</guimenu><guisubmenu>Targets</guisubmenu> </menuchoice></term> -<listitem> -<para>Toggle the display of &kappname;'s <guilabel>Search and Replace</guilabel> tool. -</para> -</listitem> +<listitem><para>A submenu containing a list of targets (executables). +</para></listitem> </varlistentry> -</variablelist> +<varlistentry id="gdb-menus-arg-lists"> +<term><menuchoice> +<guimenu>Debug</guimenu><guisubmenu>Arg Lists</guisubmenu> +</menuchoice></term> +<listitem><para>A submenu containing all argument lists.</para></listitem> +</varlistentry> -</sect2> -</sect1> +<varlistentry id="gdb-menus-start"> +<term><menuchoice> +<guimenu>Debug</guimenu><guimenuitem>Start Debugging</guimenuitem> +</menuchoice></term> +<listitem><para>Starts &gdb; with a target.</para></listitem> +</varlistentry> -<sect1 id="kate-application-plugin-fsbrowser"> +<varlistentry id="gdb-menus-kill"> +<term><menuchoice> +<guimenu>Debug</guimenu><guimenuitem>Kill / Stop Debugging</guimenuitem> +</menuchoice></term> +<listitem><para>Stops &gdb;.</para></listitem> +</varlistentry> -<title>Filesystem Browser</title> +<varlistentry id="gdb-menus-restart"> +<term><menuchoice> +<guimenu>Debug</guimenu><guimenuitem>Restart Debugging</guimenuitem> +</menuchoice></term> +<listitem><para>Restarts &gdb;.</para></listitem> +</varlistentry> -<para>The Filesystem Browser is a folder viewer, allowing you to open -files from a displayed folder in the current frame.</para> +<varlistentry id="gdb-menus-break"> +<term><menuchoice> +<guimenu>Debug</guimenu><guimenuitem>Toggle Breakpoint / Break</guimenuitem> +</menuchoice></term> +<listitem><para>Set a breakpoint at the current cursor position. +</para></listitem> +</varlistentry> -<sect2 id="fsbrowser-menu"> -<title>Menu Structure</title> -<variablelist> +<varlistentry id="gdb-menus-step-in"> +<term><menuchoice> +<guimenu>Debug</guimenu><guimenuitem>Step In</guimenuitem> +</menuchoice></term> +<listitem><para>Execute the present statement (function call will be debugged). +</para></listitem> +</varlistentry> -<varlistentry id="view-toolviews-show-filebrowser"> +<varlistentry id="gdb-menus-step-over"> <term><menuchoice> -<guimenu>View</guimenu><guisubmenu>Tool Views</guisubmenu> -<guimenuitem>Show Filesystem Browser</guimenuitem> +<guimenu>Debug</guimenu><guimenuitem>Step Over</guimenuitem> </menuchoice></term> -<listitem> -<para>Toggle the display of &kate;'s Filesystem Browser.</para> -</listitem> +<listitem><para>Execute the present statement (function call will not be +debugged).</para></listitem> +</varlistentry> + +<varlistentry id="gdb-menus-step-out"> +<term><menuchoice> +<guimenu>Debug</guimenu><guimenuitem>Step Out</guimenuitem> +</menuchoice></term> +<listitem><para>Resumes execution until the program that is executing +terminates.</para></listitem> +</varlistentry> + +<varlistentry id="gdb-menus-move-pc"> +<term><menuchoice> +<guimenu>Debug</guimenu><guimenuitem>Move PC</guimenuitem> +</menuchoice></term> +<listitem><para>Move program counter (next execution).</para></listitem> +</varlistentry> + +<varlistentry id="gdb-menus-run-to-cursor"> +<term><menuchoice> +<guimenu>Debug</guimenu><guimenuitem>Run To Cursor</guimenuitem> +</menuchoice></term> +<listitem><para>Runs the program until it reaches current cursor position. +</para></listitem> +</varlistentry> + +<varlistentry id="gdb-menus-continue"> +<term><menuchoice> +<guimenu>Debug</guimenu><guimenuitem>Continue</guimenuitem> +</menuchoice></term> +<listitem><para>Ignores any breakpoints and executes program until it terminates +(successfully or not).</para></listitem> +</varlistentry> + +<varlistentry id="gdb-menus-print-value"> +<term><menuchoice> +<guimenu>Debug</guimenu><guimenuitem>Print Value</guimenuitem> +</menuchoice></term> +<listitem><para>Prints the value of the variable that the cursor is currently +pointing to.</para></listitem> +</varlistentry> + +<varlistentry id="gdb-menus-toolbar"> +<term><menuchoice> +<guimenu>Settings</guimenu><guisubmenu>Toolbars Shown</guisubmenu><guimenuitem>&gdb; Plugin</guimenuitem> +</menuchoice></term> +<listitem><para>Display the debugging toolbar.</para></listitem> </varlistentry> </variablelist> + </sect2> -<sect2 id="fsbrowser-interface"> -<title>Interface</title> +<sect2 id="gdb-debug-view"> +<title>Debug View</title> -<para>From the top down, the Filesystem Browser consists of the following -elements:</para> +<para>The <guilabel>Debug View</guilabel> tool view consists of several tabs: +</para> <variablelist> + <varlistentry> -<term>A Toolbar</term> +<term><guilabel>&gdb; Output</guilabel></term> <listitem> -<para>This contains standard navigations tool buttons:</para> -<variablelist> -<varlistentry> -<term><guibutton>Back</guibutton></term> -<listitem><para>Causes the folder view to <command>cd</command> to the previously displayed folder in the history. -This button is disabled, if there is no previous item.</para></listitem> -</varlistentry> -<varlistentry> -<term><guibutton>Forward</guibutton></term> -<listitem><para>Causes the folder view to <command>cd</command> to the next folder in the history. -This button is disabled, if there is no next folder.</para></listitem> -</varlistentry> -<!--varlistentry> -<term><guibutton>Parent Folder</guibutton></term> -<listitem><para>This will cause the folder view to <command>cd</command> to the immediate parent of the currently displayed -folder if possible.</para></listitem> -</varlistentry--> -<varlistentry> -<term><guibutton>Bookmarks</guibutton></term> -<listitem><para>Opens a submenu to edit or add bookmarks and to add a new bookmark folder.</para></listitem> -</varlistentry> -<varlistentry> -<term><guibutton>Current Document Folder</guibutton></term> -<listitem><para>This button will cause the folder view to -<command>cd</command> to the folder of the currently active -document if possible. This button is disabled, if the active document -is a new, unsaved file, or the folder in which it resides can not -be decided.</para></listitem> +<para>Contains output from &gdb; and a &gdb; command line.</para> + +<screenshot id="screenshot-gdb-output"> +<screeninfo>The Output Tab</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="gdb-output.png" format="PNG"/></imageobject> +<textobject><phrase>The Output tab.</phrase></textobject> +<caption><para>The <guilabel>Output</guilabel> tab displaying the output from a +debugging session.</para></caption> +</mediaobject> +</screenshot> + +</listitem> </varlistentry> + <varlistentry> -<term><guibutton>Options</guibutton></term> +<term><guilabel>Settings</guilabel></term> <listitem> <variablelist> + <varlistentry> -<term><guimenuitem>Short View</guimenuitem></term> -<listitem><para>Displays only the filenames.</para></listitem> -</varlistentry> -<varlistentry> -<term><guimenuitem>Detailed View</guimenuitem></term> -<listitem><para>Displays <guilabel>Name</guilabel>, <guilabel>Date</guilabel>, -<guilabel>Size</guilabel> and <guilabel>Type</guilabel> of the files.</para></listitem> +<term><guilabel>Target</guilabel></term> +<listitem><para>Path to the target (executable) for debugging.</para></listitem> </varlistentry> + <varlistentry> -<term><guimenuitem>Tree View</guimenuitem></term> -<listitem><para>Like Short View, but folders can be expanded to view their contents.</para></listitem> +<term><guilabel>Working Directory</guilabel></term> +<listitem><para>The current working directory provided to the target. +</para></listitem> </varlistentry> + <varlistentry> -<term><guimenuitem>Detailed Tree View</guimenuitem></term> -<listitem><para>This also allows folders to be expanded, but displays the additional columns -available in Detailed View.</para></listitem> +<term><guilabel>Arg List</guilabel></term> +<listitem><para>Arguments passed to the program.</para></listitem> </varlistentry> + <varlistentry> -<term><guimenuitem>Show Hidden Files</guimenuitem></term> -<listitem><para>Displays files normally hidden by your &OS;.</para></listitem> +<term><guilabel>Keep focus</guilabel></term> +<listitem><para>Keeps focus on the &gdb; command line.</para></listitem> </varlistentry> + <varlistentry> -<term><guimenuitem>Automatically synchronize with current document</guimenuitem></term> -<listitem><para>When this option is enabled the filesystem browser will automatically <command>cd</command> -to the folder of the document currently open in the editing area every time it changes.</para></listitem> -</varlistentry> -</variablelist> -</listitem> +<term><guilabel>Redirect IO</guilabel></term> +<listitem><para>Opens a new <guilabel>IO</guilabel> tab in the <guilabel>Debug +View</guilabel> where you can view output and provide input to the running +program.</para></listitem> </varlistentry> + </variablelist> -</listitem> -</varlistentry> -<varlistentry> -<term>A Location Entry</term> -<listitem> -<para>This displays a breadcrumb navigation to the currently open folder, similarly to -&dolphin;. You can click on a any folder to browse to it, or click on one of the -arrows to the left of a folder to select any folders beneath it. You may also -select from your list of Places by clicking the leftmost icon in the breadcrumb -navigation, which displays an icon that represents your current Place.</para> +<screenshot id="screenshot-gdb-settings"> +<screeninfo>The Settings Tab</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="gdb-settings.png" format="PNG"/></imageobject> +<textobject><phrase>The Settings tab.</phrase></textobject> +<caption><para>The <guilabel>Settings</guilabel> tab displaying the configuration +of a debugging session.</para></caption> +</mediaobject> +</screenshot> -<para>You can also click to the right of the breadcrumbs to change them to a text box -where you can type the path of a folder to browse. The &URL; -entry maintains a list of previously typed paths. To choose one, use -the arrow button to the right of the entry.</para> -<tip><para>The &URL; entry has folder auto-completion. The completion -method can be set using the &RMB; menu of the text -entry.</para></tip> </listitem> </varlistentry> <varlistentry> -<term>A Folder View</term> -<listitem><para>This is a standard &kde; folder view.</para></listitem> -</varlistentry> - -<varlistentry> -<term>A Filter Entry</term> +<term><guilabel>IO</guilabel></term> <listitem> -<para>The Filter entry allows you to enter a filter for the files -displayed in the folder view. The filter uses standard globs; patterns -must be separated by white space. Example: <userinput>*.cpp *.h -*.moc</userinput></para> -<para>To display all files, enter a single asterisk -<userinput>*</userinput>.</para> -<para>The filter entry saves the last 10 filters entered between -sessions. To use one, press the arrow button on the right of the entry -and select the desired filter string. You can disable the filter by pressing -the <guibutton>Clear text</guibutton> button to the left of the autocompletion -arrow button.</para> +<para>Contains an area that displays output from the running program and a +command line where you may provide input to it.</para> + +<screenshot id="screenshot-gdb-io"> +<screeninfo>The IO Tab</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="gdb-io.png" format="PNG"/></imageobject> +<textobject><phrase>The IO tab.</phrase></textobject> +<caption><para>The <guilabel>IO</guilabel> tab displaying output from a simple +test program.</para></caption> +</mediaobject> +</screenshot> + </listitem> </varlistentry> </variablelist> -</sect2> +</sect2> -<sect2 id="fsbrowser-config"> -<title>Configuration</title> +<sect2 id="gdb-other"> +<title>Call Stack and Locals</title> -<para>This plugin can be configured on the <guilabel>Filesystem Browser</guilabel> page -of <link linkend="configuring-kate-configdialog">&kate;'s configuration</link>.</para> +<para>The <guilabel>Call Stack</guilabel> tool view contains a list of the formatted +backtrace returned from &gdb;.</para> -<variablelist> -<varlistentry> -<term><guilabel>Toolbar</guilabel></term> -<listitem><para>Configure the buttons on the Filesystem Browser toolbar -by moving the ones you want enabled to the <guilabel>Selected Actions</guilabel> -list, and order them using the arrow buttons at the side of the list.</para> - </listitem> -</varlistentry> +<screenshot id="screenshot-gdb-call-stack"> +<screeninfo>The &gdb; Call Stack Tool View</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="gdb-call-stack.png" format="PNG"/></imageobject> +<textobject><phrase>The Call Stack tool view.</phrase></textobject> +<caption><para>The &gdb; Plugin's <guilabel>Call Stack</guilabel> tool view. +</para></caption> +</mediaobject> +</screenshot> -</variablelist> -</sect2> -</sect1> +<para>The <guilabel>Locals</guilabel> tool view contains a list of all currently +loaded variables from the program and their corresponding values.</para> - <!-- - FIXME: replaced by built-in functionality in 4.12 - lots of this is wrong, other parts need to be moved somewhere else --> -<sect1 id="kate-application-plugin-snippets"> -<sect1info> -<authorgroup> -<author><firstname>Martin</firstname> <surname>Gergov</surname></author> -<author>&TC.Hollingsworth; &TC.Hollingsworth.mail;</author> -</authorgroup> -</sect1info> -<title>Kate Snippets</title> +<screenshot id="screenshot-gdb-locals"> +<screeninfo>The &gdb; Locals Tool View</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="gdb-locals.png" format="PNG"/></imageobject> +<textobject><phrase>The Locals tool view.</phrase></textobject> +<caption><para>The &gdb; Plugin's <guilabel>Locals</guilabel> tool view. +</para></caption> +</mediaobject> +</screenshot> -<sect2 id="snippets-intro"> -<title>Introduction</title> -<para>Kate Snippets is a plugin used to save you some time by adding support for -so-called <quote>snippets</quote> (re-usable source code, machine code or text). The plugin -also supports code completion and QtScript.</para> </sect2> -<sect2 id="snippets-menu"> -<title>Menu Structure</title> +<sect2 id="gdb-ack"> +<title>Thanks and Acknowledgments</title> -<variablelist> -<varlistentry> -<term><menuchoice><guimenu>View</guimenu><guisubmenu>Tool Views</guisubmenu> -<guimenuitem>Show Snippets</guimenuitem></menuchoice></term> -<listitem><para>Shows snippets panel containing all snippets in your repository -that are for the currently opened file type.</para></listitem> -</varlistentry> -</variablelist> +<para>Special thanks to Google Code-In 2011 participant Martin Gergov for +writing much of this section.</para> </sect2> -<sect2 id="snippets-panel"> -<title>Snippets panel</title> - -<screenshot id="screenshot-snippets-panel"> -<screeninfo>Kate Snippets Panel</screeninfo> -<mediaobject> -<imageobject><imagedata fileref="snippets-panel.png" format="PNG"/></imageobject> -<textobject><phrase>The &kate; snippets panel.</phrase></textobject> -<caption><para>The panel for &kate; Snippets.</para></caption> -</mediaobject> -</screenshot> +</sect1> -<para>In the panel you should see a list of snippet repositories, -along with options to create your own, get them from the Internet or load -them from a local file. Each repository has a checkbox that can be used to -activate or deactivate it. There are also buttons to edit and delete existing -repositories.</para> +<sect1 id="kate-application-plugin-searchinfiles"> +<sect1info> +<authorgroup><author> +&TC.Hollingsworth; &TC.Hollingsworth.mail; +</author></authorgroup> +</sect1info> +<title>Search & Replace</title> -<sect3 id="snippets-repo-internet"> -<title>Loading Snippet Repository Files</title> -<para>You can download snippet repositories from the Internet. Just click -<guibutton>Get New Snippets</guibutton> and a window with a list of snippet -repositories will open. After downloading the desired snippet, make sure that -you have activated it.</para> -<!--FIXME no way to load a local file ?--> -<para>You can also load snippet repositories from a local file using the file -browser at the bottom of the panel. Click <guibutton>Copy to repository</guibutton> -when finished.</para> -</sect3> +<sect2 id="searchinfiles-intro"> +<title>Introduction</title> +<para>&kappname;'s Search & Replace plugin allows you to search for text or +<ulink url="help:/katepart/regular-expressions.html">regular expressions</ulink> +in many different files at once. You can search all open files, all the files +in one directory and optionally its subdirectories, or all files in the current +project. You can even filter by filename, for instance searching only files +that end with a particular file extension.</para> -<sect3 id="snippets-repo-editor"> -<title>Creating and Editing Snippets</title> +</sect2> -<screenshot id="screenshot-snippets-form"> -<screeninfo>Snippet Editor</screeninfo> -<mediaobject> -<imageobject><imagedata fileref="snippets-form.png" format="PNG"/></imageobject> -<textobject><phrase>The snippet editor.</phrase></textobject> -<caption><para>The snippet editor interface.</para></caption> -</mediaobject> -</screenshot> +<sect2 id="searchinfiles-ui"> +<title>Interface</title> -<para>To create a new snippet repository, click <guibutton>New Snippet File</guibutton>. -You should now see a dialog that asks for the name of the snippet file, license and -author. After choosing the desired options, click <guibutton>Create</guibutton>, -and the snippet editor will open.</para> +<sect3 id="searchinfiles-ui-query"> +<title>Search Query</title> -<para>The snippet editor contains the following options:</para> +<para>The following options are always displayed at the top of the Search in +Files tool view:</para> <variablelist> + <varlistentry> -<term><guilabel>File Type</guilabel></term> -<listitem><para>Select the file type(s) you want the snippet repository to apply -to. It is set to <quote>*</quote> by default, so the repository applies to all files. You -can change it to something like <userinput>C++</userinput> for instance, or select -from a list by hitting the <guibutton>Edit</guibutton>. You can specify more -than one file type by separating them with <userinput>;</userinput>.</para></listitem> +<term><guiicon>New Tab</guiicon></term> +<listitem><para> +You can have as many searches as you want open at the same time. Simply click +the <guibutton>New Tab</guibutton> button at the top-left corner of the Search +tool view and a new results tab will open permitting you to perform another +search. +</para></listitem> </varlistentry> <varlistentry> -<term><guilabel>Authors</guilabel></term> -<listitem><para>Enter the name(s) of the author(s) of the snippet file.</para></listitem> +<term><guiicon>Toggle Results</guiicon></term> +<listitem><para> +The down arrow in the top right-corner of the Search in Files tool view will +toggle the bottom half of the tool view between displaying additional options +for the Search in Folder mode and the results of your search. +</para></listitem> </varlistentry> <varlistentry> -<term>Snippets List</term> -<listitem><para>Contains all snippets defined in the snippet file. You can -simply click on a snippet listed there to edit it.</para></listitem> +<term><guilabel>Find</guilabel></term> +<listitem><para> +This is where you type in what you want to find. You may enter standard text, +or a regular expression if enabled. +</para></listitem> </varlistentry> - + <varlistentry> -<term>Add (<guibutton>+</guibutton>)</term> -<listitem><para>Used to add a new snippet.</para></listitem> +<term><guilabel>Replace</guilabel> (text box)</term> +<listitem><para> +Replacement text that will be added to file(s) in place of the text in the +<guilabel>Find</guilabel> text box. +</para></listitem> </varlistentry> <varlistentry> -<term>Delete (<guibutton>-</guibutton>)</term> -<listitem><para>Used to delete a snippet.</para></listitem> +<term><guibutton>Search</guibutton></term> +<listitem><para> +When you've finished configuring everything, just press the +<guibutton>Search</guibutton> button to perform your search. You may also press +&Enter; in the <guilabel>Find</guilabel> text box to do the same. +</para></listitem> </varlistentry> <varlistentry> -<term><guilabel>Match/Name</guilabel></term> -<listitem><para>Appears in the list of snippets in the tool view and is also -searched when using the code completion feature.</para></listitem> +<term><guibutton>Replace</guibutton></term> +<listitem><para> +When you've finished configuring everything, just press the +<guibutton>Replace</guibutton> button to replace the text entered in the +<guilabel>Find</guilabel> text box with that of the <guilabel>Replace</guilabel> +text box. You may also press &Enter; in the <guilabel>Replace</guilabel> text +box to do the same. +</para></listitem> </varlistentry> <varlistentry> -<term><guilabel>Display Prefix</guilabel>, <guilabel>Display Postfix</guilabel>, -and <guilabel>Display Arguments</guilabel></term> -<listitem><para>Used to display helpful information while using code completion. -The prefix and postfix are displayed before and after the name, while the arguments -are displayed in parenthesis immediately after the name.</para></listitem> +<term><guibutton>Next</guibutton></term> +<listitem><para> +Go to the next match of your search query, switching files if necessary. +</para></listitem> </varlistentry> <varlistentry> -<term><guilabel>Snippet Content</guilabel></term> -<listitem><para>Reusable text or code. This is what appears in your document -when the snippet is used.</para></listitem> +<term><guibutton>Replace checked</guibutton></term> +<listitem><para> +The same as <guibutton>Replace</guibutton>, but will only perform replacements +in files that are checked in the pane below. +</para></listitem> </varlistentry> </variablelist> - -<para>In <guilabel>Snippet Content</guilabel> you can specify variables with -<userinput>${<replaceable>name</replaceable>}</userinput> or -<userinput>%{<replaceable>name</replaceable>}</userinput>. These can be filled -by QtScript or when the snippet is used. There is a special variable - -${cursor} or %{cursor} - which automatically sets the cursor to its first -occurrence.</para> - </sect3> -</sect2> - -<sect2 id="snippets-using"> -<title>Using Snippets</title> - -<screenshot id="screenshot-snippets-usage"> -<screeninfo>Kate Snippets in Action</screeninfo> -<mediaobject> -<imageobject><imagedata fileref="snippets-usage.png" format="PNG"/></imageobject> -<textobject><phrase>Accessing &kate; Snippets from a tool view and a drop down menu.</phrase></textobject> -<caption><para>Selecting from a list of snippets.</para></caption> -</mediaobject> -</screenshot> - -<para>You can call snippets in two ways:</para> - -<itemizedlist> -<listitem><para>By choosing the snippet from the tool view.</para></listitem> -<listitem><para>While writing, you can press <keycombo action="simul">&Ctrl; -<keysym>Space</keysym></keycombo>, which will display all the snippets in a -convenient window from which you can choose. You may enter the beginning -of the snippets name before or after pressing this key combination, which provides -functionality similar to code completion.</para></listitem> -</itemizedlist> - -<para>If the snippet contains variables (besides <literal>${cursor}</literal>) -the cursor will automatically go to the first occurrence of a variable and will -wait for you to write something. When you are done, you can press 	 to move -to the next variable, and so on.</para> - -</sect2> - -<sect2 id="snippets-ack"> -<title>Thanks and Acknowledgments</title> -<para>&kate; Snippets was written by Joseph Wenninger.</para> -<para>Special thanks to Google Code-In 2011 participant Martin Gergov for -writing much of this section.</para> -</sect2> - -</sect1> +<sect3 id="searchinfiles-ui-folder"> +<title>Search in Folder Options</title> -<sect1 id="kate-application-plugin-build"> -<!--http://kate-editor.org/2011/06/21/kate-plugin-updates-part-1/ --> -<sect1info> -<authorgroup> -<author><firstname>Salma</firstname> <surname>Sultana</surname></author> -<author>&TC.Hollingsworth; &TC.Hollingsworth.mail;</author> -</authorgroup> -</sect1info> -<title>Build Plugin</title> - -<sect2 id="build-intro"> -<title>Introduction</title> +<para>These options are displayed below the aforementioned query options. If search +results are being displayed instead, press the <guiicon>Toggle Results</guiicon> +button to display them.</para> -<para>The Build plugin allows you to run actions like build, clean and compile -on a project.</para> +<variablelist> -</sect2> +<varlistentry> +<term><guilabel>Match case</guilabel></term> +<listitem><para> +Restricts search results to only those that have the exact same combination +of upper and lower case letters as your search query. +</para></listitem> +</varlistentry> -<sect2 id="build-using"> -<title>Using the Build Plugin</title> +<varlistentry> +<term><guilabel>Regular expressions</guilabel></term> +<listitem><para> +Permits you to use <ulink url="help:/katepart/regular-expressions.html">regular +expressions</ulink> instead of simple text as your search query. +</para></listitem> +</varlistentry> -<para>The Build plugin adds a <guilabel>Build Output</guilabel> tool view at the -bottom and a <guimenu>Build</guimenu> menu on the menubar. The tool view can be used to configure -build target settings, while the menu can be used to perform build, clean and -compile actions.</para> +<varlistentry> +<term><guilabel>Expand results</guilabel></term> +<listitem><para> +Display all the results found in each file, instead of just a list of files +that contain the search query. +</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Search</guilabel></term> +<listitem><para> +This has three options. Select <guilabel>in Open files</guilabel> to search all +files currently open in &kappname;. Select <guilabel>in Folder</guilabel> to +search inside a folder and optionally its subfolders. Select <guilabel>in +Project</guilabel> to search all the files listed in the currently open project. +</para></listitem> +</varlistentry> -<para>The <guilabel>Build Output</guilabel> tool view has three tabs:</para> +<varlistentry> +<term><guilabel>Folder</guilabel></term> +<listitem><para> +You may enter the path of the folder you wish to search. For instance, you might +enter <userinput>~/development/kde/kate/</userinput> if you wished to search the +&kate; source code. This option is only available when using +<guilabel>in Folder</guilabel> mode. +</para></listitem> +</varlistentry> -<itemizedlist> -<listitem><para><guilabel>Target Settings</guilabel></para></listitem> -<listitem><para><guilabel>Output</guilabel></para></listitem> -<listitem><para><guilabel>Errors & Warnings</guilabel></para></listitem> -</itemizedlist> +<varlistentry> +<term><guiicon>Open file dialog</guiicon></term> +<listitem><para> +Press this button to locate the folder in your desktop's folder browser. This +button only works when using <guilabel>in Folder</guilabel> mode. +</para></listitem> +</varlistentry> -<sect3 id="build-using-target-settings"> -<title>Target Settings tab</title> +<varlistentry> +<term><guiicon>Up</guiicon></term> +<listitem><para> +Press this button to change <guilabel>Folder</guilabel> to the parent of the +currently selected folder. This button only works when using +<guilabel>in Folder</guilabel> mode. +</para></listitem> +</varlistentry> -<para>The target settings tab can be used to configure various build targets.</para> +<varlistentry> +<term><guiicon>Restore Current Folder</guiicon></term> +<listitem><para> +This button will set the <guilabel>Folder</guilabel> entry to the folder in which +the currently open document is located. This button only works when using +<guilabel>in Folder</guilabel> mode. +</para></listitem> +</varlistentry> -<para>Each target contains four configuration options:</para> +<varlistentry> +<term><guilabel>Filter</guilabel></term> +<listitem><para> +This permits you to only search filenames that match a particular pattern. For +instance, to only search files written in C++, change it to +<userinput>*.cpp</userinput>. To search only files beginning with +<literal>kate</literal>, change it to <userinput>kate*</userinput>. You can +enter multiple filters separated with a comma (<userinput>,</userinput>). This +option is not available when using <guilabel>in Open files</guilabel> mode. +</para></listitem> +</varlistentry> -<variablelist> <varlistentry> -<term><guilabel>Working Directory</guilabel></term> -<listitem><para>You can set the path to the project here. Leave this empty to -use the directory the current document is located in.</para></listitem> +<term><guilabel>Exclude</guilabel></term> +<listitem><para> +The opposite of <guilabel>Filter</guilabel>, this prevents &kappname; from +searching files that match the specified patterns. As with +<guilabel>Filter</guilabel>, you can enter multiple patterns separated with a +comma (<userinput>,</userinput>). This option is not available when using +<guilabel>in Open files</guilabel> mode. +</para></listitem> </varlistentry> <varlistentry> -<term><guilabel>Build</guilabel></term> -<listitem><para>This option lets you define the build command. It is set to -<command>make</command> by default.</para></listitem> +<term><guilabel>Recursive</guilabel></term> +<listitem><para> +If this option is enabled, &kappname; will also search in all subfolders of the +selected folder. This option is only available when using +<guilabel>in Folder</guilabel> mode. +</para></listitem> </varlistentry> <varlistentry> -<term><guilabel>Clean</guilabel></term> -<listitem><para>The option lets you define the clean command. It is set to -<command>make clean</command> by default.</para></listitem> +<term><guilabel>Include hidden</guilabel></term> +<listitem><para> +If this option is enabled, &kappname; will also search in files or folders that +are typically hidden by your &OS;. This option is only available when using +<guilabel>in Folder</guilabel> mode. +</para></listitem> </varlistentry> <varlistentry> -<term><guilabel>Quick Compile</guilabel></term> -<listitem><para>This option lets you define the quick compile command. It is set -to <command>gcc -Wall -g %f</command> by default.</para></listitem> +<term><guilabel>Follow symbolic links</guilabel></term> +<listitem><para> +The Search in Files plugin typically doesn't follow +<ulink url="http://en.wikipedia.org/wiki/Symbolic_link";>symbolic links</ulink>. +When this option is enabled, the plugin will follow them instead and search inside +the files or folders they reference. This option is only available when using +<guilabel>in Folder</guilabel> mode. +</para> +<warning><para>It's possible for symbolic links to reference a folder that is the +parent of the folder currently being searched, or other folders that contain +symbolic links to their parent. If there is such a link in the folder being +searched and this option is enabled, &kappname; will repeatedly follow the link +and search the folder, and the search will never complete.</para></warning> +</listitem> </varlistentry> -</variablelist> - -<para>One can create a new target by using the <guibutton>New</guibutton> button. -The <guibutton>Copy</guibutton> button can be used to make a copy of an existing -target. To delete a target, use the <guibutton>Delete</guibutton> button.</para> - -</sect3> -<sect3 id="build-using-output"> -<title>Output tab</title> - -<para>The <guilabel>Output</guilabel> tab shows the console output generated by -the last command.</para> +<varlistentry> +<term><guilabel>Include binary files</guilabel></term> +<listitem><para> +If enabled, &kappname; will also search in files that do not appear to be text +files. +</para></listitem> +</varlistentry> +</variablelist> </sect3> -<sect3 id="buiid-using-errors"> -<title>Errors & Warnings</title> +<sect3 id="searchinfiles-ui-results"> +<title>Search Results</title> -<para>The <guilabel>Errors & Warnings</guilabel> tab lists the errors and -warnings generated by the last command.</para> +<para>The results of your search are displayed below the query options. If +options for Search in Folder mode are displayed, simply press the +<guiicon>Toggle Results</guiicon> button to display them. They will also +automatically be displayed as soon as a search is performed.</para> -<para>Each line contains a message and the file name and line number if available. -Clicking on the error or warning takes you to the appropriate file and places -the cursor on the corresponding line number.</para> +<para>The search results display a list of files that contains text that matches +your search query, followed by the number of matches found in that file.</para> -<para>There are <guibutton>Errors</guibutton>, <guibutton>Warnings</guibutton>, -and <guibutton>Others</guibutton> buttons at the top that allow you to show -or hide those categories of output.</para> +<para>To see a list of matches in that file, simply click the expansion arrow +to the left of the file name. (If you selected the <guilabel>Expand +results</guilabel> option, this will already be done for you.) The line number +each match is found on will be displayed, followed by the contents of that line, +with your search query indicated in bold text.</para> -<!--FIXME: These shortcuts now seem to be used by the Project plugin in 4.11. - https://bugs.kde.org/show_bug.cgi?id=328170 --> -<para>To navigate to the previous error, press -<keycombo action="simul">&Ctrl;&Alt;<keysym>Left</keysym></keycombo>. -To navigate to the next error, press -<keycombo action="simul">&Ctrl;&Alt;<keysym>Right</keysym></keycombo>.</para> +<para>To open the file your result was found in, simply double-click it. &kappname; +will open the file if needed. You can also move the cursor to the location of +a particular match by double-clicking on its listing instead of the file name. +</para> </sect3> </sect2> -<sect2 id="build-menu"> +<sect2 id="searchinfiles-menu"> <title>Menu Structure</title> -<variablelist id="build-build"> -<varlistentry> -<term><menuchoice> -<guimenu>Build</guimenu><guimenuitem>Build</guimenuitem> -</menuchoice></term> -<listitem><para>Runs the <guilabel>Build</guilabel> command for the currently -selected target.</para></listitem> -</varlistentry> +<variablelist> -<varlistentry id="build-clean"> +<varlistentry id="edit-searchinfiles"> <term><menuchoice> -<guimenu>Build</guimenu><guimenuitem>Clean</guimenuitem> +<guimenu>Edit</guimenu> +<guimenuitem>Search in Files</guimenuitem> </menuchoice></term> -<listitem><para>Runs the <guilabel>Clean</guilabel> command for the currently -selected target.</para></listitem> +<listitem> +<para>Launches the Search and Replace tool view.</para> +</listitem> </varlistentry> -<varlistentry id="build-compile"> +<varlistentry id="edit-next-match"> <term><menuchoice> -<guimenu>Build</guimenu><guimenuitem>Quick Compile</guimenuitem> +<guimenu>Edit</guimenu> +<guimenuitem>Go to Next Match</guimenuitem> </menuchoice></term> -<listitem><para>Runs the <guilabel>Quick Compile</guilabel> command for the -currently selected target.</para></listitem> +<listitem> +<para>Go to the next match in a search performed by the Search and Replace +plugin.</para> +</listitem> </varlistentry> -<varlistentry id="build-previous-error"> +<varlistentry id="edit-previous-match"> <term><menuchoice> -<shortcut><keycombo action="simul">&Ctrl;&Alt;<keysym>Left</keysym></keycombo></shortcut> -<guimenu>Build</guimenu><guimenuitem>Previous Error</guimenuitem> +<guimenu>Edit</guimenu> +<guimenuitem>Go to Previous Match</guimenuitem> </menuchoice></term> -<listitem><para>Moves the cursor to the location of the previous error in the -document.</para></listitem> +<listitem> +<para>Go to the previous match in a search performed by the Search and Replace +plugin.</para> +</listitem> </varlistentry> -<varlistentry id="build-next-error"> +<varlistentry id="view-toolviews-searchandreplace"> <term><menuchoice> -<shortcut><keycombo action="simul">&Ctrl;&Alt;<keysym>Right</keysym></keycombo></shortcut> -<guimenu>Build</guimenu><guimenuitem>Next Error</guimenuitem> -</menuchoice></term> -<listitem><para>Moves the cursor to the location of the next error in the -document.</para></listitem> -</varlistentry> - -<varlistentry> -<term><menuchoice id="build-targets"> -<guimenu>Build</guimenu><guisubmenu>Targets</guisubmenu> -</menuchoice></term> -<listitem><para>Select from a list of targets configured by the user.</para></listitem> -</varlistentry> - -<varlistentry> -<term><menuchoice id="build-next-target"> -<guimenu>Build</guimenu><guimenuitem>Next Target</guimenuitem> +<guimenu>View</guimenu><guisubmenu>Tool Views</guisubmenu> +<guimenuitem>Show Search and Replace</guimenuitem> </menuchoice></term> -<listitem><para>Switch to the next target configured by the user.</para></listitem> +<listitem> +<para>Toggle the display of &kappname;'s <guilabel>Search and Replace</guilabel> tool. +</para> +</listitem> </varlistentry> </variablelist> -</sect2> -<sect2 id="build-ack"> -<title>Thanks and Acknowledgments</title> -<para>The &kate; Build Plugin was written by Kåre Särs.</para> -<para>Special thanks to Google Code-In 2011 participant Salma Sultana for -writing much of this section.</para> </sect2> </sect1> -<sect1 id="kate-application-plugin-sql"> + <!-- + FIXME: replaced by built-in functionality in 4.12 + lots of this is wrong, other parts need to be moved somewhere else --> +<sect1 id="kate-application-plugin-snippets"> <sect1info> <authorgroup> -<author><firstname>Ömer</firstname> <othername>Faruk</othername> <surname>ORUÇ</surname></author> +<author><firstname>Martin</firstname> <surname>Gergov</surname></author> <author>&TC.Hollingsworth; &TC.Hollingsworth.mail;</author> </authorgroup> </sect1info> -<title>SQL Plugin</title> - -<sect2 id="sql-intro"> -<title>Introduction</title> - -<para>The Structured Query Language (SQL) is a specialized language for updating, -deleting, and requesting information from databases.</para> - -<para>The &kate; SQL Plugin allows you to:</para> - -<itemizedlist> -<listitem><para>Create a database</para></listitem> -<listitem><para>Connect to existing databases</para></listitem> -<listitem><para>Insert and delete data in the database</para></listitem> -<listitem><para>Execute queries</para></listitem> -<listitem><para>Display results in a table</para></listitem> -</itemizedlist> +<title>Kate Snippets</title> -<!--FIXME If Kate is installed on your computer, at first open Kate. -If Kate isn't installed on your computer, download and install it. +<sect2 id="snippets-intro"> +<title>Introduction</title> +<para>Kate Snippets is a plugin used to save you some time by adding support for +so-called <quote>snippets</quote> (re-usable source code, machine code or text). The plugin +also supports code completion and QtScript.</para> +</sect2> -Using SQL Plugin -After opening the Kate; -Click Settings→ Configure Kate -and then; -Click Application → Select Plugins in the tree widget +<sect2 id="snippets-menu"> +<title>Menu Structure</title> -In the Plugin Manager panel on the right, check SQL Plugin and click OK. ---> +<variablelist> +<varlistentry> +<term><menuchoice><guimenu>View</guimenu><guisubmenu>Tool Views</guisubmenu> +<guimenuitem>Show Snippets</guimenuitem></menuchoice></term> +<listitem><para>Shows snippets panel containing all snippets in your repository +that are for the currently opened file type.</para></listitem> +</varlistentry> +</variablelist> </sect2> -<sect2 id="sql-connecting"> -<title>Connecting to a Database</title> +<sect2 id="snippets-panel"> +<title>Snippets panel</title> -<para>Select <guibutton>Add Connection</guibutton> from the <guimenu>SQL</guimenu> -menu or toolbar, and then select the Qt database driver you want to use (including -QSQLITE, QMYSQL3, QMYSQL, QODBC3, QODBC, QPSQL7, and QPSQL). If you can't see -the desired driver, you need to install it. Then, press <guibutton>Next</guibutton>. -</para> +<screenshot id="screenshot-snippets-panel"> +<screeninfo>Kate Snippets Panel</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="snippets-panel.png" format="PNG"/></imageobject> +<textobject><phrase>The &kate; snippets panel.</phrase></textobject> +<caption><para>The panel for &kate; Snippets.</para></caption> +</mediaobject> +</screenshot> -<para>If the database you selected uses a file, simply indicate the database's -location and press the <guibutton>Next</guibutton> button. If it requires connecting -to a server, you must enter the hostname of the server, your username and password, -and any other information that particular driver may require. Then press -<guibutton>Next</guibutton>.</para> +<para>In the panel you should see a list of snippet repositories, +along with options to create your own, get them from the Internet or load +them from a local file. Each repository has a checkbox that can be used to +activate or deactivate it. There are also buttons to edit and delete existing +repositories.</para> -<para>Finally, give a name to your connection, and press <guibutton>Finish</guibutton>.</para> +<sect3 id="snippets-repo-internet"> +<title>Loading Snippet Repository Files</title> +<para>You can download snippet repositories from the Internet. Just click +<guibutton>Get New Snippets</guibutton> and a window with a list of snippet +repositories will open. After downloading the desired snippet, make sure that +you have activated it.</para> +<!--FIXME no way to load a local file ?--> +<para>You can also load snippet repositories from a local file using the file +browser at the bottom of the panel. Click <guibutton>Copy to repository</guibutton> +when finished.</para> +</sect3> -</sect2> +<sect3 id="snippets-repo-editor"> +<title>Creating and Editing Snippets</title> -<sect2 id="sql-querying"> -<title>Running Queries</title> +<screenshot id="screenshot-snippets-form"> +<screeninfo>Snippet Editor</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="snippets-form.png" format="PNG"/></imageobject> +<textobject><phrase>The snippet editor.</phrase></textobject> +<caption><para>The snippet editor interface.</para></caption> +</mediaobject> +</screenshot> -<sect3 id="sql-querying-insert-delete-update"> -<title>INSERT/DELETE/UPDATE</title> +<para>To create a new snippet repository, click <guibutton>New Snippet File</guibutton>. +You should now see a dialog that asks for the name of the snippet file, license and +author. After choosing the desired options, click <guibutton>Create</guibutton>, +and the snippet editor will open.</para> -<para>You can insert, delete, and update data using the SQL plugin just as -you would from the command line or from within a program. Simply enter a query -and press the <guibutton>Run query</guibutton>.</para> +<para>The snippet editor contains the following options:</para> -<example> -<title>Some Example Queries</title> <variablelist> - <varlistentry> -<term><command>INSERT</command></term> -<listitem><para><programlisting> -INSERT INTO <replaceable>table_name</replaceable> ("<replaceable>feature1</replaceable>", "<replaceable>feature2</replaceable>", "<replaceable>feature3</replaceable>", "<replaceable>feature4</replaceable>", "<replaceable>feature5</replaceable>") -VALUES ("<replaceable>value1</replaceable>", "<replaceable>value2</replaceable>", "<replaceable>value3</replaceable>", "<replaceable>value4</replaceable>", "<replaceable>value5</replaceable>" ) -</programlisting></para></listitem> +<term><guilabel>File Type</guilabel></term> +<listitem><para>Select the file type(s) you want the snippet repository to apply +to. It is set to <quote>*</quote> by default, so the repository applies to all files. You +can change it to something like <userinput>C++</userinput> for instance, or select +from a list by hitting the <guibutton>Edit</guibutton>. You can specify more +than one file type by separating them with <userinput>;</userinput>.</para></listitem> </varlistentry> <varlistentry> -<term><command>DELETE</command></term> -<listitem><para><programlisting> -DELETE FROM <replaceable>table_name</replaceable> WHERE name = "<replaceable>text</replaceable>" -</programlisting></para></listitem> +<term><guilabel>Authors</guilabel></term> +<listitem><para>Enter the name(s) of the author(s) of the snippet file.</para></listitem> </varlistentry> <varlistentry> -<term><command>UPDATE</command></term> -<listitem><para><programlisting> -UPDATE <replaceable>table_name</replaceable> SET "<replaceable>feature1</replaceable>" = "<replaceable>text</replaceable>", "<replaceable>feature2</replaceable>" = "<replaceable>text</replaceable>", "<replaceable>feature3</replaceable>" = "<replaceable>text</replaceable>", "<replaceable>feature4</replaceable>" = "<replaceable>text</replaceable>", "<replaceable>feature5</replaceable>" = "<replaceable>text</replaceable>" -</programlisting></para></listitem> +<term>Snippets List</term> +<listitem><para>Contains all snippets defined in the snippet file. You can +simply click on a snippet listed there to edit it.</para></listitem> </varlistentry> - -</variablelist> -</example> - -</sect3> - -<sect3 id="sql-querying-select"> -<title>SELECT</title> - -<para>After running a <command>SELECT</command> query, you can view the results -as a table that will appear in the <guilabel>SQL Data Output</guilabel> tool view at -the bottom of &kappname;, or as text in the <guilabel>SQL Text Output</guilabel>. -If there is an error, you can see it in the text output.</para> - -<example> -<title>Example <command>SELECT</command> Query</title> -<para><programlisting> -SELECT * FROM <replaceable>table_name</replaceable> -</programlisting></para> -</example> - -<para>In the <guilabel>SQL Data Output</guilabel> tool view, there are several buttons:</para> - -<variablelist> - + <varlistentry> -<term><guibutton>Resize columns to contents</guibutton></term> -<listitem><para>Changes the size of columns to fit their contents.</para></listitem> +<term>Add (<guibutton>+</guibutton>)</term> +<listitem><para>Used to add a new snippet.</para></listitem> </varlistentry> <varlistentry> -<term><guibutton>Resize rows to contents</guibutton></term> -<listitem><para>Changes the size of rows to fit their contents.</para></listitem> +<term>Delete (<guibutton>-</guibutton>)</term> +<listitem><para>Used to delete a snippet.</para></listitem> </varlistentry> <varlistentry> -<term><guibutton>Copy</guibutton></term> -<listitem><para>Selects all of the table contents and copies it to the clipboard buffer.</para></listitem> +<term><guilabel>Match/Name</guilabel></term> +<listitem><para>Appears in the list of snippets in the tool view and is also +searched when using the code completion feature.</para></listitem> </varlistentry> <varlistentry> -<term><guibutton>Export</guibutton></term> -<listitem><para>Exports all of the table contents to a file, the clipboard, or the -current document in the Comma Separated Values format.</para></listitem> +<term><guilabel>Display Prefix</guilabel>, <guilabel>Display Postfix</guilabel>, +and <guilabel>Display Arguments</guilabel></term> +<listitem><para>Used to display helpful information while using code completion. +The prefix and postfix are displayed before and after the name, while the arguments +are displayed in parenthesis immediately after the name.</para></listitem> </varlistentry> <varlistentry> -<term><guibutton>Clear</guibutton></term> -<listitem><para>Removes everything from the table view</para></listitem> +<term><guilabel>Snippet Content</guilabel></term> +<listitem><para>Reusable text or code. This is what appears in your document +when the snippet is used.</para></listitem> </varlistentry> </variablelist> -<para>You can now change the colors displayed in the table in the <guilabel>SQL</guilabel> -section of <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &kate;</guimenuitem> -</menuchoice>.</para> +<para>In <guilabel>Snippet Content</guilabel> you can specify variables with +<userinput>${<replaceable>name</replaceable>}</userinput> or +<userinput>%{<replaceable>name</replaceable>}</userinput>. These can be filled +by QtScript or when the snippet is used. There is a special variable - +${cursor} or %{cursor} - which automatically sets the cursor to its first +occurrence.</para> </sect3> </sect2> -<sect2 id="sql-browsing"> -<title>Browsing</title> - -<para>You can browse your database using the <guilabel>SQL Schema Browser</guilabel> -tool view on the left. The information displayed varies depending on which -database driver you are using.</para> - -<para>To refresh this list, right-click anywhere in the tool view and select -<guimenuitem>Refresh</guimenuitem>. To generate a query on any entry in the list, -right-click on an entry, select <guisubmenu>Generate</guisubmenu>, and select the -query type (<guimenuitem>SELECT</guimenuitem>, <guimenuitem>UPDATE</guimenuitem>, -<guimenuitem>INSERT</guimenuitem>, or <guimenuitem>DELETE</guimenuitem>) from -the submenu that appears.</para> - -</sect2> - -<sect2 id="sql-menus"> -<title>Menu Structure</title> -<variablelist> - -<varlistentry> -<term><menuchoice> -<guimenu>SQL</guimenu><guimenuitem>Add connection...</guimenuitem> -</menuchoice></term> -<listitem><para> -Adds a new connection using any database driver. -</para></listitem> -</varlistentry> +<sect2 id="snippets-using"> +<title>Using Snippets</title> -<varlistentry> -<term><menuchoice> -<guimenu>SQL</guimenu><guimenuitem>Remove connection</guimenuitem> -</menuchoice></term> -<listitem><para> -Removes the selected connection. -</para></listitem> -</varlistentry> +<screenshot id="screenshot-snippets-usage"> +<screeninfo>Kate Snippets in Action</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="snippets-usage.png" format="PNG"/></imageobject> +<textobject><phrase>Accessing &kate; Snippets from a tool view and a drop down menu.</phrase></textobject> +<caption><para>Selecting from a list of snippets.</para></caption> +</mediaobject> +</screenshot> -<varlistentry> -<term><menuchoice> -<guimenu>SQL</guimenu><guimenuitem>Edit connection...</guimenuitem> -</menuchoice></term> -<listitem><para> -Edits the current connection's settings. -</para></listitem> -</varlistentry> +<para>You can call snippets in two ways:</para> -<varlistentry> -<term>Connections</term> -<listitem><para> -All database connections you have created are listed between the -<guimenuitem>Edit connection</guimenuitem> and <guimenuitem>Run query</guimenuitem> -menu items. Select one to run queries or make modifications to it. -</para></listitem> -</varlistentry> +<itemizedlist> +<listitem><para>By choosing the snippet from the tool view.</para></listitem> +<listitem><para>While writing, you can press <keycombo action="simul">&Ctrl; +<keysym>Space</keysym></keycombo>, which will display all the snippets in a +convenient window from which you can choose. You may enter the beginning +of the snippets name before or after pressing this key combination, which provides +functionality similar to code completion.</para></listitem> +</itemizedlist> -<varlistentry> -<term><menuchoice> -<shortcut><keycombo action="simul">&Ctrl;<keycap>E</keycap></keycombo></shortcut> -<guimenu>SQL</guimenu><guimenuitem>Run query</guimenuitem> -</menuchoice></term> -<listitem><para> -Runs your query. -</para></listitem> -</varlistentry> +<para>If the snippet contains variables (besides <literal>${cursor}</literal>) +the cursor will automatically go to the first occurrence of a variable and will +wait for you to write something. When you are done, you can press 	 to move +to the next variable, and so on.</para> -</variablelist> </sect2> -<sect2 id="sql-ack"> +<sect2 id="snippets-ack"> <title>Thanks and Acknowledgments</title> - -<para>The SQL Plugin was written by Marco Mentasti.</para> -<para>Special thanks to Google Code-In 2011 participant Ömer Faruk ORUÇ for +<para>&kate; Snippets was written by Joseph Wenninger.</para> +<para>Special thanks to Google Code-In 2011 participant Martin Gergov for writing much of this section.</para> - </sect2> </sect1> -<sect1 id="kate-application-plugin-gdb"> -<!--http://kate-editor.org/2011/06/23/kate-plugin-updates-part-2/--> + +<sect1 id="kate-application-plugin-sql"> <sect1info> <authorgroup> -<author><firstname>Martin</firstname> <surname>Gergov</surname></author> +<author><firstname>Ömer</firstname> <othername>Faruk</othername> <surname>ORUÇ</surname></author> <author>&TC.Hollingsworth; &TC.Hollingsworth.mail;</author> </authorgroup> </sect1info> -<title>&gdb; Plugin</title> +<title>SQL Plugin</title> -<sect2 id="gdb-intro"> +<sect2 id="sql-intro"> <title>Introduction</title> -<para>&kappname;'s &gdb; plugin provides a simple frontend to the popular &GNU; -Project Debugger.</para> +<para>The Structured Query Language (SQL) is a specialized language for updating, +deleting, and requesting information from databases.</para> -<important> -<para>Previous experience with &gdb; is strongly recommended. For more -information on using &gdb;, visit <ulink url="http://www.gnu.org/s/gdb/";>the -&gdb; website</ulink>.</para> -</important> +<para>The &kate; SQL Plugin allows you to:</para> + +<itemizedlist> +<listitem><para>Create a database</para></listitem> +<listitem><para>Connect to existing databases</para></listitem> +<listitem><para>Insert and delete data in the database</para></listitem> +<listitem><para>Execute queries</para></listitem> +<listitem><para>Display results in a table</para></listitem> +</itemizedlist> + +<!--FIXME If Kate is installed on your computer, at first open Kate. +If Kate isn't installed on your computer, download and install it. + +Using SQL Plugin +After opening the Kate; +Click Settings→ Configure Kate +and then; +Click Application → Select Plugins in the tree widget -<para>You can enable the &gdb; plugin in -<link linkend="config-dialog-plugins">the Plugins section of &kappname;'s -configuration</link>.</para> +In the Plugin Manager panel on the right, check SQL Plugin and click OK. +--> -<para>For the plugin to work properly, you must have a source file (of any type -supported by &gdb;) and an executable.</para> +</sect2> -<tip> -<para>If you compile using &gcc;/<command>g++</command> you might want to use -the <command><parameter>-ggdb</parameter></command> command line argument. +<sect2 id="sql-connecting"> +<title>Connecting to a Database</title> + +<para>Select <guibutton>Add Connection</guibutton> from the <guimenu>SQL</guimenu> +menu or toolbar, and then select the Qt database driver you want to use (including +QSQLITE, QMYSQL3, QMYSQL, QODBC3, QODBC, QPSQL7, and QPSQL). If you can't see +the desired driver, you need to install it. Then, press <guibutton>Next</guibutton>. </para> -</tip> -<para>After these preparations are made, open the source file in &kappname;, -enter the path to the executable in the <guilabel>Settings</guilabel> tab of the -<guilabel>Debug View</guilabel> tool view, and select -<menuchoice><guimenu>Debug</guimenu><guimenuitem>Start Debugging</guimenuitem></menuchoice> -from the menu to get started.</para> +<para>If the database you selected uses a file, simply indicate the database's +location and press the <guibutton>Next</guibutton> button. If it requires connecting +to a server, you must enter the hostname of the server, your username and password, +and any other information that particular driver may require. Then press +<guibutton>Next</guibutton>.</para> -</sect2> +<para>Finally, give a name to your connection, and press <guibutton>Finish</guibutton>.</para> -<sect2 id="gdb-menus"> -<title>Menu and Toolbar Structure</title> +</sect2> -<para>All of these options are available in &kappname;'s menus, and many are -available on the Debug toolbar as well.</para> +<sect2 id="sql-querying"> +<title>Running Queries</title> -<variablelist> +<sect3 id="sql-querying-insert-delete-update"> +<title>INSERT/DELETE/UPDATE</title> -<varlistentry id="gdb-menus-show-debug-view"> -<term><menuchoice> -<guimenu>View</guimenu><guisubmenu>Tool View</guisubmenu><guimenuitem>Show Debug View</guimenuitem> -</menuchoice></term> -<listitem><para>Shows a tool view containing &gdb; output, the &gdb; command -line used, and other settings.</para></listitem> -</varlistentry> +<para>You can insert, delete, and update data using the SQL plugin just as +you would from the command line or from within a program. Simply enter a query +and press the <guibutton>Run query</guibutton>.</para> -<varlistentry id="gdb-menus-show-locals"> -<term><menuchoice> -<guimenu>View</guimenu><guisubmenu>Tool View</guisubmenu><guimenuitem>Show Locals</guimenuitem> -</menuchoice></term> -<listitem><para>Shows a list of all currently loaded variables and their values. -</para></listitem> -</varlistentry> +<example> +<title>Some Example Queries</title> +<variablelist> -<varlistentry id="gdb-menus-show-call-stack"> -<term><menuchoice> -<guimenu>View</guimenu><guisubmenu>Tool View</guisubmenu><guimenuitem>Show Call Stack</guimenuitem> -</menuchoice></term> -<listitem><para>Shows a &gdb; backtrace.</para></listitem> +<varlistentry> +<term><command>INSERT</command></term> +<listitem><para><programlisting> +INSERT INTO <replaceable>table_name</replaceable> ("<replaceable>feature1</replaceable>", "<replaceable>feature2</replaceable>", "<replaceable>feature3</replaceable>", "<replaceable>feature4</replaceable>", "<replaceable>feature5</replaceable>") +VALUES ("<replaceable>value1</replaceable>", "<replaceable>value2</replaceable>", "<replaceable>value3</replaceable>", "<replaceable>value4</replaceable>", "<replaceable>value5</replaceable>" ) +</programlisting></para></listitem> </varlistentry> -<varlistentry id="gdb-menus-targets"> -<term><menuchoice> -<guimenu>Debug</guimenu><guisubmenu>Targets</guisubmenu> -</menuchoice></term> -<listitem><para>A submenu containing a list of targets (executables). -</para></listitem> +<varlistentry> +<term><command>DELETE</command></term> +<listitem><para><programlisting> +DELETE FROM <replaceable>table_name</replaceable> WHERE name = "<replaceable>text</replaceable>" +</programlisting></para></listitem> </varlistentry> -<varlistentry id="gdb-menus-arg-lists"> -<term><menuchoice> -<guimenu>Debug</guimenu><guisubmenu>Arg Lists</guisubmenu> -</menuchoice></term> -<listitem><para>A submenu containing all argument lists.</para></listitem> +<varlistentry> +<term><command>UPDATE</command></term> +<listitem><para><programlisting> +UPDATE <replaceable>table_name</replaceable> SET "<replaceable>feature1</replaceable>" = "<replaceable>text</replaceable>", "<replaceable>feature2</replaceable>" = "<replaceable>text</replaceable>", "<replaceable>feature3</replaceable>" = "<replaceable>text</replaceable>", "<replaceable>feature4</replaceable>" = "<replaceable>text</replaceable>", "<replaceable>feature5</replaceable>" = "<replaceable>text</replaceable>" +</programlisting></para></listitem> </varlistentry> -<varlistentry id="gdb-menus-start"> -<term><menuchoice> -<guimenu>Debug</guimenu><guimenuitem>Start Debugging</guimenuitem> -</menuchoice></term> -<listitem><para>Starts &gdb; with a target.</para></listitem> -</varlistentry> +</variablelist> +</example> -<varlistentry id="gdb-menus-kill"> -<term><menuchoice> -<guimenu>Debug</guimenu><guimenuitem>Kill / Stop Debugging</guimenuitem> -</menuchoice></term> -<listitem><para>Stops &gdb;.</para></listitem> -</varlistentry> +</sect3> -<varlistentry id="gdb-menus-restart"> -<term><menuchoice> -<guimenu>Debug</guimenu><guimenuitem>Restart Debugging</guimenuitem> -</menuchoice></term> -<listitem><para>Restarts &gdb;.</para></listitem> -</varlistentry> +<sect3 id="sql-querying-select"> +<title>SELECT</title> -<varlistentry id="gdb-menus-break"> -<term><menuchoice> -<guimenu>Debug</guimenu><guimenuitem>Toggle Breakpoint / Break</guimenuitem> -</menuchoice></term> -<listitem><para>Set a breakpoint at the current cursor position. -</para></listitem> -</varlistentry> +<para>After running a <command>SELECT</command> query, you can view the results +as a table that will appear in the <guilabel>SQL Data Output</guilabel> tool view at +the bottom of &kappname;, or as text in the <guilabel>SQL Text Output</guilabel>. +If there is an error, you can see it in the text output.</para> -<varlistentry id="gdb-menus-step-in"> -<term><menuchoice> -<guimenu>Debug</guimenu><guimenuitem>Step In</guimenuitem> -</menuchoice></term> -<listitem><para>Execute the present statement (function call will be debugged). -</para></listitem> -</varlistentry> +<example> +<title>Example <command>SELECT</command> Query</title> +<para><programlisting> +SELECT * FROM <replaceable>table_name</replaceable> +</programlisting></para> +</example> -<varlistentry id="gdb-menus-step-over"> -<term><menuchoice> -<guimenu>Debug</guimenu><guimenuitem>Step Over</guimenuitem> -</menuchoice></term> -<listitem><para>Execute the present statement (function call will not be -debugged).</para></listitem> -</varlistentry> +<para>In the <guilabel>SQL Data Output</guilabel> tool view, there are several buttons:</para> -<varlistentry id="gdb-menus-step-out"> -<term><menuchoice> -<guimenu>Debug</guimenu><guimenuitem>Step Out</guimenuitem> -</menuchoice></term> -<listitem><para>Resumes execution until the program that is executing -terminates.</para></listitem> -</varlistentry> +<variablelist> -<varlistentry id="gdb-menus-move-pc"> -<term><menuchoice> -<guimenu>Debug</guimenu><guimenuitem>Move PC</guimenuitem> -</menuchoice></term> -<listitem><para>Move program counter (next execution).</para></listitem> +<varlistentry> +<term><guibutton>Resize columns to contents</guibutton></term> +<listitem><para>Changes the size of columns to fit their contents.</para></listitem> </varlistentry> -<varlistentry id="gdb-menus-run-to-cursor"> -<term><menuchoice> -<guimenu>Debug</guimenu><guimenuitem>Run To Cursor</guimenuitem> -</menuchoice></term> -<listitem><para>Runs the program until it reaches current cursor position. -</para></listitem> +<varlistentry> +<term><guibutton>Resize rows to contents</guibutton></term> +<listitem><para>Changes the size of rows to fit their contents.</para></listitem> </varlistentry> -<varlistentry id="gdb-menus-continue"> -<term><menuchoice> -<guimenu>Debug</guimenu><guimenuitem>Continue</guimenuitem> -</menuchoice></term> -<listitem><para>Ignores any breakpoints and executes program until it terminates -(successfully or not).</para></listitem> +<varlistentry> +<term><guibutton>Copy</guibutton></term> +<listitem><para>Selects all of the table contents and copies it to the clipboard buffer.</para></listitem> </varlistentry> -<varlistentry id="gdb-menus-print-value"> -<term><menuchoice> -<guimenu>Debug</guimenu><guimenuitem>Print Value</guimenuitem> -</menuchoice></term> -<listitem><para>Prints the value of the variable that the cursor is currently -pointing to.</para></listitem> +<varlistentry> +<term><guibutton>Export</guibutton></term> +<listitem><para>Exports all of the table contents to a file, the clipboard, or the +current document in the Comma Separated Values format.</para></listitem> </varlistentry> -<varlistentry id="gdb-menus-toolbar"> -<term><menuchoice> -<guimenu>Settings</guimenu><guisubmenu>Toolbars Shown</guisubmenu><guimenuitem>&gdb; Plugin</guimenuitem> -</menuchoice></term> -<listitem><para>Display the debugging toolbar.</para></listitem> +<varlistentry> +<term><guibutton>Clear</guibutton></term> +<listitem><para>Removes everything from the table view</para></listitem> </varlistentry> </variablelist> -</sect2> - -<sect2 id="gdb-debug-view"> -<title>Debug View</title> - -<para>The <guilabel>Debug View</guilabel> tool view consists of several tabs: -</para> - -<variablelist> +<para>You can now change the colors displayed in the table in the <guilabel>SQL</guilabel> +section of <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &kate;</guimenuitem> +</menuchoice>.</para> -<varlistentry> -<term><guilabel>&gdb; Output</guilabel></term> -<listitem> -<para>Contains output from &gdb; and a &gdb; command line.</para> +</sect3> +</sect2> -<screenshot id="screenshot-gdb-output"> -<screeninfo>The Output Tab</screeninfo> -<mediaobject> -<imageobject><imagedata fileref="gdb-output.png" format="PNG"/></imageobject> -<textobject><phrase>The Output tab.</phrase></textobject> -<caption><para>The <guilabel>Output</guilabel> tab displaying the output from a -debugging session.</para></caption> -</mediaobject> -</screenshot> +<sect2 id="sql-browsing"> +<title>Browsing</title> -</listitem> -</varlistentry> +<para>You can browse your database using the <guilabel>SQL Schema Browser</guilabel> +tool view on the left. The information displayed varies depending on which +database driver you are using.</para> -<varlistentry> -<term><guilabel>Settings</guilabel></term> -<listitem> -<variablelist> +<para>To refresh this list, right-click anywhere in the tool view and select +<guimenuitem>Refresh</guimenuitem>. To generate a query on any entry in the list, +right-click on an entry, select <guisubmenu>Generate</guisubmenu>, and select the +query type (<guimenuitem>SELECT</guimenuitem>, <guimenuitem>UPDATE</guimenuitem>, +<guimenuitem>INSERT</guimenuitem>, or <guimenuitem>DELETE</guimenuitem>) from +the submenu that appears.</para> -<varlistentry> -<term><guilabel>Target</guilabel></term> -<listitem><para>Path to the target (executable) for debugging.</para></listitem> -</varlistentry> +</sect2> -<varlistentry> -<term><guilabel>Working Directory</guilabel></term> -<listitem><para>The current working directory provided to the target. -</para></listitem> -</varlistentry> +<sect2 id="sql-menus"> +<title>Menu Structure</title> +<variablelist> <varlistentry> -<term><guilabel>Arg List</guilabel></term> -<listitem><para>Arguments passed to the program.</para></listitem> +<term><menuchoice> +<guimenu>SQL</guimenu><guimenuitem>Add connection...</guimenuitem> +</menuchoice></term> +<listitem><para> +Adds a new connection using any database driver. +</para></listitem> </varlistentry> <varlistentry> -<term><guilabel>Keep focus</guilabel></term> -<listitem><para>Keeps focus on the &gdb; command line.</para></listitem> +<term><menuchoice> +<guimenu>SQL</guimenu><guimenuitem>Remove connection</guimenuitem> +</menuchoice></term> +<listitem><para> +Removes the selected connection. +</para></listitem> </varlistentry> <varlistentry> -<term><guilabel>Redirect IO</guilabel></term> -<listitem><para>Opens a new <guilabel>IO</guilabel> tab in the <guilabel>Debug -View</guilabel> where you can view output and provide input to the running -program.</para></listitem> +<term><menuchoice> +<guimenu>SQL</guimenu><guimenuitem>Edit connection...</guimenuitem> +</menuchoice></term> +<listitem><para> +Edits the current connection's settings. +</para></listitem> </varlistentry> -</variablelist> - -<screenshot id="screenshot-gdb-settings"> -<screeninfo>The Settings Tab</screeninfo> -<mediaobject> -<imageobject><imagedata fileref="gdb-settings.png" format="PNG"/></imageobject> -<textobject><phrase>The Settings tab.</phrase></textobject> -<caption><para>The <guilabel>Settings</guilabel> tab displaying the configuration -of a debugging session.</para></caption> -</mediaobject> -</screenshot> - -</listitem> +<varlistentry> +<term>Connections</term> +<listitem><para> +All database connections you have created are listed between the +<guimenuitem>Edit connection</guimenuitem> and <guimenuitem>Run query</guimenuitem> +menu items. Select one to run queries or make modifications to it. +</para></listitem> </varlistentry> <varlistentry> -<term><guilabel>IO</guilabel></term> -<listitem> -<para>Contains an area that displays output from the running program and a -command line where you may provide input to it.</para> - -<screenshot id="screenshot-gdb-io"> -<screeninfo>The IO Tab</screeninfo> -<mediaobject> -<imageobject><imagedata fileref="gdb-io.png" format="PNG"/></imageobject> -<textobject><phrase>The IO tab.</phrase></textobject> -<caption><para>The <guilabel>IO</guilabel> tab displaying output from a simple -test program.</para></caption> -</mediaobject> -</screenshot> - -</listitem> +<term><menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>E</keycap></keycombo></shortcut> +<guimenu>SQL</guimenu><guimenuitem>Run query</guimenuitem> +</menuchoice></term> +<listitem><para> +Runs your query. +</para></listitem> </varlistentry> </variablelist> - -</sect2> - -<sect2 id="gdb-other"> -<title>Call Stack and Locals</title> - -<para>The <guilabel>Call Stack</guilabel> tool view contains a list of the formatted -backtrace returned from &gdb;.</para> - -<screenshot id="screenshot-gdb-call-stack"> -<screeninfo>The &gdb; Call Stack Tool View</screeninfo> -<mediaobject> -<imageobject><imagedata fileref="gdb-call-stack.png" format="PNG"/></imageobject> -<textobject><phrase>The Call Stack tool view.</phrase></textobject> -<caption><para>The &gdb; Plugin's <guilabel>Call Stack</guilabel> tool view. -</para></caption> -</mediaobject> -</screenshot> - -<para>The <guilabel>Locals</guilabel> tool view contains a list of all currently -loaded variables from the program and their corresponding values.</para> - -<screenshot id="screenshot-gdb-locals"> -<screeninfo>The &gdb; Locals Tool View</screeninfo> -<mediaobject> -<imageobject><imagedata fileref="gdb-locals.png" format="PNG"/></imageobject> -<textobject><phrase>The Locals tool view.</phrase></textobject> -<caption><para>The &gdb; Plugin's <guilabel>Locals</guilabel> tool view. -</para></caption> -</mediaobject> -</screenshot> - </sect2> -<sect2 id="gdb-ack"> +<sect2 id="sql-ack"> <title>Thanks and Acknowledgments</title> -<para>Special thanks to Google Code-In 2011 participant Martin Gergov for +<para>The SQL Plugin was written by Marco Mentasti.</para> +<para>Special thanks to Google Code-In 2011 participant Ömer Faruk ORUÇ for writing much of this section.</para> </sect2> @@ -1782,6 +1634,155 @@ so the calling program is aware you have finished editing the file.</para></list </sect1> +<!-- from doc/kate-addons/xmlcheck.docbook --> +<sect1 id="kate-application-plugin-xmltools"> +<sect1info> +<authorgroup><author> +&Daniel.Naber; &Daniel.Naber.mail; +</author></authorgroup> +</sect1info> +<title>&XML; Completion</title> + +<para>This plugin gives hints about what is allowed at a certain position in +an &XML; file, according to the file's DTD. It will list possible +elements, attributes, attribute values or entities, depending on the +cursor position (⪚ all entities are listed if the character on the left +of the cursor is <quote>&</quote>). It's also possible to close the nearest +open tag on the left.</para> + +<para>The <acronym>DTD</acronym> must exist in &XML; format, as produced by the Perl program +<command>dtdparse</command>. We will call a DTD in this format <quote>meta DTD</quote>. +Some meta DTDs are supplied. They are installed in +<filename class="directory">$KDEDIR/share/apps/katexmltools/</filename>, +which is also the default folder when you choose +<guimenuitem>Assign Meta DTD...</guimenuitem>. +To produce your own meta DTDs, get <command>dtdparse</command> from +<ulink url="http://dtdparse.sourceforge.net";>http://dtdparse.sourceforge.net</ulink>.</para> + +<sect2 id="xmltools-how-to-use"> +<title>How to Use</title> + +<para>Start &kate; and open the configuration dialog under <menuchoice><guimenu>Settings</guimenu> +<guimenuitem>Configure &kate;...</guimenuitem></menuchoice>. +Then select <guilabel>&XML; Completion</guilabel> which will appear +in the <menuchoice><guimenu>Application</guimenu> +<guimenuitem>Plugins</guimenuitem></menuchoice> page and close the dialog. After +that, select <menuchoice><guimenu>&XML;</guimenu><guimenuitem>Assign Meta DTD...</guimenuitem></menuchoice>. +If your document contains no <quote>DOCTYPE</quote> or the doctype is unknown, you will have to +select a meta DTD from the file system. Otherwise the meta DTD that +matches the current document's DOCTYPE will be loaded automatically.</para> + +<para>You can now use the plugin while typing your text:</para> + +<variablelist> + +<varlistentry> +<term><keycap><</keycap> (less than key)</term> +<listitem><para>This will trigger a list of possible elements unless the +cursor is inside a tag already. Note that you currently cannot use +this to insert the top level element (⪚ <quote><html></quote>).</para></listitem> +</varlistentry> + +<varlistentry> +<term><keycap><</keycap><keycap>/</keycap>(less than key + slash)</term> +<listitem><para>Entering these characters will offer to close the current element +(nearest open one to the left of the cursor). Press &Enter; to accept the suggestion. +Unlike the <guimenuitem>Close Element</guimenuitem> menu item, this works only with +a DTD assigned.</para></listitem> +</varlistentry> + +<varlistentry> +<term><keycap>"</keycap> (quote key)</term> +<listitem><para>The quote key will trigger a list of possible attribute +values (if there are any) if you are inside a tag.</para></listitem> +</varlistentry> + +<varlistentry> +<term><keycap> </keycap> (space key)</term> +<listitem><para>This key will trigger a list of possible attributes for the +current element if you are inside a tag.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><keycap>&</keycap> (ampersand key)</term> +<listitem><para>This key will trigger a list of named entities.</para></listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2 id="xmltools-features-and-limitations"> +<title>Features and Limitations</title> + +<para>You can test all functions and limitations by loading +<filename>$KDEDIR/share/apps/katexmltools/testcases.xml</filename><!--FIXME replacement for KDEDIRS--> +into &kate; and following the instructions.</para> + +</sect2> + + +<sect2 id="xmltools-menu"> +<title>Menu Structure</title> + +<variablelist id="xml-insert-element"> +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>Return</keycap></keycombo> +</shortcut> +<guimenu>&XML;</guimenu> +<guimenuitem>Insert Element...</guimenuitem> +</menuchoice></term> +<listitem><para>This will open a dialog that lets you insert an &XML; element. +The <, > characters and the closing tag will be inserted automatically. +If you have selected text when this menu item is selected, the selected +text will be surrounded by the opening and the closing tag. +The dialog also offers completion of all elements that may be inserted +at the current cursor position if you have assigned a meta DTD by +using <guimenuitem>Assign Meta DTD...</guimenuitem>. +</para></listitem> +</varlistentry> + +<varlistentry id="xml-close-element"> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap><</keycap></keycombo> +</shortcut> +<guimenu>&XML;</guimenu> +<guimenuitem>Close Element</guimenuitem> +</menuchoice></term> +<listitem><para>This will search your text for a tag that is not yet closed +and will close it by inserting the corresponding closing tag. +The search starts at the cursor position and goes left. If +it cannot find an open tag nothing will happen.</para></listitem> +</varlistentry> + +<varlistentry id="xml-assign-metadtd"> +<term><menuchoice> +<guimenu>&XML;</guimenu> +<guimenuitem>Assign Meta DTD...</guimenuitem> +</menuchoice></term> +<listitem><para>This will tell the plugin which meta DTD to use for the +current document. Note that this assignment will not be saved. +You will have to repeat it when you start &kate; the next time.</para></listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2 id="xmltools-thanks-and-acknowledgements"> +<title>Thanks and Acknowledgments</title> +<para> +&kate; Plugin <quote>&XML; Completion</quote> copyright 2001,2002 &Daniel.Naber; +&Daniel.Naber.mail;. +</para> +<para>KDE SC 4 version copyright 2010 Tomáš Trnka</para> +<para>Documentation copyright 2001,2002 &Daniel.Naber;</para> +</sect2> +</sect1> + + <!--FIXME Missing (according to config docs) Additional pages for enabled plugins: _______________________________________________ kde-doc-english mailing list [email protected] https://mail.kde.org/mailman/listinfo/kde-doc-english
