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/Makefile.am | 3 + doc/kate/TODO | 6 + doc/kate/advanced.docbook | 1242 ++++++++++++++++++++++++++ doc/kate/configdialog01.png | Bin 0 -> 44641 bytes doc/kate/configdialog02.png | Bin 0 -> 25384 bytes doc/kate/configuring.docbook | 1595 ++++++++++++++++++++++++++++++++++ doc/kate/fundamentals.docbook | 621 +++++++++++++ doc/kate/highlighted.png | Bin 0 -> 4797 bytes doc/kate/highlighting.docbook | 931 ++++++++++++++++++++ doc/kate/index.docbook | 293 +++++++ doc/kate/kate.png | Bin 0 -> 81016 bytes doc/kate/man-kate.1.docbook | 165 ++++ doc/kate/mdi.docbook | 266 ++++++ doc/kate/menus.docbook | 1438 ++++++++++++++++++++++++++++++ doc/kate/mimetypechooser.png | Bin 0 -> 15823 bytes doc/kate/part.docbook | 671 ++++++++++++++ doc/kate/plugins.docbook | 28 + doc/kate/regular-expressions.docbook | 664 ++++++++++++++ doc/kate/unhighlighted.png | Bin 0 -> 3471 bytes 19 files changed, 7923 insertions(+) create mode 100644 doc/kate/Makefile.am create mode 100644 doc/kate/TODO create mode 100644 doc/kate/advanced.docbook create mode 100644 doc/kate/configdialog01.png create mode 100644 doc/kate/configdialog02.png create mode 100644 doc/kate/configuring.docbook create mode 100644 doc/kate/fundamentals.docbook create mode 100644 doc/kate/highlighted.png create mode 100644 doc/kate/highlighting.docbook create mode 100644 doc/kate/index.docbook create mode 100644 doc/kate/kate.png create mode 100644 doc/kate/man-kate.1.docbook create mode 100644 doc/kate/mdi.docbook create mode 100644 doc/kate/menus.docbook create mode 100644 doc/kate/mimetypechooser.png create mode 100644 doc/kate/part.docbook create mode 100644 doc/kate/plugins.docbook create mode 100644 doc/kate/regular-expressions.docbook create mode 100644 doc/kate/unhighlighted.png (limited to 'doc/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..b9b0cda91 --- /dev/null +++ b/doc/kate/advanced.docbook @@ -0,0 +1,1242 @@ + + + +&Anders.Lund; &Anders.Lund.mail; +&Dominik.Haumann; &Dominik.Haumann.mail; + + + +Advanced Editing Tools + + + +Comment/Uncomment + +The Comment and Uncomment commands, available from the +Tools menu allow you to add or remove comment +markers to the selection, or the current line if no text is selected, +if comments are supported by the format of the text you are +editing. + +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. + +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. + +If a single line marker is available, commenting single lines is +preferred where applicable, as this helps to avoid problems with +nested comments. + +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. + +comment +To place comment markers, use the +ToolsComment +menu item or the related keyboard shortcut sequence, default is +&Ctrl;D. + +uncomment +To remove comment markers, use the +ToolsUncomment +menu item or the related keyboard shortcut, default is &Ctrl;&Shift;D. + + + + +The Editor Component Command Line + +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 +ViewSwitch to Command Line +or use the shortcut (default is +F7). The editor provides +a set of commands as documented below, and additional commands can be provided +by plugins. + +To execute a command, type the comand then press the return key. The +command line will indicate wether it succeded and possibly display a message. If +you entered the command line by pressing F7 it will +automatically hide after a few seconds. To clear the message and enter a new +command, press F7 again. + +The command line has a built-in help system, issue the command +help to get started. To see a list of all available commands +issue help list, to view help for a specific command, do +help command. + +The command line has a built in history, so you can reuse commands already +typed. To navigate the history, use the Up and +Down keys. When showing historical commands, the argument part +of the command will be selected, allowing you to easily overwrite the +arguments. + + +Standard Command Line Commands + + +Commands for Configuring the Editor + +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. + + + +Argument types + + +BOOLEAN +This is used with commands that turns things on or off. +Legal values are on, off, +true, false, +1 or 0 + + + +INTEGER +An integer number + + + +STRING +A string + + + + + + + +set-tab-widthINTEGER width +Sets the tab width to the number width + + + +set-indent-widthINTEGER width +Sets the indentation width to the number +width. Used only if you are indenting with +spaces. + + + +set-word-wrap-columnINTEGER width +Sets the line width for hard wrapping to +width. This is used if you are having your text wrapped +automatically. + + + +set-icon-borderBOOLEAN enable + +Sets the visibility of the icon border. + + + +set-folding-markersBOOLEAN enable +Sets the visibility of the folding markers pane. + + + +set-line-numbersBOOLEAN enable +Sets the visibility of the line numbers pane. + + + +set-replace-tabsBOOLEAN enable +If enabled, tabs are replaced with spaces as you type. + + + + +set-remove-trailing-spaceBOOLEAN enable +If enabled, trailing whitespace are removed whenever the cursor +leaves a line. + + + +set-show-tabsBOOLEAN enable +If enabled, TAB characters and trailing whitespace will be +visualized by a small dot. + + + +set-indent-spacesBOOLEAN enable +If enabled, the editor will indent with + spaces for each indentation level, rather than +with one TAB character. + + + +set-mixed-indentBOOLEAN enable +If enabled, kate will use a mix of TAB and spaces for +indentation. Each indentation level will be wide, +and more indentation levels will be optimized to use as many TAB characters as +possible. +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 + for the document at the time of execution. + + + +set-word-wrapBOOLEAN +enable +Enables dynamic word wrap according to +enable + + + +set-replace-tabs-saveBOOLEAN enable + +When enabled, tabs will be replaced with whitespace whenever + the document is saved. + + + +set-remove-trailing-space-saveBOOLEAN enable +When enabled, trailing space will be removed from each line +whenever the document is saved. + + + +set-indent-modename +Sets the autoindentation mode to name. +If name is not known, the mode is set to 'none'. Valid +modes are 'cstyle', 'csands', 'xml', 'python', 'varindent' and 'none'. + + + +set-highlighthighlight +Sets the syntax highlighting system for the document. The +argument must be a valid highlight name, as seen in the +ToolsHighlighting +menu. This command provides an autocompletion list for its +argument. + + + + + + + +Commands for editing + +These commands modify the current document. + + + +indent +Indents the selected lines or the current line. + + + +unindent +Unindents the selected lines or current line. + + + +cleanindent +Cleans up the indentation of the selected lines or current line +according to the indentation settings in the document. + + + + +comment +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. + + + +uncomment +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. + + + +kill-line +Deletes the current line. + + + +replacepatternreplacement +Replaces text matching pattern with +replacement. If you want to include whitespace in the +pattern, you must quote both the pattern +and replacement with single or double quotes. If the +arguments are unquoted, the first word is used as pattern +and the rest for replacement. If +replacement is empty, each occurrence of +pattern is removed. +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 +replace:options pattern replacement. Available options +are: + + + + +b +Search backwards. + + + +c +Search from cursor position. + + + +e +Search in the selection only. + + + +r +Do regular expression search. If set, you may use +\N where N is a number to represent captures in the +replacement string. + + + +s +Do case sensitive search. + + + +p +Prompt for permission to replace the next occurence. + + + +w +Match whole words only. + + + + + + + + + +dateformat +Inserts a date/time string as defined by the specified +format, or the format yyyy-MM-dd hh:mm:ss +if none is specified. The following translations are done when interpreting +format: + + + + +dThe day as number without a leading zero (1-31). +ddThe day as number with a leading zero (01-31). +dddThe abbreviated localized day name (e.g. 'Mon'..'Sun'). +ddddThe long localized day name (e.g. 'Monday'..'Sunday'). +MThe month as number without a leading zero (1-12). +MMThe month as number with a leading zero (01-12). +MMMThe abbreviated localized month name (e.g. 'Jan'..'Dec'). +yyThe year as two digit number +(00-99). +yyyyThe year as four digit number (1752-8000). +hThe hour without a leading zero (0..23 or 1..12 if AM/PM display). +hhThe hour with a leading zero (00..23 or 01..12 if AM/PM display). +mThe minute without a leading zero (0..59). +mmThe minute with a leading zero (00..59). +sThe second without a leading zero (0..59). +ssThe second with a leading zero (00..59). +zThe milliseconds without leading zeroes (0..999). +zzzThe milliseconds with leading zeroes (000..999). +APUse AM/PM display. AP will be replaced by either "AM" or "PM". +apUse am/pm display. ap will be replaced by either "am" or "pm". + + + + + + + + + +charidentifier + +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 char: +[number] in the entry box, then hit +OK. + + +<command>char</command> examples + +Input: char:234 +Output: ê +Input: char:0x1234 +Output: ሴ + + + + + + + +replace, sed style +search, sed style +s///[ig] %s///[ig] + + +This command does a sed-like search/replace operation on the +current line, or on the whole file (%s///). + +In short, the text is searched for text matching the +search pattern, 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 part of the string. Parentheses in the search pattern +create back references, that is the command +remembers which part of the match matched in the parentheses; these +strings can be reused in the replace pattern, referred to as +\1 for the first set of parentheses, +\2 for the second and so on. + +To search for a literal ( or +), you need to escape it using +a backslash character: \(\) + +If you put an i at the end of the +expression, the matching will be case insensitive. If you put a +g at the end, all occurrences of the pattern will be +replaced, otherwise only the first occurrence is replaced. + + + +Replacing text in the current line + +Your friendly compiler just stopped, telling you that the class +myClass mentioned in line 3902 in your source file +is not defined. + +"Buckle!" you think, it is of course +MyClass. You go to line 3902, and instead of trying +to find the word in the text, you launch the Editing Command Dialog, +enter s/myclass/MyClass/i, hit the +OK button, save the file and compile – +successfully without the error. + + + + +Replacing text in the whole file + +Imagine that you have a file, in which you mention a Miss +Jensen several times, when someone comes in and tells you that +she just got married to Mr Jones. You want, of course, +to replace each and every occurrence of Miss Jensen +with Ms Jones. + +Enter the command line and issue the command +%s/Miss Jensen/Ms Jones/ and hit return, you +are done. + + + + +A More Advanced Example + +This example makes use of back references +as well as a character class (if you do not know what +that is, please refer to the related documentation mentioned +below). + +Suppose you have the following line: + +void MyClass::DoStringOps( String &foo, String &bar String *p, int &a, int &b ) + +Now you realize that this is not nice code, and decide that you +want to use the const keyword for all +address of arguments, those characterized by the & +operator in front of the argument name. You would also like to +simplify the white space, so that there is only 1 whitespace character +between each word. + +Launch the Editing Command Dialog, and enter: +s/\s+(\w+)\s+(&)/ const \1 \2/g and hit the +OK button. The g at the end of the expression makes +the regular expression recompile for each match to save the backreferences. + +Output: + +void MyClass::DoStringOps( const String &foo, const String &bar String *p, const int &a, const int &b ) + +Mission completed! Now, what happened? Well, we looked for some +white space (\s+) followed by one or more +alphabetic characters (\w+) followed by some more +whitespace (\s+) followed by an ampersand, and in +the process saved the alphabetic chunk and the ampersand for reuse in +the replace operation. Then we replaced the matching part of our line +with one whitespace followed by const followed by one +whitespace followed by our saved alphabetical chunk +(\1) followed by one whitespace followed by our +saved ampersand (\2) + +Now in some cases the alphabetical chunk was +String, in some int, so using the +character class \w and the + +quantifier proved a valuable asset. + + + + + + + + + + + + +Commands for navigation + + + + +gotoINT line +This command navigates to the specified line. + + + +findpattern +This command navigates to the first occurrence of +pattern according to the configuration. Following +occurrences can be found using +EditFind Next +(the default shortcut is F3). +The find command can be configured by appending a colon followed by one or +more options, the form is +find:options pattern. The +following options are supported: + + + + +b +Search backwards. + + + +c +Search from cursor position. + + + +e +Search in the selection only. + + + +r +Do regular expression search. If set, you may use +\N where N is a number to represent captures in the +replacement string. + + + +s +Do case sensitive search. + + + +w +Match whole words only. + + + + + + + + + + + +ifindpattern +This command provides as-you-type searching. You +can configure the behavior of the search by appending a colon +followed by one or more options, like this: +ifind:options pattern. Allowed options are + + + +b +Search backwards. + + + +r +Do regular expression search. + + + +s +Do case sensitive search. + + + +c +Search from cursor position. + + + + + + + + + + + + + + + +Using Code Folding + +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 formats - typically program source code, +XML markup and similar. Most highlight definitions supporting code folding +also lets you manually define foldable regions, typically using the +BEGIN and END keywords. + +To use the code folding feature, activate the folding markers using +ViewShow Folding +Markers 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 the - will +collapse the region and a + will be displayed instead. + +Four commands are provided to manipulate the state of folding regions, +see the menu documentation. + + +If you do not want to use the code folding feature, you can disable +the Show folding markers (if available) option in the +Appearance page of the editor +configuration + + + + + +Scripting the editor component with Javascript + + + +Introduction + +Starting with version 2.5, the &kate; editor component supports +scripting with ECMA script, also known as JavaScript. + +Scripts can be used through the built in command line +only. The requirements is that the script is placed in a folder where &kate; +can find it, along with an optional .desktop file that defines the related +properties. The valid folder are named katepart/scripts +in the &kde; data folders. You can find the data folders by running the command +kde-config data +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 for you only. + +This feature is experimental and will most likely change during +future development. +We know that many of you will be disappointed because you can't add +your scripts to the menu or assign shortcuts to them. Sorry, sometime +in the future that will likely be possible. +It is also not possible to pass any arguments to your scripts yet. Be +patient, and that may be added in the bright future ;) + + + + + + +The Kate JavaScript API + +Here is listed the complete set of functions and properties available +in the document and view objects. +In addition you can of course use all the standard objects such as +Math, String Regex and so forth. + +When a script is run, the document object is the +current document, and the view object is the current +view. + +The types of arguments are of course not used in JavaScript at +this time, they are there solely to indicate what sort of value the funcitons +expect. + + +Global Functions + +debug( string) +[function] + + +parameters +string the string to output + + +Outputs the string to STDERR using +kdDebug(). A dedicated output area is used for the output, +which will be prefixed Kate (KJS Scripts): + + + + + + +The <classname>document</classname> API + + +document.attribute( line +, column ); + [function] + + +Parameters +uint line The line of the position for which +to find the attribute. +uint column The column of the position for +which to find the attribute. + +Returns the numeric ID of the attribute for the document position +[line,column]. 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. + + + + +document.canBreakAt( Char c, +uint attribute ); [function] + + +Parameters +c The character to test +attribute The attribute at the position +of c. + +Returns whether it is allowed to break the line at a character c with +attribute attribute. The result is decided by querying the highlight owning +attribute for which characters allow breaking the line. + + + + +document.canComment( uint start_attribute, +uint end_attribute ); [function] + + +Parameters +start_attribute The attribute at the +start of the range to turn into a comment. +end_attribute The attribute at end of +the range to turn into a comment. + +Returns whether start_attribute and end_attribute belongs to the same +syntax highlight system. If they do, it is sane. + + +using canComment + +if ( document.canComment( document.attribute(1,0), document.attribute(5,0) ) ) { + // 1,0 and 5,0 belongs to the same syntax highlighting system +} + + + + + + +document.clear(); [function] +Clears the document. + + + +document.commentStart( uint attribute ); +[function] + + +Parameters +attribute The attribute of the text for +which to get the commentStart string. + +Returns the string required to start a multiline comment for a text with +attribute, or an empty string if multiline comments are not supported for that +text. + + + + +document.commentMarker( uint attribute ); +[function] + + +Parameters +attribute The attribute of the text for +which to get the commentMarker string + +Returns the string used to mark the rest of the line as a comment for a +text with attribute or an empty string if single line comments are not supported +for that text. + + + + +document.commentEnd( uint attribute ); +[function] + + +Parameters +attribute The attribute of the text for +which to get the commentEnd string + +Returns the string required to end a multiline comment for a text with +attribute, or an empty string if multiline comments are not supported for that +text. + + + + +document.editBegin(); [function] + +Start an editing group. All actions done until the call of editEnd() will +be grouped as one undo-action. + + + + +document.editEnd(); [function] + +Finish an editing group. + + + + +document.highlightMode; [property:read only] + +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 None. Notice +that you need to use the English name in cases where it differs from the +translated one. + + + + +document.indentMode; [property:read only] + +The name of the document indent mode, such as +normal or cstyle. +Remember that if no indent mode is set, the value is none. + + + + + +document.indentWidth; [property:read only] + +The indentation width set for the document. This is used if space +indenting is enabled. + + + + +document.insertLine( uint line, +string text ); [function] + + +Parameters +line document line number + +text text to insert + +Inserts a new line with the text text at the +line line. + + + + +document.insertText( uint line, +uint column, string text ); +[function] + + +Parameters +line the line number +column the column +text the text which is to be +inserted + +Inserts the text text in line +line and column column. + + + + +document.length(); [function] + +Returns the document's size in bytes. + + + + +document.lines(); [function] + +Returns the number of lines in the document. + + + + +document.mixedIndent; [property:read only] + +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 used by the Emacs editor. + + + + +document.removeLine( uint line ); [function] + + +Parameters +line line number + +Removes the document line line. + + + + +document.removeText( uint startLine, +uint startColumn, uint endLine, +uint endColumn ); [function] + + +Parameters +startLine specifies the beginning +line +startColumn specifies the beginning +column +endLine specifies the ending +line +endColumn specifies the ending +column + +Removes the text range from line startLine and +column startColumn up to line +endLine and column endColumn. + + + + + +document.setText( string text ); +[function] + + +Parameters +text document text + +Sets the entire document content to text. + + + + +document.spaceIndent; [property:read only] + +A boolean telling whether space-indent is enabled for the document. +If so, the document is indented with indentWidth spaces pr level, otherwise +indentation is one tab character pr. level. + + + + +document.textFull(); [function] + +Returns the full document text. If the text spans over multiple lines the +linefeed character is \n. + + + + +document.textLine( uint line ); [function] + + +Parameters +line the line + +Returns the text of line line. + + + + +document.textRange( uint startLine, +uint startColumn, uint endLine, +uint endColumn ); [function] + + +Parameters +startLine specifies the beginning +line +startColumn specifies the beginning +column +endLine specifies the ending line + +endColumn specifies the ending +column + +Returns the specified text range. If the range spans over multiple lines +the linefeed character is \n. + + + + + + +The <classname>view</classname> API + + +view.clearSelection(); [function] + +Deselects all text. + + + + +view.cursorColumn(); [function] + +Returns the current cursor column (TAB characters are expanded). + + + + +view.cursorColumnReal(); [function] + +Returns the current real cursor column (TAB characters counts one). + + + + +view.cursorLine(); [function] + +Returns the current cursor line. + + + + +view.hasSelection(); [function] + +Returns true if the view contains selected text, +otherwise false. + + + + +view.removeSelectedText(); [function] + +Removes the selected text, if the view has a selection. + + + + +view.selectAll(); [function] + +Selects all text. + + + + +view.selection(); [function] + +Returns the selected text. If the selection spans over multiple lines the +linefeed character is \n. + + + + +view.selectionEndColumn; [property:read only] + +Returns the ending column of the selection. + + + + +view.selectionEndLine; [property:read only] + +Returns the ending line of the selection. + + + + +view.selectionStartColumn; [property:read only] + +Returns the starting column of the selection. + + + + +view.selectionStartLine; [property:read only] + +Returns the starting line of the selection. + + + + +view.setCursorPosition( uint line, +uint column ); [function] + + +Parameters +line Specifies the line for the +cursor. +column Specifies the column for the +cursor. + +Sets the input cursor position in the view to [line, +col]. This sets the cursor position by visual means, +that is the a TAB character counts up to tabwidth +depending on the position inside the line. The cursor position is made visible. +Both line and column are zero-based. + + + + +view.setCursorPositionReal( uint line, +uint column ); [function] + + +Parameters +line Specifies the line for the +cursor. +column Specifies the column for the +cursor. + +Sets the input cursor position to [line, +col]. This sets the string position, that is a TAB +character counts for 1. The cursor position is made visible. Both line and +column are zero-based. + + + + +view.setSelection( uint startLine, +uint startColumn, uint endLine, +uint endColumn ); [function] + + +Parameters +startLine specifies the beginning line +startColumn specifies the beginning column +endLine specifies the ending line +endColumn specifies the ending column + +Sets a selection from line startLine and column +startColumn up to line endLine +and column endColumn. + + + + + + + +A sample script +As an example we will create a small script that uppercases the selection. +It is obvious that we first need to check whether a selection exists, if so we +get the text, change the case and then replace it with the new one. An +implementation could look like this: + + +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(); +} + + +To group this action together so that they will be reverted by a single +activation of Undo we encapsulate the lines +view.removeSelectedText() and +document.insertText() with a +document.editBegin() and +document.editEnd(). + + + + +A sample <filename>.desktop</filename> file + +Here is a sample .desktop file that accompanies the above script. + + +# Example of a .desktop file +[Desktop Entry] +Encoding=UTF-8 +Name=Kate Part JavaScript Uppercase +Comment=Script to uppercase the selection +X-Kate-Command=uppercase-selection +X-Kate-Help=<p>Usage: <code>uppercase-selection</code></p> + + +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. The entries +Name, Comment and X-Kate-Help are automatically translated into other languages +by the KDE translation teams, if the files are in KDE's SVN repository. + + + + +Putting it togeather + +&kate; will search the script folders (see above) for +*.js files. For every file it checks whether there is a +corresponding .desktop file, like for uppercase.js it +would look for uppercase.desktop. +If a .desktop file can not be found the script will +be registered in katepart's command line with the filename without the ending +.js, so in our example this would be uppercase. If the +command-name is fine and you don't need the extra features a +.desktop file provides you do not need a +.desktop file at all. +If a .desktop file exists katepart will read the name +under which the script will be registered from the .desktop-entry +X-Kate-Command, for example X-Kate-Command=uppercase-selection. + + + + + + + + diff --git a/doc/kate/configdialog01.png b/doc/kate/configdialog01.png new file mode 100644 index 000000000..751066792 Binary files /dev/null and b/doc/kate/configdialog01.png differ diff --git a/doc/kate/configdialog02.png b/doc/kate/configdialog02.png new file mode 100644 index 000000000..70a7ecaed Binary files /dev/null and b/doc/kate/configdialog02.png differ diff --git a/doc/kate/configuring.docbook b/doc/kate/configuring.docbook new file mode 100644 index 000000000..14642c74c --- /dev/null +++ b/doc/kate/configuring.docbook @@ -0,0 +1,1595 @@ + + + +&Anders.Lund; &Anders.Lund.mail; + + + +Configuring &kate; + + +Overview + + +configure +settings +preferences + + + + + + + +&kate; offers several means of tweaking the application to behave as desired. +The most important ones are: + + + + +The Configuration Dialog +The main configuration tool, allowing you to configure the &kate; application, +the editor component and the usage of plugins. + + +The Settings Menu +Allows you to change often used settings, and to +launch the configuration dialogs. + + +The View Menu +Allows you to split the current frame, as well as to +display the icons and line numbers pane for the currently edited +document. + + + +The embedded &konsole; is using the configuration defined in the +&kcontrolcenter;, and may be configured by clicking the +right mouse button and choosing from the +Settings sub menu. + + + + +The Main Configuration Dialog + + + + + + + +The &kate; configuration dialog displays a tree of topics on the +left, and a configuration page corresponding to the selected topic on +the right. + +The configuration is divided into two groups, namely + +Application configuration + +Editor component configuration + + + + + + + + +The &kate; Application Configuration +This group contains pages to configure the main &kate; application + + +The General Page +This section contains a few global options for &kate; + + + + + +Show Full Path in Title +When enabled, Kate will display the full URL of your +current document in the window title, rather than just the file name. + + + + + +Behavior + + + + + +Sync Konsole with Active Document +This will cause the built-in &konsole; to +cd 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. + + + + + +Warn about files modified by foreign processes +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. +If not enabled, &kate; will prompt you for action when a externally +modified file receives focus within the application. + + + + + + + + + +Meta Data + + + + + +Keep meta-information past sessions +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. + + + + +Delete unused meta information after +Set the maximum number of days to keep meta information +for unopen files. This helps keeping the database of meta information +reasonably sized. + + + + + + + + + + + +The Sessions Page + +This section contains options related to using sessions. + + + + + +Elements of Sessions + + + +Include window configuration +If enabled, &kate; will save the window configuration +with each session. + + + + + + + +Behavior on Application Startup + +Select how you want &kate; to behave at startup. This setting can be +overridden by specifying what to do on the command line. + + +Start new session +With this option, &kate; will start a new, unnamed session +when you start it. + + +Load last used session +&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. + + +Manually choose a session +&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. + + + + + + + +Behavior on Application Exit or Session Switch + + + +Do not save session +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. + + +Save Session +&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. + + + +Ask user +You will be asked if you want to save the session every time a +named session is closed. + + + + + + + + + + +The <guilabel>Filesystem Browser</guilabel> Page + + + +Toolbar +Configure the buttons on the file system browser toolbar +by moving the ones you want enabled to the Selected Actions +list, and order them using the arrow buttons at the side of the list. + + + + +Auto Synchronization +You can have the filesystem browser automatically navigate to +the directory containing the current document on certain events: + +When a new document becomes the active one. +When the filesystem browser becomes visible. + +Even if you select not to use this feature, you can manually synchronize the +browser with the current document by pressing the +Synchronize toolbar button. + + + + +Remember locations +Select how long a browsing history you want. The browser does +only remember individual locations, duplicates are removed. + + + +Remember filters +Select how many filters you want remembered. Only individually +distinct filters are remembered, duplicates are removed. + + + +Session + +Configure wether the file system browser should remember its location and +filter over sessions. + + + + + + + + +The <guilabel>Doucment List</guilabel> Page + + + +Backgound Shading +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 The Document List for more about +this feature. + + +Sort By +Set how you want the document list sorted. This can be set +from the &RMB; menu in the document list as well. + + + + + + +The <guilabel>Plugins</guilabel> Page + +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. + + +If a plug-in provides configuration options, a section to access those +will appear as a child of this page. + + + + + +External Tools + +In the Tools menu you will find a submenu labeled +External Tools. 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. + +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. + + +External Tools Properties + +Label +A friendly label for the External Tools menu. + + + +Script +The script to execute when the tool is activated. Before passing +the script to the shell, the following macros are substituted: + + + +%URL +The full URL of the current document, or an empty string if the +document is unsaved. + + + +%URLS +A space seperated list of the URLs of all open documents +(except unsaved ones). + + + +%directory +The directory part of the current documents URL or an empty +string if the current document is unsaved. + + + +%filename +the filename of the current document without the path, or an +empty string if the current document is unsaved. + + + +%line +The line number of the insertion cursor is in the current +document. + + + +%column +The column number of the insertion cursor in the current +document. + + + +%selection +The selected text in the current document, or an empty string +if no text is selected + + + +%text +The full text of the current document. Beware that this will +potentially exceed the maximum command length allowed on your system. +Use with care. + + + + + + + + +Executable +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 PATH variable. + + + +Mimetypes +A semicolon separated list of mimetypes for which this command +should be enabled. This is currently unused. + + + +Save +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. + + + +Command Line Name +If you fill this, the tool will be available in the +editors command line as +exttool-Command Line Name +(the string you enter here prepended exttool-). + + + + + + + + + +The Editor Component Configuration +This group contains all pages related to the editor component of +&kate;. Most of the settings here are defaults, they can be overridden by +defining a filetype, +by Document Variables or by changing +them pr. document during an editing session. + + + +Appearance + + + +Word Wrap + + + +Dynamic word wrap +If this option is checked, the text lines +will be wrapped at the view border on the screen. + + +Dynamic word wrap indicators +Choose when the Dynamic word wrap indicators +should be displayed. + + +Vertically align dynamically wrapped lines +to indentation depth: + +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.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. + + + + + + +Code Folding + + + +Show folding markers (if available) + +If this option is checked, the current view will display marks +for code folding, if code folding is available. + + + + + + +Borders + + + +Show icon border + +If this is checked, you will see an icon border on the left +hand side. The icon border shows bookmark signs for instance. + + +Show line numbers + +If this is checked, you will see line numbers on the left +hand side. + + +Show scrollbar marks + +If this option is checked the current view +will show marks on the vertical scrollbar. These marks will +for instance show bookmarks. + + + + + + +Sort Bookmarks Menu + + + + +By position + +The bookmarks will be ordered by the line +numbers they are placed at. + + +By creation + +Each new bookmark will be added to the bottom, +independently from where it is placed in the document. + + + + + + +Show identation lines + +If this is checked, the editor wil display +vertical lines to help identifying indent lines. + + + + + +Fonts & Colors + +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. + + +&kate; will preselect the currently active scheme for you, if you want to +work on a different scheme start by selecting that from the +Schema combobox. + + +Colors + + + +Text Area Background + + + + + +Normal text +This is the default background for the editor area, it will be +the dominant color on the editor area. + + + +Selected Text +This is the background for selected text. The default is +the global selection color, as set in your &kde; color preferences. + + + + +Current Line +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. + + + + +Bookmark +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. + + + + + + + +Other Elements + + + +Left Border Background +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. + + + +Line Numbers +This color is used to draw the line numbers on the left side of +the view when displayed. + + +Bracket Highlight +This color is used to draw the background of matching brackets. + + + +Word Wrap Markers +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. + + +Tab Markers +This color is used to draw white space indicators when enabled. + + + + + + + + + + +Fonts + +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. + + + + +Normal Text Styles +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. +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. + +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. + + + +Highlighting Text Styles +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 Highlight combobox +above the style list. + +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. + +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. +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. + + + + + + +Cursor & Selection + + + + +Text Cursor Movement + + + +Smart home + +When selected, pressing the home key will cause the cursor to +skip white space and go to the start of a line's text. + + + +Wrap cursor + +When on, moving the insertion cursor using the Left and Right keys will +go on to previous/next line at beginning/end of the line, similar to most +editors.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. + + + +Page Up/Page Down moves cursor + +This option changes the behavior of the cursor when the user presses +the Page Up or Page Down 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. + + + +Autocenter cursor (lines): + +Sets the number of lines to maintain visible above and below the cursor +when possible. + + + + + + + +Selection Mode + + + +Normal + +Selections will be overwritten by typed text and will be lost on +cursor movement. + + + +Persistent + +Selections will stay even after cursor movement and typing. + + + + + + + + + + +Editing + + + +Tabulators + + + +Insert spaces instead of tabulators + +When this is enabled the editor will insert a calculated number of spaces +according to the position in the text and the setting +when you press the TAB key. + + + +Show tabulators + +When this is enabled &kate; will display a small dot as a visual +representation of tabulator characters. +This also causes dots to be drawn to indicate trailing white space. +This will be fixed in a future version of &kate; + + + +Tab Width If the +Replace Tabs By +Spaces +option is selected this entry determines the number of +spaces with which the editor will automatically replace +tabs. + + + + + + +Static Word Wrap + +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 Wrap Words +At: option. + + +Enable static word wrap + +Turns static word wrap on or off. + + + +Show static word wrap markers +(if applicable) + +If this option is checked, a vertical line will be drawn at the word wrap +column as defined in the Settings +Configure Editor... in the Editing tab. +Please note that the word wrap marker is only drawn if you use a fixed pitch +font. + + + +Wrap words at: + +If the Word Wrap option is selected +this entry determines the length (in characters) at which the editor will +automatically start a new line. + + + + + + + +Remove Trailing Spaces +&kate; will automatically eliminate extra spaces +at the ends of lines of text. + + +Auto Brackets When +the user types a left bracket ([, (, or {) &kate; automatically enters the +right bracket (}, ), or ]) to the right of the cursor. + + + Maximum undo steps: +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, i.e. click the undo +button 10 times and obtain results. + + Smart search text from: +This determines where &kate; will get the search +text from (this will be automatically entered into the Find Text +dialog): + +Nowhere: Don't guess the search +text. +Selection Only: Use + the current text selection, if available. +Selection, then Current Word: +Use the current selection if available, otherwise use the current word. + +Current Word +Only: Use the word that the cursor is currently resting on, if +available. +Current Word, then Selection: +Use the current word if available, otherwise use the current selection. + + +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. + + + + + + +Indentation + + +Automatic indentation + + + +Indentation mode: + +Select the automatic indentation mode you want to use as default. It is +strongly recommended to use None or +Normalhere, and use filetype configurations to set other +indentation modes for text formats like C/C++ code or &XML;. + + + +Insert leading Doxygen "*" when typing + +Automatically insert a leading "*" while typing within a doxygen +style comment. This setting is only enabled when applicable. + + + + + + + +Indentation with Spaces + + + +Use spaces instead of tabs to indent + +This replaces tabs with the number of spaces set in Number of +spaces: below. + + + +Emacs style mixed mode + +Use a mix of tabs and space characters for indentation. + + + +Number of spaces: + +Set the number of spaces you want to use for indentation when you +check Use spaces instead of tabs to indent +above. + + + + + + + +Keep Indent Profile +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. + + + + +Keep Extra Spaces +Indentations of more than the selected number of spaces +will not be shortened. + + + +Keys to use + + + +Tab key indents + +This allows the tab key to be used to indent. + + + +Backspace key indent + +This allows the backspace key to be used to +indent. + + + + + + + +Tab Key Mode if Nothing Selected + + + +Insert indent characters + +This allows the Tab key insert indent +characters. + + + +Insert tab character + +This allows the Tab key insert a tab. + + + +Indent current line + +This allows the Tab key indent the current +line. + + + + + + + + + + +Open & Save + + + + +File Format + + + +Encoding: + +This sets the default character encoding for your files. + + + +End of line: + +Choose your prefered end of line mode for your active +document. You have the choice between &UNIX;, DOS/&Windows; or Macintosh. + + + +Automatic end of line detection + +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. + + + + + + + +Memory Usage + + + +Maximum loaded blocks per file: + +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. +This can cause little delays while navigating in the document; a +larger block count increases the editing speed at the cost of memory. +For normal usage, just choose the highest possible block count: +limit it only if you have problems with the memory usage. + + + + + + + +Automatic Cleanups on Load/Save + + + +Remove trailing spaces + +The editor will automatically eliminate extra spaces at the ends of lines +of text while loading/saving the file. + + + + + + + +Folder Config File + + + +Search depth for config file: + +The editor will search the given number of folder levels upwards +for &kate; config file and load the settings line from it. + + + + + + + +Backup on Save +Backing up on save will cause &kate; to copy the disk file to +<prefix><filename><suffix>' before saving changes. +The suffix defaults to ~ and prefix is empty by +default. + + +Local files + +Check this if you want backups of local files when +saving. + + + +Remote files + +Check this if you want backups of remote files when saving. + + + +Prefix + +Enter the prefix to prepend to the backup file names. + + + +Suffix + +Enter the suffix to add to the backup file names. + + + + + + + + + + + +Highlighting +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. + + + +Highlight: +This is used to choose the language type to +configure. + + + +Informations + + +View the properties of the chosen language highlighting rules: +author name and license. + + + + + +Properties + + + +File extensions: +This is the list of file extensions used to determine which +files to highlight using the current syntax highlight mode. + + +MIME types: +Clicking the wizard button will display a dialog with a list of +all available mime types to choose from.The File Extensions entry will automatically be edited as +well. + + +Priority: +Set the priority of the highlight rule. + + + + + + +Download... + + +Click this button to download new or updated syntax highlight descriptions +from the &kate; website. + + + + + + + + +Filetypes +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. + + + +Filetype: +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. + + +New +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. + + +Delete +To remove an existing filetype, select it from the drop down +box and press the Delete button. + + + + + +Properties of current filetype +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. + + +Name: +The name of the filetype will be the text of the corresponding +menu item. This name is displayed in the +ToolsFiletypes + + + +Section: +The section name is used to organize the file types in +menus. This is also used in the +ToolsFiletypes + menu. + + +Variables: +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.For a full list of known variables, see the +manual. + + +File extensions: +The wildcards mask allows you to select files by filename. A +typical mask uses an asterisk and the file extension, for example +*.txt; *.text. The string is a semicolon-separated list of +masks. + + +MIME types: +Displays a wizard that helps you easily select +mimetypes. + + +Priority: +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. + + + + + + + + +Shortcuts +You can change here the shortcut keys configuration. Select an +action and click on Custom if you want a different shortcut +for this action. +The search line alllows you to look for a specific action and see +its associated shortcut. + + + +Plugins +This tab lists all available plugins and you can check those you +want to use. Once a plugin is checked, the +Configure button is enabled and you can click it +in order to configure the highlighted plugin. + + + + + + + + +Configuring With Document Variables + +Kate variables is kateparts implementation of document variables, similar +to emacs and vi modelines. In katepart, the lines have the format + +kate: VARIABLENAME VALUE; [ VARIABLENAME VALUE; ... ] + +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. + +Here is an example variable line, forcing indentation settings for a C++, +java or javascript file: + +// kate: space-indent on; indent-width 4; mixedindent off; indent-mode cstyle; + + +Only the first and last 10 lines are searched for variable lines. + +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. + + +How kate uses variables + +When reading configuration, katepart looks in the following places +(in that order): + + +The global configuration. +Optional session data. +The "Filetype" configuration. +Document variables in the document itself. +Settings made during editing from menu or command line. + + +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. + +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. + +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: + +BOOL - on|off|true|false|1|0 +INTEGER - any integer number +STRING - anything else + + + + +Available Variables + + +auto-bracketsBOOL +Set auto insertion of brackets on or off. + + + +auto-center-linesINT +Set the number of autocenter lines. + + + +auto-insert-doxygenBOOL +Turn insertion of the leading asterisk in doxygen comments on or +off. This has no effect unless you use the cstyle auto-indenter. + + + +background-colorSTRING +Set the document background color. The value must be something +that can be evaluated to a valid color, for example "#ff0000". + + + +backspace-indentsBOOL +Turn backspace indenting on or off. + + + +block-selectionBOOL +Turn block selection on or off. + + + +bracket-highlight-colorSTRING +Set the color for the bracket highlight. The value must be +something that can be evaluated to a valid color, for example "#ff0000" + + + +current-line-colorSTRING +Set the color for the current line. The value must be +something that can be evaluated to a valid color, for example "#ff0000". + + + +dynamic-word-wrapBOOL +Turns dynamic word wrap on or off. + + + +eol | end-of-lineSTRING +Set the end of line mode. Valid settings are +unix, mac and dos + + + +encodingSTRING +Set the document encoding. The value must be a valid encoding +name, like utf-8. + + + +font-sizeINT +Set the point size of the document font. + + + +fontSTRING +Set the font of the document. The value should be a valid font +name, for example courier. + + + +icon-bar-colorSTRING +Set the icon bar color. The value must be something that can +be evaluated to a valid color, for example #ff0000. + + + +icon-borderBOOL +Set the display of the icon border on or off. + + + +folding-markersBOOL +Set the display of folding markers on or off. + + + +indent-modeSTRING +Set the auto-indentation mode. The options none, +normal, cstyle, csands, +python, xml are recognized. See the section + for details. + + + +indent-widthINT +Set the indentation width. + + + +keep-extra-spacesBOOL +Set wheather to keep extra spaces when calculating indentation width. + + + +keep-indent-profileBOOL +If enabled, prevents unindenting a block if at least one line +has no indentation. + + + +line-numbersBOOL +Set the display of line numbers on or off. + + + +mixed-indentBOOL +Set mixed indentation ala Emacs on or off. + + + +overwrite-modeBOOL +Set overwrite mode on or off. + + + +persistent-selectionBOOL +Set persistent selection on or off. + + + +remove-trailing-spaceBOOL +Set dynamic end of line cleanup on or off. + + + +replace-tabs-saveBOOL +Set tab->space conversion on save on or off. + + + +replace-tabsBOOL +Set dynamic tab->space conversion on or off. + + + +replace-trailing-space-saveBOOL +Set end of line cleanup on save on or off. + + + +schemeSTRING +Set the color scheme. The string must be the name of a color +scheme that exists in your configuration to have any effect. + + + +selection-colorSTRING +Set the selection color. The value must be something that can +be evaluated to a valid color, for example "#ff0000". + + + +show-tabsBOOL +Set the visual TAB character on or off. + + + +smart-homeBOOL +Set smart home navigation on or off. + + + +space-indentBOOL +Set indentation with spaces on or off. + + + +tab-indentsBOOL +Set the TAB key indentation on or off. + + + +tab-widthINT +Set the tab display width. + + + +undo-stepsINT +Set the number of undo steps to remember. + + + +word-wrap-columnINT +Set the hard word wrap width. + + + +word-wrap-marker-colorSTRING +Set the word wrap marker color. The value must be something +that can be evaluated to a valid color, for example "#ff0000". + + + +word-wrapBOOL +Set hard word wrapping on or off. + + + +wrap-cursorBOOL +Set cursor wrapping on or off. + + + + + + + + + diff --git a/doc/kate/fundamentals.docbook b/doc/kate/fundamentals.docbook new file mode 100644 index 000000000..e6beaac58 --- /dev/null +++ b/doc/kate/fundamentals.docbook @@ -0,0 +1,621 @@ + + + + + + + +The Fundamentals + + +If you have ever used a text editor, you will have no problem using +&kate;. In the next two sections, Starting +&kate; and in Working with +&kate;, we'll show you everything you need to get up and running +quickly. + + + +Starting &kate; + + +You can start &kate; from the K menu or from the +command line. + + + +From the Menu + +Open the &kde; program menu by clicking on the +big K icon on the toolbar at the bottom left of your +screen. This will raise the program menu. Move your +cursor up the menu to the Utilities +Editors menu item. A list +of available editors will appear. Choose +&kate;. + + + +Unless you configure &kate; not to, it will load the last files you +edited. See Configuring &kate; to learn +how to toggle this feature on and off. + + + + + +From the Command Line + + +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. + + + + +%kate + + + + +If you have an active connection, and permission, you can take advantage +of &kde;'s network transparency to open files on the internet. + + + + +%kate + + + + +Command Line Options +&kate; accepts following command line options: + + + +kate + + +This lists the most basic options available at the command line. + + + + + +kate + + + +This lists the options available for changing the way &kate; interacts +with &Qt;. + + + + + +kate + + +This lists the options available for changing the way &kate; interacts +with &kde;. + + + + + +kate + name + + +Starts kate with the session name. 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, an instance running this session will be used as +well. + + + + + +kate + URL + + +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 kde application configuration, as well as create a shell alias +in your command intepreter if it supports that. + + + + + +kate + PID + + +Only reuses an instance with the specified PID (Process ID). Used with the + option. + + + + + +kate + encoding +URL +Uses the specified encoding for the document. + + + + +kate + line +URL +Navigates to the specified line after opening the document. + + + + +kate + column +URL +Navigates to the specified column after opening the document. + + + + +kate + +Reads the document content from STDIN. This +is similar to the common option used in many command line +programs, and allows you to pipe command output into &kate;. + + + +kate + +Since &kate; 2.5.1 this standard &kde; 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. + + + +kate + + + +This lists all of the command line options. + + + + + +kate + + + +Lists &kate;'s authors in the terminal window. + + + + + +kate + + + +Lists version information for &Qt;, &kde;, and &kate;. + + + + + +kate + + + +Shows license information. + + + + + + + + +Drag and Drop + +&kate; uses the &kde; 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. + + + + + +Working with &kate; + +Quick Start will show you how to +toggle four simple options that will let you configure some of &kate;'s +more powerful features right away. +Shortcuts lays out some of the default keystroke +shortcuts for those who can't or don't want to use a mouse. + + + +Quick Start + + +This section will describe some of the items on the +Settings menu so that you can quickly configure +&kate; to work the way you want it. + + + 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. + + + +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. + + +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. + + + +You can toggle the Documents and Filesystem Browser window on and off in +WindowTool Views +menu. This menu offers you your first glimpse into &kate;'s power and +flexibility. In this section we'll look at three items: + + + + + + + +Show/Hide Documents + + + + +Toggles the Documents on and off. If the Documents/Filesystem Browser window is +not open, &kate; launches the side bar as a separate, undocked, +window. To dock the window grab the two thin parallel lines above the +tabs by clicking on them with your &LMB; and holding the button +down. Drag the the window into &kate;'s editing window and release the +&LMB; when you have positioned the Documents/Filesystem Browser window as you +prefer. + + + + +If you have grabbed the two parallel lines successfully your mouse +pointer will turn into two crossed arrows as you drag. + + + + + + +Show/Hide +Filesystem Browser + + +Toggles the Filesystem Browser on and off. This menu item is the same as +Show Documents with one difference. Toggling +it on launches the window with the Filesystem Browser on top. + + + + + +Show/Hide +Terminal + + +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. + + + + + + + +Shortcuts + + +Many of &kate;'s keystroke commands (shortcuts) are configurable by +way of the Settings menu. By default +&kate; honors the following key bindings. + + + + + + +Insert + +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. + + +Left Arrow +Move the cursor one character to the left + + +Right Arrow + Move the cursor one character to the right + + +Up Arrow + Move the cursor up one line + + +Down Arrow + Move the cursor down one line + + +Page Up + Move the cursor up one page + + +Page Down +Move the cursor down one page + + +Backspace + Delete the character to the left of the cursor + + +Home + Move the cursor to the beginning of the line + + +End + Move the cursor to the end of the line + + +Delete +Delete the character to the right of the cursor (or any selected +text) + + +&Shift;Left Arrow + Mark text one character to the left + + +&Shift;Right Arrow + Mark text one character to the right + + +F1 + Help + + +&Shift;F1 +What's this? + + +&Ctrl;F + Find + + +F3 + Find again + + +&Ctrl;B +Set a Bookmark + + +&Ctrl;C + Copy the marked text to the clipboard. + + + +&Ctrl;N + New document + + +&Ctrl;P +Print + + + +&Ctrl;Q +Quit - close active copy of editor + + +&Ctrl;R + Replace + + +&Ctrl;S +Save your file. + + +&Ctrl;V + Paste. + + + +&Ctrl;X +Delete the marked text and copy it to the clipboard. + + +&Ctrl;Z +Undo + + +&Ctrl;&Shift;Z +Redo + + + + + + + + + +Using Sessions + +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. + +Sessions are supported in three areas: + + +Command line +options that lets you select and start sessions when launching +kate from the command line. + +The Sessions +menu that lets you switch, save, start and manage your +sessions +Configuration +options that lets you decide how sessions generally should +behave. + + + + +When starting a new session, the GUI configuration of Default +Session 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. + +When a named session is loaded, &kate; will display the session name at +the start of the window title, which then have the form +"Session Name: Document name or +&URL; - &kate;" + +When opening files on the command line with 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 commandline in a new, unnamed +session, configure kate to start a new session pr default in the session page of +the configuration dialog or use with an empty string: +''. + +Since &kate; 2.5.1 the PID of the current instance is +exported to the environment variable KATE_PID. When opening files +from the built in terminal Kate will automatically select the current instance +if nothing else is indicated on the command line. + + +Restoring old style &kate; behavior + +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: + + +Make kate allways start with the +parameter by adding that to the command in the application preferences, +and additionally using a shell alias. +Configure &kate; to load the last used session at startup. + +Configure &kate; to save the file list when closing a session. + +Load the default session once + + + + + + + + + +Getting Help + + + +With &kate; + + + +This manual + + +Offers detailed documentation on all menu commands, +configuration options, tools, dialogs, plugins &etc; as well as +descriptions of of the &kate; window, the editor and various concepts +used in the application. + +Press F1 or use the +Help +Contents menu topic to view this +manual. + + + + +What's This Help + +What's This help offers immediate help with single elements of +graphical windows, such as buttons or other window areas. + +We strive to provide What's This help for any elements for which +it makes sense. It is available throughout the configuration dialog, +and in many other dialogs as well. + +To employ What's This help, press +&Shift;F1 or use the +HelpWhat's +This 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. + + + + +Help Buttons in Dialogs + +Some dialogs have a Help Button. Pressing +it will start the &khelpcenter; and open the relevant +documentation. + + + + + + + +With Your Text Files + +&kate; does not (yet!) provide any means for reading document +related documentation. Depending on the file you are editing, you may +find the Built in +&konsole; helpful for viewing related &UNIX; manual pages or +info documentation, or you can use &konqueror;. + + + + + + diff --git a/doc/kate/highlighted.png b/doc/kate/highlighted.png new file mode 100644 index 000000000..ffb95ec48 Binary files /dev/null and b/doc/kate/highlighted.png differ diff --git a/doc/kate/highlighting.docbook b/doc/kate/highlighting.docbook new file mode 100644 index 000000000..76952d26a --- /dev/null +++ b/doc/kate/highlighting.docbook @@ -0,0 +1,931 @@ + + + + + + + +Working with Syntax Highlighting + + + +Overview + +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. + + + +A Perl function, rendered with syntax +highlighting. +A Perl function, rendered with syntax highlighting. + + + + + +The same Perl function, without +highlighting. +The same Perl function, without highlighting. + + +Of the two examples, which is easiest to read? + +&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. + +&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 +DocumentsHighlight +Mode menu. + +The styles and colors used by each syntax highlight definition +can be configured using the Appearance page of the +Config Dialog, while the &MIME; Types +it should be used for, are handeled by the Highlight +page. + + +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%. + + + +You can download updated or additional syntax highlight +definitions from the &kate; website by clicking the +Download button in the Highlight Page of the Config Dialog. + + + + + + +The &kate; Syntax Highlight System + +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. + + + +How it Works + +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. + +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. + +The syntax definitions used by the &kate; Syntax Highlighting System are +&XML; files, containing + +Rules for detecting the role of text, organized into context blocks +Keyword lists +Style Item definitions + + + +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. + + + + +Rules + +The detection rules are the heart of the highlighting detection +system. A rule is a string, character or regular expression 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. + +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. + + +Contexts may be generated dynamically to allow the usage of instance +specific data in rules. + + + + +Context Styles and Keywords + +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. + +A syntax definition may contain as many styles as required to +cover the concepts of the format it is used for. + +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. + + + + +Default Styles + +If you open a C++ source file, a &Java; source file and an +HTML 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. + +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. + + +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 available default styles +will be explained later. + + + + + + + +The Highlight Definition &XML; Format + + +Overview + +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. + +The formal definition, aka the DTD is stored +in the file language.dtd which should be +installed on your system in the folder +$KDEDIR/share/apps/katepart/syntax. + + + +Main sections of &kate; Highlight Definition files + + +A highlighting file contains a header that sets the XML version and the doctype: + + +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE language SYSTEM "language.dtd"> + + + + + +The root of the definition file is the element language. +Available attributes are: + + +Required attributes: +name sets the name of the language. It appears in the menus and dialogs afterwards. +section specifies the category. +extensions defines file extensions, like "*.cpp;*.h" + +Optional attributes: +mimetype associates files &MIME; Type based. +version specifies the current version of the definition file. +kateversion specifies the latest supported &kate; version. +casesensitive defines, whether the keywords are casesensitiv or not. +priority is necessary if another highlight definition file uses the same extensions. The higher priority will win. +author contains the name of the author and his email-address. +license contains the license, usually LGPL, Artistic, GPL and others. +hidden defines, whether the name should appear in &kate;'s menus. +So the next line may look like this: + +<language name="C++" version="1.00" kateversion="2.4" section="Sources" extensions="*.cpp;*.h" /> + + + + + + +Next comes the highlighting element, which +contains the optional element list and the required +elements contexts and itemDatas. + +list elements contain a list of keywords. In +this case the keywords are class and const. +You can add as many lists as you need. +The contexts element contains all contexts. +The first context is by default the start of the highlighting. There are +two rules in the context Normal Text, which match +the list of keywords with the name somename and a +rule that detects a quote and switches the context to string. +To learn more about rules read the next chapter. +The third part is the itemDatas element. It +contains all color and font styles needed by the contexts and rules. +In this example, the itemData Normal Text, +String and Keyword are used. + + + <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> + + + + + +The last part of a highlight definition is the optional +general section. It may contain information +about keywords, code folding, comments and indentation. + + +The comment section defines with what +string a single line comment is introduced. You also can define a +multiline comments using multiLine with the +additional attribute end. This is used if the +user presses the corresponding shortcut for comment/uncomment. +The keywords section defines whether +keyword lists are casesensitive or not. Other attributes will be +explained later. + + <general> + <comments> + <comment name="singleLine" start="#"/> + </comments> + <keywords casesensitive="1"/> + </general> +</language> + + + + + + + + + + +The Sections in Detail +This part will describe all available attributes for contexts, +itemDatas, keywords, comments, code folding and indentation. + + + +The element context belongs into the group +contexts. A context itself defines context specific +rules like what should happen if the highlight system reaches the end of a +line. Available attributes are: + + + +name the context name. Rules will use this name +to specify the context to switch to if the rule matches. +lineEndContext 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, #stay to not switch the context +(eg. do nothing) or #pop which will cause to leave this +context. It is possible to use for example #pop#pop#pop +to pop three times. +lineBeginContext defines the context if a begin +of a line is encountered. Default: #stay. +fallthrough defines if the highlight system switches +to the context specified in fallthroughContext if no rule matches. +Default: false. +fallthroughContext specifies the next context +if no rule matches. +dynamic if true, the context +remembers strings/placeholders saved by dynamic rules. This is needed for HERE +documents for example. Default: false. + + + + + +The element itemData is in the group +itemDatas. 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: + + +name sets the name of the itemData. +Contexts and rules will use this name in their attribute +attribute to reference an itemData. +defStyleNum defines which default style to use. +Available default styles are explained in detail later. +color defines a color. Valid formats are +'#rrggbb' or '#rgb'. +selColor defines the selection color. +italic if true, the text will be italic. +bold if true, the text will be bold. +underline if true, the text will be underlined. +strikeout if true, the text will be stroked out. + + + + + +The element keywords in the group +general defines keyword properties. Available attributes are: + + +casesensitive may be true +or false. If true, all keywords +are matched casesensitive +weakDeliminator is a list of characters that +do not act as word delimiters. For example the dot '.' +is a word delimiter. Assume a keyword in a list contains +a dot, it will only match if you specify the dot as a weak delimiter. +additionalDeliminator defines additional delimiters. +wordWrapDeliminator defines characters after which a +line wrap may occur. +Default delimiters and word wrap delimiters are the characters +.():!+,-<=>%&*/;?[]^{|}~\, space (' ') +and tabulator ('\t'). + + + + + +The element comment in the group +comments defines comment properties which are used +for ToolsComment and +ToolsUncomment. +Available attributes are: + + +name is either singleLine +or multiLine. If you choose multiLine +the attributes end and region are +required. +start defines the string used to start a comment. +In C++ this would be "/*". +end defines the string used to close a comment. +In C++ this would be "*/". +region should be the name of the the foldable +multiline comment. Assume you have beginRegion="Comment" +... endRegion="Comment" in your rules, you should use +region="Comment". 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. + + + + + +The element folding in the group +general defines code folding properties. +Available attributes are: + + +indentationsensitive if true, 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 false. + + + + + +The element indentation in the group +general 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: + + +mode is the name of the indenter. Available indenters +right now are: normal, cstyle, csands, xml, python and +varindent. + + + + + + + + + + +Available Default Styles +Default Styles were already explained, +as a short summary: Default styles are predefined font and color styles. + + +So here only the list of available default styles: + +dsNormal, used for normal text. +dsKeyword, used for keywords. +dsDataType, used for data types. +dsDecVal, used for decimal values. +dsBaseN, used for values with a base other than 10. +dsFloat, used for float values. +dsChar, used for a character. +dsString, used for strings. +dsComment, used for comments. +dsOthers, used for 'other' things. +dsAlert, used for warning messages. +dsFunction, used for function calls. +dsRegionMarker, used for region markers. +dsError, used for error highlighting and wrong syntax. + + + + + + + + + +Highlight Detection Rules + +This section describes the syntax detection rules. + +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 attribute +defined by the rule, and a rule may ask that the current context is +switched. + +A rule looks like this: + +<RuleName attribute="(identifier)" context="(identifier)" [rule specific attributes] /> + +The attribute identifies the style to use +for matched characters by name, and the context +identifies the context to use from here. + +The context can be identified by: + + + +An identifier, which is the name of the other +context. + + +An order telling the engine to stay in the +current context (#stay), or to pop back to a +previous context used in the string (#pop). +To go back more steps, the #pop keyword can be repeated: +#pop#pop#pop + + + +Some rules can have child rules 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: + + +<RuleName (attributes)> + <ChildRuleName (attributes) /> + ... +</RuleName> + + + +Rule specific attributes varies and are described in the +following sections. + + + +Common attributes +All rules have the following attributes in common and are +available whenever (common attributes) appears. +attribute and context +are required attributes, all others are optional. + + + +attribute: An attribute maps to a defined itemData. + + +context: Specify the context to which the highlighting system switches if the rule matches. + + +beginRegion: Start a code folding block. Default: unset. + + +endRegion: Close a code folding block. Default: unset. + + +lookAhead: If true, the +highlighting system will not process the matches length. +Default: false. + + +firstNonSpace: Match only, if the string is +the first non-whitespace in the line. Default: false. + + +column: Match only, if the column matches. Default: unset. + + + + +Dynamic rules +Some rules allow the optional attribute dynamic +of type boolean that defaults to false. If dynamic is +true, a rule can use placeholders representing the text +matched by a regular expression rule that switched to the +current context in its string or +char attributes. In a string, +the placeholder %N (where N is a number) will be +replaced with the corresponding capture N +from the calling regular expression. In a +char the placeholer must be a number +N and it will be replaced with the first character of +the corresponding capture N from the calling regular +expression. Whenever a rule allows this attribute it will contain a +(dynamic). + + +dynamic: may be (true|false). + + + + +The Rules in Detail + + + +DetectChar + +Detect a single specific character. Commonly used for example to +find the ends of quoted strings. +<DetectChar char="(character)" (common attributes) (dynamic) /> +The char attribute defines the character +to match. + + + + +Detect2Chars + +Detect two specific characters in a defined order. +<Detect2Chars char="(character)" char1="(character)" (common attributes) (dynamic) /> +The char attribute defines the first character to match, +char1 the second. + + + + +AnyChar + +Detect one character of a set of specified characters. +<AnyChar String="(string)" (common attributes) /> +The String attribute defines the set of +characters. + + + + +StringDetect + +Detect an exact string. +<StringDetect String="(string)" [insensitive="true|false"] (common attributes) (dynamic) /> +The String attribute defines the string +to match. The insensitive attribute defaults to +false and is passed to the string comparison +function. If the value is true insensitive +comparing is used. + + + + +RegExpr + +Matches against a regular expression. +<RegExpr String="(string)" [insensitive="true|false"] [minimal="true|false"] (common attributes) (dynamic) /> +The String attribute defines the regular +expression. +insensitive defaults to +false and is passed to the regular expression +engine. +minimal defaults to +false and is passed to the regular expression +engine. +Because the rules are always matched against the beginning of +the current string, a regular expression starting with a caret +(^) indicates that the rule should only be +matched against the start of a line. +See Regular Expressions +for more information on those. + + + + +keyword + +Detect a keyword from a specified list. +<keyword String="(list name)" (common attributes) /> +The String attribute identifies the +keyword list by name. A list with that name must exist. + + + + +Int + +Detect an integer number. +<Int (common attributes) (dynamic) /> +This rule has no specific attributes. Child rules are typically +used to detect combinations of L and +U after the number, indicating the integer type +in program code. Actually all rules are allowed as child rules, though, +the DTD only allowes the child rule StringDetect. +The following example matches integer numbers follows by the character 'L'. + +<Int attribute="Decimal" context="#stay" > + <StringDetect attribute="Decimal" context="#stay" String="L" insensitive="true"/> +</Int> + + + + + + +Float + +Detect a floating point number. +<Float (common attributes) /> +This rule has no specific attributes. AnyChar is +allowed as a child rules and typically used to detect combinations, see rule +Int for reference. + + + + +HlCOct + +Detect an octal point number representation. +<HlCOct (common attributes) /> +This rule has no specific attributes. + + + + +HlCHex + +Detect a hexadecimal number representation. +<HlCHex (common attributes) /> +This rule has no specific attributes. + + + + +HlCStringChar + +Detect an escaped character. +<HlCStringChar (common attributes) /> +This rule has no specific attributes. + +It matches literal representations of characters commonly used in +program code, for example \n +(newline) or \t (TAB). + +The following characters will match if they follow a backslash +(\): +abefnrtv"'?\. Additionally, escaped +hexadecimal numbers like for example \xff and +escaped octal numbers, for example \033 will +match. + + + + + +HlCChar + +Detect an C character. +<HlCChar (common attributes) /> +This rule has no specific attributes. + +It matches C characters enclosed in a tick (Example: 'c'). +So in the ticks may be a simple character or an escaped character. +See HlCStringChar for matched escaped character sequences. + + + + + +RangeDetect + +Detect a string with defined start and end characters. +<RangeDetect char="(character)" char1="(character)" (common attributes) /> +char defines the character starting the range, +char1 the character ending the range. +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. + + + + +LineContinue + +Matches at end of line. +<LineContinue (common attributes) /> +This rule has no specific attributes. +This rule is useful for switching context at end of line, if the last +character is a backslash ('\'). This is needed for +example in C/C++ to continue macros or strings. + + + + +IncludeRules + +Include rules from another context or language/file. +<IncludeRules context="contextlink" [includeAttrib="true|false"] /> + +The context attribute defines which context to include. +If it a simple string it includes all defined rules into the current context, example: +<IncludeRules context="anotherContext" /> + + +If the string begins with ## the highlight system +will look for another language definition with the given name, example: +<IncludeRules context="##C++" /> +If includeAttrib attribute is +true, 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. + + + + + + +DetectSpaces + +Detect whitespaces. +<DetectSpaces (common attributes) /> + +This rule has no specific attributes. +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. + + + + + +DetectIdentifier + +Detect identifier strings (as a regular expression: [a-zA-Z_][a-zA-Z0-9_]*). +<DetectIdentifier (common attributes) /> + +This rule has no specific attributes. +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. + + + + + + + +Tips & Tricks + + +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. + + + +If you only match two characters use Detect2Chars +instead of StringDetect. The same applies to +DetectChar. + + +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 '#' if it is the first character in the +line. A regular expression based solution would look like this: +<RegExpr attribute="Macro" context="macro" String="^\s*#" /> +You can achieve the same much faster in using: +<DetectChar attribute="Macro" context="macro" char="#" firstNonSpace="true" /> +If you want to match the regular expression '^#' you +can still use DetectChar with the attribute column="0". +The attribute column counts character based, so a tabulator still is only one character. + + + +You can switch contexts without processing characters. Assume that you +want to switch context when you meet the string */, but +need to process that string in the next context. The below rule will match, and +the lookAhead attribute will cause the highlighter to +keep the matched string for the next context. +<Detect2Chars attribute="Comment" context="#pop" char="*" char1="/" lookAhead="true" /> + + + +Use DetectSpaces if you know that many whitespaces occur. + + +Use DetectIdentifier instead of the regular expression '[a-zA-Z_]\w*'. + + +Use default styles whenever you can. This way the user will find a familiar environment. + + +Look into other XML-files to see how other people implement tricky rules. + + +You can validate every XML file by using the command +xmllint --dtdvalid language.dtd mySyntax.xml. + + +If you repeat complex regular expression very often you can use +ENTITIES. Example: + +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE language SYSTEM "language.dtd" +[ + <!ENTITY myref "[A-Za-z_:][\w.:_-]*"> +]> + +Now you can use &myref; instead of the regular +expression. + + + + + + + diff --git a/doc/kate/index.docbook b/doc/kate/index.docbook new file mode 100644 index 000000000..fe409a83d --- /dev/null +++ b/doc/kate/index.docbook @@ -0,0 +1,293 @@ + + + + + + + + + + + + + + +]> + + +The &kate; Handbook + + + +&Anders.Lund; &Anders.Lund.mail; +&Seth.Rothberg; &Seth.Rothberg.mail; +&Dominik.Haumann; &Dominik.Haumann.mail; + + + + +2000 +2001 +&Seth.Rothberg; + + +200220032005 +&Anders.Lund; + + +2005 +&Dominik.Haumann; + + +&FDLNotice; + +2005-12-29 +2.5.0 + + +&kate; is a programmer's text editor for &kde; 2.2 and above. + +This handbook documents &kate; Version 2.5.0 + + + +KDE +kdebase +Kate +text +editor +programmer +programming +projects +MDI +Multi +Document +Interface +terminal +console + + + + + +Introduction + + +Welcome to &kate;, a programmer's text editor for &kde; version 2.2 and +above. Some of &kate;'s many features include configurable syntax +highlighting for languages ranging from C and C++ to +HTML to bash scripts, the ability to create and +maintain projects, a multiple document interface +(MDI), and a self-contained terminal emulator. + + + +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;. + + + + + +Editing this manual... + + + + + +&fundamentals-chapter; + +&mdi-chapter; + +&part-chapter; + +&plugins-chapter; + +&advanced-chapter; + +&menu-chapter; + +&configuring-chapter; + + + +Credits and License + + +&kate;. Program copyright 2000, 2001, 2002 - 2005 by the &kate; developer team. + + + +The &kate; team: + +&Christoph.Cullmann; &Christoph.Cullmann.mail; +Project Manager & Core Developer + + +&Anders.Lund; &Anders.Lund.mail; +Core Developer, Perl syntax highlighting, +documentation + + +&Joseph.Wenninger; &Joseph.Wenninger.mail; +Core Developer, syntax highlighting + + +Michael Bartl michael.bartl1@chello.at +Core Developer + + +Phlip phlip_cpp@my-deja.com +The project compiler + + +&Waldo.Bastian; &Waldo.Bastian.mail; +The cool buffer system + + +Matt Newell newellm@proaxis.com +Testing... + + +Michael McCallum gholam@xtra.co.nz +Core Developer + + +Jochen Wilhemly digisnap@cs.tu-berlin.de +KWrite Author + + +&Michael.Koch; &Michael.Koch.mail; +KWrite port to KParts + + +Christian Gebauer gebauer@bigfoot.com +Unspecified + + +&Simon.Hausmann; &Simon.Hausmann.mail; +Unspecified + + +Glen Parker glenebob@nwlink.com +KWrite Undo History, KSpell integration + + +Scott Manson sdmanson@alltel.net +KWrite XML syntax highlighting support + + +&John.Firebaugh; &John.Firebaugh.mail; +Various Patches + + +&Dominik.Haumann; &Dominik.Haumann.mail; +Developer, Highlight wizard + + + + +Many other people have contributed: + +Matteo Merli merlim@libero.it +Highlighting for RPM Spec-Files, Diff and more + + +Rocky Scaletta rocky@purdue.edu +Highlighting for VHDL + + +Yury Lebedev +Highlighting for SQL + + +Chris Ross +Highlighting for Ferite + + +Nick Roux +Highlighting for ILERPG + + +John Firebaugh +Highlighting for Java, and much more + + +Carsten Niehaus +Highlighting for LaTeX + + +Per Wigren +Highlighting for Makefiles, Python + + +Jan Fritz +Highlighting for Python + + +&Daniel.Naber; +Small bugfixes, XML plugin + + + +Documentation copyright 2000,2001 &Seth.Rothberg; +&Seth.Rothberg.mail; + +Documentation copyright 2002, 2003, 2005 &Anders.Lund; +&Anders.Lund.mail; + + + +&underFDL; +&underGPL; + + + +&highlighting-appendix; + +®exp-appendix; + + +Installation + +&install.intro.documentation; + +&install.compile.documentation; + + + +&documentation.index; + + + + + + diff --git a/doc/kate/kate.png b/doc/kate/kate.png new file mode 100644 index 000000000..dc1ee4c40 Binary files /dev/null and b/doc/kate/kate.png differ diff --git a/doc/kate/man-kate.1.docbook b/doc/kate/man-kate.1.docbook new file mode 100644 index 000000000..80899a4fb --- /dev/null +++ b/doc/kate/man-kate.1.docbook @@ -0,0 +1,165 @@ + + +]> + + + +KDE User's Manual +&Lauri.Watts; &Lauri.Watts.mail; +June 07, 2005 +K Desktop Environment + + + +kate +1 + + + +kate +Advanced text editor for &kde; + + + + +kate + +name + + +pid + +name + +line + + column + +KDE Generic Options +Qt Generic Options + + + + +Description +&kate; is the &kde; Advanced Text Editor. +&kate; also provides the editor part for various applications, under +the name &kwrite;. +Some of &kate;'s many features include configurable syntax +highlighting for languages ranging from C and C++ to +HTML to bash scripts, the ability to create and +maintain projects, a multiple document interface +(MDI), and a self-contained terminal emulator. + + + +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;. + + + + + + +Options + + + +, name + +Start &kate; with a given session. + + + +Use an already running &kate; + + + +pid +Only try to reuse kate instance with this +pid + + + +name +Set encoding for the file to openYou can use +this to force a file opened in utf-8 format, for instance. (The command +iconv -l provides a list of encodings, which may be +helpful to you.) + + + line +Navigate to this line + + + +column +Navigate to this column + + + +Read the contents of +stdin + + + + + + +See Also + +kwrite(1) + +More detailed user documentation is available from help:/kate +(either enter this URL into &konqueror;, or run +khelpcenter +help:/kate). + +There is also further information available at the &kate; website. + + + +Examples + +To open a file named source.cpp at column 15, +line 25, in an existing &kate; window, you could use: +kate source.cpp + +If you have an active internet connection, you can take advantage of +&kde;'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. +kate + + + + + + + + +Authors +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. + + + diff --git a/doc/kate/mdi.docbook b/doc/kate/mdi.docbook new file mode 100644 index 000000000..a6c6854db --- /dev/null +++ b/doc/kate/mdi.docbook @@ -0,0 +1,266 @@ + + + +&Anders.Lund; &Anders.Lund.mail; + + + +Working With the &kate; <acronym>MDI</acronym> + + +Overview + +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. + + + +The Main Window + +Main window +The &kate; Main Window is a standard &kde; 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. + +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. + +The docking capabilities of the window is used for the tool +windows: + + +The File List +The Filesystem +Browser +The Built in Terminal Emulator + + +And possibly other tool views, for example provided by +plugins. + +Tool views can be positioned in any sidebar, to move a tool right click +its sidebar button and select from the &RMB; menu + +A tool view can be marked as persistent in the &RMB; +menu for its sidebar button. The sidebar can contain +more tools at one time so that when a tool is persistant other tools can be +shown simultaneously. + + + + + + + + +The Editor area + +Editing Area +&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 +emacs 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. + +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. + +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. + +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). The new +frame gets the focus, which is visualized by a small green led in the +focused frame. + + + + +The Document List + +File list +The file list displays a list of all documents currently open in +&kate;. Modified files will have a small floppy +disk icon on their left to indicate that state. + +If two or more files with the same name (located in different +folders) are open, the names of the second will be prepended +<2> and so on. The tool-tip for the file will +display its full name including the path, allowing you to choose the +desired one. To display a document in the currently +active frame, click the document name in the list. + +You can sort the list in a few different ways by rightclicking the +list and selecting from the Sort By menu. + +The options are + + + +Opening Order +Lists the documents in the order of opening + + + +Document Name +Lists the documents alphabetically by their name. + + + +URL +Lists the documents alphabetically by URL. + + + + + + +The document list will pr 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 +The Document List Page +of the configuration dialog. + +The default location in the &kate; window is to the left of the +editing area. + + + +The Filesystem Browser + +Filesystem Browser +The Filesystem Browser is a folder viewer, allowing you to open +files from a displayed folder in the current frame. + +From top down, the Filesystem Browser consist of the following +elements: + + + +A Toolbar + +This contains standard navigations tool buttons: + + +Home +Pressing it will cause the folder view to cd to your home folder. + + +Up +This will cause the folder view to cd to the immediate parent of the currently displayed +folder if possible. + + +Back +Causes the folder view to cd to the previously displayed folder in the history. +This button is disabled, if there is no previous item. + + +Forward +Causes the folder view to cd to the next folder in the history. +This button is disabled, if there is no next folder. + + +Sync +This button will cause the folder view to +cd 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. + + + + + + + +A &URL; entry + +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. +The &URL; entry has folder auto-completion. The completion +method can be set using the &RMB; menu of the text +entry. + + + + +A Folder View +This is a standard &kde; folder view. + + + +A Filter Entry + +The Filter entry allows you to enter a filter for the files +displayed in the folder view. The filter uses standard globs; patterns +must be separated by white space. Example: *.cpp *.h +*.moc +To display all files, enter a single asterisk +*. +The filter entry saves the last 10 filters entered between +sessions, to use one, press the arrow button on the right of the entry +and select the desired filter string. + + + + + + + + + +The Built in Terminal Emulator + +Terminal emulator +The built in Terminal Emulator is a copy of the &kde; &konsole; +terminal application, for your convenience. It is available from the +SettingsShow Terminal +Emulator menu item or by pressing the F7 key, and will get the focus +whenever displayed. Additionally, if the Sync &konsole; with +active document option is enabled, it will +change into the directory of the current document if +possible when it is displayed, or when the current document +changes. + +The default location in the &kate; window is at the bottom, +below the editing area. + +You can configure the &konsole; using its &RMB; menu, for more +information, see the &konsole; manual. + + + + +External Tools + +In the Tools menu you will find a submenu labeled +External Tools. These tools invokes external +applications with data related to the current document, for example its URL, +directory, text or selection. + +External tools are user defined, you can add, edit or remove tools using +the External Tools configuration panel. + + + + + diff --git a/doc/kate/menus.docbook b/doc/kate/menus.docbook new file mode 100644 index 000000000..26ae7551e --- /dev/null +++ b/doc/kate/menus.docbook @@ -0,0 +1,1438 @@ + + + + + + + +Menu Entries + + +The <guimenu>File</guimenu> Menu + + + + + + + +&Ctrl;N + +File +New + + + + +This command starts a new document in the editing +window. In the Documents list on the left the new file +is named Untitled. + + + + + + + + + +&Ctrl;O + +File +Open... + + + +Launches &kde;'s open file dialog box to let you open one or more files. + + + + + + + + + +File +Open Recent + + + + +This command allows you to open a file from a submenu +that contains a list of recently edited files. + + + + + + + + +File +Open With + + + + +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. +In addition, a entry Other... command launches +the open with dialog box that allows you to select another application +to open the active file. Your file will still be open in &kate;. + + + + + + + + + +&Ctrl;S + +File +Save + + + + +This command saves your file. Use it often. If the file is +Untitled then +Save becomes +Save As. + + + + + + + + +File +Save As... + + + + +Name and rename files 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. + + + +Type the name you want to give the file you are saving in the +Location combo box and press the +OK button. + + + + + + + + + +&Ctrl;L + +File +Save All + + + + +This command saves all modified open files. + + + + + + + + + +F5 + +File +Reload + + + + +Reloads the active file. This command is +useful if another program or process has changed the file while you have +it open in &kate; + + + + + + + + + +&Ctrl;P + +File +Print... + + + + +Print the active file. + + + + + + + +File +Export as HTML... + + + + +Export your file in HTML format so your document can be viewed as a +web page. + + + + + + + +File +Mail... + + + + +Open your mail client and attach the file in the mail. + + + + + + + + + +&Ctrl;W + +File +Close + + + + +Close the active file with this command. If you +have made unsaved changes, you will be prompted to save +the file before &kate; closes it. + + + + + + + + +File +Close All + + + + +This command closes all the files you have open +in &kate;. + + + + + + + + + +&Ctrl;Q + +File +Quit + + + + +This command closes &kate; 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. + + + + + + + +The <guimenu>Edit</guimenu> Menu +The Edit menu contains a host of commands, +all to work with the currently active document. + + +Menu Entries + + + + +&Ctrl;Z +Edit +Undo + + + +Undo the last editing command (typing, copying, cutting etc.) +If grouped undo is enabled, this may undo several editing commands of the same type, like typing in characters. + + + + + + + +&Ctrl;&Shift;Z +Edit +Redo + + + +Redo the last undo step. + + + + + + + +&Ctrl;X +Edit +Cut + + + +Removes selected text if any, and places a copy of the removed text in the clipboard. + + + + + + + +&Ctrl;C +Edit +Copy + + + +Copies selected text, if any, to the clipboard. + + + + + + + +Edit +Copy as HTML + + + +Copies selected text with the syntax highlight as HTML text. + + + + + + + +&Ctrl;V +Edit +Paste + + + +Copies the first item in the clipboard into the editor at cursor position. +If Overwrite Selection is enabled, the pasted text will overwrite the selection, if any. + + + + + + + +&Ctrl;A +Edit +Select All + + + +Selects all text in the editor. + + + + + + + +&Ctrl;&Shift;A +Edit +Deselect + + + +Deselects the selected text in the editor if any. + + + + + + + +&Ctrl;Shift +B +Edit +Block Selection Mode + + + +Toggles Selection Mode. When the Selection Mode is BLOCK, you can make vertical selections, +ie select column 5 to 10 in lines 9 to 15. +The status bar shows the current state of the Selection Mode, either NORM or BLK. + + + + + + + +&Ctrl;F +Edit +Find... + + + +Launch the Find Dialog to allow you to search for text in the edited document. + + + + + + + +F3 +Edit +Find Next + + + +Go to the nearest downwards match of the last text or regular expression searched for, starting from cursor position + + + + + + + +&Shift;F3 +Edit +Find Previous + + + +Go to the nearest upwards match of the last text or regular expression searched for, starting from cursor position + + + + + + + +&Ctrl;R +Edit +Replace... + + + +Launch the Replace Dialog to replace one or more instances of a defined text with something else. + + + + + + + +&Ctrl;G +Edit +Go to line... + + + +Launches the Go To Line Dialog, allowing you to enter the number of a line to find in +the document + + + + + + + + +The <guimenu>Document</guimenu> Menu +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. +In addition, commands to browse your open documents are provided: + +Menu items + + + + + +&Alt;Left +Document +Back + + + +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. The order is the order in which documents were +opened, rather than a logical history. This behavior may change in future +versions of &kate;. + + + + + + + +&Alt;Right +Document +Forward + + + +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. +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;. + + + + + + + +The <guimenu>View</guimenu> menu + +The View menu allows you to manage settings +specific to the active editor, and to manage frames. + + +Menu Items + + +F7 +ViewSwitch to Command Line + +This command will toggle the display of the +built in command line. + + + + +ViewSchema + +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 config dialog + + + + +F10 + +ViewDynamic Word Wrap + +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. + + + + +ViewShow/Hide Static Word +Wrap Marker +Toggles the display of a vertical line indicating the position +of the wrap width as configured in the config dialog. This +feature requires that you use a true fixed-width font. + + + + + + + +F6 +View +Show/Hide Icon Border + + + +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. + + + + + + + +F11 +View +Show/Hide Line Numbers + + + +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. + + + + +ViewShow/Hide Scrollbar +Marks +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. + + + +F9 + +ViewShow/Hide Folding Markers + +Toggles the display of the folding marker pane in the left +side of the view. See Using +Code Folding. + + + + + + +Code Folding + + + + + + +&Ctrl; +Shift- +Collapse Toplevel + +Collapse all toplevel regions in the document. + + +&Ctrl; +Shift+ +Expand Toplevel + +Expand all toplevel regions in the document. + + +&Ctrl; +- +Collapse One Local Level + +Collapse the region closest to the cursor. + + +&Ctrl; ++ +Expand One Local Level + +Expand the region closest to the cursor. + + + + + + + + + + + +The <guimenu>Bookmarks</guimenu> Menu + +The Bookmarks menu allows you to work with +the bookmarks in the currently active document. + +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. + + + +Menu Items + + + + + +&Ctrl;B +Bookmarks +Set/Clear Bookmark + + + +Sets or removes a bookmark in the current line of the active document. +(If it's there, it is removed, otherwise one is set.) + + + + + + + +Bookmarks +Clear All Bookmarks + + + +Clears (removes) all bookmarks in the active document. + + + + +&Alt; +Page Up +BookmarksPrevious + +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. + + + +&Alt; +Page Down +BookmarksNext +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. + + + + + + + + +The <guimenu>Tools</guimenu> Menu + + + + +ToolsPipe to +Console +Feed the currently selected text ito the built in terminal +emulator. No newline is added after the text. + + + +ToolsExternal +Tools +This submenu contains all the external toolsyou have +configured. + + + + +Tools +Read Only Mode + +Set the current document to Read Only mode. This prevents any text +addition and any changes in the document formatting. + + + + + +Tools +Filletype + +Choose the filetype scheme you prefer for the active document. This +overwrites the global filetype +mode set in Settings Configure +Editor... in the Filetypes tab for your current +document only. + + + + + +Tools +Highlighting + +Choose the Highlighting scheme you prefer for the active document. This +overwrites the global highlighting mode set in +Settings Configure Editor... + for your current document only. + + + + + +Tools +Indentation + +Choose the style of +indentation you want for your active document. +This overwrites the global indentation mode set in +Settings Configure Editor... + for your current document only. + + + + + +Tools +Encoding + +You can overwrite the default encoding set in +Settings +Configure +Editor... in the Open/Save tab +to set a different encoding for your current document. The encoding you +set here will be only valid for your current document. + + + + + +Tools +End of Line + +Choose your prefered end of line mode for your active +document. This overwrites the global end of line mode set in +Settings Configure Editor... + for your current document only. + + + + + +ToolsSpelling... + + +This initiates the spellchecking program - a program +designed to help the user catch and correct any spelling errors. +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: + + + +Unknown word: +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. + + +Replace with: + 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. + + +Suggested Words: + 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 Replacement: box, +above. + + +Language: + If you have installed multiple dictionaries, here you can +select which dictionary/language should be used. + + + +On the right side of the dialog box are 5 buttons that allow the user to +control the spellcheck process. They are: + + + +Add to Dictionary +Pressing this button adds the word in the Misspelled +Word: box to the checker's dictionary. This means that in the future +the checker will always consider this word to be correctly +spelled. + + +Replace + This button has the checker replace the word under +consideration in the document with the word in the +Replacement: box. + + +Replace All + This button causes the checker to replace not only the current +Unknown word: but to automatically make the same +substitution for any other occurrences of this Misspelled +Word: in the document. + + +Ignore +Activating this button will have the checker move on without +making any changes. + + +Ignore All + This button tells the checker to do nothing with the current +Unknown word: and to pass over any other instances of +the same word. This only applies to the current spellcheck +run. If the checker is run again later it will stop on this same +word. + + + +Three more buttons are located horizontally along the bottom of the +spellcheck dialog. They are: + + + +Help + This invokes the &kde; help system starting at the &kate; help +pages (this document). + + + +Finished + This button ends the spellcheck process, and returns to the +document. + + + +Cancel + This button cancels the spellcheck process, all modifications +are reverted, and you will return to your document. + + + + + + + + + +Tools +Spelling (from cursor)... + +This initiates the spellchecking program but it starts where your cursor +is instead of at the beginning of the document. + + + + + +Tools +Spellcheck Selection... + +Spellchecks the current selection. + + + + + + +&Ctrl;I + +ToolsIndent + +This increases the paragraph's indentation by one step. The size of the +step depends on the indentation +settings. + + + + + + +&Ctrl;&Shift;I + +ToolsUnindent + + +This reduces the paragraph's indentation by one step. The size of the step + +depends on the indentation settings. + + + + + + +ToolsClean +Indentation +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. + + + + + +Tools +Align + + +Causes a realign of the current line or selected lines using the +indentation mode and indentation settings in the doucment. + + + + + + +&Ctrl;D + +Tools +Comment + +This adds one space to the beginning of the line +where the text cursor is located or to the beginning of any +selected lines. + + + + + + +&Ctrl;&Shift;D + +Tools +Uncomment + +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. + + + + + +&Ctrl;U + +Tools +Uppercase + +Put the selected text or the letter after the cursor in +uppercase. + + + + + +&Ctrl;&Shift;U + +Tools +Lowercase + +Put the selected text or the letter after the cursor in +lowercase. + + + + + +&Alt;&Ctrl;U + +Tools +Capitalize + +Capitalize the selected text or the current +word. + + + + + +&Ctrl;J + +Tools +Join Lines + +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. + + + + +Tools +Word Wrap Document + +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 +SettingsConfigure +Editor... + + + + + + + + +The <guimenu>Sessions</guimenu> Menu + +This menu contains entries for using and managing &kate; sessions. +For more information, read Using Sessions. + + + + +Sessions +New +Creates a new empty session. All currently open files will +be closed. + + + + +SessionsOpen... + +Open an existing session. The Session Chooser dialog is +displayed to let you choose one. + + + +SessionsQuick Open + +This submenu lets you open an existing session. + + + + +SessionsSave + +Save the current session. If the session is anonymous, you will +be prompted for a session name. + + + +SessionsSave +As... +Save the current session under a new name. You are prompted for +a name to use. + + + +SessionsManage... + +Displays the Session Manager dialog which allows you to rename +and delete sessions. + + + + + + + + + +The <guimenu>Settings</guimenu> Menu + +The Settings menu allows you to change the properties +of the main window, such as showing/hiding toolbars, and provides +access to the configuration dialogs. + + + + + + + +Settings +Toolbars + + + +This submenu lists the available toolbars, each item toggles the display +of the associated toolbar. + + + + +SettingsFull Screen +Mode +Toggles full screen display. +This commmand will be moved to the Window menu in a future +version of &kate; + + + + + + + +Settings +Configure Shortcuts... + + + +Display the familiar &kde; Keyboard Shortcut Configuration +Dialog. + + + + + + + + +Settings +Configure Toolbars... + + + +Display the familiar &kde; Toolbar Configuration Dialog. + + + + + + + +Settings +Configure &kate;... + + + +Launch the Main Configuration Dialog + + + + + + + + +the <guimenu>Window</guimenu> Menu + + + + + + +Window +New Window + + + + +Opens another instance of &kate;. +The new instance will be identical to your previous instance. + + + + + + + + +&Ctrl;&Shift;L +Window +Split Vertical + + + +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. +See also Working with the &kate; MDI + + + + + + + +&Ctrl;&Shift;T +Window +Split Horizontal + + + +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. +See also Working with the &kate; MDI + + + + + + + +&Ctrl;&Shift;R +Window +Close Current + + + +Closes the active frame. This is disabled, if there is only one frame +(the main editing area). No documents get closed by closing a +frame – they will still be available in the Documents Menu as well as in +the File List. See also Working with the +&kate; MDI + + + + +F8 +WindowNext +View +Focus the next document view, if you have split the editor area +in more views. + + + +&Shift;F8 +WindowPrevious +View +Focus the previous document view, if you have split the editor +area in more views. + + + +WindowTool Views + + + + + +WindowTool Views +Show/Hide Sidebars +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. + + + + + + +WindowTool Views +Show Documents + + + +Toggle the display of &kate;'s Documents list + + + + + + + +WindowTool Views +Show/Hide Filesystem Browser + + + +Toggle the display of &kate;'s Filesystem Browser + + + + + + + +WindowTool Views +Show/Hide Find in Files + + + +Toggle the display of &kate;'s Find in Files tool. + + + + + + + + +WindowTool Views +Show/Hide Terminal + + + +Toggles the display of the built in terminal emulator. +When activated the first time, the terminal will be created. +When the terminal emulator is displayed, it will get the focus, so that +you can start typing in commands immediately. If the Sync Konsole with Active +Document option is enabled in the General Page of the Main configuration dialog the shell session will +change to the directory of the active document, if it is a local file. + + + + + + + + + + + + + + +The <guimenu>Help</guimenu> Menu + +Apart from standard &kde; Help menu items +described below you will have menu entries to show the +Plugins User Manuals for installed plugins. + +&help.menu.documentation; + + + + diff --git a/doc/kate/mimetypechooser.png b/doc/kate/mimetypechooser.png new file mode 100644 index 000000000..45220f8a4 Binary files /dev/null and b/doc/kate/mimetypechooser.png differ 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'). + + + + + + + + + + + + + diff --git a/doc/kate/plugins.docbook b/doc/kate/plugins.docbook new file mode 100644 index 000000000..a097cb526 --- /dev/null +++ b/doc/kate/plugins.docbook @@ -0,0 +1,28 @@ + + + + +&Anders.Lund; &Anders.Lund.mail; + + + + +Working with Plug-ins + +Kate is using two different forms of plug-ins, namely plug-ins for the +&kate; application and plug-ins 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 plug-ins are specific +to the &kate; application. + +You can enable both types of plug-ins in the configuration dialog, which also +provides access to additional configuration options for plug-ins that requires +that. + +There are many plugins for various purposes available in the kdeaddons +module, and you can search the web for more. A few plugins are shipped with the +editor component, for doing word completion, automatic bookmarks, insert files, +thesaurus and word spell checking and incremental search. + + 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 @@ + + + +&Anders.Lund; &Anders.Lund.mail; + + + + +Regular Expressions + + This Appendix contains a brief but hopefully sufficient and +covering introduction to the world of regular +expressions. 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 +grep. + + + +Introduction + +Regular Expressions 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. + +An example: Say you want to search a text for paragraphs that +starts with either of the names Henrik or +Pernille followed by some form of the verb +say. + +With a normal search, you would start out searching for the +first name, Henrik maybe followed by sa +like this: Henrik sa, 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 sa was not either says, +said or so. And then of cause repeat all of that with +the next name... + +With Regular Expressions, that task could be accomplished with a +single search, and with a larger degree of preciseness. + +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: A line +starting with either Henrik or Pernille +(possibly following up to 4 blanks or tab characters) followed by a +whitespace followed by sa and then either +ys or id could be expressed with +the following regular expression: ^[ +\t]{0,4}(Henrik|Pernille) sa(ys|id) + +The above example demonstrates all four major concepts of modern +Regular Expressions, namely: + + +Patterns +Assertions +Quantifiers +Back references + + +The caret (^) starting the expression is an +assertion, being true only if the following matching string is at the +start of a line. + +The stings [ \t] and +(Henrik|Pernille) sa(ys|id) are patterns. The first +one is a character class that matches either a +blank or a (horizontal) tab character; the other pattern contains +first a subpattern matching either Henrik +or Pernille, then a piece +matching the exact string sa and finally a +subpattern matching either ys +or id + +The string {0,4} is a quantifier saying +anywhere from 0 up to 4 of the previous. + +Because regular expression software supporting the concept of +back references 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. + +All together, the expression will match where we wanted it to, +and only there. + +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. + + + + + +Patterns + +Patterns consists of literal strings and character +classes. Patterns may contain sub-patterns, which are patterns enclosed +in parentheses. + + +Escaping characters + +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 escaped to let the regular +expression software know that it should interpret such characters in +their literal meaning. + +This is done by prepending the character with a backslash +(\). + + +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 j (\j) is +safe. If you are in doubt whether a character could have a special +meaning, you can therefore escape it safely. + +Escaping of cause includes the backslash character it self, to +literally match a such, you would write +\\. + + + + +Character Classes and abbreviations + +A character class 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, [], or by using one of +the abbreviated classes described below. + +Simple character classes just contains one or more literal +characters, for example [abc] (matching either +of the letters a, b or c) +or [0123456789] (matching any digit). + +Because letters and digits have a logical order, you can +abbreviate those by specifying ranges of them: +[a-c] is equal to [abc] +and [0-9] is equal to +[0123456789]. Combining these constructs, for +example [a-fynot1-38] is completely legal (the +last one would match, of cause, either of +a,b,c,d, +e,f,y,n,o,t, +1,2,3 or +8). + +As capital letters are different characters from their +non-capital equivalents, to create a caseless character class matching +a or b, in any case, you need to write it +[aAbB]. + +It is of cause possible to create a negative +class matching as anything but To do so put a caret +(^) at the beginning of the class: + +[^abc] will match any character +but a, b or +c. + +In addition to literal characters, some abbreviations are +defined, making life still a bit easier: + + + + +\a + This matches the ASCII bell character (BEL, 0x07). + + + +\f + This matches the ASCII form feed character (FF, 0x0C). + + + +\n + This matches the ASCII line feed character (LF, 0x0A, Unix newline). + + + +\r + This matches the ASCII carriage return character (CR, 0x0D). + + + +\t + This matches the ASCII horizontal tab character (HT, 0x09). + + + +\v + This matches the ASCII vertical tab character (VT, 0x0B). + + +\xhhhh + + This matches the Unicode character corresponding to +the hexadecimal number hhhh (between 0x0000 and 0xFFFF). \0ooo (&ie;, +\zero ooo) matches the ASCII/Latin-1 character +corresponding to the octal number ooo (between 0 and +0377). + + + +. (dot) + This matches any character (including newline). + + + +\d + This matches a digit. Equal to [0-9] + + + +\D + This matches a non-digit. Equal to [^0-9] or [^\d] + + + +\s + This matches a whitespace character. Practically equal to [ \t\n\r] + + + +\S + This matches a non-whitespace. Practically equal to [^ \t\r\n], and equal to [^\s] + + + +\w +Matches any word character - in this case any letter or digit. Note that +underscore (_) is not matched, as is the case with perl regular expressions. +Equal to [a-zA-Z0-9] + + + +\W +Matches any non-word character - anything but letters or numbers. +Equal to [^a-zA-Z0-9] or [^\w] + + + + + + + +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 +[\w \.] + + The POSIX notation of classes, [:<class +name>:] is currently not supported. + + +Characters with special meanings inside character classes + +The following characters has a special meaning inside the +[] character class construct, and must be escaped to be +literally included in a class: + + + +] +Ends the character class. Must be escaped unless it is the very first character in the +class (may follow an unescaped caret) + + +^ (caret) +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. + + +- (dash) +Denotes a logical range. Must always be escaped within a character class. + + +\ (backslash) +The escape character. Must always be escaped. + + + + + + + + + + +Alternatives: matching <quote>one of</quote> + +If you want to match one of a set of alternative patterns, you +can separate those with | (vertical bar character). + +For example to find either John or Harry you would use an expression John|Harry. + + + + + +Sub Patterns + +Sub patterns are patterns enclosed in +parentheses, and they have several uses in the world of regular +expressions. + + + +Specifying alternatives + +You may use a sub pattern to group a set of alternatives within +a larger pattern. The alternatives are separated by the character +| (vertical bar). + +For example to match either of the words int, +float or double, you could use the +pattern int|float|double. If you only want to +find one if it is followed by some whitespace and then some letters, +put the alternatives inside a subpattern: +(int|float|double)\s+\w+. + + + + + +Capturing matching text (back references) + +If you want to use a back reference, use a sub pattern to have +the desired part of the pattern remembered. + +For example, it you want to find two occurrences of the same +word separated by a comma and possibly some whitespace, you could +write (\w+),\s*\1. The sub pattern +\w+ 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 \1 references the first sub pattern +enclosed in parentheses) + + + + + + +Lookahead Assertions + +A lookahead assertion is a sub pattern, starting with either +?= or ?!. + +For example to match the literal string Bill but +only if not followed by Gates, you could use this +expression: Bill(?! Gates). (This would find +Bill Clinton as well as Billy the kid, +but silently ignore the other matches.) + +Sub patterns used for assertions are not captured. + +See also Assertions + + + + + + +Characters with a special meaning inside patterns + +The following characters have meaning inside a pattern, and +must be escaped if you want to literally match them: + + + + +\ (backslash) +The escape character. + + + +^ (caret) +Asserts the beginning of the string. + + + +$ +Asserts the end of string. + + + +() (left and right parentheses) +Denotes sub patterns. + + + +{} (left and right curly braces) +Denotes numeric quantifiers. + + + +[] (left and right square brackets) +Denotes character classes. + + + +| (vertical bar) +logical OR. Separates alternatives. + + + ++ (plus sign) +Quantifier, 1 or more. + + + +* (asterisk) +Quantifier, 0 or more. + + + +? (question mark) +An optional character. Can be interpreted as a quantifier, 0 or 1. + + + + + + + + + + + +Quantifiers + +Quantifiers allows a regular expression to +match a specified number or range of numbers of either a character, +character class or sub pattern. + +Quantifiers are enclosed in curly brackets ({ +and }) and have the general form +{[minimum-occurrences][,[maximum-occurrences]]} + + +The usage is best explained by example: + + + + +{1} +Exactly 1 occurrence + + + +{0,1} +Zero or 1 occurrences + + + +{,1} +The same, with less work;) + + + +{5,10} +At least 5 but maximum 10 occurrences. + + + +{5,} +At least 5 occurrences, no maximum. + + + + + + +Additionally, there are some abbreviations: + + + + +* (asterisk) +similar to {0,}, find any number of occurrences. + + + ++ (plus sign) +similar to {1,}, at least 1 occurrence. + + + +? (question mark) +similar to {0,1}, zero or 1 occurrence. + + + + + + + + +Greed + +When using quantifiers with no maximum, regular expressions +defaults to match as much of the searched string as possible, commonly +known as greedy behavior. + +Modern regular expression software provides the means of +turning off greediness, 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 Minimal +matching as well as it ought to indicate if greediness is the +default behavior. + + + + +In context examples + +Here are a few examples of using quantifiers + + + + +^\d{4,5}\s +Matches the digits in 1234 go and 12345 now, but neither in 567 eleven +nor in 223459 somewhere + + + +\s+ +Matches one or more whitespace characters + + + +(bla){1,} +Matches all of blablabla and the bla in blackbird or tabla + + + +/?> +Matches /> in <closeditem/> as well as +> in <openitem>. + + + + + + + + + +Assertions + +Assertions allows a regular expression to +match only under certain controlled conditions. + +An assertion does not need a character to match, it rather +investigates the surroundings of a possible match before acknowledging +it. For example the word boundary 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. + +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. + +Regular Expressions as documented here supports the following +assertions: + + + + +^ (caret: beginning of +string) +Matches the beginning of the searched +string. The expression ^Peter will +match at Peter in the string Peter, hey! +but not in Hey, Peter! + + + +$ (end of string) +Matches the end of the searched string. + +The expression you\?$ will match at the +last you in the string You didn't do that, did you? but +nowhere in You didn't do that, right? + + + + + +\b (word boundary) +Matches if there is a word character at one side and not a word character at the +other. +This is useful to find word ends, for example both ends to find +a whole word. The expression \bin\b will match +at the separate in in the string He came in +through the window, but not at the in in +window. + + + + +\B (non word boundary) +Matches wherever \b does not. +That means that it will match for example within words: The expression +\Bin\B will match at in window but not in integer or I'm in love. + + + + +(?=PATTERN) (Positive lookahead) +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 PATTERN of the assertion, but the text matched by that will +not be included in the result. +The expression handy(?=\w) will match at handy in +handyman but not in That came in handy! + + + + +(?!PATTERN) (Negative lookahead) + +The negative lookahead prevents a possible match to be +acknowledged if the following part of the searched string does match +its PATTERN. +The expression const \w+\b(?!\s*&) +will match at const char in the string const +char* foo while it can not match const QString +in const QString& bar because the +& matches the negative lookahead assertion +pattern. + + + + + + + + + + + + diff --git a/doc/kate/unhighlighted.png b/doc/kate/unhighlighted.png new file mode 100644 index 000000000..6361032f3 Binary files /dev/null and b/doc/kate/unhighlighted.png differ -- cgit v1.2.1