diff options
Diffstat (limited to 'doc/kate/part.docbook')
| -rw-r--r-- | doc/kate/part.docbook | 711 |
1 files changed, 711 insertions, 0 deletions
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> |