The Moonspeaker:
Where Some Ideas Are Stranger Than Others...
GEDIT SNIPPETS
Resized screenshot of gedit running under gnu/linux with the side panel plug in enabled. Image courtesy of GNOME. The fullsize original may be viewed at the a tour of gedit page.
Among the many subjects upon which people who do any sort of coding or scripting on computers may have extended, fruitless arguments over is the question of text editors. Everyone has their favourite, and over time a set of features has come together representing a status of, "if the editor doesn't have this, it just isn't serious for day to day work," even though originally we all did without. Among the most familiar are: line numbers, code colouring, document statistics, spell checking, and a file browser. That's quite a lot already, and many editors include means to auto-insert dates, highlight selected text, straighten educated quotes, and balance delimiters. But the specific feature personally I cannot do without is the ability to define and use auto-inserted code snippets. A combination of templates and pre-define code snippets can vastly reduce development and production time. So when I first began more seriously running gnu/linux, text editors were inevitably a serious factor. Comparatively barebones editors like nano are great for certain types of work, and the major IDEs are impressive. However, my coding work tends to involve a medium-sized sort of load, understandably too much to expect nano to handle, but a gnat compared to a sledgehammer for some of the most familiar IDEs. On top of that, my main gnu/linux machine runs a conservative debian-based distribution, which perforce is running an older version of gedit. For those not so fond of GNOME these days, MATE's pluma is very similar and has some additional features now that gedit does not. Still, I worked out how to set up the collection of snippets I needed in gedit after frankly, far too much time smacking my head against the documentation, which is not quite so forthcoming as might be hoped, as is difficult to avoid since so much free/libre software documentation is put together by developers in lieu of doing without.
In the end I managed to put together my notes on the not so obvious gotchas that can catch out the newcomer to gedit snippets, and set aside my puzzlement on why it was so difficult to find the information that was written up already for another day. I did add an item to my lengthy to-do list to actually tidy up these notes and post them at least on my website to make them findable for others. As I understand it, gedit came together to begin with as an IDE for development in python, and accordingly this was the language of most plug ins. There was originally a fair number of third-party plug ins as well as the default set to keep everyone busy, though only so many. I sought mightily for a symbol navigation plug in with not much luck, and did not have enough time to try turning my hand to coding one up myself. The search process made it obvious that external plug in development was at least for the time being, moribund. Worse yet, the GNOME application documentation was undergoing a slow migration to a new template and hosting, making it all the more difficult to figure out what was happening. On further research and relocating the blog reporting on gedit development, I have learned that gedit has dropped python support for third party plug ins and several plug ins were removed in version 48 as of november 2024, including none other than snippets. According to the blog posts, this was in order to reduce the amount of code to be maintained and the number of languages supported. Gedit has also has a reduced developer group now, which bodes ill for its future as a medium-sized IDE. It may be that poor gedit will become the gnu/linux equivalent of notepad on windows or textedit (formerly simpletext way back in the day) in macOS. Perhaps that's inevitable, but it is still rather sad. Sad or no, that is the direction GNOME is taking, including renaming gedit, now better known simply as Text Editor.
Therefore, the information and links collated below about using the third party snippet plug in are only good up to gedit 47, or for pluma in the MATE desktop. Based on the most recent commits in the log at MATE's github site, they have opted to maintain support for external plug ins written in python, and its current release is the 1.26.x branch. Pluma's documentation links tend to redirect to gedit's equivalent pages, but I suspect this won't last for much longer as the two editors will be on more divergent rather than parallel paths. Now, in terms of links, there are two main ones, for as long as they last online.
Now, with all that covered, here is the overview I put together to help make sense of how to write and adjust recipes in the snippets plug in.
First things first, unlike many other text editors, in gedit the autocomplete key is "tab" and so far I have not found a way to reassign it. There is a "Manage Snippet..." item under the hamburger menu, which pops up a mini-editor with three parts. There is a list of snippets on the left hand side, the editor on the right, and across the bottom a section labelled "Activation" where a person can set the tab trigger, short cut key, and drop target. The "tab key" is just a few select letters to be typed before hitting tab, which will then insert the snippet. Short cut keys are a bit fiddly to assign because some combinations simply don't work for unclear reasons, and others must be reassigned if already in use or part of the system short cut suite. Full disclosure, I never figured out the "drop target" option. In my experience, it was necessary to at least click on the snippet list and away from the snippet I was editing to make sure all the changes had saved before testing it out. This is a bit awkward, but there does not seem to be an explicit save UI button or key for the snippet editor.
After this point, it is easy to get very confused, because snippets can do some very clever things using variables and the gedit placeholder system. Gedit placeholders begin with a "$" and except for two cases are all in upper case with words separated by underscores. When learning a snippet and placeholder system, there are five items I look up and learn first:
- The placeholder for where the insertion point goes: $1
- The placeholder for the end of a snippet: $0
- How to preserve selected text on snippet insertion: place $GEDIT_SELECTED_TEXT either right before or right after $1
- How to auto-insert the name of the document: $GEDIT_CURRENT_DOCUMENT_NAME
- Insert the date using the default format in the text editor: $(1:date +%F | head -n 2)
Items 2 and 3 are especially important. Without them, it is possible to end up with such horrors as having a snippet still selected such that it is easily deleted by accident on hitting the next key, or needing to go and select text to be replaced by hand within the inserted snippet. In my experience item 5 is a good case study for learning the next level of detail, which is python placeholders, bits of python code processed at insertion time. Despite my lack of enthusiasm for python as such, this is a useful feature that probably also caused a lot of headaches for the developers because of the need to keep a sharp eye on its security behaviour. Finally, here are a few simple examples from my repertoire of snippets with brief descriptions. The format of each item is:
(tab key, short cut key) snippet string
Description
- (anchor, Ctrl+Alt+A) <a href="$1">$GEDIT_SELECTED_TEXT</a>$0
Surround the selected text with anchor tags and set the cursor ready to paste the link.
- (bold, Ctrl+B) <span style="font-weight:bold;">$GEDIT_SELECTED_TEXT</span>$1$0
Make the selected text bold, deselect it, and move the cursor to the end of the text.
- (dpara, Shift+Ctrl+P) <p class="TextParagraphIndented">$GEDIT_SELECTED_TEXT$1</p>$0
Insert a default paragraph tag; if no text is selected, place the cursor between the paragraph tags; if text is selected, surround it with the default paragraph tags, deselect the text, and place the cursor at the end of the former selection.
- (rssd, Shift+Ctrl+R) $(1:date "+%a, %b%e %H:%M:%S %Y %Z" | head -n 2)
Insert the date formated according to rss 2.0.
As I hope these examples show, it is possible to a lot without doing much more than scratching the surface of what this plug in can do. To date I have not bumped into a character limit, with the maximum number of characters so far being 380. A reasonable approach is to consider 512 characters the practical maximum. Based on my general coding experience and the range of tasks called for, I did not need to use a full on python reference, the old GNOME wiki page was enough. Well, except for date string formats of course, but those generally follow the ICU Documentation on formatting dates and times.
- I have written two brief pieces about the challenges involved in writing documentation, Documentation Woes and More On Documentation. It's a tough and frustrating job even for those who are best placed to write it, which is not the developers of the software but the people who use it and have not developed it.
|
