Seeking feedback for a new package & plugin guidebook

[UltraInstinct05]

Hi everyone

These past few months, I have been devoting a massive amount of efforts into writing a guide book/hand book (whatever term you may want to use ) for plugin & package development (Hence, my suspicious lack for answering any questions ) .

This guide book is going to be designed in a way to provide benefits for both beginners (who haven’t made packages & plugins before) & advanced users (who may find a few tips & tricks) alike. There has been a surprising lack of written resources for this (even though Sublime Text has existed for a long time) and I hope to fill a gap with this new guidebook.

My main goal with this guide book is to actually give back to the community. I consider myself a pretty hard core Sublime Text user at this point but I too remember times (nearly 3 years ago) when I just started out with Sublime Text and wanted to write plugins to customize & suit the editor for my needs. The community helped me a lot back then & this is my small way of saying thanks

I would like to know from the community as to what’s your biggest challenge when it comes to writing plugins and what are the topics you would like to see being covered in the guide book ? That would help me a lot when it comes to preparing material. Right now, the entire guide book is exercise driven, meaning you would first see examples of plugins that demonstrates a particular concept and then a bunch of exercises where you actually take what you have learnt & apply them to create plugins (kind of like a university course/book). I believe the best way to learn is to just keep practicing & problem solving.

Thank you & wishing you all a wonderful 2023

Note: I don’t have an exact ETA for when this guide book will be out (I am already close to 5000 - 7000 words but there’s a lot more to cover). I do plan to get it out sometime in 2023 at least.

[deathaxe]

I’d say one topic to cover is how to write / handle more sophisticated plugins, which consist of various modules depending on each other. Such a topic should cover how to organize all modules in a sub directory and how to export API classes so ST can hook them up. Would need to cover how to handle reloading sub-modules to seemlessly handle plugin updates.

[deathaxe]

Do you want to extend/replace https://docs.sublimetext.io/guide/extensibility/plugins/ ?

[UltraInstinct05]

I’d say one topic to cover is how to write / handle more sophisticated plugins, which consist of various modules depending on each other. Such a topic should cover how to organize all modules in a sub directory and how to export API classes so ST can hook them up.

I guess you are referring to an end to end package example ? I could explain all that in theory, but finding examples to showcase the need (without going overly specific) may be difficult.

Would need to cover how to handle reloading sub-modules to seemlessly handle plugin updates.

Yes, I do plan to cover this (probably in an “Advanced” section) with other topics like threading etc.

[UltraInstinct05]

I don’t plan on making a PR to the community docs. This will be a separate project on it’s own. However, it will be open source, so anyone can contribute, make corrections, update examples & suggest new material.

[frou]

Kudos for embarking on this project. If syntax stuff is in scope, I think something interesting to cover would be how writing a syntax definition for a language is different to writing an actual parser for the language. i.e. how to get into the mindset of writing something that’s more forgiving of input.

[UltraInstinct05]

A guide to writing good syntax definitions (& covering what all ST has to offer in terms of the new syntax engine like inheritance, lazy embeds, sublime.ContextBacktrace API for better debugging) would probably be a whole other project on it’s own

[Lozminda]

I think the tricky part is the ST api, not that it’s difficult per say but there’s a lot of it.

Would that be a good base on which to hang the structure of the document ?

Start with simple uses of the most used parts of the API (what ever they are) and then build complexity from there? (I have no idea what that plugin would be…)

Do you want to extend/replace https://docs.sublimetext.io/guide/extensibility/plugins/ ?

Is a good intro, but it’s the ST API where the meat is (as it were). Obvs folks are gonna need python, you could maybe have a few notes here and there for the less experienced python users ?

I also wonder what is your goal of the book ? It seems from your post that it’s a teaching ‘book’/‘document’ rather than a reference book ? Do folks want to be doing exercises?

particular concept and then a bunch of exercises

For me personally ST is the tool to help me do other stuff and would use your book to solve a specific ST problem (similar to how I use Stack Overflow, eg: how to I write a plugin to change all the 'w’s in this text to links to random websites? and I’d wanna spend the shortest amount of time solving that problem to then get on with work).

Having said all of the above, ST actually it is a good learning instrument in it’s own right. (I learned all about JSON and had my interest in Python increased) I’m not saying you’re wrong for it to be a teaching resource, I’m saying be clear what it’s purpose is, and that’ll help it’s creation, and keep you on track etc. Maybe it can be both…

Perthaps is the folks on this forum could post what plugins they have and that’d give you some examples of what the general user is using…

All my have been written by @OdatNurd and they include
GotoAnyColumn
InstantSnippetCreator
FindandReplace (for macros)

I’d like to write some for C++, but at the mo am writing my first ‘commercial software’ but that’s in Android Studio, but of the top of my head they’d be:

Add to the auto complete list all the words in the project
Perhaps filter those in terms of context and scope
A plugin to refactor code
A plugin that would add automatically member declarations to header files

Good luck with the work, I think it’s good idea (esp with API demystification )

PS I’d be happy to proof read, offer thoughts, don’t have much spare time, but could give you an hour or so here and there…

Pps. Just re-reading you do say it’s a guidebook, but it’s exercise driven, that does make me feel a little weird.

[UltraInstinct05]

Would that be a good base on which to hang the structure of the document ?

Start with simple uses of the most used parts of the API (what ever they are) and then build complexity from there? (I have no idea what that plugin would be…)

Yes, that’s one aspect that would go into the overall structure.

I also wonder what is your goal of the book ? It seems from your post that it’s a teaching ‘book’/‘document’ rather than a reference book ? Do folks want to be doing exercises?

It can be used for both teaching & as a reference. If readers do not want to do exercises, up to them. At the end of the day, you need to practice a topic to understand & one good & proven way of doing that is solving more problems.

For me personally ST is the tool to help me do other stuff and would use your book to solve a specific ST problem (similar to how I use Stack Overflow, eg: how to I write a plugin to change all the 'w’s in this text to links to random websites? and I’d wanna spend the shortest amount of time solving that problem to then get on with work).

Well, I wouldn’t use my guide book as a replacement for the forum or SO. It will give you all the knowledge required for you to solve your issues (hopefully).

Pps. Just re-reading you do say it’s a guidebook, but it’s exercise driven, that does make me feel a little weird.

Not sure what’s weird about that ?

[gnreeke]

I have been looking for a long time for just documentation of whatever API calls there are into the editor, e.g. to move the cursor, search, delete, open a file, all that kind of stuff and I have never been able to find it so I am currently just using the built-in keystrokes. I am looking to write my own plugins to do stuff like (simple example) draw boxes around strings of comments in code I am writing. So provide that documentation, or if it already exists, please just tell me where to find it.
To answer your question, I don’t really like documents organized according to a list of examples–too hard to find a specific function of interest; I would prefer sections on functions one might want to do, then with the examples within that outline.
Thanks, I’d love to see this.
George

[bschaaf]

The full plugin API is documented here: https://www.sublimetext.com/docs/api_reference.html

[gnreeke]

Thanks, that’s just what I needed.
George

[Lozminda]

Pps. Just re-reading you do say it’s a guidebook, but it’s exercise driven, that does make me feel a little weird.

Not sure what’s weird about that ?

The main take-away, from my points (though perhaps expressed badly), was that you should be sure what your end goals are, what is it that your guide/manual/etc is going to achieve/be.

In answer to you’re specific point, so the first thing that came to my mind (and I’m dating myself) pre internet, if you wanted to know what some code did, you went to a manual, I remember the SBAS and INTBAS manuals (one for the kids there). What does print() do, go to index, look up print(), goto page 56, there’s print() (A bit like this). No exercises though.

Or a travel guidebook, there’s maps, info but no exercises. There might be suggestions of places to go, is that an exercise?

Or this might be a U.K. thing, the Haynes Manuals which are books on how to take your car appart. There are detailed schematics, list of tollerances, but no exercises per say. (Walking around is a different kind of exercise )

That’s why I feel a ‘little weird’ because no guidebook I can think about has exercises in it. Exercise books have exercises in

The last coding book i read was Concurrency in Action C++ it has examples, a summary but no exercises.

I’m not saying don’t do it, and maybe this is a semantic argument about what a guidebook is? I’d kinda hoped a few more folks would have had their 10cents worth, because a few people is a very small sample size.

On the flip side (and I wouldn’t count my self as a naysayer, perhaps a cautionary breeze instead) is I find naysayers very useful. All the times folks have said ‘no’ I’ve achieved ‘good’ things, but that’s really just me and my life…

[UltraInstinct05]

That’s why I feel a ‘little weird’ because no guidebook I can think about has exercises in it. Exercise books have exercises in

I use the term “guide” here to refer to the fact that this “book” would guide you to writing plugins & packages.

In that respect, I may also clarify that this isn’t going to be a “book” in the literal sense. Just a website with information & exercises on writing plugins.

[simov]

I just wanted to say that I have bookmarked this thread so hopefully I will get the notifications when this is ready. For me that type of guide with a bit more background information about things will be really helpful. I’m not a Python expert, nor do I have done any Sublime plugins so far. Obviously all of the source code is out there and on a few occasions I had to patch some small plugins myself, but again having a bit more background information besides just the code will be appreciated.

[UltraInstinct05]

but again having a bit more background information besides just the code will be appreciated.

Yup, that’s the plan. Do note however, that I don’t plan on providing any sort of tutorial on Python itself. There’s a great deal of material/videos/books out there so the reader is expected to know the basics and a bit of OOP before diving into the guidebook

[smokinmoe]

A good example for deathaxe’s suggestion, component of your guide would be the setting up of all prereqs to get linting to function. I’m a sublime novice and I’ve had a lot of difficulty getting HTML & CSS linting packages to work. To get linting to work one must install external packages to cover base functionality (java, NodeJS, npm, nvm & stylelint), before the SublimeLinter plugin (No linters included) stands a chance of working. Prereqs and config of plugins specifics are currently above my pay grade and I’d love to see and use your guide.
Being that these things (plugins) are java coded, one should be able to adapt existing plugins to newer/newest versions of ST and/or for their own specific purpose… or am I wrong?

[UltraInstinct05]

A good example for deathaxe’s suggestion, component of your guide would be the setting up of all prereqs to get linting to function. I’m a sublime novice and I’ve had a lot of difficulty getting HTML & CSS linting packages to work. To get linting to work one must install external packages to cover base functionality (java, NodeJS, npm, nvm & stylelint), before the SublimeLinter plugin (No linters included) stands a chance of working.

Linting ? That is a very specific topic not related to plugins.

Prereqs and config of plugins specifics are currently above my pay grade and I’d love to see and use your guide.

Sorry, but I don’t understand what this specifically means either ? Are you referring to configuring packages you have installed ? The best place for that would be the projects README or if it has some sort of website/wiki documentation.

Being that these things (plugins) are java coded, one should be able to adapt existing plugins to newer/newest versions of ST and/or for their own specific purpose… or am I wrong?

Plugins are coded in Python, not Java.

[smokinmoe]

UltaInstinc05:

Plugins are coded in Python, not Java.

I did state that I am a novice😔. Thanks for replying…

I’ll try to explain what I meant and it’s relevancy to your feedback request…

To get plugins to work a user must install & configure the plug-in. The configuration instructions are usually given by the plug-in author and do involve low level pseudo-coding (the ST configuration file is in a java-like syntax if I’m not mistaken?). The installation of a plug-in involves following a set of instructions that most semi computer literate users should be able to follow; the configuration is much the same in that it requires a level of literacy and following a set of instructions and/or rules.
Part of writing/coding a functional plug-in is installing & configuring it. My thought was to use an ST 'linting" plug-in as an example for your guide - ‘walking through’ the necessary steps and rules to follow, post-coding, in order to get the plug-in to work. For instance, as I stated before, the ST ‘Sublimelinter’ plug-in requires a plethora of steps and prerequisites to make it work and I figure this is the sort of thing one might include in a guide such as that which you intend to create.
Perhaps this is out of scope or completely off the mark…? My sincere apologies if either is true.

[simov]

I’ve never used the SublimeLinter plugin myself, but I doubt that’s using Java in case you are referring to linting JavaScript code? To use the linter for JavaScript you need to install Node.js first, because that specific linter is written in JavaScript, meaning Node.js as it does not run in the browser. That seems to be fairly specific to the language of choice that you use. Maybe only the part that is part of the actual sublime plugin can be covered, assuming that it uses the same code base to utilize all of the underlying linters.