Git commit 4e1c7714038298b573daa683f0fbcb2805eb7c49 by Dominik Haumann. Committed on 07/08/2014 at 11:14. Pushed by dhaumann into branch 'master'.
adapt documentation to now script headers M +89 -90 doc/katepart/development.docbook http://commits.kde.org/kate/4e1c7714038298b573daa683f0fbcb2805eb7c49 diff --git a/doc/katepart/development.docbook b/doc/katepart/development.docbook index 64b2bd7..43b7567 100644 --- a/doc/katepart/development.docbook +++ b/doc/katepart/development.docbook @@ -228,7 +228,9 @@ the highlight detection rules.</para> <para>The formal definition, also known as the <acronym>DTD</acronym>, is stored in the file <filename>language.dtd</filename> which should be installed on your system in the folder -<filename>$<envar>KDEDIR</envar>/share/apps/katepart/syntax</filename>. +<filename>$<envar>XDG_DATA_DIRS</envar>/katepart5/syntax</filename>. Therein, +the environment variable <envar>XDG_DATA_DIRS</envar> typically expands to +<filename>/usr/share</filename>. </para> <variablelist> @@ -989,8 +991,8 @@ expression.</para> <title>Scripting with JavaScript</title> <para> -Since &kappname; 3.4 in &kde; 4.4 the &kappname; editor component is easily extensible by -writing scripts. The scripting language is ECMAScript (widely known as JavaScript). +The &kappname; editor component is easily extensible by writing scripts. +The scripting language is ECMAScript (widely known as JavaScript). &kappname; supports two kinds of scripts: indentation and command line scripts. </para> @@ -1007,38 +1009,33 @@ the indentation level often increases. The following sections describe step by step how to create the skeleton for a simple indenter. As a first step, create a new <filename>*.js</filename> file called ⪚ <filename>javascript.js</filename> in the local home folder -<filename>$KDEHOME/share/apps/katepart/script/indentation</filename>. +<filename>$<envar>XDG_DATA_HOME</envar>/katepart5/script/indentation</filename>. +Therein, the environment variable <envar>XDG_DATA_HOME</envar> typically expands to +either <filename>~/.local</filename> or <filename>~/.local/share</filename>. </para> <sect3 id="dev-scripting-indentation-header"> <title>The Indentation Script Header</title> <para> -The header of the file <filename>javascript.js</filename> is embedded in a -comment and is of the following form: +The header of the file <filename>javascript.js</filename> is embedded as JSON at the beginning of the document as follows: <programlisting> -/* kate-script - * name: JavaScript - * author: Example Name <example.name at some.address.org> - * license: BSD - * revision: 1 - * kate-version: 3.4 - * required-syntax-style: javascript - * indent-languages: javascript - * priority: 0 - * i18n-catalog: mycatalog - * - * A line without a colon ':' stops header parsing. That is, you can add optional - * text here such as a detailed license. - */ +var katescript = { + "name": "JavaScript", + "author": "Example Name <example.name at some.address.org>", + "license": "BSD License", + "revision": 1, + "kate-version": "5.1", + "required-syntax-style": "javascript", + "indent-languages": ["javascript"], + "priority": 0, + "i18n-catalog": "mycatalog" +}; // kate-script-header, must be at the start of the file without comments </programlisting> Each entry is explained in detail now: <itemizedlist> <listitem><para> -<literal>kate-script</literal> [required]: This text string has to appear in the first line of the <filename>*.js</filename> file, otherwise &kappname; skips the script. -</para></listitem> -<listitem><para> <literal>name</literal> [required]: This is the indenter name that appears in the menu <menuchoice><guimenu>Tools</guimenu><guimenuitem>Indentation</guimenuitem></menuchoice> and in the configuration dialog. @@ -1047,7 +1044,7 @@ and in the configuration dialog. <literal>author</literal> [optional]: The author's name and contact information. </para></listitem> <listitem><para> -<literal>license</literal> [optional]: Short form of the license, such as BSD or LGPLv3. +<literal>license</literal> [optional]: Short form of the license, such as BSD License or LGPLv3. </para></listitem> <listitem><para> <literal>revision</literal> [required]: The revision of the script. This number should be increased whenever the script is modified. @@ -1059,7 +1056,7 @@ and in the configuration dialog. <literal>required-syntax-style</literal> [optional]: The required syntax style, which matches the specified <literal>style</literal> in syntax highlighting files. This is important for indenters that rely on specific highlight information in the document. If a required syntax style is specified, the indenter is available only when the appropriate highlighter is active. This prevents <quote>undefined behavior</quote> caused by using the indenter without the expected highlighting schema. For instance, the Ruby indenter makes use of this in the files <filename>ruby.js</filename> and <filename>ruby.xml</filename>. </para></listitem> <listitem><para> -<literal>indent-languages</literal> [optional]: Comma separated list of syntax styles the indenter can indent correctly, ⪚: c++, java. +<literal>indent-languages</literal> [optional]: JSON array of syntax styles the indenter can indent correctly, ⪚: <literal>["c++", "java"]</literal>. </para></listitem> <listitem><para> <literal>priority</literal> [optional]: If several indenters are suited for a certain highlighted file, the priority decides which indenter is chosen as default indenter. @@ -1068,13 +1065,6 @@ and in the configuration dialog. </itemizedlist> </para> -<para> -&kappname; reads all pairs of the form -<quote><replaceable>key</replaceable>:<replaceable>value</replaceable></quote> -until it cannot find a colon anymore. This implies that the header can contain -arbitrary text such as a license as shown in the example. -</para> - </sect3> <sect3 id="dev-scripting-indentation-body"> @@ -1140,7 +1130,7 @@ with a different tab width. <para> A default &kde; installation ships &kappname; with several indenters. The -corresponding JavaScript source code can be found in <filename>$KDEDIR/share/apps/katepart/script/indentation</filename>. +corresponding JavaScript source code can be found in <filename>$<envar>XDG_DATA_DIRS</envar>/katepart5/script/indentation</filename>. </para> <para> @@ -1173,48 +1163,54 @@ For instance, the command Command line scripts are located in the same folder as indentation scripts. So as a first step, create a new <filename>*.js</filename> file called <filename>myutils.js</filename> in the local home folder -<filename>$KDEHOME/share/apps/katepart/script/commands</filename>. +<filename>$<envar>XDG_DATA_HOME</envar>/katepart5/script/commands</filename>. +Therein, the environment variable <envar>XDG_DATA_HOME</envar> typically expands to +either <filename>~/.local</filename> or <filename>~/.local/share</filename>. </para> <sect3 id="dev-scripting-command-line-header"> <title>The Command Line Script Header</title> <para> -The header of each command line script is embedded in a comment and is of the -following form: +The header of each command line script is embedded in JSON at the beginning of the script as follows: <programlisting> -/* kate-script - * author: Example Name <example.name at some.address.org> - * license: BSD - * revision: 1 - * kate-version: 3.4 - * functions: sort, format-paragraph - * i18n-catalog: mycatalog - * - * A line without a colon ':' stops header parsing. That is, you can add optional - * text here such as a detailed license. - */ +var katescript = { + "author": "Example Name <example.name at some.address.org>", + "license": "LGPLv2+", + "revision": 1, + "kate-version": "5.1", + "functions": ["sort", "moveLinesDown"], + "i18n-catalog": "mycatalog", + "actions": [ + { "function": "sort", + "name": "Sort Selected Text", + "category": "Editing", + "interactive": "false" + }, + { "function": "moveLinesDown", + "name": "Move Lines Down", + "category": "Editing", + "shortcut": "Ctrl+Shift+Down", + "interactive": "false" + } + ] +}; // kate-script-header, must be at the start of the file without comments </programlisting> Each entry is explained in detail now: <itemizedlist> -<listitem><para><literal>kate-script</literal> [required]: This text string has to appear in the first line of the <filename>*.js</filename> file, otherwise &kappname; skips the script.</para></listitem> <listitem><para><literal>author</literal> [optional]: The author's name and contact information.</para></listitem> -<listitem><para><literal>license</literal> [optional]: Short form of the license, such as BSD or LGPLv3.</para></listitem> +<listitem><para><literal>license</literal> [optional]: Short form of the license, such as BSD License or LGPLv2.</para></listitem> <listitem><para><literal>revision</literal> [required]: The revision of the script. This number should be increased whenever the script is modified.</para></listitem> <listitem><para><literal>kate-version</literal> [required]: Minimum required &kappname; version.</para></listitem> -<listitem><para><literal>functions</literal> [required]: Comma separated list of commands in the script.</para></listitem> +<listitem><para><literal>functions</literal> [required]: JSON array of commands in the script.</para></listitem> <listitem><para><literal>i18n-catalog</literal> [optional]: Additional message catalog (<literal>po</literal> file) loaded for translation of 3rd-party scripts.</para></listitem> +<listitem><para><literal>actions</literal> [optional]: JSON Array of JSON objects that defines the actions that appear in the application menu. Detailed information is provided in the section <link linkend="advanced-editing-tools-commandline">Binding Shortcuts</link>.</para></listitem> </itemizedlist> </para> <para> -&kappname; reads all pairs of the form -<quote><replaceable>key</replaceable>:<replaceable>value</replaceable></quote> -until it cannot find a colon -anymore. This implies that the header can contain arbitrary text such as a license -as shown in the example. The value of the key functions is a comma separated list -of command line commands. This means a single script contains an arbitrary number +Since the value of <literal>functions</literal> is a JSON array, a single script is able contain an arbitrary number of command line commands. Each function is available through &kappname;'s <link linkend="advanced-editing-tools-commandline">built-in command line</link>. </para> @@ -1226,7 +1222,7 @@ of command line commands. Each function is available through &kappname;'s <para> All functions specified in the header have to be implemented in the script. For instance, the script file from the example above needs to implement the two -functions <command>sort</command> and <command>format-paragraph</command>. +functions <command>sort</command> and <command>moveLinesDown</command>. All functions have the following syntax: <programlisting> @@ -1264,45 +1260,48 @@ documentation to the user. Make sure to <link linkend="dev-scripting-api-i18n">translate the strings</link>. </para> +<para> +Developing a command line script requires reloading the scripts to see whether +the changes behave appropriately. Instead of restarting the application, simply +switch to the command line and invoke the command <command>reload-scripts</command>. +</para> + <sect4 id="dev-scripting-command-line-shortcuts"> <title>Binding Shortcuts</title> -<para>In order to be able to assign shortcuts, the script needs to provide a -function called <literal>action</literal> as follows: +<para>In order to make the scripts accessible in the application menu and assign shortcuts, the script needs to provide an appropriate +script header. In the above example, both functions <literal>sort</literal> and <literal>moveLinesDown</literal> appear in the menu +due to the following part in the script header: <programlisting> -function action(cmd) -{ - var a = new Object(); - if (cmd == "sort") { - a.text = i18n("Sort Selected Text"); - a.icon = ""; - a.category = ""; - a.interactive = false; - a.shortcut = ""; - } else if (cmd == "moveLinesDown") { - // same for next action - } - return a; -} +var katescript = { + ... + "actions": [ + { "function": "sort", + "name": "Sort Selected Text", + "icon": "", + "category": "Editing", + "interactive": "false" + }, + { "function": "moveLinesDown", + "name": "Move Lines Down", + "icon": "", + "category": "Editing", + "shortcut": "Ctrl+Shift+Down", + "interactive": "false" + } + ] +}; </programlisting> -The parameter <literal>cmd</literal> of the function specifies the command for -which a shortcut is requested. There are several fields you have to specify in -the returned javascript object: +The fields for one action are as follows: <itemizedlist> -<listitem><para><literal>a.text</literal> [required]: The text appears in the menu <menuchoice><guimenu>Tools</guimenu> <guisubmenu>Scripts</guisubmenu></menuchoice>. Make sure to use <literal>i18n</literal> for translation.</para></listitem> -<listitem><para><literal>a.icon</literal> [optional]: The icon appears next to the text in the menu. All &kde; icon names can be used here.</para></listitem> -<listitem><para><literal>a.category</literal> [optional]: If a category is specified, the script appears in a submenu. Make sure to use <literal>i18n</literal> for translation.</para></listitem> -<listitem><para><literal>a.interactive</literal> [optional]: If the script needs user input, set this to <literal>true</literal>.</para></listitem> -<listitem><para><literal>a.shortcut</literal> [optional]: The shortcut given here is the default shortcut. Example: Ctrl+Alt+t. See the <ulink url="http://qt-project.org/doc/qt-4.8/qt.html#Key-enum";>Qt documentation</ulink> for further details.</para></listitem> +<listitem><para><literal>function</literal> [required]: The function that should appear in the menu <menuchoice><guimenu>Tools</guimenu> <guisubmenu>Scripts</guisubmenu></menuchoice>.</para></listitem> +<listitem><para><literal>name</literal> [required]: The text appears in the script menu.</para></listitem> +<listitem><para><literal>icon</literal> [optional]: The icon appears next to the text in the menu. All &kde; icon names can be used here.</para></listitem> +<listitem><para><literal>category</literal> [optional]: If a category is specified, the script appears in a submenu.</listitem> +<listitem><para><literal>shortcut</literal> [optional]: The shortcut given here is the default shortcut. Example: <literal>Ctrl+Alt+t</literal>. See the <ulink url="http://qt-project.org/doc/qt-5/qt.html#Key-enum";>Qt documentation</ulink> for further details.</para></listitem> +<listitem><para><literal>interactive</literal> [optional]: If the script needs user input in the command line, set this to <literal>true</literal>.</para></listitem> </itemizedlist> </para> - -<para> -Developing a command line script requires reloading the scripts to see whether -the changes behave appropriately. Instead of restarting the application, simply -switch to the command line and invoke the command <command>reload-scripts</command>. -</para> - <para> If you develop useful scripts please consider contributing to the &kappname; Project by <ulink url="mailto:kwrite-devel at kde.org">contacting the mailing list</ulink>. @@ -1318,7 +1317,7 @@ by <ulink url="mailto:kwrite-devel at kde.org">contacting the mailing list</ulink>. <para> The scripting API presented here is available to all scripts, &ie; indentation scripts and command line commands. -The <classname>Cursor</classname> and <classname>Range</classname> classes are provided by library files in <filename>$KDEDIR/share/apps/katepart/libraries</filename>. +The <classname>Cursor</classname> and <classname>Range</classname> classes are provided by library files in <filename>$<envar>XDG_DATA_DIRS</envar>/katepart5/libraries</filename>. If you want to use them in your script, which needs to use some of the <classname>Document</classname> or <classname>View</classname> functions, please include the necessary library by using: <programlisting> @@ -1330,7 +1329,7 @@ require ("range.js"); <para> To extend the standard scripting API with your own functions and prototypes simply create a new file in &kde;'s local configuration folder -<filename>$KDEHOME/share/apps/katepart/libraries</filename> and include it into your script using: +<filename>$<envar>XDG_DATA_HOME</envar>/katepart5/libraries</filename> and include it into your script using: <programlisting> require ("myscriptnamehere.js");
