Bug 123506 - Online help: Multiple help index entries are shown
Summary: Online help: Multiple help index entries are shown
Status: VERIFIED FIXED
Alias: None
Product: LibreOffice
Classification: Unclassified
Component: Documentation (show other bugs)
Version:
(earliest affected)
6.2.1.1 rc
Hardware: All All
: medium normal
Assignee: Ross Johnson
URL:
Whiteboard: target:7.3.0 inReleaseNotes:7.3
Keywords:
: 139216 (view as bug list)
Depends on:
Blocks:
 
Reported: 2019-02-17 00:28 UTC by Martin Srebotnjak
Modified: 2022-01-27 12:43 UTC (History)
5 users (show)

See Also:
Crash report or crash signature:
Regression By:


Attachments
Screenshots of current results (212.88 KB, application/vnd.oasis.opendocument.graphics)
2021-09-22 18:14 UTC, Rafael Lima
Details
LO 7.2 Help page for "colors -- adding" (77.04 KB, image/png)
2021-09-23 12:30 UTC, Ross Johnson
Details
LO 7.3 Help page for "colors -- adding" (76.98 KB, image/png)
2021-09-23 12:31 UTC, Ross Johnson
Details

Note You need to log in before you can comment on or make changes to this bug.
Description Martin Srebotnjak 2019-02-17 00:28:15 UTC
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:
Comment 1 Alex Thurgood 2019-03-13 08:33:52 UTC
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.
Comment 2 Martin Srebotnjak 2019-10-24 09:40:40 UTC
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".
Comment 3 eisa01 2020-02-17 21:21:37 UTC
This is still the case, and I presume applicable to all OSes, since the help is online, so setting OS all to raise visibility
Comment 4 Ross Johnson 2021-09-19 06:02:08 UTC
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.
Comment 5 Commit Notification 2021-09-20 14:15:51 UTC
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
Comment 6 Rafael Lima 2021-09-22 18:14:18 UTC
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.
Comment 7 Rafael Lima 2021-09-22 18:17:58 UTC
Ilmari, maybe you can help with this discussion.
Comment 8 Buovjaga 2021-09-23 06:48:08 UTC
(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.
Comment 9 Ross Johnson 2021-09-23 12:30:00 UTC
Created attachment 175220 [details]
LO 7.2 Help page for "colors -- adding"
Comment 10 Ross Johnson 2021-09-23 12:31:06 UTC
Created attachment 175221 [details]
LO 7.3 Help page for "colors -- adding"
Comment 11 Ross Johnson 2021-09-23 12:53:37 UTC
(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.
Comment 12 Ross Johnson 2021-09-23 13:09:03 UTC
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.
Comment 13 Ross Johnson 2021-09-23 22:56:59 UTC
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.
Comment 14 Buovjaga 2021-09-24 05:57:32 UTC
(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.
Comment 15 Buovjaga 2021-09-24 09:35:27 UTC
(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.
Comment 16 Buovjaga 2021-09-24 09:49:01 UTC
*** Bug 139216 has been marked as a duplicate of this bug. ***
Comment 17 Buovjaga 2021-09-24 13:47:02 UTC
(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/
Comment 18 Ross Johnson 2021-09-24 22:24:37 UTC
(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).
Comment 19 Buovjaga 2021-09-25 09:13:20 UTC
(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.
Comment 20 Ross Johnson 2021-09-25 11:06:40 UTC
(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.
Comment 21 Buovjaga 2021-09-25 11:19:11 UTC
(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 :)
Comment 22 Ross Johnson 2021-10-01 07:23:50 UTC
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.
Comment 23 Ross Johnson 2021-10-01 07:34:18 UTC
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.
Comment 24 Commit Notification 2021-10-01 18:14:07 UTC
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
Comment 25 stragu 2022-01-27 12:43:21 UTC
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.