Git commit 3ff39713378a392c947da96396e5834150a0f935 by Burkhard L?ck, on behalf of David Palser. Committed on 05/11/2013 at 17:33. Pushed by lueck into branch 'KDE/4.12'.
Typo corrections, improvements to grammar, and adding entities. (cherry picked from commit 4ee46d7b8c084fa2407bd1fa772570aa9316bf26) backport to 4.12.1 M +50 -50 doc/kate/development.docbook http://commits.kde.org/kate/3ff39713378a392c947da96396e5834150a0f935 diff --git a/doc/kate/development.docbook b/doc/kate/development.docbook index 457ee8d..6152bd1 100644 --- a/doc/kate/development.docbook +++ b/doc/kate/development.docbook @@ -27,7 +27,7 @@ enhancements with the world!</para> <title>Scripting with JavaScript</title> <para> -Since &kappname; 3.4 in KDE 4.4 the &kappname; editor component is easily extensible by +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). &kappname; supports two kinds of scripts: indentation and command line scripts. </para> @@ -37,14 +37,14 @@ writing scripts. The scripting language is ECMAScript (widely known as JavaScrip <para> Indentation scripts - also referred as indenters - automatically indent the -source code while typing text. As example, after hitting the return-key code +source code while typing text. As an example, after hitting the return key the indentation level often increases. </para> <para> The following sections describe step by step how to create the skeleton for a -simple indenter. As first step, create a new <filename>*.js</filename> file -called e.g. <filename>javascript.js</filename> in the local home folder +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>. </para> @@ -52,7 +52,7 @@ called e.g. <filename>javascript.js</filename> in the local home folder <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 +comment and is of the following form: <programlisting> /* kate-script @@ -66,7 +66,7 @@ comment and is of the following form * priority: 0 * i18n-catalog: mycatalog * - * A line without colon ':' stops header parsing. That is, you can add optional + * A line without a colon ':' stops header parsing. That is, you can add optional * text here such as a detailed license. */ </programlisting> @@ -91,13 +91,13 @@ and in the configuration dialog. <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]: Minimal required &kappname; version. +<literal>kate-version</literal> [required]: Minimum required &kappname; version. </para></listitem> <listitem><para> <literal>required-syntax-style</literal> [optional]: Comma separated list of required syntax highlighting styles. 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, e.g.: c++, java. +<literal>indent-languages</literal> [optional]: Comma separated list of syntax styles the indenter can indent correctly, ⪚: c++, java. </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. @@ -140,7 +140,7 @@ function indent(line, indentWidth, ch) The function <function>indent()</function> has three parameters: <itemizedlist> <listitem><para><literal>line</literal>: the line that has to be indented</para></listitem> -<listitem><para><literal>indentWidth</literal>: the indentation width in amount of spaces</para></listitem> +<listitem><para><literal>indentWidth</literal>: the indentation width in number of spaces</para></listitem> <listitem><para><literal>ch</literal>: either a newline character (<literal>ch == '\n'</literal>), the trigger character specified in <literal>triggerCharacters</literal> or empty if the user invoked the action <menuchoice><guimenu>Tools</guimenu><guimenuitem>Align</guimenuitem></menuchoice>.</para></listitem> </itemizedlist> The return value of the <function>indent()</function> function specifies how @@ -155,7 +155,7 @@ Alternatively, an array of two elements can be returned: <itemizedlist> <listitem><para><literal>return [ indent, align ];</literal></para></listitem> </itemizedlist> -In this case, the first element is the indentation depth like above with the +In this case, the first element is the indentation depth as above with the same meaning of the special values. However, the second element is an absolute value representing a column for <quote>alignment</quote>. If this value is higher than the indent value, the difference represents a number of spaces to be added after @@ -177,12 +177,12 @@ with a different tab width. </para> <para> -A default KDE installation ships &kappname; with several indenters. The +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>. </para> <para> -Developing an indenter requires to reload the scripts to see whether the changes +Developing an indenter 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> @@ -203,13 +203,13 @@ As it is hard to satisfy everyone's needs, &kappname; supports little helper too for quick text manipulation through the <link linkend="advanced-editing-tools-commandline">built-in command line</link>. For instance, the command -<command>sort</command> is implemented as script. This section explains how to create +<command>sort</command> is implemented as a script. This section explains how to create <filename>*.js</filename> files to extend &kappname; with arbitrary helper scripts. </para> <para> Command line scripts are located in the same folder as indentation scripts. -So as first step, create a new <filename>*.js</filename> file called +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>. </para> @@ -218,7 +218,7 @@ So as first step, create a new <filename>*.js</filename> file called <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 +following form: <programlisting> /* kate-script @@ -229,7 +229,7 @@ following form * functions: sort, format-paragraph * i18n-catalog: mycatalog * - * A line without colon ':' stops header parsing. That is, you can add optional + * A line without a colon ':' stops header parsing. That is, you can add optional * text here such as a detailed license. */ </programlisting> @@ -240,7 +240,7 @@ Each entry is explained in detail now: <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>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]: Minimal required &kappname; version.</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>i18n-catalog</literal> [optional]: Additional message catalog (<literal>po</literal> file) loaded for translation of 3rd-party scripts.</para></listitem> </itemizedlist> @@ -252,7 +252,7 @@ Each entry is explained in detail now: 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 amount +of command line commands. This means a single script contains 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> @@ -296,7 +296,7 @@ function help(cmd) </programlisting> Executing <command>help sort</command> in the command line then calls this help function with -the argument <parameter>cmd</parameter> set to the given command, i.e. +the argument <parameter>cmd</parameter> set to the given command, &ie; <parameter>cmd == "sort"</parameter>. &kappname; then presents the returned text as documentation to the user. Make sure to <link linkend="dev-scripting-api-i18n">translate the strings</link>. @@ -327,7 +327,7 @@ which a shortcut is requested. There are several fields you have to specify in the returned javascript object: <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.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> @@ -336,7 +336,7 @@ the returned javascript object: <para> -Developing a command line script requires to reload the scripts to see whether +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> @@ -354,10 +354,10 @@ by <ulink url="mailto:kwrite-devel at kde.org">contacting the mailing list</ulink>. <title>Scripting API</title> <para> -The scripting API presented here is available in all scripts, i.e. indentation +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> are provided by library files in <filename>$KDEDIR/share/apps/katepart/libraries</filename>. -If you want to use them in your script, which is required to use some of the <classname>Document</classname> or <classname>View</classname> functions, please include the needed library by using: +The <classname>Cursor</classname> and <classname>Range</classname> classes are provided by library files in <filename>$KDEDIR/share/apps/katepart/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> // required katepart js libraries, e.g. range.js if you use Range @@ -366,8 +366,8 @@ require ("range.js"); </para> <para> -To extend the standard scripting API with own functions and prototypes simply -create a new file in the KDE's local configuration folder +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: <programlisting> @@ -451,7 +451,7 @@ Cursor.setPosition(<parameter>int <replaceable>line</replaceable></parameter>, < <listitem><para> Sets the cursor position to <replaceable>line</replaceable> and <replaceable>column</replaceable>.</para> <para> -Since: KDE 4.11 +Since: &kde; 4.11 </para></listitem> </varlistentry> @@ -475,7 +475,7 @@ Example: <function>var valid = cursor.isValid();</function> Cursor Cursor.invalid(); </synopsis></term> <listitem><para> -Returns an new invalid cursor located at <literal>(-1, -1)</literal>. +Returns a new invalid cursor located at <literal>(-1, -1)</literal>. </para> <para>Example: <function>var invalidCursor = cursor.invalid();</function> </para></listitem> @@ -585,7 +585,7 @@ Returns <literal>true</literal>, if the start and end cursors are equal. <para>Example: <function>var empty = range.isEmpty();</function> </para> <para> -Since: KDE 4.11 +Since: &kde; 4.11 </para></listitem> </varlistentry> @@ -694,10 +694,10 @@ bool Range.onSingleLine(); </synopsis></term> <listitem><para> Returns <literal>true</literal>, if the range starts and ends at the same line, -i.e. if <replaceable>Range.start.line == Range.end.line</replaceable>. +&ie; if <replaceable>Range.start.line == Range.end.line</replaceable>. </para> <para> -Since: KDE 4.9 +Since: &kde; 4.9 </para></listitem> </varlistentry> @@ -751,7 +751,7 @@ Will search the given <replaceable>file</replaceable> relative to the <literal>k <literal>require</literal> is internally guarded against multiple inclusions of the same <replaceable>file</replaceable>. </para> <para> - Since: KDE 4.10 + Since: &kde; 4.10 </para> </listitem> </varlistentry></variablelist> @@ -780,15 +780,15 @@ console launching the application. strings in scripts, namely <literal>i18n</literal>, <literal>i18nc</literal>, <literal>i18np</literal> and <literal>i18ncp</literal>. These functions behave exactly like <ulink url="http://techbase.kde.org/Development/Tutorials/Localization/i18n";> -KDE's translation functions</ulink>. +&kde;'s translation functions</ulink>. </para> -<para>The translation functions translate the wrapped strings through KDE's +<para>The translation functions translate the wrapped strings through &kde;'s translation system to the language used in the application. Strings in scripts being developed in the official &kappname; sources are automatically extracted and translatable. In other words, as a &kappname; developer you do not have to bother with message extraction and translation. However, for 3rd-party scripts developed -outside of KDE, you have to extract and translate the messages yourself. Along +outside of &kde;, you have to extract and translate the messages yourself. Along with your scripts you have to also distribute a translation catalog, that includes all translated strings. Further, your script header then must explicitly state the catalog to load by specifying @@ -1108,7 +1108,7 @@ is invalid (see Range.isValid()), if the text position is after the end of a line. If there is no word at the given cursor, an empty range is returned. </para> <para> - Since: KDE 4.9 + Since: &kde; 4.9 </para> </listitem> </varlistentry> @@ -1282,10 +1282,10 @@ bool document.wrapLine(<parameter>Cursor <replaceable>cursor</replaceable></para </synopsis></term> <listitem><para> Wraps the line at the given cursor position. Returns <literal>true</literal> on success, -otherwise <literal>false</literal>, e.g. if line < 0. +otherwise <literal>false</literal>, ⪚ if line < 0. </para> <para> - Since: KDE 4.9 + Since: &kde; 4.9 </para> </listitem> </varlistentry> @@ -1307,7 +1307,7 @@ void document.joinLines(<parameter>int <replaceable>startLine</replaceable></par int document.lines(); </synopsis></term> <listitem><para> - Returns the amount of lines in the document. + Returns the number of lines in the document. </para></listitem> </varlistentry> @@ -1340,7 +1340,7 @@ void document.editBegin(); Starts an edit group for undo/redo grouping. Make sure to always call <function>editEnd()</function> as often as you call <function>editBegin()</function>. Calling <function>editBegin()</function> - internally uses a reference counter, i.e., this call can be nested. + internally uses a reference counter, &ie;, this call can be nested. </para></listitem> </varlistentry> @@ -1350,7 +1350,7 @@ void document.editBegin(); void document.editEnd(); </synopsis></term> <listitem><para> - Ends an edit group. The last call of <function>editEnd()</function> (i.e. + Ends an edit group. The last call of <function>editEnd()</function> (&ie; the one for the first call of <function>editBegin()</function>) finishes the edit step. </para></listitem> @@ -1385,7 +1385,7 @@ int document.prevNonSpaceColumn(<parameter>int <replaceable>line</replaceable></ int document.prevNonSpaceColumn(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); </synopsis></term> <listitem><para> - Returns the column with a non-whitespace characters starting at the given + Returns the column with a non-whitespace character starting at the given cursor position and searching backwards. </para></listitem> </varlistentry> @@ -1397,7 +1397,7 @@ int document.nextNonSpaceColumn(<parameter>int <replaceable>line</replaceable></ int document.nextNonSpaceColumn(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); </synopsis></term> <listitem><para> - Returns the column with a non-whitespace characters starting at the given + Returns the column with a non-whitespace character starting at the given cursor position and searching forwards. </para></listitem> </varlistentry> @@ -1522,7 +1522,7 @@ String document.attributeName(<parameter>int <replaceable>line</replaceable></pa String document.attributeName(<parameter>Cursor <replaceable>cursor</replaceable></parameter>); </synopsis></term> <listitem><para> - Returns the attribute name as human readable text. This equals to the + Returns the attribute name as human readable text. This is equal to the <literal>itemData</literal> name in the syntax highlighting files. </para></listitem> </varlistentry> @@ -1557,13 +1557,13 @@ String document.setVariable(<parameter>String <replaceable>key</replaceable></pa </synopsis></term> <listitem><para> Set the value of the requested document variable <replaceable>key</replaceable>. - Returns the value of set variable. + Returns the value of the set variable. </para> <para> See also: <link linkend="config-variables">Kate document variables</link> </para> <para> - Since: KDE 4.8 + Since: &kde; 4.8 </para></listitem> </varlistentry> @@ -1623,8 +1623,8 @@ Cursor document.anchor(<parameter>Cursor <replaceable>cursor</replaceable></para </synopsis></term> <listitem><para> Searches backward for the given character starting from the given cursor. - As example, if '(' is passed as character, this function will return the - position of the opening '('. This reference counting, i.e. other '(...)' + As an example, if '(' is passed as character, this function will return the + position of the opening '('. This reference counting, &ie; other '(...)' are ignored. </para></listitem> </varlistentry> @@ -1636,7 +1636,7 @@ Cursor document.rfind(<parameter>int <replaceable>line</replaceable></parameter> Cursor document.rfind(<parameter>Cursor <replaceable>cursor</replaceable></parameter>, <parameter>String <replaceable>text</replaceable></parameter>, <parameter>int <replaceable>attribute</replaceable> = -1</parameter>); </synopsis></term> <listitem><para> - Find backward the given text with the appropriate <replaceable>attribute</replaceable>. + Find searching backwards the given text with the appropriate <replaceable>attribute</replaceable>. The argument <replaceable>attribute</replaceable> is ignored if it is set to <literal>-1</literal>. The returned cursor is invalid, if the text could not be found. </para></listitem> @@ -1738,7 +1738,7 @@ bool document.isOthers(<parameter>Cursor <replaceable>cursor</replaceable></para <title>Editor Component Extensions</title> <para><link linkend="editor-component-plugins">Editor Component Extensions</link> -extend KatePart, the Advanced Text Editor component used within many KDE +extend KatePart, the Advanced Text Editor component used within many &kde; applications, such as &kate;, &kwrite;, Kile, and KDevelop. Creating an Editor Component Plugin will allow you to extend the editor's functionality in any and all of these programs.</para>
