diff options
Diffstat (limited to 'doc/kate')
| -rw-r--r-- | doc/kate/CMakeLists.txt | 12 | ||||
| -rw-r--r-- | doc/kate/Makefile.am | 3 | ||||
| -rw-r--r-- | doc/kate/TODO | 6 | ||||
| -rw-r--r-- | doc/kate/advanced.docbook | 1159 | ||||
| -rw-r--r-- | doc/kate/configdialog01.png | bin | 0 -> 44641 bytes | |||
| -rw-r--r-- | doc/kate/configdialog02.png | bin | 0 -> 25384 bytes | |||
| -rw-r--r-- | doc/kate/configuring.docbook | 1595 | ||||
| -rw-r--r-- | doc/kate/fundamentals.docbook | 611 | ||||
| -rw-r--r-- | doc/kate/highlighted.png | bin | 0 -> 4797 bytes | |||
| -rw-r--r-- | doc/kate/highlighting.docbook | 931 | ||||
| -rw-r--r-- | doc/kate/index.docbook | 292 | ||||
| -rw-r--r-- | doc/kate/kate.png | bin | 0 -> 81016 bytes | |||
| -rw-r--r-- | doc/kate/man-kate.1.docbook | 165 | ||||
| -rw-r--r-- | doc/kate/mdi.docbook | 385 | ||||
| -rw-r--r-- | doc/kate/menus.docbook | 1438 | ||||
| -rw-r--r-- | doc/kate/mimetypechooser.png | bin | 0 -> 15823 bytes | |||
| -rw-r--r-- | doc/kate/part.docbook | 711 | ||||
| -rw-r--r-- | doc/kate/plugins.docbook | 34 | ||||
| -rw-r--r-- | doc/kate/regular-expressions.docbook | 664 | ||||
| -rw-r--r-- | doc/kate/unhighlighted.png | bin | 0 -> 3471 bytes |
20 files changed, 8006 insertions, 0 deletions
diff --git a/doc/kate/CMakeLists.txt b/doc/kate/CMakeLists.txt new file mode 100644 index 000000000..c318aaa9d --- /dev/null +++ b/doc/kate/CMakeLists.txt @@ -0,0 +1,12 @@ +################################################# +# +# (C) 2010-2011 Serghei Amelian +# serghei (DOT) amelian (AT) gmail.com +# +# Improvements and feedback are welcome +# +# This file is released under GPL >= 2 +# +################################################# + +tde_create_handbook( DESTINATION kate ) diff --git a/doc/kate/Makefile.am b/doc/kate/Makefile.am new file mode 100644 index 000000000..17a314c39 --- /dev/null +++ b/doc/kate/Makefile.am @@ -0,0 +1,3 @@ +KDE_LANG = en +KDE_DOCS = AUTO +KDE_MANS = AUTO diff --git a/doc/kate/TODO b/doc/kate/TODO new file mode 100644 index 000000000..d41ed4b80 --- /dev/null +++ b/doc/kate/TODO @@ -0,0 +1,6 @@ +Fill empty sections. +Rewrite intro chapter. +Write regexp appendix. +Add Misc Tools chapter, ao Find in Files. +Go over everything and make sure it reflects the practial truuth ;) +Add links to foreign documentation. diff --git a/doc/kate/advanced.docbook b/doc/kate/advanced.docbook new file mode 100644 index 000000000..e0d552c80 --- /dev/null +++ b/doc/kate/advanced.docbook @@ -0,0 +1,1159 @@ +<chapter id="advanced-editing-tools"> +<chapterinfo> +<authorgroup> +<author>&Anders.Lund; &Anders.Lund.mail;</author> +<author>&Dominik.Haumann; &Dominik.Haumann.mail;</author> +<author>&tde-authors;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</chapterinfo> +<title>Advanced Editing Tools</title> + +<sect1 id="advanced-editing-tools-comment"> + +<title>Comment/Uncomment</title> + +<para>The Comment and Uncomment commands, available from the +<guimenu>Tools</guimenu> menu allow you to add or remove comment +markers to the selection, or to the current line if no text is selected, +if comments are supported by the format of the file you are +editing.</para> + +<para>The rules for how commenting is done are defined in the syntax +definitions, so if syntax highlighting is not used, commenting/uncommenting +is not possible.</para> + +<para>Some formats define single line comment markers, some multiline +markers and some both. If multiline markers are not available, +commenting out a selection that does not fully include its last line +is not possible.</para> + +<para>If a single line marker is available, commenting single lines is +preferred where applicable, as this helps to avoid problems with +nested comments.</para> + +<para>When removing comment markers, no uncommented text should be +selected. When removing multiline comment markers from a selection, +any whitespace outside the comment markers is ignored.</para> + +<para><indexterm><primary>comment</primary></indexterm> +To place comment markers, use the +<menuchoice><guimenu>Tools</guimenu><guimenuitem>Comment</guimenuitem></menuchoice> +menu item or the related keyboard shortcut sequence, default is +<keycombo action="simul">&Ctrl;<keycap>D</keycap></keycombo>.</para> + +<para><indexterm><primary>uncomment</primary></indexterm> +To remove comment markers, use the +<menuchoice><guimenu>Tools</guimenu><guimenuitem>Uncomment</guimenuitem></menuchoice> +menu item or the related keyboard shortcut, default is <keycombo +action="simul">&Ctrl;&Shift;<keycap>D</keycap></keycombo>.</para> + +</sect1> + +<sect1 id="advanced-editing-tools-commandline"> +<title>The Editor Component Command Line</title> + +<para>Kate's editor component has an internal command line, allowing you to +perform various actions from a minimal GUI. The command line is a text entry +in the bottom of the editor area, to show it select +<menuchoice><guimenu>View</guimenu><guimenuitem>Switch to Command Line</guimenuitem></menuchoice> +or use the keyboard shortcut (default is +<keycombo action="simul"><keycap>F7</keycap></keycombo>). The editor provides +a set of commands as documented below, and additional commands can be provided +by plugins.</para> + +<para>To execute a command, type the command and then press the enter key. The +command line will indicate whether it succeeded and possibly display a message. If +you entered the command line by pressing <keycap>F7</keycap> it will +automatically hide after a few seconds. To clear the message and enter a new +command, press <keycap>F7</keycap> again.</para> + +<para>The command line has a built-in help system, you can type the command +<command>help</command> to get started. To see a list of all available commands +type <command>help list</command>, to view help for a specific command, do +<command>help <replaceable>command</replaceable></command>.</para> + +<para>The command line has a built-in history too, so you can reuse commands already +typed. To navigate the history, use the <keycap>Up</keycap> and +<keycap>Down</keycap> keys. When showing historical commands, the argument part +of the command will be selected, allowing you to easily overwrite the +arguments.</para> + +<sect2 id="advanced-editing-tools-commandline-commands"> +<title>Standard Command Line Commands</title> + +<variablelist> +<title>Argument types</title> + +<varlistentry> +<term>BOOLEAN</term> +<listitem><para>This is used with commands that turn things on or off. +Legal values are <userinput>on</userinput>, <userinput>off</userinput>, +<userinput>true</userinput>, <userinput>false</userinput>, +<userinput>1</userinput>, <userinput>0</userinput></para></listitem> +</varlistentry> + +<varlistentry> +<term>INTEGER</term> +<listitem><para>An integer number</para></listitem> +</varlistentry> + +<varlistentry> +<term>STRING</term> +<listitem><para>A string</para></listitem> +</varlistentry> + +</variablelist> + +<sect3 id="advanced-editing-tools-commandline-commands-configure"> +<title>Commands for Configuring the Editor</title> + +<para>These commands are provided by the editor component, and allows you to +configure the active document and view only. This is handy if you want to use +a setting different from the default settings, for example for indentation. +</para> + +<variablelist> + +<varlistentry> +<term><cmdsynopsis><command>set-tab-width</command><arg>INTEGER width</arg></cmdsynopsis></term> +<listitem><para>Sets the tab width to the number <userinput>width</userinput></para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-indent-width</command><arg>INTEGER width</arg></cmdsynopsis></term> +<listitem><para>Sets the indentation width to the number +<userinput>width</userinput>. Used only if you are indenting with +spaces.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-word-wrap-column</command><arg>INTEGER width</arg></cmdsynopsis></term> +<listitem><para>Sets the line width for hard wrapping to +<userinput>width</userinput>. This is used if you are having your text wrapped +automatically.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-icon-border</command><arg>BOOLEAN enable</arg> +</cmdsynopsis></term> +<listitem><para>Sets the visibility of the icon border.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-folding-markers</command><arg>BOOLEAN enable</arg></cmdsynopsis></term> +<listitem><para>Sets the visibility of the folding markers pane.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-line-numbers</command><arg>BOOLEAN enable</arg></cmdsynopsis></term> +<listitem><para>Sets the visibility of the line numbers pane.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-replace-tabs</command><arg>BOOLEAN enable</arg></cmdsynopsis></term> +<listitem><para>If enabled, tabs are replaced with spaces as you type. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-remove-trailing-space</command><arg>BOOLEAN enable</arg></cmdsynopsis></term> +<listitem><para>If enabled, trailing whitespace are removed whenever the cursor +leaves a line.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-show-tabs</command><arg>BOOLEAN enable</arg></cmdsynopsis></term> +<listitem><para>If enabled, TAB characters and trailing whitespace will be +visualized by a small dot.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-indent-spaces</command><arg>BOOLEAN enable</arg></cmdsynopsis></term> +<listitem><para>If enabled, the editor will indent with +<option>indent-width</option> spaces for each indentation level, rather than +with one TAB character.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-mixed-indent</command><arg>BOOLEAN enable</arg></cmdsynopsis></term> +<listitem><para>If enabled, kate will use a mix of TAB and spaces for +indentation. Each indentation level will be <option>indent-width</option> wide, +and more indentation levels will be optimized to use as many TAB characters as +possible.</para> +<para>When executed, this command will additionally set space indentation enabled, +and if the indent width is unspecified it will be set to half of the +<option>tab-width</option> for the document at the time of execution.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-word-wrap</command><arg>BOOLEAN +enable</arg></cmdsynopsis></term> +<listitem><para>Enables dynamic word wrap according to +<userinput>enable</userinput></para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-replace-tabs-save</command><arg>BOOLEAN enable +</arg></cmdsynopsis></term> +<listitem><para>When enabled, tabs will be replaced with whitespaces whenever + the document is saved.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-remove-trailing-space-save</command><arg>BOOLEAN enable</arg></cmdsynopsis></term> +<listitem><para>When enabled, trailing space will be removed from each line +whenever the document is saved.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-indent-mode</command><arg>name</arg></cmdsynopsis></term> +<listitem><para>Sets the autoindentation mode to <userinput>name</userinput>. +If <userinput>name</userinput> is not known, the mode is set to 'none'. Valid +modes are 'cstyle', 'csands', 'xml', 'python', 'varindent' and 'none'.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-highlight</command><arg>highlight</arg></cmdsynopsis></term> +<listitem><para>Sets the syntax highlighting system for the document. The +argument must be a valid highlight name, as seen in the +<menuchoice><guimenu>Tools</guimenu><guisubmenu>Highlighting</guisubmenu></menuchoice> +menu. This command provides an autocompletion list for its +argument.</para></listitem> +</varlistentry> + +</variablelist> + +</sect3> + +<sect3 id="advanced-editing-tools-commandline-commands-edit"> +<title>Commands for editing</title> + +<para>These commands modify the current document.</para> + +<variablelist> +<varlistentry> +<term><cmdsynopsis><command>indent</command></cmdsynopsis></term> +<listitem><para>Indents the selected lines or the current line.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>unindent</command></cmdsynopsis></term> +<listitem><para>Unindents the selected lines or current line.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>cleanindent</command></cmdsynopsis></term> +<listitem><para>Cleans up the indentation of the selected lines or current line +according to the indentation settings in the document. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>comment</command></cmdsynopsis></term> +<listitem><para>Inserts comment markers to make the selection or selected lines +or current line a comment according to the text format as defined by the syntax +highlight definition for the document.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>uncomment</command></cmdsynopsis></term> +<listitem><para>Removes comment markers from the selection or selected lines +or current line according to the text format as defined by the syntax highlight +definition for the document.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>kill-line</command></cmdsynopsis></term> +<listitem><para>Deletes the current line.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>replace</command><arg>pattern</arg><arg>replacement</arg></cmdsynopsis></term> +<listitem><para>Replaces text matching <userinput>pattern</userinput> with +<userinput>replacement</userinput>. If you want to include whitespace in the +<userinput>pattern</userinput>, you must quote both the <userinput>pattern</userinput> +and <userinput>replacement</userinput> with single or double quotes. If the +arguments are unquoted, the first word is used as <userinput>pattern</userinput> +and the rest for <userinput>replacement</userinput>. If +<userinput>replacement</userinput> is empty, each occurrence of +<userinput>pattern</userinput> is removed.</para> +<para>You can set flags to configure the search by adding a colon, followed +by one or more letters each representing a configuration, giving the form +<userinput>replace:options pattern replacement</userinput>. Available options +are: + +<variablelist> + +<varlistentry> +<term><userinput>b</userinput></term> +<listitem><para>Search backwards.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>c</userinput></term> +<listitem><para>Search from cursor position.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>e</userinput></term> +<listitem><para>Search in the selection only.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>r</userinput></term> +<listitem><para>Do regular expression search. If set, you may use +<userinput>\N</userinput> where N is a number to represent captures in the +replacement string.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>s</userinput></term> +<listitem><para>Do case sensitive search.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>p</userinput></term> +<listitem><para>Prompt for permission to replace the next occurence.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>w</userinput></term> +<listitem><para>Match whole words only.</para></listitem> +</varlistentry> + +</variablelist> + +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>date</command><arg>format</arg></cmdsynopsis></term> +<listitem><para>Inserts a date/time string as defined by the specified +<userinput>format</userinput>, or the format <quote>yyyy-MM-dd hh:mm:ss</quote> +if none is specified. The following translations are done when interpreting +<userinput>format</userinput>: + +<informaltable> +<tgroup cols="2"> +<tbody> +<row><entry><literal>d</literal></entry><entry>The day as number without a leading zero (1-31).</entry></row> +<row><entry><literal>dd</literal></entry><entry>The day as number with a leading zero (01-31).</entry></row> +<row><entry><literal>ddd</literal></entry><entry>The abbreviated localized day name (e.g. 'Mon'..'Sun').</entry></row> +<row><entry><literal>dddd</literal></entry><entry>The long localized day name (e.g. 'Monday'..'Sunday').</entry></row> +<row><entry><literal>M</literal></entry><entry>The month as number without a leading zero (1-12).</entry></row> +<row><entry><literal>MM</literal></entry><entry>The month as number with a leading zero (01-12).</entry></row> +<row><entry><literal>MMM</literal></entry><entry>The abbreviated localized month name (e.g. 'Jan'..'Dec').</entry></row> +<row><entry><literal>yy</literal></entry><entry>The year as two digit number +(00-99).</entry></row> +<row><entry><literal>yyyy</literal></entry><entry>The year as four digit number (1752-8000).</entry></row> +<row><entry><literal>h</literal></entry><entry>The hour without a leading zero (0..23 or 1..12 if AM/PM display).</entry></row> +<row><entry><literal>hh</literal></entry><entry>The hour with a leading zero (00..23 or 01..12 if AM/PM display).</entry></row> +<row><entry><literal>m</literal></entry><entry>The minute without a leading zero (0..59).</entry></row> +<row><entry><literal>mm</literal></entry><entry>The minute with a leading zero (00..59).</entry></row> +<row><entry><literal>s</literal></entry><entry>The second without a leading zero (0..59).</entry></row> +<row><entry><literal>ss</literal></entry><entry>The second with a leading zero (00..59).</entry></row> +<row><entry><literal>z</literal></entry><entry>The milliseconds without leading zeroes (0..999).</entry></row> +<row><entry><literal>zzz</literal></entry><entry>The milliseconds with leading zeroes (000..999).</entry></row> +<row><entry><literal>AP</literal></entry><entry>Use AM/PM display. AP will be replaced by either "AM" or "PM".</entry></row> +<row><entry><literal>ap</literal></entry><entry>Use am/pm display. ap will be replaced by either "am" or "pm".</entry></row> + +</tbody> +</tgroup> +</informaltable> + +</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>char</command><arg>identifier</arg></cmdsynopsis></term> +<listitem> +<para>This command allows you to insert literal characters by their +numerical identifier, in decimal, octal or hexadecimal form. +To use it launch the Editing Command dialog and type <userinput>char: +[number]</userinput> in the entry box, then hit +<guibutton>OK</guibutton>.</para> + +<example> +<title><command>char</command> examples</title> + +<para>Input: <userinput>char:234</userinput></para> +<para>Output: <computeroutput>ê</computeroutput></para> +<para>Input: <userinput>char:0x1234</userinput></para> +<para>Output: <computeroutput>ሴ</computeroutput></para> +</example> + +</listitem> +</varlistentry> + +<varlistentry> +<term> +<indexterm><primary>replace, sed style</primary> +<secondary>search, sed style</secondary></indexterm> +<command>s///[ig]</command> and <command>%s///[ig]</command></term> + +<listitem> +<para>This command does a sed-like search/replace operation on the +current line, or on the whole file (<command>%s///</command>).</para> + +<para>In short, &kate; searches for text matching the +<emphasis>search pattern</emphasis> (the regular expression between +the first and the second slash), and when a match is found the +matching part of the text is replaced with the expression between the +middle and last slash. Parenthesis in the search pattern +create <emphasis>back references</emphasis>, that is the command +remembers which part of the text matched in the parenthesis. These +strings can be reused in the replace pattern, referred to as +<userinput>\1</userinput> for the first set of parenthesis, +<userinput>\2</userinput> for the second and so on.</para> + +<para>To search for a literal <literal>(</literal> or +<literal>)</literal>, you need to escape it using +a backslash character: <userinput>\(, \)</userinput></para> + +<para>If you put an <userinput>i</userinput> at the end of the +expression, the matching will be case insensitive. If you put a +<userinput>g</userinput> at the end, all occurrences of the pattern will be +replaced, otherwise only the first occurrence is replaced.</para> + +<example> + +<title>Replacing text in the current line</title> + +<para>Your friendly compiler just stopped, telling you that the class +<classname>myClass</classname> mentioned in line 3902 in your source file +is not defined.</para> + +<para>"Buckle!" you think, it is of course +<classname>MyClass</classname>. You go to line 3902, and instead of trying +to find the word in the text, you launch the Editing Command Dialog, +enter <userinput>s/myclass/MyClass/i</userinput>, hit the +<guibutton>OK</guibutton> button, save the file and compile +successfully without the error.</para> + +</example> + +<example> +<title>Replacing text in the whole file</title> + +<para>Imagine that you have a file, in which you mention a <quote>Miss +Jensen</quote> several times, when someone comes in and tells you that +she just got married to <quote>Mr. Jones</quote>. You want, of course, +to replace each and every occurrence of <quote>Miss Jensen</quote> +with <quote>Ms Jones</quote>.</para> + +<para>Enter the command line and issue the command +<userinput>%s/Miss Jensen/Ms. Jones/</userinput> and hit enter, you +are done.</para> + +</example> + +</listitem> + +</varlistentry> + +</variablelist> + +</sect3> + +<sect3 id="advanced-editing-tools-commandline-commands-navigation"> +<title>Commands for navigation</title> + +<variablelist> + +<varlistentry> +<term><cmdsynopsis><command>goto</command><arg>INT line</arg></cmdsynopsis></term> +<listitem><para>This command navigates to the specified line.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>find</command><arg>pattern</arg></cmdsynopsis></term> +<listitem><para>This command navigates to the first occurrence of +<userinput>pattern</userinput> according to the configuration. Following +occurrences can be found using +<menuchoice><guimenu>Edit</guimenu><guimenuitem>Find Next</guimenuitem></menuchoice> +(the default shortcut is <keycap>F3</keycap>).</para> +<para>The find command can be configured by appending a colon followed by one or +more options, the form is +<userinput>find:options pattern</userinput>. The +following options are supported: + +<variablelist> + +<varlistentry> +<term><userinput>b</userinput></term> +<listitem><para>Search backwards.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>c</userinput></term> +<listitem><para>Search from cursor position.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>e</userinput></term> +<listitem><para>Search in the selection only.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>r</userinput></term> +<listitem><para>Do regular expression search.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>s</userinput></term> +<listitem><para>Do case sensitive search.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>w</userinput></term> +<listitem><para>Match whole words only.</para></listitem> +</varlistentry> + +</variablelist> + +</para> + +</listitem> + +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>ifind</command><arg>pattern</arg></cmdsynopsis></term> +<listitem><para>This command provides <quote>incremental (as-you-type)</quote> searching. You +can configure the behavior of the search by appending a colon +followed by one or more options, like this: +<userinput>ifind:options pattern</userinput>. Allowed options are: + +<variablelist> +<varlistentry> +<term><userinput>b</userinput></term> +<listitem><para>Search backwards.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>r</userinput></term> +<listitem><para>Do regular expression search.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>s</userinput></term> +<listitem><para>Do case sensitive search.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>c</userinput></term> +<listitem><para>Search from cursor position.</para></listitem> +</varlistentry> + +</variablelist> +</para></listitem> +</varlistentry> + +</variablelist> + +</sect3> + +</sect2> + +</sect1> + +<sect1 id="advanced-editing-tools-code-folding"> +<title>Using Code Folding</title> + +<para>Code folding allows you to hide parts of a document in the editor, making +it easier to overview large documents. In &kate; the foldable regions are +calculated using rules defined in the syntax highlight definitions and +therefore it is only available in some file formats - typically program source code, +XML markup and similar. Most highlight definition files supporting code folding +also let you manually define foldable regions, typically using the +<userinput>BEGIN</userinput> and <userinput>END</userinput> keywords.</para> + +<para>To use the code folding feature, activate the folding markers using +<menuchoice><guimenu>View</guimenu><guimenuitem>Show Folding +Markers</guimenuitem></menuchoice> menu item if they are not already visible. +The Folding Markers Pane in the left side of the screen displays a graphical +view of the foldable regions, with +/- signs to indicate the possible operation +on a given region. A - means that the region is expanded; clicking on the - will +collapse the region and a + will be displayed instead.</para> + +<para>Four commands are provided to manipulate the state of folding regions, +see the <link linkend="view-code-folding">menu documentation</link> for details. +</para> + +<para>If you do not want to use the code folding feature, you can disable it +completely using the <guilabel>Show folding markers (if available)</guilabel> option in the +<link linkend="appearance-code-folding">Editor Appearance</link> configuration page</para> + +</sect1> + +<sect1 id="advanced-editing-tools-scripting"> + +<title>Scripting the editor with JS</title> + +<sect2 id="advanced-editing-tools-scripting-introduction"> + +<title>Introduction</title> + +<para>Starting with version 2.5, the &kate; editor component supports +scripting with ECMA script, also known as JavaScript.</para> + +<para>Scripts can be used through <link +linkend="advanced-editing-tools-commandline">the built-in command line</link> +only. The requirements are that the scripts are placed in a folder where &kate; +can find them, along with an optional .desktop file that defines the related +properties. The valid folders are named <filename>katepart/scripts</filename> +in the &tde; data folders. You can find the data folders by running the command +<command>tde-config <option>--path</option> <parameter>data</parameter></command>. +You will usually have at least a system and a personal data folder. Of course +scripts in the system data folder are available to all users on the system, +while those in the personal folder are available to you only.</para> + +</sect2> + +<sect2 id="advanced-editing-tools-scripting-reference"> + +<title>The Kate JavaScript API</title> + +<para>Here is the complete set of functions and properties available +in the <type>document</type> and <type>view</type> objects. +In addition, you can use all the standard objects such as +<type>Math</type>, <type>String</type> <type>Regex</type> and so forth.</para> + +<para>When a script is run, the <classname>document</classname> object is the +current document, and the <classname>view</classname> object is the current +view.</para> + +<note><para>Types are not used in JavaScript. In this list, they are +there solely to indicate what sort of arguments the functions expect.</para></note> + +<variablelist id="advanced-editing-tools-scripting-global"> +<title>Global Functions</title> +<varlistentry> +<term><function>debug(<parameter><replaceable>string s</replaceable></parameter>) +function</function></term> +<listitem> +<itemizedlist> +<title>parameters</title> +<listitem><para><parameter>s</parameter> the string to output.</para> +</listitem> +</itemizedlist> +<para>Outputs the string to <acronym>STDERR</acronym> using +<function>kdDebug()</function>. A dedicated output area is used for the output, +which will be prefixed by "<emphasis>Kate (KJS Scripts):</emphasis>" +</para> +</listitem> +</varlistentry> +</variablelist> + +<variablelist id="advanced-editing-tools-scripting-document"> +<title>The <classname>document</classname> API</title> + +<varlistentry> +<term><function>document.attribute(<parameter><replaceable>uint line</replaceable></parameter>, +<parameter><replaceable>uint column</replaceable></parameter>) +function</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>line</parameter> the line of the position for which +to find the attribute.</para></listitem> +<listitem><para><parameter>column</parameter> the column of the position for +which to find the attribute.</para></listitem> +</itemizedlist> +<para>Returns the numeric ID of the attribute for the document position +[<parameter>line</parameter>, <parameter>column</parameter>]. The attribute +represents the visual appearance or style of the text, and is also used to +calculate the syntax highlight for a specific part of the text in mixed formats +like HTML or PHP.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.canBreakAt(<parameter>char c</parameter>, +<parameter>attribute attrib</parameter>) function</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>c</parameter> the character to test.</para></listitem> +<listitem><para><parameter>attrib</parameter> the attribute at the position +of <parameter>c</parameter>.</para></listitem> +</itemizedlist> +<para>Returns whether it is allowed to break the line at the character +<parameter>c</parameter> with attribute <parameter>attribute</parameter>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.canComment(<parameter>attribute start_attrib</parameter>, +<parameter>attribute end_attrib</parameter>) function</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>start_attrib</parameter> the attribute at the +start of the range to turn into a comment.</para></listitem> +<listitem><para><parameter>end_attrib</parameter> the attribute at end of +the range to turn into a comment.</para></listitem> +</itemizedlist> +<para>Returns whether <parameter>start_attribute</parameter> and +<parameter>end_attribute</parameter> belongs to the same +syntax highlight system. If they do, it is possible to comment the block. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.clear() function</function></term> +<listitem><para>Clears the document.</para></listitem> +</varlistentry> + +<varlistentry> +<term><function>document.commentStart(<parameter>attribute attrib</parameter>) +function</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>attrib</parameter> the attribute of the text for +which to get the commentStart string.</para></listitem> +</itemizedlist> +<para>Returns the string required to start a multiline comment for a text with +attribute <parameter>attrib</parameter>, or an empty string if multiline comments are not supported for that +text.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.commentMarker(<parameter>attribute attrib</parameter>) +function</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>attrib</parameter> the attribute of the text for +which to get the commentMarker string.</para></listitem> +</itemizedlist> +<para>Returns the string used to mark the rest of the line as a comment for a +text with attribute <parameter>attrib</parameter> or an empty string if single +line comments are not supported for that text.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.commentEnd(<parameter>attribute attrib</parameter>) +function</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>attrib</parameter> the attribute of the text for +which to get the commentEnd string.</para></listitem> +</itemizedlist> +<para>Returns the string required to end a multiline comment for a text with +attribute <parameter>attrib</parameter>, or an empty string if multiline +comments are not supported for that text.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.editBegin() function</function></term> +<listitem> +<para>Starts an editing group. All actions done until the call to editEnd() will +be grouped as a single undo action.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.editEnd() function</function></term> +<listitem> +<para>Ends an editing group.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.highlightMode property, read only</function></term> +<listitem> +<para>The name of the document's highlight mode, such as JavaScript or C++. +If no syntax highlight mode is set for the document, the value is <emphasis>none</emphasis>. +Notice that you need to use the English name in cases where it differs from the +translated one.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.indentMode property, read only</function></term> +<listitem> +<para>The name of the document indent mode, such as +<literal>normal</literal> or <literal>cstyle</literal>. +If no indent mode is set, the value is <emphasis>none</emphasis>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.indentWidth property, read only</function></term> +<listitem> +<para>The indentation width set for the document. This is used if space +indenting is enabled.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.insertLine(<parameter>uint line</parameter>, +<parameter>string text</parameter>) function</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>line</parameter> the document line number.</para> +</listitem> +<listitem><para><parameter>text</parameter> the text to insert.</para></listitem> +</itemizedlist> +<para>Inserts a new line with the text <parameter>text</parameter> at the +line <parameter>line</parameter>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.insertText(<parameter>uint line</parameter>, +<parameter>uint column</parameter>, <parameter>string text</parameter>) +function</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>line</parameter> the line number.</para></listitem> +<listitem><para><parameter>column</parameter> the column number.</para></listitem> +<listitem><para><parameter>text</parameter> the text to insert.</para></listitem> +</itemizedlist> +<para>Inserts the text <parameter>text</parameter> in line +<parameter>line</parameter> at column <parameter>column</parameter>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>document.length() function</term> +<listitem> +<para>Returns the document's size in bytes.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.lines() function</function></term> +<listitem> +<para>Returns the number of lines in the document.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>document.mixedIndent property, read only</term> +<listitem> +<para>A boolean telling whether the mixed-indent setting is enabled for the +document. If so, indentation is optimized to contain a mix of tab characters and +spaces like in the Emacs editor.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>document.removeLine(<parameter>uint line</parameter>) function</term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>line</parameter> the line number.</para></listitem> +</itemizedlist> +<para>Removes the document line <parameter>line</parameter>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.removeText(<parameter>uint startLine</parameter>, +<parameter>uint startColumn</parameter>, <parameter>uint endLine</parameter>, +<parameter>uint endColumn</parameter>) function</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>startLine</parameter> specifies the beginning line.</para></listitem> +<listitem><para><parameter>startColumn</parameter> specifies the beginning column.</para></listitem> +<listitem><para><parameter>endLine</parameter> specifies the ending line.</para></listitem> +<listitem><para><parameter>endColumn</parameter> specifies the ending column.</para></listitem> +</itemizedlist> +<para>Removes the text range from line <parameter>startLine</parameter> and +column <parameter>startColumn</parameter> to line +<parameter>endLine</parameter> and column <parameter>endColumn</parameter>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.setText(<parameter>string text</parameter>) +function</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>text</parameter> the new document text.</para></listitem> +</itemizedlist> +<para>Sets the entire document content to <parameter>text</parameter>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.spaceIndent property, read only</function></term> +<listitem> +<para>A boolean telling whether space-indent is enabled for the document. +If so, the document is indented with indentWidth spaces per level, otherwise +indentation is one tab character per level.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.textFull() function</function></term> +<listitem> +<para>Returns the full document text. If the text spans over multiple lines the +linefeed character is <constant>\n</constant>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.textLine(<parameter>uint line</parameter>) function</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>line</parameter> the line number.</para></listitem> +</itemizedlist> +<para>Returns the text at line <parameter>line</parameter>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.textRange(<parameter>uint startLine</parameter>, +<parameter>uint startColumn</parameter>, <parameter>uint endLine</parameter>, +<parameter>uint endColumn</parameter>) function</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>startLine</parameter> specifies the beginning line.</para></listitem> +<listitem><para><parameter>startColumn</parameter> specifies the beginning column.</para></listitem> +<listitem><para><parameter>endLine</parameter> specifies the ending line.</para></listitem> +<listitem><para><parameter>endColumn</parameter> specifies the ending column.</para></listitem> +</itemizedlist> +<para>Returns the specified text range. If the range spans over multiple lines +the linefeed character is <constant>\n</constant>.</para> +</listitem> +</varlistentry> + +</variablelist><!--/ document API --> + +<variablelist id="advanced-editing-tools-scripting-view"> +<title>The <classname>view</classname> API</title> + +<varlistentry> +<term><function>view.clearSelection() function</function></term> +<listitem> +<para>Deselects all text.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.cursorColumn() function</function></term> +<listitem> +<para>Returns the current cursor column (TAB characters are expanded).</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.cursorColumnReal() function</function></term> +<listitem> +<para>Returns the current real cursor column (a TAB character counts as one).</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.cursorLine() function</function></term> +<listitem> +<para>Returns the current cursor line.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.hasSelection() function</function></term> +<listitem> +<para>Returns <constant>true</constant> if some text in the view has been selected, +otherwise <constant>false</constant>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.removeSelectedText() function</function></term> +<listitem> +<para>Removes the selected text, if the view has a selection.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.selectAll() function</function></term> +<listitem> +<para>Selects all text.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.selection() function</function></term> +<listitem> +<para>Returns the selected text. If the selection spans over multiple lines the +linefeed character is <constant>\n</constant>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.selectionEndColumn property, read only</function></term> +<listitem> +<para>Returns the ending column of the selection.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.selectionEndLine property, read only</function></term> +<listitem> +<para>Returns the ending line of the selection.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.selectionStartColumn property, read only</function></term> +<listitem> +<para>Returns the starting column of the selection.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.selectionStartLine property, read only</function></term> +<listitem> +<para>Returns the starting line of the selection.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.setCursorPosition(<parameter>uint line</parameter>, +<parameter>uint column</parameter>) function</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>line</parameter> specifies the new line for the cursor.</para></listitem> +<listitem><para><parameter>column</parameter> specifies the new column for the cursor.</para></listitem> +</itemizedlist> +<para>Sets the input cursor position in the view to (<parameter>line</parameter>, +<parameter>column</parameter>). TAB characters are expanded and +the cursor position is made visible. Both <parameter>line</parameter> +and <parameter>column</parameter> are zero-based.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.setCursorPositionReal(<parameter>uint line</parameter>, +<parameter>uint column</parameter>) function</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>line</parameter> specifies the new line for the cursor.</para></listitem> +<listitem><para><parameter>column</parameter> specifies the new column for the cursor.</para></listitem> +</itemizedlist> +<para>Sets the input cursor position to (<parameter>line</parameter>, +<parameter>column</parameter>). This sets the string position, that is a TAB +character counts for 1, and the cursor position is made visible. Both <parameter>line</parameter> +and <parameter>column</parameter> are zero-based.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.setSelection(<parameter>uint startLine</parameter>, +<parameter>uint startColumn</parameter>, <parameter>uint endLine</parameter>, +<parameter>uint endColumn</parameter>) function</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>startLine</parameter> specifies the beginning line.</para></listitem> +<listitem><para><parameter>startColumn</parameter> specifies the beginning column.</para></listitem> +<listitem><para><parameter>endLine</parameter> specifies the ending line.</para></listitem> +<listitem><para><parameter>endColumn</parameter> specifies the ending column.</para></listitem> +</itemizedlist> +<para>Sets a selection from line <parameter>startLine</parameter> and column +<parameter>startColumn</parameter> to line <parameter>endLine</parameter> +and column <parameter>endColumn</parameter>.</para> +</listitem> +</varlistentry> + +</variablelist> + +<example id="advanced-editing-tools-scripting-example"> + +<title>A sample script</title> +<para>As an example we will create a small script that transforms the selected +text to upper case. We first need to check whether a selection exists: if so we +get the text, change the case and then replace the original text with the new one. +An implementation would look something like this:</para> + +<programlisting> +if (view.hasSelection()) +{ + // uppercase selection + column = view.selectionStartColumn; + line = view.selectionStartLine; + + selection = view.selection().toUpperCase(); + + document.editBegin(); + view.removeSelectedText(); + document.insertText(line, column, selection); + document.editEnd(); +} +</programlisting> + +<para>To group this actions together so that they will be reverted by a single +activation of <guimenuitem>Undo</guimenuitem>, we encapsulate the lines +<programlisting> +view.removeSelectedText() +document.insertText() +</programlisting> in a <emphasis>document.editBegin()</emphasis> - +<emphasis>document.editEnd()</emphasis> block.</para> + +</example> + +<example id="advanced-editing-tools-desktop-example"> +<title>A sample <filename>.desktop</filename> file</title> + +<para>Here is a sample .desktop file that accompanies the above script.</para> + +<programlisting> +# Example of a .desktop file +[Desktop Entry] +Encoding=UTF-8 +Name=Kate Part JavaScript Uppercase Script +Comment=Script to transform the selected text to upper case +X-Kate-Command=uppercase-selection +X-Kate-Help=<p>Usage: <code>uppercase-selection</code></p> +</programlisting> + +<para>As you can see you can define the Encoding, set a Name, a Comment, a help +text using X-Kate-Help and the command line name via X-Kate-Command.</para> + +</example> + +<sect3> +<title>Putting it all together</title> + +<para>&kate; will search the script folders (see <link +linkend="advanced-editing-tools-scripting-introduction">above</link>) for +<filename>.js</filename> files. For every such file found, &kate; will check +whether there is a corresponding <filename>.desktop</filename> file with +the same basename (for example script.js and script.desktop).</para> +<para>If a corresponding <filename>.desktop</filename> file exists, the script +will be registered using the name from the .desktop entry <emphasis>X-Kate-Command</emphasis>.</para> +<para>If a corresponding <filename>.desktop</filename> file can not be found, the script will +be registered with the file basename (i.e. without the ending .js). +If you only need the command name and none of the extra features +that a <filename>.desktop</filename> file would provide, you do not need a +<filename>.desktop</filename> file at all.</para> + +</sect3> + +</sect2> + +</sect1> + +</chapter> diff --git a/doc/kate/configdialog01.png b/doc/kate/configdialog01.png Binary files differnew file mode 100644 index 000000000..751066792 --- /dev/null +++ b/doc/kate/configdialog01.png diff --git a/doc/kate/configdialog02.png b/doc/kate/configdialog02.png Binary files differnew file mode 100644 index 000000000..70a7ecaed --- /dev/null +++ b/doc/kate/configdialog02.png diff --git a/doc/kate/configuring.docbook b/doc/kate/configuring.docbook new file mode 100644 index 000000000..f7cd3bff6 --- /dev/null +++ b/doc/kate/configuring.docbook @@ -0,0 +1,1595 @@ +<chapter id="configuring-kate"> +<chapterinfo> +<authorgroup> +<author>&Anders.Lund; &Anders.Lund.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</chapterinfo> +<title>Configuring &kate;</title> + +<sect1 id="configuring-overview"> +<title>Overview</title> +<para> +<indexterm> +<primary>configure</primary> +<secondary>settings</secondary> +<tertiary>preferences</tertiary></indexterm> +<anchor id="find"/> +<anchor id="find-again"/> +<!-- <anchor id="print"/> --> +<anchor id="replace"/> +<!-- <anchor id="save"/> --> +<anchor id="undo"/> +<anchor id="redo"/> +&kate; offers several means of tweaking the application to behave as desired. +The most important ones are: +</para> + +<variablelist> +<varlistentry> +<term id="configure">The Configuration Dialog</term> +<listitem><para>The main configuration tool, allowing you to configure the &kate; application, +the editor component and the usage of plugins.</para></listitem> +</varlistentry> +<varlistentry> +<term id="settings">The <guimenu>Settings</guimenu> Menu</term> +<listitem><para>Allows you to change often used settings, and to +launch the configuration dialogs.</para></listitem> +</varlistentry> +<varlistentry> +<term>The <guimenu>View</guimenu> Menu</term> +<listitem><para>Allows you to split the current frame, as well as to +display the icons and line numbers pane for the currently edited +document.</para></listitem> +</varlistentry> +</variablelist> + +<para>The embedded &konsole; is using the configuration defined in the +&kcontrolcenter;, and may be configured by clicking the +<mousebutton>right</mousebutton> mouse button and choosing from the +<guimenuitem>Settings</guimenuitem> sub menu.</para> + +</sect1> + +<sect1 id="configuring-kate-configdialog"> +<title>The Main Configuration Dialog</title> + +<mediaobject> +<imageobject> +<imagedata format="PNG" fileref="configdialog01.png"/> +</imageobject> +</mediaobject> + +<para>The &kate; configuration dialog displays a tree of topics on the +left, and a configuration page corresponding to the selected topic on +the right.</para> + +<para>The configuration is divided into two groups, namely +<itemizedlist> +<listitem><para><link linkend="config-dialog">Application configuration</link> +</para></listitem> +<listitem><para><link linkend="config-dialog-editor">Editor component configuration</link></para></listitem> + +</itemizedlist> + +</para> + +</sect1> + +<sect1 id="config-dialog"> +<title>The &kate; Application Configuration</title> +<para>This group contains pages to configure the main &kate; application</para> + +<sect2 id="config-dialog-general"> +<title>The General Page</title> +<para>This section contains a few global options for &kate;</para> + +<variablelist> + +<varlistentry> +<term><anchor id="config-dialog-general-show-full-path" /> +<guilabel>Show Full Path in Title</guilabel></term> +<listitem><para>When enabled, Kate will display the full URL of your +current document in the window title, rather than just the file name.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="config-general-behavior"/> +<guilabel>Behavior</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term> +<anchor id="config-dialog-general-sync-konsole"/> +<guibutton>Sync terminal emulator with active document</guibutton></term> +<listitem><para>This will cause the built-in &konsole; to +<command>cd</command> into the directory of the active document when +launched and when a new document gets the focus. If not enabled, you +have to do all your navigation in the &konsole; on your own. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="config-dialog-general-warn-mod"/> +<guilabel>Warn about files modified by foreign processes</guilabel></term> +<listitem><para>When enabled, &kate; will notify you about files modified +from outside the application whenever the main window receives input focus. +You will be able to deal with several modified files at once, you +can reload, save or discard changed files in groups.</para> +<para>If not enabled, &kate; will prompt you for action when a externally +modified file receives focus within the application.</para> +</listitem> +</varlistentry> + +</variablelist> +</listitem> +</varlistentry><!-- /behavior group --> + +<varlistentry> +<term><anchor id="config-general-meta-data"/> +<guilabel>Meta Data</guilabel></term> +<listitem> + +<variablelist> +<varlistentry> +<term><anchor id="config-general-keep-meta-information"/> +<guilabel>Keep meta-information past sessions</guilabel></term> +<listitem><para>When enabled, &kate; will store meta data such as bookmarks +and session configuration even when you close your documents. The data +will be used if the document is unchanged when reopened.</para></listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="config-general-delete-meta-information-after"/> +<guilabel>Delete unused meta information after</guilabel></term> +<listitem><para>Set the maximum number of days to keep meta information +for unopen files. This helps keeping the database of meta information +reasonably sized.</para></listitem> +</varlistentry> + +</variablelist> + +</listitem> +</varlistentry><!-- /meta data group --> + +</variablelist> +</sect2> + +<sect2 id="config-dialog-sessions"> +<title>The Sessions Page</title> + +<para>This section contains options related to <link +linkend="fundamentals-using-sessions">using sessions</link>.</para> + +<variablelist> + +<varlistentry> +<term><anchor id="config-dialog-sessions-elements"/> +<guilabel>Elements of Sessions</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Include window configuration</guilabel></term> +<listitem><para>If enabled, &kate; will save the window configuration +with each session.</para></listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry><!-- /elements of sessions --> + +<varlistentry> +<term><anchor id="config-dialog-sessions-startup-behavior"/> +<guilabel>Behavior on Application Startup</guilabel></term> +<listitem> +<para>Select how you want &kate; to behave at startup. This setting can be +overridden by specifying what to do on the <link +linkend="command-line-options">command line</link>.</para> +<variablelist> +<varlistentry> +<term><guilabel>Start new session</guilabel></term> +<listitem><para>With this option, &kate; will start a new, unnamed session +when you start it.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Load last used session</guilabel></term> +<listitem><para>&kate; will use the most recently opened session at +startup. This is good if you want to use the same session always or switch +rarely.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Manually choose a session</guilabel></term> +<listitem><para>&kate; will display a small dialog that lets you choose +your preferred session. This is the default behavior. Nice if you use a lot of +different sessions frequently.</para></listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry><!-- /startup behavior --> + +<varlistentry> +<term><anchor id="config-dialog-sessions-exit-behavior"/> +<guilabel>Behavior on Application Exit or Session Switch</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Do not save session</guilabel></term> +<listitem><para>The changes to the session data (open files and if enabled, +window configuration) will not be saved. You will of course be prompted if you +have unsaved files. With this option, your can configure your sessions once, and +not worry about closing extra files that you opened and do not want to see +next time you use the session.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Save Session</guilabel></term> +<listitem><para>&kate; will save session data, except if the session is unnamed. +With this option, your sessions are allways restored just like you left them. +This is the default behavior. +</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Ask user</guilabel></term> +<listitem><para>You will be asked if you want to save the session every time a +named session is closed.</para></listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry><!-- /exit/switch behavior --> + +</variablelist> + +</sect2> + +<sect2 id="config-dialog-fileselector"> +<title>The <guilabel>Filesystem Browser</guilabel> Page</title> + +<variablelist> +<varlistentry> +<term><guilabel>Toolbar</guilabel></term> +<listitem><para>Configure the buttons on the file system 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> + +<varlistentry> +<term><guilabel>Auto Synchronization</guilabel></term> +<listitem><para>You can have the filesystem browser automatically navigate to +the directory containing the current document on certain events: +<itemizedlist> +<listitem><para>When a new document becomes the active one.</para></listitem> +<listitem><para>When the filesystem browser becomes visible.</para></listitem> +</itemizedlist> +Even if you select not to use this feature, you can manually synchronize the +browser with the current document by pressing the +<guilabel>Synchronize</guilabel> toolbar button. +</para></listitem> +</varlistentry> + +<varlistentry id="config-dialog-fileselector-urls"> +<term><guilabel>Remember locations</guilabel></term> +<listitem><para>Select how long a browsing history you want. The browser does +only remember individual locations, duplicates are removed.</para></listitem> +</varlistentry> + +<varlistentry id="config-dialog-fileselector-filters"> +<term><guilabel>Remember filters</guilabel></term> +<listitem><para>Select how many filters you want remembered. Only individually +distinct filters are remembered, duplicates are removed.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Session</guilabel></term> +<listitem> +<para>Configure wether the file system browser should remember its location and +filter over sessions.</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="config-dialog-documentlist"> +<title>The <guilabel>Document List</guilabel> Page</title> + +<variablelist> +<varlistentry> +<term><guilabel>Backgound Shading</guilabel></term> +<listitem><para>This section allows you to enable or disable the background +shading visualization of your recent activity, and chose which colors to use if +enabled. See the section about <link +linkend="kate-mdi-tools-document-list">The Document List</link> for more about +this feature.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Sort By</guilabel></term> +<listitem><para>Set how you want the document list sorted. This can be set +from the &RMB; menu in the document list as well.</para></listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2 id="config-dialog-plugins"> +<title>The <guilabel>Plugins</guilabel> Page</title> + +<para>This page provides a list of installed plugins for the &kate; +application. Each plug-in is represented with its name and a short description. +You can check the checkbox with an item to enable the plug-in it represents. +</para> + +<para>If a plug-in provides configuration options, a section to access those +will appear as a child of this page.</para> + +</sect2> + + +<sect2 id="config-dialog-externaltools"> +<title>External Tools</title> + +<para>In the <guimenu>Tools</guimenu> menu you will find a submenu labeled +<guisubmenu>External Tools</guisubmenu>. These tools invokes external +applications with data related to the current document, for example its URL, +directory, text or selection. This page allows you to manage the menu and edit, +remove or add new tools.</para> + +<para>Each external tool is a shell command which contains macros representing +the document data. When activated, the macros are substituted with data from the +active document.</para> + +<variablelist> +<title>External Tools Properties</title> +<varlistentry> +<term>Label</term> +<listitem><para>A friendly label for the External Tools menu.</para></listitem> +</varlistentry> + +<varlistentry> +<term>Script</term> +<listitem><para>The script to execute when the tool is activated. Before passing +the script to the shell, the following macros are substituted: + +<variablelist> +<varlistentry> +<term>%URL</term> +<listitem><para>The full URL of the current document, or an empty string if the +document is unsaved.</para></listitem> +</varlistentry> + +<varlistentry> +<term>%URLS</term> +<listitem><para>A space seperated list of the URLs of all open documents +(except unsaved ones).</para></listitem> +</varlistentry> + +<varlistentry> +<term>%directory</term> +<listitem><para>The directory part of the current documents URL or an empty +string if the current document is unsaved.</para></listitem> +</varlistentry> + +<varlistentry> +<term>%filename</term> +<listitem><para>the filename of the current document without the path, or an +empty string if the current document is unsaved.</para></listitem> +</varlistentry> + +<varlistentry> +<term>%line</term> +<listitem><para>The line number of the insertion cursor is in the current +document.</para></listitem> +</varlistentry> + +<varlistentry> +<term>%column</term> +<listitem><para>The column number of the insertion cursor in the current +document.</para></listitem> +</varlistentry> + +<varlistentry> +<term>%selection</term> +<listitem><para>The selected text in the current document, or an empty string +if no text is selected</para></listitem> +</varlistentry> + +<varlistentry> +<term>%text</term> +<listitem><para>The full text of the current document. Beware that this will +potentially exceed the maximum command length allowed on your system. +Use with care.</para></listitem> +</varlistentry> + +</variablelist> + +</para></listitem> +</varlistentry> + +<varlistentry> +<term>Executable</term> +<listitem><para>The main executable is the script. This is mandatory, and is used +to test if the command can be run at all. A fully qualified path is allowed +in case the executable is not in your <envar>PATH</envar> variable.</para></listitem> +</varlistentry> + +<varlistentry> +<term>Mimetypes</term> +<listitem><para>A semicolon separated list of mimetypes for which this command +should be enabled. This is currently unused.</para></listitem> +</varlistentry> + +<varlistentry> +<term>Save</term> +<listitem><para>You can optionally select to have the current or all documents +saved prior to executing the script. This is handy if your script reads the file +from disk.</para></listitem> +</varlistentry> + +<varlistentry> +<term>Command Line Name</term> +<listitem><para>If you fill this, the tool will be available in the +<link linkend="advanced-editing-tools-commandline">editors command line</link> as +<command>exttool-<replaceable>Command Line Name</replaceable></command> +(the string you enter here prepended <quote>exttool-</quote>).</para></listitem> +</varlistentry> + +</variablelist> + +</sect2> + +</sect1> + +<sect1 id="config-dialog-editor"> +<title>The Editor Component Configuration</title> +<para>This group contains all pages related to the editor component of +&kate;. Most of the settings here are defaults, they can be overridden by +<link linkend="config-dialog-editor-filetypes">defining a filetype</link>, +by <link linkend="config-variables">Document Variables</link> or by changing +them pr. document during an editing session.</para> + + +<sect2 id="config-dialog-editor-appearance"> +<title>Appearance</title> + +<variablelist> +<varlistentry> +<term><guilabel>Word Wrap</guilabel></term> +<listitem> +<variablelist> +<varlistentry id="appearance-settings"> +<term><guilabel>Dynamic word wrap</guilabel></term> +<listitem><para>If this option is checked, the text lines +will be wrapped at the view border on the screen.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Dynamic word wrap indicators</guilabel></term> +<listitem><para>Choose when the Dynamic word wrap indicators +should be displayed. +</para></listitem></varlistentry> +<varlistentry> +<term><guilabel>Vertically align dynamically wrapped lines +to indentation depth: +</guilabel></term> +<listitem><para>Enables the start of dynamically wrapped +lines to be aligned vertically to the indentation level of the first +line. This can help to make code and markup more +readable.</para><para>Additionally, this allows you to +set a maximum width of the screen, as a percentage, +after which dynamically wrapped lines will no longer be vertically aligned. +For example, at 50%, lines whose indentation levels are deeper than 50% of the +width of the screen will not have vertical alignment applied to subsequent +wrapped lines.</para></listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry id="appearance-code-folding"> +<term><guilabel>Code Folding</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Show folding markers (if available) +</guilabel></term> +<listitem><para>If this option is checked, the current view will display marks +for code folding, if code folding is available.</para></listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Borders</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Show icon border +</guilabel></term> +<listitem><para>If this is checked, you will see an icon border on the left +hand side. The icon border shows bookmark signs for instance.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Show line numbers +</guilabel></term> +<listitem><para>If this is checked, you will see line numbers on the left +hand side.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Show scrollbar marks +</guilabel></term> +<listitem><para>If this option is checked the current view +will show marks on the vertical scrollbar. These marks will +for instance show bookmarks.</para></listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Sort Bookmarks Menu +</guilabel></term> +<listitem><para> +<variablelist> +<varlistentry> +<term><guilabel>By position +</guilabel></term> +<listitem><para>The bookmarks will be ordered by the line +numbers they are placed at.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>By creation +</guilabel></term> +<listitem><para>Each new bookmark will be added to the bottom, +independently from where it is placed in the document.</para></listitem> +</varlistentry> +</variablelist> +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Show identation lines +</guilabel></term> +<listitem><para>If this is checked, the editor wil display +vertical lines to help identifying indent lines.</para></listitem> +</varlistentry> +</variablelist> +</sect2> + +<sect2 id="config-dialog-editor-colors"> +<title>Fonts & Colors</title> + +<para>This section of the dialog lets you configure all fonts and colors in +any color scheme you have, as well creating new schemes or deleting existing +ones. Each scheme has settings for colors, fonts and normal and highlight text +styles. +</para> + +<para>&kate; will preselect the currently active scheme for you, if you want to +work on a different scheme start by selecting that from the +<guilabel>Schema</guilabel> combobox.</para> + +<sect3 id="config-dialog-editor-colors-colors"> +<title>Colors</title> + +<variablelist> +<varlistentry id="config-dialog-editor-colors-colors-text-background"> +<term><guilabel>Text Area Background</guilabel></term> +<listitem> + +<variablelist> + +<varlistentry id="config-dialog-editor-colors-normal-text"> +<term><guilabel>Normal text</guilabel></term> +<listitem><para>This is the default background for the editor area, it will be +the dominant color on the editor area.</para></listitem> +</varlistentry> + +<varlistentry id="config-dialog-editor-colors-selected-text"> +<term><guilabel>Selected Text</guilabel></term> +<listitem><para>This is the background for selected text. The default is +the global selection color, as set in your &tde; color preferences. +</para></listitem> +</varlistentry> + +<varlistentry id="config-dialog-editor-colors-current-line"> +<term><guilabel>Current Line</guilabel></term> +<listitem><para>Set the color for the current line. Setting this a bit different +from the Normal text background helps to keep focus on the current line. +</para></listitem> +</varlistentry> + +<varlistentry id="config-dialog-editor-colors-marks"> +<term><guilabel>Bookmark</guilabel></term> +<listitem><para>This combo lets you set overlay colors for various mark types. +The color is mixed into the background color of a marked line, so that a line +with more marks or a marked line that is current has a background that is a mix +of more colors. The mark colors are also used if you enable display of scrollbar +marks.</para></listitem> +</varlistentry> + +</variablelist> +</listitem> +</varlistentry> + +<varlistentry id="config-dialog-editor-colors-colors-other-elements"> +<term><guilabel>Other Elements</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Left Border Background</guilabel></term> +<listitem><para>This color is used for the marks, line numbers and folding +marker borders in the left side of the editor view when they are displayed. +</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Line Numbers</guilabel></term> +<listitem><para>This color is used to draw the line numbers on the left side of +the view when displayed.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Bracket Highlight</guilabel></term> +<listitem><para>This color is used to draw the background of matching brackets. +</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Word Wrap Markers</guilabel></term> +<listitem><para>This color is used to draw a pattern to the left of dynamically +wrapped lines when those are aligned vertically, as well as for the static word +wrap marker.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Tab Markers</guilabel></term> +<listitem><para>This color is used to draw white space indicators when enabled. +</para></listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +</variablelist> +</sect3> + +<sect3 id="config-dialog-editor-colors-fonts"> +<title>Fonts</title> +<para> +Here you can choose the font for the schema. You can choose from +any font available on your system, and set a default size. A sample text +displays at the bottom of the dialog, so you can see the effect of your choices. +</para> +</sect3> + +<sect3 id="config-dialog-editor-colors-normal-text-styles"> +<title>Normal Text Styles</title> +<para>The normal text styles are inherited by the highlight text styles, +allowing the editor to present text in a very consistent way, for example comment +text is using the same style in allmost all of the text formats that kate can +highlight.</para> +<para>The name in the list of styles is using the style configured for +the item, providing you with an immediate preview when configuring a style. +</para> +<para>Each style lets you select common attributes as well as foreground +and background colors. To unset a background color, rightclick to use the +context menu.</para> +</sect3> + +<sect3 id="config-dialog-editor-colors-highlighting-text-styles"> +<title>Highlighting Text Styles</title> +<para>Here you can edit the text styles used by a specific highlight definition. +The editor preselects the highlight used by your current document. To work on a +different highlight, select one in the <guilabel>Highlight</guilabel> combobox +above the style list. +</para> +<para>The name in the list of styles is using the style configured for +the item, providing you with an immediate preview when configuring a style. +</para> +<para>Each style lets you select common attributes as well as foreground +and background colors. To unset a background color, rightclick to use the +context menu. In addition you can see if a style is equal to the default style +used for the item, and set it to that if not.</para> +<para>You will notice that many highlights contain other highlights represented +by groups in the style list. For example most highlights import the Alert +highlight, and many source code formats imports the Doxygen highlight. Editing +colors in those groups only affects the styles when used in the edited highlight +format. +</para> +</sect3> + +</sect2> + +<sect2 id="config-dialog-editor-cursor-selection"> +<title>Cursor & Selection</title> + +<variablelist> + +<varlistentry> +<term><guilabel>Text Cursor Movement</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Smart home</guilabel></term> +<listitem> +<para>When selected, pressing the home key will cause the cursor to +skip white space and go to the start of a line's text.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Wrap cursor</guilabel></term> +<listitem> +<para>When on, moving the insertion cursor using the <emphasis +role="bold">Left</emphasis> and <emphasis role="bold">Right</emphasis> keys will +go on to previous/next line at beginning/end of the line, similar to most +editors.</para><para>When off, the insertion cursor cannot be moved left of the +line start, but it can be moved off the line end, which can be very handy for +programmers. When this option is chosen, moving the cursor with the arrow keys +off the end of a line (to the right) causes it to jump down to the beginning of +the next line. Likewise when the cursor is moved past the beginning of a line +(to the left) it jumps up to the end of the preceding line. When this option is +not selected, moving the cursor right past the end of a line merely causes it to +continue horizontally in the same line and trying to move it left past the +beginning does nothing.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Page Up/Page Down moves cursor</guilabel></term> +<listitem> +<para>This option changes the behavior of the cursor when the user presses +the <keycap>Page Up</keycap> or <keycap>Page Down</keycap> key. If unselected +the text cursor will maintain its relative position within the visible text in +&kate; as new text becomes visible as a result of the operation. So if the +cursor is in the middle of the visible text when the operation occurs it will +remain there (except when one reaches the beginning or end.) With this option +selected, the first key press will cause the cursor to move to either the top or +bottom of the visible text as a new page of text is displayed.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Autocenter cursor (lines):</guilabel></term> +<listitem> +<para>Sets the number of lines to maintain visible above and below the cursor +when possible.</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry id="config-dialog-editor-selection-mode"> +<term><guilabel>Selection Mode</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Normal</guilabel></term> +<listitem> +<para>Selections will be overwritten by typed text and will be lost on +cursor movement.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Persistent</guilabel></term> +<listitem> +<para>Selections will stay even after cursor movement and typing.</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +</variablelist> +</sect2> + +<sect2 id="config-dialog-editor-edit"> +<title>Editing</title> +<variablelist> + +<varlistentry> +<term><guilabel>Tabulators</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Insert spaces instead of tabulators</guilabel></term> +<listitem> +<para>When this is enabled the editor will insert a calculated number of spaces +according to the position in the text and the <option>tab-width</option> setting +when you press the <keycap>TAB</keycap> key.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Show tabulators</guilabel></term> +<listitem> +<para>When this is enabled &kate; will display a small dot as a visual +representation of tabulator characters.</para> +<note><para>This also causes dots to be drawn to indicate trailing white space. +This will be fixed in a future version of &kate;</para></note> +</listitem> +</varlistentry> +<varlistentry> +<term id="config-dialog-editor-tab-width">Tab Width</term> <listitem><para>If the +<link linkend="config-dialog-editor-word-wrap"><guilabel>Replace Tabs By +Spaces</guilabel></link> +option is selected this entry determines the number of +spaces with which the editor will automatically replace +tabs.</para></listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term id="config-dialog-editor-word-wrap"><guilabel>Static Word Wrap</guilabel></term> +<listitem><para> +Word wrap is a feature that causes the editor to automatically start a new line +of text and move (wrap) the cursor to the beginning of that new line. &kate; +will automatically start a new line of text when the current line reaches the +length specified by the <link linkend="config-dialog-editor-wrap-words-at">Wrap Words +At:</link> option.</para> +<variablelist> +<varlistentry id="config-dialog-editor-enable-static-word-wrap"> +<term><guilabel>Enable static word wrap</guilabel></term> +<listitem> +<para>Turns static word wrap on or off.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Show static word wrap markers +(if applicable)</guilabel></term> +<listitem> +<para>If this option is checked, a vertical line will be drawn at the word wrap +column as defined in the <menuchoice> <guimenu>Settings</guimenu> +<guimenuitem>Configure Editor...</guimenuitem></menuchoice> in the Editing tab. +Please note that the word wrap marker is only drawn if you use a fixed pitch +font.</para> +</listitem> +</varlistentry> +<varlistentry id="config-dialog-editor-wrap-words-at"> +<term><guilabel>Wrap words at</guilabel></term> +<listitem> +<para>If the <link linkend="config-dialog-editor-word-wrap">Word Wrap</link> option is selected +this entry determines the length (in characters) at which the editor will +automatically start a new line.</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Remove Trailing Spaces</guilabel></term> +<listitem><para>&kate; will automatically eliminate extra spaces +at the ends of lines of text.</para></listitem> </varlistentry> + +<varlistentry> +<term><guilabel>Auto Brackets</guilabel></term> <listitem><para>When +the user types a left bracket ([, (, or {) &kate; automatically enters the +right bracket (}, ), or ]) to the right of the cursor.</para></listitem> +</varlistentry> + +<varlistentry> <term>Maximum <link linkend="undo">undo</link> steps:</term> +<listitem><para>Here the user may specify the number of steps &kate; will +retain in memory for purposes of undoing entries and actions. This means that +the higher the number of steps set the more memory &kate; will use for this. +Setting this entry to 10 would mean that the user would be be able reverse the +last ten operations, <abbrev>i.e.</abbrev> click the <guibutton>undo</guibutton> +button 10 times and obtain results.</para></listitem> </varlistentry> + +<varlistentry> <term>Smart search text from:</term> +<listitem><para>This determines where &kate; will get the search +text from (this will be automatically entered into the Find Text +dialog): +<itemizedlist> +<listitem><para><emphasis role="bold">Nowhere:</emphasis> Don't guess the search +text.</para></listitem> +<listitem><para><emphasis role="bold">Selection Only:</emphasis> Use + the current text selection, if available.</para></listitem> +<listitem><para><emphasis role="bold">Selection, then Current Word:</emphasis> +Use the current selection if available, otherwise use the current word. +</para></listitem> +<listitem><para><emphasis role="bold">Current Word +Only:</emphasis> Use the word that the cursor is currently resting on, if +available.</para></listitem> +<listitem><para><emphasis role="bold">Current Word, then Selection:</emphasis> +Use the current word if available, otherwise use the current selection. +</para></listitem> +</itemizedlist> +Note that, in all the above modes, if a +search string has not been or cannot be determined, then the Find Text Dialog +will fall back to the last search text. +</para></listitem> +</varlistentry> +</variablelist> +</sect2> + +<sect2 id="config-dialog-editor-indent"> +<title>Indentation</title> +<variablelist> +<varlistentry> +<term><guilabel>Automatic indentation</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Indentation mode:</guilabel></term> +<listitem> +<para>Select the automatic indentation mode you want to use as default. It is +strongly recommended to use <userinput>None</userinput> or +<userinput>Normal</userinput>here, and use filetype configurations to set other +indentation modes for text formats like C/C++ code or &XML;.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Insert leading Doxygen "*" when typing</guilabel></term> +<listitem> +<para>Automatically insert a leading "*" while typing within a doxygen +style comment. This setting is only enabled when applicable.</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Indentation with Spaces</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Use spaces instead of tabs to indent</guilabel></term> +<listitem> +<para>This replaces tabs with the number of spaces set in <guilabel>Number of +spaces:</guilabel> below.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Emacs style mixed mode</guilabel></term> +<listitem> +<para>Use a mix of tabs and space characters for indentation.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Number of spaces:</guilabel></term> +<listitem> +<para>Set the number of spaces you want to use for indentation when you +check <guilabel>Use spaces instead of tabs to indent</guilabel> +above.</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Keep Indent Profile</guilabel></term> +<listitem><para>When this is enabled, the editor will not unindent lines in a +selection further when the line with the least indentation becomes unindented. +If you sometimes unindent blocks of indented code, this may be helpful. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Keep Extra Spaces</guilabel></term> +<listitem><para>Indentations of more than the selected number of spaces +will not be shortened.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Keys to use</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Tab key indents</guilabel></term> +<listitem> +<para>This allows the <keycombo +action="simul"><keycap>tab</keycap></keycombo> key to be used to indent.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Backspace key indent</guilabel></term> +<listitem> +<para>This allows the <keycombo +action="simul"><keycap>backspace</keycap></keycombo> key to be used to +indent.</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Tab Key Mode if Nothing Selected</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Insert indent characters</guilabel></term> +<listitem> +<para>This allows the <keycombo +action="simul"><keycap>Tab</keycap></keycombo> key insert indent +characters.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Insert tab character</guilabel></term> +<listitem> +<para>This allows the <keycombo +action="simul"><keycap>Tab</keycap></keycombo> key insert a tab.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Indent current line</guilabel></term> +<listitem> +<para>This allows the <keycombo +action="simul"><keycap>Tab</keycap></keycombo> key indent the current +line.</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +</variablelist> +</sect2> + +<sect2 id="config-dialog-editor-open-save"> +<title>Open & Save</title> + +<variablelist> + +<varlistentry> +<term><guilabel>File Format</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Encoding:</guilabel></term> +<listitem> +<para>This sets the default character encoding for your files.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>End of line:</guilabel></term> +<listitem> +<para>Choose your prefered end of line mode for your active +document. You have the choice between &UNIX;, DOS/&Windows; or Macintosh.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Automatic end of line detection</guilabel></term> +<listitem> +<para>Check this if you want the editor to autodetect the end of line +type. The first found end of line type will be used for the whole file.</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Memory Usage</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Maximum loaded blocks per file:</guilabel></term> +<listitem> +<para>The editor will load given number of blocks (of around 2048 lines) of +text into memory; if the filesize is bigger than this the other blocks +are swapped to disk and loaded transparently as-needed.</para> +<para>This can cause little delays while navigating in the document; a +larger block count increases the editing speed at the cost of memory. +</para><para>For normal usage, just choose the highest possible block count: +limit it only if you have problems with the memory usage.</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Automatic Cleanups on Load/Save</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Remove trailing spaces</guilabel></term> +<listitem> +<para>The editor will automatically eliminate extra spaces at the ends of lines +of text while loading/saving the file.</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Folder Config File</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Search depth for config file:</guilabel></term> +<listitem> +<para>The editor will search the given number of folder levels upwards +for &kate; config file and load the settings line from it.</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Backup on Save</guilabel></term> +<listitem><para>Backing up on save will cause &kate; to copy the disk file to +<prefix><filename><suffix>' before saving changes. +The suffix defaults to <emphasis role="bold">~</emphasis> and prefix is empty by +default.</para> +<variablelist> +<varlistentry> +<term><guilabel>Local files</guilabel></term> +<listitem> +<para>Check this if you want backups of local files when +saving.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Remote files</guilabel></term> +<listitem> +<para>Check this if you want backups of remote files when saving.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Prefix</guilabel></term> +<listitem> +<para>Enter the prefix to prepend to the backup file names.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Suffix</guilabel></term> +<listitem> +<para>Enter the suffix to add to the backup file names.</para> +</listitem> +</varlistentry> + +</variablelist> +</listitem> +</varlistentry> + +</variablelist> +</sect2> + +<sect2 id="config-dialog-editor-highlighting"> +<title>Highlighting</title> +<para>This group of options is used to customize the highlighting styles for +each programming language type. Any changes you made in other areas of this +dialog apply only to this type.</para> + +<variablelist> +<varlistentry> +<term><guilabel>Highlight:</guilabel></term> +<listitem><para>This is used to choose the language type to +configure.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Informations</guilabel></term> +<listitem> +<para> +View the properties of the chosen language highlighting rules: +author name and license. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Properties</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>File extensions:</guilabel></term> +<listitem><para>This is the list of file extensions used to determine which +files to highlight using the current syntax highlight mode.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>MIME types:</guilabel></term> +<listitem><para>Clicking the wizard button will display a dialog with a list of +all available mime types to choose from.</para><para>The <emphasis +role="bold">File Extensions</emphasis> entry will automatically be edited as +well.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Priority:</guilabel></term> +<listitem><para>Set the priority of the highlight rule.</para></listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>Download...</guibutton></term> +<listitem> +<para> +Click this button to download new or updated syntax highlight descriptions +from the &kate; website. +</para> +</listitem> +</varlistentry> + +</variablelist> +</sect2> + +<sect2 id="config-dialog-editor-filetypes"> +<title>Filetypes</title> +<para>This page allows you to override the default configuration for documents +of specified mimetypes. When the editor loads a document, it will try if it +matches the file masks or mimetypes for one of the defined filetypes, and if so +apply the variables defined. If more filetypes match, the one with the highest +priority will be used. +</para> +<variablelist> +<varlistentry> +<term><guilabel>Filetype:</guilabel></term> +<listitem><para>The filetype with the highest priority is the one displayed in +the first drop down box. If more filetypes were found, they are +also listed.</para> +<variablelist> +<varlistentry> +<term><guilabel>New</guilabel></term> +<listitem><para>This is used to create a new filetype. After +you click on this button, the fields below get empty and you +can fill the properties you want for the new filetype.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Delete</guilabel></term> +<listitem><para>To remove an existing filetype, select it from the drop down +box and press the Delete button.</para></listitem> +</varlistentry> +</variablelist> +</listitem> </varlistentry> + +<varlistentry> +<term><guilabel>Properties of current filetype</guilabel></term> +<listitem><para>The filetype with the highest priority is the one displayed in +the first drop down box. If more filetypes were found, they are also +listed.</para> +<variablelist> +<varlistentry> +<term><guilabel>Name:</guilabel></term> +<listitem><para>The name of the filetype will be the text of the corresponding +menu item. This name is displayed in the +<menuchoice><guimenu>Tools</guimenu><guimenuitem>Filetypes</guimenuitem> +</menuchoice ></para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Section:</guilabel></term> +<listitem><para>The section name is used to organize the file types in +menus. This is also used in the +<menuchoice><guimenu>Tools</guimenu><guimenuitem>Filetypes</guimenuitem> +</menuchoice> menu.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Variables:</guilabel></term> +<listitem><para>This string allows you to configure &kate;'s settings for the +files selected by this mimetype using &kate; variables. You can set almost any +configuration option, such as highlight, indent-mode, encoding, +etc.</para><para>For a full list of known variables, see the +manual.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>File extensions:</guilabel></term> +<listitem><para>The wildcards mask allows you to select files by filename. A +typical mask uses an asterisk and the file extension, for example +<filename>*.txt; *.text</filename>. The string is a semicolon-separated list of +masks.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>MIME types:</guilabel></term> +<listitem><para>Displays a wizard that helps you easily select +mimetypes.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Priority:</guilabel></term> +<listitem><para>Sets a priority for this file type. If more than one file type +selects the same file, the one with the highest priority will be +used.</para></listitem> +</varlistentry> +</variablelist> +</listitem> </varlistentry> + +</variablelist> +</sect2> + +<sect2 id="config-dialog-editor-shortcuts"> +<title>Shortcuts</title> +<para>You can change here the shortcut keys configuration. Select an +action and click on <guilabel>Custom</guilabel> if you want a different shortcut +for this action.</para> +<para>The search line alllows you to look for a specific action and see +its associated shortcut.</para> +</sect2> + +<sect2 id="config-dialog-editor-plugins"> +<title>Plugins</title> +<para>This tab lists all available plugins and you can check those you +want to use. Once a plugin is checked, the +<guibutton>Configure</guibutton> button is enabled and you can click it +in order to configure the highlighted plugin.</para> +</sect2> + +</sect1> + + + +<sect1 id="config-variables"> + +<title>Configuring With Document Variables</title> + +<para>Kate variables is kateparts implementation of document variables, similar +to emacs and vi modelines. In katepart, the lines have the format + +<userinput>kate: VARIABLENAME VALUE; [ VARIABLENAME VALUE; ... ]</userinput> + +the lines can of course be in a comment, if the file is in a format with comments. +Variable names are single words (no whitespace), and anything up to the next +semicolon is the value. The semicolon is required.</para> + +<para>Here is an example variable line, forcing indentation settings for a C++, +java or javascript file: + +<programlisting>// kate: space-indent on; indent-width 4; mixedindent off; indent-mode cstyle;</programlisting> +</para> + +<note><para>Only the first and last 10 lines are searched for variable lines.</para></note> + +<para>There are variables to support almost all configurations in katepart, and +aditionally plugins can use variables, in which case it should be documented in +the plugin's documentation.</para> + +<sect2 id="config-variables-howto"> +<title>How kate uses variables</title> + +<para>When reading configuration, katepart looks in the following places +(in that order): + +<itemizedlist> +<listitem><para>The global configuration.</para></listitem> +<listitem><para>Optional session data.</para></listitem> +<listitem><para>The "Filetype" configuration.</para></listitem> +<listitem><para>Document variables in the document itself.</para></listitem> +<listitem><para>Settings made during editing from menu or command line.</para></listitem> +</itemizedlist> + +As you can understand document variables has the next highest precedence. +Whenever a document is saved, the document variables are reread, and will +overwrite changes made using menu items or the command line.</para> + +<para>Any variable not listed below is stored in the document and can be queried +by other objects such as plugins, which can use them for their own purpose. +For example the variable indent mode uses document variables for its +configuration.</para> + +<para>The variables listed here documents &kate; version 2.4. More variables +may be added in the future. There are 3 possible types of values for variables, +with the following valid expressions: +<itemizedlist> +<listitem><para>BOOL - on|off|true|false|1|0</para></listitem> +<listitem><para>INTEGER - any integer number</para></listitem> +<listitem><para>STRING - anything else</para></listitem> +</itemizedlist> +</para> + +<variablelist> +<title>Available Variables</title> + +<varlistentry> +<term><cmdsynopsis><command>auto-brackets</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Set auto insertion of brackets on or off.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>auto-center-lines</command><arg>INT</arg></cmdsynopsis></term> +<listitem><para>Set the number of autocenter lines.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>auto-insert-doxygen</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Turn insertion of the leading asterisk in doxygen comments on or +off. This has no effect unless you use the cstyle auto-indenter.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>background-color</command><arg>STRING</arg></cmdsynopsis></term> +<listitem><para>Set the document background color. The value must be something +that can be evaluated to a valid color, for example "#ff0000".</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>backspace-indents</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Turn backspace indenting on or off.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>block-selection</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Turn block selection on or off.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>bracket-highlight-color</command><arg>STRING</arg></cmdsynopsis></term> +<listitem><para>Set the color for the bracket highlight. The value must be +something that can be evaluated to a valid color, for example "#ff0000" </para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>current-line-color</command><arg>STRING</arg></cmdsynopsis></term> +<listitem><para>Set the color for the current line. The value must be +something that can be evaluated to a valid color, for example "#ff0000".</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>dynamic-word-wrap</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Turns dynamic word wrap on or off.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>eol | end-of-line</command><arg>STRING</arg></cmdsynopsis></term> +<listitem><para>Set the end of line mode. Valid settings are +<quote>unix</quote>, <quote>mac</quote> and <quote>dos</quote></para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>encoding</command><arg>STRING</arg></cmdsynopsis></term> +<listitem><para>Set the document encoding. The value must be a valid encoding +name, like <quote>utf-8</quote>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>font-size</command><arg>INT</arg></cmdsynopsis></term> +<listitem><para>Set the point size of the document font.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>font</command><arg>STRING</arg></cmdsynopsis></term> +<listitem><para>Set the font of the document. The value should be a valid font +name, for example <quote>courier</quote>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>icon-bar-color</command><arg>STRING</arg></cmdsynopsis></term> +<listitem><para>Set the icon bar color. The value must be something that can +be evaluated to a valid color, for example <literal>#ff0000</literal>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>icon-border</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Set the display of the icon border on or off.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>folding-markers</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Set the display of folding markers on or off.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>indent-mode</command><arg>STRING</arg></cmdsynopsis></term> +<listitem><para>Set the auto-indentation mode. The options <quote>none</quote>, +<quote>normal</quote>, <quote>cstyle</quote>, <quote>csands</quote>, +<quote>python</quote>, <quote>xml</quote> are recognized. See the section +<xref linkend="kate-part-autoindent"/> for details.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>indent-width</command><arg>INT</arg></cmdsynopsis></term> +<listitem><para>Set the indentation width.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>keep-extra-spaces</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Set wheather to keep extra spaces when calculating indentation width.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>keep-indent-profile</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>If enabled, prevents unindenting a block if at least one line +has no indentation.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>line-numbers</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Set the display of line numbers on or off.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>mixed-indent</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Set mixed indentation ala Emacs on or off.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>overwrite-mode</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Set overwrite mode on or off.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>persistent-selection</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Set persistent selection on or off.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>remove-trailing-space</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Set dynamic end of line cleanup on or off.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>replace-tabs-save</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Set tab->space conversion on save on or off.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>replace-tabs</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Set dynamic tab->space conversion on or off.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>replace-trailing-space-save</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Set end of line cleanup on save on or off.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>scheme</command><arg>STRING</arg></cmdsynopsis></term> +<listitem><para>Set the color scheme. The string must be the name of a color +scheme that exists in your configuration to have any effect.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>selection-color</command><arg>STRING</arg></cmdsynopsis></term> +<listitem><para>Set the selection color. The value must be something that can +be evaluated to a valid color, for example "#ff0000".</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>show-tabs</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Set the visual TAB character on or off.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>smart-home</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Set smart home navigation on or off.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>space-indent</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Set indentation with spaces on or off.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>tab-indents</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Set the TAB key indentation on or off.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>tab-width</command><arg>INT</arg></cmdsynopsis></term> +<listitem><para>Set the tab display width.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>undo-steps</command><arg>INT</arg></cmdsynopsis></term> +<listitem><para>Set the number of undo steps to remember.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>word-wrap-column</command><arg>INT</arg></cmdsynopsis></term> +<listitem><para>Set the hard word wrap width.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>word-wrap-marker-color</command><arg>STRING</arg></cmdsynopsis></term> +<listitem><para>Set the word wrap marker color. The value must be something +that can be evaluated to a valid color, for example "#ff0000".</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>word-wrap</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Set hard word wrapping on or off.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>wrap-cursor</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Set cursor wrapping on or off.</para></listitem> +</varlistentry> + +</variablelist> + +</sect2> + +</sect1> + +</chapter> diff --git a/doc/kate/fundamentals.docbook b/doc/kate/fundamentals.docbook new file mode 100644 index 000000000..c42614a71 --- /dev/null +++ b/doc/kate/fundamentals.docbook @@ -0,0 +1,611 @@ +<chapter id="fundamentals"> +<chapterinfo> +<authorgroup> +<author><personname><firstname></firstname></personname></author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</chapterinfo> +<title>The Fundamentals</title> + +<para> +If you have ever used a text editor, you will have no problem using +&kate;. In the next two sections, <link linkend="starting-kate">Starting +&kate; </link> and <link linkend="working-with-kate">Working with +&kate;</link>, you will find everything you need to get up and running +quickly. +</para> + +<sect1 id="starting-kate"> +<title>Starting &kate;</title> + +<para> +You can start &kate; from the <guimenu>TDE menu</guimenu> or from the +command line. +</para> + +<sect2 id="starting-from-the-menu"> +<title>From the Menu</title> +<para> +Open the &tde; program menu by clicking on the +<guiicon>big T</guiicon> icon on the toolbar at the bottom left of your +screen. This will raise the <guimenu>program menu</guimenu>. Move your +cursor up the menu to the <menuchoice><guimenu>Utilities</guimenu> +<guimenuitem>Editors</guimenuitem></menuchoice> menu item. A list +of available editors will appear. Choose +<guimenuitem>&kate;</guimenuitem>. +</para> + +<para> +Unless you configure &kate; not to, it will load the last files you +edited. See <link linkend="configure">Configuring &kate;</link> to learn +how to toggle this feature on and off. +</para> + +</sect2> + +<sect2 id="starting-from-the-command-line"> +<title>From the Command Line</title> + +<para> +You can start &kate; by typing its name on the command line. If you give +it a file name, as in the example below, it will open or create that +file. +</para> + +<informalexample> +<screen> +<prompt>%</prompt><userinput><command>kate</command> <option><replaceable>myfile.txt</replaceable></option></userinput> +</screen> +</informalexample> + +<para> +If you have an active connection and permission, you can take advantage +of &tde;'s network transparency to open files on the internet. +</para> + +<informalexample> +<screen> +<prompt>%</prompt><userinput><command>kate</command> <option><replaceable>http://git.trinitydesktop.org/cgit/tdebase/plain/doc/kate/index.docbook</replaceable></option></userinput> +</screen> +</informalexample> + +<sect3 id="command-line-options"> +<title>Command Line Options</title> +<para>&kate; accepts the following command line options:</para> + +<variablelist> +<varlistentry> +<term><userinput><command>kate</command> <option>--help</option></userinput></term> +<listitem> +<para> +This lists the most basic options available at the command line. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><userinput><command>kate</command> +<option>--help-qt</option></userinput></term> +<listitem> +<para> +This lists the options available for changing the way &kate; interacts with &Qt;. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><userinput><command>kate</command> <option>--help-tde</option></userinput></term> +<listitem> +<para> +This lists the options available for changing the way &kate; interacts with &tde;. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><userinput><command>kate</command> <option>--help-tde-tempfile</option></userinput></term> +<listitem> +<para> +This lists the available &tde;-tempfile specific options. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><userinput><command>kate</command> +<option>--help-all</option></userinput></term> +<listitem> +<para> +This lists all of the command line options. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><userinput><command>kate</command> +<option>--author</option></userinput></term> +<listitem> +<para> +Lists &kate;'s authors in the terminal window. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><userinput><command>kate</command> +<option>-v</option> <option>--version</option></userinput></term> +<listitem> +<para> +Lists version information for &Qt;, &tde;, and &kate;. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><userinput><command>kate</command> +<option>--license</option></userinput></term> +<listitem> +<para> +Shows license information. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><userinput><command>kate</command> +<option>-s</option> <option>--start</option> <parameter>name</parameter></userinput></term> +<listitem> +<para> +Starts kate with the session <parameter>name</parameter>. The session is created +if it does not exist already. If a &kate; instance running the specified session +exists, the specified files are loaded in that instance. When used with the +<option>--use</option> option, an instance running this session will be used as +well. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><userinput><command>kate</command> +<option>-u</option> <option>--use</option> <parameter>URL</parameter></userinput></term> +<listitem> +<para> +Causes &kate; to use and existing instance if there is one. If you want all +documents to open in one kate instance, you can add this option to the default +command in your &tde; application configuration, as well as create a shell alias +in your command intepreter if it supports that. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><userinput><command>kate</command> +<option>-f</option> <option>--force-sdi</option> </userinput></term> +<listitem> +<para> +If the multiple document interface (MDI) setting is enabled, forces &kate; to +use the single document interface (SDI) mode. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><userinput><command>kate</command> +<option>-p</option> <option>--pid</option> <parameter>PID</parameter></userinput></term> +<listitem> +<para> +Only reuses an instance with the specified PID (Process ID). Used with the +<option>--use</option> option. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><userinput><command>kate</command> +<option>-e</option> <option>--encoding</option> <parameter>encoding</parameter> +<parameter>URL</parameter></userinput></term> +<listitem><para>Uses the specified encoding for the document. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput><command>kate</command> +<option>-l</option> <option>--line</option> <parameter>line</parameter> +<parameter>URL</parameter></userinput></term> +<listitem><para>Navigates to the specified line after opening the document. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput><command>kate</command> +<option>-c</option> <option>--column</option> <parameter>column</parameter> +<parameter>URL</parameter></userinput></term> +<listitem><para>Navigates to the specified column after opening the document. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput><command>kate</command> +<option>-i</option> <option>--stdin</option></userinput></term> +<listitem><para>Reads the document content from STDIN. This +is similar to the common option <option>-</option> used in many command line +programs, and allows you to pipe command output into &kate;.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput><command>kate</command> +<option>--tempfile</option></userinput></term> +<listitem><para>Since &kate; 2.5.1 this standard &tde; option is supported. +When used, the specified files are treated as temporary files and +deleted (if they are local files and you have sufficient permissions) when +closed, unless they are modified since they were opened.</para></listitem> +</varlistentry> +</variablelist> + +</sect3> +</sect2> + +<sect2 id="drag-and-drop"> +<title>Drag and Drop</title> +<para> +&kate; uses the &tde; Drag and Drop protocol. Files may be dragged and +dropped onto &kate; from the Desktop, &konqueror; or some remote ftp +site opened in one of &konqueror;'s windows. +</para> +</sect2> +</sect1> + +<sect1 id="working-with-kate"> +<title>Working with &kate;</title> +<para> +<link linkend="quick-start">Quick Start</link> will show you how to +toggle four simple options that will let you configure some of &kate;'s +more powerful features right away. <link linkend="keystroke-commands"> +Shortcuts</link> lays out some of the default keystroke +shortcuts for those who can't or don't want to use a mouse. +</para> + +<sect2 id="quick-start"> +<title>Quick Start</title> + +<para> +This section will describe some of the items on the +<guimenu>Settings</guimenu> menu so that you can quickly configure +&kate; to work the way you want it. +</para> + +<para> When you start &kate; for the first time you'll see two windows +with white backgrounds. Above the two windows is a toolbar with the +usual labeled icons. And above that, a menubar. +</para> + +<para> +The left-hand window is a side bar. It combines the Documents +and Filesystem Browser windows. Switch between the two by clicking on the tabs +to the left of the window.</para> + +<para> +If you've started &kate; with a file, the right-hand window will show +the file you are editing and the Documents on the side bar will show the +name of the file. Use the Filesystem Browser window to open files. +</para> + +<para> +You can toggle the Documents and Filesystem Browser window on and off in +<menuchoice><guimenu>Window</guimenu><guimenu>Tool Views</guimenu></menuchoice> +menu. This menu offers you your first glimpse into &kate;'s power and +flexibility. In this section we'll look at three items: +</para> + +<variablelist> + +<varlistentry> +<term> +<menuchoice> +<guimenuitem>Show/Hide Documents</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +Toggles the Documents on and off. If the Documents/Filesystem Browser side bar +window is not open, &kate; will open the side bar window.</para> + +</listitem> +</varlistentry> +<varlistentry> +<term><menuchoice><guimenuitem>Show/Hide +Filesystem Browser</guimenuitem></menuchoice></term> +<listitem> +<para> +Toggles the Filesystem Browser on and off. This menu item is the same as +<guimenuitem>Show Documents</guimenuitem> with one difference. Toggling +it on launches the window with the Filesystem Browser on top. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenuitem>Show/Hide +Terminal</guimenuitem></menuchoice></term> +<listitem> +<para> +Toggles a terminal emulator on and off at the bottom of &kate;'s +window. In other words, it gives you a command line within the +application. +</para> +</listitem> +</varlistentry> +</variablelist> +</sect2> + +<sect2 id="keystroke-commands"> +<title>Shortcuts</title> + +<para> +Many of &kate;'s keystroke commands (shortcuts) are configurable by +way of the <link linkend="settings">Settings</link> menu. By default +&kate; honors the following key bindings. +</para> + +<informaltable> +<tgroup cols="2"> +<tbody> + +<row><entry><para><keycap>Insert</keycap></para></entry> +<entry><para> +Toggle between Insert and Overwrite mode. When in insert mode the editor +will add any typed characters to the text and push any previously typed +data to the right of the text cursor. Overwrite mode causes the entry of +each character to eliminate the current character.</para></entry> +</row> +<row> +<entry><para><keycombo><keycap>Left Arrow</keycap></keycombo></para></entry> +<entry><para>Move the cursor one character to the left </para></entry> +</row> +<row> +<entry><para><keycombo><keycap>Right Arrow</keycap></keycombo></para></entry> +<entry><para> Move the cursor one character to the right </para></entry> +</row> +<row> +<entry><para><keycombo action="simul"><keycap>Up Arrow</keycap></keycombo></para></entry> +<entry><para> Move the cursor up one line </para></entry> +</row> +<row> +<entry><para><keycombo action="simul"><keycap>Down Arrow</keycap></keycombo></para></entry> +<entry><para> Move the cursor down one line </para></entry> +</row> +<row> +<entry><para><keycombo action="simul"><keycap>Page Up</keycap></keycombo></para></entry> +<entry><para> Move the cursor up one page </para></entry> +</row> +<row> +<entry><para><keycombo action="simul"><keycap>Page Down</keycap></keycombo></para></entry> +<entry><para>Move the cursor down one page </para></entry> +</row> +<row> +<entry><para><keycombo action="simul"><keycap>Backspace</keycap></keycombo></para></entry> +<entry><para> Delete the character to the left of the cursor </para></entry> +</row> +<row> +<entry><para><keycombo action="simul"><keycap>Home</keycap></keycombo></para></entry> +<entry><para> Move the cursor to the beginning of the line </para></entry> +</row> +<row> +<entry><para><keycombo action="simul"><keycap>End</keycap></keycombo></para></entry> +<entry><para> Move the cursor to the end of the line </para></entry> +</row> +<row> +<entry><para><keycombo action="simul"><keycap>Delete</keycap></keycombo></para></entry> +<entry><para>Delete the character to the right of the cursor (or any selected +text)</para></entry> +</row> +<row> +<entry><para><keycombo action="simul">&Shift;<keycap>Left Arrow</keycap></keycombo></para></entry> +<entry><para> Mark text one character to the left </para></entry> +</row> +<row> +<entry><para><keycombo action="simul">&Shift;<keycap>Right Arrow</keycap></keycombo></para></entry> +<entry><para> Mark text one character to the right </para></entry> +</row> +<row> +<entry><para><keycombo action="simul"><keycap>F1</keycap></keycombo></para></entry> +<entry><para> Help</para></entry> +</row> +<row> +<entry><para><keycombo action="simul">&Shift;<keycap>F1</keycap></keycombo></para></entry> +<entry><para><link linkend="whats-this">What's this?</link></para></entry> +</row> +<row> +<entry><para><keycombo action="simul">&Ctrl;<keycap>F</keycap></keycombo></para></entry> +<entry><para><link linkend="kate-part-find-replace">Find</link></para></entry> +</row> +<row> +<entry><para><keycombo action="simul"><keycap>F3</keycap></keycombo></para></entry> +<entry><para>Find again</para></entry> +</row> +<row> +<entry><para><keycombo action="simul">&Ctrl;<keycap>B</keycap></keycombo></para></entry> +<entry><para>Set a Bookmark</para></entry> +</row> +<row> +<entry><para><keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo></para></entry> +<entry><para> Copy the marked text to the clipboard.</para></entry> +</row> + +<row> +<entry><para><keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo></para></entry> +<entry><para> <link linkend="new">New</link> document</para></entry> +</row> +<row> +<entry><para><keycombo action="simul">&Ctrl;<keycap>P</keycap></keycombo></para></entry> +<entry><para><link linkend="print">Print</link> </para></entry> +</row> +<row> + +<entry><para><keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo></para></entry> +<entry><para>Quit - close active copy of editor </para></entry> +</row> +<row> +<entry><para><keycombo action="simul">&Ctrl;<keycap>R</keycap></keycombo></para></entry> +<entry><para><link linkend="kate-part-find-replace">Replace</link></para></entry> +</row> +<row> +<entry><para><keycombo action="simul">&Ctrl;<keycap>S</keycap></keycombo></para></entry> +<entry><para>Save your file.</para></entry> +</row> +<row> +<entry><para><keycombo action="simul">&Ctrl;<keycap>V</keycap></keycombo></para></entry> +<entry><para> Paste.</para></entry> +</row> + +<row> +<entry><para><keycombo action="simul">&Ctrl;<keycap>X</keycap></keycombo></para></entry> +<entry><para>Delete the marked text and copy it to the clipboard.</para></entry> +</row> +<row> +<entry><para><keycombo action="simul">&Ctrl;<keycap>Z</keycap></keycombo></para></entry> +<entry><para><link linkend="edit-undo">Undo</link></para></entry> +</row> +<row> +<entry><para><keycombo action="simul">&Ctrl;&Shift;<keycap>Z</keycap></keycombo></para></entry> +<entry><para><link linkend="edit-redo">Redo</link></para></entry> +</row> +</tbody> +</tgroup> +</informaltable> +</sect2> + +</sect1> + +<sect1 id="fundamentals-using-sessions"> +<title>Using Sessions</title> + +<para>Sessions is how &kate; lets you keep more than one list of files and +GUI configuration around. You can have as many named sessions as you want, +and you can use unnamed or anonymous sessions for files you want to use only +once. Currently &kate; can save the list of open files, and the general window +configuration in the session, future versions of &kate; may add more features +that can be saved in sessions. With the introduction of sessions, &kate; also +allows you to open any number of instances of the application instead of just +one as it used to do as the default behavior.</para> + +<para>Sessions are supported in three areas: + +<itemizedlist> +<listitem><para><link linkend="command-line-options"><emphasis>Command line +options</emphasis></link> that lets you select and start sessions when launching +kate from the command line.</para> +</listitem> +<listitem><para><link linkend="sessions-menu"><emphasis>The Sessions +menu</emphasis></link> that lets you switch, save, start and manage your +sessions</para></listitem> +<listitem><para><link linkend="config-dialog-sessions"><emphasis>Configuration +options</emphasis></link> that lets you decide how sessions generally should +behave.</para></listitem> +</itemizedlist> + +</para> + +<para>When starting a new session, the GUI configuration of <guilabel>Default +Session</guilabel> is loaded. To save window configuration in the default +session, you need to enable saving window configuration in the sessions +configuration page of the configuration dialog and then load the default +session, set up the window as desired and save the session again.</para> + +<para>When a named session is loaded, &kate; will display the session name at +the start of the window title, which then have the form +"<replaceable>Session Name</replaceable>: <replaceable>Document name or +&URL;</replaceable> - &kate;"</para> + +<para>When opening files on the command line with <option>--start +<replaceable>name</replaceable></option> or if a session is selected using the +session chooser, the specified session is loaded prior to the files specified +on the command line. To open files from the command line in a new, unnamed +session, configure kate to start a new session per default in the session page of +the configuration dialog or use <option>--start</option> with an empty string: +<replaceable>''</replaceable>.</para> + +<para>Since &kate; 2.5.1 the <acronym>PID</acronym> of the current instance is +exported to the environment variable <envar>KATE_PID</envar>. When opening files +from the built in terminal, Kate will automatically select the current instance +if nothing else is indicated on the command line.</para> + +<sect2 id="old-behavior"> +<title>Restoring old style &kate; behavior</title> + +<para>When you get used to using sessions you will hopefully see that they +provide a very simple and efficient tool for working in different areas. +However, if you prefer the old &kate; behavior (one instance opens all files), +you can easily achieve that by following this simple strategy: + +<itemizedlist> +<listitem><para>Make &kate; always start with the <option>--use</option> +parameter by adding that to the command in the application preferences, +and additionally using a shell alias.</para></listitem> +<listitem><para>Configure &kate; to load the last used session at startup.</para> +</listitem> +<listitem><para>Configure &kate; to save the file list when closing a session. +</para></listitem> +<listitem><para>Load the default session once</para></listitem> +</itemizedlist> +</para> + +</sect2> + +</sect1> + +<sect1 id="fundamentals-getting-help"> + +<title>Getting Help</title> + +<variablelist> + +<varlistentry> +<term>This manual</term> + +<listitem> +<para>Offers detailed documentation on all menu commands, +configuration options, tools, dialogs, plugins &etc; as well as a +description of the &kate; window, the editor and various concepts +used in the application.</para> + +<para>Press <keycap>F1</keycap> or use the +<menuchoice><guimenu>Help</guimenu> +<guimenuitem>Kate handbook</guimenuitem></menuchoice> menu topic to view this +manual.</para></listitem> + +</varlistentry> + +<varlistentry id="whats-this"> +<term>What's This Help</term> +<listitem> +<para>What's This Help offers immediate help with single elements of +graphical windows, such as buttons or other window areas.</para> + +<para>We strive to provide What's This Help for any element for which +it makes sense. It is available throughout the configuration dialog, +and in many other dialogs as well.</para> + +<para>To employ What's This Help, press +<keycombo>&Shift;<keycap>F1</keycap></keycombo> or use the +<menuchoice><guimenu>Help</guimenu><guimenuitem>What's +This</guimenuitem></menuchoice> menu item to enable What's This +mode. The cursor will turn into an arrow with a question mark, and you +can now click any element in the window to read the What's This Help +for that element, if it is available.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Help Buttons in Dialogs</term> +<listitem> +<para>Some dialogs have a <guibutton>Help</guibutton> Button. Pressing +it will start the &khelpcenter; and open the relevant +documentation.</para> +</listitem> +</varlistentry> +</variablelist> + +</sect1> + +</chapter> diff --git a/doc/kate/highlighted.png b/doc/kate/highlighted.png Binary files differnew file mode 100644 index 000000000..ffb95ec48 --- /dev/null +++ b/doc/kate/highlighted.png diff --git a/doc/kate/highlighting.docbook b/doc/kate/highlighting.docbook new file mode 100644 index 000000000..3a64d9d2c --- /dev/null +++ b/doc/kate/highlighting.docbook @@ -0,0 +1,931 @@ +<appendix id="highlight"> +<appendixinfo> +<authorgroup> +<author><personname><firstname></firstname></personname></author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</appendixinfo> +<title>Working with Syntax Highlighting</title> + +<sect1 id="highlight-overview"> + +<title>Overview</title> + +<para>Syntax Highlighting is what makes the editor automatically +display text in different styles/colors, depending on the function of +the string in relation to the purpose of the file. In program source +code for example, control statements may be rendered bold, while data +types and comments get different colors from the rest of the +text. This greatly enhances the readability of the text, and thus +helps the author to be more efficient and productive.</para> + +<mediaobject> +<imageobject><imagedata format="PNG" fileref="highlighted.png"/></imageobject> +<textobject><phrase>A Perl function, rendered with syntax +highlighting.</phrase></textobject> +<caption><para>A Perl function, rendered with syntax highlighting.</para> +</caption> +</mediaobject> + +<mediaobject> +<imageobject><imagedata format="PNG" fileref="unhighlighted.png"/></imageobject> +<textobject><phrase>The same Perl function, without +highlighting.</phrase></textobject> +<caption><para>The same Perl function, without highlighting.</para></caption> +</mediaobject> + +<para>Of the two examples, which is easiest to read?</para> + +<para>&kate; comes with a flexible, configurable and capable system +for doing syntax highlighting, and the standard distribution provides +definitions for a wide range of programming, scripting and markup +languages and other text file formats. In addition you can +provide your own definitions in simple &XML; files.</para> + +<para>&kate; will automatically detect the right syntax rules when you +open a file, based on the &MIME; Type of the file, determined by its +extension, or, if it has none, the contents. Should you experience a +bad choice, you can manually set the syntax to use from the +<menuchoice><guimenu>Documents</guimenu><guisubmenu>Highlight +Mode</guisubmenu></menuchoice> menu.</para> + +<para>The styles and colors used by each syntax highlight definition +can be configured using the <link +linkend="config-dialog-editor-appearance">Appearance</link> page of the +<link linkend="config-dialog">Config Dialog</link>, while the &MIME; Types +it should be used for, are handeled by the <link +linkend="config-dialog-editor-highlighting">Highlight</link> +page.</para> + +<note> +<para>Syntax highlighting is there to enhance the readability of +correct text, but you cannot trust it to validate your text. Marking +text for syntax is difficult depending on the format you are using, +and in some cases the authors of the syntax rules will be proud if 98% +of text gets correctly rendered, though most often you need a rare +style to see the incorrect 2%.</para> +</note> + +<tip> +<para>You can download updated or additional syntax highlight +definitions from the &kate; website by clicking the +<guibutton>Download</guibutton> button in the <link +linkend="config-dialog-editor-highlighting">Highlight Page</link> of the <link +linkend="config-dialog">Config Dialog</link>.</para> +</tip> + +</sect1> + +<sect1 id="katehighlight-system"> + +<title>The &kate; Syntax Highlight System</title> + +<para>This section will discuss the &kate; syntax highlighting +mechanism in more detail. It is for you if you want to know about +it, or if you want to change or create syntax definitions.</para> + +<sect2 id="katehighlight-howitworks"> + +<title>How it Works</title> + +<para>Whenever you open a file, one of the first things the &kate; +editor does is detect which syntax definition to use for the +file. While reading the text of the file, and while you type away in +it, the syntax highlighting system will analyze the text using the +rules defined by the syntax definition and mark in it where different +contexts and styles begin and end.</para> + +<para>When you type in the document, the new text is analyzed and marked on the +fly, so that if you delete a character that is marked as the beginning or end +of a context, the style of surrounding text changes accordingly.</para> + +<para>The syntax definitions used by the &kate; Syntax Highlighting System are +&XML; files, containing +<itemizedlist> +<listitem><para>Rules for detecting the role of text, organized into context blocks</para></listitem> +<listitem><para>Keyword lists</para></listitem> +<listitem><para>Style Item definitions</para></listitem> +</itemizedlist> +</para> + +<para>When analyzing the text, the detection rules are evaluated in +the order in which they are defined, and if the beginning of the +current string matches a rule, the related context is used. The start +point in the text is moved to the final point at which that rule +matched and a new loop of the rules begins, starting in the context +set by the matched rule.</para> + +</sect2> + +<sect2 id="highlight-system-rules"> +<title>Rules</title> + +<para>The detection rules are the heart of the highlighting detection +system. A rule is a string, character or <link +linkend="regular-expressions">regular expression</link> against which +to match the text being analyzed. It contains information about which +style to use for the matching part of the text. It may switch the +working context of the system either to an explicitly mentioned +context or to the previous context used by the text.</para> + +<para>Rules are organized in context groups. A context group is used +for main text concepts within the format, for example quoted text +strings or comment blocks in program source code. This ensures that +the highlighting system does not need to loop through all rules when +it is not necessary, and that some character sequences in the text can +be treated differently depending on the current context. +</para> + +<para>Contexts may be generated dynamically to allow the usage of instance +specific data in rules.</para> + +</sect2> + +<sect2 id="highlight-context-styles-keywords"> +<title>Context Styles and Keywords</title> + +<para>In some programming languages, integer numbers are treated +differently than floating point ones by the compiler (the program that +converts the source code to a binary executable), and there may be +characters having a special meaning within a quoted string. In such +cases, it makes sense to render them differently from the surroundings +so that they are easy to identify while reading the text. So even if +they do not represent special contexts, they may be seen as such by +the syntax highlighting system, so that they can be marked for +different rendering.</para> + +<para>A syntax definition may contain as many styles as required to +cover the concepts of the format it is used for.</para> + +<para>In many formats, there are lists of words that represent a +specific concept. For example in programming languages, the control +statements is one concept, data type names another, and built in +functions of the language a third. The &kate; Syntax Highlighting +System can use such lists to detect and mark words in the text to +emphasize concepts of the text formats.</para> + +</sect2> + +<sect2 id="kate-highlight-system-default-styles"> +<title>Default Styles</title> + +<para>If you open a C++ source file, a &Java; source file and an +<acronym>HTML</acronym> document in &kate;, you will see that even +though the formats are different, and thus different words are chosen +for special treatment, the colors used are the same. This is because +&kate; has a predefined list of Default Styles which are employed by +the individual syntax definitions.</para> + +<para>This makes it easy to recognize similar concepts in different +text formats. For example comments are present in almost any +programming, scripting or markup language, and when they are rendered +using the same style in all languages, you do not have to stop and +think to identify them within the text.</para> + +<tip> +<para>All styles in a syntax definition use one of the default +styles. A few syntax definitions use more styles that there are +defaults, so if you use a format often, it may be worth launching the +configuration dialog to see if some concepts are using the same +style. For example there is only one default style for strings, but as +the Perl programming language operates with two types of strings, you +can enhance the highlighting by configuring those to be slightly +different. All <link linkend="kate-highlight-default-styles">available default styles</link> +will be explained later.</para> +</tip> + +</sect2> + +</sect1> + +<sect1 id="katehighlight-xml-format"> +<title>The Highlight Definition &XML; Format</title> + +<sect2> +<title>Overview</title> + +<para>This section is an overview of the Highlight Definition &XML; +format. Based on a small example it will describe the main components +and their meaning and usage. The next section will go into detail with +the highlight detection rules.</para> + +<para>The formal definition, aka the <acronym>DTD</acronym> is stored +in the file <filename>language.dtd</filename> which should be +installed on your system in the folder +<filename>$<envar>TDEDIR</envar>/share/apps/katepart/syntax</filename>. +</para> + +<variablelist> +<title>Main sections of &kate; Highlight Definition files</title> + +<varlistentry> +<term>A highlighting file contains a header that sets the XML version and the doctype:</term> +<listitem> +<programlisting> +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE language SYSTEM "language.dtd"> +</programlisting> +</listitem> +</varlistentry> + +<varlistentry> +<term>The root of the definition file is the element <userinput>language</userinput>. +Available attributes are:</term> + +<listitem> +<para>Required attributes:</para> +<para><userinput>name</userinput> sets the name of the language. It appears in the menus and dialogs afterwards.</para> +<para><userinput>section</userinput> specifies the category.</para> +<para><userinput>extensions</userinput> defines file extensions, like "*.cpp;*.h"</para> + +<para>Optional attributes:</para> +<para><userinput>mimetype</userinput> associates files &MIME; Type based.</para> +<para><userinput>version</userinput> specifies the current version of the definition file.</para> +<para><userinput>kateversion</userinput> specifies the latest supported &kate; version.</para> +<para><userinput>casesensitive</userinput> defines, whether the keywords are casesensitiv or not.</para> +<para><userinput>priority</userinput> is necessary if another highlight definition file uses the same extensions. The higher priority will win.</para> +<para><userinput>author</userinput> contains the name of the author and his email-address.</para> +<para><userinput>license</userinput> contains the license, usually LGPL, Artistic, GPL and others.</para> +<para><userinput>hidden</userinput> defines, whether the name should appear in &kate;'s menus.</para> +<para>So the next line may look like this:</para> +<programlisting> +<language name="C++" version="1.00" kateversion="2.4" section="Sources" extensions="*.cpp;*.h" /> +</programlisting> +</listitem> +</varlistentry> + + +<varlistentry> +<term>Next comes the <userinput>highlighting</userinput> element, which +contains the optional element <userinput>list</userinput> and the required +elements <userinput>contexts</userinput> and <userinput>itemDatas</userinput>.</term> +<listitem> +<para><userinput>list</userinput> elements contain a list of keywords. In +this case the keywords are <emphasis>class</emphasis> and <emphasis>const</emphasis>. +You can add as many lists as you need.</para> +<para>The <userinput>contexts</userinput> element contains all contexts. +The first context is by default the start of the highlighting. There are +two rules in the context <emphasis>Normal Text</emphasis>, which match +the list of keywords with the name <emphasis>somename</emphasis> and a +rule that detects a quote and switches the context to <emphasis>string</emphasis>. +To learn more about rules read the next chapter.</para> +<para>The third part is the <userinput>itemDatas</userinput> element. It +contains all color and font styles needed by the contexts and rules. +In this example, the <userinput>itemData</userinput> <emphasis>Normal Text</emphasis>, +<emphasis>String</emphasis> and <emphasis>Keyword</emphasis> are used. +</para> +<programlisting> + <highlighting> + <list name="somename"> + <item> class </item> + <item> const </item> + </list> + <contexts> + <context attribute="Normal Text" lineEndContext="#pop" name="Normal Text" > + <keyword attribute="Keyword" context="#stay" String="somename" /> + <DetectChar attribute="String" context="string" char="&quot;" /> + </context> + <context attribute="String" lineEndContext="#stay" name="string" > + <DetectChar attribute="String" context="#pop" char="&quot;" /> + </context> + </contexts> + <itemDatas> + <itemData name="Normal Text" defStyleNum="dsNormal" /> + <itemData name="Keyword" defStyleNum="dsKeyword" /> + <itemData name="String" defStyleNum="dsString" /> + </itemDatas> + </highlighting> +</programlisting> +</listitem> +</varlistentry> + +<varlistentry> +<term>The last part of a highlight definition is the optional +<userinput>general</userinput> section. It may contain information +about keywords, code folding, comments and indentation.</term> + +<listitem> +<para>The <userinput>comment</userinput> section defines with what +string a single line comment is introduced. You also can define a +multiline comments using <emphasis>multiLine</emphasis> with the +additional attribute <emphasis>end</emphasis>. This is used if the +user presses the corresponding shortcut for <emphasis>comment/uncomment</emphasis>.</para> +<para>The <userinput>keywords</userinput> section defines whether +keyword lists are casesensitive or not. Other attributes will be +explained later.</para> +<programlisting> + <general> + <comments> + <comment name="singleLine" start="#"/> + </comments> + <keywords casesensitive="1"/> + </general> +</language> +</programlisting> +</listitem> +</varlistentry> + +</variablelist> + + +</sect2> + +<sect2 id="kate-highlight-sections"> +<title>The Sections in Detail</title> +<para>This part will describe all available attributes for contexts, +itemDatas, keywords, comments, code folding and indentation.</para> + +<variablelist> +<varlistentry> +<term>The element <userinput>context</userinput> belongs into the group +<userinput>contexts</userinput>. A context itself defines context specific +rules like what should happen if the highlight system reaches the end of a +line. Available attributes are:</term> + + +<listitem> +<para><userinput>name</userinput> the context name. Rules will use this name +to specify the context to switch to if the rule matches.</para> +<para><userinput>lineEndContext</userinput> defines the context the highlight +system switches to if it reaches the end of a line. This may either be a name +of another context, <userinput>#stay</userinput> to not switch the context +(eg. do nothing) or <userinput>#pop</userinput> which will cause to leave this +context. It is possible to use for example <userinput>#pop#pop#pop</userinput> +to pop three times.</para> +<para><userinput>lineBeginContext</userinput> defines the context if a begin +of a line is encountered. Default: #stay.</para> +<para><userinput>fallthrough</userinput> defines if the highlight system switches +to the context specified in fallthroughContext if no rule matches. +Default: <emphasis>false</emphasis>.</para> +<para><userinput>fallthroughContext</userinput> specifies the next context +if no rule matches.</para> +<para><userinput>dynamic</userinput> if <emphasis>true</emphasis>, the context +remembers strings/placeholders saved by dynamic rules. This is needed for HERE +documents for example. Default: <emphasis>false</emphasis>.</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term>The element <userinput>itemData</userinput> is in the group +<userinput>itemDatas</userinput>. It defines the font style and colors. +So it is possible to define your own styles and colors, however we +recommend to stick to the default styles if possible so that the user +will always see the same colors used in different languages. Though, +sometimes there is no other way and it is necessary to change color +and font attributes. The attributes name and defStyleNum are required, +the other optional. Available attributes are:</term> + +<listitem> +<para><userinput>name</userinput> sets the name of the itemData. +Contexts and rules will use this name in their attribute +<emphasis>attribute</emphasis> to reference an itemData.</para> +<para><userinput>defStyleNum</userinput> defines which default style to use. +Available default styles are explained in detail later.</para> +<para><userinput>color</userinput> defines a color. Valid formats are +'#rrggbb' or '#rgb'.</para> +<para><userinput>selColor</userinput> defines the selection color.</para> +<para><userinput>italic</userinput> if <emphasis>true</emphasis>, the text will be italic.</para> +<para><userinput>bold</userinput> if <emphasis>true</emphasis>, the text will be bold.</para> +<para><userinput>underline</userinput> if <emphasis>true</emphasis>, the text will be underlined.</para> +<para><userinput>strikeout</userinput> if <emphasis>true</emphasis>, the text will be stroked out.</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term>The element <userinput>keywords</userinput> in the group +<userinput>general</userinput> defines keyword properties. Available attributes are:</term> + +<listitem> +<para><userinput>casesensitive</userinput> may be <emphasis>true</emphasis> +or <emphasis>false</emphasis>. If <emphasis>true</emphasis>, all keywords +are matched casesensitive</para> +<para><userinput>weakDeliminator</userinput> is a list of characters that +do not act as word delimiters. For example the dot <userinput>'.'</userinput> +is a word delimiter. Assume a keyword in a <userinput>list</userinput> contains +a dot, it will only match if you specify the dot as a weak delimiter.</para> +<para><userinput>additionalDeliminator</userinput> defines additional delimiters.</para> +<para><userinput>wordWrapDeliminator</userinput> defines characters after which a +line wrap may occur.</para> +<para>Default delimiters and word wrap delimiters are the characters +<userinput>.():!+,-<=>%&*/;?[]^{|}~\</userinput>, space (<userinput>' '</userinput>) +and tabulator (<userinput>'\t'</userinput>).</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term>The element <userinput>comment</userinput> in the group +<userinput>comments</userinput> defines comment properties which are used +for <menuchoice><guimenu>Tools</guimenu><guimenuitem>Comment</guimenuitem></menuchoice> and +<menuchoice><guimenu>Tools</guimenu><guimenuitem>Uncomment</guimenuitem></menuchoice>. +Available attributes are:</term> + +<listitem> +<para><userinput>name</userinput> is either <emphasis>singleLine</emphasis> +or <emphasis>multiLine</emphasis>. If you choose <emphasis>multiLine</emphasis> +the attributes <emphasis>end</emphasis> and <emphasis>region</emphasis> are +required.</para> +<para><userinput>start</userinput> defines the string used to start a comment. +In C++ this would be "/*".</para> +<para><userinput>end</userinput> defines the string used to close a comment. +In C++ this would be "*/".</para> +<para><userinput>region</userinput> should be the name of the the foldable +multiline comment. Assume you have <emphasis>beginRegion="Comment"</emphasis> +... <emphasis>endRegion="Comment"</emphasis> in your rules, you should use +<emphasis>region="Comment"</emphasis>. This way uncomment works even if you +do not select all the text of the multiline comment. The cursor only must be +in the multiline comment.</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term>The element <userinput>folding</userinput> in the group +<userinput>general</userinput> defines code folding properties. +Available attributes are:</term> + +<listitem> +<para><userinput>indentationsensitive</userinput> if <emphasis>true</emphasis>, the code folding markers +will be added indentation based, like in the scripting language Python. Usually you +do not need to set it, as it defaults to <emphasis>false</emphasis>.</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term>The element <userinput>indentation</userinput> in the group +<userinput>general</userinput> defines which indenter will be used, however we strongly +recommend to omit this element, as the indenter usually will be set by either defining +a File Type or by adding a mode line to the text file. If you specify an indenter though, +you will force a specific indentation on the user, which he might not like at all. +Available attributes are:</term> + +<listitem> +<para><userinput>mode</userinput> is the name of the indenter. Available indenters +right now are: <emphasis>normal, cstyle, csands, xml, python</emphasis> and +<emphasis>varindent</emphasis>.</para> +</listitem> +</varlistentry> + + +</variablelist> + + +</sect2> + +<sect2 id="kate-highlight-default-styles"> +<title>Available Default Styles</title> +<para>Default Styles were <link linkend="kate-highlight-system-default-styles">already explained</link>, +as a short summary: Default styles are predefined font and color styles.</para> +<variablelist> +<varlistentry> +<term>So here only the list of available default styles:</term> +<listitem> +<para><userinput>dsNormal</userinput>, used for normal text.</para> +<para><userinput>dsKeyword</userinput>, used for keywords.</para> +<para><userinput>dsDataType</userinput>, used for data types.</para> +<para><userinput>dsDecVal</userinput>, used for decimal values.</para> +<para><userinput>dsBaseN</userinput>, used for values with a base other than 10.</para> +<para><userinput>dsFloat</userinput>, used for float values.</para> +<para><userinput>dsChar</userinput>, used for a character.</para> +<para><userinput>dsString</userinput>, used for strings.</para> +<para><userinput>dsComment</userinput>, used for comments.</para> +<para><userinput>dsOthers</userinput>, used for 'other' things.</para> +<para><userinput>dsAlert</userinput>, used for warning messages.</para> +<para><userinput>dsFunction</userinput>, used for function calls.</para> +<para><userinput>dsRegionMarker</userinput>, used for region markers.</para> +<para><userinput>dsError</userinput>, used for error highlighting and wrong syntax.</para> +</listitem> +</varlistentry> +</variablelist> + +</sect2> + +</sect1> + +<sect1 id="kate-highlight-rules-detailled"> +<title>Highlight Detection Rules</title> + +<para>This section describes the syntax detection rules.</para> + +<para>Each rule can match zero or more characters at the beginning of +the string they are test against. If the rule matches, the matching +characters are assigned the style or <emphasis>attribute</emphasis> +defined by the rule, and a rule may ask that the current context is +switched.</para> + +<para>A rule looks like this:</para> + +<programlisting><RuleName attribute="(identifier)" context="(identifier)" [rule specific attributes] /></programlisting> + +<para>The <emphasis>attribute</emphasis> identifies the style to use +for matched characters by name, and the <emphasis>context</emphasis> +identifies the context to use from here.</para> + +<para>The <emphasis>context</emphasis> can be identified by:</para> + +<itemizedlist> +<listitem> +<para>An <emphasis>identifier</emphasis>, which is the name of the other +context.</para> +</listitem> +<listitem> +<para>An <emphasis>order</emphasis> telling the engine to stay in the +current context (<userinput>#stay</userinput>), or to pop back to a +previous context used in the string (<userinput>#pop</userinput>).</para> +<para>To go back more steps, the #pop keyword can be repeated: +<userinput>#pop#pop#pop</userinput></para> +</listitem> +</itemizedlist> + +<para>Some rules can have <emphasis>child rules</emphasis> which are +then evaluated only if the parent rule matched. The entire matched +string will be given the attribute defined by the parent rule. A rule +with child rules looks like this:</para> + +<programlisting> +<RuleName (attributes)> + <ChildRuleName (attributes) /> + ... +</RuleName> +</programlisting> + + +<para>Rule specific attributes varies and are described in the +following sections.</para> + + +<itemizedlist> +<title>Common attributes</title> +<para>All rules have the following attributes in common and are +available whenever <userinput>(common attributes)</userinput> appears. +<emphasis>attribute</emphasis> and <emphasis>context</emphasis> +are required attributes, all others are optional. +</para> + +<listitem> +<para><emphasis>attribute</emphasis>: An attribute maps to a defined <emphasis>itemData</emphasis>.</para> +</listitem> +<listitem> +<para><emphasis>context</emphasis>: Specify the context to which the highlighting system switches if the rule matches.</para> +</listitem> +<listitem> +<para><emphasis>beginRegion</emphasis>: Start a code folding block. Default: unset.</para> +</listitem> +<listitem> +<para><emphasis>endRegion</emphasis>: Close a code folding block. Default: unset.</para> +</listitem> +<listitem> +<para><emphasis>lookAhead</emphasis>: If <emphasis>true</emphasis>, the +highlighting system will not process the matches length. +Default: <emphasis>false</emphasis>.</para> +</listitem> +<listitem> +<para><emphasis>firstNonSpace</emphasis>: Match only, if the string is +the first non-whitespace in the line. Default: <emphasis>false</emphasis>.</para> +</listitem> +<listitem> +<para><emphasis>column</emphasis>: Match only, if the column matches. Default: unset.</para> +</listitem> +</itemizedlist> + +<itemizedlist> +<title>Dynamic rules</title> +<para>Some rules allow the optional attribute <userinput>dynamic</userinput> +of type boolean that defaults to <emphasis>false</emphasis>. If dynamic is +<emphasis>true</emphasis>, a rule can use placeholders representing the text +matched by a <emphasis>regular expression</emphasis> rule that switched to the +current context in its <userinput>string</userinput> or +<userinput>char</userinput> attributes. In a <userinput>string</userinput>, +the placeholder <replaceable>%N</replaceable> (where N is a number) will be +replaced with the corresponding capture <replaceable>N</replaceable> +from the calling regular expression. In a +<userinput>char</userinput> the placeholer must be a number +<replaceable>N</replaceable> and it will be replaced with the first character of +the corresponding capture <replaceable>N</replaceable> from the calling regular +expression. Whenever a rule allows this attribute it will contain a +<emphasis>(dynamic)</emphasis>.</para> + +<listitem> +<para><emphasis>dynamic</emphasis>: may be <emphasis>(true|false)</emphasis>.</para> +</listitem> +</itemizedlist> + +<sect2 id="highlighting-rules-in-detail"> +<title>The Rules in Detail</title> + +<variablelist> +<varlistentry> +<term>DetectChar</term> +<listitem> +<para>Detect a single specific character. Commonly used for example to +find the ends of quoted strings.</para> +<programlisting><DetectChar char="(character)" (common attributes) (dynamic) /></programlisting> +<para>The <userinput>char</userinput> attribute defines the character +to match.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Detect2Chars</term> +<listitem> +<para>Detect two specific characters in a defined order.</para> +<programlisting><Detect2Chars char="(character)" char1="(character)" (common attributes) (dynamic) /></programlisting> +<para>The <userinput>char</userinput> attribute defines the first character to match, +<userinput>char1</userinput> the second.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>AnyChar</term> +<listitem> +<para>Detect one character of a set of specified characters.</para> +<programlisting><AnyChar String="(string)" (common attributes) /></programlisting> +<para>The <userinput>String</userinput> attribute defines the set of +characters.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>StringDetect</term> +<listitem> +<para>Detect an exact string.</para> +<programlisting><StringDetect String="(string)" [insensitive="true|false"] (common attributes) (dynamic) /></programlisting> +<para>The <userinput>String</userinput> attribute defines the string +to match. The <userinput>insensitive</userinput> attribute defaults to +<emphasis>false</emphasis> and is passed to the string comparison +function. If the value is <emphasis>true</emphasis> insensitive +comparing is used.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>RegExpr</term> +<listitem> +<para>Matches against a regular expression.</para> +<programlisting><RegExpr String="(string)" [insensitive="true|false"] [minimal="true|false"] (common attributes) (dynamic) /></programlisting> +<para>The <userinput>String</userinput> attribute defines the regular +expression.</para> +<para><userinput>insensitive</userinput> defaults to +<emphasis>false</emphasis> and is passed to the regular expression +engine.</para> +<para><userinput>minimal</userinput> defaults to +<emphasis>false</emphasis> and is passed to the regular expression +engine.</para> +<para>Because the rules are always matched against the beginning of +the current string, a regular expression starting with a caret +(<literal>^</literal>) indicates that the rule should only be +matched against the start of a line.</para> +<para>See <link linkend="regular-expressions">Regular Expressions</link> +for more information on those.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>keyword</term> +<listitem> +<para>Detect a keyword from a specified list.</para> +<programlisting><keyword String="(list name)" (common attributes) /></programlisting> +<para>The <userinput>String</userinput> attribute identifies the +keyword list by name. A list with that name must exist.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Int</term> +<listitem> +<para>Detect an integer number.</para> +<para><programlisting><Int (common attributes) (dynamic) /></programlisting></para> +<para>This rule has no specific attributes. Child rules are typically +used to detect combinations of <userinput>L</userinput> and +<userinput>U</userinput> after the number, indicating the integer type +in program code. Actually all rules are allowed as child rules, though, +the <acronym>DTD</acronym> only allowes the child rule <userinput>StringDetect</userinput>.</para> +<para>The following example matches integer numbers follows by the character 'L'. +<programlisting> +<Int attribute="Decimal" context="#stay" > + <StringDetect attribute="Decimal" context="#stay" String="L" insensitive="true"/> +</Int> +</programlisting></para> + +</listitem> +</varlistentry> + +<varlistentry> +<term>Float</term> +<listitem> +<para>Detect a floating point number.</para> +<para><programlisting><Float (common attributes) /></programlisting></para> +<para>This rule has no specific attributes. <userinput>AnyChar</userinput> is +allowed as a child rules and typically used to detect combinations, see rule +<userinput>Int</userinput> for reference.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>HlCOct</term> +<listitem> +<para>Detect an octal point number representation.</para> +<para><programlisting><HlCOct (common attributes) /></programlisting></para> +<para>This rule has no specific attributes.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>HlCHex</term> +<listitem> +<para>Detect a hexadecimal number representation.</para> +<para><programlisting><HlCHex (common attributes) /></programlisting></para> +<para>This rule has no specific attributes.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>HlCStringChar</term> +<listitem> +<para>Detect an escaped character.</para> +<para><programlisting><HlCStringChar (common attributes) /></programlisting></para> +<para>This rule has no specific attributes.</para> + +<para>It matches literal representations of characters commonly used in +program code, for example <userinput>\n</userinput> +(newline) or <userinput>\t</userinput> (TAB).</para> + +<para>The following characters will match if they follow a backslash +(<literal>\</literal>): +<userinput>abefnrtv"'?\</userinput>. Additionally, escaped +hexadecimal numbers like for example <userinput>\xff</userinput> and +escaped octal numbers, for example <userinput>\033</userinput> will +match.</para> + +</listitem> +</varlistentry> + +<varlistentry> +<term>HlCChar</term> +<listitem> +<para>Detect an C character.</para> +<para><programlisting><HlCChar (common attributes) /></programlisting></para> +<para>This rule has no specific attributes.</para> + +<para>It matches C characters enclosed in a tick (Example: <userinput>'c'</userinput>). +So in the ticks may be a simple character or an escaped character. +See HlCStringChar for matched escaped character sequences.</para> + +</listitem> +</varlistentry> + +<varlistentry> +<term>RangeDetect</term> +<listitem> +<para>Detect a string with defined start and end characters.</para> +<programlisting><RangeDetect char="(character)" char1="(character)" (common attributes) /></programlisting> +<para><userinput>char</userinput> defines the character starting the range, +<userinput>char1</userinput> the character ending the range.</para> +<para>Usefull to detect for example small quoted strings and the like, but +note that since the highlighting engine works on one line at a time, this +will not find strings spanning over a line break.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>LineContinue</term> +<listitem> +<para>Matches at end of line.</para> +<programlisting><LineContinue (common attributes) /></programlisting> +<para>This rule has no specific attributes.</para> +<para>This rule is useful for switching context at end of line, if the last +character is a backslash (<userinput>'\'</userinput>). This is needed for +example in C/C++ to continue macros or strings.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>IncludeRules</term> +<listitem> +<para>Include rules from another context or language/file.</para> +<programlisting><IncludeRules context="contextlink" [includeAttrib="true|false"] /></programlisting> + +<para>The <userinput>context</userinput> attribute defines which context to include.</para> +<para>If it a simple string it includes all defined rules into the current context, example: +<programlisting><IncludeRules context="anotherContext" /></programlisting></para> + +<para> +If the string begins with <userinput>##</userinput> the highlight system +will look for another language definition with the given name, example: +<programlisting><IncludeRules context="##C++" /></programlisting></para> +<para>If <userinput>includeAttrib</userinput> attribute is +<emphasis>true</emphasis>, change the destination attribute to the one of +the source. This is required to make for example commenting work, if text +matched by the included context is a different highlight than the host +context. +</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term>DetectSpaces</term> +<listitem> +<para>Detect whitespaces.</para> +<programlisting><DetectSpaces (common attributes) /></programlisting> + +<para>This rule has no specific attributes.</para> +<para>Use this rule if you know that there can several whitespaces ahead, +for example in the beginning of indented lines. This rule will skip all +whitespace at once, instead of testing multiple rules and skipping one at the +time due to no match.</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term>DetectIdentifier</term> +<listitem> +<para>Detect identifier strings (as a regular expression: [a-zA-Z_][a-zA-Z0-9_]*).</para> +<programlisting><DetectIdentifier (common attributes) /></programlisting> + +<para>This rule has no specific attributes.</para> +<para>Use this rule to skip a string of word characters at once, rather than +testing with multiple rules and skipping one at the time due to no match.</para> +</listitem> +</varlistentry> + +</variablelist> +</sect2> + +<sect2> +<title>Tips & Tricks</title> + +<itemizedlist> +<para>Once you have understood how the context switching works it will be +easy to write highlight definitions. Though you should carefully check what +rule you choose in what situation. Regular expressions are very mighty, but +they are slow compared to the other rules. So you may consider the following +tips. +</para> + +<listitem> +<para>If you only match two characters use <userinput>Detect2Chars</userinput> +instead of <userinput>StringDetect</userinput>. The same applies to +<userinput>DetectChar</userinput>.</para> +</listitem> +<listitem> +<para>Regular expressions are easy to use but often there is another much +faster way to achieve the same result. Consider you only want to match +the character <userinput>'#'</userinput> if it is the first character in the +line. A regular expression based solution would look like this: +<programlisting><RegExpr attribute="Macro" context="macro" String="^\s*#" /></programlisting> +You can achieve the same much faster in using: +<programlisting><DetectChar attribute="Macro" context="macro" char="#" firstNonSpace="true" /></programlisting> +If you want to match the regular expression <userinput>'^#'</userinput> you +can still use <userinput>DetectChar</userinput> with the attribute <userinput>column="0"</userinput>. +The attribute <userinput>column</userinput> counts character based, so a tabulator still is only one character. +</para> +</listitem> +<listitem> +<para>You can switch contexts without processing characters. Assume that you +want to switch context when you meet the string <userinput>*/</userinput>, but +need to process that string in the next context. The below rule will match, and +the <userinput>lookAhead</userinput> attribute will cause the highlighter to +keep the matched string for the next context. +<programlisting><Detect2Chars attribute="Comment" context="#pop" char="*" char1="/" lookAhead="true" /></programlisting> +</para> +</listitem> +<listitem> +<para>Use <userinput>DetectSpaces</userinput> if you know that many whitespaces occur.</para> +</listitem> +<listitem> +<para>Use <userinput>DetectIdentifier</userinput> instead of the regular expression <userinput>'[a-zA-Z_]\w*'</userinput>.</para> +</listitem> +<listitem> +<para>Use default styles whenever you can. This way the user will find a familiar environment.</para> +</listitem> +<listitem> +<para>Look into other XML-files to see how other people implement tricky rules.</para> +</listitem> +<listitem> +<para>You can validate every XML file by using the command +<command>xmllint --dtdvalid language.dtd mySyntax.xml</command>.</para> +</listitem> +<listitem> +<para>If you repeat complex regular expression very often you can use +<emphasis>ENTITIES</emphasis>. Example:</para> +<programlisting> +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE language SYSTEM "language.dtd" +[ + <!ENTITY myref "[A-Za-z_:][\w.:_-]*"> +]> +</programlisting> +<para>Now you can use <emphasis>&myref;</emphasis> instead of the regular +expression.</para> +</listitem> +</itemizedlist> +</sect2> + +</sect1> + +</appendix> diff --git a/doc/kate/index.docbook b/doc/kate/index.docbook new file mode 100644 index 000000000..01835025f --- /dev/null +++ b/doc/kate/index.docbook @@ -0,0 +1,292 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ + <!ENTITY kappname "&kate;"> + <!ENTITY package "tdebase"> + <!ENTITY configuring-chapter SYSTEM "configuring.docbook"> + <!ENTITY highlighting-appendix SYSTEM "highlighting.docbook"> + <!ENTITY advanced-chapter SYSTEM "advanced.docbook"> + <!ENTITY fundamentals-chapter SYSTEM "fundamentals.docbook"> + <!ENTITY mdi-chapter SYSTEM "mdi.docbook"> + <!ENTITY menu-chapter SYSTEM "menus.docbook"> + <!ENTITY part-chapter SYSTEM "part.docbook"> + <!ENTITY plugins-chapter SYSTEM "plugins.docbook"> + <!ENTITY regexp-appendix SYSTEM "regular-expressions.docbook"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE"><!-- change language only here --> +]> + +<book lang="&language;"> +<title>The &kate; Handbook</title> + +<bookinfo> +<authorgroup> +<author>&Anders.Lund; &Anders.Lund.mail;</author> +<author>&Seth.Rothberg; &Seth.Rothberg.mail;</author> +<author>&Dominik.Haumann; &Dominik.Haumann.mail;</author> +<author>&tde-authors;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<copyright> +<year>2000</year> +<year>2001</year> +<holder>&Seth.Rothberg;</holder> +</copyright> +<copyright> +<year>2002</year><year>2003</year><year>2005</year> +<holder>&Anders.Lund;</holder> +</copyright> +<copyright> +<year>2005</year> +<holder>&Dominik.Haumann;</holder> +</copyright> +<copyright> +<year>&tde-copyright-date;</year> +<holder>&tde-team;</holder> +</copyright> + +<legalnotice>&FDLNotice;</legalnotice> + +<date>January 16, 2014</date> +<releaseinfo>&tde-release-version;</releaseinfo> + +<abstract> +<para>&kate; is a programmer's text editor for &tde;</para> + +<para>This handbook documents &kate; Version 2.5.14</para> +</abstract> + +<keywordset> +<keyword>TDE</keyword> +<keyword>tdebase</keyword> +<keyword>Kate</keyword> +<keyword>text</keyword> +<keyword>editor</keyword> +<keyword>programmer</keyword> +<keyword>programming</keyword> +<keyword>projects</keyword> +<keyword>MDI</keyword> +<keyword>Multi</keyword> +<keyword>Document</keyword> +<keyword>Interface</keyword> +<keyword>terminal</keyword> +<keyword>console</keyword> +</keywordset> + +</bookinfo> + +<chapter id="introduction"> +<title>Introduction</title> + +<para> +Welcome to &kate;, a programmer's text editor for &tde;. +Some of &kate;'s many features include configurable syntax +highlighting for languages ranging from C and C++ to +<acronym>HTML</acronym> to bash scripts, the ability to create and +maintain projects, a multiple document interface +(<acronym>MDI</acronym>), and a self-contained terminal emulator. +</para> + +<para> +But &kate; is more than a programmer's editor. Its ability to open +several files at once makes it ideal for editing &UNIX;'s many +configuration files. This document was written in &kate;. +</para> + +<para> +<mediaobject> +<imageobject><imagedata format="PNG" fileref="kate.png"/></imageobject> +</mediaobject> +</para> + +</chapter> + +&fundamentals-chapter; + +&mdi-chapter; + +&part-chapter; + +&plugins-chapter; + +&advanced-chapter; + +&menu-chapter; + +&configuring-chapter; + +<chapter id="credits"> + +<title>Credits and License</title> + +<para> +&kate;. Program copyright 2000, 2001, 2002 - 2005 by the &kate; developer team. +</para> +<para> +&kate;. Program copyright &tde-copyright-date; by &tde-team;. +</para> + +<variablelist> +<title>The &kate; team:</title> +<varlistentry> +<term>&Christoph.Cullmann; &Christoph.Cullmann.mail;</term> +<listitem><para>Project Manager & Core Developer</para></listitem> +</varlistentry> +<varlistentry> +<term>&Anders.Lund; &Anders.Lund.mail;</term> +<listitem><para>Core Developer, Perl syntax highlighting, +documentation</para></listitem> +</varlistentry> +<varlistentry> +<term>&Joseph.Wenninger; &Joseph.Wenninger.mail;</term> +<listitem><para>Core Developer, syntax highlighting</para></listitem> +</varlistentry> +<varlistentry> +<term>Michael Bartl <email>[email protected]</email></term> +<listitem><para>Core Developer</para></listitem> +</varlistentry> +<varlistentry> +<term>Phlip <email>[email protected]</email></term> +<listitem><para>The project compiler</para></listitem> +</varlistentry> +<varlistentry> +<term>&Waldo.Bastian; &Waldo.Bastian.mail;</term> +<listitem><para>The cool buffer system</para></listitem> +</varlistentry> +<varlistentry> +<term>Matt Newell <email>[email protected]</email></term> +<listitem><para>Testing...</para></listitem> +</varlistentry> +<varlistentry> +<term>Michael McCallum <email>[email protected]</email></term> +<listitem><para>Core Developer</para></listitem> +</varlistentry> +<varlistentry> +<term>Jochen Wilhemly <email>[email protected]</email></term> +<listitem><para>KWrite Author</para></listitem> +</varlistentry> +<varlistentry> +<term>&Michael.Koch; &Michael.Koch.mail;</term> +<listitem><para>KWrite port to KParts</para></listitem> +</varlistentry> +<varlistentry> +<term>Christian Gebauer <email>[email protected]</email></term> +<listitem><para>Unspecified</para></listitem> +</varlistentry> +<varlistentry> +<term>&Simon.Hausmann; &Simon.Hausmann.mail;</term> +<listitem><para>Unspecified</para></listitem> +</varlistentry> +<varlistentry> +<term>Glen Parker <email>[email protected]</email></term> +<listitem><para>KWrite Undo History, KSpell integration</para></listitem> +</varlistentry> +<varlistentry> +<term>Scott Manson <email>[email protected]</email></term> +<listitem><para>KWrite XML syntax highlighting support</para></listitem> +</varlistentry> +<varlistentry> +<term>&John.Firebaugh; &John.Firebaugh.mail;</term> +<listitem><para>Various Patches</para></listitem> +</varlistentry> +<varlistentry> +<term>&Dominik.Haumann; &Dominik.Haumann.mail;</term> +<listitem><para>Developer, Highlight wizard</para></listitem> +</varlistentry> +</variablelist> + +<variablelist> +<title>Many other people have contributed:</title> +<varlistentry> +<term>Matteo Merli <email>[email protected]</email></term> +<listitem><para>Highlighting for RPM Spec-Files, Diff and more</para></listitem> +</varlistentry> +<varlistentry> +<term>Rocky Scaletta <email>[email protected]</email></term> +<listitem><para>Highlighting for VHDL</para></listitem> +</varlistentry> +<varlistentry> +<term>Yury Lebedev </term> +<listitem><para>Highlighting for SQL</para></listitem> +</varlistentry> +<varlistentry> +<term>Chris Ross</term> +<listitem><para>Highlighting for Ferite</para></listitem> +</varlistentry> +<varlistentry> +<term>Nick Roux</term> +<listitem><para>Highlighting for ILERPG</para></listitem> +</varlistentry> +<varlistentry> +<term>John Firebaugh</term> +<listitem><para>Highlighting for Java, and much more</para></listitem> +</varlistentry> +<varlistentry> +<term>Carsten Niehaus</term> +<listitem><para>Highlighting for LaTeX</para></listitem> +</varlistentry> +<varlistentry> +<term>Per Wigren</term> +<listitem><para>Highlighting for Makefiles, Python</para></listitem> +</varlistentry> +<varlistentry> +<term>Jan Fritz</term> +<listitem><para>Highlighting for Python</para></listitem> +</varlistentry> +<varlistentry> +<term>&Daniel.Naber;</term> +<listitem><para>Small bugfixes, XML plugin</para></listitem> +</varlistentry> +</variablelist> + +<para>Documentation copyright 2000,2001 &Seth.Rothberg; +&Seth.Rothberg.mail;</para> + +<para>Documentation copyright 2002, 2003, 2005 &Anders.Lund; +&Anders.Lund.mail;</para> + +<para>Documentation copyright &tde-copyright-date; &tde-team;.</para> +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +&underFDL; <!-- FDL: do not remove --> +&underGPL; <!-- GPL License --> + +</chapter> + +&highlighting-appendix; + +®exp-appendix; + +&documentation.index; + +<!-- +Index Word List: +menu - context - syntax - markup - shortcuts - highlighting +embedded terminal - editing - search - replace - regexp -> Regular Expression +split window - selection - insert overwrite - selection - +configure/customize/preferences - insert/overwrite - non-printing characters +font - unicode - wordwrap/linewrap - project - bookmarks - docks - plugins +block selection / rectangles - view - indenting - editor - word processor +copy - paste - find - spelling - language (both kinds) - encoding - +pretty printing - formatting - line numbers - icon border - +folding - insert time - sed + +done +comment / uncomment +configure / settings / preferences + +--> + +</book> + +<!-- +Local Variables: +mode: sgml +sgml-namecase-general: t +sgml-namecase-entity: nil +sgml-general-insert-case: lower +sgml-minimize-attributes: nil +sgml-omittag: nil +End: +--> diff --git a/doc/kate/kate.png b/doc/kate/kate.png Binary files differnew file mode 100644 index 000000000..dc1ee4c40 --- /dev/null +++ b/doc/kate/kate.png diff --git a/doc/kate/man-kate.1.docbook b/doc/kate/man-kate.1.docbook new file mode 100644 index 000000000..ff15e0009 --- /dev/null +++ b/doc/kate/man-kate.1.docbook @@ -0,0 +1,165 @@ +<?xml version="1.0" ?> +<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ +<!ENTITY % English "INCLUDE"> +]> + +<refentry lang="&language;"> +<refentryinfo> +<title>KDE User's Manual</title> +<author>&Lauri.Watts; &Lauri.Watts.mail;</author> +<date>June 07, 2005</date> +<productname>Trinity Desktop Environment</productname> +</refentryinfo> + +<refmeta> +<refentrytitle><command>kate</command></refentrytitle> +<manvolnum>1</manvolnum> +</refmeta> + +<refnamediv> +<refname><command>kate</command></refname> +<refpurpose>Advanced text editor for &tde;</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>kate</command> +<group choice="opt"><option>-s, --start</option> <replaceable> +name</replaceable> </group> +<group choice="opt"><option>-u, --use</option></group> +<group choice="opt"><option>-p, --pid</option><replaceable> +pid</replaceable></group> +<group choice="opt"><option>-e, --encoding</option> <replaceable> +name</replaceable></group> +<group choice="opt"><option>-l, --line</option> <replaceable> +line</replaceable></group> +<group choice="opt"><option>-c, --column</option> +<replaceable> column</replaceable></group> +<group choice="opt"><option>-i, --stdin</option></group> +<arg choice="opt">KDE Generic Options</arg> +<arg choice="opt">Qt Generic Options</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> +<para>&kate; is the &tde; Advanced Text Editor.</para> +<para>&kate; also provides the editor part for various applications, under +the name &kwrite;.</para> +<para>Some of &kate;'s many features include configurable syntax +highlighting for languages ranging from C and C++ to +<acronym>HTML</acronym> to bash scripts, the ability to create and +maintain projects, a multiple document interface +(<acronym>MDI</acronym>), and a self-contained terminal emulator. +</para> + +<para> +But &kate; is more than a programmer's editor. Its ability to open +several files at once makes it ideal for editing &UNIX;'s many +configuration files. This document was written in &kate;. +</para> + + +</refsect1> + +<refsect1> +<title>Options</title> + +<variablelist> +<varlistentry> +<term><option>-s</option>, <option>--start</option> <replaceable>name</replaceable></term> + +<listitem><para>Start &kate; with a given session.</para></listitem> +</varlistentry> +<varlistentry> +<term><option>-u, --use</option></term> +<listitem><para>Use an already running &kate;</para></listitem> +</varlistentry> +<varlistentry> +<term><option>-p, --pid</option> <replaceable> +pid</replaceable></term> +<listitem><para>Only try to reuse kate instance with this +<replaceable>pid</replaceable></para></listitem> +</varlistentry> +<varlistentry> +<term><option>-e, --encoding</option> <replaceable> +name</replaceable></term> +<listitem><para>Set encoding for the file to open</para><para>You can use +this to force a file opened in utf-8 format, for instance. (The command +<command>iconv -l</command> provides a list of encodings, which may be +helpful to you.)</para></listitem> +</varlistentry> +<varlistentry> +<term><option>-l, --line</option> <replaceable> line</replaceable></term> +<listitem><para>Navigate to this line</para></listitem> +</varlistentry> +<varlistentry> +<term><option>-c, --column</option> <replaceable> +column</replaceable></term> +<listitem><para>Navigate to this column</para></listitem> +</varlistentry> +<varlistentry> +<term><option>-i, --stdin</option></term> +<listitem><para>Read the contents of +<filename>stdin</filename></para></listitem> +</varlistentry> +</variablelist> + +</refsect1> + +<refsect1> +<title>See Also</title> + +<para>kwrite(1)</para> + +<para>More detailed user documentation is available from <ulink +url="help:/kate">help:/kate</ulink> +(either enter this <acronym>URL</acronym> into &konqueror;, or run +<userinput><command>khelpcenter</command> +<parameter>help:/kate</parameter></userinput>).</para> + +<para>There is also further information available at <ulink +url="http://kate.kde.org/">the &kate; website</ulink>.</para> +</refsect1> + +<refsect1> +<title>Examples</title> + +<para>To open a file named <filename>source.cpp</filename> at column 15, +line 25, in an existing &kate; window, you could use:</para> +<screen><userinput><command>kate</command> <option>-c 15</option> <option>-l +25</option> <option>-u</option> <filename>source.cpp</filename></userinput> </screen> + +<para>If you have an active internet connection, you can take advantage of +&tde;'s network transparency to open a file from an ftp site. If you do not +have write permission on the remote server, the file will be opened read +only and you will be prompted for a local filename to save to if you make +changes. If you do have write permission, changes will be saved +transparently over the network.</para> +<screen><userinput><command>kate</command> <option><replaceable>ftp://ftp.kde.org/pub/kde/README_FIRST</replaceable></option></userinput></screen> + +<!-- FIXME: Some more useful examples would be cool, how about this snagged --> +<!-- from a mail of anders (slightly edited /line/l to remove the double --> +<!-- dashes: + +> /some/file/path/file.name:lineno +> it would rock if Kate could understand that and not only open up file.name, +> but jump to lineno after the file is opened. + +How bad is it to have to convert that into +-l lineno /some/file/path/file.name + +sed s,([^:]*):(\d+),-l \2 \1, + +will do that, for example.--> + +</refsect1> + +<refsect1> +<title>Authors</title> +<para>The maintainer of &kate; is &Christoph.Cullmann; +&Christoph.Cullmann.mail;. A comprehensive list of authors and contributors +is available in the complete user manual mentioned above.</para> +</refsect1> + +</refentry> diff --git a/doc/kate/mdi.docbook b/doc/kate/mdi.docbook new file mode 100644 index 000000000..993682b6e --- /dev/null +++ b/doc/kate/mdi.docbook @@ -0,0 +1,385 @@ +<chapter id="kate-mdi"> +<chapterinfo> +<authorgroup> +<author>&Anders.Lund; &Anders.Lund.mail;</author> +<author>&tde-authors;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</chapterinfo> +<title>Working With the &kate; <acronym>MDI</acronym></title> + +<sect1 id="kate-mdi-overview"> +<title>Overview</title> + +<para>Window, View, Document, Frame, Editor... What are they all in +the terminology of &kate;, and how do you get the most out of it? This +chapter will explain all of that, and even more.</para> + +<sect2 id="kate-mdi-overview-mainwindow"> + +<title>The Main Window</title> + +<para><indexterm><primary>Main window</primary></indexterm> +The &kate; Main Window is a standard &tde; application window, +with the addition of side bars containing tool views. It has a +Menubar with all the common menus, and some more, and a toolbar +providing access to commonly used commands.</para> + +<para>The most important part of the window is the Editing Area, by +default displaying a single text editor component, in which you can +work with your documents.</para> + +<para>The docking capabilities of the window is used for the tool +windows:</para> + +<itemizedlist> +<listitem><para><link linkend="kate-mdi-tools-document-list">The Document List</link></para></listitem> +<listitem><para><link linkend="kate-mdi-tools-file-selector">The Filesystem +Browser</link></para></listitem> +<listitem><para><link linkend="kate-mdi-tools-konsole">The Built in Terminal Emulator</link></para></listitem> +</itemizedlist> + +<para>And possibly other tool views, for example provided by +plugins.</para> + +<para>Tool views can be positioned in any sidebar. To move a tool, right click its +sidebar button and select the destination sidebar from the <guimenu>Move to</guimenu> menu that appears.</para> + +<para>A tool view can be marked as <emphasis>persistent</emphasis>. Selecting another +tool view in the same sidebar will not hide any of the persistent tool views. +To make a tool view persistent, right click its sidebar button and select the +"Make persistent" entry from the <guimenu>Behavior</guimenu> menu that appears.</para> + +<para>Each sidebar can contain more than one tool, so when a tool is persistant +other tools can be shown simultaneously.</para> + +</sect2> + + +</sect1> + +<sect1 id="kate-mdi-editor"> + +<title>The Editor area</title> + +<para><indexterm><primary>Editing Area</primary></indexterm> +&kate; is capable of having more than one document open at the +same time, and also of splitting the editing area into any number of +frames, similar to how for example &konqueror; or the popular +<application>emacs</application> text editor works. This way you can +view several documents at the same time, or more instances of the same +document, handy for example if your document contains definitions in +the top that you want to see often for reference. Or you could view a +program source header in one frame, while editing the implementation +file in another.</para> + +<para>When a document is available in more than one editor, changes +made in one editor will immediately be reflected in the others as +well. This includes changing the text as well as selecting +text. Search operations or cursor movement is only reflected in the +current editor.</para> + +<para>It is currently not possible to have more instances of the same +document open in the sense that one instance will be edited while the +other will not.</para> + +<para>When splitting an editor into two frames, it is divided into two +equally sized frames, both displaying the current document of that +editor. The new frame will be at the bottom (in the case of a +horizontal split) or at the right (for a vertical split) and will +get the focus.</para> + +<para>Refer to this <link linkend="window-split-vertical">section</link> +for instructions on how to split the current editor.</para> + +</sect1> + +<sect1 id="kate-mdi-tools-document-list"> +<title>The Document List</title> + +<para><indexterm><primary>Document list</primary></indexterm> +The document list displays a list of all documents currently open in +&kate;. Modified files will have a small <guiicon>floppy +disk</guiicon> icon on their left to indicate that state.</para> + +<para>If two or more files with the same name (located in different +folders) are open, the name of the second will be appended with +<quote>(2)</quote> and so on. The tool-tip for the file will +display its full name including the path, allowing you to choose the +desired one.</para> <para>To display a document in the currently +active frame, click the document name in the list.</para> + +<para>You can sort the list in a few different ways by rightclicking the +list and selecting from the <guisubmenu>Sort By</guisubmenu> menu. + +The options are: +<variablelist> + +<varlistentry> +<term><guimenuitem>Opening Order</guimenuitem></term> +<listitem><para>Lists the documents in the order of opening.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Document Name</guimenuitem></term> +<listitem><para>Lists the documents alphabetically by their name.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>URL</guimenuitem></term> +<listitem><para>Lists the documents alphabetically by URL.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Manual Placement</guimenuitem></term> +<listitem><para>Allows you to specify the order of the documents. You can change the order by dragging files up/down the list.</para></listitem> +</varlistentry> + +</variablelist> + +</para> + +<para>The document list will per default visualize your history by shading the +entries for the most recent documents with a background color. If the document +was edited, an extra color is blended in. The most recent document has the +strongest color, so that you can easily find the documents you are working on. +This feature can be disabled in +<link linkend="config-dialog-documentlist">The Document List Page</link> +of the configuration dialog.</para> + +<para>The default location of the Document List in &kate; is to the left of the +editing area.</para> + +</sect1> + +<sect1 id="kate-mdi-tools-file-selector"> +<title>The Filesystem Browser</title> + +<para><indexterm><primary>Filesystem Browser</primary></indexterm> +The Filesystem Browser is a folder viewer, allowing you to open +files from a displayed folder in the current frame.</para> + +<para>From top down, the Filesystem Browser consist of the following +elements:</para> + +<variablelist> +<varlistentry> +<term>A Toolbar</term> +<listitem> +<para>This contains standard navigations tool buttons (refer to this <link linkend="config-dialog-fileselector">section</link> +for instructions on how to show/hide individual toolbar buttons):</para> +<variablelist> +<varlistentry> +<term><guibutton>Home</guibutton></term> +<listitem><para>Pressing it will cause the folder view to <command>cd</command> to your home folder.</para></listitem> +</varlistentry> +<varlistentry> +<term><guibutton>Up</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>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>Reload</guibutton></term> +<listitem><para>Causes the folder view to refresh the current view.</para></listitem> +</varlistentry> +<varlistentry> +<term><guibutton>Short View</guibutton></term> +<listitem><para>The folder view will display only the file and folder names, without further details.</para></listitem> +</varlistentry> +<varlistentry> +<term><guibutton>Detailed view</guibutton></term> +<listitem><para>The folder view will display additional file and folder details (for example size, permission, modification date).</para></listitem> +</varlistentry> +<varlistentry> +<term><guibutton>Bookmarks menu</guibutton></term> +<listitem><para>A menu displaying your favourite folders for quick access to them.</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> +</varlistentry> +<varlistentry> +<term><guibutton>New folder...</guibutton></term> +<listitem><para>Pressing this button will create a new subfolder in the current folder.</para></listitem> +</varlistentry> +<varlistentry> +<term><guibutton>Delete</guibutton></term> +<listitem><para>Pressing this button will delete the selected files/folders.</para></listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term>A &URL; entry</term> +<listitem> +<para>Here 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. Refer to this <link linkend="config-dialog-fileselector-urls">section</link> +to change the number of URLs to remember.</para> +<tip><para>The &URL; entry has folder auto-completion capability. The completion +method can be set by right clicking of the &URL; text and selecting the preferred method +from the <guimenuitem>Text Completion</guimenuitem> menu.</para></tip> +</listitem> +</varlistentry> + +<varlistentry> +<term>A Folder View</term> +<listitem><para>This is a standard &tde; folder view.</para></listitem> +</varlistentry> + +<varlistentry> +<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 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> or no filter at all.</para> +<para>The filter entry saves the last 10 filters entered between +sessions. To use one of them, press the arrow button on the right of the entry +and select the desired filter string. Refer to this <link linkend="config-dialog-fileselector-filters">section</link> +to change the number of filter entries to remember.</para> +</listitem> +</varlistentry> + +</variablelist> + +<para>The default location of the Filesystem Browser in &kate; is to the left of the +editing area.</para> + +</sect1> + + +<sect1 id="kate-mdi-tools-konsole"> +<title>The Built in Terminal Emulator</title> + +<para><indexterm><primary>Terminal emulator</primary></indexterm> +The built in Terminal Emulator is a copy of the &tde; &konsole; +terminal application, for your convenience. It is available from the +<menuchoice><guimenu>Window</guimenu><guimenuitem>Tool Views</guimenuitem><guimenuitem>Show Terminal</guimenuitem></menuchoice> menu item or by pressing the <guimenu>Terminal</guimenu> +button in the sidebar where the Terminal Emulator is located, and will receive focus +when displayed.</para> +<para>Additionally, if the <link +linkend="config-dialog-general-sync-konsole">Sync terminal emulator with +active document</link> option is enabled, if possible it will +<command>cd</command> into the directory of the current document when it is displayed +or when another document is selected.</para> + +<para>The default location of the Terminal Emulator in &kate; is at the bottom, +below the editing area.</para> + +<para>You can configure the Terminal Emulator using its &RMB; menu. For more +information, see the &konsole; manual.</para> + +</sect1> + +<sect1 id="kate-mdi-tools-find-in-files"> +<title>The Find in Files Panel</title> + +<para><indexterm><primary>The Find in Files Panel</primary></indexterm> +The Find in Files panel in &kate; allows you to search for text in +multiple files at once.</para> +<para>Results of the search will be displayed in the list at the bottom of the +panel, while search errors will be displayed in a separate dialog.</para> + +<para>The panel offers the following options:</para> + +<variablelist> + +<varlistentry> +<term><guilabel>Pattern</guilabel></term> +<listitem><para>The text to look for. The interpretation of the string +depends on some of the options described below.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Case sensitive</guilabel></term> +<listitem> +<para>If enabled, the search will be case sensitive.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Regular expression</guilabel></term> +<listitem> +<para>If checked, the search string will be interpreted as a regular +expression.</para> +<para>See <link linkend="regular-expressions">Regular +Expressions</link> for more on these.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Template</guilabel> (edit field and dropbox)</term> +<listitem> +<para>Here you can specify an additional context string to be used as a wrapper around +the search pattern. Some default templates are available through the dropbox on the right +of the template edit field.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Files</guilabel></term> +<listitem> +<para>The file name pattern used to select which files to search. +It is possible to specify multiple patterns by separating them with commas +(for example *.h, *.cpp).</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Folder</guilabel></term> +<listitem> +<para>The folder to search for files.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Recursive</guilabel></term> +<listitem> +<para>If checked, the search will also recurse in the subfolders of the +specified folder.</para> +</listitem> +</varlistentry> + +</variablelist> + +<para>You can use the <guimenuitem>Find</guimenuitem> button to start the search +and the <guimenuitem>Cancel</guimenuitem> button to interrupt a running search. +</para> +<para>The <guimenuitem>Clear</guimenuitem> button can be used to clear the search +list at the bottom of the panel.</para> + +<para>The default location of the Find in Files panel in &kate; is at the bottom, +below the editing area.</para> + +</sect1> + +<sect1 id="kate-mdi-tools-externaltools"> +<title>External Tools</title> + +<para>In the <guimenu>Tools</guimenu> menu you will find a submenu labeled +<guisubmenu>External Tools</guisubmenu>. These tools invokes external +applications with data related to the current document, for example its URL, +directory, text or selection.</para> + +<para>External tools are user defined, you can add, edit or remove tools using +the <link linkend="config-dialog-externaltools">External Tools configuration panel</link>. +</para> + +</sect1> + +</chapter> diff --git a/doc/kate/menus.docbook b/doc/kate/menus.docbook new file mode 100644 index 000000000..92c91618a --- /dev/null +++ b/doc/kate/menus.docbook @@ -0,0 +1,1438 @@ +<chapter id="menu-entries"> +<chapterinfo> +<authorgroup> +<author><personname><firstname></firstname></personname></author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</chapterinfo> +<title>Menu Entries</title> + +<sect1 id="file-menu"> +<title>The <guimenu>File</guimenu> Menu</title> + +<variablelist> +<varlistentry> +<term> +<anchor id="new"/> +<menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu> +<guimenuitem>New</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +This command <action>starts a new document</action> in the editing +window. In the <guibutton>Documents</guibutton> list on the left the new file +is named <emphasis>Untitled</emphasis>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="open"/> +<menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>O</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu> +<guimenuitem>Open...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Launches &tde;'s open file dialog box to let you open one or more files. +</para> + +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="open-recent"/> +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Open Recent</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +This command allows you to <action>open a file</action> from a submenu +that contains a list of recently edited files. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="open-with"/> +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Open With</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +This submenu presents a list of applications known to handle the mime type +of your current document. Activating an entry will open the current document +with that application.</para> +<para>In addition, a entry <guimenuitem>Other...</guimenuitem> command launches +the open with dialog box that allows you to <action>select another application +to open the active file</action>. Your file will still be open in &kate;. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="save"/> +<menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>S</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu> +<guimenuitem>Save</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +This command <action>saves your file</action>. Use it often. If the file is +<emphasis>Untitled</emphasis> then +<guimenuitem>Save</guimenuitem> becomes +<guimenuitem>Save As</guimenuitem>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="save-as"/> +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Save As...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action>Name and rename files</action> with this command. +It launches the save file dialog box. This dialog works just as +the open file dialog box does. You can use it to navigate through +your file system, preview existing files, or filter your file +view with file masks. +</para> + +<para> +Type the name you want to give the file you are saving in the +Location combo box and press the +<guibutton>OK</guibutton> button. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="save-all"/> +<menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>L</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu> +<guimenuitem>Save All</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +This command <action>saves all modified open files</action>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="reload"/> +<menuchoice> +<shortcut> +<keycombo action="simul"><keycap>F5</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu> +<guimenuitem>Reload</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action>Reloads the active file</action>. This command is +useful if another program or process has changed the file while you have +it open in &kate; +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="print"/> +<menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>P</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu> +<guimenuitem>Print...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action>Print the active file</action>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="export-as-html"> +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Export as HTML...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +Export your file in HTML format so your document can be viewed as a +web page. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="mail"> +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Mail...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +Open your mail client and attach the file in the mail. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="close"/> +<menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>W</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu> +<guimenuitem>Close</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action>Close the active file</action> with this command. If you +have made unsaved changes, you will be prompted to save +the file before &kate; closes it. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="close-all"/> +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Close All</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +This command <action>closes all the files you have open</action> +in &kate;. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="quit"/> +<menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu> +<guimenuitem>Quit</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +This command <action>closes &kate;</action> and any files you were +editing. If you have made unsaved changes to any of the files you were +editing, you will be prompted to save them. +</para> +</listitem> +</varlistentry> +</variablelist> +</sect1> + +<sect1 id="edit-menu"> +<title>The <guimenu>Edit</guimenu> Menu</title> +<para>The <guimenu>Edit</guimenu> menu contains a host of commands, +all to work with the currently active document.</para> + +<variablelist> +<title>Menu Entries</title> +<varlistentry> +<term> +<anchor id="edit-undo"/> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>Z</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Undo</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Undo the last editing command (typing, copying, cutting etc.)</para> +<note><para>If grouped undo is enabled, this may undo several editing commands of the same type, like typing in characters.</para></note> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="edit-redo"/> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;&Shift;<keycap>Z</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Redo</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Redo the last undo step.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="edit-cut"/> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>X</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Cut</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Removes selected text if any, and places a copy of the removed text in the clipboard.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="edit-copy"/> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Copy</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Copies selected text, if any, to the clipboard.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="edit-copy-as-html"/> +<menuchoice> +<guimenu>Edit</guimenu> +<guimenuitem>Copy as HTML</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Copies selected text with the syntax highlight as HTML text.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="edit-paste" /> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>V</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Paste</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Copies the first item in the clipboard into the editor at cursor position.</para> +<note><para>If Overwrite Selection is enabled, the pasted text will overwrite the selection, if any.</para></note> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="edit-select-all"/> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>A</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Select All</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Selects all text in the editor.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="edit-deselect"/> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;&Shift;<keycap>A</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Deselect</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Deselects the selected text in the editor if any.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="edit-toggle-block-selection"/> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>Shift</keycap> +<keycap>B</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Block Selection Mode</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Toggles Selection Mode. When the Selection Mode is <quote>BLOCK</quote>, you can make vertical selections, +ie select column 5 to 10 in lines 9 to 15.</para> +<para>The status bar shows the current state of the Selection Mode, either <quote>NORM</quote> or <quote>BLK</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="edit-find"/> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>F</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Find...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Launch the Find Dialog to allow you to search for text in the edited document.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="edit-find-next"/> +<menuchoice> +<shortcut><keycombo action="simul"><keycap>F3</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Find Next</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Go to the nearest downwards match of the last text or regular expression searched for, starting from cursor position</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="edit-find-previous"/> +<menuchoice> +<shortcut><keycombo action="simul">&Shift;<keycap>F3</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Find Previous</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Go to the nearest upwards match of the last text or regular expression searched for, starting from cursor position</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="edit-replace"/> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>R</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Replace...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Launch the Replace Dialog to replace one or more instances of a defined text with something else.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="edit-go-to-line"/> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>G</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Go to line...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Launches the Go To Line Dialog, allowing you to enter the number of a line to find in +the document</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="document-menu"> +<title>The <guimenu>Document</guimenu> Menu</title> +<para>The Document menu provides a menu entry for each open document. +Clicking one of these will bring the requested document to focus. If you have +multiple frames, an editor for that document will be displayed in the currently +active frame.</para> +<para>In addition, commands to browse your open documents are provided: +<variablelist> +<title>Menu items</title> + +<varlistentry> +<term> +<anchor id="document-back"/> +<menuchoice> +<shortcut><keycombo action="simul">&Alt;<keycap>Left</keycap></keycombo></shortcut> +<guimenu>Document</guimenu> +<guimenuitem>Back</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>This will bring the previous document in the stack in focus. If you have +multiple frames, an editor for the document will be displayed in the currently +active frame.</para> <para>The order is the order in which documents were +opened, rather than a logical history. This behavior may change in future +versions of &kate;.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="document-forward"/> +<menuchoice> +<shortcut><keycombo action="simul">&Alt;<keycap>Right</keycap></keycombo></shortcut> +<guimenu>Document</guimenu> +<guimenuitem>Forward</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>This will bring the next document in the stack in focus. If you have +multiple frames, an editor for the document will be displayed in the currently +active frame.</para> +<para>The order is the order in which the documents were opened, +rather than a logical history. This behavior may change in future versions of +&kate;.</para> +</listitem> +</varlistentry> +</variablelist> +</para> +</sect1> + +<sect1 id="view-menu"> +<title>The <guimenu>View</guimenu> menu</title> + +<para>The <guimenu>View</guimenu> menu allows you to manage settings +specific to the active editor, and to manage frames.</para> + +<variablelist> +<title>Menu Items</title> + +<varlistentry> +<term><menuchoice><shortcut><keycap>F7</keycap></shortcut> +<guimenu>View</guimenu><guimenuitem>Switch to Command Line</guimenuitem> +</menuchoice></term> +<listitem><para>This command will toggle the display of the +<link linkend="advanced-editing-tools-commandline">built in command line</link>. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>View</guimenu><guisubmenu>Schema</guisubmenu> +</menuchoice></term> +<listitem><para>This menu lists the available schemas. You can change the schema +for the current view here, to change the default schema you need to +use the <link linkend="config-dialog-editor-colors">config dialog</link></para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><shortcut><keycombo action="simul"><keycap>F10</keycap> +</keycombo></shortcut> +<guimenu>View</guimenu><guimenuitem>Dynamic Word Wrap</guimenuitem></menuchoice> +</term> +<listitem><para>Toggles dynamic word wrap in the current view. Dynamic word +wrap makes all the text in a view visible without the need for horizontal +scrolling by rendering one actual line on more visual lines as needed.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>View</guimenu><guimenuitem>Show/Hide Static Word +Wrap Marker</guimenuitem></menuchoice></term> +<listitem><para>Toggles the display of a vertical line indicating the position +of the wrap width as configured in the <link +linkend="config-dialog-editor-wrap-words-at">config dialog</link>. This +feature requires that you use a true fixed-width font.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="view-show-icon-border"/> +<menuchoice> +<shortcut><keycombo action="simul"><keycap>F6</keycap></keycombo></shortcut> +<guimenu>View</guimenu> +<guimenuitem>Show/Hide Icon Border</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>This is a toggle item. Setting it on checked will make the Icon Border +visible in the left side of the active editor, and vice versa.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="view-show-line-numbers"/> +<menuchoice> +<shortcut><keycombo action="simul"><keycap>F11</keycap></keycombo></shortcut> +<guimenu>View</guimenu> +<guimenuitem>Show/Hide Line Numbers</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>This is a toggle Item. Setting it on checked will make a pane displaying +the line numbers of the document visible in the left border of the active editor, +and vice versa.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>View</guimenu><guimenuitem>Show/Hide Scrollbar +Marks</guimenuitem></menuchoice></term> +<listitem><para>Toggles the visualization of bookmarks (and other marks) on the +vertical scrollbar. When enabled, marks are represented by a thin line in the +mark color at the scrollbar, middleclicking on the lines will scroll the view +to a position near the mark.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><shortcut><keycombo action="simul"><keycap>F9</keycap> +</keycombo></shortcut> +<guimenu>View</guimenu><guimenuitem>Show/Hide Folding Markers</guimenuitem> +</menuchoice></term> +<listitem><para>Toggles the display of the folding marker pane in the left +side of the view. See <link linkend="advanced-editing-tools-code-folding">Using +Code Folding</link>.</para></listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="view-code-folding"/> +<menuchoice> +<guimenuitem>Code Folding</guimenuitem> +</menuchoice> +</term> + +<listitem> +<variablelist> +<varlistentry> +<term><menuchoice><shortcut><keycombo action="simul">&Ctrl; +<keycap>Shift</keycap><keycap>-</keycap></keycombo></shortcut> +<guimenuitem>Collapse Toplevel</guimenuitem></menuchoice> +</term> +<listitem><para>Collapse all toplevel regions in the document.</para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice><shortcut><keycombo action="simul">&Ctrl; +<keycap>Shift</keycap><keycap>+</keycap></keycombo></shortcut> +<guimenuitem>Expand Toplevel</guimenuitem></menuchoice> +</term> +<listitem><para>Expand all toplevel regions in the document.</para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice><shortcut><keycombo action="simul">&Ctrl; +<keycap>-</keycap></keycombo></shortcut> +<guimenuitem>Collapse One Local Level</guimenuitem></menuchoice> +</term> +<listitem><para>Collapse the region closest to the cursor.</para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice><shortcut><keycombo action="simul">&Ctrl; +<keycap>+</keycap></keycombo></shortcut> +<guimenuitem>Expand One Local Level</guimenuitem></menuchoice> +</term> +<listitem><para>Expand the region closest to the cursor.</para></listitem> +</varlistentry> +</variablelist> +</listitem> + +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="bookmarks-menu"> +<title>The <guimenu>Bookmarks</guimenu> Menu</title> + +<para>The <guimenu>Bookmarks</guimenu> menu allows you to work with +the bookmarks in the currently active document.</para> + +<para>Below the entries described here, one entry for each bookmark in +the active document will be available. The text will be the first few +words of the marked line. Choose an item to move the cursor to the +start of that line. The editor will scroll as necessary to make that +line visible.</para> + +<variablelist> + +<title>Menu Items</title> + +<varlistentry> +<term> +<anchor id="bookmarks-toggle-bookmark"/> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>B</keycap></keycombo></shortcut> +<guimenu>Bookmarks</guimenu> +<guimenuitem>Set/Clear Bookmark</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Sets or removes a bookmark in the current line of the active document. +(If it's there, it is removed, otherwise one is set.)</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="bookmarks-clear-bookmarks"/> +<menuchoice> +<guimenu>Bookmarks</guimenu> +<guimenuitem>Clear All Bookmarks</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Clears (removes) all bookmarks in the active document.</para> +</listitem> +</varlistentry> + +<varlistentry id="bookmarks-previous"> +<term><menuchoice><shortcut><keycombo action="simul">&Alt; +<keycap>Page Up</keycap></keycombo></shortcut> +<guimenu>Bookmarks</guimenu><guimenuitem>Previous</guimenuitem></menuchoice> +</term> +<listitem><para>This will move the cursor to beginning of the first above line +with a bookmark. The menuitem text will include the line number and the first +piece of text on the line. This item is only available when there is a bookmark +in a line above the cursor.</para></listitem> +</varlistentry> + +<varlistentry id="bookmarks-next"> +<term><menuchoice><shortcut><keycombo action="simul">&Alt; +<keycap>Page Down</keycap></keycombo></shortcut> +<guimenu>Bookmarks</guimenu><guimenuitem>Next</guimenuitem></menuchoice></term> +<listitem><para>This will move the cursor to beginning of the next line with a +bookmark. The menuitem text will include the line number and the first piece of +text on the line. This item is only available when there is a bookmark in a line +below the cursor.</para></listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="tools-menu"> + +<title>The <guimenu>Tools</guimenu> Menu</title> + +<variablelist> + +<varlistentry> +<term><menuchoice><guimenu>Tools</guimenu><guimenuitem>Pipe to +Console</guimenuitem></menuchoice></term> +<listitem><para>Feed the currently selected text ito the built in terminal +emulator. No newline is added after the text.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>Tools</guimenu><guisubmenu>External +Tools</guisubmenu></menuchoice></term> +<listitem><para>This submenu contains all the <link +linkend="kate-mdi-tools-externaltools">external tools</link>you have +configured.</para></listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-read-only"/><menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Read Only Mode</guimenuitem></menuchoice></term> +<listitem> +<para>Set the current document to Read Only mode. This prevents any text +addition and any changes in the document formatting.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-filetype"/><menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Filletype</guimenuitem></menuchoice></term> +<listitem> +<para>Choose the filetype scheme you prefer for the active document. This +overwrites the global <link linkend="config-dialog-editor-filetypes">filetype</link> +mode set in <menuchoice> <guimenu>Settings</guimenu> <guimenuitem>Configure +Editor...</guimenuitem></menuchoice> in the Filetypes tab for your current +document only.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-highlighting"/><menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Highlighting</guimenuitem></menuchoice></term> + <listitem> +<para>Choose the Highlighting scheme you prefer for the active document. This +overwrites the global highlighting mode set in <menuchoice> +<guimenu>Settings</guimenu> <guimenuitem>Configure Editor...</guimenuitem> +</menuchoice> for your current document only.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-indentation"/><menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Indentation</guimenuitem></menuchoice></term> +<listitem> +<para>Choose the <link linkend="kate-part-autoindent">style of +indentation</link> you want for your active document. +This overwrites the global indentation mode set in <menuchoice> +<guimenu>Settings</guimenu> <guimenuitem>Configure Editor...</guimenuitem> +</menuchoice> for your current document only.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-encoding"/><menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Encoding</guimenuitem></menuchoice></term> +<listitem> +<para>You can overwrite the default encoding set in <menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure +Editor...</guimenuitem></menuchoice> in the <guilabel>Open/Save</guilabel> tab +to set a different encoding for your current document. The encoding you +set here will be only valid for your current document.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-end-of-line"/><menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>End of Line</guimenuitem></menuchoice></term> +<listitem> +<para>Choose your prefered end of line mode for your active +document. This overwrites the global end of line mode set in <menuchoice> +<guimenu>Settings</guimenu> <guimenuitem>Configure Editor...</guimenuitem> +</menuchoice> for your current document only.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-spelling"/><menuchoice> +<guimenu>Tools</guimenu><guimenuitem>Spelling...</guimenuitem></menuchoice> +</term> + +<listitem><para><action>This initiates the spellchecking program - a program +designed to help the user catch and correct any spelling errors.</action> +Clicking on this entry will start the checker and bring up the speller dialog +box through which the user can control the process. There are four settings +lined up vertically in the center of the dialog with their corresponding labels +just to the left. Starting at the top they are:</para> + +<variablelist> +<varlistentry> +<term><guilabel>Unknown word:</guilabel></term> +<listitem><para>Here, the spellchecker indicates the word currently under +consideration. This happens when the checker encounters a word not in its +dictionary - a file containing a list of correctly spelled words against which +it compares each word in the editor.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Replace with:</guilabel></term> +<listitem><para> If the checker has any similar words in its dictionary the +first one will be listed here. The user can accept the suggestion, type in his +or her own correction, or choose a different suggestion from the next +box.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Suggested Words:</guilabel></term> +<listitem><para> The checker may list here a number of possible replacements for +the word under consideration. Clicking on any one of the suggestions will cause +that word to be entered in the <guilabel>Replacement:</guilabel> box, +above.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Language:</guilabel></term> +<listitem><para> If you have installed multiple dictionaries, here you can +select which dictionary/language should be used.</para></listitem> +</varlistentry> +</variablelist> + +<para>On the right side of the dialog box are 5 buttons that allow the user to +control the spellcheck process. They are:</para> + +<variablelist> +<varlistentry> +<term><guibutton>Add to Dictionary</guibutton></term> +<listitem><para>Pressing this button adds the word in the <guilabel>Misspelled +Word:</guilabel> box to the checker's dictionary. This means that in the future +the checker will always consider this word to be correctly +spelled.</para></listitem> +</varlistentry> +<varlistentry> +<term><guibutton>Replace</guibutton></term> +<listitem><para> This button has the checker replace the word under +consideration in the document with the word in the +<guilabel>Replacement:</guilabel> box.</para></listitem> +</varlistentry> +<varlistentry> +<term><guibutton>Replace All</guibutton></term> +<listitem><para> This button causes the checker to replace not only the current +<guilabel>Unknown word:</guilabel> but to automatically make the same +substitution for any other occurrences of this <guilabel>Misspelled +Word:</guilabel> in the document.</para></listitem> +</varlistentry> +<varlistentry> +<term><guibutton>Ignore</guibutton></term> +<listitem><para>Activating this button will have the checker move on without +making any changes.</para></listitem> +</varlistentry> +<varlistentry> +<term><guibutton>Ignore All</guibutton></term> +<listitem><para> This button tells the checker to do nothing with the current +<guilabel>Unknown word:</guilabel> and to pass over any other instances of +the same word.</para> <note><para>This only applies to the current spellcheck +run. If the checker is run again later it will stop on this same +word.</para></note></listitem> +</varlistentry> +</variablelist> + +<para>Three more buttons are located horizontally along the bottom of the +spellcheck dialog. They are:</para> + +<variablelist> +<varlistentry> +<term><guibutton>Help</guibutton></term> +<listitem><para> This invokes the &tde; help system starting at the &kate; help +pages (this document).</para></listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>Finished</guibutton></term> +<listitem><para> This button ends the spellcheck process, and returns to the +document.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>Cancel</guibutton></term> +<listitem><para> This button cancels the spellcheck process, all modifications +are reverted, and you will return to your document.</para></listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> +</variablelist> + +<variablelist> +<varlistentry> +<term><anchor id="tools-spelling-from-cursor"/><menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Spelling (from cursor)...</guimenuitem></menuchoice></term> + <listitem> +<para>This initiates the spellchecking program but it starts where your cursor +is instead of at the beginning of the document.</para> + </listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-spellcheck-selection"/><menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Spellcheck Selection...</guimenuitem></menuchoice></term> + <listitem> +<para>Spellchecks the current selection.</para> + </listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="indent"/><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>I</keycap></keycombo> +</shortcut> +<guimenu>Tools</guimenu><guimenuitem>Indent</guimenuitem></menuchoice></term> +<listitem> +<para>This increases the paragraph's indentation by one step. The size of the +step depends on the <link linkend="config-dialog-editor-indent">indentation +settings</link>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-unindent"/><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;&Shift;<keycap>I</keycap></keycombo> +</shortcut> +<guimenu>Tools</guimenu><guimenuitem>Unindent</guimenuitem></menuchoice></term> + +<listitem> +<para>This reduces the paragraph's indentation by one step. The size of the step + +depends on the <link linkend="config-dialog-editor-indent">indentation settings</link>.</para> + +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-cleanindent"/><menuchoice> +<guimenu>Tools</guimenu><guimenuitem>Clean +Indentation</guimenuitem></menuchoice></term> <listitem> +<para>This cleans the indentation for the current selection or for the +line the cursor is currently in. Cleaning the indentation ensures that +all your selected text follows the indentation mode you choose.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-align"/><menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Align</guimenuitem> +</menuchoice></term> +<listitem> +<para>Causes a realign of the current line or selected lines using the +indentation mode and indentation settings in the document.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-comment"/><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>D</keycap></keycombo> +</shortcut> +<guimenu>Tools</guimenu> +<guimenuitem>Comment</guimenuitem> +</menuchoice></term> +<listitem><para>This adds one space to the beginning of the line +where the text cursor is located or to the beginning of any +selected lines.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-uncomment"/><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;&Shift;<keycap>D</keycap></keycombo> +</shortcut> +<guimenu>Tools</guimenu> +<guimenuitem>Uncomment</guimenuitem> +</menuchoice></term> +<listitem><para>This removes one space (if any exist) from the beginning of the +line where the text cursor is located or from the beginning of any +selected lines.</para></listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-uppercase"/><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>U</keycap></keycombo> +</shortcut> +<guimenu>Tools</guimenu> +<guimenuitem>Uppercase</guimenuitem> +</menuchoice></term> +<listitem><para>Put the selected text or the letter after the cursor in +uppercase.</para></listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-lowercase"/><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;&Shift;<keycap>U</keycap></keycombo> +</shortcut> +<guimenu>Tools</guimenu> +<guimenuitem>Lowercase</guimenuitem> +</menuchoice></term> +<listitem><para>Put the selected text or the letter after the cursor in +lowercase.</para></listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-capitalize"/><menuchoice> +<shortcut> +<keycombo action="simul">&Alt;&Ctrl;<keycap>U</keycap></keycombo> +</shortcut> +<guimenu>Tools</guimenu> +<guimenuitem>Capitalize</guimenuitem> +</menuchoice></term> +<listitem><para>Capitalize the selected text or the current +word.</para></listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-join-lines"/><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>J</keycap></keycombo> +</shortcut> +<guimenu>Tools</guimenu> +<guimenuitem>Join Lines</guimenuitem> +</menuchoice></term> +<listitem><para>Joins the selected lines, or the current line and the line below +with one white space character as a separator. Leading/trailing white space on +joined lines is removed in the affected ends.</para></listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-word-wrap-document"/><menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Word Wrap Document</guimenuitem> +</menuchoice></term> +<listitem><para>Apply static word wrapping on all the document. That means that +a new line of text will automatically start when the current +line exceeds the length specified by the Wrap words at: option +in the Editing tab in <menuchoice> +<guimenu>Settings</guimenu><guimenuitem>Configure +Editor...</guimenuitem></menuchoice></para></listitem> +</varlistentry> + +</variablelist> + + +</sect1> + +<sect1 id="sessions-menu"> +<title>The <guimenu>Sessions</guimenu> Menu</title> + +<para>This menu contains entries for using and managing &kate; sessions. +For more information, read <link +linkend="fundamentals-using-sessions">Using Sessions</link>.</para> + +<variablelist> + +<varlistentry id="sessions-new"> +<term><menuchoice><guimenu>Sessions</guimenu> +<guimenuitem>New</guimenuitem></menuchoice></term> +<listitem><para>Creates a new empty session. All currently open files will +be closed.</para></listitem> + +</varlistentry> + +<varlistentry id="sessions-open"> +<term><menuchoice><guimenu>Sessions</guimenu><guimenuitem>Open...</guimenuitem> +</menuchoice></term> +<listitem><para>Open an existing session. The Session Chooser dialog is +displayed to let you choose one.</para></listitem> +</varlistentry> + +<varlistentry id="sessions-quick-open"> +<term><menuchoice><guimenu>Sessions</guimenu><guisubmenu>Quick Open</guisubmenu> +</menuchoice></term> +<listitem><para>This submenu lets you open an existing session.</para> +</listitem> +</varlistentry> + +<varlistentry id="sessions-save"> +<term><menuchoice><guimenu>Sessions</guimenu><guimenuitem>Save</guimenuitem> +</menuchoice></term> +<listitem><para>Save the current session. If the session is anonymous, you will +be prompted for a session name.</para></listitem> +</varlistentry> + +<varlistentry id="sessions-save-as"> +<term><menuchoice><guimenu>Sessions</guimenu><guimenuitem>Save +As...</guimenuitem></menuchoice></term> +<listitem><para>Save the current session under a new name. You are prompted for +a name to use.</para></listitem> +</varlistentry> + +<varlistentry id="sessions-manage"> +<term><menuchoice><guimenu>Sessions</guimenu><guimenuitem>Manage...</guimenuitem> +</menuchoice></term> +<listitem><para>Displays the Session Manager dialog which allows you to rename +and delete sessions.</para></listitem> +</varlistentry> + + +</variablelist> + +</sect1> + +<sect1 id="settings-menu"> + +<title>The <guimenu>Settings</guimenu> Menu</title> + +<para>The <guimenu>Settings</guimenu> menu allows you to change the properties +of the main window, such as showing/hiding toolbars, and provides +access to the configuration dialogs.</para> + +<variablelist> + +<varlistentry> +<term> +<anchor id="settings-toolbars"/> +<menuchoice> +<guimenu>Settings</guimenu> +<guisubmenu>Toolbars</guisubmenu> +</menuchoice> +</term> +<listitem> +<para>This submenu lists the available toolbars, each item toggles the display +of the associated toolbar.</para> +</listitem> +</varlistentry> + +<varlistentry id="settings-fullscreen"> +<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Full Screen +Mode</guimenuitem></menuchoice></term> +<listitem><para>Toggles full screen display.</para> +<note><para>This commmand will be moved to the Window menu in a future +version of &kate;</para></note> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="settings-configure-shortcuts"/> +<menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure Shortcuts...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Display the familiar &tde; Keyboard Shortcut Configuration +Dialog.</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term> +<anchor id="settings-configure-toolbars"/> +<menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure Toolbars...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Display the familiar &tde; Toolbar Configuration Dialog.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="settings-configure-kate"/> +<menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure &kate;...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Launch the <link linkend="config-dialog">Main Configuration Dialog</link></para> +</listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="window-menu"> +<title>the <guimenu>Window</guimenu> Menu</title> + +<variablelist> +<varlistentry> +<term> +<anchor id="window-new"/> +<menuchoice> +<guimenu>Window</guimenu> +<guimenuitem>New Window</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action>Opens another instance of &kate;</action>. +The new instance will be identical to your previous instance. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="window-split-vertical"/> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;&Shift;<keycap>L</keycap></keycombo></shortcut> +<guimenu>Window</guimenu> +<guimenuitem>Split Vertical</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>This will split the frame (which may be the main editing area) in two equally sized frames, +the new one to the left of the current one. The new frame gets the focus, and will display the +same document as the old one.</para> +<para>See also <link linkend="kate-mdi">Working with the &kate; MDI</link></para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="window-split-horizontal"/> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;&Shift;<keycap>T</keycap></keycombo></shortcut> +<guimenu>Window</guimenu> +<guimenuitem>Split Horizontal</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Splits the current frame (which may be the main editing area) in two equally sized frames, +the new one at the bottom half. The new frame gets the focus, and displays the same document as +the old one.</para> +<para>See also <link linkend="kate-mdi">Working with the &kate; MDI</link></para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="window-close-current"/> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;&Shift;<keycap>R</keycap></keycombo></shortcut> +<guimenu>Window</guimenu> +<guimenuitem>Close Current</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Closes the active frame. This is disabled, if there is only one frame +(the main editing area).</para> <para>No documents get closed by closing a +frame – they will still be available in the <link +linkend="document-menu"><guimenu>Documents</guimenu> Menu</link> as well as in +the File List.</para> <para>See also <link linkend="kate-mdi">Working with the +&kate; MDI</link></para> +</listitem> +</varlistentry> + +<varlistentry id="window-next-view"> +<term><menuchoice><shortcut><keycombo action="simul"><keycap>F8</keycap> +</keycombo></shortcut><guimenu>Window</guimenu><guimenuitem>Next +View</guimenuitem></menuchoice></term> +<listitem><para>Focus the next document view, if you have split the editor area +in more views.</para></listitem> +</varlistentry> + +<varlistentry id="window-previous-view"> +<term><menuchoice><shortcut><keycombo action="simul">&Shift;<keycap>F8</keycap> +</keycombo></shortcut><guimenu>Window</guimenu><guimenuitem>Previous +View</guimenuitem></menuchoice></term> +<listitem><para>Focus the previous document view, if you have split the editor +area in more views.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>Window</guimenu><guisubmenu>Tool Views</guisubmenu> +</menuchoice></term> +<listitem> +<variablelist> +<varlistentry> +<term><anchor id="window-toolviews-show-sidebars"/> +<menuchoice><guimenu>Window</guimenu><guisubmenu>Tool Views</guisubmenu> +<guimenuitem>Show/Hide Sidebars</guimenuitem></menuchoice></term> +<listitem><para>Toggles the display of the sidebar button rows. This command +does not affect the display of the sidebar content widgets, any sidebar that +is visible will stay visible, and if you assigned shortcuts to the below +commands those will of course continue to work.</para></listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="window-toolviews-show-filelist"/> +<menuchoice> +<guimenu>Window</guimenu><guisubmenu>Tool Views</guisubmenu> +<guimenuitem>Show Documents</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Toggle the display of &kate;'s Documents list</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="window-toolviews-show-fileselector"/> +<menuchoice> +<guimenu>Window</guimenu><guisubmenu>Tool Views</guisubmenu> +<guimenuitem>Show/Hide Filesystem Browser</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Toggle the display of &kate;'s Filesystem Browser</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="window-toolviews-greptool"/> +<menuchoice> +<guimenu>Window</guimenu><guisubmenu>Tool Views</guisubmenu> +<guimenuitem>Show/Hide Find in Files</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Toggle the display of &kate;'s <guilabel>Find in Files</guilabel> tool. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="window-toolviews-show-konsole"/> +<menuchoice> +<guimenu>Window</guimenu><guisubmenu>Tool Views</guisubmenu> +<guimenuitem>Show/Hide Terminal</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Toggles the display of the built in terminal emulator.</para> +<para>When activated the first time, the terminal will be created.</para> +<para>When the terminal emulator is displayed, it will get the focus, so that +you can start typing in commands immediately. If the <link +linkend="config-dialog-general-sync-konsole">Sync Konsole with Active +Document</link> option is enabled in the <link +linkend="config-dialog-general">General Page</link> of the <link +linkend="config-dialog">Main configuration dialog</link> the shell session will +change to the directory of the active document, if it is a local file.</para> +</listitem> +</varlistentry> + +</variablelist> + +</listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="help-menu"> + +<title>The <guimenu>Help</guimenu> Menu</title> + +<para>Apart from standard &tde; <guimenu>Help</guimenu> menu items +described below you will have menu entries to show the +Plugins User Manuals for installed plugins.</para> + +&help.menu.documentation; + +</sect1> + +</chapter> diff --git a/doc/kate/mimetypechooser.png b/doc/kate/mimetypechooser.png Binary files differnew file mode 100644 index 000000000..45220f8a4 --- /dev/null +++ b/doc/kate/mimetypechooser.png diff --git a/doc/kate/part.docbook b/doc/kate/part.docbook new file mode 100644 index 000000000..ad74be9c7 --- /dev/null +++ b/doc/kate/part.docbook @@ -0,0 +1,711 @@ +<chapter id="kate-part"> +<chapterinfo> +<authorgroup> +<author>&Anders.Lund; &Anders.Lund.mail;</author> +<author>&tde-authors;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +</chapterinfo> +<title>Working with the &kate; editor</title> + +<sect1 id="kate-part-overview"> + +<title>Overview</title> + +<para>The &kate; editor is the editing area of the &kate; window. This +editor is also used by &kwrite;, and it can be used in &konqueror; for +displaying text files from your local computer, or from the +network.</para> + +<para>The editor is composed of the following components:</para> + +<variablelist> + +<varlistentry> +<term>The editing area</term> +<listitem><para>This is where the text of your document is located.</para></listitem> +</varlistentry> + +<varlistentry> +<term>The Scroll bars</term> +<listitem> +<para>The scroll bars indicate the position of the visible part of +the document text, and can be used to move around the +document. Dragging the scrollbars will not cause the insertion cursor +to be moved.</para> +<para>The scroll bars are displayed and hidden as required.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>The Icon Border</term> +<listitem> +<para>The icon border is a small pane on the left side of the editor, +displaying a small icon next to marked lines.</para> +<para>You can set or remove a <link +linkend="kate-part-bookmarks">bookmark</link> in a visible line by +clicking the &LMB; in the icon border next to that line.</para> +<para>The display of the icon border can be toggled using the +<menuchoice><guimenu>View</guimenu> <guimenuitem>Show/Hide Icon +Border</guimenuitem></menuchoice> menu item.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>The Line Numbers Pane</term> +<listitem> +<para>The Line Numbers Pane shows the line number of all visible +lines in the document.</para> +<para>The display of the Line Numbers Pane can be toggled using the +<menuchoice><guimenu>View</guimenu> <guimenuitem>Show/Hide Line +Numbers</guimenuitem></menuchoice> menu item.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>The Folding Pane</term> +<listitem> +<para>The folding pane allows you to collapse or expand foldable blocks +of lines. The calculation of the foldable regions are done according to +rules in the syntax highlight definition for the document.</para> +</listitem> +</varlistentry> + +</variablelist> + +<itemizedlist> +<title>Also in this Chapter:</title> +<listitem><para><link linkend="kate-part-navigation">Navigating in the +Text</link> </para></listitem> +<listitem><para><link linkend="kate-part-selection">Working with the +Selection</link></para></listitem> +<listitem><para><link linkend="kate-part-copy-and-paste">Copying and +Pasting Text</link></para></listitem> +<listitem><para><link linkend="kate-part-find-replace">Finding and +Replacing Text</link></para></listitem> +<listitem><para><link linkend="kate-part-bookmarks">Using +Bookmarks</link></para></listitem> +<listitem><para><link linkend="kate-part-auto-wrap">Automatically +Wrapping Text</link></para></listitem> +<listitem><para><link linkend="kate-part-autoindent">Using automatic indenting</link></para></listitem> +</itemizedlist> + +</sect1> + +<sect1 id="kate-part-navigation"> +<title>Navigating in the Text</title> + +<para>Moving around the text in &kate; is like in most graphical text +editors. You move the cursor using the <keycap>arrow keys</keycap> and the +<keycap>Page Up</keycap>, <keycap>Page Down</keycap>, <keycap>Home</keycap> and +<keycap>End</keycap> keys in combination with the <keycap>Ctrl</keycap> and +<keycap>Shift</keycap> modifiers. The <keycap>Shift</keycap> key is always used +to generate a selection, while the <keycap>Ctrl</keycap> key have different +effects on different keys: +<itemizedlist> +<listitem><para>For the <keycap>Up</keycap> and <keycap>Down</keycap> keys it +means scroll rather than move the cursor.</para></listitem> +<listitem><para>For the <keycap>Left</keycap> and <keycap>Right</keycap> +keys it means skip words rather than characters.</para></listitem> +<listitem><para>for the <keycap>Page Up</keycap> and <keycap>Page Down</keycap> +keys it means move to the visible edge of the view rather than browse.</para> +</listitem> +<listitem><para>For the <keycap>Home</keycap> and <keycap>End</keycap> keys it +means move to the beginning or end of the document rather than the beginning or +end of the line.</para></listitem> +</itemizedlist> +</para> + +<para>&kate; also provides you with a way to quickly jump to a matching brace +or paranthesis. Place the cursor on the inside of a parenthesis or brace +character, and press <keycombo><keycap>Ctrl</keycap><keycap>6</keycap></keycombo> +to jump to the matching parenthesis or brace.</para> + +<para>In addition you can use +<link linkend="kate-part-bookmarks">bookmarks</link> to quickly jump to +positions that you define on your own.</para> + +</sect1> + +<sect1 id="kate-part-selection"> +<title>Working with the Selection</title> + +<para>There are two basic ways of selecting text in &kate;: using the +mouse and using the keyboard.</para> + +<para>To select text using the mouse, hold down the &LMB; while dragging +the mouse cursor from the point where the selection should start to the desired +end point. The text gets selected as you drag.</para> + +<para>Double-clicking a word will select that word.</para> + +<para>Triple-clicking in a line will select the entire line.</para> + +<para>If &Shift; is held down while clicking, text will be +selected as follow:</para> + +<itemizedlist> +<listitem><para>If nothing is already selected, from the text cursor +position to the mouse cursor position.</para></listitem> +<listitem><para>If there is already a selection, from the selection start point +to the mouse cursor position.</para></listitem> +</itemizedlist> + +<note> +<para>When selecting text by dragging the mouse, the +selected text is copied to the clipboard and can be pasted by +clicking the middle mouse button in the editor, or in any other +application to which you want to paste the text. +</para> +</note> + +<para>To select text using the keyboard, hold down the &Shift; key while +using the navigation keys (the <keycap>arrow keys</keycap>, <keycap>Page Up</keycap>, +<keycap>Page Down</keycap>, <keycap>Home</keycap> and +<keycap>End</keycap>, possibly in combination with &Ctrl; to extend +the move of the text cursor).</para> + +<para>See also the section <link +linkend="kate-part-navigation">Navigating in the Text</link> in this +chapter.</para> + +<para>To <action>copy</action> the current selection, use the +<menuchoice><guimenu>Edit</guimenu> +<guimenuitem>Copy</guimenuitem></menuchoice> menu item or the keyboard +shortcut (defaults to <keycombo +action="simul">&Ctrl;<keycap>C</keycap></keycombo>).</para> + +<para>To <action>deselect</action> the current selection, use the +<menuchoice><guimenu>Edit</guimenu> +<guimenuitem>Deselect</guimenuitem></menuchoice> menu item, or the +keyboard shortcut (default is <keycombo +action="simul">&Ctrl;&Shift;<keycap>A</keycap></keycombo>), or click +with the &LMB; in the editor.</para> + +<sect2 id="kate-part-selection-block"> +<title>Using Block Selection</title> + +<para>When the Block Selection Mode is enabled, you can make <quote>vertical +selections</quote> in the text, meaning selecting limited columns from +multiple lines. This is handy for working with tab separated lines for +example.</para> + +<para>Block Selection Mode can be toggled using the +<menuchoice><guimenu>Edit</guimenu> +<guimenuitem>Block Selection Mode</guimenuitem></menuchoice> menu item. The default keyboard +shortcut is <keycombo action="simul">&Ctrl;&Shift;<keycap>B</keycap></keycombo>.</para> + +</sect2> + +<sect2 id="kate-part-seleciton-overwrite"> + +<title>Using Normal Selection Mode</title> + +<para>If Normal Selection Mode is enabled, typing or pasting text into +the selection will cause the selected text to be replaced. If not +enabled, new text will be added at the position of the text +cursor.</para> + +<para>Normal Selection Mode is enabled by default.</para> + +<para>To change the setting for this option, use the <link +linkend="config-dialog-editor-selection-mode">Cursor & Selection page</link> of the <link +linkend="config-dialog">configuration dialog</link>.</para> + +</sect2> + +<sect2 id="kate-part-selection-persistent"> + +<title>Using Persistent Selection Mode</title> + +<para>When Persistent Selection Mode is enabled, typing characters or +moving the cursor will not cause the selection to become +deselected. This means that you can move the cursor away from the +selection and type text.</para> + +<para>Persistent Selection Mode is disabled by default.</para> + +<para>Persistent Selection Mode can be enabled in the <link +linkend="config-dialog-editor-selection-mode">Cursor & Selection page</link> of the <link +linkend="config-dialog">configuration dialog</link>.</para> + +</sect2> + +</sect1> + +<sect1 id="kate-part-copy-and-paste"> + +<title>Copying and Pasting Text</title> + +<para>To copy text, select it and use the +<menuchoice><guimenu>Edit</guimenu> +<guimenuitem>Copy</guimenuitem></menuchoice> menu item. Additionally, +selecting text with the mouse will cause selected text to be copied to +the clipboard.</para> + +<para>To paste the text currently in the clipboard, use the +<menuchoice> +<guimenu>Edit</guimenu><guimenuitem>Paste</guimenuitem></menuchoice> +menu item.</para> + +<para>Additionally, text selected with the mouse may be pasted by +clicking the <mousebutton>middle</mousebutton> mouse button at the +desired position.</para> + +<tip> +<para>You can also retrieve earlier copied text from any application using +the &klipper; icon in the &kicker; icon tray.</para> +</tip> + +</sect1> + +<sect1 id="kate-part-find-replace"> +<title>Finding and Replacing Text</title> + +<sect2 id="find-replace-dialog"> +<title>The <guilabel>Find Text</guilabel> and <guilabel>Replace +Text</guilabel> Dialogs</title> + + +<para>The Find and Replace Text dialogs in &kate; are very much the +same, except the Replace Text dialog offers the means of entering a +replacement string along with a few extra options.</para> + +<para>The dialogs offer the following common options:</para> + +<variablelist> + +<varlistentry> +<term><guilabel>Text to Find</guilabel></term> +<listitem><para>This is where to enter the search string. The interpretation of the string +depends on some of the options described below.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Regular expression</guilabel></term> +<listitem> +<para>If checked, the search string is interpreted as a regular +expression. A button for using a graphical tool to create or edit the +expression will be enabled.</para> +<para>See <link linkend="regular-expressions">Regular +Expressions</link> for more on these.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Case sensitive</guilabel></term> +<listitem> +<para>If enabled, the search will be case sensitive.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Whole words only</guilabel></term> +<listitem> +<para>If checked, the search will only match if there is a word +boundary at both ends of the string matching, meaning neither an +alphanumeric character, nor some other visible characters, nor a line +end.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>From cursor</guilabel></term> +<listitem> +<para>If checked, the search will start at the current cursor position, +otherwise it will start at the beginning of the document.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Find backwards</guilabel></term> +<listitem> +<para>If checked, the search will look for the first match above the +starting point, either the cursor position or the beginning of the +document depending on the status of the <guilabel>From cursor</guilabel> option.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Selected text</guilabel></term> +<listitem> +<para>This option is not available if no text is selected. +If some text has been selected and the option is checked, the +search string will be matched only against the selected text.</para> +</listitem> +</varlistentry> + +</variablelist> + +<para>The <guilabel>Replace Text</guilabel> dialog offers some +additional options:</para> + +<variablelist> + +<varlistentry> +<term><guilabel>Replace With</guilabel></term> +<listitem> +<para>This is where to enter the replacement string.</para> +</listitem> +</varlistentry> + +<varlistentry id="replace-use-placeholders"> +<term><guilabel>Use placeholders</guilabel></term> +<listitem> +<para>If enabled, any occurrence of <keycap>\N</keycap> where +<keycap>N</keycap> is an integer number, will be replaced +with the corresponding string capture (parenthesized substring) +from the search pattern. A button for listing all available string captures +will also be enabled. You can click on any of the available string captures +to include them in your replacement string.</para> +<note><para>Placeholders can only be used when searching using regular expressions.</para></note> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Prompt on replace</guilabel></term> +<listitem><para>If checked, a small dialog will prompt you for what to +do for each time a match is found. It offers the following options: +<variablelist> + +<varlistentry> +<term><guibutton>Replace</guibutton></term> +<listitem><para>Use this button to replace the current match, which is +selected in the editor. After the replacement, search for the next match +automatically.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>Replace & Close</guibutton></term> +<listitem><para>Use this button to replace the current match, which is +selected in the editor. After the replacement, close the dialog.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>Replace All</guibutton></term> +<listitem><para>Use this button to replace all matches without further prompt.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>Find next</guibutton></term> +<listitem><para>Use this button to skip replacing the current match and try to find the next one.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>Close</guibutton></term> +<listitem><para>Use this button to skip replacing the current match and close the dialog.</para></listitem> +</varlistentry> + +</variablelist> + +</para></listitem> +</varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="finding-text"> +<title>Finding Text</title> + +<para>To find text, launch the <guilabel>Find Text</guilabel> dialog +with <keycombo action="simul">&Ctrl;<keycap>F</keycap></keycombo> or +from the <menuchoice><guimenu>Edit</guimenu> +<guimenuitem>Find...</guimenuitem></menuchoice> menu item, enter a +search string, set the <link linkend="find-replace-dialog">options</link> as desired and hit the +<guibutton>Find</guibutton> button.</para> + +<para>If a match is found it is selected and the <guilabel>Find +Text</guilabel> dialog is hidden. Finding further +matches is very easy.</para> + +<para>To find the next match in the search direction, use the +<menuchoice><guimenu>Edit</guimenu> <guimenuitem>Find +Next</guimenuitem></menuchoice> command or press +<keycap>F3</keycap>.</para> + +<para>To find the next match in the opposite direction, use the +<menuchoice><guimenu>Edit</guimenu> <guimenuitem>Find +Previous</guimenuitem></menuchoice> command or press <keycombo +action="simul">&Shift;<keycap>F3</keycap></keycombo>.</para> + +<para>If no match is found before reaching the document end (or beginning if you +are searching backward), you will be asked if you want to continue the search +from the other end of the document.</para> + +</sect2> + +<sect2> +<title>Replacing Text</title> + +<para>To replace text, launch the <guilabel>Replace Text</guilabel> +dialog using the <menuchoice><guimenu>Edit</guimenu> +<guimenuitem>Replace...</guimenuitem></menuchoice> command or the +<keycombo action="simul">&Ctrl;<keycap>R</keycap></keycombo> shortcut, +enter a search string and optionally a replace string, set +the <link linkend="find-replace-dialog">options</link> as desired and +hit the <guibutton>Replace</guibutton> button. If the replace +string is empty, each match will be removed.</para> + +<tip> +<para>If you are using a regular expression to find the text to replace, you can +employ <link linkend="replace-use-placeholders">placeholders</link> to reuse text +captured in parenthesized subpatterns of the expression.</para> +</tip> + +<tip><para>You can do <command>find</command>, <command>replace</command> and +<command>ifind</command> (incremental search) from the editor +<link linkend="advanced-editing-tools-commandline">command line</link>.</para> +</tip> + +</sect2> + +<sect2> +<title>Finding text in multiple files</title> +<para>To search for text in multiple files at once, please refer to the +<link linkend="kate-mdi-tools-find-in-files">Find in Files Panel</link> section.</para> +</sect2> + +</sect1> + +<sect1 id="kate-part-bookmarks"> +<title>Using Bookmarks</title> + +<para>The bookmarks feature allows you to mark certain lines, to be +able to easily find them again.</para> + +<para>You can set or remove a bookmark in a line in two ways:</para> + +<itemizedlist> +<listitem> +<para>Move the insertion cursor to the line and activate the +<menuchoice><guimenu>Bookmarks</guimenu><guimenuitem>Set +Bookmark</guimenuitem></menuchoice> (<keycombo +action="simul">&Ctrl;<keycap>B</keycap></keycombo>) command.</para> +</listitem> +<listitem> +<para>Click on the Icon Border Pane next to the line.</para> +</listitem> +</itemizedlist> + + +<para>Bookmarks are available in the <guimenu>Bookmarks</guimenu> +menu. The individual bookmarks are available as menu items, labeled +with the line number of the line with the bookmark, and the first few +characters of the text in the line. To move the insertion cursor to +the beginning of a bookmarked line, open the menu and select the +bookmark.</para> + +<para>To quickly move between bookmarks or to the next/previous bookmark, +use the <menuchoice><guimenu>Bookmarks</guimenu><guimenuitem>Next</guimenuitem> +</menuchoice> (<keycombo action="simul"><keycap>Alt</keycap> +<keycap>Page Down</keycap></keycombo>) or <menuchoice> +<guimenu>Bookmarks</guimenu><guimenuitem>Previous</guimenuitem></menuchoice> +(<keycombo action="simul"><keycap>Alt</keycap><keycap>Page Up</keycap> +</keycombo>) commands.</para> + +<para>To remove a single bookmark, move the insertion cursor to the line +of that bookmark and activate the <menuchoice><guimenu>Bookmarks</guimenu> +<guimenuitem>Clear Bookmark</guimenuitem></menuchoice> (<keycombo +action="simul">&Ctrl;<keycap>B</keycap></keycombo>) command.</para> + +<para>To remove all bookmarks at once, use the <menuchoice><guimenu>Bookmarks</guimenu> +<guimenuitem>Clear All Bookmarks</guimenuitem></menuchoice> menu entry.</para> + +</sect1> + +<sect1 id="kate-part-auto-wrap"> + +<title>Wrapping text</title> + +<para>There are two types of text wrapping: +<itemizedlist> +<listitem> +<para><link linkend="static-word-wrapping">Static word wrapping</link></para> +</listitem> + +<listitem> +<para><link linkend="dynamic-word-wrapping">Dynamic word wrapping</link></para> +</listitem> +</itemizedlist> +</para> + +<sect2 id="static-word-wrapping"> +<title>Static word wrapping</title> + +<para>This feature allows you to have the text formatted in a very simple way: the text will be wrapped, +so that no lines exceed a maximum number of characters per line, unless there is a longer string of +non-whitespace characters.</para> + +<para>To enable/disable it, check/uncheck the +<link linkend="config-dialog-editor-enable-static-word-wrap">Enable static word wrap</link> checkbox in the +<link linkend="config-dialog-editor-edit">Editing page</link> of the <link linkend="config-dialog">configuration dialog</link>.</para> + +<para>To set the maximum line length (maximum characters per line), use the +<link linkend="config-dialog-editor-wrap-words-at">Wrap words at</link> option in the +<link linkend="config-dialog-editor-edit">Editing page</link> of the +<link linkend="config-dialog">configuration dialog</link>.</para> + +<para>If enabled, static word wrapping has the following effects: + +<itemizedlist> +<listitem><para>While typing, the editor will automatically insert a hard line break after +the last whitespace character at a position before the maximum line width is reached.</para></listitem> +<listitem><para>While loading a document, the editor will wrap the text in a similar way so that +no lines will be longer than the maximum line length, if they contain any whitespace allowing that.</para></listitem> +</itemizedlist> + +</para> + +</sect2> + +<sect2 id="dynamic-word-wrapping"> +<title>Dynamic word wrapping</title> + +<para>This feature allows the text lines to be wrapped at the view border of the screen. +The wrapping only affects the view, no hard line break character is inserted in the text.</para> + +<para>To enable/disable it, check/uncheck the +<link linkend="appearance-settings">Dynamic word wrap</link> checkbox in the +<link linkend="config-dialog-editor-appearance">Appearance page</link> of the +<link linkend="config-dialog">configuration dialog</link>.</para> +</sect2> + +</sect1> + +<sect1 id="kate-part-autoindent"> +<title>Using automatic indentation</title> + +<para>The &kate; editor component supports several autoindenting modes, +designed for different text formats. You can pick from the available modes using +the <menuchoice><guimenu>Tools</guimenu><guisubmenu>Indentation</guisubmenu></menuchoice> +menu. The autoindent modules also provides a function +<menuchoice><guimenu>Tools</guimenu><guimenuitem>Align</guimenuitem></menuchoice> +which will recalculate the indentation of the selected or current line. Thus, +you may reindent your entire document by selecting all the text and activating +that action.</para> + +<para>All the indent modes use the indentation related settings in the active +document.</para> + +<tip><para>You can set all sorts of configuration variables, including +those related to indentation using <link linkend="config-variables">Document +Variables</link> and <link linkend="config-dialog-editor-filetypes">File +types</link>.</para></tip> + +<variablelist> + +<title>Available Autoindent Modes</title> + +<varlistentry> +<term>None</term> +<listitem><para>Selecting this mode turns automatic indentation off entirely.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Normal</term> +<listitem><para>This indenter simply keeps the indentation similar to the +previous line with any content other than whitespace. You can combine this +with using the indent and unindent actions for indenting to your own taste. +</para></listitem> +</varlistentry> + +<varlistentry><term>C Style</term> +<listitem><para>An indenter for C and similar languages, such as +C++, C#, java, javascript and so on. This indenter will not work with scripting +languages such as Perl or PHP.</para></listitem> +</varlistentry> + +<varlistentry> +<term>Python Style</term> +<listitem><para>An indenter specifically designed for the python scripting language. +</para></listitem> +</varlistentry> + +<varlistentry> +<term>XML</term> +<listitem><para>A very nice XML auto-indenter. However tempting, do not try to +use this with HTML other than XHTML, because it fails with the old style +HTML tags (open tags like for example <br>)</para></listitem> +</varlistentry> + +<varlistentry> +<term>S&S C Style</term> +<listitem><para>An alternative indenter for C and similar languages, with the +same constraints.</para></listitem> +</varlistentry> + +<varlistentry> +<term>Variable Based Indenter</term> +<listitem><para> +The variable based indenter is special in that it can be configured using variables in +the document or in a filetype configuration. The following variables are +read: + +<variablelist> +<varlistentry> +<term>var-indent-indent-after</term> +<listitem> +<para>A regular expression which will cause a line to +be indented by one unit, if the first non-whitespace-only line above matches.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>var-indent-indent</term> +<listitem> +<para>A regular expression, which will cause a matching line +to be indented by one unit if matching.</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term>var-indent-unindent</term> +<listitem> +<para>A regular expression which will cause the line to be +unindented by one unit if matching.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>var-indent-triggerchars</term> +<listitem> +<para>A list of characters that should cause the +indention to be recalculated immediately when typed.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>var-indent-handle-couples</term> +<listitem> +<para>A list of paranthesis sets to handle. Any combination +of 'paranthesis', 'braces' and 'brackets'. Each set type is handled in +the following way. If there are unmatched opening instances on the above line, +one indent unit is added. If there are unmatched closing instances on the +current line, one indent unit is removed.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><literal>var-indent-couple-attribute</literal></term> +<listitem> +<para>When looking for unmatched couple openings/closings, +only characters with this attribute are considered. The value must be the +attribute name from the syntax xml file, for example "Symbol". If it is not +specified, attribute 0 is used (usually 'Normal Text').</para> +</listitem> +</varlistentry> + +</variablelist> + +</para></listitem> +</varlistentry> + +</variablelist> + +</sect1> + +</chapter> diff --git a/doc/kate/plugins.docbook b/doc/kate/plugins.docbook new file mode 100644 index 000000000..48c164de2 --- /dev/null +++ b/doc/kate/plugins.docbook @@ -0,0 +1,34 @@ +<chapter id="plugins"> + +<chapterinfo> +<authorgroup> +<author>&Anders.Lund; &Anders.Lund.mail;</author> +<author>&tde-authors;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</chapterinfo> + +<title>Working with Plugins</title> + +<para>Kate is using two different forms of plugins, namely plugins for the +&kate; application and plugins for the &kate; editor component. The latter are +available to any application using the editor component, such as KDevelop, +Quanta, Kile, KWrite and many others, while application plugins are specific +to the &kate; application.</para> + +<para>You can enable both types of plugins in the <link +linkend="configuring-kate-configdialog">configuration dialog</link>, which also +provides access to additional configuration options for plugins that requires +that.</para> + +<para>There are many plugins for various purposes available in the <emphasis>tdeaddons</emphasis> +module, and you can search the web for more. A few plugins are shipped with the +editor component, for doing word completion, insert files, +thesaurus and word spell checking and incremental search.</para> + +<para>You can find additional information about some of &kate;'s plugins in +<emphasis>The Kate Plugins Handbook</emphasis> accessible from +<menuchoice><guimenu>Help</guimenu><guimenuitem>Plugins Handbook</guimenuitem></menuchoice> +if the <emphasis>tdeaddons</emphasis> module has been installed on your system</para> + +</chapter> diff --git a/doc/kate/regular-expressions.docbook b/doc/kate/regular-expressions.docbook new file mode 100644 index 000000000..c15685d75 --- /dev/null +++ b/doc/kate/regular-expressions.docbook @@ -0,0 +1,664 @@ +<appendix id="regular-expressions"> +<appendixinfo> +<authorgroup> +<author>&Anders.Lund; &Anders.Lund.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</appendixinfo> + +<title>Regular Expressions</title> + +<synopsis> This Appendix contains a brief but hopefully sufficient and +covering introduction to the world of <emphasis>regular +expressions</emphasis>. It documents regular expressions in the form +available within &kate;, which is not compatible with the regular +expressions of perl, nor with those of for example +<command>grep</command>.</synopsis> + +<sect1> + +<title>Introduction</title> + +<para><emphasis>Regular Expressions</emphasis> provides us with a way +to describe some possible contents of a text string in a way +understood by a small piece of software, so that it can investigate if +a text matches, and also in the case of advanced applications with the +means of saving pieces or the matching text.</para> + +<para>An example: Say you want to search a text for paragraphs that +starts with either of the names <quote>Henrik</quote> or +<quote>Pernille</quote> followed by some form of the verb +<quote>say</quote>.</para> + +<para>With a normal search, you would start out searching for the +first name, <quote>Henrik</quote> maybe followed by <quote>sa</quote> +like this: <userinput>Henrik sa</userinput>, and while looking for +matches, you would have to discard those not being the beginning of a +paragraph, as well as those in which the word starting with the +letters <quote>sa</quote> was not either <quote>says</quote>, +<quote>said</quote> or so. And then of cause repeat all of that with +the next name...</para> + +<para>With Regular Expressions, that task could be accomplished with a +single search, and with a larger degree of preciseness.</para> + +<para>To achieve this, Regular Expressions defines rules for +expressing in details a generalization of a string to match. Our +example, which we might literally express like this: <quote>A line +starting with either <quote>Henrik</quote> or <quote>Pernille</quote> +(possibly following up to 4 blanks or tab characters) followed by a +whitespace followed by <quote>sa</quote> and then either +<quote>ys</quote> or <quote>id</quote></quote> could be expressed with +the following regular expression:</para> <para><userinput>^[ +\t]{0,4}(Henrik|Pernille) sa(ys|id)</userinput></para> + +<para>The above example demonstrates all four major concepts of modern +Regular Expressions, namely:</para> + +<itemizedlist> +<listitem><para>Patterns</para></listitem> +<listitem><para>Assertions</para></listitem> +<listitem><para>Quantifiers</para></listitem> +<listitem><para>Back references</para></listitem> +</itemizedlist> + +<para>The caret (<literal>^</literal>) starting the expression is an +assertion, being true only if the following matching string is at the +start of a line.</para> + +<para>The stings <literal>[ \t]</literal> and +<literal>(Henrik|Pernille) sa(ys|id)</literal> are patterns. The first +one is a <emphasis>character class</emphasis> that matches either a +blank or a (horizontal) tab character; the other pattern contains +first a subpattern matching either <literal>Henrik</literal> +<emphasis>or</emphasis> <literal>Pernille</literal>, then a piece +matching the exact string <literal> sa</literal> and finally a +subpattern matching either <literal>ys</literal> +<emphasis>or</emphasis> <literal>id</literal></para> + +<para>The string <literal>{0,4}</literal> is a quantifier saying +<quote>anywhere from 0 up to 4 of the previous</quote>.</para> + +<para>Because regular expression software supporting the concept of +<emphasis>back references</emphasis> saves the entire matching part of +the string as well as sub-patterns enclosed in parentheses, given some +means of access to those references, we could get our hands on either +the whole match (when searching a text document in an editor with a +regular expression, that is often marked as selected) or either the +name found, or the last part of the verb.</para> + +<para>All together, the expression will match where we wanted it to, +and only there.</para> + +<para>The following sections will describe in details how to construct +and use patterns, character classes, assertions, quantifiers and +back references, and the final section will give a few useful +examples.</para> + +</sect1> + +<sect1 id="regex-patterns"> + +<title>Patterns</title> + +<para>Patterns consists of literal strings and character +classes. Patterns may contain sub-patterns, which are patterns enclosed +in parentheses.</para> + +<sect2> +<title>Escaping characters</title> + +<para>In patterns as well as in character classes, some characters +have a special meaning. To literally match any of those characters, +they must be marked or <emphasis>escaped</emphasis> to let the regular +expression software know that it should interpret such characters in +their literal meaning.</para> + +<para>This is done by prepending the character with a backslash +(<literal>\</literal>).</para> + + +<para>The regular expression software will silently ignore escaping a +character that does not have any special meaning in the context, so +escaping for example a <quote>j</quote> (<userinput>\j</userinput>) is +safe. If you are in doubt whether a character could have a special +meaning, you can therefore escape it safely.</para> + +<para>Escaping of cause includes the backslash character it self, to +literally match a such, you would write +<userinput>\\</userinput>.</para> + +</sect2> + +<sect2> +<title>Character Classes and abbreviations</title> + +<para>A <emphasis>character class</emphasis> is an expression that +matches one of a defined set of characters. In Regular Expressions, +character classes are defined by putting the legal characters for the +class in square brackets, <literal>[]</literal>, or by using one of +the abbreviated classes described below.</para> + +<para>Simple character classes just contains one or more literal +characters, for example <userinput>[abc]</userinput> (matching either +of the letters <quote>a</quote>, <quote>b</quote> or <quote>c</quote>) +or <userinput>[0123456789]</userinput> (matching any digit).</para> + +<para>Because letters and digits have a logical order, you can +abbreviate those by specifying ranges of them: +<userinput>[a-c]</userinput> is equal to <userinput>[abc]</userinput> +and <userinput>[0-9]</userinput> is equal to +<userinput>[0123456789]</userinput>. Combining these constructs, for +example <userinput>[a-fynot1-38]</userinput> is completely legal (the +last one would match, of cause, either of +<quote>a</quote>,<quote>b</quote>,<quote>c</quote>,<quote>d</quote>, +<quote>e</quote>,<quote>f</quote>,<quote>y</quote>,<quote>n</quote>,<quote>o</quote>,<quote>t</quote>, +<quote>1</quote>,<quote>2</quote>,<quote>3</quote> or +<quote>8</quote>).</para> + +<para>As capital letters are different characters from their +non-capital equivalents, to create a caseless character class matching +<quote>a</quote> or <quote>b</quote>, in any case, you need to write it +<userinput>[aAbB]</userinput>.</para> + +<para>It is of cause possible to create a <quote>negative</quote> +class matching as <quote>anything but</quote> To do so put a caret +(<literal>^</literal>) at the beginning of the class: </para> + +<para><userinput>[^abc]</userinput> will match any character +<emphasis>but</emphasis> <quote>a</quote>, <quote>b</quote> or +<quote>c</quote>.</para> + +<para>In addition to literal characters, some abbreviations are +defined, making life still a bit easier: + +<variablelist> + +<varlistentry> +<term><userinput>\a</userinput></term> +<listitem><para> This matches the <acronym>ASCII</acronym> bell character (BEL, 0x07).</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>\f</userinput></term> +<listitem><para> This matches the <acronym>ASCII</acronym> form feed character (FF, 0x0C).</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>\n</userinput></term> +<listitem><para> This matches the <acronym>ASCII</acronym> line feed character (LF, 0x0A, Unix newline).</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>\r</userinput></term> +<listitem><para> This matches the <acronym>ASCII</acronym> carriage return character (CR, 0x0D).</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>\t</userinput></term> +<listitem><para> This matches the <acronym>ASCII</acronym> horizontal tab character (HT, 0x09).</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>\v</userinput></term> +<listitem><para> This matches the <acronym>ASCII</acronym> vertical tab character (VT, 0x0B).</para></listitem> +</varlistentry> +<varlistentry> +<term><userinput>\xhhhh</userinput></term> + +<listitem><para> This matches the Unicode character corresponding to +the hexadecimal number hhhh (between 0x0000 and 0xFFFF). \0ooo (&ie;, +\zero ooo) matches the <acronym>ASCII</acronym>/Latin-1 character +corresponding to the octal number ooo (between 0 and +0377).</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>.</userinput> (dot)</term> +<listitem><para> This matches any character (including newline).</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>\d</userinput></term> +<listitem><para> This matches a digit. Equal to <literal>[0-9]</literal></para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>\D</userinput></term> +<listitem><para> This matches a non-digit. Equal to <literal>[^0-9]</literal> or <literal>[^\d]</literal></para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>\s</userinput></term> +<listitem><para> This matches a whitespace character. Practically equal to <literal>[ \t\n\r]</literal></para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>\S</userinput></term> +<listitem><para> This matches a non-whitespace. Practically equal to <literal>[^ \t\r\n]</literal>, and equal to <literal>[^\s]</literal></para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>\w</userinput></term> +<listitem><para>Matches any <quote>word character</quote> - in this case any letter or digit. Note that +underscore (<literal>_</literal>) is not matched, as is the case with perl regular expressions. +Equal to <literal>[a-zA-Z0-9]</literal></para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>\W</userinput></term> +<listitem><para>Matches any non-word character - anything but letters or numbers. +Equal to <literal>[^a-zA-Z0-9]</literal> or <literal>[^\w]</literal></para></listitem> +</varlistentry> + + +</variablelist> + +</para> + +<para>The abbreviated classes can be put inside a custom class, for +example to match a word character, a blank or a dot, you could write +<userinput>[\w \.]</userinput></para> + +<note> <para>The POSIX notation of classes, <userinput>[:<class +name>:]</userinput> is currently not supported.</para> </note> + +<sect3> +<title>Characters with special meanings inside character classes</title> + +<para>The following characters has a special meaning inside the +<quote>[]</quote> character class construct, and must be escaped to be +literally included in a class:</para> + +<variablelist> +<varlistentry> +<term><userinput>]</userinput></term> +<listitem><para>Ends the character class. Must be escaped unless it is the very first character in the +class (may follow an unescaped caret)</para></listitem> +</varlistentry> +<varlistentry> +<term><userinput>^</userinput> (caret)</term> +<listitem><para>Denotes a negative class, if it is the first character. Must be escaped to match literally if it is the first character in the class.</para></listitem> +</varlistentry> +<varlistentry> +<term><userinput>-</userinput> (dash)</term> +<listitem><para>Denotes a logical range. Must always be escaped within a character class.</para></listitem> +</varlistentry> +<varlistentry> +<term><userinput>\</userinput> (backslash)</term> +<listitem><para>The escape character. Must always be escaped.</para></listitem> +</varlistentry> + +</variablelist> + +</sect3> + +</sect2> + +<sect2> + +<title>Alternatives: matching <quote>one of</quote></title> + +<para>If you want to match one of a set of alternative patterns, you +can separate those with <literal>|</literal> (vertical bar character).</para> + +<para>For example to find either <quote>John</quote> or <quote>Harry</quote> you would use an expression <userinput>John|Harry</userinput>.</para> + +</sect2> + +<sect2> + +<title>Sub Patterns</title> + +<para><emphasis>Sub patterns</emphasis> are patterns enclosed in +parentheses, and they have several uses in the world of regular +expressions.</para> + +<sect3> + +<title>Specifying alternatives</title> + +<para>You may use a sub pattern to group a set of alternatives within +a larger pattern. The alternatives are separated by the character +<quote>|</quote> (vertical bar).</para> + +<para>For example to match either of the words <quote>int</quote>, +<quote>float</quote> or <quote>double</quote>, you could use the +pattern <userinput>int|float|double</userinput>. If you only want to +find one if it is followed by some whitespace and then some letters, +put the alternatives inside a subpattern: +<userinput>(int|float|double)\s+\w+</userinput>.</para> + +</sect3> + +<sect3> + +<title>Capturing matching text (back references)</title> + +<para>If you want to use a back reference, use a sub pattern to have +the desired part of the pattern remembered.</para> + +<para>For example, it you want to find two occurrences of the same +word separated by a comma and possibly some whitespace, you could +write <userinput>(\w+),\s*\1</userinput>. The sub pattern +<literal>\w+</literal> would find a chunk of word characters, and the +entire expression would match if those were followed by a comma, 0 or +more whitespace and then an equal chunk of word characters. (The +string <literal>\1</literal> references <emphasis>the first sub pattern +enclosed in parentheses</emphasis>)</para> + +<!-- <para>See also <link linkend="backreferences">Back references</link>.</para> --> + +</sect3> + +<sect3 id="lookahead-assertions"> +<title>Lookahead Assertions</title> + +<para>A lookahead assertion is a sub pattern, starting with either +<literal>?=</literal> or <literal>?!</literal>.</para> + +<para>For example to match the literal string <quote>Bill</quote> but +only if not followed by <quote> Gates</quote>, you could use this +expression: <userinput>Bill(?! Gates)</userinput>. (This would find +<quote>Bill Clinton</quote> as well as <quote>Billy the kid</quote>, +but silently ignore the other matches.)</para> + +<para>Sub patterns used for assertions are not captured.</para> + +<para>See also <link linkend="assertions">Assertions</link></para> + +</sect3> + +</sect2> + +<sect2 id="special-characters-in-patterns"> +<title>Characters with a special meaning inside patterns</title> + +<para>The following characters have meaning inside a pattern, and +must be escaped if you want to literally match them: + +<variablelist> + +<varlistentry> +<term><userinput>\</userinput> (backslash)</term> +<listitem><para>The escape character.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>^</userinput> (caret)</term> +<listitem><para>Asserts the beginning of the string.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>$</userinput></term> +<listitem><para>Asserts the end of string.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>()</userinput> (left and right parentheses)</term> +<listitem><para>Denotes sub patterns.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>{}</userinput> (left and right curly braces)</term> +<listitem><para>Denotes numeric quantifiers.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>[]</userinput> (left and right square brackets)</term> +<listitem><para>Denotes character classes.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>|</userinput> (vertical bar)</term> +<listitem><para>logical OR. Separates alternatives.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>+</userinput> (plus sign)</term> +<listitem><para>Quantifier, 1 or more.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>*</userinput> (asterisk)</term> +<listitem><para>Quantifier, 0 or more.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>?</userinput> (question mark)</term> +<listitem><para>An optional character. Can be interpreted as a quantifier, 0 or 1.</para></listitem> +</varlistentry> + +</variablelist> + +</para> + +</sect2> + +</sect1> + +<sect1 id="quantifiers"> +<title>Quantifiers</title> + +<para><emphasis>Quantifiers</emphasis> allows a regular expression to +match a specified number or range of numbers of either a character, +character class or sub pattern.</para> + +<para>Quantifiers are enclosed in curly brackets (<literal>{</literal> +and <literal>}</literal>) and have the general form +<literal>{[minimum-occurrences][,[maximum-occurrences]]}</literal> +</para> + +<para>The usage is best explained by example: + +<variablelist> + +<varlistentry> +<term><userinput>{1}</userinput></term> +<listitem><para>Exactly 1 occurrence</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>{0,1}</userinput></term> +<listitem><para>Zero or 1 occurrences</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>{,1}</userinput></term> +<listitem><para>The same, with less work;)</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>{5,10}</userinput></term> +<listitem><para>At least 5 but maximum 10 occurrences.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>{5,}</userinput></term> +<listitem><para>At least 5 occurrences, no maximum.</para></listitem> +</varlistentry> + +</variablelist> + +</para> + +<para>Additionally, there are some abbreviations: + +<variablelist> + +<varlistentry> +<term><userinput>*</userinput> (asterisk)</term> +<listitem><para>similar to <literal>{0,}</literal>, find any number of occurrences.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>+</userinput> (plus sign)</term> +<listitem><para>similar to <literal>{1,}</literal>, at least 1 occurrence.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>?</userinput> (question mark)</term> +<listitem><para>similar to <literal>{0,1}</literal>, zero or 1 occurrence.</para></listitem> +</varlistentry> + +</variablelist> + +</para> + +<sect2> + +<title>Greed</title> + +<para>When using quantifiers with no maximum, regular expressions +defaults to match as much of the searched string as possible, commonly +known as <emphasis>greedy</emphasis> behavior.</para> + +<para>Modern regular expression software provides the means of +<quote>turning off greediness</quote>, though in a graphical +environment it is up to the interface to provide you with access to +this feature. For example a search dialog providing a regular +expression search could have a check box labeled <quote>Minimal +matching</quote> as well as it ought to indicate if greediness is the +default behavior.</para> + +</sect2> + +<sect2> +<title>In context examples</title> + +<para>Here are a few examples of using quantifiers</para> + +<variablelist> + +<varlistentry> +<term><userinput>^\d{4,5}\s</userinput></term> +<listitem><para>Matches the digits in <quote>1234 go</quote> and <quote>12345 now</quote>, but neither in <quote>567 eleven</quote> +nor in <quote>223459 somewhere</quote></para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>\s+</userinput></term> +<listitem><para>Matches one or more whitespace characters</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>(bla){1,}</userinput></term> +<listitem><para>Matches all of <quote>blablabla</quote> and the <quote>bla</quote> in <quote>blackbird</quote> or <quote>tabla</quote></para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>/?></userinput></term> +<listitem><para>Matches <quote>/></quote> in <quote><closeditem/></quote> as well as +<quote>></quote> in <quote><openitem></quote>.</para></listitem> +</varlistentry> + +</variablelist> + +</sect2> + +</sect1> + +<sect1 id="assertions"> +<title>Assertions</title> + +<para><emphasis>Assertions</emphasis> allows a regular expression to +match only under certain controlled conditions.</para> + +<para>An assertion does not need a character to match, it rather +investigates the surroundings of a possible match before acknowledging +it. For example the <emphasis>word boundary</emphasis> assertion does +not try to find a non word character opposite a word one at its +position, instead it makes sure that there is not a word +character. This means that the assertion can match where there is no +character, &ie; at the ends of a searched string.</para> + +<para>Some assertions actually does have a pattern to match, but the +part of the string matching that will not be a part of the result of +the match of the full expression.</para> + +<para>Regular Expressions as documented here supports the following +assertions: + +<variablelist> + +<varlistentry> +<term><userinput>^</userinput> (caret: beginning of +string)</term> +<listitem><para>Matches the beginning of the searched +string.</para> <para>The expression <userinput>^Peter</userinput> will +match at <quote>Peter</quote> in the string <quote>Peter, hey!</quote> +but not in <quote>Hey, Peter!</quote> </para> </listitem> +</varlistentry> + +<varlistentry> +<term><userinput>$</userinput> (end of string)</term> +<listitem><para>Matches the end of the searched string.</para> + +<para>The expression <userinput>you\?$</userinput> will match at the +last you in the string <quote>You didn't do that, did you?</quote> but +nowhere in <quote>You didn't do that, right?</quote></para> + +</listitem> +</varlistentry> + +<varlistentry> +<term><userinput>\b</userinput> (word boundary)</term> +<listitem><para>Matches if there is a word character at one side and not a word character at the +other.</para> +<para>This is useful to find word ends, for example both ends to find +a whole word. The expression <userinput>\bin\b</userinput> will match +at the separate <quote>in</quote> in the string <quote>He came in +through the window</quote>, but not at the <quote>in</quote> in +<quote>window</quote>.</para></listitem> + +</varlistentry> + +<varlistentry> +<term><userinput>\B</userinput> (non word boundary)</term> +<listitem><para>Matches wherever <quote>\b</quote> does not.</para> +<para>That means that it will match for example within words: The expression +<userinput>\Bin\B</userinput> will match at in <quote>window</quote> but not in <quote>integer</quote> or <quote>I'm in love</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><userinput>(?=PATTERN)</userinput> (Positive lookahead)</term> +<listitem><para>A lookahead assertion looks at the part of the string following a possible match. +The positive lookahead will prevent the string from matching if the text following the possible match +does not match the <emphasis>PATTERN</emphasis> of the assertion, but the text matched by that will +not be included in the result.</para> +<para>The expression <userinput>handy(?=\w)</userinput> will match at <quote>handy</quote> in +<quote>handyman</quote> but not in <quote>That came in handy!</quote></para> +</listitem> +</varlistentry> + +<varlistentry> +<term><userinput>(?!PATTERN)</userinput> (Negative lookahead)</term> + +<listitem><para>The negative lookahead prevents a possible match to be +acknowledged if the following part of the searched string does match +its <emphasis>PATTERN</emphasis>.</para> +<para>The expression <userinput>const \w+\b(?!\s*&)</userinput> +will match at <quote>const char</quote> in the string <quote>const +char* foo</quote> while it can not match <quote>const QString</quote> +in <quote>const QString& bar</quote> because the +<quote>&</quote> matches the negative lookahead assertion +pattern.</para> +</listitem> +</varlistentry> + +</variablelist> + +</para> + +</sect1> + +<!-- TODO sect1 id="backreferences"> + +<title>Back References</title> + +<para></para> + +</sect1 --> + +</appendix> diff --git a/doc/kate/unhighlighted.png b/doc/kate/unhighlighted.png Binary files differnew file mode 100644 index 000000000..6361032f3 --- /dev/null +++ b/doc/kate/unhighlighted.png |
