Function finder

[michaelhkay]

With the number of functions in the fn:namespace now standing at 213, the use of a drop-down in the F+O "function finder" has become a little unwieldy. Are there ways it could be improved, for example by reducing the size of the list when you type the first character of the required function name?

[ndw]

Yes, that sounds practical.

[ndw]

There are, on 20 minutes of investigation, three ways to do this: cobble together a wodge of JavaScript, HTML, and CSS to do the dropdown by hand, use some third party library[1] that contains a wodge of JavaScript, HTML, and CSS, or use a datalist. The advantage of the datalist is that it requires one hacky trick and about 8 lines of JavaScript. The disadvantage is that the presentation varies on different browsers, and won't work at all on sufficiently old or niche browsers.

I made a version that uses datalist by hand, if anyone wants to express an opinion.

[1] A third party library, like jQuery, is a dependency I think we should avoid. They grow stale over time and can have security complications.

[michaelhkay]

The datalist seems reasonably OK to me. Not sure if it's best to retain the partitioning by namespace?

[ChristianGruen]

I made a version that uses datalist by hand, if anyone wants to express an opinion.

Thanks for the preview. I like the combination of prefixes and names. Next, if I could choose, I would love to…

• select the first list entry to pressing ENTER (without Cursor-DOWN), and
• use the / key to jump to the search component (as it’s possible on many other websites, like GitHub). I’m too stupid/lazy to use the mouse or the pad, which is why I’ve never used this component in the past.

[ndw]

I don't think I can do anything about selecting an entry without pressing down, but I think I have made "/" move the focus to the input box. Reload and see what you think.

[ChristianGruen]

I don't think I can do anything about selecting an entry without pressing down, but I think I have made "/" move the focus to the input box. Reload and see what you think.

Excellent!

[Arithmeticus]

One thing I have done when my function library has grown too large is to supply keywords to each function in the source, and then at the head of the documentation supply a concise index of functions organized by keyword. That supports both convenience and discovery, as functions that straddle two concepts can now be listed in both.

[michaelhkay]

The current function finder is geared towards people who know what they are looking for and want to get there as quickly as possible, which is a very different requirement from people who come in wanting to find out if there is anything to calculate (say) a standard deviation.

[Arithmeticus]

yes, I was just thinking an extra tool beyond the current dropdown widget, not about its replacement.

[ChristianGruen]

@ndw +1 for your suggestion to just merge and deploy it.

[wendellpiez]

This improvement LGTM, although I think I'd prefer the dropdown's sort order to go by local names.

I am not sure it makes sense to cater to small touchscreens -- although it is true that one time in the Tokyo subway I stole a glance at some guy's handheld mobile device and he was looking at Linux docs. (DocBook!)

[ndw]

I can certainly try sorting the list by local name and see what that produces. I don't actually have any control of (or have to write any code for!) the selection of items from the list. That's in the browser. If I was in control, I'd be tempted to make leading matches more significant than later ones (e.g, if you type "ge" you should get "array:get" and "map:get" before "fn:message"). But it is what it is and I didn't have to write any code for it so the bugs aren't mine!

Regarding small screens: our specs are mostly pretty fine. I expect some of the longer examples would require a bit of scrolling, but it's an overconstrained problem: "please show this (1) 80 character wide verbatim text, (2) in a font large enough to read, (3) on a display 7cm wide". Pick two. But the side bar navigation and ToC are clunkier. I think they still work, they're just clunky.

[wendellpiez]

@ndw, to point 1: acknowledged. (Yay rah.)

To point 2: I will definitely be using the term "overconstrained problem" going forward.

[ndw]

Since the current verison is just one I constructed by hand, I updated it so the items in the data list are sorted by local name. I'm not sure I think it's an improvement. To my eye, it makes a more jumbled list. But I don't feel strongly about it because I think the point is to type enough letters so there are only one or two choices anyway.

[ChristianGruen]

I have a slight preference for the version sorted by prefix:local-name. It’s all an improvement though.

[wendellpiez]

Agreed, it is more jumbled when sorted by local-name. :-(

Sorting is also all upper-case first followed by all lower case.

Could the list be sorted case-insensitively (in any case), and displayed as {local-name(.)} [{prefix-from-QName(.)}] ?

Rendering as (for example) prefix-from-QName [fn] is this ... more confusing not less?

I also agree that it is all an improvement.

[ndw]

Done.