docs: fix typo and newly discovered keymap context condition... #125
Conversation
...for key bindings: `is_javadoc`. I found it lurking in the `Default (Windows).sublime-keymap` file with the `enter` key. It returns `true` when the caret(s) is (are) in a comment that starts with `/**`. I tested it in a `.c` and `.css` file and it works in both places.
...also found in `Default (Windows).sublime-keymap`.
...also found in Default (Windows).sublime-keymap (build 4192).
There was a problem hiding this comment.
Thanks for the changes. There are actually several more context keys available according to the official docs, so we are a bit behind here. This is mostly an FYI, but feel free to add those as well
Okay, I shall! By the way, I'm a career programmer (33 yrs so far with a long history of accomplishments) as well as a writer, and I'm looking to connect with someone who: A) knows the history of the documentation (both official and unofficial), and because I have a proposal for team. Reason:I just discovered Sublime Text for the first time just a few days ago (8-May-2025), mostly because I have been exceedingly satisfied with the programmable programmer's editor I have been using up to this point (since 1992!). (And no, it's not EMACS! The observation I would like to address is that, from certain perspectives, the official documentation looks like it has been "abandoned" at version 2 or something, which has a dramatically bad Public Relations impact on Sublime Text as an editor of choice, and I suspect it drives a percentage of programmers away. If we know anything from the history of the software industry, we know that That said, I have a history of writing excellent technical documentation (along with my success as a programmer) and recently applied my talents to the LVGL graphics library (most of its clients are in the firmware field). As of August of last year (2024), LVGL was an excellent project, but it was EXCRUCIATINGLY HARD TO LEARN!!! And I know that drives programmers away in droves, because it was—literally PAINFUL—and it took a "real bulldog" (persistent) to really actually learn how to use it well and correctly, because you had to go into the source code to learn how to use it! (I.e. its documentation was in a shambles.) I convinced the (Hungarian) author to let me rewrite a major portion of the documentation the programmers initially run into while they are trying to learn it. (And it was the perfect time to do so, because I had just gone through that learning curve myself, and so was very fresh on what EXACTLY was wrong with that documentation and what was missing from it.) Fortunately, LVGL's creator was willing to listen carefully to what I had to say, because he appeared to not be aware that there were serious problems with it. By mid-December 2024 I got the bulk of it re-written (though much of its internal [source code] documentation still needs work), so the external documentation is now EASY AND FUN to learn from, and the feedback we have gotten from it so far is that people are very enthusiastic about the documentation now, most expressing things like, "This is the documentation I wish I had when I was learning it!". Since December 2024:
All since December! I don't think it is a coincidence. LVGL's author publicly thanked me for the documentation re-work. These posts since then 1, 2, 3, 4 all mention LVGL's excellent documentation. Look at his Linkedin posts since December. They tell an amazing story of flourishing. In any case, from what I can see, Sublime Text, as the genius product that it is, has the potential to really BOOM its market, if this documentation problem was fixed. And I would like to make a bonafide offer to the core development team to do for Sublime Text what I just did for the LVGL graphics library, in a way that makes it no longer necessary to even HAVE "unofficial documentation" because it is so good. Do you know who I should be talking to? Kind regards, |
Done! A few I had to mostly quote (adjusted to be clearer English) from the web page you referred me to, because I don't understand them yet, but I'm getting there! Note: I also sorted them in alphabetical order so they are easier to find. (This appeared to be the original sort order, which then got things added to the bottom instead of in sorted order.) |
Well, I have been a recognized figure in the community for more than a decade, have seen ST evolve from ST2 into the ST4 version that it is now and have probably written or revised most of what is currently hosted on docs.sublimetext.io, so I can at least speak for the unofficial part. However, as you may have guessed, the unofficial (or "community", as I prefer to call it now) documentation is not directly affiliated with Sublime Hq, the team behind Sublime Text. There is some general communication on the forum and the discord server, which are also the two places I would suggest you to try reaching them. That said, I definitely agree that there is a lot to improve with the official and/or community documentation that I would like to see to make this good product more accessible and easy to use. There has definitely been some progress on this over the past years, official and community, but it's still not in a state I would call satisfactory. For the community documentation, you can see that we have some open issues on this repo already, if you would like to focus on a certain area as a starter. Beyond that, I intended to go through the guide section from start to finish and refine it into a more modern guide that goes into the various aspects of how you can use Sublime Text, explain important and useful concepts as well as accompanying key bindings, and refer to the more detailed reference section for anything that goes beyond this. Some pages already follow this style, some don't, some do it slightly differently, etc. It's just that I haven't gotten to it yet as my unplanned free time is rather sparse these days and I mostly see my focus on other things, such as responding to pull requests on my various other Open Source projects. However, I don't want to go too much into it. If you'd like to do some work in the community documentation, feel free to open PRs, or issues with dedicated questions or talk to me over the discord server, where we have a separate channel for this project. (Note that I cannot compensate you for anything you do for the community documentation, of course, since this is also just a passion project of mine.) |
There was a problem hiding this comment.
Thanks for also adding the other context keys. The table representation on the official docs is probably better, since it also contains information about what operands you would like to use with each of the keys, but that is something for later consideration.
|
Hello, @FichteFoll ! I'm honored to meet you! I know Fichte is a (per my understanding) a German surname. Is Foll your first name, or is it a nick-name like "Vic" is for "Victor"? How would you like to be addressed? (As for me, I generally go by "Vic".) Indeed, Sublime Text seems to be a beautifully architected, genius product that SHOULD be getting a lot more attention that it does. This is the 2nd case in 2 years where a truly excellent product has landed in my lap and had a documentation problem which I discovered by trying to learn it myself, and from what has evolved since December for the LVGL library, I am thinking maybe I was an "angel" that came to LVGL just at the right time. And truly the perfect time to SEE THINGS FROM A BEGINNER'S POINT OF VIEW (and thus know what a beginner GOES THROUGH WHILE LEARNING) is indeed when I am a beginner, and literally myself going through that learning curve! And now Sublime Text.... Same pattern. Meanwhile, I'm glad you liked my change and the alphabetical order adjustment. It seemed like the right thing to do!
I see that you already started with the Guide > Extensibility > Snippets page and clarified that whole mechanism of "passing" arbitrarily-named arguments to a Snippet! Nicely written, and concise too! Part of my replacing my old (beloved) programmable editor is something that involves just that, so I dived into it to see if it was possible to do the extensive dynamic "snippet-like" behavior I built into it as a customization. So thank you for that! That will allow me to both complete that phase of my test, as well as begin believing Sublime Text may just be able to replace my old editor. Interestingly, I found your update because I was going to do the same thing just 20 minutes ago (add a section covering arbitrarily-named arguments for Snippets)—and I saw the PARAM1..PARAMn line was now missing and checked out the changes you made. But you beat me to it! 😄 Also, thank you very much for your thoughtful guidance regarding how to contact the core development team, and the orientation regarding the documentation. I just created a Discord account on the Discord Server as |
Fichte or FF is fine. It is not my real name, but it is what people know me as.
Actually, these changes were contributed by @deathaxe in #127 as a followup to the forum discussion. 😅 As for a more modern guide-like section and as an example for the direction I envision, you can take a look at the most recently added (albeit already a few years ago) section about input handlers: https://docs.sublimetext.io/guide/extensibility/plugins/input_handlers.html |
Oh, sure enough (looking back in the Git history). My oversight. Well, thank you to @deathaxe then. 😄
Very nice work! I will be studying ALL of that in depth here soon.... (Note: Intended to be helpful: I found the evidently-intended page at https://docs.sublimetext.io/guide/extensibility/plugins/input_handlers/index.html . Different topic: I tried building the docs (something I encourage others to do when editing docs on a doc-build system I am currently maintaining using |
I found this weird at the time and wanted to check this out when I had more time. Turns out the behavior is indeed very weird. When going to the "old" |
Cool. 😄 |
...for key bindings:
is_javadoc. I found it lurking in theDefault (Windows).sublime-keymapfile with theenterkey. It returnstruewhen the caret(s) is (are) in a comment that starts with/**. I tested it in a.cand.cssfile and it works in both places. I added in in alphabetical order, which looked like the originally-intended order of the "Context Keys" list.Also added context condition
group_has_multiselect, also found inDefault (Windows).sublime-keymap.Als added
overlay_has_focuskey context condition, .also found in Default (Windows).sublime-keymap (build 4192).