Code conversion completed + docs 1 & 2

.idea/gradle.xml

@@ -16,6 +16,18 @@
           </set>
         </option>
       </GradleProjectSettings>
+      <GradleProjectSettings>
+        <option name="distributionType" value="DEFAULT_WRAPPED" />
+        <option name="externalProjectPath" value="$PROJECT_DIR$/code_samples/editor_basics" />
+        <option name="gradleHome" value="C:/Program Files (x86)/Gradle/gradle-2.9" />
+        <option name="gradleJvm" value="1.8" />
+        <option name="modules">
+          <set>
+            <option value="$PROJECT_DIR$/code_samples/editor_basics" />
+          </set>
+        </option>
+        <option name="useQualifiedModuleNames" value="true" />
+      </GradleProjectSettings>
       <GradleProjectSettings>
         <option name="distributionType" value="DEFAULT_WRAPPED" />
         <option name="externalProjectPath" value="$PROJECT_DIR$/code_samples/gradle_plugin_demo" />

.idea/misc.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <project version="4">
   <component name="ExternalStorageConfigurationManager" enabled="true" />
-  <component name="ProjectRootManager" version="2" languageLevel="JDK_1_8" default="false" project-jdk-name="IU-192.5438.14" project-jdk-type="IDEA JDK">
+  <component name="ProjectRootManager" version="2" languageLevel="JDK_1_8" default="false" project-jdk-name="IU-192.5728.12" project-jdk-type="IDEA JDK">
     <output url="file://$PROJECT_DIR$/build" />
   </component>
 </project>

.idea/modules.xml

@@ -4,7 +4,6 @@
     <modules>
       <module fileurl="file://$PROJECT_DIR$/code_samples/comparing_references_inspection/comparing_references_inspection.iml" filepath="$PROJECT_DIR$/code_samples/comparing_references_inspection/comparing_references_inspection.iml" group="code_samples" />
       <module fileurl="file://$PROJECT_DIR$/code_samples/conditional_operator_intention/conditional_operator_intention.iml" filepath="$PROJECT_DIR$/code_samples/conditional_operator_intention/conditional_operator_intention.iml" group="code_samples" />
-      <module fileurl="file://$PROJECT_DIR$/code_samples/editor_basics/editor_basics.iml" filepath="$PROJECT_DIR$/code_samples/editor_basics/editor_basics.iml" group="code_samples" />
       <module fileurl="file://$PROJECT_DIR$/code_samples/facet_basics/facet_basics.iml" filepath="$PROJECT_DIR$/code_samples/facet_basics/facet_basics.iml" group="code_samples" />
       <module fileurl="file://$PROJECT_DIR$/code_samples/framework/framework.iml" filepath="$PROJECT_DIR$/code_samples/framework/framework.iml" group="code_samples" />
       <module fileurl="file://$PROJECT_DIR$/.idea/intellij-sdk-docs.iml" filepath="$PROJECT_DIR$/.idea/intellij-sdk-docs.iml" />

.idea/runConfigurations/editor_basics.xml

@@ -1,8 +0,0 @@
-<component name="ProjectRunConfigurationManager">
-  <configuration default="false" name="editor_basics" type="#org.jetbrains.idea.devkit.run.PluginConfigurationType" factoryName="Plugin">
-    <module name="editor_basics" />
-    <option name="VM_PARAMETERS" value="-Xmx512m -Xms256m -XX:MaxPermSize=250m -ea" />
-    <option name="PROGRAM_PARAMETERS" value="" />
-    <method />
-  </configuration>
-</component>

code_samples/editor_basics/build.gradle

@@ -0,0 +1,31 @@
+// Copyright 2000-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file.
+
+plugins {
+    id 'java'
+    id 'org.jetbrains.intellij' version '0.4.9'
+}
+
+group 'org.intellij.sdk'
+version '2.0.0'
+
+sourceCompatibility = 1.8
+
+repositories {
+    mavenCentral()
+}
+
+dependencies {
+    testCompile group: 'junit', name: 'junit', version: '4.12'
+}
+
+// See https://github.com/JetBrains/gradle-intellij-plugin/
+intellij {
+  version '2019.2'
+  updateSinceUntilBuild = false
+}
+patchPluginXml {
+  version = project.version
+}
+
+// Force javadoc rebuild before jar is built
+jar.dependsOn javadoc

code_samples/editor_basics/editor_basics.iml

@@ -1,12 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<module type="PLUGIN_MODULE" version="4">
-  <component name="DevKit.ModuleBuildProperties" url="file://$MODULE_DIR$/resources/META-INF/plugin.xml" />
-  <component name="NewModuleRootManager" inherit-compiler-output="true">
-    <content url="file://$MODULE_DIR$">
-      <sourceFolder url="file://$MODULE_DIR$/src" isTestSource="false" />
-      <sourceFolder url="file://$MODULE_DIR$/resources" type="java-resource" />
-    </content>
-    <orderEntry type="inheritedJdk" />
-    <orderEntry type="sourceFolder" forTests="false" />
-  </component>
-</module>

code_samples/editor_basics/gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,5 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-4.10.3-bin.zip
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists

code_samples/editor_basics/gradlew

@@ -0,0 +1,172 @@
+#!/usr/bin/env sh
+
+##############################################################################
+##
+##  Gradle start up script for UN*X
+##
+##############################################################################
+
+# Attempt to set APP_HOME
+# Resolve links: $0 may be a link
+PRG="$0"
+# Need this for relative symlinks.
+while [ -h "$PRG" ] ; do
+    ls=`ls -ld "$PRG"`
+    link=`expr "$ls" : '.*-> \(.*\)$'`
+    if expr "$link" : '/.*' > /dev/null; then
+        PRG="$link"
+    else
+        PRG=`dirname "$PRG"`"/$link"
+    fi
+done
+SAVED="`pwd`"
+cd "`dirname \"$PRG\"`/" >/dev/null
+APP_HOME="`pwd -P`"
+cd "$SAVED" >/dev/null
+
+APP_NAME="Gradle"
+APP_BASE_NAME=`basename "$0"`
+
+# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
+DEFAULT_JVM_OPTS=""
+
+# Use the maximum available, or set MAX_FD != -1 to use that value.
+MAX_FD="maximum"
+
+warn () {
+    echo "$*"
+}
+
+die () {
+    echo
+    echo "$*"
+    echo
+    exit 1
+}
+
+# OS specific support (must be 'true' or 'false').
+cygwin=false
+msys=false
+darwin=false
+nonstop=false
+case "`uname`" in
+  CYGWIN* )
+    cygwin=true
+    ;;
+  Darwin* )
+    darwin=true
+    ;;
+  MINGW* )
+    msys=true
+    ;;
+  NONSTOP* )
+    nonstop=true
+    ;;
+esac
+
+CLASSPATH=$APP_HOME/gradle/wrapper/gradle-wrapper.jar
+
+# Determine the Java command to use to start the JVM.
+if [ -n "$JAVA_HOME" ] ; then
+    if [ -x "$JAVA_HOME/jre/sh/java" ] ; then
+        # IBM's JDK on AIX uses strange locations for the executables
+        JAVACMD="$JAVA_HOME/jre/sh/java"
+    else
+        JAVACMD="$JAVA_HOME/bin/java"
+    fi
+    if [ ! -x "$JAVACMD" ] ; then
+        die "ERROR: JAVA_HOME is set to an invalid directory: $JAVA_HOME
+
+Please set the JAVA_HOME variable in your environment to match the
+location of your Java installation."
+    fi
+else
+    JAVACMD="java"
+    which java >/dev/null 2>&1 || die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
+
+Please set the JAVA_HOME variable in your environment to match the
+location of your Java installation."
+fi
+
+# Increase the maximum file descriptors if we can.
+if [ "$cygwin" = "false" -a "$darwin" = "false" -a "$nonstop" = "false" ] ; then
+    MAX_FD_LIMIT=`ulimit -H -n`
+    if [ $? -eq 0 ] ; then
+        if [ "$MAX_FD" = "maximum" -o "$MAX_FD" = "max" ] ; then
+            MAX_FD="$MAX_FD_LIMIT"
+        fi
+        ulimit -n $MAX_FD
+        if [ $? -ne 0 ] ; then
+            warn "Could not set maximum file descriptor limit: $MAX_FD"
+        fi
+    else
+        warn "Could not query maximum file descriptor limit: $MAX_FD_LIMIT"
+    fi
+fi
+
+# For Darwin, add options to specify how the application appears in the dock
+if $darwin; then
+    GRADLE_OPTS="$GRADLE_OPTS \"-Xdock:name=$APP_NAME\" \"-Xdock:icon=$APP_HOME/media/gradle.icns\""
+fi
+
+# For Cygwin, switch paths to Windows format before running java
+if $cygwin ; then
+    APP_HOME=`cygpath --path --mixed "$APP_HOME"`
+    CLASSPATH=`cygpath --path --mixed "$CLASSPATH"`
+    JAVACMD=`cygpath --unix "$JAVACMD"`
+
+    # We build the pattern for arguments to be converted via cygpath
+    ROOTDIRSRAW=`find -L / -maxdepth 1 -mindepth 1 -type d 2>/dev/null`
+    SEP=""
+    for dir in $ROOTDIRSRAW ; do
+        ROOTDIRS="$ROOTDIRS$SEP$dir"
+        SEP="|"
+    done
+    OURCYGPATTERN="(^($ROOTDIRS))"
+    # Add a user-defined pattern to the cygpath arguments
+    if [ "$GRADLE_CYGPATTERN" != "" ] ; then
+        OURCYGPATTERN="$OURCYGPATTERN|($GRADLE_CYGPATTERN)"
+    fi
+    # Now convert the arguments - kludge to limit ourselves to /bin/sh
+    i=0
+    for arg in "$@" ; do
+        CHECK=`echo "$arg"|egrep -c "$OURCYGPATTERN" -`
+        CHECK2=`echo "$arg"|egrep -c "^-"`                                 ### Determine if an option
+
+        if [ $CHECK -ne 0 ] && [ $CHECK2 -eq 0 ] ; then                    ### Added a condition
+            eval `echo args$i`=`cygpath --path --ignore --mixed "$arg"`
+        else
+            eval `echo args$i`="\"$arg\""
+        fi
+        i=$((i+1))
+    done
+    case $i in
+        (0) set -- ;;
+        (1) set -- "$args0" ;;
+        (2) set -- "$args0" "$args1" ;;
+        (3) set -- "$args0" "$args1" "$args2" ;;
+        (4) set -- "$args0" "$args1" "$args2" "$args3" ;;
+        (5) set -- "$args0" "$args1" "$args2" "$args3" "$args4" ;;
+        (6) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" ;;
+        (7) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" ;;
+        (8) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" ;;
+        (9) set -- "$args0" "$args1" "$args2" "$args3" "$args4" "$args5" "$args6" "$args7" "$args8" ;;
+    esac
+fi
+
+# Escape application args
+save () {
+    for i do printf %s\\n "$i" | sed "s/'/'\\\\''/g;1s/^/'/;\$s/\$/' \\\\/" ; done
+    echo " "
+}
+APP_ARGS=$(save "$@")
+
+# Collect all arguments for the java command, following the shell quoting and substitution rules
+eval set -- $DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS "\"-Dorg.gradle.appname=$APP_BASE_NAME\"" -classpath "\"$CLASSPATH\"" org.gradle.wrapper.GradleWrapperMain "$APP_ARGS"
+
+# by default we should be in the correct project dir, but when run from Finder on Mac, the cwd is wrong
+if [ "$(uname)" = "Darwin" ] && [ "$HOME" = "$PWD" ]; then
+  cd "$(dirname "$0")"
+fi
+
+exec "$JAVACMD" "$@"

code_samples/editor_basics/gradlew.bat

@@ -0,0 +1,84 @@
+@if "%DEBUG%" == "" @echo off
+@rem ##########################################################################
+@rem
+@rem  Gradle startup script for Windows
+@rem
+@rem ##########################################################################
+
+@rem Set local scope for the variables with windows NT shell
+if "%OS%"=="Windows_NT" setlocal
+
+set DIRNAME=%~dp0
+if "%DIRNAME%" == "" set DIRNAME=.
+set APP_BASE_NAME=%~n0
+set APP_HOME=%DIRNAME%
+
+@rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
+set DEFAULT_JVM_OPTS=
+
+@rem Find java.exe
+if defined JAVA_HOME goto findJavaFromJavaHome
+
+set JAVA_EXE=java.exe
+%JAVA_EXE% -version >NUL 2>&1
+if "%ERRORLEVEL%" == "0" goto init
+
+echo.
+echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
+echo.
+echo Please set the JAVA_HOME variable in your environment to match the
+echo location of your Java installation.
+
+goto fail
+
+:findJavaFromJavaHome
+set JAVA_HOME=%JAVA_HOME:"=%
+set JAVA_EXE=%JAVA_HOME%/bin/java.exe
+
+if exist "%JAVA_EXE%" goto init
+
+echo.
+echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME%
+echo.
+echo Please set the JAVA_HOME variable in your environment to match the
+echo location of your Java installation.
+
+goto fail
+
+:init
+@rem Get command-line arguments, handling Windows variants
+
+if not "%OS%" == "Windows_NT" goto win9xME_args
+
+:win9xME_args
+@rem Slurp the command line arguments.
+set CMD_LINE_ARGS=
+set _SKIP=2
+
+:win9xME_args_slurp
+if "x%~1" == "x" goto execute
+
+set CMD_LINE_ARGS=%*
+
+:execute
+@rem Setup the command line
+
+set CLASSPATH=%APP_HOME%\gradle\wrapper\gradle-wrapper.jar
+
+@rem Execute Gradle
+"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" org.gradle.wrapper.GradleWrapperMain %CMD_LINE_ARGS%
+
+:end
+@rem End local scope for the variables with windows NT shell
+if "%ERRORLEVEL%"=="0" goto mainEnd
+
+:fail
+rem Set variable GRADLE_EXIT_CONSOLE if you need the _script_ return code instead of
+rem the _cmd.exe /c_ return code!
+if  not "" == "%GRADLE_EXIT_CONSOLE%" exit 1
+exit /b 1
+
+:mainEnd
+if "%OS%"=="Windows_NT" endlocal
+
+:omega

code_samples/editor_basics/resources/META-INF/plugin.xml

@@ -1,36 +0,0 @@
-<idea-plugin url="www.jetbrains.com">
-  <id>org.jetbrains.plugins.sample.EditorBasics</id>
-  <name>Editor basics</name>
-  <version>1.0</version>
-  <vendor email="support@jetbrains.com" url="https://www.jetbrains.com">JetBrains</vendor>
-
-  <description>Illustration of various basic Editor APIs</description>
-
-  <idea-version since-build="131"/>
-  <depends>com.intellij.modules.lang</depends>
-
-  <!-- Product and plugin compatibility requirements -->
-  <depends>com.intellij.modules.lang</depends>
-
-  <actions>
-    <action id="EditorBasics.EditorIllustration"
-            class="org.jetbrains.tutorials.editor.basics.EditorIllustration"
-            text="Editor Basics"
-            description="Illustrates how to plug an action in">
-      <add-to-group group-id="EditorPopupMenu" anchor="first"/>
-    </action>
-    <action id="EditorBasics.EditorHandlerIllustration"
-            class="org.jetbrains.tutorials.editor.basics.EditorHandlerIllustration"
-            text="Editor Handler"
-            description="Illustrates how to plug an action in">
-      <add-to-group group-id="EditorPopupMenu" anchor="first"/>
-    </action>
-    <action id="EditorBasics.LogicalPositionIllustration"
-            class="org.jetbrains.tutorials.editor.basics.EditorAreaIllustration"
-            text="Caret Position"
-            description="Illustrates how editor area is organized">
-      <add-to-group group-id="EditorPopupMenu" anchor="first"/>
-    </action>
-  </actions>
-
-</idea-plugin>

code_samples/editor_basics/settings.gradle

@@ -0,0 +1,2 @@
+rootProject.name = 'editor'
+

code_samples/editor_basics/src/main/java/icons/EditorBasicsIcons.java

@@ -0,0 +1,11 @@
+// Copyright 2000-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file.
+
+package icons;
+
+import com.intellij.openapi.util.IconLoader;
+
+import javax.swing.*;
+
+public class EditorBasicsIcons {
+  public static final Icon Sdk_default_icon = IconLoader.getIcon("/icons/sdk_16.svg");
+}

code_samples/editor_basics/src/main/java/org/intellij/sdk/editor/EditorAreaIllustration.java

@@ -1,4 +1,6 @@
-package org.jetbrains.tutorials.editor.basics;
+// Copyright 2000-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file.
+
+package org.intellij.sdk.editor;
 
 import com.intellij.openapi.actionSystem.*;
 import com.intellij.openapi.editor.*;
@@ -18,13 +20,18 @@ public class EditorAreaIllustration extends AnAction {
     int offset = caretModel.getOffset();
     Messages.showInfoMessage(logicalPosition.toString() + "\n" +
                              visualPosition.toString() + "\n" +
-                             "Offset: " + offset, "Caret Parameters Inside The Editor");
+                             "Offset: " + offset
+                             // TODO: Remove the next line of diagnostic code
+                             + "\n" + "LogicalPosition.leansForward = " + String.valueOf(logicalPosition.leansForward),
+                             "Caret Parameters Inside The Editor");
   }
 
   @Override
   public void update(AnActionEvent e) {
+    //Get required data keys
     final Project project = e.getData(CommonDataKeys.PROJECT);
     final Editor editor = e.getData(CommonDataKeys.EDITOR);
+    //Set visibility only in case of existing project and editor
     e.getPresentation().setVisible(project != null && editor != null);
   }
 }

code_samples/editor_basics/src/main/java/org/intellij/sdk/editor/EditorHandlerIllustration.java

@@ -1,4 +1,6 @@
-package org.jetbrains.tutorials.editor.basics;
+// Copyright 2000-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file.
+
+package org.intellij.sdk.editor;
 
 import com.intellij.openapi.actionSystem.*;
 import com.intellij.openapi.editor.Editor;

code_samples/editor_basics/src/main/java/org/intellij/sdk/editor/EditorIllustration.java

@@ -1,4 +1,6 @@
-package org.jetbrains.tutorials.editor.basics;
+// Copyright 2000-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file.
+
+package org.intellij.sdk.editor;
 
 import com.intellij.openapi.actionSystem.*;
 import com.intellij.openapi.command.WriteCommandAction;
@@ -24,14 +26,15 @@ public class EditorIllustration extends AnAction {
     final Project project = e.getRequiredData(CommonDataKeys.PROJECT);
     //Access document, caret, and selection
     final Document document = editor.getDocument();
+    // Get information about the selection
     final SelectionModel selectionModel = editor.getSelectionModel();
-
     final int start = selectionModel.getSelectionStart();
     final int end = selectionModel.getSelectionEnd();
-    //Making the replacement
+    //Make the replacement with the name of this plugin
     WriteCommandAction.runWriteCommandAction(project, () ->
-        document.replaceString(start, end, "Replacement")
+        document.replaceString(start, end, "Replaced by editor_basics")
     );
+    // De-select the text range that was just replaced
     selectionModel.removeSelection();
   }
 

code_samples/editor_basics/src/main/java/org/intellij/sdk/editor/MyTypedHandler.java

@@ -1,4 +1,6 @@
-package org.jetbrains.tutorials.editor.basics;
+// Copyright 2000-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file.
+
+package org.intellij.sdk.editor;
 
 import com.intellij.openapi.actionSystem.DataContext;
 import com.intellij.openapi.command.WriteCommandAction;
@@ -10,17 +12,12 @@ import org.jetbrains.annotations.NotNull;
 /**
  * @author Anna Bulenkova
  */
-public class MyTypedHandler implements TypedActionHandler {
+class MyTypedHandler implements TypedActionHandler {
   @Override
   public void execute(@NotNull Editor editor, char c, @NotNull DataContext dataContext) {
     final Document document = editor.getDocument();
     Project project = editor.getProject();
-    Runnable runnable = new Runnable() {
+    Runnable runnable = () -> document.insertString(0, "Inserted by editor_basics\n");
-      @Override
-      public void run() {
-        document.insertString(0, "Typed\n");
-      }
-    };
     WriteCommandAction.runWriteCommandAction(project, runnable);
   }
 }

code_samples/editor_basics/src/main/resources/META-INF/plugin.xml

@@ -0,0 +1,63 @@
+<!-- Copyright 2000-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. -->
+
+<idea-plugin>
+
+  <!--  Unique id for this plugin. Must stay constant for the life of the plugin.  -->
+  <id>org.intellij.sdk.editor</id>
+
+  <!-- Text to display as name on Preferences/Settings | Plugin page  -->
+  <name>SDK: Editor Sample Project</name>
+
+  <!-- The version of this plugin -->
+  <version>2.0.0</version>
+
+  <!-- Compatible with the following versions of IntelliJ Platform -->
+  <idea-version since-build="171"/>
+
+  <!-- Product and plugin compatibility requirements -->
+  <depends>com.intellij.modules.lang</depends>
+
+  <!-- Text to display as description on Preferences/Settings | Plugin page  -->
+  <description>
+    <![CDATA[
+        Illustrates various basic Editor APIs. Requires at least project to be open, and a file open in the editor to see the menu items this plugin adds to the editor popup menu.<br>Mouse over each of this plugin's menu items to see hints in the lower left corner of the IDE.
+      ]]>
+  </description>
+  <change-notes>
+    <![CDATA[
+      <ul>
+        <li><b>2.0.0</b> Convert to Gradle-based plugin</li>
+        <li><b>1.0.0</b> Release 2019.1 and earlier.</li>
+      </ul>
+    ]]>
+  </change-notes>
+
+  <!-- Text to display as company information on Preferences/Settings | Plugin page -->
+  <vendor url="https://plugins.jetbrains.com">IntelliJ Platform SDK</vendor>
+
+  <actions>
+    <action id="EditorBasics.EditorIllustration"
+            class="org.intellij.sdk.editor.EditorIllustration"
+            text="Editor Replace Text"
+            description="Replaces selected text with 'Replacement'."
+            icon="EditorBasicsIcons.Sdk_default_icon">
+      <add-to-group group-id="EditorPopupMenu" anchor="first"/>
+    </action>
+    <action id="EditorBasics.EditorHandlerIllustration"
+            class="org.intellij.sdk.editor.EditorHandlerIllustration"
+            text="Editor Add Caret"
+            description="Adds a second caret below the existing one."
+            icon="EditorBasicsIcons.Sdk_default_icon">
+      <add-to-group group-id="EditorPopupMenu" anchor="first"/>
+    </action>
+    <!-- Place this entry first in the popup menu; it's always enabled if a project and editor are open -->
+    <action id="EditorBasics.LogicalPositionIllustration"
+            class="org.intellij.sdk.editor.EditorAreaIllustration"
+            text="Caret Position"
+            description="Reports information about the caret position."
+            icon="EditorBasicsIcons.Sdk_default_icon">
+      <add-to-group group-id="EditorPopupMenu" anchor="first"/>
+    </action>
+  </actions>
+
+</idea-plugin>

code_samples/editor_basics/src/main/resources/META-INF/pluginIcon.svg

@@ -0,0 +1,58 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="81" height="80" viewBox="0 0 81 80">
+  <defs>
+    <linearGradient id="pluginsdk_80-a" x1="-.031%" x2="100.053%" y1="49.963%" y2="49.963%">
+      <stop offset="25.81%" stop-color="#F97A12"/>
+      <stop offset="45.91%" stop-color="#B07B58"/>
+      <stop offset="72.41%" stop-color="#577BAE"/>
+      <stop offset="91.05%" stop-color="#1E7CE5"/>
+      <stop offset="100%" stop-color="#087CFA"/>
+    </linearGradient>
+    <linearGradient id="pluginsdk_80-b" x1="27.55%" x2="82.223%" y1="34.514%" y2="77.605%">
+      <stop offset="0%" stop-color="#F97A12"/>
+      <stop offset="7.18%" stop-color="#CB7A3E"/>
+      <stop offset="15.41%" stop-color="#9E7B6A"/>
+      <stop offset="24.2%" stop-color="#757B91"/>
+      <stop offset="33.44%" stop-color="#537BB1"/>
+      <stop offset="43.24%" stop-color="#387CCC"/>
+      <stop offset="53.81%" stop-color="#237CE0"/>
+      <stop offset="65.52%" stop-color="#147CEF"/>
+      <stop offset="79.25%" stop-color="#0B7CF7"/>
+      <stop offset="100%" stop-color="#087CFA"/>
+    </linearGradient>
+    <linearGradient id="pluginsdk_80-c" x1="63.121%" x2="40.793%" y1="97.699%" y2="-6.587%">
+      <stop offset="0%" stop-color="#FE315D"/>
+      <stop offset="7.84%" stop-color="#CB417E"/>
+      <stop offset="16.01%" stop-color="#9E4E9B"/>
+      <stop offset="24.74%" stop-color="#755BB4"/>
+      <stop offset="33.92%" stop-color="#5365CA"/>
+      <stop offset="43.65%" stop-color="#386DDB"/>
+      <stop offset="54.14%" stop-color="#2374E9"/>
+      <stop offset="65.76%" stop-color="#1478F3"/>
+      <stop offset="79.4%" stop-color="#0B7BF8"/>
+      <stop offset="100%" stop-color="#087CFA"/>
+    </linearGradient>
+    <linearGradient id="pluginsdk_80-d" x1="25.331%" x2="93.854%" y1="24.119%" y2="132.621%">
+      <stop offset="0%" stop-color="#FE315D"/>
+      <stop offset="4.023%" stop-color="#F63462"/>
+      <stop offset="10.37%" stop-color="#DF3A71"/>
+      <stop offset="16.67%" stop-color="#C24383"/>
+      <stop offset="29.12%" stop-color="#AD4A91"/>
+      <stop offset="54.98%" stop-color="#755BB4"/>
+      <stop offset="91.75%" stop-color="#1D76ED"/>
+      <stop offset="100%" stop-color="#087CFA"/>
+    </linearGradient>
+  </defs>
+  <g fill="none" fill-rule="evenodd">
+    <g fill-rule="nonzero" transform="translate(8 8)">
+      <path fill="url(#pluginsdk_80-a)" d="M6.08754566,64 L2.66453526e-15,59.1000946 L0,26.7918961 L30,38.6703369 L10.1403967,64 L6.08754566,64 Z"/>
+      <path fill="url(#pluginsdk_80-b)" d="M20.9524706,64 L52.2740919,31.9159091 L37.6708832,0.460194805 L38.0580944,1.33226763e-15 L64,0 L64,64 L20.9524706,64 Z"/>
+      <path fill="url(#pluginsdk_80-c)" d="M34.4123783,0 L64,0 L64,28.0366227 L49.0078336,44 L34,0.44696173 L34.4123783,0 Z"/>
+      <path fill="url(#pluginsdk_80-d)" d="M30.3358775,64 L0,64 L0,49.9709549 L6.23437817,29.2830519 L0,27.1596093 L0,0 L39.4697238,0 L58,21.3844805 L30.5381317,63.9259091 L30.3358775,64 Z"/>
+    </g>
+    <g fill-rule="nonzero" transform="translate(12 12)">
+      <rect width="56" height="56" fill="#000"/>
+      <rect width="22" height="4" x="4" y="46" fill="#FFFEFE"/>
+      <path fill="#FFFEFE" d="M11.128,25.28 C8.584,25.28 6.016,24.392 4,22.592 L6.184,19.976 C7.696,21.224 9.28,22.016 11.2,22.016 C12.712,22.016 13.624,21.416 13.624,20.432 L13.624,20.384 C13.624,19.448 13.048,18.968 10.24,18.248 C6.856,17.384 4.672,16.448 4.672,13.112 L4.672,13.064 C4.672,10.016 7.12,8 10.552,8 C13,8 15.088,8.768 16.792,10.136 L14.872,12.92 C13.384,11.888 11.92,11.264 10.504,11.264 C9.088,11.264 8.344,11.912 8.344,12.728 L8.344,12.776 C8.344,13.88 9.064,14.24 11.968,14.984 C15.376,15.872 17.296,17.096 17.296,20.024 L17.296,20.072 C17.296,23.408 14.752,25.28 11.128,25.28 Z M19.512,25.04 L19.512,8.24 L26.064,8.24 C31.344,8.24 34.992,11.864 34.992,16.592 L34.992,16.64 C34.992,21.368 31.344,25.04 26.064,25.04 L19.512,25.04 Z M26.064,11.576 L23.208,11.576 L23.208,21.704 L26.064,21.704 C29.088,21.704 31.128,19.664 31.128,16.688 L31.128,16.64 C31.128,13.664 29.088,11.576 26.064,11.576 Z M37.28,25.04 L37.28,8.24 L40.976,8.24 L40.976,15.584 L47.744,8.24 L52.28,8.24 L45.416,15.368 L52.568,25.04 L48.128,25.04 L42.92,17.888 L40.976,19.904 L40.976,25.04 L37.28,25.04 Z"/>
+    </g>
+  </g>
+</svg>

code_samples/editor_basics/src/main/resources/icons/sdk_16.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 16 16">
+  <g fill="none" transform="translate(1 1)">
+    <rect width="14" height="14" fill="#000"/>
+    <rect width="5" height="1" x="1" y="11" fill="#FFFEFE"/>
+    <path fill="#FFFEFE" d="M1,5.96113281 L1.85546875,5.96113281 C1.89648438,6.30390625 2.2421875,6.52363281 2.74023438,6.52363281 C3.20019531,6.52363281 3.52539063,6.30097656 3.52539063,5.98164062 C3.52539063,5.71210937 3.31445313,5.55683594 2.79589844,5.44550781 L2.24511719,5.32832031 C1.47460938,5.1671875 1.09667969,4.76582031 1.09667969,4.12128906 C1.09667969,3.32441406 1.73828125,2.8 2.71386719,2.8 C3.64550781,2.8 4.3046875,3.32148437 4.33105469,4.07441406 L3.49902344,4.07441406 C3.45800781,3.74042969 3.14746094,3.51777344 2.71972656,3.51777344 C2.27734375,3.51777344 1.984375,3.72285156 1.984375,4.04511719 C1.984375,4.30585937 2.18652344,4.45527344 2.68164063,4.56074219 L3.19140625,4.66914062 C4.04101563,4.84785156 4.40722656,5.2140625 4.40722656,5.8703125 C4.40722656,6.72285156 3.75390625,7.24433594 2.69335938,7.24433594 C1.68554688,7.24433594 1.03222656,6.74921875 1,5.96113281 Z M5.19603365,2.90546875 L6.86009615,2.90546875 C8.11693209,2.90546875 8.84349459,3.6671875 8.84349459,4.99140625 C8.84349459,6.36542969 8.12572115,7.1359375 6.86009615,7.1359375 L5.19603365,7.1359375 L5.19603365,2.90546875 Z M6.08079927,3.66132812 L6.08079927,6.38007812 L6.71947115,6.38007812 C7.50169771,6.38007812 7.94115084,5.89960937 7.94115084,5.00605469 C7.94115084,4.15058594 7.48704927,3.66132812 6.71947115,3.66132812 L6.08079927,3.66132812 Z M10.5170673,7.1359375 L9.63230167,7.1359375 L9.63230167,2.90839844 L10.5170673,2.90839844 L10.5170673,4.7921875 L10.5698017,4.7921875 L12.1313251,2.90839844 L13.1157001,2.90839844 L11.5746845,4.76289062 L13.2240985,7.1359375 L12.1635517,7.1359375 L10.9360126,5.36640625 L10.5170673,5.86152344 L10.5170673,7.1359375 Z"/>
+  </g>
+</svg>

tutorials/editor_basics/coordinates_system.md

@@ -1,20 +1,26 @@
 ---
-title: 2. Editor coordinates system. Positions and offsets
+title: 2. Editor Coordinate Systems - Positions and Offsets
 ---
 
+The previous tutorial [Working with Text](working_with_text.md) discussed extending the [AnAction.java](upsource:///platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java) class, and using an [AnActionEvent](upsource:///platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnActionEvent.java) object.
+The event object provides access to [Project](upsource:///platform/core-api/src/com/intellij/openapi/project/Project.java), [Document](upsource:///platform/core-api/src/com/intellij/openapi/editor/Document.java), and [Editor](upsource:///platform/editor-ui-api/src/com/intellij/openapi/editor/Editor.java) objects.
 
-Every caret in the editor has a set of properties describing its coordinates.
+Every caret has a set of properties describing its position in one of several coordinate systems.
-These properties can be accessed by obtaining a
+This tutorial describes how to access information about the caret(s) in the editor.
-[caret model instance](upsource:///platform/editor-ui-api/src/com/intellij/openapi/editor/CaretModel.java).
-Working with caret positions and their logical and visual properties will be explained in the sample below.
 
 ## 2.1. Pre-requirements
-Access to the Editor is performed through an action.
+In this tutorial the [editor_basics](https://github.com/JetBrains/intellij-sdk-docs/tree/master/code_samples/editor_basics) code sample is used to explore caret positions.
+In particular, the **Caret Position** action added by `editor_basics` to the editor context menu is used to retrieve information about the current caret position.  
 
-## 2.2. Accessing caret positions
+![Editor Basics Menu](img/edit_basics_menu.png){:width="600px"}
 
-To get an access to caret positions an instance of `CaretModel` should be obtained.
+The source code for the Java class behind the menu action is [EditorAreaIllustration.java](https://github.com/JetBrains/intellij-sdk-docs/blob/master/code_samples/editor_basics/src/main/java/org/intellij/sdk/editor/EditorAreaIllustration.java).
+The focus of discussion will be the `EditorAreaIllustration.actionPerformed()` method.
 
+## 2.2. Accessing Caret Positions from the CaretModel Object
+The properties of a caret can be accessed by obtaining an instance of the [CaretModel](upsource:///platform/editor-ui-api/src/com/intellij/openapi/editor/CaretModel.java) object for a caret.
+As in the [Working with Text](working_with_text.md) tutorial, the `AnActionEvent` is used to get the `Editor` object.
+The `Editor` object provides access to the `CaretModel` object, as shown below:
 ```java
 public class EditorAreaIllustration extends AnAction {
     @Override
@@ -23,18 +29,45 @@ public class EditorAreaIllustration extends AnAction {
         CaretModel caretModel = editor.getCaretModel();
     }
     @Override
-    public void update(AnActionEvent e) {
+    public void update(AnActionEvent e) { /* ... */ }
-       //...
-    }
 }
 ```
 
-## 2.3. Logical position
+## 2.3. Caret Position
+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.
+Note that the editor coordinate system is different from what is shown in the editor UI, which is one-based rather than zero-based.
 
-[LogicalPosition.java](upsource:///platform/editor-ui-api/src/com/intellij/openapi/editor/LogicalPosition.java)
+[//]: # (TODO: Mention multiple carets, primary carets, single caret in Editor = primary caret)
-represents a line and a column of the current logical position of the caret. Logical positions ignore folding —
-for example, if the top 10 lines of the document are folded, the 10th line in the document will have the line number 10 in its logical position.
 
+### 2.3.1. Caret Logical Position
+The caret _Logical Position_ is a zero-based, (line and column) position of the caret in the Editor Tool Window.
+Line values are based on the corresponding lines in the underlying Document being edited.
+Logical Position information is obtained from the [LogicalPosition](upsource:///platform/editor-ui-api/src/com/intellij/openapi/editor/LogicalPosition.java) object for that caret.   
+
+The Logical Position line number of a caret ignores the effects of settings that change the presentation of a Document within the Editor Tool Window.
+Examples of these settings are [Code (Line) Folding](https://www.jetbrains.com/help/idea/working-with-source-code.html#code_folding) and [Soft Line Wrap](https://www.jetbrains.com/help/idea/using-code-editor.html#f804afd8). 
+This means regardless of whether one or more lines in an Editor Tool Window are folded or soft-wrapped, the caret Logical Position line number will not change.
+
+The image below shows the simplest case of reporting Logical Position using the caret position functionality of the `editor_basics` plugin.
+No Soft Wrap or Code Folding is applied.
+Each line has a comment showing the Logical Position line number.
+The caret - a blue block - is placed on the letter "p" in "public".
+The caret is reported to be at Logical Position (5,0) - which is Logical (Position) line 5, character 0 - the first character in the line.
+[Caret Visual Position](#232-caret-visual-position), [caret leaning,](#233-caret-column-position), and [caret offset](#234-caret-offset) are discussed in later sections.  
+
+![Caret Logical Position](img/logical_pos_exp.png){:width="800px"}
+
+If Logical Position line numbers 1-3 are folded into line 0, the caret is still reported as Logical Position (5,0).
+This means that caret Logical Position is not changed by Code Folding:  
+
+![Caret Logical Position with Folding](img/logical_pos_folded.png){:width="800px"} 
+
+However, note that applying Code Folding _does change the reported Visual Position_ of the caret even if the Logical Position stays constant.
+More about [Visual Position](#232-caret-visual-position) is discussed below, but it's clear combinations of Code Folding and Soft Wrap can mean that one Logical Position of a caret could map to multiple Visual Positions.
+It is for this reason the Editor interface provides a number of methods to work with a caret Logical and Visual Position, such as the method `Editor.logicalToVisualPosition()`.
+
+The `LogicalPosition` object for a caret is obtained from the caret's `CaretModel`object, as shown in the code snippet below.
 ```java
 public class EditorAreaIllustration extends AnAction {
     @Override
@@ -44,25 +77,26 @@ public class EditorAreaIllustration extends AnAction {
         LogicalPosition logicalPosition = caretModel.getLogicalPosition();
     }
     @Override
-    public void update(AnActionEvent e) {
+    public void update(AnActionEvent e) { /* ... */ }
-        //...
-    }
 }
 ```
 
-Logical position may store additional parameters that define its mapping to
+### 2.3.2. Caret Visual Position
-[VisualPosition.java](upsource:///platform/editor-ui-api/src/com/intellij/openapi/editor/VisualPosition.java).
+A caret's _Visual Position_ differs from Logical Position in that it takes into account editor presentation settings such as Code Folding and Soft Line Wrap.
-Rationale is that a single logical pair matches a virtual space introduced by soft wrap, i.e. different visual positions
+In doing so, [VisualPosition](upsource:///platform/editor-ui-api/src/com/intellij/openapi/editor/VisualPosition.java) counts - zero-based - the lines of a Document that are _displayed_ in an editor Tool Window.  
-may correspond to the same logical position. It's convenient to store exact visual location details within the logical
+Consequently, Visual Position lines are not uniquely mapped to corresponding lines in the underlying Document being edited.
-position in order to simplify further 'logical position' -> 'visual position' mapping.
 
-## 2.4. Visual position
+For example, when Soft Line Wrap is applied to a line displayed in an Editor Tool Window it affects the Visual Position.
+In the image below, Soft Line Wrap has been applied to Logical line three.
+With the caret placed at the same location as in previous tests, it is evident the Logical Position has not changed.
+However, the Visual Position line number has increased by 1!
+The comments on each line illustrate how the Soft Wrap portion of Editor Line three is considered Visual Position line four, as though it was a separate line.
 
-[VisualPosition.java](upsource:///platform/editor-ui-api/src/com/intellij/openapi/editor/VisualPosition.java)
+![Caret Visual Position with Soft-Wrap](img/vis_pos_soft_wrap.png){:width="800px"} 
-represents a visual position and may differ from the corresponding logical position.
-Visual positions take folding into account — for example,
-if the top 10 lines of the document are folded, the 10th line in the document will have the line number 1 in its visual position.
 
+The Editor interface provides a number of methods to work with a caret Logical and Visual Position, such as the method `Editor.visualToLogicalPosition()`.
+
+The Visual Position object for a caret is obtained from the caret's `CaretModel` object, as shown in the code snippet below. 
 ```java
 public class EditorAreaIllustration extends AnAction {
     @Override
@@ -73,16 +107,58 @@ public class EditorAreaIllustration extends AnAction {
         VisualPosition visualPosition = caretModel.getVisualPosition();
     }
     @Override
-    public void update(AnActionEvent e) {
+    public void update(AnActionEvent e) { /* ... */ }
-        //...
-    }
 }
 ```
 
-## 2.5. Offset
+### 2.3.3. Caret Column Position
+The _Column Position_ is a count of characters from the beginning of a Logical (Position) line to the current caret position in that line.
+Characters are counted using a zero-based numbering system, so the first character of a line is numbered zero.
+Note that Column Position is different from what is shown in the editor UI, which uses a one-based numbering scheme.
 
-An absolute offset for a given caret position is accessible through `CaretModel` as well:
+Column Position includes:
+* The first character in a Logical line.
+* Whitespace, such as tabs.
+  Tabs can occupy multiple columns, up to the tab size set for the editor.
+* The character selected by the caret.
 
+More specifically, the Logical Position of a caret represents the boundary between two characters.
+As defined in the [LogicalPosition](upsource:///platform/editor-ui-api/src/com/intellij/openapi/editor/LogicalPosition.java) class, if a caret position is associated with a succeeding character it is said to _Lean Forward_.
+
+[//]: # (TODO: Add an understandable definition for characters leaning forward. BOL leans, just before "space" does not.)
+
+In the example below, placing a (red) line caret on the first visible character in Logical line three produces a **complete lack of lean forward?!**
+**Only with caret color #FF0000 ?! The same color as for 'Unknown Symbol' in my Preferences \| Editor \| Color Scheme \| General**
+
+[//]: # (TODO: Why does this not work for red line caret?)
+
+![Caret Column Position - Line Caret](img/caret_col_pos_line.png){:width="800px"} 
+
+In the example below, placing a (blue) block caret on the first visible character in Logical line three produces a column position of 0 for both Visual and Logical Positions.
+In both Visual and Logical Positions the character leans forward, meaning it is associated with the succeeding character in the Logical line.
+
+[//]: # (TODO: Why does this seem to always return leans forward for a block caret?)
+
+![Caret Column Position - Block Caret](img/caret_col_pos_block.png){:width="800px"} 
+
+
+### 2.3.4. Caret Offset
+The _Offset_ of a caret is a character count from the beginning of a Document to the caret position.
+Caret offsets are always calculated in terms of Logical Position.
+The caret Offset includes:
+* The first (0th) character in a document.
+* Whitespace characters, including end-of-line and tabs.
+* Any characters after end-of-line if the IDE settings permit them.
+  (**Preferences \| Editor \| General \| Virtual Space**)
+* The character selected by the caret.
+
+The example below demonstrates the Offset of a caret placed at the first character of Logical line one.
+Note the Offset is 22, which is 1 greater than the number of visible characters on line one, and the first character on line two.
+This is because the Offset includes the EOL character for the first line.
+
+![Line 2 Caret Offset](img/caret_offset_l2.png){:width="800px"}
+
+The Offset for a given caret position is accessible through `CaretModel` as well:
 ```java
 public class EditorAreaIllustration extends AnAction {
     @Override
@@ -94,15 +170,14 @@ public class EditorAreaIllustration extends AnAction {
         int offset = caretModel.getOffset();
     }
     @Override
-    public void update(AnActionEvent e) {
+    public void update(AnActionEvent e) { /* ... */ }
-        //...
+ }
-    }
-}
 ```
 
-## 2.6. Displaying position values
+
-To display the actual values of logical and visual positions we add an
+## 2.4. Displaying position values
-`Messages.showInfoMessage()` call that will show them in form of notification after the action is performed.
+To display the actual values of logical and visual positions an
+`Messages.showInfoMessage()` call shows them in form of notification after the action is performed.
 
 ```java
 public class EditorAreaIllustration extends AnAction {
@@ -118,28 +193,9 @@ public class EditorAreaIllustration extends AnAction {
                         "Offset: " + offset, "Caret Parameters Inside The Editor");
     }
     @Override
-    public void update(AnActionEvent e) {
+    public void update(AnActionEvent e) { /* ... */ }
-           //...
-    }
 }
 ```
 
-Check out, compile, and run the
+[//]: # (TODO: Add section with hints for reader to work with multiple carets.)
-[Editor Basics Plugin](https://github.com/JetBrains/intellij-sdk-docs/tree/master/code_samples/editor_basics),
-then move carets, invoke
-[EditorAreaIllustration](https://github.com/JetBrains/intellij-sdk-docs/blob/master/code_samples/editor_basics/src/org/jetbrains/tutorials/editor/basics/EditorAreaIllustration.java)
-action, and see how logical and visual positions are related dependently on folding.
-
-Find the action in the context menu:
-
-![Show coordinates action](img/coordinates_action.png)
-
-Perform the action to see caret positions:
-
-![Show coordinates action](img/coordinates_demo.png)
-
-
-
-
-
 

tutorials/editor_basics/working_with_text.md

@@ -4,47 +4,45 @@ title: 1. Working with text
 
 The following set of steps will show how to access a text selection and change it.
 
+## 1.1. Introduction
+This tutorial relies heavily on the [editor_basics](https://github.com/JetBrains/intellij-sdk-docs/tree/master/code_samples/editor_basics/) plugin code sample from the IntelliJ Platform SDK.
+It may be helpful to open that project in an IntelliJ Platform-based IDE, build the project, run it, select some text in the editor, and invoke the "Editor Replace Text" menu item on the editor context menu.
 
-## 1.1. Pre-requirements
+-----------
 
-### 1.1.1 Creating a new action
+![String replacement action](img/basics.png){:width="600px"}
 
-In this example we access the editor from an action.
+-----------
-To create an action we need to extend the
-[AnAction.java](upsource:///platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java)
-class.
 
+### 1.1.1 Creating a New action
+The source code for the Java class in this example is [EditorIllustration.java](https://github.com/JetBrains/intellij-sdk-docs/blob/master/code_samples/editor_basics/src/main/java/org/intellij/sdk/editor/EditorIllustration.java).
 
+In this example, we access the editor from an action.
+To create an action we need to extend the [AnAction.java](upsource:///platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnAction.java) class.
 ```java
 public class EditorIllustration extends AnAction {
 }
 ```
 
-
+### 1.1.2. Registering an Action
-### 1.1.2. Registering an action
+To register the action, we should add the corresponding elements to the `<actions>` section of the plugin configuration file
-
+[plugin.xml](https://github.com/JetBrains/intellij-sdk-docs/blob/master/code_samples/editor_basics/src/main/resources/META-INF/plugin.xml)
-To register the action we should add the corresponding tag to the `<actions>` section of the plugin configuration file
-[plugin.xml](https://github.com/JetBrains/intellij-sdk-docs/blob/master/code_samples/editor_basics/resources/META-INF/plugin.xml)
-
-
 ```xml
-<actions>
+    <action id="EditorBasics.EditorIllustration"
-    <action id="EditorBasics.EditorIllustration" class="EditorIllustration" text="Editor Basics"
+            class="org.intellij.sdk.editor.EditorIllustration"
-        description="Illustrates how to plug an action in">
+            text="Editor Replace Text"
-        <add-to-group group-id="EditorPopupMenu" anchor="last"/>
+            description="Replaces selected text with 'Replacement'."
+            icon="EditorBasicsIcons.Sdk_default_icon">
+      <add-to-group group-id="EditorPopupMenu" anchor="first"/>
     </action>
-</actions>
 ```
 
-If an action is registered in the group `EditorPopupMenu`, like the sample above shows,
+If an action is registered in the group `EditorPopupMenu`, as the sample above shows,
 it will be available from the context menu when the focus is located in the editor.
 
-
+### 1.1.3. Defining Action's Visibility
-### 1.1.3. Defining action's visibility
-
 To determine conditions by which the action will be visible and available for being executed we need to override its
 `public void update(AnActionEvent e)` method.
-
 ```java
 public class EditorIllustration extends AnAction {
     @Override
@@ -54,19 +52,15 @@ public class EditorIllustration extends AnAction {
 ```
 
 If we want to work with a selected part of the text, it's reasonable to make the action available only when the following requirements are met:
+* There is a [Project](upsource:///platform/core-api/src/com/intellij/openapi/project/Project.java) object,
+* There is an instance of [Editor](upsource:///platform/editor-ui-api/src/com/intellij/openapi/editor/Editor.java) available,
+* There is a text selection in `Editor`.
 
-* There is a project open
+Further steps will show how to check these conditions through obtaining instances of `Project` and `Editor` objects, and how to show or hide the action's menu items based on them.
-* There is an instance of the Editor available
-* There is a text selection in the Editor
-
-Further steps will show how to check these conditions through obtaining instances of Project and Editor and how to show or hide the action based on them.
-
-## 1.2. Getting an instance of the active Editor
-
-A reference to an instance of the Editor can be obtained by calling `getData(CommonDataKeys.EDITOR)`.
-To obtain a project reference, we use the `getProject()` method.
-
 
+## 1.2. Getting an Instance of the Active Editor from an Event
+Using the [AnActionEvent](upsource:///platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnActionEvent.java) event passed into the `update` method, a reference to an instance of the editor can be obtained by calling `getData(CommonDataKeys.EDITOR)`.
+Similarly, to obtain a project reference, we use the `getProject()` method.
 ```java
 public class EditorIllustration extends AnAction {
     @Override
@@ -74,30 +68,24 @@ public class EditorIllustration extends AnAction {
         //Get required data keys
         final Project project = e.getProject();
         final Editor editor = e.getData(CommonDataKeys.EDITOR);
-        //Set visibility only in case of existing project and editor
+        //Set visibility only in case of existing project and editor (for now, selection is added below)
         e.getPresentation().setVisible(project != null && editor != null);
     }
 }
 ```
 
-**Note:**
+**Note:**  
-
+There are other ways to access an `Editor` instance:
-To access an Editor instance, other ways can also be used:
+* If a [DataContext](upsource:///platform/editor-ui-api/src/com/intellij/openapi/actionSystem/DataContext.java) object is available: `final Editor editor = CommonDataKeys.EDITOR.getData(context);`
-
+* If only a `Project` object is available, use `FileEditorManager.getInstance(project).getSelectedTextEditor()`
-* If [DataContext](upsource:///platform/editor-ui-api/src/com/intellij/openapi/actionSystem/DataContext.java)
-  object is available: `final Editor editor = CommonDataKeys.EDITOR.getData(context);`
-
-* If only a `Project` is available, you can use `FileEditorManager.getInstance(project).getSelectedTextEditor()`
 
 
-## 1.3. Obtaining a caret model and selection
+## 1.3. Obtaining a Caret Model and Selection
-
+After making sure a project is open and an instance of the editor is obtained, we need to check if any selection is available.
-After making sure we have a project open and an instance of the Editor we need to check if any selection is available and set action's visibility according to these conditions.
+The [SelectionModel](upsource:///platform/editor-ui-api/src/com/intellij/openapi/editor/SelectionModel.java) interface is accessed from the `Editor` object.
-[SelectionModel](upsource:///platform/editor-ui-api/src/com/intellij/openapi/editor/SelectionModel.java)
+Determining whether some text is selected is accomplished by calling the `hasSelection()` method.
-accessed from the Editor allows to do it by calling its `hasSelection()` method.
 Here's how our `update(AnActionEvent e)` method should look like in the end:
 
-
 ```java
 public class EditorIllustration extends AnAction {
     @Override
@@ -105,21 +93,17 @@ public class EditorIllustration extends AnAction {
         //Get required data keys
         final Project project = e.getProject();
         final Editor editor = e.getData(CommonDataKeys.EDITOR);
-        //Set visibility only in case of existing project and editor and if some text in the editor is selected
+        //Set visibility only in case of the existence of a project, editor, and if text is selected in the editor
-        e.getPresentation().setVisible(project != null && editor != null &&
+        e.getPresentation().setVisible( project != null 
-            editor.getSelectionModel().hasSelection());
+                                          && editor != null 
+                                          && editor.getSelectionModel().hasSelection() );
     }
 }
 ```
 
 **Note:**
-Editor allows to access different models of text representation. 
+`Editor` also allows access to different models of text representation. 
-Model classes are located in
+The model classes are located in [editor](upsource:///platform/editor-ui-api/src/com/intellij/openapi/editor), and include:
-[editor](upsource:///platform/editor-ui-api/src/com/intellij/openapi/editor)
-subpackage of the
-[editor-ui-api](upsource:///platform/editor-ui-api)
-package and include:
-
 * [CaretModel.java](upsource:///platform/editor-ui-api/src/com/intellij/openapi/editor/CaretModel.java),
 * [FoldingModel.java](upsource:///platform/editor-ui-api/src/com/intellij/openapi/editor/FoldingModel.java),
 * [IndentsModel.java](upsource:///platform/editor-ui-api/src/com/intellij/openapi/editor/IndentsModel.java),
@@ -127,32 +111,21 @@ package and include:
 * [SoftWrapModel.java](upsource:///platform/editor-ui-api/src/com/intellij/openapi/editor/SoftWrapModel.java)
 
 
-## 1.4. Obtaining a Document
+## 1.4. Obtaining the Document
-
+The `EditorIllustration` action menu item is visible and available now. 
-The action is visible and available now. 
+To make it do something we need to override its `actionPerformed()` method.
-In order to make it do something we need to override its
-`public void actionPerformed(AnActionEvent anActionEvent)` method.
-
-
 ```java
 public class EditorIllustration extends AnAction {
-    @Override
-    public void update(AnActionEvent e) {
-        //code here
-    }
     @Override
     public void actionPerformed(AnActionEvent anActionEvent) {
     }
 }
 ```
 
-To modify the text an instance of the
+Modifying the text requires an instance of the [Document](upsource:///platform/core-api/src/com/intellij/openapi/editor/Document.java) object, which is accessed from the `Editor` object. 
-[Document](upsource:///platform/core-api/src/com/intellij/openapi/editor/Document.java)
+The [Document](/basics/architectural_overview/documents.md) represents the contents of a text file loaded into memory and possibly opened in an IDEA text editor.
-needs to be accessed. [Document](/basics/architectural_overview/documents.md) represents the contents of a text file loaded into memory and possibly opened in an IDEA text editor.
 The instance of a Document will be used later when a text replacement is performed.
-We also need to figure out where the selected part of the text is located.
+We also need to figure out where the selected part of the text is located in the document.
-
-
 ```java
 @Override
 public void actionPerformed(final AnActionEvent e) {
@@ -167,14 +140,11 @@ public void actionPerformed(final AnActionEvent e) {
 }
 ```
 
-## 1.5. Modifying text
+## 1.5. Modifying Text
-
+Generally, text replacement can be done by calling the `Document` object's `replaceString()` method. 
-Generally replacement can be done by calling
+However, safely replacing the text requires the Document to be locked and any changes performed in a [write action](upsource:///platform/core-api/src/com/intellij/openapi/command/WriteCommandAction.java)<!--#L172-->.
-`void replaceString(int startOffset, int endOffset, @NotNull CharSequence s);` of the Document, however,
-the operation of replacement must be executed safely, this means the Document must be locked and
-any changes should be performed in a [write action](upsource:///platform/core-api/src/com/intellij/openapi/command/WriteCommandAction.java)<!--#L172-->.
 See the [Threading Issues](/basics/architectural_overview/general_threading_rules.md) section to learn more about synchronization issues and changes safety on the IntelliJ Platform.
-
+This example changes the document within a `WriteCommandAction`.
 ```java
 @Override
 public void actionPerformed(final AnActionEvent e) {
@@ -183,26 +153,17 @@ public void actionPerformed(final AnActionEvent e) {
     final Project project = e.getProject();
     //Access document, caret, and selection
     final Document document = editor.getDocument();
+     // Get information about the selection
     final SelectionModel selectionModel = editor.getSelectionModel();
-
     final int start = selectionModel.getSelectionStart();
     final int end = selectionModel.getSelectionEnd();
-    //Making the replacement
+    //Make the replacement
     WriteCommandAction.runWriteCommandAction(project, () ->
         document.replaceString(start, end, "Replacement")
     );
+    // Deselect the replaced text
     selectionModel.removeSelection();
 }
 ```
 
------------
 
-![String replacement action](img/basics.png)
-
------------
-
-The source code is located in
-[EditorIllustration.java](https://github.com/JetBrains/intellij-sdk-docs/blob/master/code_samples/editor_basics/src/org/jetbrains/tutorials/editor/basics/EditorIllustration.java).
-To see how text replacement works, check out
-[Editor Basics](https://github.com/JetBrains/intellij-sdk-docs/tree/master/code_samples/editor_basics/src/org/jetbrains/tutorials/editor/basics/)
-plugin, make the project, run it, then invoke the *EditorIllustration* action which is available in the context menu of the editor.