GitLab

Gabriela Bittencourt authored Jul 07, 2021 and Albert Gräf committed Aug 25, 2021

If an object has a "related objects" field in its help patch meta data,
then the list of related objects will be added to the help index and
will be displayed along with its description in the help browser.

Moreover, objects will be listed in the search results if they have the
search term as a related object. For instance, a search for 'pulse' will
also list 'metro' because 'metro' has 'pulse' as a related object.

Note that depending on the actual meta data, relatedness isn't
necessarily symmetric. E.g., 'pulse' doesn't list 'metro' as a related
object in turn and thus a search for 'metro' will *not* show 'pulse' in
the search results, even though 'pulse' is related to 'metro'.

Due to the usage of "keyup" as a trigger for the search, the aucomplete
window disappears before the user can take an action - making it
useless. That's not optimal, but it's a quick fix.

Core documentation (inside pd-l2ork/doc/...) should be ranked before
external libraries. Add a multiplier to increase the score of files
inside that folder.

Chosen priority: title > keywords > description. The chosen weights
(boost parameters) were chosen arbitrarily based on manual iterations
and could be improved.

Word expansion was enabled in title and keywords fields to allow
matching of parts of a word.

This uses findAndReplaceDOMText(), which apparently looks for
case-sensitive matches, but the search text entered by the user is
*always* converted to lowercase. This means that mixed case search terms
just won't be found, which is bad. (E.g., try searching for "GEM" in the
toc to see this bug in action.)

Fixed by just removing the call to toLowerCase() on the search text,
case-sensitive searches now work as expected, problem solved.

This resolves a long-standing bug (the relevant code is 4-5 years old).
While it is just one little missing check in the keyboard event handler,
which is surely just an oversight, this has the dire consequence of
breaking navigation with the Tab key.

- The root cause for this issue is in the document.body event listener
  callback, where we always reset the focus to the search text input if
  there's *any* keyboard input (other than a LF or CR on the file
  browser and bookmark buttons) while the focus is on something
  else (such as an item in the toc or in the search results). The
  intention there surely was to enable the user to just start
  typing *anywhere* in the dialog, which is convenient, but has the
  unwanted side-effect of breaking Tab navigation (as well as the cursor
  keys).

- The fix is simply to *not* reset the focus if the key event is the Tab
  key. Besides Tab, we also treat the modifier and cursor keys in the
  same fashion, so that these will be handled on the spot rather than
  being forwarded to the search text input. By these means, you can
  still start typing your search terms from anywhere in the dialog, but
  navigation with Tab and Shift+Tab and the cursor keys now also work as
  expected.

- Also, why is the div holding the toc items created again and again for
  each item in display_toc()? I moved the corresponding statement,
  div = document.createElement("div"), right before the toc.forEach()
  loop now, which I think is where it really belongs.

Disable the bookmark icon in situations where bookmarking isn't possible (search results, doc directory).

- Use canonical paths just about everywhere in the help browser. We want
  to stick to portable, normalized paths as much as possible, to avoid
  funky Windows path names, especially in bookmark files which should be
  portable across different platforms.

- Fix the generated click_toc() call in display_toc(); we need to
  properly stringify the callback argument there.

- Update the search field after opening a directory via the file
  browser, so that the search text matches the directory display. Is
  there a reason that we're not already doing this? I don't think so,
  because we're doing the same when clicking a link in the toc.

- Prevent the doc directory from being bookmarked. There's nothing
  interesting to see there anyway (just subdirectories, no help
  patches). Also, since the toc lives there (in a virtual sense, i.e.,
  the current browser directory is set to this directory whenever the
  toc is displayed), we also avoid an interesting race condition which
  arises if we try to update the toc while we're displaying it. (This
  doesn't seem to happen on all platforms, but I've seen it on the Mac
  at least.)

- Fix a purely cosmetic issue with the bookmark entries. (Entries with a
  null description were stored as is and then written to the bookmarks
  file. Now the description is just omitted in that case.)

This takes the form of a little bookmark icon to the right of the file
browser icon. Just the plain icon indicates that the current directory
hasn't been bookmarked yet, and that clicking on it will bookmark it.
If you do this, a little red cross appears on the icon, which reminds
you that the directory has been bookmarked, and that clicking on the
icon will remove the bookmark again.

Note that in general a directory may have been bookmarked multiple
times, by using the keyboard shortcut (Ctrl-D). In this case the red
cross will stick until the last instance of the bookmark has been
removed.

The icons come from the Manjaro KDE Breath theme (a variation of the
KDE Breeze theme), and we also replaced the folder icon with a matching
icon from the same theme. Thanks are due to the Manjaro and KDE teams!

While we were at it, we also fixed the vertical alignment of the icons
with respect to the search field, they are properly aligned to the
middle now.

The Ctrl+D keyboard command in the help browser adds a bookmark for the
current browser directory, Shift+Ctrl+D removes it again. Note that the
same directory can be bookmarked multiple times (using Ctrl+D), in which
case the same number of delete commands (Shift+Ctrl+D) are required to
delete all instances of the bookmark again; at any time, the oldest
instance will be removed first.

This also provides a (really simplistic) way to reorder bookmarks, since
you can re-add an existing bookmark and delete its older instance
afterwards, which effectively moves the bookmark to the end of the
bookmarks section. It goes without saying that this becomes rather
laborious if you have to manage a lot of bookmarks, so in that case you
might prefer to just edit the bookmarks file (see below) in your
favorite text editor instead.

Bookmarks are shown in their own "Bookmarks" section at the bottom of
the toc, after the built-in toc sections. The "Bookmarks" section title
will be visible only if there are any bookmarks. As with the built-in
toc items, clicking on the title of a bookmark takes you to the
corresponding directory, which may be in the doc or extra hierarchy, or
anywhere else on your hard disk. If a <dir>-meta.pd file in pddp format
is present in the bookmarked directory, the browser will try to extract
title and description from the NAME and DESCRIPTION tags in that file,
otherwise it simply uses the basename of the directory as title and
leaves the description empty.

The bookmarks are stored permanently on disk as a JSON file in the users
home directory, named .purr-data/bookmarks.json on Linux and the Mac,
and AppData/Roaming/Purr-Data/bookmarks.json on Windows. This file is
read each time the help browser opens, so the bookmarks persist across
program invocations, and you can even edit the file manually and reopen
the help browser to make it pick up your changes while Purr Data keeps
running.

Ivica Bukvic authored Aug 31, 2020 and Albert Gräf committed Sep 06, 2020

* Created new and hopefully improved dialogs that should work on all
  three OSs. These include improved margins, optimal sizes that account
  for OS-specific idiosyncrasies, use of non-native toplevel window
  titlebars that cause bunch of issues (e.g. ability to maximize a
  dialog window since nw.js, at least in the earlier versions, has
  spotty support for disabling those), fixed window sizes with minimal
  scrollbars where appropriate, proper spacing between items, better
  positioning of the checkbox and radio buttons, etc.

* Enabled CTRL+W for the search dialog.

* Improved and consistent find bar appearance on all windows (console,
  patch, search).

* Refined activated box to match different zoom levels and font
  sizes. Small discrepancies still exist when using both custom fonts
  and zoom levels, but these are now no more than pixel off, whereas
  before it was all over the place.

* Made sure that patch windows on all OSs are exactly the same size,
  even w...

This reworks the file button in the help browser so that it opens the file
browser on whatever directory we visited last (as given by the current_dir
variable), or the doc directory by default.

Help browser: Move the index construction into pdgui.js, so that it is only done once during startup.

Help browser: Construct the help index from all of lib/pd-l2ork, to make the keyword search more useful.

Add a check that a toc entry actually exists before adding it. Added DISIS and Gem entries back to the toc.

handle negative coordinates for pd META regex, add doc/* directory search trigger, various refactoring

change id to the document's full path-- this will make it easier to fetch specific documents from the index when displaying directory contents