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.
| to support common programming languages out of the box. | ||
|
|
||
| Examples: Default, Python, Java, C++, Markdown. | ||
| Examples: Default, Python, Java, C++, Markdown, reStructuredText. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
... and I too am working on a growing list of ST utils for reST ...
If you have anything to share, now would be a good time at sublimehq/Packages#4212
There was a problem hiding this comment.
If you have anything to share, now would be a good time at sublimehq/Packages#4212
@jrappen I'm honored! See you there.
docs/guide/extensibility/packages.md
Outdated
| - 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.
| Any file you create in this package directory | ||
| will literally replace any identically named | ||
| (and identically path-ed) file | ||
| in the original package. Sublime Text literally |
There was a problem hiding this comment.
literally identically identically literally ... maybe you could rephrase this
There was a problem hiding this comment.
literally identically identically literally ... maybe you could rephrase this
Good catch! I think you will like how I re-worded it to be more graceful and intuitive.
However, one of the CI checks is failing on (I think) a build-tool version? I'm not sure if it is within my power to resolves. Can you have a look?
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.