[kde-doc-english] [kate] doc/kate: Typo corrections, improvements to grammar, and adding entities.
Yuri Chornoivan
yurchor at ukr.net
Tue Nov 5 17:33:31 UTC 2013
Git commit 4ee46d7b8c084fa2407bd1fa772570aa9316bf26 by Yuri Chornoivan, on behalf of David Palser.
Committed on 05/11/2013 at 17:33.
Pushed by yurchor into branch 'master'.
Typo corrections, improvements to grammar, and adding entities.
M +50 -50 doc/kate/development.docbook
http://commits.kde.org/kate/4ee46d7b8c084fa2407bd1fa772570aa9316bf26
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>
More information about the kde-doc-english
mailing list