feat: enhance packages.md#131
Conversation
- .sublime-commands after menus and before `metadata` since commands seem relatively common in Packages. - .sublime-completions before `snippets` since, according to the official documentation, a Snippet is just a Completion with more flexible (and more readable) content formatting.
...to a freshly-installed state. This method keeps the old Data directory as a backup so that the step to do this is not considered quite as "extreme" as requiring a backup to recover lost customizations.
| - 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.
| as if they were part of it. | ||
|
|
||
| ::: warning | ||
| Files in override packages override entire files. |
There was a problem hiding this comment.
This sentence is not inaccurate but it may be misleading in isolation. Files in override packages do entirely replace the respective file in the Installed Packages (oder in the shipped packages) folder they are overriding. This happens before resource file merging for JSON ressources like menu and keymap files is considered. Please drop the commit.
There was a problem hiding this comment.
Hmmmm.... That clarification takes care of PART of the problem I was seeing. However, I tested it with one of the JSON file types (a menu) and found that if I merely COPIED the file, that Sublime Text used BOTH files from the original Package PLUS the identically-named file in my override Package (Packages/<pkg_name>). I tested it with the OverrideAudit Package's Main.sublime-menu.
I am concerned that some (like I initially did) could read that and think that the effect is as if the original Package file "goes away" and the override version of it takes over all its functions, which appears not to be true for the JSON types.
Thoughts?
There was a problem hiding this comment.
It's also possible that I put it in my User Package, so I may need to re-do my test to confirm what I am thinking....
There was a problem hiding this comment.
My apologies! Additional testing shows that Context Menus, and even the Main Menu items (from Main.sublime-menu) are indeed fully replaced.... I know what happened is that in my test I must have put the "override" files in my User Package, which clearly causes different behavior. Commit dropped! Good catch, sir!
I will additionally submit another commit to add content about Safe Mode mentioned above, so don't merge yet. :-)
There was a problem hiding this comment.
Voilà!
- I combined use of Safe Mode and the prior diagnostic steps into a coherent whole in a "Troubleshooting" section. I hope you like it.
- I added some clarification about override-file behavior that makes it more difficult to misunderstand.
Looking forward to your reply,
Vic
There was a problem hiding this comment.
@FichteFoll Hi! No doubt you've been busy.... I just wanted to check if this meets with your approval, or if I need to change something?
Kind regards,
Vic
vwheeler63
force-pushed
the
feature/enhance_packages_doc
branch
from
7aefe15 to
4dd5106
Compare
...a full troubleshooting section that includes using the new Safe Mode (since Sublime Text 4) and then continuing with the Data Directory "surgery" if the problem was not isolated/resolved up to that point.
- additional clarifications added; - image added showing the "Safe Mode" announcement dialog box, which as important official information in it; - added additional information about using Safe Mode; and - refined troubleshooting information.
|
Thank you for the changes and iterating over them again. I have checked them out locally, did a few changes, applied semantic line feeds, and moved the troubleshooting section to a new page because I believe it to be too generic to be hidden inside the "Packages" folder and it deserves its own page. See 28ca990 for the full changeset. |
Sweet! 😄 |
3 participants
Supplement list of typical Package contents:
.sublime-commandsaftermenusand beforemetadatasince commands seem relatively common in Packages;.sublime-completionsbeforesnippetssince, according to the official documentation, a Snippet is just a Completion with more flexible (and more readable) content formatting.Combined the previous "reset-Sublime-Text-to-a-freshly-installed-state" section into a Troubleshooting section that also includes use of the new Safe Mode (since Sublime Text 4). This method keeps the old Data Directory as a backup so that the previous customizations are not "lost forever", but are kept as evidence, and possibly copying back for customizations that were well behaved.
The override-file behavior was less clear than it might have been for someone (like myself) who has seen and used the "merge" override behavior of JSON resources in the
Userpackage. So I added some clarification so the reader can clearly see the different behavior between the two types of overriding.