rustdoc: feature request directly go to item on exact match

[TrAyZeN]

Problem

Hello, we already have an option Directly go to item in search if there is only one result which can be enabled in the settings

However, when typing an item path we have a lot of results that shows up and so we can rarely get redirected with the previous option.

Solution

I think that it could be useful to have a feature Directly go to item on exact match.

• This feature would be an option which can be enabled in the settings (so we still let users to choose what they prefer).
• As the name suggests it would redirected to the item documentation when typing the exact path.

For instance, on the previous screenshot when typing std::vec::Vec it would redirect to the item page.

[jyn514]

Rather than adding a new option, I would change the existing option to take you to the page if there's only one match or there's an exact match.

[PatchMixolydic]

If I'm reading this correctly, redirecting on an exact match when there's more than one result could be problematic if one type's name is the prefix of another (ex. searching for std::ffi::OsString would take you to std::ffi::OsStr).

[jyn514]

(ex. searching for std::ffi::OsString would take you to std::ffi::OsStr).

I don't see why that's true? OsString is not an exact match for OsStr.

[Rustin170506]

@rustbot claim

[Rustin170506]

I would like to try it.

[PatchMixolydic]

(ex. searching for std::ffi::OsString would take you to std::ffi::OsStr).

I don't see why that's true? OsString is not an exact match for OsStr.

This could be problematic for slow typers due to Rustdoc's incremental search feature. I may be misunderstanding how this feature will work, but if I'm not, then the problem is as follows: the user may type out std::ffi::OsSt, press 'r', then move to press 'i', but then get redirected to OsStr's docs before they can press the key.

[jyn514]

Oh I see - we could increase the delay for sending you to an exact match to something like a couple seconds.

[the8472]

How about going to the first result when hitting the return key?

[jyn514]

How about going to the first result when hitting the return key?

Sure, that also seems useful, right now enter does nothing immediately after a search. I think we can do both :)

[TrAyZeN]

If I'm reading this correctly, redirecting on an exact match when there's more than one result could be problematic if one type's name is the prefix of another (ex. searching for std::ffi::OsString would take you to std::ffi::OsStr).

I did not think about that issue but what @the8472 proposed sounds good to me.

[Rustin170506]

How about going to the first result when hitting the return key?

Sure, that also seems useful, right now enter does nothing immediately after a search. I think we can do both :)

I will add these two features.

[jsha]

@TrAyZeN Can you tell us more about the workflow you are using? Are you copy-pasting the fully-qualified path (std::vec::Vec) into a search box, or are you typing it out? If you're typing it out, it seems like it would be much faster to type just the item name (Vec), hit the down arrow, and hit enter. That's five keystrokes, vs fifteen keystrokes for the version you describe (including shift).

I agree with @jyn514 that we shouldn't have separate options for "directly go to single result" and "directly go to exact match." The former is already a niche feature, and off-by-default. We should update the existing feature to be something like "directly go to strong match," where a strong match is:

• single result
• exact match that is not a prefix of any other exact match

By the way, the current behavior, when you enable "directly go to single result", is that the navigation can be triggered if you pause for 500ms while typing. That's pretty surprising - and very unusual among search interfaces, as far as I know. I think as long as we're refining this functionality we should make navigation happen only if you hit enter.

[TrAyZeN]

My workflow may not be optimal but I am using rustdoc search engine in my browser. I expected when typing r std::vec::Vec in the url bar (r being my search engine keyword for rustdoc and std::vec::Vec being the content of the search) to be redirected to the std::vec::Vec page directly (i.e. not having to load search results and then getting redirected to the item page). However, what happens is that I get redirected to the list of search results. So, I was looking for settings and I found that Directly go to item on exact match option which was rarely triggered.

[jsha]

Ah, that makes sense! I also have a search engine in my browser to search the rust docs (I use the prefix rs). And I often use it as a shortcut to get to docs even when I already know where I'm going So I have a similar use case I'd like to solve.

For this use case, we know when we're typing the search that we're going to want the "go to first result" behavior, regardless of whether it's an exact match, or a unique match. So we could follow the example of Google's "I'm feeling lucky" searches: we could have a query parameter that indicates "go to first result," and people could put that in their browser searches. For instance, it might look like ?search=Vec&go_to_first=true. That has the advantage that it can trigger even on a short input like "Vec" - you don't have to type all the characters to make it unambiguous.

Another model we could borrow from is macOS Spotlight / Windows Start Menu. In those systems, as you type, the "best match" is highlighted. If you hit enter at any time, that best match will be executed. If we adopted this style in rustdoc, it wouldn't solve the browser toolbar search, but it might make a good replacement for the current "go directly on exact match" setting, because it could be enabled by default. The downside is that this model relies on very fast updates as you type each character. Our current search doesn't have that - it doesn't search until you've paused typing for 500ms.

Also it would be cool to try out OpenSearch to enable browser autodiscovery of the search functionality: https://martin-thoma.com/search-engine-autodiscovery/

[Manishearth]

So we could follow the example of Google's "I'm feeling lucky" searches: we could have a query parameter that indicates "go to first result," and people could put that in their browser searches. For instance, it might look like ?search=Vec&go_to_first=true. That has the advantage that it can trigger even on a short input like "Vec" - you don't have to type all the characters to make it unambiguous.

Strongly agree with this; in general we should probably be probing how users use the tool more and make design decisions based on that kind of thing.

I like the go_to_first plan

[Rustin170506]

By the way, the current behavior, when you enable "directly go to single result", is that the navigation can be triggered if you pause for 500ms while typing. That's pretty surprising - and very unusual among search interfaces, as far as I know. I think as long as we're refining this functionality we should make navigation happen only if you hit enter.

I also think the design is unusual, and if I were to expand on this feature I think it could lead to a bad experience, because maybe someone just wants to see similar results, but then they'll be forced to jump.

[Rustin170506]

For this use case, we know when we're typing the search that we're going to want the "go to first result" behavior, regardless of whether it's an exact match, or a unique match. So we could follow the example of Google's "I'm feeling lucky" searches: we could have a query parameter that indicates "go to first result," and people could put that in their browser searches. For instance, it might look like ?search=Vec&go_to_first=true. That has the advantage that it can trigger even on a short input like "Vec" - you don't have to type all the characters to make it unambiguous.

I think this is a good solution.

[jsha]

I found some more authoritative information on how Chrome discovers search engines automatically. OpenSearch is part of the story, but not all: http://code.google.com/p/chromium/issues/detail?id=2573

Once Chromium has determined it can search a site, any time the user types the URL of the site into the Omnibox the user is offered the ability to search the site.

1. On your site's homepage provide a link to an OpenSearch description document. [ or ... ]
2. If ... the user submits a form, then Chrome automatically adds the site to the list of searchable sites. ...the form must generate a GET, must result in a HTTP url, and the form must not have OnSubmit script.

Unfortunately, Rust's documentation on doc.rust-lang.org misses out on all of these. There's no search functionality on the homepage; users don't usually type out the full hostname because it's long; and searching doesn't generate a GET, because it's all done in JavaScript (and because we do search-as-you-type, so there's no moment at which the user has to actually "submit" the form).

The heuristics above actually do pick up on docs.rs' search functionality quite quickly, if you do a search from the homepage.

[Manishearth]

The basic way to implement this would be to check for the jump_to_result param directly here and find the first matching result.

rust/src/librustdoc/html/static/search.js

Lines 1256 to 1291 in 9964284

	function search(e, forced) {
	var params = searchState.getQueryStringParams();
	var query = getQuery(searchState.input.value.trim());
	if (e) {
	e.preventDefault();
	}
	if (query.query.length === 0) {
	return;
	}
	if (!forced && query.id === currentResults) {
	if (query.query.length > 0) {
	searchState.putBackSearch(searchState.input);
	}
	return;
	}
	// Update document title to maintain a meaningful browser history
	searchState.title = "Results for " + query.query + " - Rust";
	// Because searching is incremental by character, only the most
	// recent search query is added to the browser history.
	if (searchState.browserSupportsHistoryApi()) {
	var newURL = getNakedUrl() + "?search=" + encodeURIComponent(query.raw) +
	window.location.hash;
	if (!history.state && !params.search) {
	history.pushState(query, "", newURL);
	} else {
	history.replaceState(query, "", newURL);
	}
	}
	var filterCrates = getFilterCrates();
	showResults(execSearch(query, index, filterCrates));
	}

[jeanlucthumm]

@rustbot claim