Cleanup of lead-in pages.

Added JB-Dmitry feedback.

reference_guide/editors.md

@@ -2,5 +2,13 @@
 title: Editors
 ---
 
+This section covers working with text in the IntelliJ Platform editor. 
+It is presented in two major sections:
 * [Editor basics tutorial](/tutorials/editor_basics.md)
+  * Using the action system to access a caret placed in a document open in an editor.
+  * Accessing position information about a caret in an editor: coordinate systems and offsets. 
+  * Handling actions activated by keystroke events in the editor. 
 * [Multiple carets](multiple_carets.md)
+  * Working with multiple, independent, carets in one editor.
+  * How multiple carets affect core functionality, editor actions, typing actions, and code insight actions. 
+   

tutorials/editor_basics.md

@@ -2,33 +2,25 @@
 title: Basics of working with the Editor
 ---
 
-
-[Source code](https://github.com/JetBrains/intellij-sdk-docs/tree/master/code_samples/editor_basics)
-
-----------
-
-This tutorial will lead you through the series of steps showing how to work with the IntelliJ Platform Editor, how to access and modify text it contains,
-and how to handle events sent to the editor.
-
+This tutorial will lead you through the series of steps showing how to work with the IntelliJ Platform Editor, how to access and modify text it contains, and how to handle events sent to the editor. 
 * [1. Working With Text](editor_basics/working_with_text.md)
-* [2. Editor coordinates system. Positions and offsets](editor_basics/coordinates_system.md)
+* [2. Editor coordinate systems: positions and offsets](editor_basics/coordinates_system.md)
 * [3. Handling Editor Events](editor_basics/editor_events.md)
 
-**Note:** The described part of the API allows to operate only with text.
-If you need to access PSI please see
-[PSI Cookbook](/basics/psi_cookbook.md)
-section.
+**Note:** The part of the API described in this tutorial only allows operations with text. 
+For operations that require access to the PSI please see the [PSI Cookbook](/basics/psi_cookbook.md) section.
 
-**See also:**
-[editor-ui-api package](upsource:///platform/editor-ui-api),
-[Editor.java](upsource:///platform/editor-ui-api/src/com/intellij/openapi/editor/Editor.java),
-[EditorImpl.java](upsource:///platform/platform-impl/src/com/intellij/openapi/editor/impl/EditorImpl.java).
-[CommonDataKeys.java](upsource:///platform/editor-ui-api/src/com/intellij/openapi/actionSystem/CommonDataKeys.java),
-[DataKey.java](upsource:///platform/editor-ui-api/src/com/intellij/openapi/actionSystem/DataKey.java),
-[AnActionEvent](upsource:///platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnActionEvent.java),
-[DataContext](upsource:///platform/editor-ui-api/src/com/intellij/openapi/actionSystem/DataContext.java)
-
-**Related topics:**
-[Action System](/tutorials/action_system.md)
+**See also:**  
+The following are referenced in the tutorial:
+* The [editor_basics](https://github.com/JetBrains/intellij-sdk-docs/tree/master/code_samples/editor_basics/) plugin code sample,
+* [editor-ui-api package](upsource:///platform/editor-ui-api),
+* Those not found in editor-ui-api package:
+  * [EditorActionManager](upsource:///platform/platform-api/src/com/intellij/openapi/editor/actionSystem/EditorActionManager.java),
+  * [EditorActionHandler](upsource:///platform/platform-api/src/com/intellij/openapi/editor/actionSystem/EditorActionHandler.java),
+  * [TypedActionHandler](upsource:///platform/platform-api/src/com/intellij/openapi/editor/actionSystem/TypedActionHandler.java),
+  * [TypedAction](upsource:///platform/platform-api/src/com/intellij/openapi/editor/actionSystem/TypedAction.java).
 
+**Related topics:** 
+* [Action System](/tutorials/action_system.md)
+* [Threading Issues](/basics/architectural_overview/general_threading_rules.md)
 

tutorials/editor_basics/coordinates_system.md

@@ -37,13 +37,17 @@ public class EditorAreaIllustration extends AnAction {
 }
 ```
 
-## Caret Coordinate Systems
+## Editor Coordinate Systems
 When a `Document` is opened, the `Editor` assigns an internal, zero-based coordinate system to lines and columns in the `Document`. 
 The first line in a `Document` and the first character in each line are assigned the zero position. 
 Every character in a `Document` is assigned an [_Offset_](#caret-offset), which is a zero-based count of the characters from the beginning of the file to that character. 
 These [LogicalPosition](#caret-logical-position) coordinates are used to describe the line and column number for a caret position. 
 Note that the Logical Position coordinate system is different from the editor UI, which is one-based rather than zero-based.
 
+Logical Position coordinates and other coordinate systems discussed in this tutorial can be used to characterize any location in an `Editor`, not just carets. 
+Hints used for code insights are characterized in terms of these coordinates, for example [HintManager.getHintPosition()](upsource:///platform/platform-impl/src/com/intellij/codeInsight/hint/HintManagerImpl.java). 
+Custom visual elements displayed in an `Editor`, called [Inlay](upsource:///platform/editor-ui-api/src/com/intellij/openapi/editor/Inlay.java) objects, are also expressed in terms of these coordinate systems.
+
 The diagram below shows the Logical Position coordinate system applied to some example content. 
 The character "s" in the red box represents placing the cursor on that character. 
 It has the caret position of line 1, column 9, and Offset 28. 
@@ -90,7 +94,7 @@ The comments on each line illustrate how the Soft Wrap portion of Logical line t
 
 ![Caret Visual Position with Soft-Wrap](img/vis_pos_soft_wrap.png){:width="800px"} 
 
-The Logical and Visual Position objects for a caret are obtained from the `Caret` object, as shown in the code snippet below. 
+The Logical and Visual Position objects for a caret are obtained from the [Caret](upsource:///platform/editor-ui-api/src/com/intellij/openapi/editor/Caret.java) object, as shown in the code snippet below. 
 ```java
 public class EditorAreaIllustration extends AnAction {
     @Override