From 4aed2c8219774f5d797760606b8489a92ddc5163 Mon Sep 17 00:00:00 2001 From: toma Date: Wed, 25 Nov 2009 17:56:58 +0000 Subject: Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features. BUG:215923 git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdebase@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da --- doc/kate/part.docbook | 671 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 671 insertions(+) create mode 100644 doc/kate/part.docbook (limited to 'doc/kate/part.docbook') diff --git a/doc/kate/part.docbook b/doc/kate/part.docbook new file mode 100644 index 000000000..e09725b31 --- /dev/null +++ b/doc/kate/part.docbook @@ -0,0 +1,671 @@ + + + +&Anders.Lund; &Anders.Lund.mail; + + + +Working with the &kate; editor + + + +Overview + +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. + +The editor is composed of the following components: + + + + +The editing area +This is where the text of your document is located. + + + +The Scroll bars + +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. +The scroll bars are displayed and hidden as required. + + + + +The Icon Border + +The icon border is a small pane on the left side of the editor, +displaying a small icon next to marked lines. +You can set or remove a bookmark in a visible line by +clicking the &LMB; in the icon border next to that line. +The display of the icon border can be toggled using the +View Show Icon +Border menu item. + + + + +The Line Numbers Pane + +The Line numbers pane shows the line numbers of all visible +lines in the document. +The display of the Line Numbers Pane can be toggled using the +View Show Line +Numbers menu item. + + + + +The Folding Pane + +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. + + + + + + +Also in this Chapter: +Navigating in the +Text +Working with the +Selection +Copying and +Pasting Text +Finding and +Replacing Text +Using +Bookmarks +Automatically +Wrapping Text +Using automatic indenting + + + + + +Navigating in the Text + +Moving around in the text in &kate; is like in most graphical text +editors. You move the cursor using the arrow keys and the +Page Up, Page Down, Home and +End keys in combination with the Ctrl and +Shift modifiers. The Shift key is always used +to generate a selection, while the Ctrl key have different +effects on different keys: + +For the Up and Down keys it +means scroll rather than move the cursor. +For the Left and Right +keys it means skip words rather than characters. +for the Page Up and Page Down +keys it means move to the visible edge of the view rather than browse. + +For the Home and End keys it +means move to the beginning or end of the document rather than the beginning or +end of the line. + + + +&kate; also provides you with a way to quickly jump to a matching brace +or paranthese: Place the cursor on the inside of a parenthese or brace +character, and press Ctrl6 +to jump to the matching parenthese or brace. + +In addition you can use +bookmarks to quickly jump to +positions that you define on your own. + + + + +Working with the Selection + +There are two basic ways of selecting text in &kate;: using the +mouse, and using the keyboard. + +To select using the mouse, hold down the &LMB; while dragging +the mouse cursor from where the selection should start, to the desired +end point. The text gets selected as you drag. + +Double-clicking a word will select that word. + +Triple-clicking in a line will select the entire line. + +If &Shift; is held down while clicking, text will be +selected: + + +If nothing is already selected, from the text cursor +position to the mouse cursor position. +If there is a selection, from and including that +selection to the mouse cursor position + + + +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. + + + +To select using the keyboard, hold down the &Shift; key while +using the navigation keys (The Arrow keys, Page Up, +Page Down, Home and +End, possibly in combination with &Ctrl; to extend +the move of the text cursor). + +See also the section Navigating in the Text in this +Chapter. + +To Copy the current selection, use the +Edit +Copy menu item or the keyboard +shortcut (defaults to &Ctrl;C). + +To Deselect the current selection, use the +Edit +Deselect menu item, or the +keyboard shortcut (default is &Ctrl;&Shift;A), or click +with the &LMB; in the editor. + + +Using Block Selection + +When Block Selection is enabled, you can make vertical +selections in the text, meaning selecting limited columns from +multiple lines. This is handy for working with tab separated lines for +example. + +Block Selection can be toggled using the +Edit Toggle Block +Selection menu item. The default keyboard +shortcut is F4 + + + + + +Using Overwrite Selection + +If Overwrite Selection 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. + +Overwrite Selection is enabled by default. + +To change the setting for this option, use the Select Page of the Configuration Dialog. + + + + + +Using Persistent Selection + +When Persistent selection 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. + +Persistent Selection is disabled by default. + +Persistent Selection can be enabled in the Select Page of the Configuration Dialog. + + +If Persistent Selection and Overwrite Selection are both +enabled, typing or pasting text when the text cursor is inside the +selection will cause it to be replaced and deselected. + + + + + + + + +Copying and Pasting Text + +To copy text, select it and use the +Edit +Copy menu item. Additionally, +selecting text with the mouse will cause selected text to be copied to +the X selection. + +To paste the text currently in the clipboard, use the + +EditPaste +menu item. + +Additionally, text selected with the mouse may be pasted by +clicking the middle mouse button at the +desired position. + + +If you are using the &kde; desktop, you can retrieve earlier +copied text from any application using the &klipper; icon in the +&kicker; icon tray. + + + + + +Finding and Replacing Text + + +The <guilabel>Find Text</guilabel> and <guilabel>Replace +Text</guilabel> Dialogs + + +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. + +The dialogs offer the following common options: + + + + +Text to Find +This is where to enter the search string. The interpretation of the string +depends on some of the options described below. + + + +Regular Expression + +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. +See Regular +Expressions for more on these. + + + + +Case Insensitive + +If enabled, the search will be case insensitive. + + + + +Whole Words Only + +If checked, the search will only match if there is a word +boundary at both ends of the string matching, meaning not an +alphanumeric character - either some other visible character or a line +end. + + + + +From cursor + +If checked, the search will start at cursor position, otherwise it will +start at the beginning of the first line in the document. + + + + +Find Backwards + +If checked, the search will look for the first match above the +starting point, either cursor position or the beginning of the +document, if the From Beginning option is +enabled. + + + + + +The Replace Text Dialog offers some +additional options: + + + + +Replace With +This is where to enter the replacement +string. + + + +Selected Text + +This option is disabled if no text is selected, or if the +Prompt on Replace +option is enabled. If checked, all matches of the search string within +the selected text will be replaced with the replace string. + + + + +Prompt on Replace +If checked, a small dialog will prompt you for what to +do for each time a match is found. It offers the following options: + + + +Yes +Activate this to replace the current match (which is +selected in the editor). + + + +No +Activate to skip the current match, and try to find another one. + + + +All +Activate to cancel prompting, and just replace all +matches. + + + +Close +Activate this to skip the current match and end the +searching. + + + + + + + + + + +There is currently no way to use minimal matching when searching +for a regular expression. This will be added in a future version of +&kate; + + + + + +Finding Text + +To find text, launch the Find Text Dialog +with &Ctrl;For +from the Edit +Find... menu item, enter a +search string, set the options as desired and hit +Ok. If the search was started at cursor position and no +match was found before reaching the end (or beginning if you are searching +backward) of the document, you will be asked if you want to wrap the search. + + +If a match is found it is selected and the Find +Text Dialog is hidden, but stay tuned, finding further +matches is very easy: + +To find the next match in the search direction, use the +Edit Find +Next command or press +F3. + +To find the next match in the opposite direction, use the +Edit Find +Previous command or press &Shift;F3. + +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 wrap the search. + + + + + +Replacing Text + +To replace text, launch the Replace text +Dialog using the Edit +Replace command, or the +&Ctrl;R shortcut, +enter a search string and optionally a replace string (if the replace +string is empty, each match will be removed), set +the options as desired and +hit the Ok button. + + +If you are using a regular expression to find the text to replace, you can +employ backreferences to reuse text captured in parenthesized subpatterns of the expression. +See for more +on those. + + +You can do find, replace and +ifind (incremental search) from the +command line. + + + + + + + +Using Bookmarks + +The bookmarks feature allows you to mark certain lines, to be +able to easily find them again. + +You can set or remove a bookmark in a line in two ways: + + + +Move the insertion cursor to the line and activate the +BookmarksToggle +Bookmark (&Ctrl;B) command. + + +Click in the Icon Border next to the line. + + + + +Bookmarks are available in the Bookmarks +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. + +To quickly move between bookmarks or to the next/previous bookmark, +use the BookmarksNext + (Ctrl +Page Down) or +BookmarksPrevious +(CtrlPage Up +) commands. + + + + + +Automatically Wrapping text + +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. + +To enable/disable it, check/uncheck the Word Wrap checkbox in the +edit page of the configuration dialog. + +To set the maximum line width (maximum characters per line), use the +Wrap Words At +option in the edit page of the configuration +dialog. + +If enabled, +it has the following effects: + + +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. +While loading a document, the editor will wrap the text in a similar way, so that +no lines are longer than the maximum line width, if they contain any whitespace allowing that. + + + + +There is currently no way to set word wrap for document types, or even to enable or disable +the feature on document level. This will be fixed in a future version of &kate; + + + + +Using automatic indenting + +&kate;s editor component supports a variation of autoindenting modes, +designed for different text formats. You can pick from the available modes using +the ToolsIndentation +menu. The autoindent modules also provides a function +ToolsAlign +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. + +All the indent modes use the indentation related settings in the active +document. + +You can set all sorts of configuration variables, including +those related to indentation using Document +Variables and File +types. + + + +Available Autoindent Modes + + +None +Selecting this mode turns automatic indenting off entirely. + + + + +Normal +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. + + + +C Style +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. + + + +SS C Style +An alternative indenter for C and similar languages, with the +same constraints. + + + +Python Style +An indenter specifically for the python scripting language. + + + + +XML +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>) + + + +Variable Indenter + + + +The variable indenter is experimental, and may change behavior or +disappear in future versions. + + + +The variable indenter is special in that it can be configured using variables in +the document (or in a filetype configuration). The followwing variables are +read: + + + +var-indent-indent-after + +A regular expression which will cause a line to +be indented by one unit, if the first non-whitespace-only line above matches. +var-indent-indent: A regular expression, which will cause a matching line +to be indented by one unit. + + + + + +var-indent-unindent + +A regular expression which will cause the line to be +unindented by one unit if matching. + + + + +var-indent-triggerchars + +A list of characters that should cause the +indention to be recalculated immediately when typed. + + + + +var-indent-handle-couples + +A list of parenthese sets to handle. Any combination +of 'parens' 'braces' and 'brackets'. Each set type is handled +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. + + + + +var-indent-couple-attribute + +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's not +specified, attribute 0 is used (usually 'Normal Text'). + + + + + + + + + + + + + -- cgit v1.2.1