feat: enhance packages.md #131
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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, reStructuredText. | ||
|
|
||
| Located in `Shipped Packages`. | ||
|
|
||
|
|
@@ -310,11 +312,24 @@ packages and plugins. | |
| <!-- TODO --safe-mode --> | ||
| To revert Sublime Text to its default configuration | ||
| and remove all your settings and configurations, | ||
|
|
||
| - Close Sublime Text if it is running. | ||
| - Rename the [Data directory](../getting-started/basic-concepts.md#the-data-directory) | ||
| to another name to keep it as a backup and reference about what | ||
| Packages you installed and what customizations you made. | ||
| - Re-start Sublime Text. | ||
|
|
||
| This starts Sublime Text with a fresh new Data directory and | ||
| you will find that the "apparent bug" disappears. | ||
|
There was a problem hiding this comment. These are good changes, as the previous method was definitely too easy to misunderstand. However, I would much rather recommend Safe Mode for quickly checking whether something is indeed broken in a vanilla installation or only due to a third-party package. The modified instructions are still useful for when Safe Mode does not help (e.g. you need several packages to reproduce a bug with a couple ST restarts in-between). There was a problem hiding this comment. This is an excellent point! I haven't studied Safe Mode yet, so please give me a few days to study it and I will submit another commit to include it. |
||
|
|
||
| Keep in mind this also effectively de-installs every Package in | ||
| your `Installed Packages` folder, so you will probably want to | ||
| re-install the ones that are well-behaved. This sequence can also | ||
| allow you to detect which Package was misbehaving. | ||
|
|
||
| If it was not a misbehaving Installed Package that | ||
| was causing the problem, then adding your own | ||
| customizations back in, one at a time can also help | ||
| isolate what was causing it. Use the renamed (now-backup-copy) | ||
| [Data directory](../getting-started/basic-concepts.md#the-data-directory) | ||
| as a reference. | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Why add
reStructuredText, one of the worst syntax definition that ST currently ships with (though improvements are underway via sublimehq/Packages#4212)? Most people will not know what it is anyway.If you want something different, I would add a serialization format for structured data types such as JSON, YAML or TOML there.
Uh oh!
There was an error while loading. Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Good question!
Actually, since the arrival of version 7 and 8 of the Sphinx documentation generator, I find that reStructuredText's popularity is growing very quickly. Here is a list of projects that are using it, and I THINK these are only the ones that the Sphinx project got permission to publish.
https://www.sphinx-doc.org/en/master/examples.html
I'm working on a MAJOR one for the LVGL graphics library.
And I too am working on a growing list of some Sublime Text utilities for reStructuredText.
The reason I included it was that "Markdown" was sitting there all alone, and, in my opinion, reStructuredText does a few things better than Markdown—especially with Sphinx. I don't know if you were aware, but the Linux project switched over to using Sphinx for its documentation a few years ago. This fact is what made me take a serious look at Sphinx and reStructuredText, and I have been a very happy user of it ever since. All of my documentation, book, and booklet projects now use it (about a dozen of them).
So my feeling is that it is quite appropriate to be there as an example.
If you have strong feelings about it, I can remove it, but after working in reStructuredText SOLID for the last 10 months, I'm convinced it's a winner! 😄
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If you have anything to share, now would be a good time at sublimehq/Packages#4212
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@jrappen I'm honored! See you there.