Index: /CKEditor/trunk/_source/core/editor.js
===================================================================
--- /CKEditor/trunk/_source/core/editor.js	(revision 7037)
+++ /CKEditor/trunk/_source/core/editor.js	(revision 7038)
@@ -121,9 +121,9 @@
 		/**
 		 * The name of the skin used by this editor instance. The skin name can
-		 * be set though the {@link CKEDITOR.config.skin} setting.
+		 * be set through the <code>{@link CKEDITOR.config.skin}</code> setting.
 		 * @name CKEDITOR.editor.prototype.skinName
 		 * @type String
 		 * @example
-		 * alert( editor.skinName );  // "kama" (e.g.)
+		 * alert( editor.skinName );  // E.g. "kama"
 		 */
 		editor.skinName = skinName;
@@ -134,5 +134,5 @@
 		 * @type String
 		 * @example
-		 * alert( editor.skinPath );  // "http://example.com/ckeditor/skins/kama/" (e.g.)
+		 * alert( editor.skinPath );  // E.g. "http://example.com/ckeditor/skins/kama/"
 		 */
 		editor.skinPath = skinPath;
@@ -143,5 +143,5 @@
 		 * @type String
 		 * @example
-		 * alert( editor.skinClass );  // "cke_skin_kama" (e.g.)
+		 * alert( editor.skinClass );  // E.g. "cke_skin_kama"
 		 */
 		editor.skinClass = 'cke_skin_' + skinName;
@@ -150,12 +150,12 @@
 		 * The <a href="http://en.wikipedia.org/wiki/Tabbing_navigation">tabbing
 		 * navigation</a> order that has been calculated for this editor
-		 * instance. This can be set by the {@link CKEDITOR.config.tabIndex}
-		 * setting or taken from the "tabindex" attribute of the
-		 * {@link #element} associated to the editor.
+		 * instance. This can be set by the <code>{@link CKEDITOR.config.tabIndex}</code>
+		 * setting or taken from the <code>tabindex</code> attribute of the
+		 * <code>{@link #element}</code> associated with the editor.
 		 * @name CKEDITOR.editor.prototype.tabIndex
 		 * @type Number
 		 * @default 0 (zero)
 		 * @example
-		 * alert( editor.tabIndex );  // "0" (e.g.)
+		 * alert( editor.tabIndex );  // E.g. "0"
 		 */
 		editor.tabIndex = editor.config.tabIndex || editor.element.getAttribute( 'tabindex' ) || 0;
@@ -183,19 +183,19 @@
 				/**
 				 * The code for the language resources that have been loaded
-				 * for the user internface elements of this editor instance.
+				 * for the user interface elements of this editor instance.
 				 * @name CKEDITOR.editor.prototype.langCode
 				 * @type String
 				 * @example
-				 * alert( editor.langCode );  // "en" (e.g.)
+				 * alert( editor.langCode );  // E.g. "en"
 				 */
 				editor.langCode = languageCode;
 
 				/**
-				 * An object holding all language strings used by the editor
+				 * An object that contains all language strings used by the editor
 				 * interface.
 				 * @name CKEDITOR.editor.prototype.lang
 				 * @type CKEDITOR.lang
 				 * @example
-				 * alert( editor.lang.bold );  // "Negrito" (e.g. if language is Portuguese)
+				 * alert( editor.lang.bold );  // E.g. "Negrito" (if the language is set to Portuguese)
 				 */
 				// As we'll be adding plugin specific entries that could come
@@ -256,10 +256,10 @@
 
 				/**
-				 * And object holding references to all plugins used by this
-				 * editor istance.
+				 * An object that contains references to all plugins used by this
+				 * editor instance.
 				 * @name CKEDITOR.editor.prototype.plugins
 				 * @type Object
 				 * @example
-				 * alert( editor.plugins.dialog.path );  // "http://example.com/ckeditor/plugins/dialog/" (e.g.)
+				 * alert( editor.plugins.dialog.path );  // E.g. "http://example.com/ckeditor/plugins/dialog/"
 				 */
 				editor.plugins = plugins;
@@ -350,5 +350,5 @@
 				 * @type CKEDITOR.theme
 				 * @example
-				 * alert( editor.theme );  "http://example.com/ckeditor/themes/default/" (e.g.)
+				 * alert( editor.theme );  // E.g. "http://example.com/ckeditor/themes/default/"
 				 */
 				var editorTheme = editor.theme = CKEDITOR.themes.get( theme );
@@ -425,5 +425,5 @@
 	/**
 	 * Initializes the editor instance. This function is called by the editor
-	 * contructor (editor_basic.js).
+	 * contructor (<code>editor_basic.js</code>).
 	 * @private
 	 */
@@ -441,22 +441,23 @@
 
 			/**
-			 * The DOM element that has been replaced by this editor instance. This
-			 * element holds the editor data on load and post.
+			 * The DOM element that was replaced by this editor instance. This
+			 * element stores the editor data on load and post.
 			 * @name CKEDITOR.editor.prototype.element
 			 * @type CKEDITOR.dom.element
 			 * @example
 			 * var editor = CKEDITOR.instances.editor1;
-			 * alert( <b>editor.element</b>.getName() );  "textarea"
+			 * alert( <strong>editor.element</strong>.getName() );  // E.g. "textarea"
 			 */
 			this.element = element;
 
 			/**
-			 * The editor instance name. It hay be the replaced element id, name or
-			 * a default name using a progressive counter (editor1, editor2, ...).
+			 * The editor instance name. It may be the replaced element ID, name, or
+			 * a default name using the progressive counter (<code>editor1</code>,
+			 * <code>editor2</code>, ...).
 			 * @name CKEDITOR.editor.prototype.name
 			 * @type String
 			 * @example
 			 * var editor = CKEDITOR.instances.editor1;
-			 * alert( <b>editor.name</b> );  "editor1"
+			 * alert( <strong>editor.name</strong> );  // "editor1"
 			 */
 			this.name = ( element && ( this.elementMode == CKEDITOR.ELEMENT_MODE_REPLACE )
@@ -468,5 +469,5 @@
 
 			/**
-			 * A unique random string assigned to each editor instance in the page.
+			 * A unique random string assigned to each editor instance on the page.
 			 * @name CKEDITOR.editor.prototype.id
 			 * @type String
@@ -476,5 +477,5 @@
 			/**
 			 * The configurations for this editor instance. It inherits all
-			 * settings defined in (@link CKEDITOR.config}, combined with settings
+			 * settings defined in <code>(@link CKEDITOR.config}</code>, combined with settings
 			 * loaded from custom configuration files and those defined inline in
 			 * the page when creating the editor.
@@ -483,10 +484,10 @@
 			 * @example
 			 * var editor = CKEDITOR.instances.editor1;
-			 * alert( <b>editor.config.theme</b> );  "default" e.g.
+			 * alert( <strong>editor.config.theme</strong> );  // E.g. "default"
 			 */
 			this.config = CKEDITOR.tools.prototypedCopy( CKEDITOR.config );
 
 			/**
-			 * Namespace containing UI features related to this editor instance.
+			 * The namespace containing UI features related to this editor instance.
 			 * @name CKEDITOR.editor.prototype.ui
 			 * @type CKEDITOR.ui
@@ -498,5 +499,5 @@
 			 * Controls the focus state of this editor instance. This property
 			 * is rarely used for normal API operations. It is mainly
-			 * destinated to developer adding UI elements to the editor interface.
+			 * intended for developers adding UI elements to the editor interface.
 			 * @name CKEDITOR.editor.prototype.focusManager
 			 * @type CKEDITOR.focusManager
@@ -519,5 +520,5 @@
 		/**
 		 * Adds a command definition to the editor instance. Commands added with
-		 * this function can be later executed with {@link #execCommand}.
+		 * this function can be executed later with the <code>{@link #execCommand}</code> method.
 		 * @param {String} commandName The indentifier name of the command.
 		 * @param {CKEDITOR.commandDefinition} commandDefinition The command definition.
@@ -537,6 +538,7 @@
 
 		/**
-		 * Add a trunk of css text to the editor which will be applied to the wysiwyg editing document.
-		 * Note: This function should be called before editor is loaded to take effect.
+		 * Adds a piece of CSS code to the editor which will be applied to the WYSIWYG editing document.
+		 * This CSS would not be added to the output, and is there mainly for editor-specific editing requirements.
+		 * Note: This function should be called before the editor is loaded to take effect.
 		 * @param css {String} CSS text.
 		 * @example
@@ -555,7 +557,7 @@
 		 *		element with the instance contents.
 		 * @example
-		 * alert( CKEDITOR.instances.editor1 );  e.g "object"
-		 * <b>CKEDITOR.instances.editor1.destroy()</b>;
-		 * alert( CKEDITOR.instances.editor1 );  "undefined"
+		 * alert( CKEDITOR.instances.editor1 );  //  E.g "object"
+		 * <strong>CKEDITOR.instances.editor1.destroy()</strong>;
+		 * alert( CKEDITOR.instances.editor1 );  // "undefined"
 		 */
 		destroy : function( noUpdate )
@@ -572,9 +574,10 @@
 
 		/**
-		 * Executes a command.
+		 * Executes a command associated with the editor.
 		 * @param {String} commandName The indentifier name of the command.
-		 * @param {Object} [data] Data to be passed to the command
-		 * @returns {Boolean} "true" if the command has been successfuly
-		 *		executed, otherwise "false".
+		 * @param {Object} [data] Data to be passed to the command.
+		 * @returns {Boolean} <code>true</code> if the command was executed
+		 *		successfully, otherwise <code>false</code>.
+		 * @see CKEDITOR.editor.addCommand
 		 * @example
 		 * editorInstance.execCommand( 'bold' );
@@ -608,10 +611,12 @@
 
 		/**
-		 * Gets one of the registered commands. Note that, after registering a
-		 * command definition with addCommand, it is transformed internally
-		 * into an instance of {@link CKEDITOR.command}, which will be then
-		 * returned by this function.
+		 * Gets one of the registered commands. Note that after registering a
+		 * command definition with <code>{@link #addCommand}</code>, it is
+		 * transformed internally into an instance of
+		 * <code>{@link CKEDITOR.command}</code>, which will then be returned
+		 * by this function.
 		 * @param {String} commandName The name of the command to be returned.
-		 * This is the same used to register the command with addCommand.
+		 * This is the same name that is used to register the command with
+		 * 		<code>addCommand</code>.
 		 * @returns {CKEDITOR.command} The command object identified by the
 		 * provided name.
@@ -628,5 +633,5 @@
 		 * @returns (String) The editor data.
 		 * @example
-		 * if ( CKEDITOR.instances.editor1.<b>getData()</b> == '' )
+		 * if ( CKEDITOR.instances.editor1.<strong>getData()</strong> == '' )
 		 *     alert( 'There is no data available' );
 		 */
@@ -656,9 +661,11 @@
 		/**
 		 * Gets the "raw data" currently available in the editor. This is a
-		 * fast method which return the data as is, without processing, so it's
-		 * not recommended to use it on resulting pages. It can be used instead
-		 * combined with the {@link #loadSnapshot} so one can automatic save
-		 * the editor data from time to time while the user is using the
-		 * editor, to avoid data loss, without risking performance issues.
+		 * fast method which returns the data as is, without processing, so it is
+		 * not recommended to use it on resulting pages. Instead it can be used
+		 * combined with the <code>{@link #loadSnapshot}</code> method in order
+		 * to be able to automatically save the editor data from time to time
+		 * while the user is using the editor, to avoid data loss, without risking
+		 * performance issues.
+		 * @see CKEDITOR.editor.getData
 		 * @example
 		 * alert( editor.getSnapshot() );
@@ -679,11 +686,12 @@
 
 		/**
-		 * Loads "raw data" in the editor. This data is loaded with processing
+		 * Loads "raw data" into the editor. The data is loaded with processing
 		 * straight to the editing area. It should not be used as a way to load
 		 * any kind of data, but instead in combination with
-		 * {@link #getSnapshot} produced data.
+		 * <code>{@link #getSnapshot}</code> produced data.
+		 * @see CKEDITOR.editor.setData
 		 * @example
 		 * var data = editor.getSnapshot();
-		 * editor.<b>loadSnapshot( data )</b>;
+		 * editor.<strong>loadSnapshot( data )</strong>;
 		 */
 		loadSnapshot : function( snapshot )
@@ -693,19 +701,20 @@
 
 		/**
-		 * Sets the editor data. The data must be provided in raw format (HTML).<br />
+		 * Sets the editor data. The data must be provided in the raw format (HTML).<br />
 		 * <br />
-		 * Note that this menthod is asynchronous. The "callback" parameter must
+		 * Note that this method is asynchronous. The <code>callback</code> parameter must
 		 * be used if interaction with the editor is needed after setting the data.
 		 * @param {String} data HTML code to replace the curent content in the
 		 *		editor.
-		 * @param {Function} callback Function to be called after the setData
+		 * @param {Function} callback Function to be called after the <code>setData</code>
 		 *		is completed.
-		 *@param {Boolean} internal Whether suppress  any event firing when copying data internally inside editor.
-		 * @example
-		 * CKEDITOR.instances.editor1.<b>setData</b>( '&lt;p&gt;This is the editor data.&lt;/p&gt;' );
-		 * @example
-		 * CKEDITOR.instances.editor1.<b>setData</b>( '&lt;p&gt;Some other editor data.&lt;/p&gt;', function()
+		 *@param {Boolean} internal Whether to suppress any event firing when copying data
+		 *		internally inside the editor.
+		 * @example
+		 * CKEDITOR.instances.editor1.<strong>setData</strong>( '&lt;p&gt;This is the editor data.&lt;/p&gt;' );
+		 * @example
+		 * CKEDITOR.instances.editor1.<strong>setData</strong>( '&lt;p&gt;Some other editor data.&lt;/p&gt;', function()
 		 *     {
-		 *         this.checkDirty();    // true
+		 *         this.checkDirty();  // true
 		 *     });
 		 */
@@ -732,10 +741,11 @@
 		/**
 		 * Puts or restores the editor into read-only state. When in read-only,
-		 * the user is not able to change the editor contents, but still use
-		 * some editor features. This function sets the readOnly property of
-		 * the editor, firing the "readOnly" event.<br><br>
+		 * the user is not able to change the editor contents, but can still use
+		 * some editor features. This function sets the <code>{@link CKEDITOR.config.readOnly}</code>
+		 * property of the editor, firing the <code>{@link CKEDITOR.editor#readOnly}</code> event.<br><br>
 		 * <strong>Note:</strong> the current editing area will be reloaded.
 		 * @param {Boolean} [isReadOnly] Indicates that the editor must go
-		 *		read-only (true, default) or be restored and made editable (false).
+		 *		read-only (<code>true</code>, default) or be restored and made editable
+		 * 		(<code>false</code>).
 		 * @since 3.6
 		 */
@@ -755,8 +765,8 @@
 
 		/**
-		 * Inserts HTML into the currently selected position in the editor.
+		 * Inserts HTML code into the currently selected position in the editor in WYSIWYG mode.
 		 * @param {String} data HTML code to be inserted into the editor.
 		 * @example
-		 * CKEDITOR.instances.editor1.<b>insertHtml( '&lt;p&gt;This is a new paragraph.&lt;/p&gt;' )</b>;
+		 * CKEDITOR.instances.editor1.<strong>insertHtml( '&lt;p&gt;This is a new paragraph.&lt;/p&gt;' )</strong>;
 		 */
 		insertHtml : function( data )
@@ -767,12 +777,12 @@
 		/**
 		 * Insert text content into the currently selected position in the
-		 * editor, in WYSIWYG mode, styles of the selected element will be applied to the inserted text,
-		 * spaces around the text will be leaving untouched.
-		 * <strong>Note:</strong> two subsequent line-breaks will introduce one paragraph, which element depends on {@link CKEDITOR.config.enterMode};
+		 * editor in WYSIWYG mode. The styles of the selected element will be applied to the inserted text.
+		 * Spaces around the text will be leaving untouched.
+		 * <strong>Note:</strong> two subsequent line-breaks will introduce one paragraph. This depends on <code>{@link CKEDITOR.config.enterMode}</code>;
 		 * A single line-break will be instead translated into one &lt;br /&gt;.
 		 * @since 3.5
 		 * @param {String} text Text to be inserted into the editor.
 		 * @example
-		 * CKEDITOR.instances.editor1.<b>insertText( ' line1 \n\n line2' )</b>;
+		 * CKEDITOR.instances.editor1.<strong>insertText( ' line1 \n\n line2' )</strong>;
 		 */
 		insertText : function( text )
@@ -783,10 +793,10 @@
 		/**
 		 * Inserts an element into the currently selected position in the
-		 * editor.
+		 * editor in WYSIWYG mode.
 		 * @param {CKEDITOR.dom.element} element The element to be inserted
 		 *		into the editor.
 		 * @example
 		 * var element = CKEDITOR.dom.element.createFromHtml( '&lt;img src="hello.png" border="0" title="Hello" /&gt;' );
-		 * CKEDITOR.instances.editor1.<b>insertElement( element )</b>;
+		 * CKEDITOR.instances.editor1.<strong>insertElement( element )</strong>;
 		 */
 		insertElement : function( element )
@@ -796,14 +806,14 @@
 
 		/**
-		 * Checks whether the current editor contents present changes when
+		 * Checks whether the current editor contents contain changes when
 		 * compared to the contents loaded into the editor at startup, or to
-		 * the contents available in the editor when {@link #resetDirty} has
-		 * been called.
-		 * @returns {Boolean} "true" is the contents present changes.
+		 * the contents available in the editor when <code>{@link #resetDirty}</code>
+		 * was called.
+		 * @returns {Boolean} "true" is the contents contain changes.
 		 * @example
 		 * function beforeUnload( e )
 		 * {
-		 *     if ( CKEDITOR.instances.editor1.<b>checkDirty()</b> )
-		 * 	        return e.returnValue = "You'll loose the changes made in the editor.";
+		 *     if ( CKEDITOR.instances.editor1.<strong>checkDirty()</strong> )
+		 * 	        return e.returnValue = "You will lose the changes made in the editor.";
 		 * }
 		 *
@@ -820,9 +830,9 @@
 		/**
 		 * Resets the "dirty state" of the editor so subsequent calls to
-		 * {@link #checkDirty} will return "false" if the user will not make
-		 * further changes to the contents.
-		 * @example
-		 * alert( editor.checkDirty() );  // "true" (e.g.)
-		 * editor.<b>resetDirty()</b>;
+		 * <code>{@link #checkDirty}</code> will return <code>false</code> if the user will not
+		 * have made further changes to the contents.
+		 * @example
+		 * alert( editor.checkDirty() );  // E.g. "true"
+		 * editor.<strong>resetDirty()</strong>;
 		 * alert( editor.checkDirty() );  // "false"
 		 */
@@ -834,6 +844,7 @@
 
 		/**
-		 * Updates the &lt;textarea&gt; element that has been replaced by the editor with
+		 * Updates the <code>&lt;textarea&gt;</code> element that was replaced by the editor with
 		 * the current data available in the editor.
+		 * @see CKEDITOR.editor.element
 		 * @example
 		 * CKEDITOR.instances.editor1.updateElement();
@@ -872,5 +883,5 @@
 
 /**
- * Whether escape HTML when editor update original input element.
+ * Whether to escape HTML when the editor updates the original input element.
  * @name CKEDITOR.config.htmlEncodeOutput
  * @since 3.1
@@ -882,6 +893,6 @@
 
 /**
- * If "true", makes the editor start in read-only state. Otherwise, it'll check
- * if the linked &lt;textarea&gt; has the "disabled" attribute.
+ * If <code>true</code>, makes the editor start in read-only state. Otherwise, it will check
+ * if the linked <code>&lt;textarea&gt;</code> element has the <code>disabled</code> attribute.
  * @name CKEDITOR.config.readOnly
  * @see CKEDITOR.editor#setReadOnly
@@ -896,5 +907,5 @@
  * Fired when a CKEDITOR instance is created, but still before initializing it.
  * To interact with a fully initialized instance, use the
- * {@link CKEDITOR#instanceReady} event instead.
+ * <code>{@link CKEDITOR#instanceReady}</code> event instead.
  * @name CKEDITOR#instanceCreated
  * @event
@@ -910,5 +921,5 @@
 
 /**
- * Fired when the language is loaded
+ * Fired when the language is loaded into the editor instance.
  * @name CKEDITOR.editor#langLoaded
  * @event
@@ -925,5 +936,5 @@
 
 /**
- * Fired before the command execution when {@link #execCommand} is called.
+ * Fired before the command execution when <code>{@link #execCommand}</code> is called.
  * @name CKEDITOR.editor#beforeCommandExec
  * @event
@@ -936,5 +947,5 @@
 
 /**
- * Fired after the command execution when {@link #execCommand} is called.
+ * Fired after the command execution when <code>{@link #execCommand}</code> is called.
  * @name CKEDITOR.editor#afterCommandExec
  * @event
@@ -947,14 +958,13 @@
 
 /**
- * Fired every custom configuration file is loaded, before the final
+ * Fired when the custom configuration file is loaded, before the final
  * configurations initialization.<br />
  * <br />
  * Custom configuration files can be loaded thorugh the
- * {@link CKEDITOR.config.customConfig} setting. Several files can be loading
- * by chaning this setting.
+ * <code>{@link CKEDITOR.config.customConfig}</code> setting. Several files can be loaded
+ * by changing this setting.
  * @name CKEDITOR.editor#customConfigLoaded
  * @event
  * @param {CKEDITOR.editor} editor This editor instance.
- * @example
  */
 
@@ -964,12 +974,9 @@
  * @event
  * @param {CKEDITOR.editor} editor This editor instance.
- * @example
- * if( editor.config.fullPage )
- *     alert( 'This is a full page editor' );
  */
 
 /**
  * Fired when this editor instance is destroyed. The editor at this
- * point isn't usable and this event should be used to perform clean up
+ * point is not usable and this event should be used to perform the clean-up
  * in any plugin.
  * @name CKEDITOR.editor#destroy
@@ -984,5 +991,5 @@
 
 /**
- * Internal event to perform the #getSnapshot call.
+ * Internal event to perform the <code>#getSnapshot</code> call.
  * @name CKEDITOR.editor#getSnapshot
  * @event
@@ -990,12 +997,11 @@
 
 /**
- * Internal event to perform the #loadSnapshot call.
+ * Internal event to perform the <code>#loadSnapshot</code> call.
  * @name CKEDITOR.editor#loadSnapshot
  * @event
  */
 
-
-/**
- * Event fired before the #getData call returns allowing additional manipulation.
+/**
+ * Event fired before the <code>#getData</code> call returns allowing additional manipulation.
  * @name CKEDITOR.editor#getData
  * @event
@@ -1005,5 +1011,5 @@
 
 /**
- * Event fired before the #setData call is executed allowing additional manipulation.
+ * Event fired before the <code>#setData</code> call is executed allowing additional manipulation.
  * @name CKEDITOR.editor#setData
  * @event
@@ -1013,6 +1019,6 @@
 
 /**
- * Event fired at the end of the #setData call is executed. Usually it's better to use the
- * {@link CKEDITOR.editor.prototype.dataReady} event.
+ * Event fired at the end of the <code>#setData</code> call execution. Usually it is better to use the
+ * <code>{@link CKEDITOR.editor.prototype.dataReady}</code> event.
  * @name CKEDITOR.editor#afterSetData
  * @event
@@ -1022,5 +1028,5 @@
 
 /**
- * Internal event to perform the #insertHtml call
+ * Internal event to perform the <code>#insertHtml</code> call
  * @name CKEDITOR.editor#insertHtml
  * @event
@@ -1030,5 +1036,5 @@
 
 /**
- * Internal event to perform the #insertText call
+ * Internal event to perform the <code>#insertText</code> call
  * @name CKEDITOR.editor#insertText
  * @event
@@ -1038,5 +1044,5 @@
 
 /**
- * Internal event to perform the #insertElement call
+ * Internal event to perform the <code>#insertElement</code> call
  * @name CKEDITOR.editor#insertElement
  * @event
@@ -1046,5 +1052,5 @@
 
 /**
- * Event fired after {@link CKEDITOR.editor#readOnly} property changes.
+ * Event fired after the <code>{@link CKEDITOR.editor#readOnly}</code> property changes.
  * @name CKEDITOR.editor#readOnly
  * @event