Merge branch 'feature/enhance_packages_doc'

Adds a new "Troubleshooting" page in the extensibility section.

Author: FichteFoll

docs/.vitepress/config.ts

@@ -133,6 +133,7 @@ export default defineConfig({
             },
             { text: 'Snippets', link: '/guide/extensibility/snippets.md' },
             { text: 'Syntax Definitions', link: '/guide/extensibility/syntaxdefs.md' },
+            { text: 'Troubleshooting', link: '/guide/extensibility/troubleshooting.md' },
           ],
         },
         {

docs/guide/extensibility/images/safe_mode_announcement.png

@@ -72,10 +72,12 @@ Typical resources found in packages include:
 - key maps (`.sublime-keymap`)
 - macros (`.sublime-macro`)
 - menus (`.sublime-menu`)
+- commands (`.sublime-commands`)
 - metadata (`.tmPreferences`)
 - mouse maps (`.sublime-mousemap`)
 - plugins (`.py`)
 - settings (`.sublime-settings`)
+- completions (`.sublime-completions`)
 - snippets (`.sublime-snippet`)
 - syntax definitions (`.sublime-syntax`, `.tmLanguage`)
 - themes (`.sublime-theme`)
@@ -101,7 +103,7 @@ and you don't need to learn it.
   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, reStructuredText, YAML
 
   Located in `Shipped Packages`.
 
@@ -241,6 +243,7 @@ If you want to stop using a shipped package,
 
 
 ## Customizing or Overriding Packages
+
 [overriding]: #customizing-or-overriding-packages
 
 Since packages in `.sublime-package` zip archives
@@ -255,30 +258,38 @@ To create an override package,
 create a new folder under `Packages`
 and name it after the `.sublime-package` file
 you want to override, excluding the extension.
-Any file you create in this package
-will take precedence over any identically named file
+
+Any file you create in this package directory
+will replace any identically named (and path-ed) file
 in the original package.
+Sublime Text will completely ignore the same-named file inside the `.sublime-package`
+and use your replacement for all purposes.
+Note that this is unlike the effect of placing files in the `User` Package,
+where, for certain JSON file types like settings,
+Sublime Text [merges][merging] them into global data structures.
 
 Python plugins in override packages
 are able to use relative imports
 for accessing other modules in the corresponding `.sublime-package` file
 as if they were part of it.
 
 ::: warning
-  Files in override packages override entire files.
-  If the overridden file in the corresponding `.sublime-package` is updated,
-  you will not be notified.
+Files in override packages override the *entire file*.
+If the overridden file in the corresponding `.sublime-package` is updated,
+you will not be notified.
 
-  The [OverrideAudit][] package provides monitoring of override files
-  and will notify you
-  when the file it overrides has been updated.
+The [OverrideAudit][] package provides monitoring of override files
+and will notify you
+when the file it overrides has been updated.
 
-  [OverrideAudit]: https://github.com/OdatNurd/OverrideAudit
+[OverrideAudit]: https://github.com/OdatNurd/OverrideAudit
 :::
 
 
 ## Merging and Order of Precedence
 
+[merging]: #merging-and-order-of-precedence
+
 Package precedence is important for merging certain resources,
 for example, `.sublime-keymap` and `.sublime-settings` files,
 and for loading plugins (`.py` files).
@@ -299,22 +310,3 @@ Sublime Text loads packages in this order:
 1. `Packages/User`
 
 
-## Reverting Sublime Text to Its Default Configuration
-
-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.
-
-<!-- TODO --safe-mode -->
-To revert Sublime Text to its default configuration
-and remove all your settings and configurations,
-delete the [Data directory](../getting-started/basic-concepts.md#the-data-directory)
-and restart the editor.
-Keep in mind
-that the `Installed Packages` folder will be deleted too,
-so you'll lose all your installed packages.
-
-Always make sure to back up your data
-before taking an extreme measure like this one!

docs/guide/extensibility/packages.md

@@ -0,0 +1,152 @@
+## Troubleshooting
+
+Because Sublime Text is so customizable,
+it is possible for third-party packages and/or local customization
+to interfere with one another or cause other problems.
+You might see this, for example,
+as Python exceptions that don't make sense in the Console Panel,
+or certain functionality isn't behaving as you expect.
+
+### Safe Mode
+
+![Safe Mode Announcement](./images/safe_mode_announcement.png)
+
+Starting with version 4,
+you can launch Sublime Text in *Safe Mode*
+via the Command Line Interface:
+
+```sh
+subl --safe-mode
+```
+
+Additionally on Windows and Mac,
+holding a modifier key while starting the application
+will open it in Safe Mode:
+
+* **Windows**: <Key k="shift+alt" />
+* **Mac**: <Key k="option" />
+
+When launched this way,
+Sublime Text uses an alternate [Data directory][],
+thus disabling all third-party packages and local customizations,
+as well as not loading any previously opened sessions.
+This will help you to verify whether the behavior you are observing
+is or is not coming from Sublime Text itself
+or one of its shipped packages.
+
+The alternate Data directory used is:
+
+* **Windows**: `%APPDATA%\Sublime Text (Safe Mode)\`
+* **macOS**: `~/Library/Application Support/Sublime Text (Safe Mode)/`
+* **Linux**: `~/.config/sublime-text-safe-mode/`
+
+Another nice aspect about Safe Mode is
+that you can perform experimental customizations
+or packages you think might have caused problems
+without affect Sublime Text's ability
+to start and behave normally,
+because:
+
+- such packages will be installed in the alternate Data directory,
+  thus not impacting normal sessions, and
+- each time Sublime Text starts in Safe Mode,
+  it deletes any content in the Safe Mode Data directory,
+  so it "doesn't hurt" if a package installed there
+  did something it wasn't supposed to.
+
+::: warning Caution
+**Do not store anything important in the Safe-Mode Data directory!**
+The data will be removed latest on the next Safe Mode start.
+
+**Do not install suspicious packages with Python plugins even in Safe Mode!**
+Python plugins still have access to the full Python library
+and can access your file system
+as if they were running natively on your system.
+:::
+
+After attempting to reproduce the behavior you observed previously in Safe Mode,
+you were either successful or not.
+
+**Reproducible in Safe Mode**
+: If the behavior is still being exhibited,
+  it could be caused by a corrupted shipped Package file,
+  which can be remedied by re-installing Sublime Text,
+  or a bug.
+  You can look for already reported bugs
+  on the [official issue tracker][issue tracker]
+  or report a new one
+  if no existing one matches your situation.
+
+[issue tracker]: https://github.com/sublimehq/sublime_text/issues
+
+**Not Reproducible in Safe Mode**
+: If the behavior disappears,
+  then you know it was caused by something in your Data directory.
+  Follow the section below to narrow down the cause further.
+
+
+### Diagnosing Trouble from the Data Directory
+
+If you have reached the conclusion
+that the trouble you are experiencing has come from the Data directory
+(third-party packages and/or local customization),
+you can discover the source of the problem by following these steps.
+Knowing *when* the problem started is also an asset,
+because the cause will most likely have occurred
+just before the problem started.
+
+1. Close Sublime Text if it is running.
+1. Rename the [Data directory][] to another name
+   to keep it as a backup and reference about
+   what packages you installed and what customizations you made.
+1. Re-start Sublime Text.
+
+When Sublime Text starts, it will create a fresh new Data directory.
+
+::: tip Note
+In subsequent steps,
+it is recommended to keep
+the contents of the renamed problematic Data directory unaltered
+for the sake of preserving the evidence.
+This is so that if your first attempt at isolating the problem isn't successful,
+you can repeat it
+as many times as needed
+using smaller or different steps
+until you have isolated the problem.
+:::
+
+#### Diagnosis by Isolating Packages
+
+Now you can re-install third-party packages you had in place
+(and were working correctly)
+well before the problem started.
+You can install each package individually
+or multiple (related) packages in a group
+to speed up the process.
+
+Verify whether the problem is occurring after each increment.
+
+**The problem is *not* occurring**
+: Continue re-adding more packages
+  until the behavior returns.
+
+**The problem *is* occurring**
+: Now you know the problem is somewhere in that group of packages,
+  and you can take steps to further isolate the source
+  by reverting and repeating this step
+  with only half of the packages in the group.
+  Keep dividing the group until you have isolated the source
+  ideally to a single package.
+
+#### Diagnosis by Isolating Customizations
+
+If you have re-installed all third-party packages
+and the problem has not returned,
+now you can add your own customizations back in,
+one at a time,
+until the problem resurfaces.
+If/When you encounter the problem again,
+you will know where to investigate further to remedy,
+or, as the case may be, what *not* to do.
+
+[Data directory]: ../getting-started/basic-concepts.md#the-data-directory