Use icons instead of words for search result types #10661

zyphlar · 2024-02-17T08:35:16Z

The default external search behavior outputs words like

object MyInterface(int foo)

for each search result, however for any sizable project this gets visually very cluttered while adding relatively little understanding. Iconography is probably a better way of helping people skim for what they want.

This PR is a work in progress and feedback/changes/rewrites welcome, but I think it would be valuable for everyone. The use of Google Fonts is optional, any similar symbol would be just as useful, I just wanted to minimize the number of asset files to worry about while maximizing the number of available free icons at my disposal.

Here's what the PR looks like:

Stock, with some css tweaks:

  .material-symbols-outlined {
    font-size: 1em;
  }
  .searchresult .material-symbols-outlined {
    margin-left: 0.5em;
    vertical-align: middle;
  }

Or with doxygen-awesome-css in dark mode:

  .material-symbols-outlined {
    font-size: 1em;
  }
  .searchresult .material-symbols-outlined {
    margin-left: 0.5em;
    vertical-align: bottom;
  }

sonarcloud · 2024-02-17T08:48:22Z

Quality Gate failed

Failed conditions
81.6% Duplication on New Code (required ≤ 3%)

See analysis details on SonarCloud

albert-github · 2024-02-17T09:52:07Z

I'm not sure whether a reference to the google fonts is a good choice (but you already wrote: The use of Google Fonts is optional, any similar symbol would be just as useful, I just wanted to minimize the number of asset files to worry about while maximizing the number of available free icons at my disposal.):

potential licensing / copyright issues
need for an internet connection, one could have a local server running to do tests etc. or be inside a closed network that has no connection to the outside world.

I think it would be better to use a local set of icons, which would also give the possibility (through redefinition / settings) to use ones own preferred icons.

Furthermore it might be better to have the icon before the text as now it is a bit "ragged".

Note: as you mention it is still work in progress maybe an idea to make this more clear by setting the PR into WIP mode (right hand side of the PR page).:

templates/html/extsearch.js

doxygen · 2024-02-17T10:13:22Z

src/htmlgen.cpp

@@ -420,6 420,8 @@ static QCString substituteHtmlKeywords(const QCString &str,
 if (!serverBasedSearch)
 {
 searchCssJs = "<script type=\"text/javascript\" src=\"$relpath^search/searchdata.js\"></script>\n";
+ } else {
+ searchCssJs = "<link rel=\"stylesheet\" href=\"https://fonts.googleapis.com/css2?family=Material Symbols Outlined:opsz,wght,FILL,GRAD@24,400,0,0\" />";


I don't really like the external dependency. May break in the future and prevents off-line browsing. Better to bundle the set of icons with doxygen.

doxygen · 2024-02-17T10:15:36Z

templates/html/extsearch.js

+
+ icon = "asterisk";
+
+ if (item.type == "dir")


Suggest to use a map instead of if..else if..else if, i.e.

const myMap = { "key 1" : "value 1", "key 2" : "value 2", ... "key n" : "value n" };

zyphlar · 2024-02-17T21:16:45Z

Thanks for the feedback! All good points. It may be possible to bundle a WebFont with appropriate licensing to reduce the internet dependency.

As for putting the icons on the left vs the right, I started out on the left but it visually clashed with the numbering, as if there were two bullets. To me the right hand side sort of has a "external link information, here's what you'll get if you click" feel, kinda like Google's "cached" or other link metadata. I don't have a strong opinion though, anyone with a good sense for design is welcome to improve. I wonder if the numbered bullets are even that important? Or maybe the icons float to the left of the number like a pre-bullet?

albert-github · 2024-02-18T09:04:40Z

As for putting the icons on the left vs the right, I started out on the left but it visually clashed with the numbering, as if there were two bullets. ...

I'm not getting this, how does this clash? I was thinking something like: <number> <icon> <text>
Maybe you could shown an image of the "left side problem"

doxygen · 2024-02-18T09:50:17Z

As for putting the icons on the left vs the right, I started out on the left but it visually clashed with the numbering, as if there were two bullets. ...

I'm not getting this, how does this clash? I was thinking something like: <number> <icon> <text> Maybe you could shown an image of the "left side problem"

The number also doesn't add that much, so the icon could also serve as the "bullet" instead of a number.

zyphlar · 2024-05-18T05:22:47Z

@albert-github @doxygen I finally got around to working on this again, here's what it looks like with the "left hand side number clash problem" and with no numbers, just icons. I think no numbers just icons looks best, personally, though I wonder if people may prefer to have the option. To get rid of the external dependency without a whole bunch of SVG wrangling and file copying and duplication between light and dark and relative path nonsense, I checked out the Google Font license and copied the font file and its license into the repo. If we want to try and find two dozen other icons and not use Google at all that's OK but webfont technology is pretty slick, <span class="material-symbols-outlined">icon_name</span> generates a day or night colored icon with zero javascript, and it's Apache licensed.

Left hand side icon with numbers:

No numbers just icons:

Stock (no awesome-css):

I also print the result type in the title attribute so that arbitrary icons may be less confusing:

Please see the updated PR, depending on your decisions I think after cursory review this is pretty good to go!

zyphlar · 2024-05-18T07:35:44Z

Also fun fact, this woff file contains a few instances of the bytes 0x0d0a which means that git may interpret it as text and try to replace it with 0x0a ... in other words, turn \r\n into \n in a binary file.

Anyway I think I fixed that issue lol :) you can see what files git has mistakenly interpreted as text by running git ls-files --eol | head

zyphlar · 2024-06-24T21:37:48Z

@albert-github this should be ready if it looks good to you

Use icons instead of words for search result types

1fa0abe

albert-github reviewed Feb 17, 2024

View reviewed changes

templates/html/extsearch.js Show resolved Hide resolved

doxygen reviewed Feb 17, 2024

View reviewed changes

zyphlar marked this pull request as draft February 17, 2024 21:17

zyphlar marked this pull request as ready for review May 18, 2024 05:23

Moving search result icons to replace numbers; copy Google Font locally

baa2b3e

zyphlar force-pushed the custom_search_iconography branch from 5f5d6bd to baa2b3e Compare May 18, 2024 07:29

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Use icons instead of words for search result types #10661

Use icons instead of words for search result types #10661

zyphlar commented Feb 17, 2024

sonarcloud bot commented Feb 17, 2024

albert-github commented Feb 17, 2024

doxygen Feb 17, 2024

doxygen Feb 17, 2024

zyphlar commented Feb 17, 2024

albert-github commented Feb 18, 2024

doxygen commented Feb 18, 2024

zyphlar commented May 18, 2024

zyphlar commented May 18, 2024 •

edited

Loading

zyphlar commented Jun 24, 2024

Use icons instead of words for search result types #10661

Are you sure you want to change the base?

Use icons instead of words for search result types #10661

Conversation

zyphlar commented Feb 17, 2024

Stock, with some css tweaks:

Or with doxygen-awesome-css in dark mode:

sonarcloud bot commented Feb 17, 2024

Quality Gate failed

albert-github commented Feb 17, 2024

doxygen Feb 17, 2024

Choose a reason for hiding this comment

doxygen Feb 17, 2024

Choose a reason for hiding this comment

zyphlar commented Feb 17, 2024

albert-github commented Feb 18, 2024

doxygen commented Feb 18, 2024

zyphlar commented May 18, 2024

zyphlar commented May 18, 2024 • edited Loading

zyphlar commented Jun 24, 2024

zyphlar commented May 18, 2024 •

edited

Loading