Zeal: 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

[r-barnes]

+1: I have a lot of docsets downloaded to my machine as a "just in case" measure - you never know when you might need them. But, for any given project, I can go weeks needing only one or two docsets. I wish that, during this period, I could disable the rest.

[gomio]

You can simply rename the folders xxx.docset you don't need to xxx.docset.OFF (or any other name).

El 18 de junio de 2017 20:14:05 CEST, Richard Barnes [e-mail] escribió:

+1: I have a lot of docsets downloaded to my machine as a "just in
case" measure - you never know when you might need them. But, for any
given project, I can go weeks needing only one or two docsets. I wish
that, during this period, I could disable the rest.

--
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/zealdocs/zeal/issues/77#issuecomment-309293387

--
Enviado desde dispositivo móvil.

[ssokolow]

Likewise. In fact, I deleted a bunch recently, just to work around this shortcoming in Zeal and I still need this because I'm actively working on several different projects which use mostly mutually-exclusive sets of technology.

For example, some of the mixtures are:

• Non-SPA Web: Python 2.x, Requests, FeedParser, and a ton of web technologies (Django, Bootstrap 3, etc.) but not anything like AngularJS which degrades poorly without JS enabled.
• One of my local GUI apps: Python 3.x, Rust, and Qt5 (glued together using rust-cpython and PyQt5)
• High-reliability CLI scripting: Pure Rust
• Another of my local GUI apps: Python 3.x, PyQt5, Pillow, OpenCV, and NumPy, but no Rust
• VPS/Workstation provisioning: Ansible (which uses Jinja), Vagrant, bash, and Nginx

[ssokolow]

@gomio Not good enough. I tend to work on two or more projects in parallel, so I need to be able to have different sets searchable in different Zeal tabs at the same time.

[r-barnes]

I could generate a little CLI script for switching docsets in and out, but this seems like the kind of thing that would be more usefully included in Zeal itself.

Also, the duplication of docsets implied by the directory renaming would make it difficult to ensure that all the documentation stays up to date.

[stimata-debug]

Is there a way to start up multiple zeal instances? zeal-html, zeal-ui, zeal-personal, zeal-work, etc would be really nice.

It is super tedious to have to remove, and add docsets whenever I switch contexts.

[trollixx]

@0e318236-1680-41a8-a989-3c9227637cdf not at the moment, see #546 for a similar request.

[PrinceMerluza]

9 years. Would also love this feature.

[Asharas]

I just tried this feature with python3:json and the search returns nothing even if Python3 docset is installed.
If I search python:json, search returns results not pertaining to Python3 docset (in my case returns also Jinja2 tojson filter).

[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.