Skip to content

A simple bookmark feature for the help browser

Albert Gräf requested to merge aggraef/purr-data:help-browser-bookmarks into master

Here is a last one for 2.14.1, then I'll be a happy camper and go away, so that you can prepare the release without further distractions from me. ;-)

With the loading times finally fixed in !548 (merged), I have one last gripe with the help browser, and that is the lack of customizability of the toc. I really want to be able to put my own favorite directories with help patches there. Whether it's a library that I use a lot, like mrpeach in the extra hierarchy, some examples I prepared for the students, or just stuff that I'm currently working on, I need to be able to bookmark these, and have the bookmarks stick around when I exit Purr and launch it again.

This MR implements just that, in the simplest and least intrusive way I can think of. I really want the help browser to stay as simple and accessible as it is, so the new bookmark feature stays out of the way if you don't want it, but is readily available with a keystroke or a mouse click if needed. So OOTB it mostly still looks as before:

image

Well, there's a new "favorite" icon there, and I also replaced the folder icon with something that matches up (I pilfered these from the KDE/Plasma Breeze theme, so they ought to be open-source). Moreover, I fixed the positioning of these so that they are nicely lined up with the search input now.

To add a bookmark, you go to the directory that you want to bookmark by any possible means (file browser, typing something like extra/mrpeach in the search box, etc.), and click on the favorite icon, or use the Ctrl+D keyboard shortcut. E.g., here I've selected and bookmarked extra/iemguts (note how the favorite icon lights up when a bookmark is set):

image

Of course, bookmarks can also be deleted again, either by clicking the favorite icon of a bookmarked directory, or by using the Shift+Ctrl+D keyboard command.

Bookmarks are shown in their own section at the bottom of the toc, after all the built-in sections. (The "Bookmarks" section title only appears if there are any bookmarks to show.) Here's my personal "Bookmarks" section, which I already populated with some bookmarks for illustration purposes:

image

As you can see, the browser also tries to pick up descriptions for the bookmarks if a corresponding dirname-meta.pd file is available in the bookmarked directory. Also, note that the lua-examples link there actually links to a folder in my Documents directory, so the links can point to any location that you can read, not just Purr's doc and extra folders. (I had to rework the main entry point to the search engine a bit to make that work; in particular, it does a proper check for directories typed into the search input now.)

Bookmarks are stored in ~/.purr-data (Linux, Mac) or ~/AppData/Roaming/Purr-Data (Windows) as a (nicely formatted) JSON file named bookmarks.json. That file is read whenever the help browser is opened, so bookmarks are persistent and can also be edited in a text editor when needed.

That's about it (read more about all the gory details in the commit messages). This is a really simple, but very useful facility (for me at least), and thus IMHO follows the spirit of how the help browser has always been working: simple, but powerful.

Tested only on Linux so far (hence WIP for now), but I think that I can complete testing on Mac and Windows today.

Edited by Albert Gräf

Merge request reports