&Anders.Lund; &Anders.Lund.mail;
&Dominik.Haumann; &Dominik.Haumann.mail;
Antoni
Bella

    bella5@teleline.es

Traductor

# Eines d'edició avançades

## Comenta/descomenta

Els comandaments Comenta i Descomenta, disponibles des del menú Eines us permeten afegir o eliminar marques de comentari per a la selecció, o de la línia actual si no hi ha cap selecció. El format dels comentaris dependrà del format del text que estigueu editant.

Les regles que determinen com hauran de ser els comentaris s'estableixen en les definicions de sintaxi, de manera que si no s'usa el ressaltat de la sintaxi, no serà possible fer això.

Alguns formats defineixen marques de comentaris d'una sola línia, d'altres de diverses línies i d'altres usen ambdues possibilitats. Si no estan disponibles les marques de comentaris de diverses línies, no serà possible comentar una selecció en que l'última línia d'aquesta no estigui inclosa completament.

Si està disponible una marca de comentari d'una sola línia, es preferible comentar les línies individualment, atès que així s'eviten problemes de comentaris aniuats.

En eliminar les marques de comentari, s'haurà de seleccionar el text sense comentar. En eliminar les marques de comentari multilínia d'una selecció, s'ignorarà qualsevol espai en blanc que quedi fora de les marques de comentari.

Per a posar marques de comentari, useu l'ítem del menú Eines Comenta o la drecera de teclat corresponent, per omissió és &Ctrl;D.

Per eliminar les marques de comentari, useu l'ítem del menú Eines Descomenta o la drecera de teclat corresponent, per omissió és &Ctrl;&Maj;D.

## El component línia de comandaments de l'editor

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 View Switch 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.

La línia de comandaments té un sistema d'ajuda integrat, escriviu el comandament `help` per iniciar-lo. Per a ver una llista de tots els comandaments disponibles escriviu `help list`, per a veure l'ajuda específica d'un comandament, escriviu `help comandament`.

La línia de comandaments té integrat un historial, de manera que podreu tornar a usar els comandaments ja teclejats. Per a navegar a través de l'historial, useu les tecles Amunt i Avall. Quan es mostrin els comandaments de l'historial, restarà seleccionada la part de l'argument, permetent-vos tronar a escriure'ls amb facilitat.

### Comandaments estàndard de la línia de comandaments

#### Comandaments per a configurar l'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.

##### Tipus d'arguments

BOOLEAN

  Aquest s'usa amb comandaments que activen o desactiven coses. Els valors acceptats son: `on`, `off`, `true`, `false`, `1` o `0`

INTEGER

  Un número enter.

STRING

  Una cadena.

    set-tab-widthINTEGER amplada

  Estableix l'amplada de la pestanya al número `amplada`

    set-indent-widthINTEGER amplada

  Estableix l'amplada del sagnat al número `amplada`. Tan sols s'usa si esteu sagnant amb espais.

    set-word-wrap-columnINTEGER amplada

  Estableix l'amplada per a l'ajust de línia al número `amplada`. Tan sols s'usa si teniu l'ajust de línia automàtic.

    set-icon-borderBOOLEAN enable

  Estableix la visibilitat de la vora d'icones.

    set-folding-markersBOOLEAN habilita

  Estableix la visibilitat de les marques plegables al plafó.

    set-line-numbersBOOLEAN habilita

  Estableix la visibilitat dels números de línia al plafó.

    set-replace-tabsBOOLEAN habilita

  Si està habilitat, es substitueixen els espais de tabulació per espais normals mentre aneu escrivint.

    set-remove-trailing-spaceBOOLEAN habilita

  Si està habilitat, els espais en blanc de marca seran eliminats en el moment en que el cursor surti d'una línia.

    set-show-tabsBOOLEAN habilita

  Si està habilitat, els caràcters de tabulació i espais en blanc de marca es veuran com un punt petit.

    set-indent-spacesBOOLEAN habilita

  Si està habilitat, l'editor farà un sagnat amb `indent-width` espais per a cada nivell de sagnat, en comptes de amb un caràcter de tabulació.

    set-mixed-indentBOOLEAN habilita

  Si està habilitat, el kate usarà una mescla de tabulacions i espais per al sagnat. Cada nivell de sagnat serà `indent-width` d'amplada, i els diferents nivells de sagnat s'optimitzaran usant el màxim de caràcters de tabulació com sigui possible.

  Quan s'executa, aquest comandament habilita el sagnat amb espais, i si no s'especifica l'amplada se li assignarà un valor igual a la meitat de `tab-width` per al document en temps d'execució.

    set-word-wrapBOOLEAN habilita

  Habilita l'ajust de línia dinàmic d'acord amb el valor de `habilita`

    set-replace-tabs-saveBOOLEAN enable

  Quan està habilitat, les tabulacions seran substituïdes amb espais en blanc al desar el document.

    set-remove-trailing-space-saveBOOLEAN habilita

  Quan està habilitat, s'eliminen els espais de marca de cada línia al desar el document.

    set-indent-modenom

  Estableix el mode de sagnat automàtic a `nom`. Si `nom` és desconegut, el mode seleccionat serà 'none'. Els modes vàlids són 'cstyle', 'csands', 'xml', 'python', 'varindent' i 'none'.

    set-highlightressaltat

  Sets the syntax highlighting system for the document. The argument must be a valid highlight name, as seen in the Tools Highlighting menu. This command provides an autocompletion list for its argument.

#### Comandaments per a l'edició

These commands modify the current document.

    indent

  Sagna les línies seleccionades o la línia actual.

    unindent

  Treu el sagnat de les línies seleccionades o la línia actual.

    cleanindent

  Treu el sagnat de les línies seleccionades o la línia actual d'acord amb les opcions de sagnat que tingueu establertes al document.

    comment

  Insereix marques de comentari fent que la selecció, les línies seleccionades o la línia actual siguin un comentari d'acord amb el format de text que s'hagi definit a la sintaxi de ressaltat per al document.

    uncomment

  Elimina les marques de comentari de la selecció, de les línies seleccionades o la línia actual, d'acord amb el format del text tal i com és definit per la definició de ressaltat de la sintaxi per al document.

    kill-line

  Elimina la línia actual.

    replacepatrósubstitució

  Substitueix el text en que coincideixi el `patró` amb el valor de `substitució`. Si voleu incloure espais en blanc en el `patró`, haureu de posar entre cometes tan el `patró` com la `substitució` amb cometes simples o dobles. Si els arguments no són entre cometes, la primera paraula s'usarà com a `patró` i la resta com a `substitució`. Si la `substitució` és buida, cada ocurrència de `patró` serà eliminada.

  Podeu establir etiquetes per a configurar la recerca afegint dos punts, seguits d'una o més lletres cadascuna de les quals representa una configuració, quedant de la forma `replace:opcions patró substitució`. Les opcions disponibles són:

  `b`

    Cerca enrere.

  `c`

    Cerca des de la posició del cursor.

  `e`

    Cerca tan sols en el text seleccionat.

  `r`

    Cerca usant una expressió regular. Si està establerta, podeu usar `\N` a on N serà un número per a representar captures en la cadena de substitució.

  `s`

    Cerca distingint majúscules i minúscules.

  `p`

    Demana permís per a substituir la següent ocurrència.

  `w`

    Tan sols coincidiran paraules senceres.

    dateformat

  Insereix una cadena de data/hora definida d'acord al `format`, o si aquest no s'especifica s'usarà el format aaaa-MM-dd hh:mm:ss. La interpretació del `format` serà la següent:

  `d` | El dia com a número sense ceros a l'esquerra (1-31).
  `dd` | El dia com a número amb dos dígits (01-31).
  `ddd` | L'abreujament del nom del dia segons la localització (&pex;, 'Dl'..'Dg').
  `dddd` | El nom complet del dia segons la la localització (&pex;, 'Dilluns'..'Diumenge').
  `M` | El mes com a número sense ceros a l'esquerra (1-31).
  `MM` | El mes com a número amb dos dígits (01-31).
  `MMM` | L'abreujament del nom del mes segons la localització (&pex;, 'Gen'..'Dec').
  `yy` | The year as two digit number (00-99).
  `yyyy` | L'any amb un número de quatre dígits (1752-8000).
  `h` | L'hora sense ceros a l'esquerra (0..23 o 1..12 si es mostra AM/PM).
  `hh` | L'hora amb dos dígits (00..23 o 01..12 si es mostra AM/PM).
  `m` | Els minuts sense ceros a l'esquerra (0..59).
  `mm` | Els minuts amb dos dígits (00..59).
  `s` | Els segons sense ceros a l'esquerra (0..59).
  `ss` | Els segons amb dos dígits (00..59).
  `z` | Els milisegons sense ceros a l'esquerra (0..999).
  `zzz` | Els milisegons amb tres dígits (000..999).
  `AP` | S'usa per a mostrar AM/PM. AP serà substituït per "AM" o "PM".
  `ap` | S'usa per a mostrar am/pm. ap serà substituït per "am" o "pm".

    charidentificador

  Aquest comandament us permet inserir caràcters literals pel seu identificador numèric, en format decimal, octal o hexadecimal. Per a usar-lo llanceu el diàleg Comandament d'edició i escriviu `char: [número]` en la caixa d'entrada, després premeu Bé.

  ##### Exemples de `char`

  Entrada: `char:234`

  Eixida: `ê`

  Entrada: `char:0x1234`

  Eixida: `ሴ`

`s///[ig]` `%s///[ig]`

  Aquest comandament realitzarà una operació de recerca/substitució similar a les de sed sobre la línia actual o en tot el fitxer (`%s///`).

  Abreujat, es cerca en el text alguna cadena que coincideixi amb el patró de recerca, l'expressió regular entre la primera i la segona barra, i quan es troba una coincidència, la part coincident del text és substituïda per l'expressió continguda entre les barres central i última de la cadena. Els parèntesis en el patró de recerca creen referències enrere, és a dir, que el comandament recorda quina part de la coincidència es troba entre parèntesis; aquestes cadenes es poden tornar a usar en el patró de substitució, referint-se a elles com a `\1` per al primer conjunt de parèntesis, `\2` per al segon i així successivament.

  Per a fer una recerca literal de `(` o `)`, haureu d'escapar el caràcter emprant un altre caràcter de barra invertida: `\(\)`

  Si poseu una `i` al final de l'expressió, les coincidències seran sensibles a majúscules i minúscules. Si poseu una `g` al final, es substituiran totes les ocurrències del patró, en qualsevol altre cas tan sols es substituirà la primera ocurrència.

  ##### Substitució de text en la línia actual

  El vostre bon amic l'ordinador s'ha aturat, dient que la classe `myClass` mencionada en la línia 3902 del fitxer font no està definida.

  "Llamps i trons!" Pensareu. Per descomptat és `MyClass`. Anireu fins la línia 3902 i en comptes d'intentar cercar la paraula en el text, obrireu el diàleg Comandament d'edició, introduireu `s/myclass/MyClass/i`, premereu el botó Bé, desareu el fitxer i tornareu a compilar aquesta vegada sense l'error.

  ##### Substitució de text en tot el fitxer

  Imagineu que teniu un fitxer, en el que mencioneu a Miss Jensen vàries vegades, quan resulta que algú ve i us diu que s'acaba de casar amb Mr Jones. Per descomptat, voldreu substituir cada ocurrència de Miss Jensen per Ms Jones.

  Entreu a la línia de comandaments, escriviu el comandament `%s/Miss Jensen/Ms Jones/`, una vegada que premeu &Intro; ja estarà fet.

  ##### Un exemple més avançat

  Aquest exemple fa ús de referències enrere així com d'una classe de caràcter (si no sabeu què és això, si us plau, consulteu la documentació mencionada a sota).

  Suposeu que teniu la següent línia:

      void MyClass::DoStringOps( String      &foo, String &bar String *p, int  &a, int &b )

  Però us adoneu de que aquest codi no està bé i decidiu que voleu usar la paraula clau `const` per a tots els arguments adreça de, que es caracteritzen per tenir un operador & al davant del nom de l'argument. També voldreu simplificar l'espai en blanc, de manera que només n'hi hagi un entre cada paraula.

  Obriu el diàleg Comandament d'edició i introduïu: `s/\s+(\w+)\s+(&)/ const \1 \2/g`, i després premeu el botó Bé. La `g` al final de l'expressió fa que l'expressió regular recompili cada coincidència per a desar les referències enrere.

  Eixida: `void MyClass::DoStringOps( const String &foo, const String &bar String *p, const int &a, const int &b )`

  Missió completada! Ara, què ha passat? Vaja, doncs hems cercat algun espai en blanc (`\s+`) seguit d'un o més caràcters alfabètics (`\w+`) seguits d'algun espai en blanc (`\s+`) seguit del símbol &, i en el procés hem desat el bloc alfabètic i el caràcter & per a tornar a usar-los en l'operació de substitució. Llavores hem substituït la part coincident de la nostra línia per un espai en blanc seguit de const seguit d'un espai en blanc seguit del nostre bloc alfabètic (`\1`) seguit d'un espai en blanc seguit del nostre caràcter & emmagatzemat (`\2`)

  En alguns casos el bloc alfabètic era String, en d'altres int, de manera que emprant la classe de caràcter `\w` i el quantificador `+` ens ha proveït d'un valuós actiu.

#### Comandaments per a navegar

    gotoINT línia

  Aquest comandament va a la línia especificada.

    findpatró

  Aquest comandament navega fins la primera ocurrència del `patró` d'acord amb la configuració. Les següents ocurrències es poden trobar usant Edita Cerca següent (la drecera per omissió és F3).

  El comandament find pot configurar-se afegint dos punts seguits per una o més opcions, el format serà `find:opcions patró`. Estan suportades les següents opcions:

  `b`

    Cerca enrere.

  `c`

    Cerca des de la posició del cursor.

  `e`

    Cerca tan sols en el text seleccionat.

  `r`

    Cerca usant una expressió regular. Si està establerta, podeu usar `\N` a on N serà un número per a representar captures en la cadena de substitució.

  `s`

    Cerca distingint majúscules i minúscules.

  `w`

    Tan sols coincidiran paraules senceres.

    ifindpatró

  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`

    Cerca enrere.

  `r`

    Cerca mitjançant expressions regulars.

  `s`

    Cerca distingint majúscules i minúscules.

  `c`

    Cerca des de la posició del cursor.

## 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 View Show 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 `--path` `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 `document` 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 `view` 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 `.desktop` 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.