Description: When opening help on macOS in one's default internet browser you can search among available index entries. Upon typing matching index entries are shown, sorted in module names and/or "global" tag. On macOS on LO620 (maybe it happened before, I cannot remember) most of the matching index items in the "GLOBAL" part are shown at least twice, and some even in a higher number of appearances. Besides, "GLOBAL" string in not localizable, which is an additional bug. Also, the search in "GLOBAL" part finds strings that are actually not a match, like entering "kuv" in sl language you get hit index entries like "kazala vsebine -- ustvarjanje in posodabljanje", because it contains letters "k", "u" and "v". This is not how search should work, it should find strings like *kuv* ... Using sl lang-pack. Steps to Reproduce: 1. Open local help in Slovenian user interface. 2. Type a string in index search box: kuv 3. see what index entries get shown in the left sidebar Actual Results: Here is just a part of GLOBAL list of hits: kopiranje -- v okolju Unix kopiranje -- v okolju Unix kazala vsebine -- urejanje in brisanje kazala vsebine -- ustvarjanje in posodabljanje shranjevanje kot ukaz -- varnostni ukrepi shranjevanje kot ukaz -- varnostni ukrepi kazala vsebine -- urejanje ali brisanje vnosov končne opombe -- vstavljanje in urejanje komentarji -- vstavljanje/urejanje/brisanje/tiskanje komentarji -- vstavljanje/urejanje/brisanje/tiskanje klasifikacija -- prikaz v uporabniškem vmesniku grafike s slikovnimi točkami -- vstavljanje in urejanje grafike s slikovnimi točkami -- vstavljanje in urejanje faksi -- programi za faksiranje/tiskalniški faksi v okolju UNIX faksi -- programi za faksiranje/tiskalniški faksi v okolju UNIX krivulje -- urejanje točk krivulje -- urejanje točk ... Expected Results: Same index entries should be listed only once. Reproducible: Always User Profile Reset: No Additional Info:
Confirming with Version: 6.2.1.2 Build ID: 7bcb35dc3024a62dea0caee87020152d1ee96e71 Threads CPU : 4; OS : Mac OS X 10.14.2; UI Render : par défaut; VCL: osx; Locale : fr-FR (fr_FR.UTF-8); Langue IHM : fr-FR Calc: threaded I entered the string "maria", hoping to find an entry to mariadb. However, the help seems to parse the search string as individual non-contiguous characters, which may or not be separated by a space, other characters, etc. In my example, the string "maria" returned : Marque-pages -- aide (twice) Marges -- définition à l'aide de la souris (twice) Both of these results are not what is expected.
It seems also this is a problem with the way search is conducted: in the proposed search it finds also matches where one word contains k, the other u, the third v, although the search shoud be about strings containing the exact string "kuv".
This is still the case, and I presume applicable to all OSes, since the help is online, so setting OS all to raise visibility
The HTML Help page search function uses a "fuzzy" algorithm to pick matching results. The code refers to a "typo" tolerance feature. I believe this is what the reporter and commenters are mainly referring to. To aid recognition, the characters that match the search term are highlighted in boldface to show how the found entry was matched. However, the "double entries" referred to are a result of fundamental flaw in the way the search results are rendered. They are not all correctly grouped under the LO module that they relate to (CALC, WRITER, IMPRESS, etc). I have a patch prepared that fixes the grouping in the list. However the "fuzzy" matching is not a bug but showing the results correctly grouped will hopefully make this fuzz factor much more tolerable, even helpful.
Ross Johnson committed a patch related to this issue. It has been pushed to "master": https://git.libreoffice.org/help/commit/a03b2a3c515c5a15cbe22a24ee436fabd9ec272c tdf#123506 - HTML Help pages - group search results under module headings
Created attachment 175201 [details] Screenshots of current results Hi Ross! First of all, thanks for taking the time to work on this issue. After your patch, I'd like to give some feedback on its impacts and suggest directions for further improvements. First, it seems that the script guesses the LibreOffice module to which a bookmark belongs based on the folder where the help file is stored (f.i. simpress, swriter, scalc, shared, etc). To explain why this is not ideal, I'll give an example. After your patch, suppose the user wants to search about table formatting in Writer and enters the word "table" in the search box. The results from this search will only include Calc help pages (see the attached images). No Writer help page will appear. The reason for this is that much of the help content for tables (both for Writer and Calc) is stored in the "scalc" folder. This was done in the past to reuse help contents and differences between applications were tackled using <switch select="appl"> tags. The current implementation is not great as well because it return results with links to incorrect pages. For example, in the current help (prior to your patch), if you search "colors" one of the results will be "colors -- adding" under the Calc module (see page 2 in the attached file). However, when you click the link, it will open a SHARED page and thus hide all contents that are Calc-specific (and which were the contents that the user was interested in finding). There are many more instances where these issues occur. There are many contents in the "shared" folder that are not "Global" because they have specific contents for Writer, Impress, Calc and Draw. Hence, if their bookmarks appear as Global, these specific contents will never be reachable to final users searching bookmarks. I know that the problem I'm stating here is very hard to solve, because the relationship between modules and folders in helpcontent2 is not 1 to 1. But I believe we have to start discussing this issue or else the help pages will lose discoverability. Hence, it doesn't matter how much rich content we add to the pages, some users will never be able to find them. Maybe one way around this problem is to let the user select which module he/she wants to see results about, then "Global" results would always use DbPAR=MODULENAME according to what was selected by the user. Also, results could be sorted according to the Module the user is interested, f.i. showing Writer results first if the Writer module is selected. Currently the "Module" drop-down list in the Help is not capable of doing these things. It only changes DbPar and goes to the main0000 help page.
Ilmari, maybe you can help with this discussion.
(In reply to Rafael Lima from comment #7) > Ilmari, maybe you can help with this discussion. You have many good points in your comment 6 and it seems fighting the complexity with JavaScript would be rather hopeless. It seems that something would need to be done on the level of XHP file organisation.
Created attachment 175220 [details] LO 7.2 Help page for "colors -- adding"
Created attachment 175221 [details] LO 7.3 Help page for "colors -- adding"
(In reply to Rafael Lima from comment #6) > Created attachment 175201 [details] > Screenshots of current results > > Hi Ross! First of all, thanks for taking the time to work on this issue. Thanks. I'm just getting everything set up and this was maybe the second issue I've accepted. > > After your patch, suppose the user wants to search > about table formatting in Writer and enters the word "table" in the search > box. The results from this search will only include Calc help pages (see the > attached images). No Writer help page will appear. I'm pretty sure the WRITER entries are there, just not on the first page. The change that I made only sorted the index entries based on module (application) whereas before they were unsorted. It did not modify any content of the index entry elements. The module headings (CALC, WRITER etc) were and still are inserted into the list on a first matching entry basis, so it was good fortune if more than one or two module headings appeared on the first page of a longish list. But that was the issue. Users saw multiple entries for "table ..." under, say, CALC, but they didn't all belong to CALC. The same was the case for all of the modules. They appeared to be grouped but actually weren't. The help system needs some work (a lot actually). I've only just started looking at it but I'm finding small and large problems wherever I go in it. I have to be careful to identify what is an issue and what is my inexperience with it. > The reason for this is > that much of the help content for tables (both for Writer and Calc) is > stored in the "scalc" folder. This was done in the past to reuse help > contents and differences between applications were tackled using <switch > select="appl"> tags. I'm working on another issue involving that at the moment. Particularly in relation to the hid bookmarks branch. I've discovered a problem where the <switch select="appl"> isn't working entirely. I'm essentially getting the first <case select="..."> ok but subsequent <case> or <default> sections aren't appearing and I get directed to the main0000.html page for the application. It's not the javascript in help2.js because I just stepped the Chrome debugger through it. It's as if the help system is redirecting before it gets to help2.js. > The current implementation is not great as well because it return results > with links to incorrect pages. Yes, as above. For example, in the current help (prior to > your patch), My patch added three statements to one function in help.js. > if you search "colors" one of the results will be "colors -- > adding" under the Calc module (see page 2 in the attached file). However, > when you click the link, it will open a SHARED page and thus hide all > contents that are Calc-specific (and which were the contents that the user > was interested in finding). I see the same page rendered (see the two attachments). LO 7.2 is using the online help while LO 7.3 is using local help pages. All of the <switch> magic is in help2.js loaded with each HTML help page. The index simply links to that HTML page and the relative location in the list and the grouping under the application headings doesn't influence that. > > There are many more instances where these issues occur. There are many > contents in the "shared" folder that are not "Global" because they have > specific contents for Writer, Impress, Calc and Draw. Hence, if their > bookmarks appear as Global, these specific contents will never be reachable > to final users searching bookmarks. Yes there are many problems with help pages. I suspect that my changes have merely exposed them, but have not caused them. If I can resolve the other issue I'm working on I may be able to propose a solution. > > I know that the problem I'm stating here is very hard to solve, because the > relationship between modules and folders in helpcontent2 is not 1 to 1. But > I believe we have to start discussing this issue or else the help pages will > lose discoverability. Hence, it doesn't matter how much rich content we add > to the pages, some users will never be able to find them. Yes, agreed. Where should that discussion take place and when? Here in this issue is not ideal as it will likely disappear into the archives. > > Maybe one way around this problem is to let the user select which module > he/she wants to see results about, then "Global" results would always use > DbPAR=MODULENAME according to what was selected by the user. Also, results > could be sorted according to the Module the user is interested, f.i. showing > Writer results first if the Writer module is selected. I'd certainly like to see the index arranged with the application that made the call to help have it's results first in the list. That would not be possible without sorting the list. So we're one step closer now. > > Currently the "Module" drop-down list in the Help is not capable of doing > these things. It only changes DbPar and goes to the main0000 help page.
One further observation to the last comment: The index may have appeared to be more convenient because if I'm using, say, WRITER and I search for something, the chances are it will relate to WRITER, and so would have tended to appear earlier in the list. Then given the way list headings are injected into the list on a first match basis, the chances that "WRITER" would appear on the first page a higher. But the matching entries were still presented randomly under the wrong module headings.
At this point, I don't believe these are regression issues but a new bug report that needs to be raised to fix these pre-existing issues. (In reply to Rafael Lima from comment #6) > Currently the "Module" drop-down list in the Help is not capable of doing > these things. It only changes DbPar and goes to the main0000 help page. Unless there's a better method, extracting the DbPar value from the initial application main page URL and passing it into the search is surely possible. Then the index can be prioritized for the user. There are many annoying aspects to the browser help system beyond the scope of this report, eg, (all IMO): Clicking on a match in the index goes to that page but then, (a) the index changes to the complete set of bookmarks for that module. User's will normally go through some trial and error finding the specific information they need, which may be across multiple help pages, and having to refresh the search every time to look for another match is off-putting. If I want the complete list for the application, which (b) should have been shown on first entering Help, then I should be able to use the Modules dropdown, which (c) needs to be modernised to hover-over activation/deactivation and (d) needs to filter with the current search results, not merely redirect to the main application page.
(In reply to Ross Johnson from comment #13) > first entering Help, then I should be able to use the Modules dropdown, > which (c) needs to be modernised to hover-over activation/deactivation and There is nothing modern in hover activation, I made it like that on purpose. I think it was for stability of the UI (hover can be fickle) and accessibility.
(In reply to Ross Johnson from comment #13) > Clicking on a match in the index goes to that page but then, (a) the index > changes to the complete set of bookmarks for that module. User's will > normally go through some trial and error finding the specific information > they need, which may be across multiple help pages, and having to refresh > the search every time to look for another match is off-putting. This patch fixes this: https://gerrit.libreoffice.org/c/help/+/122566 It was simply due to functions being called in the wrong order. The main thing of the patch is to switch from Fuzzysort to FlexSearch. We lose fuzzy matching, but maybe it was not desired anyway.
*** Bug 139216 has been marked as a duplicate of this bug. ***
(In reply to Buovjaga from comment #15) > (In reply to Ross Johnson from comment #13) > > Clicking on a match in the index goes to that page but then, (a) the index > > changes to the complete set of bookmarks for that module. User's will > > normally go through some trial and error finding the specific information > > they need, which may be across multiple help pages, and having to refresh > > the search every time to look for another match is off-putting. > > This patch fixes this: https://gerrit.libreoffice.org/c/help/+/122566 Olivier built a preview, if you want to test: https://help.libreoffice.org/7.3/
(In reply to Buovjaga from comment #15) > (In reply to Ross Johnson from comment #13) > > Clicking on a match in the index goes to that page but then, (a) the index > > changes to the complete set of bookmarks for that module. User's will > > normally go through some trial and error finding the specific information > > they need, which may be across multiple help pages, and having to refresh > > the search every time to look for another match is off-putting. > > This patch fixes this: https://gerrit.libreoffice.org/c/help/+/122566 > > It was simply due to functions being called in the wrong order. > > The main thing of the patch is to switch from Fuzzysort to FlexSearch. We > lose fuzzy matching, but maybe it was not desired anyway. It sounds like you were able to fix it separately or does it actually depend on FlexSearch? Because there are several problems with FlexSearch (see my comment in https://gerrit.libreoffice.org/c/help/+/122566).
(In reply to Ross Johnson from comment #18) > (In reply to Buovjaga from comment #15) > > (In reply to Ross Johnson from comment #13) > > > Clicking on a match in the index goes to that page but then, (a) the index > > > changes to the complete set of bookmarks for that module. User's will > > > normally go through some trial and error finding the specific information > > > they need, which may be across multiple help pages, and having to refresh > > > the search every time to look for another match is off-putting. > > > > This patch fixes this: https://gerrit.libreoffice.org/c/help/+/122566 > > > > It was simply due to functions being called in the wrong order. > > It sounds like you were able to fix it separately or does it actually depend > on FlexSearch? Because there are several problems with FlexSearch (see my > comment in https://gerrit.libreoffice.org/c/help/+/122566). Yeah, it was basically about moving one line above another line, but I thought to do it at the same time. The problem with FlexSearch was that I didn't tell it to fully tokenise the text and it only tokenised words. Ross: about the hover menu topic, you could experiment with it. I will mention some resources. This writer advises against hover menus, so you could consider what he says and if you still want to go with them: https://css-tricks.com/in-praise-of-the-unambiguous-click-menu/ This is a reaction to the CSS Tricks article: https://chrisbracco.com/css-accessible-multi-level-dropdown-hover-navigation/ Looks like the solution presented here would be the most complete one, though, as it was reviewed by an accessibility expert: https://moderncss.dev/css-only-accessible-dropdown-navigation-menu/ "The CSS-only method needs some Javascript to fully meet WCAG 2.1. In particular, javascript needs to be used to offer a non-mouse/non-tab way to dismiss the menu (think escape key) to meet success criteria 1.4.13." Note: we don't need a polyfill for :focus-within as we don't support IE 11 anymore. We have some old polyfills laying around still and those could be dropped at some point. All of our JS could also use let & const instead of just vars, if desired.
(In reply to Buovjaga from comment #19) > Ross: about the hover menu topic, you could experiment with it. I will > mention some resources. > Thanks Ilmari. > This writer advises against hover menus, so you could consider what he says > and if you still want to go with them: > https://css-tricks.com/in-praise-of-the-unambiguous-click-menu/ I can see your, and his, point. I've landed on many a page I didn't want to go to because of things like he's describing. The thing that irritated me with the Help pages dropdowns wasn't having to click to drop the menu, but that it doesn't roll back up when I click away from it, say, on the Language dropdown, and then there are two drop downs. Or, if I click in the search box, the Modules drop down is still there obscuring the search text. So when I mentioned hover menu I was really thinking "wouldn't it be nice if the menus magically went away if I do something somewhere else on the page". I just had a closer look at Chrome's bookmarks bar. They are click to drop and the hang around but they disappear if I click anywhere outside of the menu. Are you're new changes to your FlexSearch integration available via Oliver's preview link yet? I'm still seeing the old limited results there.
(In reply to Ross Johnson from comment #20) > (In reply to Buovjaga from comment #19) > > Ross: about the hover menu topic, you could experiment with it. I will > > mention some resources. > > > Thanks Ilmari. > > > This writer advises against hover menus, so you could consider what he says > > and if you still want to go with them: > > https://css-tricks.com/in-praise-of-the-unambiguous-click-menu/ > > I can see your, and his, point. I've landed on many a page I didn't want to > go to because of things like he's describing. > > The thing that irritated me with the Help pages dropdowns wasn't having to > click to drop the menu, but that it doesn't roll back up when I click away > from it, say, on the Language dropdown, and then there are two drop downs. > Or, if I click in the search box, the Modules drop down is still there > obscuring the search text. > > So when I mentioned hover menu I was really thinking "wouldn't it be nice if > the menus magically went away if I do something somewhere else on the page". > > I just had a closer look at Chrome's bookmarks bar. They are click to drop > and the hang around but they disappear if I click anywhere outside of the > menu. Ok, we might enhance the current state with JavaScript, then. > Are you're new changes to your FlexSearch integration available via Oliver's > preview link yet? I'm still seeing the old limited results there. It's early in the morning for him still, so you would have to grab the modified help.js from the patch and replace it in your own local build for now :)
I have just submitted a patch. https://gerrit.libreoffice.org/c/help/+/122903 Focus search results to user's current module plus GLOBAL: This change focuses the search results on the module the user initially called help from and in addition, in the same way that the initial index is presented, limits the results to that module plus GLOBAL results. Explanation: Currently, when a user arrives at a help page from a module they begin with a blank search term and by default the index is focused on the module they came from. As they enter a search term the results from ALL modules are presented, paginated and either, (7.3 current) grouped by modules but in a fixed order of modules that often pushes results relative to the user's module off the first page of the index or, (7.2 and earlier) pseudo randomly with incorrect grouping under modules. If a user wishes to explor other module results they can choose a module from the Modules drop down. Their search term remains and they can easily search again.
Also, the OR noticed that 'GLOBAL' is not localisable. It also has connotations in English that don't fit it's use in LO Help. It is the wrong term. GLOBAL implies that it is common to ALL modules, not just more than one module, which is what the connotation should be. 'SHARED' (the term used internally) is a better word. I'm not sure why there is a 'GLOBAL' section at all in principal: whether it's helpful to users or if it was technically more efficient to organize subjects that way.
Ross Johnson committed a patch related to this issue. It has been pushed to "master": https://git.libreoffice.org/help/commit/8b955ca1d2fa8132a22be12daeb416618277905c tdf#123506 - focus search results to user's current module
Verified as fixed for the online help for 7.3, at least the part in which selecting a module on the help website (e.g. Writer) and then using the search box on the right (e.g. with the string "table") does actually restrict the results to the current module. Great improvement.