edit

source/extensibility/packages.rst

@@ -27,14 +27,14 @@ for different purposes.
   as **zip archives**
   in :file:`{Application}/Packages` (short: :file:`{Shipped Packages}`),
   where ``Application`` refers to the folder
-  that the Sublime Text executable resides.
+  where the Sublime Text executable resides.
 
   This folder is not intended to be modified by the user.
 
 .. note::
 
    For simplicity, we will occasionally
-   refer to all these directories simply as :file:`{Packages}`
+   refer to all these directories simply as :file:`{Packages}`,
    and to a package in any folder
    (``.sublime-package`` or not)
    as :file:`{Packages}/PackageName`.
@@ -58,17 +58,16 @@ If you do want to modify files in these archives,
 see :ref:`overriding-packages`.
 
 
-Interactions Between Packages With the Same Name
+Interactions Between Packages with The Same Name
 ************************************************
 
 If two packages with the same name exist
 in both :file:`{Installed Packages}` and :file:`{Shipped Packages}`,
 the one in :file:`{Installed Packages}` will be used
-and the other ignored.
+and the one in :file:`{Shipped Packages}` will be ignored.
 
-Any files in :file:`{Packages}` take precedence
-over their counterpart files in a ``.sublime-package`` package
-or are simply added to the package.
+Any file in :file:`{Packages/Something}` takes precedence
+over any identically named file in :file:`Installed Packages/Something.sublime-package` archive.
 
 See also :ref:`overriding-packages`.
 
@@ -93,11 +92,12 @@ Typical resources found in packages include:
    - syntax definitions (``.tmLanguage``)
    - themes (``.sublime-theme``)
 
+.. XXX Update wit .sublime-syntax
 .. XXX link to respective docs
 .. XXX add secondary extensions (.tmSnippet, .sublime-syntax)
 
 Some packages may hold support files
-for other packages or core features.
+for other packages or for core features.
 For example, the spell checker
 uses :file:`{Installed Packages}/Language - English.sublime-package`
 as a data store for English dictionaries.
@@ -114,22 +114,21 @@ and you don't need to learn it.
 .. glossary::
 
    **shipped packages**
-   **default packages**
       A set of packages
       that Sublime Text ships with.
       Some of these packages are :term:`core packages`,
       while others enhance Sublime Text
       to support common programming languages out of the box.
 
-      Examples: Default, Python, Java, C++, Markdown
+      Examples: Default, Python, Java, C++, Markdown.
 
       Located in :file:`{Shipped Packages}`.
 
    **core packages**
       Sublime Text requires these packages
       in order to function properly.
 
-      Examples: Default, Theme - Default, Color Scheme - Default
+      Examples: Default, Theme - Default, Color Scheme - Default.
 
       They are part of the shipped packages and
       located in :file:`{Shipped Packages}`.
@@ -141,7 +140,7 @@ and you don't need to learn it.
       and are always contributed by users
       or third parties.
 
-      Example: User
+      Example: User.
 
       Located in :file:`{Packages}`
       and :file:`{Installed Packages}`.
@@ -159,7 +158,7 @@ and you don't need to learn it.
          Due to the unfortunate name of this folder,
          talking about *installing*
          packages in Sublime Text
-         becomes a confusing business.
+         is confusing.
 
          Sometimes, in this guide, by *installing* we mean
          'adding a user/third party package to Sublime Text'
@@ -198,9 +197,18 @@ Managing Packages
 Installing Packages
 *******************
 
+Packages can be installed
+in two main ways:
+
+- by copying Sublime Text resources
+  to a folder under :file:`{Packages}`, or
+- by copying a ``.sublime-package`` file
+  to :file:`{Installed Packages}`.
+
+
 .. note::
 
-   Nowadays, regular users
+   Regular users
    rarely need to know
    how to install packages by hand,
    as automatic package managers
@@ -212,42 +220,31 @@ Installing Packages
    .. _Package Control: https://packagecontrol.io
 
 
-Packages can be installed
-in two main ways:
-
-- by copying Sublime Text resources
-  to a folder under :file:`{Packages}`, or
-- by copying a ``.sublime-package`` file
-  to :file:`{Installed Packages}`.
-
-
 .. _disabling-packages:
 
 Disabling Packages
 ******************
 
 To temporarily disable packages,
-you can add them to the ``ignored_packages`` list setting
+you can add them to the ``ignored_packages`` list
 in your :file:`{Packages}/User/Preferences.sublime-settings` file.
-
-Changes are detected when the file is saved
-and packages will be loaded or unloaded on the fly.
+Packages will be loaded or unloaded as needed
+when the settings file is saved.
 
 
 Enabling Packages
 *****************
 
-Similarly to :ref:`disabling-packages`,
-enabling a package is a matter of
-removing the package's name from the ``ignored_packages`` list setting.
+To re-enable a package,
+remove the package's name from the ``ignored_packages`` list
+in your :file:`{Packages}/User/Preferences.sublime-settings` file.
 
 
 Removing Packages
 *****************
 
 If you installed a package with a package manager,
-you should use the method provided by the package manager
-to remove it.
+remove it using the method provided by the package manager.
 
 If you installed a package manually,
 follow this procedure to safely remove a package:
@@ -256,25 +253,26 @@ follow this procedure to safely remove a package:
    while Sublime Text is running.
 #. Close Sublime Text.
 #. Remove the package's resources from the disk.
-4. Finally, you can remove the package
-   from the ``ignored_packages`` list setting,
-   since it doesn't exist anymore.
+#. Remove the package's name from the ``ignored_packages`` list setting.
 
 In addition to the resources
 you have placed initially
 in a :file:`{Packages}` folder or in :file:`{Installed Packages}`,
 plugins may create configuration files
 (such as ``.sublime-settings`` files)
 or other files to store package-related data.
-Usually, you will find them in the *User* package.
-If you want to remove all traces of a package,
-you need to find and remove these files manually.
+Frequently, you will find them in the *User* package.
+Therefore, if you want to remove all traces of a package,
+you will need to find and remove all the additional files
+that it may have installed.
 
 .. warning::
 
-   Shipped Packages are reinstated on every Sublime Text update.
+   Shipped packages are reinstated
+   during every Sublime Text update,
+   so you can't delete them forever.
    If you want to get rid of any of them,
-   :ref:`disable <disabling-packages>` them instead of deleting.
+   :ref:`disable <disabling-packages>` them.
 
 
 .. _overriding-packages:
@@ -284,31 +282,30 @@ Customizing or Overriding Packages
 
 Since packages in ``.sublime-package`` zip archives
 :ref:`are read-only <.sublime-package>`,
-you can not modify them directly.
+you cannot modify them directly.
 However, Sublime Text allows you
 to create an :term:`override package <override packages>`
 that will effectively inject files into the original archive
-without changing the archive file.
+without changing the archive files.
 
 To create an override package,
-just create a new folder under :file:`{Packages}`
+create a new folder under :file:`{Packages}`
 and name it after the ``.sublime-package`` file
-you want to override, without the extension.
+you want to override, excluding the extension.
 Any file you create in this package
-will take precedence over a potential counterpart file
+will take precedence over any identically named file
 in the original package.
 
 Python plugins in override packages
 are able to use relative imports
-for accessing other modules in the ``.sublime-package`` file
+for accessing other modules in the corresponding ``.sublime-package`` file
 as if they were part of it.
 
 .. warning::
 
-   Since you are always overriding entire files,
-   you will not receive any updates for these overridden files
-   if the original ``.sublime-package`` happens to be updated
-   at some point.
+   Files in override packages override entire files.
+   If the overriden file in the corresponding ``.sublime-package`` is updated,
+   you will not be notified.
 
 .. Generally, this only works on resources
    interpreted by Sublime Text directly.
@@ -326,28 +323,32 @@ Merging and Order of Precedence
 
 Package precedence is important for merging certain resources,
 for example, ``.sublime-keymap`` and ``.sublime-settings`` files,
-or for loading plugins (``.py``).
+or for loading plugins (``.py`` files).
 
 If an :term:`override package <override packages>` exists
 for a ``.sublime-package`` package,
-it will be loaded together with the ``.sublime-package`` package.
+it will be loaded at the same time as the ``.sublime-package`` archive.
+
+Sublime Text loads packages in this order:
 
-1. :file:`{Packages}/Default` is loaded.
-#. All :term:`shipped packages` and :term:`installed packages`
-   are joined and loaded in alphabetical order.
-#. All remaining :term:`user packages`
+1. :file:`{Packages}/Default`;
+#. :term:`shipped packages` and :term:`installed packages`,
+   combined and in alphabetical order;
+#. all remaining :term:`user packages`
    that did not override anything
    are loaded in alphabetical order,
-   except for :file:`{Packages}/User`.
-#. :file:`{Packages}/User` is loaded.
+   except for :file:`{Packages}/User`;
+#. :file:`{Packages}/User`
 
 
 Reverting Sublime Text to Its Default Configuration
 ===================================================
 
-For various reasons,
-packages may cause Sublime Text to not function properly
-or have bad interactions between one another.
+Reverting Sublime Text to a fresh state
+solves many problems
+that appear to be bugs in Sublime Text
+but are in fact caused by misbehaving
+packages and plugins.
 
 To revert Sublime Text to its default configuration
 and remove all your settings and configurations,
@@ -359,8 +360,3 @@ so you'll lose all your installed packages.
 
 Always make sure to back up your data
 before taking an extreme measure like this one!
-
-Reverting Sublime Text to a fresh state
-solves many problems
-that appear to be bugs in Sublime Text
-but are in fact caused by misbehaving plugins.