Page MenuHomePhabricator

Help link (pressing F1) is partially broken
Closed, ResolvedPublic

Description

For several views (e.g. all registration views, log view, property view...) pressing F1 to show the help does not work any more.

The documents are still there as I can show them in the HELP perspective when I select them. For whatever reason I think the short cut links are broken.

E.g. MatchPoint Algorithm Executor help can be found under the link
qthelp://org.mitk.gui.qt.matchpoint.algorithm.control/bundle/org_mitk_gui_qt_matchpoint_algorithm_control.html

but F1 searches for
qthelp://org.mitk.gui.qt.matchpoint.algorithm.control/bundle/org_mitk_views_matchpoint_algorithm_control.html

Revisions and Commits

rMITK MITK
Restricted Differential Revision
Restricted Differential Revision
Restricted Differential Revision
Restricted Differential Revision

Event Timeline

floca triaged this task as High priority.Jul 15 2020, 10:04 PM
floca created this task.
floca moved this task from Backlog to Documentation on the MITK (v2021.02) board.

TLDR: Basically one needs to check if the plugin-id is the same as the page-identifier inside the *.dox-file. Looking at the Registration-plugins it is clear why these are not working.

I tried it with MITK 2018.4.2 and everything seems to work.
And I can confirm that the help for e.g. the log does not work with a recent develop branch.

I can fix this by doing the following inside the Plugins\org.blueberry.ui.qt.log\documentation\UserManual\blueberrylogview.dox:

-\page org_blueberry_ui_qt_log The Logging Plugin
+\page org_blueberry_views_logview The Logging Plugin

The new page name has the same identifier as the view in MITK\src\Plugins\org.blueberry.ui.qt.log\plugin.xml

<view
 id="org.blueberry.views.logview"

Looking at different html-filenames inside http://docs.mitk.org/nightly/PluginListPage.html I found out the following:
There is a mix-up between plugins / views / editors that are identified with org_mitk_gui_qt_ (e.g. DICOM Inspector) and org_mitk_views_ (e.g. The Image Navigator). Both help-pages can be shown inside the workbench pressing F1.
Looking at the relevant files I see:
Plugins\org.mitk.gui.qt.dicominspector\documentation\UserManual\Manual.dox:

\page org_mitk_gui_qt_dicominspector DICOM Inspector

and
src\Plugins\org.mitk.gui.qt.dicominspector\plugin.xml:

<view id="org.mitk.gui.qt.dicominspector"

or

src\Plugins\org.mitk.gui.qt.imagenavigator\documentation\UserManual\QmtikImageNavigator.dox:

\page org_mitk_views_imagenavigator The Image Navigator

and
src\Plugins\org.mitk.gui.qt.imagenavigator\plugin.xml:

<view id="org.mitk.views.imagenavigator"

So looking at a help-page that is not working (e.g. MITK DICOM Browser), we'll see the following:
\src\Plugins\org.mitk.gui.qt.dicom\documentation\UserManual\QmitkDicom.dox:

\page org_mitk_gui_qt_dicom The Dicom Plugin

and
src\Plugins\org.mitk.gui.qt.dicom\plugin.xml:

<editor
 id="org.mitk.editors.dicomeditor"

Changing the help-page identifier to

-\page org_mitk_gui_qt_dicom The Dicom Plugin
+\page org_mitk_editors_dicomeditor The Dicom Plugin

fixes the bug.

PS: There is no documentation-page for properties.

Cool. Thanks for the explanation. Did you also look into the identifiers in v2018.04.2? I wonder wether some identifiers were changed since then or the code that generates the link to the help page.

No I did not check that and currently I don't know why it worked before.

These are views that have non-standard view IDs (not beginning with "org.mitk.views"):

  • QmitkCESTNormalizeView.cpp
  • CommandLineModulesViewConstants.cpp
  • QmitkDicomInspectorView.cpp
  • FitGeneratorDemoView.cpp
  • GenericDataFittingView.cpp
  • ModelFitInspectorView.cpp
  • PerfusionCurveDescriptionParameterView.cpp
  • ConcentrationCurveConverterView.cpp
  • MRPerfusionView.cpp
  • PETDynamicView.cpp
  • PerfusionDataSimulationView.cpp
  • MatchPointBrowserConstants.cpp

When fixing these IDs make sure to also change them in the corresponding plugin.xml file and in any \page links in the documentation.

kislinsk added a revision: Restricted Differential Revision.Oct 9 2020, 10:58 AM

I am currently working on task https://phabricator.mitk.org/T28294 and have added an F1 help file for the standard display (and also a general remark how to use the F1 help for other plugins). The help is shown in the doxygen user MITK user manual, but the F1 help searches for
org.mitk.gui.qt.stdmultiwidgeteditor/bundle/org_mitk_editors_stdmultiwidgets.html and a blank page is shown consequently.

The page id in the plugin xml is:
id="org.mitk.editors.stdmultiwidget"

The page identifier is:
\page org_mitk_editors_stdmultiwidget The Standard Display

and I have added to the MITKPluginGeneralManualsList.dox
\li \subpage org_mitk_editors_stdmultiwidget

and to the MITKPluginManualsList.dox
<li> \ref org_mitk_editors_stdmultiwidget </li>

org.mitk.gui.qt.stdmultiwidgeteditor/bundle/org_mitk_editors_stdmultiwidgets.html and a blank page is shown consequently.

Is there realy an s before ".html"? So plural? All other appereances you mentioned were singular.

No, that was just a typo, there is no s. (couldn't copy and paste from the Workbench)

I am currently working on task https://phabricator.mitk.org/T28294 and have added an F1 help file for the standard display (and also a general remark how to use the F1 help for other plugins). The help is shown in the doxygen user MITK user manual, but the F1 help searches for
org.mitk.gui.qt.stdmultiwidgeteditor/bundle/org_mitk_editors_stdmultiwidgets.html and a blank page is shown consequently.

The page id in the plugin xml is:
id="org.mitk.editors.stdmultiwidget"

The page identifier is:
\page org_mitk_editors_stdmultiwidget The Standard Display

and I have added to the MITKPluginGeneralManualsList.dox
\li \subpage org_mitk_editors_stdmultiwidget

and to the MITKPluginManualsList.dox
<li> \ref org_mitk_editors_stdmultiwidget </li>

I looked into this and found the following, while compared how these IDs and documents are named in the DICOM Editor:

-The page id in the plugin xml is:
id="org.mitk.editors.dicombrowser"

The page identifier is:
\page org_mitk_editors_dicombrowser The Dicom Browser Plugin

and is added to the MITKPluginGeneralManualsList.dox
\li \subpage org_mitk_editors_dicombrowser

and to the MITKPluginManuals.list.dox
<li> \ref org_mitk_editors_dicombrowser </li>

So that seems to be equal. The file that is being opened is
org.mitk.gui.qt.dicombrowser/bundle/org_mitk_editors_dicombrowser.html
It exists inside src/MITK-build/Documentation/Doxygen/html/org_mitk_editors_dicombrowser.html

Since I can't see your changes I suggest to check the following:

  • did you actually check if the build documentation (html-file) exists in the docmentation output directory?

I checked and I found the file: \MITK-build\Documentation\Doxygen\html\org_mitk_editors_stdmultiwidget.html analogous to the DICOM browser file. When I open it, it looks like it should (not a blank page).

The F1 help seems to be looking for \MITK-build\Documentation\Doxygen\html\org_mitk_editors_stdmultiwidgeteditor.html

When I use the following, the F1 help works:

Change the id in the plugin xml to:
id="org.mitk.editors.stdmultiwidgeteditor"

Change the page identifier to:
\page org_mitk_editors_stdmultiwidgeteditor The Standard Display

Change the MITKPluginGeneralManualsList.dox to
\li \subpage org_mitk_editors_stdmultiwidgeteditor

and the MITKPluginManualsList.dox to:
<li> \ref org_mitk_editors_stdmultiwidgeteditor </li>

I just don't know how much trouble changing the plugin id might cause. I have found it to be called in
C:\MITK\Plugins\org.mitk.gui.qt.ext\src\QmitkExtWorkbenchWindowAdvisor.cpp
C:\MITK\Plugins\org.mitk.gui.qt.ext\src\QmitkOpenStdMultiWidgetEditorAction.cpp
C:\MITK\Plugins\org.mitk.gui.qt.stdmultiwidgeteditor\src\QmitkStdMultiWidgetEditor.cpp

and changed it there. But it might also be called in a different context which I could have missed.

The F1 help seems to be looking for \MITK-build\Documentation\Doxygen\html\org_mitk_editors_stdmultiwidgeteditor.html

Where do you see that?

While I think it is reasonable to change this accordingly I wonder why the F1 help is looking for
org_mitk_editors_stdmultiwidgeteditor
instead of
org_mitk_editors_stdmultiwidget

It should behave the same way as it does with the "editors_dicombrowser"

I took the liberty to dig into this topic as well and found the following:
There is a Qt-resource file in MITK\src\Plugins\org.mitk.gui.qt.stdmultiwidgeteditor\resources, which defines the qresource prefix. Changing the prefix from "/org.mitk.gui.qt.stdmultiwidgeteditor" to "/org.mitk.gui.qt.stdmultiwidget" fixed this problem for me (I thought) and correctly displayed the Standard Display Help.
However, if we change this, the prefix would be different to the plugin prefix.

Strangely what happened is after I changed it back to verify my findings, I was still able to see the help-page for the Standard Display. So I deleted the MITK-Build directory and build MITK again.
But now I'm not able to get the help page to be shown again - there is something strange going on here - and I'm not sure if anything had something to do with my changes to the Qt-resource file.

What I also did: I checked the "index.html" inside the documantation build directory, clicked on MITK User Manual --> MITK Plugin Manuals to verify that The Standard Display is listed there.

I tried using for the id
org_mitk_editors_stdmultiwidgeteditor
instead of
org_mitk_editors_stdmultiwidget

when I compared the code to

org_mitk_editors_dicombrowser (as you have suggested above).

The only differences I could find was the plugin name:
org.mitk.gui.qt.dicominspector vs org.mitk.gui.qt.stdmultiwidgeteditor
,the project name in the CMakeLists.txt (and all the names within the files) and the qresource prefix.

I have not found out, however, where exactly it is defined which help-file is opened. This fix was rather educated guessing and it worked. I was thinking about renaming the plugin and the class names and remove Editor at the end of all to be consistent with the dicombrowser. But that is A LOT of renaming compared to just changing the id name.

I totally understand the reasoning and I'm very much confused how everything works. I just hesitate to accept the review because this looks more like a workaround and we may have to dig deeper to understand the real problem here.

I played around with the different occurances of org.mitk.gui.qt.stdmultiwidgeteditor and org.mitk.gui.qt.stdmultiwidget and changing now both, the id and the page identifyer back to stdmultiwidget (removing editor) now works for me. In the build directory there is also now only the org_mitk_editors_stdmultiwidget.html file present (I deleted the org_mitk_editors_stdmultiwidgeteditor.html).
I am quite puzzled by this "strange magic" and don't know why this is working now even if was not working before.