Sublime Forum

Is there no official command list with documentation of parameters?

#1

The unofficial list seems to just be a summary of the menu commands that are setup but surely there must be more and with more info. The documentation for permute lines just says “??”

With software so heavily designed around a command system there has to be better documentation on all the commands. No?

2 Likes

#2

This is where Sublime Text really has a problem: the documentation. Fortunately, there’s an unofficial one, which lists some of them (but not all of them). But have a look throught it, there’s so much awesome stuff to learn!

:+1:

0 Likes

#3

Yeah I was looking through the unofficial docs and was disappointed with the lack of detail and with the fact that it seems to only document the commands that happen to be mapped to the menus by default. There are no other commands that don’t come mapped to menus by default? Then I have to say I am bit shocked at the limited command set.

0 Likes

#4

Commands are just python plugins and you can add them by installing packages. So the relatively small default command set is not problematic and the possible commands are not limited.

Just in case you don’t know: https://packagecontrol.io/

PS. The sort_lines command has the arguments "case_sensitive": false, "reverse": false, and "remove_duplicates": false (not all are documented in the unofficial doc)

0 Likes

#5

OK thanks. I had messed with the packagecontrol.io site before but was always confused on how to actually install one of the packages. Just figured out how to use Ctrl-Shift-P and run packages install. Cool.

But yeah I am really surprised that the vanilla out of the box commands do not have better documentation. The unofficial docs for Permute lines is “XXX” for example as I said. Anyway. i will have fun playing around with the packages in packagecontrol and experimenting with all this. So far I am finding Sublime to be an enjoyable and fresh experience with computer software. Its… ahem… sublime. :wink:

0 Likes

#6

@wbond Has been adding a lot of info to the official ST3 docs. Here’s hoping, there’s some time for this.

0 Likes

#7

Yeah this has caught me as well. I was looking for a way to create a key binding to a command that has no key binding by default, thus the command could not be found in the default keymap-file. In such a situation it would be very welcome to have a reference list of commands that can actually be used when customizing the editor.

0 Likes

#8

you tried looking in the sublime-menu and sublime-commands files? its rare that a built in command isn’t referenced from somewhere. That said, the PackageDev package offers some hints for commands and args in keybindings etc

1 Like

#9

@kingkeith I only change my settings from the configuration files available from the menus, like “Preferences -> Key Bindings”. That might be why I havn’t seen the sublime-menu and sublime-commands files.

The command in question was “Save All” which I wanted a shortcut/key binding for but could not find. I can’t remember how I found out but this can be achieved with
{ "keys": ["ctrl+shift+s"], "command": "save_all" }

0 Likes

#10

You can enter sublime.log_commands(True) in Sublime’s console, then the textual name of each command will be logged as it is run (e.g. when selecting File > Save All using the mouse).

0 Likes

#11

From experience, the best advice I can give you to understand how any part of SublimeText (be it commands or specific api functions) works is:

  1. Install EditPreferences and use the List plugin commands in the command palette, this plugin is quite nice and you’ll be able to figure out where many commands live… unless the command is a ST builtin one
  2. If you’ve been lucky enough to figure out the file where the command you’re interested with lives then it’s just a matter to understand what the code does, in order to do that you can use the existing docs, be it https://www.sublimetext.com/docs/3/api_reference.html or http://www.sublimetext.com/docs/3/. Also, I’d suggest you install PackageResourceViewer to navigate through code much more easily
  3. If the command/function you need to understand is not available as python code you’ve run out of luck here as you’ll need to use your imagination and make extensive testing in order to truly understand how that undocummented piece of code works.
  4. If you’re not willing to spend your time trying to figure out how that specific non-documented close-source part works the other advice I can give you is just posting your question on the forums or open a ticket on https://github.com/SublimeTextIssues/Core claiming there is lack of documentation or clarity on certain parts you need and then just hoping somebody will take these tickets, which is highly unlikely though as they’ll be considered low-prio tickets

That said, if none of the previous points have helped you to understand how some specific command/functionality in Sublime works… well, you could always try to reverse engineer ST using debuggers or disassemblers but unless you know what you’re doing here I’d discourage going this route as you’ll end up wasting a lot of time to recover extremely trivial pieces of functionality, so it’s generally not worth the time investment.

So yeah, many times telling how something works in Sublime will be extremely easy but in other cases you’ll hit a wall… why? Well, that’s the thing when dealing with propietary closed-source software… they need to invest a lot of resources “duplicating information” in form of documentation cos they’ve decided protecting the information by obfuscation (compilation) was worth for the business :wink:

0 Likes

#12

That’s funny/tragic. On the frontpage of https://www.sublimetext.com/ they have a bullet that says CUSTOMIZE ANYTHING which is only half true if the needed information/documentation to do so is not available to the end users who bought their software!

For my part at least, the customization part was the main selling point of this editor, but I think I will have to look elsewhere after all. If customization is a selling point, you shouldn’t be needing to go through the steps outlined by BPL to figure out how to change stuff.

Most of the software I write could qualify under CUSTOMIZE ANYTHING. I mean I can customize my software any way I wanted it. I just have to re-write the code and recompile… I mean at some point Sublime Text is only customizable for the devs who wrote it because of lacking documentation.

2 Likes

#13

I agree, that bullet point on the landing page will hold depending which type of user you are. If you are a [hardcore] plugin developer you’ll consider that bulletpoint strictly false (pure marketing as saying “Customize almost everything” wouldn’t sell that well). On the other hand if you’re a casual user… I guess the largest SublimeText userbase are casual users that claim may hold… somehow :stuck_out_tongue:

At the end of the day SublimeText gives certain extension points so users will be able to add value to the software through packages, basically plugin devs are giving away their work to the community+SublimeHQ for free

I mean at some point Sublime Text is only customizable for the devs who wrote it because of lacking documentation.

Yeah, that’s correct. They’re the main winners of the whole thing, money+free plugin devs+free bug reporting… Aren’t closed source plugin architectures a great thing to have? :slight_smile:

Also… just to clarify a bit more about the CUSTOMIZE ANYTHING claim, you can read more about the policy https://forum.sublimetext.com/t/is-view-classify-buggy/43090/8?u=bpl

Summing up, you shouldn’t have any false expectations like SublimeText will be a 100% customizable editor cos is not :slight_smile:

0 Likes

#14

Just to clearify… I am not a plugin developer, of any core-ness, at all. I just want to know how to create my own keyboard shortcuts. I don’t think that is too much documentation to ask for.

0 Likes

#15

I see :slight_smile: … well, if that’s the case and self-referencing what I said in my previous comment… you’ll find SublimeText to be 99% customizable. For your particular case, please check the docs at https://www.sublimetext.com/docs/3/, specially the section which talks about https://www.sublimetext.com/docs/3/key_bindings.html, hope that helps.

0 Likes

#16

The documentation is there, perhaps just not in the format you are expecting. :slightly_smiling_face:. Looking at the Default key bindings file and the Main.sublime-menu tends to cover most of the commands.

But seriously, I have started work on an official list of commands and args, but it is rather a time consuming thing, since as soon as you list the commands and the args, then it is reasonable to expect a description of what each arg does, how various args interact, and then time is spent thinking about how to organize and present all of the command information.

4 Likes

#17

This is awesome news indeed!

Btw, talking about how to present docs… I think I’ve said it few times in the past but IMHO the way you guys created the API docs at https://www.sublimetext.com/docs/3/api_reference.html is simply perfect! A really nice clean cozy flat single page with minimal clear descriptions.

Personally I find autogenerated docs using tools like doxygen, javadoc, sphinx, … are not fast&good enough (mostly of the time).

I think that API reference flat page simplifies pretty well the whole public API… and yeah, sometimes the level of descriptions of some functions isn’t good enough to understand what they’re doing but I think that’s a very little subset of functions and overall I love that page :slight_smile:

Simplicity ftw!

Ps. Later on maybe I’ll allocate some time to loop through the whole page and select which descriptions are not clear enough :slight_smile:

0 Likes

#18

Really good news indeed :slight_smile:
For me, getting the list of commands and args out there is better than nothing. And I would rather have a list of commands and args now than wait for a list with complete correct descriptions for another year (or however long it might take).

My problem with the documentation have always been the lack of commands and args. I know I kan see the list of existing uses of a particular command in the keybindings preferences file, but as an example I have no idea how many ways I can control the “move” command with which args.

Yes, simplicity is nice. A simple list of valid values would do wonders for a start.

0 Likes

#19

Is there a chance to take a look at the API, there are a lot of undocumented functions, e.g:
meta_info(), extract_tokens_with_scopes(), is_in_edit(), indented_region(), has_non_empty_selection_region(), find_all_results_with_text()
and lots of other, many can be interpreted and usually correctly but others may not.

0 Likes

#20

I’ve review the whole API documentation and almost all functions are well explained, I’ve noticed few places where you should improve the docs:

Differences between window/layout/viewport are not explained anywhere

find_resources(pattern) - `pattern` example would make it more clear
classify - Undocummented flags
find_by_class - Undocummented flags
expand_by_class - Undocummented flags
extract_scope - Totally unclear what this functions does

The rest of functions are quite clear to me in terms of:

a) proper naming
b) good description/example
c) inputs/outputs

0 Likes