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/advanced.docbook | 1242 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1242 insertions(+) create mode 100644 doc/kate/advanced.docbook (limited to 'doc/kate/advanced.docbook') 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. + + + + + + + + -- cgit v1.2.1