Docset Groups/Docset specific searches

[mazen-mardini]

Hello,

Could you make it possible to execute docset specific search queries. Currently, if you search for a keyword, it'll search for it in all docsets whether it's in Drupal, C++, or jQuery.

This problem can be solved in at least two ways:

Search Tags:
You could ether write the docset name in the beginning of the query, like this:
"c++ std::shared_ptr"
EDIT: Already implemented. Usage: "c++: std". "c++: std::shared_ptr" is not possible because of ambiguity in the syntax, there are several colons.

Or, even safer:
Drag docset to the search field to add the tags. (In this case tags are not part of the text.)

Docset Groups:
You could also make it possible for people to create groups of docsets depending on ones current preferences. For instance:

"Web Development" - PHP, jQuery, Drupal
"Application Development" - C++, Qt5, Boost
"Mobile Development" - Android

And of course the ability to easily switch between these groups from a select-list (there is a lot of space in the top-right corner btw) or from the menu bar.

Those are just my ideas, that are mostly stolen from Dash. :)

[jkozera]

As per http://zealdocs.org/usage.html, you can use "docsetname:query" to filter search by docsetname.

I agree docset groups could be also useful though.

[mazen-mardini]

I was assuming that feature didn't exist at all. Sorry for that one. :D

Docset groups would be very helpful. and much easier to deal with than text based tags.

EDIT: The syntax "[docset]:[keyword]" is ambiguous. Because the keyword can include colons. For example: "c++: std::unique_ptr"

This will make zeal ignore "unique_ptr" and only search for "std" in the c++ docset.
A possible solution is to make zeal ignore all colons except the first one.

EDIT 2: "C++: std::unique_ptr" is not the same as "c++: std::unique_ptr". The docset name should be case-insensitive.

[mazen-mardini]

This will work now:
"c++:std::sort"

However, these two will still not work:
"c++: std::sort" - Will only search for std.
"std::sort" - Will return nothing.
"C++:std::sort" - Docset-tags are still case-sensitive.

How to fix ambiguities with colons:

• Ignore all colons except for the first one.
• If the docset doesn't exist then let the first colon be ignored too (make everything like normal text).

[roman-kashitsyn]

I've tested both "c++: std::sort" and "std::sort" and it worked for me. Have you compiled the latest version?

Case-insensitive search is a good idea and is trivial to implement. Actually, as I can see from the source, the original intention was to use case-insensitive matching. I think I'll submit a patch for this problem today.

The idea with docset existence check seems good but I don't like it:

• Query parser result becomes dependent on the global state of the system which is not good (much harder to test and predict).
• Results could be not as expected when searching inside the bindings. I will not be able to search inside the boost::python using python::class_ query (it doesn't work now either way but because of low boost docset quality).
  So, I'll stick to my current hack: don't use double semicolon as a docset filter separator. Probably, we should ask @jkozera about this, since I'm just an interested contributor, not a project owner.

Docset Groups is a good thing. As I can see from demo, Dash provides automatic profile switching based on your current activity (opened applications, etc.). It's amazing stuff and it's hard to reproduce it in a portable way (from my point of view).
It's much easier to implement "virtual" docsets working as a logical grouping of other docsets and allow user to create and edit them. Such a feature requires major code refactoring and I'm actually working on it now :)

[jkozera]

I can confirm "c++: std::sort", "std::sort", and "C++: std::sort" return correct results now in zeal-20140120. I like the current solution which just ignores double colons. It's simple now, and ignoring all colons except the first one wouldn't fix the plain "std::sort" case.

Ignoring double colons though may not work well with jQuery docset for example, where you have items starting with ":", so "jquery::button" doesn't return anything, but I reckon we can't always guess what the user is looking for.

[mazen-mardini]

@jkozera, "c++: std::sort", "std::sort", and "C++: std::sort" are working fine with me too on the 20140122 release, for some reason it didn't work before. Anyhow, regarding the potential ambiguities that can occur with different docsets, it is a good reason to implement tags that don't interfere with the search field. Such as the ones you'd find in Dash.

@roman-kashitsyn, I agree with the first point you've made. We don't need classes to function differently based on global variables, that's just unprofessional and such programming practice will surely create more problems in the future. But passing a second argument to the constructor is also not nice, so I guess that is not a proper solution after all. And I wont argue with you on your second point, ignoring double-colons will work the same way anyway.

Thanks for all the help!

[Kapeli]

For what it's worth, this is how Dash handles keywords:

1. Assume all colons are to be searched
2. Before the actual search, check out the query and compare it to the keywords of the installed docsets. If the query starts with a keyword (including the ending colon), remove that part from the query, activate the docset with that keyword and search
3. If nothing matches, just search with the colon included.

[archshift]

How this work if the docset has a space in its name? Searching "NET Framework: print", or "OpenGL 4: GL_" (for example) yields nothing, yet searching "Java SE8: print" yields many results.

[aoloe]

i like the proposition of a set of docsets (even if i would already be happy with simple checkboxes.
the current "c++:" filters are a bit hard to discover and they are not really practical to type (personally i would love to avoid it, if i could)

here is a proposal:

• by default all docsets are activated.
• shift click on a check box cycles between selecting only that checkbox and all checkbox but the one clicked (a standard in many programs...)
• clicking on a checkbox makes the dropdown change to "Custom set"
• if it's a custom set, the first entry in the dropdown is "Create new set" (based on the current selection); the last set that was selected is cached and the second entry is "Update nameOfSet set".
• if a set is active, the first entry in the dropdown is "Disable current set" (removes the set from the list; i'd prefer not to use the term delete: the user could fear that the docsets gets deleted from her computer)

i'm not sure that the current filter (c++:...) should be kept or if having checkboxes would make it unpractical.

i'm not yet 100% sure about how much time i will have in the next future, but if you like my proposal, i might try to implement it...

[Yanpas]

+1

[clfsoft]

+1

[jotaf98]

As you install more docsets this becomes a usability issue. I had to deal with cluttered search results until I decided to search for this issue and came across this. I understand the hack with text filters but having to type it every time undoes some of the productivity that you get from fast searches.

@aoloe have you had any luck realizing the mock-up you showed earlier?

[aoloe]

hi @jotaf98 no, as i wrote in my reply i would only try to do it if there is a consensus (if possible an ok from the maintainers) on the proposal being a good solution.

i'm currently rather busy with other projects, and getting started on a new code base would be a bigger step for me...

[jotaf98]

@aoloe Yes I understand, it's a lot of work to dig in an unknown codebase. Just wanted to ask, thanks!

[vinipsmaker]

I have to check differences for 3 lua versions (lua 5.1, lua 5.2 and lua 5.3) for what I'm developing right now and the lua: tag will include search results from all 3 versions. The group idea would also help me a lot. The idea is not far-out and already have been implemented in projects such as Qt's official documentation browser — Qt Assistant — for a long time: https://doc.qt.io/qt-5/assistant-details.html#filtering-help-contents

[bobbles911]

+1 this is an amazing tool, but I find having to type a label each time frustrating. Personally I'd like if the search would only ever search the currently selected docset, and that global searches never ocurred.

Perhaps this could be an option in the preferences which would avoid needing much changes to the UI otherwise?

[FalcoGer]

I suggest a drop down list next to the search text field where you select the docset you want to search in. much more usable than typing docsetname: searchtext.
Implement groups by creating new elements for this drop down list as composites of existing docssets. This should be an edge case anyway.
To keep current feature of searching all docsets, there should be an "all" option in the drop down list.

[ssokolow]

That depends on your definition of "usable". It's much more discoverable, but much less time-efficient for a skilled user... similar to the trade-off between a CLI and a GUI.

Instead, I'd propose a button next to the field which pops up a window similar to a browser's search keyword editor. That could do double duty as a reference for defined keywords so users don't have to trial-and-error their way to figuring out what the keyword is for something, and an editor for new ones. (Ideally, it'd also allow you to modify existing ones so I could do things like turning jQuery into jq, giving python2 and python3 disjoint keywords, etc.)

[trollixx]

Search prefixes are convenient, and I don't want to remove them. What's lacking is an easy way to discover them, and related or user defined grouping of docsets.

A lot can be done on the UI side. I think Dash just converts prefixes to check marks in the docset selection dropdown.

[FalcoGer]

The issue I have with it is that when I work on something, I usually reference the same docset over and over (read: I don't switch between them often/at all). and when I want to look up sum I don't want to write c++: or mysql: or something even longer like python3: in front of it. that's 75% of the search word specifying what docset i want to look in. And that's for everything I want to look up.
I like to just click the search field, ctrl+A and type what i want to know. That's why I suggested the drop down list. It's fixed and not directly affected by what I type into the search box. The checkbox idea next to the docsets is okay, too. Or maybe both, one option affecting what the other is set to.

That depends on your definition of "usable". It's much more discoverable, but much less time-efficient for a skilled user... similar to the trade-off between a CLI and a GUI.

I don't think this is the case or fair. GUIs can be faster than CLI. (certainly so with long, clunky and just the right mixture of "too verbose and lots to type, but not explaining enough" option flags as you find them in cmake scripts, opposed simple click in a checkbox which is nicely labeled).
Basically it all comes down to design.
Moving your mouse once a few pixels next to the search bar and selecting your docset(s) from a drop down list before clicking into the search bar certainly is faster, especially the more you search since the former you only have to do once, and typing it out every time will add up.

It doesn't seem too complicated to do, and if I knew the slightest bit of QT5 coding, I'd fork and try it. But I do not and it's not too pressing for me and I have other things to do unfortunately.

[ssokolow]

Moving your mouse once a few pixels next to the search bar and selecting your docset(s) from a drop down list before clicking into the search bar certainly is faster, especially the more you search since the former you only have to do once, and typing it out every time will add up.

Except that I want to switch my right hand back and forth between mouse and keyboard as little as possible in performing a query and I tend to switch back and forth between projects, so I don't want to have to keep playing around with a selector dropdown. (Though having the ability to map a custom prefix like ocr to "Python 3.x (stdlib only), Qt5, and OpenCV" for my "custom OCR frontend" project would be very nice.)

Win + Z pyTabzipi
(The entry for zipfile.ZipInfo appears)
Enter
(Input focus shifts to the main panel)
(read)
Page Down
(read)
Page Down
(read)
Ctrl + Z

For anything else, I'd have to switch to the mouse to select among the results without far too many ↓ keypresses, but that's just one switch at the end.

...and, sometimes, I do this:

Win + Z Ctrl + Shift + N (Why is this not Ctrl + T like every other tabbed UI?)
qTabrestores↓↓Enter (read for a bit) Win + Z

Throw in things like / (a simpler-to-type alternative to Ctrl + F), Esc, and Page Up/Page Down and I often interact with Zeal without ever taking my hands off the keyboard.

I just wish it were more Keyboard-friendly. For example, supporting tab-completion within searches so pyTabzipiTab would produce python:zipfile.ZipInfo so I could then continue with .com without having to type out the whole zipinfo.com.

If I can ever get around to being on a current version, I want to verify that it still has the weird "gets confused about focus and requires me to rapidly tap Ctrl+Z to get it to dismiss" bug and report it. (As well as how bad a design it is for "Please wait for all operations to finish" to continue to come up after the progress indicator has gone away because, apparently, it only provides visual feedback for the download phase of updating a docset.)

[Akronix]

I think dropdown UI selectors or checkboxes aren't incompatible with having the prefix option at all. Se for instance the interface in Github to filter issues (by label, by author, etc.)

Also, I think it's a good idea to be able to redefine your own prefixes that can be a subset of the available docsets. Although, this can be done as a separate task as it requires more more work and design I think.

[jotaf98]

Just to add my 2 cents: A dropdown menu doesn't preclude the use of keyboard shortcuts. It would be easy enough to have keys to select the next/previous item in the dropdown menu.

And it has the advantage that it's visible so very discoverable (filter keywords and keyboard shortcuts have to be read about somewhere else).

Something similar could also be done if checkboxes are added to the current sidebar instead.

[ssokolow]

It would be easy enough to have keys to select the next/previous item in the dropdown menu.

To me, that feels so out of touch with the realities of actual keyboard navigation that it's like claiming that keyboard navigation of websites is feasible because you can get to the link you want by pressing the Tab key half a million times per page.

(For an example of actual keyboard navigation on a website, try typing a ? on GitHub when no text-entry field is focused.)

We assumed that a Qt widget like a dropdown will have at least that basic affordance to keyboard navigation. It was just taken as a given. I expect Zeal to remain more efficient than running cargo doc --open in my Rust projects to access the built-in search in the generated docs.

[jotaf98]

I have 4 docsets on Zeal right now. Pressing e.g. Ctrl+J/K 2-3 times doesn't seem that out of touch to me.

But if you have lots of docsets and want to use the keyboard only, then the current filtering system (with tab auto-complete) seems like a reasonable compromise.

There is a somewhat-working (non-discoverable) keyboard solution now. What we're discussing is a mouse-based solution that is discoverable by general users, and which simply doesn't exist at the time. In this context, asking for more keyboard features seems like a poor allocation of resources.

[ssokolow]

I have 4 docsets on Zeal right now. Pressing e.g. Ctrl+J/K 2-3 times doesn't seem that out of touch to me.

But if you have lots of docsets and want to use the keyboard only, then the current filtering system (with tab auto-complete) seems like a reasonable compromise.

I have 67 docsets installed and would have more if Zeal matched the simplicity Dash claims for turning arbitrary Rust and Python package documentation into docsets.

(I use Zeal and, if I were on macOS, would use Dash for what's available of the Python, Rust, JavaScript, CSS, Lua, PHP, Linux, Arduino, and DevOps ecosystems for web, CLI, GUI, and embedded development.)

There is a somewhat-working (non-discoverable) keyboard solution now. What we're discussing is a mouse-based solution that is discoverable by general users, and which simply doesn't exist at the time. In this context, asking for more keyboard features seems like a poor allocation of resources.

I have nothing against improved discoverability. Heck, I really shouldn't have had to guess at the keyword for the OpenCV Python documentation until I found cvp. I'm arguing that, whatever solution is chosen, it must not cause a usability regression for keyboard use.

[quigonjeff]

Hello. First, thank you for the great work on Zeal. Really useful.

My issue (or question) is that the "docset:searchTerm" works for me most of the time, but it fails for languages that allow colon (:) as the first letter of the identifier. For example, in Haskell there are a number of functions that start with a colon, including colon itself.

Currently the query “haskell::” returns nothing, and I can't find a way to search for the “:” function. Is there any way to do it?

Thanks.

[trollixx]

@quigonjeff It's the same problem as #428. No quick fix unfortunately.

[rvv27]

Guys, simply add checkboxes to disable/ enable docsets. Search queries should only be performed on ticked(checkbox) docsets. This is a very basic functionality, I think. If there are multiple docsets installed it is very difficult to find an item from the search results since all docsets have lots of things in common, specially the basic classes.

Please don't confuse further, simply add checkboxes. Because at a time a developer would usually be using one or two docsets and simply disable others for easy searching, easy result finding and to save on performance and fast searching.

[rvv27]

Also guys I have a quick and easy suggestion who wants to filter docsets with ease:
Let's say I want to only browse docset: Android. So I would search like this "Android: ImageView"
Since I have added few spaces between colon and the class name, I can simply double click on ImageView text and it would only select it and I can type something else. This gets the job done and you are not required to write "docset:" keyword to search something.

You can also create separate tabs, each tabs stores the searched keyword. This is useful if you are reading items from multiple docsets at a time.

[manojbaishya]

Temporary workaround

1. Make a directory at ~/.local/share/Zeal/Zeal/backup.
2. Move lesser used docs <name>.docset from ~/.local/share/Zeal/Zeal/docsets to above.

Before	After

To restore, simply move the relevant docset from ~/.local/share/Zeal/Zeal/backup to ~/.local/share/Zeal/Zeal/docsets.

[FalcoGer]

@ssokolow I think you are a bit out of touch to be honest. You have 67 docsets installed. That's a bit of an edge case, don't you think? Most users would probably have maybe 2-10, depending on what they're working on regularly.

If I work on a python project I don't want search results for C#. When I work on something I look it up in that docset only and I don't wildly switch. An exception would be if I were to work on a C# web application, in which case I need some HTML and JS and possibly some SQL.

So in most cases it's perfectly fine to use the mouse. How long does it take to switch your mouse off your keyboard and then click a checkbox or drop down list anyway? perhaps 2 seconds at most? And switching with a keyboard shortcut could still be implemented. Heck you could even implement a command you type into the searchbar to switch with your precious autocomplete.

Even then how often do you switch your docsets, especially if you could group your search queries into something like C#Web that includes html, JS, JQuery, etc? And what then? You look for mysql:time and you find 50 search results? Then it's perfectly fine to use the keyboard to step through but not when stepping through the docsets themselves?

Also consider this. You spend 2 seconds on the mouse, 2 seconds searching and then 3 minutes reading. Does your productivity really suffer that much if you were to not use your mouse and you save those 2 seconds, or maybe you spend 5 seconds searching instead because you can't remember how a specific docset is labeled and need to think about it for a bit? If you were to use the mouse for scrolling, which I find more tactile and easier than to reach such odd buttons like page up/down and potentially hit my power button which is right next to it, you could use the hand that is already on your mouse and click the checkboxes/drop down list and save a whole second!

This is of course all moot in the face that having an option for the mouse doesn't exclude options for the keyboard, including some string that would change the docset selection.

Keyboard junkies like you may exist but are not the norm, I imagine. Unfortunately I have no data to back this up. So improving UX for those with a healthy mix of keyboard and mouse doesn't seem that out of touch with me.

[ssokolow]

@ssokolow I think you are a bit out of touch to be honest. You have 67 docsets installed. That's a bit of an edge case, don't you think? Most users would probably have maybe 2-10, depending on what they're working on regularly.

For the record, I've since pruned it down to 30 as what I actively need has narrowed. It hasn't changed the reality that I have to multi-task between potential groups within the same afternoon and want to spend as little time building and tearing down context as possible.

It's bad enough that I'm currently struggling to find a workaround for a KWin bug that prevents Zeal from appearing raised and focused when I hit Win+Z to pull it up, even if I turn Focus Stealing Prevention completely off.

[mc-marcocheng]

I have nothing against improved discoverability. Heck, I really shouldn't have had to guess at the keyword for the OpenCV Python documentation until I found cvp. I'm arguing that, whatever solution is chosen, it must not cause a usability regression for keyboard use.

@ssokolow What is that cvp that you mentioned for OpenCV Python Documentation? I downloaded the official OpenCV documentation, but it is mainly for C++.

[ssokolow]

@mc-marcocheng Here's the meta.json's contents.

{
    "name": "OpenCV_Python",
    "revision": "0",
    "sourceId": "com.kapeli",
    "title": "OpenCV Python",
    "version": "3.1.0"
}

I don't remember where I pulled each installed docset from and I don't know how to investigate further.

[mc-marcocheng]

@ssokolow Thanks. I am able to find the docset here. It is strange that I can't find it in Zeal's docset list nor in the Zeal's User Contribution list.