Context help by ThomasStivers · Pull Request #8355 · nvaccess/nvda

ThomasStivers · 2018-06-01T10:36:00Z

Link to issue number:

Summary of the issue:

Add context sensitive help referencing the user guide to settings dialogs, panels, and controls.

Description of how this pull request fixes the issue:

Using anchors previously added to the user guide this patch adds helpIds dictionaries to panels and dialogs referencing user guide sections. Pressing F1 or the help button will open an HTML fiewer to the appropriate section of the user guide.

Testing performed:

This code is very much alpha. It works as expected for some controls, but I am new to working on NVDA code, so I am seeking suggestions and assistance from the community.

Known issues with pull request:

Help is not yet implemented across all controls.

Change log entry:

New features

…by context help.

* Added named anchors to the user guide which can be linked to from help events. * Added Help button to all settings dialogs which opens help for all controls in that dialog. * Dynamically generated dictionary of control ids and anchor names including controls in any open settings dialog. This work may eventually be separated into its own module so it can be used in all NVDA generated dialogs.

…s#7762.

…ialog.

…ogs.

…tification dialogs.

…and NewProfileDialog.

…ed to the MultiCategorySettingsDialog.

josephsl · 2018-06-01T14:25:34Z

CC @derekriemer. This is actually a subtle duplicate of an issue from years ago requesting context-sensitive help on all objects, not just NVDA settings. Hopefully this should serve as a test code for that one. Thanks.

derekriemer

This looks great. A few comments here.

Also, can you list what still needs help? I am a bit worried about the ease of forgetting to include help, is there a way we could abstract help more so it is provided easier to any new NVDA dialog? I'm afraid not, but we might want to discuss it.

derekriemer · 2018-06-04T05:12:28Z

 		ProfilesDialog._instance = self
 		# Translators: The title of the Configuration Profiles dialog.
 		super(ProfilesDialog, self).__init__(parent, title=_("Configuration Profiles"))
+		self.helpIds[self.GetId()] = "ConfigurationProfiles"


Just a thought: are these translated?

The anchors in the user guide are not translated, but the help text which loads should be in the users language.

derekriemer · 2018-06-04T05:16:12Z

@@ -1,22 +1,22 @@
-%!Target: html
+%!Target: xhtml


Why do we need to change the format?

This is not necessary at this point, but I had been working on parsing the user guide as XML instead of treating it as plain text.

LeonarddeR

For code you call alpha, I think you did a pretty good job here.

I think it would be good to have some discussion about the HTML parsing. It looks like you decided to use the xml module at some point, than switched to read the user guide html line by line. The latter approach seems a bit error prone to me.

In any case, it might be good to cache the contents of the user guide file after the first load. Something like this, note that the variable names are indicative:

lines = ""
def getCachedFileContents(file):
    global lines
    if lines:
        return lines
	try:
		with open(helpFile) as help:
			lines = help.readlines()
	except:
		lines = ""
 return lines

LeonarddeR · 2018-06-07T18:21:07Z

 def txt2tags_actionFunc(target,source,env):
 	import txt2tags
-	txt2tags.exec_command_line([str(source[0])])
+	txt2tags.exec_command_line(["--outfile", str(source[0])[:-3] + "html", str(source[0])])


Could you elaborate on why you made this change?

LeonarddeR · 2018-06-07T18:27:54Z

+from logHandler import log
+from xml.etree import ElementTree
+
+class Help():


This class doesn't seem to be used anywhere. Note that class names usually start with an upper case letter and inherrit from object.

LeonarddeR · 2018-06-07T18:28:45Z

@@ -0,0 +1,60 @@
+# -*- coding: UTF-8 -*-


I think it makes sense to put this in the gui module, i.e. gui/contextHelp.py

* Use lxml.html to parse the user guide instead of working with text offsets directly. * Moved contextHelp into the gui module. * Removed unnecessary help class from contextHelp.

* Add dependency on lxml module for iterating through sibling elements in the user guide. * Ensure that proper help ids are added for the category list and help button. * Update helpIds from new panels do not replace the old list. * Some anchors were changed upstream, so updated this PR to match.

…ettingsPanel.

derekriemer · 2018-06-21T09:26:06Z

@ThomasStivers looks like CI unit tests are failing.

ThomasStivers · 2018-06-21T09:41:12Z

Yes it is failing a test.

py scons.py tests %sconsArgs%
scons: Reading SConscript files ...
scons: done reading SConscript files.
scons: Building targets ...
C:\Python27\python.exe -m unittest discover tests.unit -t .
Traceback (most recent call last):
File "C:\Python27\lib\runpy.py", line 174, in _run_module_as_main
"main", fname, loader, pkg_name)
File "C:\Python27\lib\runpy.py", line 72, in run_code
exec code in run_globals
File "C:\Python27\lib\unittest_main.py", line 12, in
main(module=None)
File "C:\Python27\lib\unittest\main.py", line 94, in init
self.parseArgs(argv)
File "C:\Python27\lib\unittest\main.py", line 113, in parseArgs
self._do_discovery(argv[2:])
File "C:\Python27\lib\unittest\main.py", line 214, in _do_discovery
self.test = loader.discover(start_dir, pattern, top_level_dir)
File "C:\Python27\lib\unittest\loader.py", line 204, in discover
raise ImportError('Start directory is not importable: %r' % start_dir)
ImportError: Start directory is not importable: 'tests.unit'
scons: *** [tests\unit] Error 1
scons: building terminated because of errors.
Command exited with code 2

I am not sure what %sconsArgs% contains, but when I run python scons.py tests locally it completes successfully.

I needed to use the lxml package which I have installed locally with pip install lxml, but i do not know how to make it a dependency. I have lxml included as a git submodule, but I am looking for pointers on how to build it when NVDA builds. That is my only guess to what is causing the CI build to fail.

feerrenrut · 2018-08-06T01:36:37Z

Rather than build lxml, create a new repo holding the prebuilt dependency. You can use pip install -t ./ lxml (while in an appropriate directory). Add a new submodule to NVDA pointing at this new repo.

Perhaps we don't need the lxml dependency. Splitting up the userguide file programmatically might cause maintenance issues in the future. There has been some talk of using different formats for these files.

The simplest approach is to load the whole user guide, presented (using a html viewer) with the target url set to point to the anchor.

An alternative approach, is to break up the userGuide.t2t into multiple files. One per section. The user guide can then be constructed by recombining these sections. Some investigation will be required on how to achieve this. My first thought would be to programatically concatenate each of the sections, and generate the html from those combined, but this leads to ordering issues.

Another way would be to convert the userGuide.t2t into a template file, which uses the t2t include command to pull in each of the subsections.
The help ID's would match the name of the subsection file (or perhaps use a mapping file), and then each subsection could be displayed directly.

dpy013 · 2019-05-22T01:52:06Z

This PR has the following error during the build
Failure: AppVeyor build failed
Can you fix it?
thank?

feerrenrut · 2020-04-01T09:41:41Z

We are interested in getting this feature merged, is anyone willing to take on the remaining issues:

Fixing conflicts / Python 3 compatibility
Looking into solving issues (building lxml) described in Context help #8355 (comment)
Looking at whether the solutions (just open whole file at the anchor or split up source documents) described are appropriate: Context help #8355 (comment)

josephsl · 2020-05-06T06:05:26Z

Hi,

I'll try at least fixing possible conflicts and Python 3 compatibility.

Thanks.

josephsl · 2020-05-06T06:45:02Z

Hi,

Dear me... Conflict resolution will involve not only checking Python 3 syntax gotchas, but also wxPython 4 changes, imports, copyright header, coding style updates... As much as I wish to continue to try and resolve hundreds of potential conflicts, it will take time, risking other life priorities and mental health (and I'm not really in a position to do it in the near term).

I propose three possibilities for this PR:

Recommend starting from scratch: this is perhaps the easiest yet most difficult, most painful possibility, as it'll involve recreating what is essentially an almost complete product.
Request community help: this will involve folks looking at what's going on and try to make sense of what needs to be done.
Ask @ThomasStivers to respond to feedback: this depends on willingness from him to take a look at feedback and doing something about them, which I imagine would be painful at first.

I think a combination of options 2 and 3 would be the best path forward: letting the community help out in essentially making a "phoenix" out of it, with Thomas providing guidance. As of now, I'm giving up.

Thanks.

feerrenrut · 2020-05-06T09:38:36Z

Given the lack of updates, I would consider this PR abandoned, and that is fine. I think this would be a valuable feature. I think the most important thing is to validate this approach, the biggest outstanding unknown is the use of lxml. To progress this work, I would suggest taking just the new file source/gui/contextHelp.py and the changes from one file that maps a help topic eg: source/speechViewer.py and then resolve the issues with lxml. I'm going to convert this PR to a draft.

josephsl · 2020-05-06T18:29:32Z

Hi,

Looking at small things at the moment (speech viewer):

we need Python 3.7 specific lxml module, as the one Thomas used was optimized for Python 2.7+Cython. Even then, we need to consider str/bytes conversion and what not, along with converting context help module to Python 3 (along with dropping hints for Python 3.8).

Therefore, I propose the following:

Experiment with Python 3.7 version of lxml (4.5.0).
Convert context help module to Python 3.
Test it on a small scale (speech viewer is the best candidate for it).
Expand this to other controls.
Investigate possible route for combining with INSERT+F1 help message capability #2699 (after this PR is merged) so the dedicated context-sensitive help gesture can work across various scenarios (NVDA objects, app modules, NVDA controls and others).
Investigate a possible route for add-ons to participate in providing help in their interfaces (later).

Thanks.

feerrenrut · 2020-08-03T19:53:38Z

Superseded by #11456

Fixes #7757 Fixes #8354 Supersedes PR #8355 Add initial support for opening the user guide at a particular section based on the context when the user presses F1 (in NVDA dialogs). For the sake of simplicity, this is done by opening the user guide in the browser. Unfortunately, this results in a lot of unnecessary verbosity. However, this is still quicker for the user than manually opening the user guide separately (also in a browser) and navigating to the chosen section manually. Co-authored-by: ThomasStivers <thomas.stivers@gmail.com> Co-authored-by: Leonard de Ruijter <leonardder@users.noreply.github.com>

Fixes nvaccess#7757 Fixes nvaccess#8354 Supersedes PR nvaccess#8355 Add initial support for opening the user guide at a particular section based on the context when the user presses F1 (in NVDA dialogs). For the sake of simplicity, this is done by opening the user guide in the browser. Unfortunately, this results in a lot of unnecessary verbosity. However, this is still quicker for the user than manually opening the user guide separately (also in a browser) and navigating to the chosen section manually. Co-authored-by: ThomasStivers <thomas.stivers@gmail.com> Co-authored-by: Leonard de Ruijter <leonardder@users.noreply.github.com>

ThomasStivers added 21 commits November 15, 2017 05:34

Added explicit anchors to section headings in the user guide for use …

5aee2e0

…by context help.

Beginning work on context sensitive help for preferences dialogs.

77c7308

continued content sensitive help work.

f5d9759

Got context help working. Added more anchors to the user guide.

617c004

Merge remote-tracking branch 'nv/master' into f1Help

75274e8

Continuing work on context sensitive help separate from issue nvacces…

13f92b1

…s#7762.

Added context help to some classes that are not children of SettingsD…

f2f1e24

…ialog.

Merge branch 'master' into contextHelp

67258a2

Replaced wrapper function with a lambda.

a0e8ef7

Added context help to add-ons manager and configuration profiles dial…

63ddd8c

…ogs.

Added context help to the elements list, speech viewer, and update no…

63d17be

…tification dialogs.

Merge branch 'master' into contextHelp

17243c4

Update what's new

69bb21e

updated showHelp function and fixed syntax errors in AddSymbolDialog …

1626552

…and NewProfileDialog.

Merge branch 'master' into contextHelp

8da7019

Added help to TouchInteractionDialog.

12c039d

Merge branch 'master' into contextHelp

1682ff0

Merge branch 'master' into contextHelp

4cc4d44

Added helpIds to SettingsPanel and made helpIds for the panels be add…

ac5de0e

…ed to the MultiCategorySettingsDialog.

Merge branch 'master' into contextHelp

e2b0a48

derekriemer reviewed Jun 4, 2018

View reviewed changes

LeonarddeR reviewed Jun 7, 2018

View reviewed changes

ThomasStivers added 5 commits June 13, 2018 05:32

Updated as suggested in review comments.

7fdb359

* Use lxml.html to parse the user guide instead of working with text offsets directly. * Moved contextHelp into the gui module. * Removed unnecessary help class from contextHelp.

Added lxml dependency as a git submodule.

d902dd3

Merge branch 'master' into contextHelp

17c43e9

Added missing translator comment and a helpIds entry for the BrailleS…

61b0e09

…ettingsPanel.

LeonarddeR added the AfterPython3Transition label Apr 24, 2019

feerrenrut removed the AfterPython3Transition label May 8, 2019

feerrenrut added the feature label Apr 8, 2020

feerrenrut marked this pull request as draft May 6, 2020 09:38

feerrenrut added Abandoned requested reports or updates are missing since more than 1 year, author or users are not available. component/user-documentation labels May 6, 2020

feerrenrut self-assigned this Jul 3, 2020

feerrenrut mentioned this pull request Aug 3, 2020

I7757 context help #11456

Merged

feerrenrut closed this Aug 3, 2020

CyrilleB79 removed the Abandoned requested reports or updates are missing since more than 1 year, author or users are not available. label Jun 18, 2024

Uh oh!

Conversation

ThomasStivers commented Jun 1, 2018

Link to issue number:

Summary of the issue:

Description of how this pull request fixes the issue:

Testing performed:

Known issues with pull request:

Change log entry:

Uh oh!

josephsl commented Jun 1, 2018 via email • edited by feerrenrut Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

derekriemer left a comment

Choose a reason for hiding this comment

Uh oh!

derekriemer Jun 4, 2018

Choose a reason for hiding this comment

Uh oh!

ThomasStivers Jun 4, 2018

Choose a reason for hiding this comment

Uh oh!

derekriemer Jun 4, 2018

Choose a reason for hiding this comment

Uh oh!

ThomasStivers Jun 4, 2018

Choose a reason for hiding this comment

Uh oh!

LeonarddeR left a comment

Choose a reason for hiding this comment

Uh oh!

LeonarddeR Jun 7, 2018

Choose a reason for hiding this comment

Uh oh!

LeonarddeR Jun 7, 2018

Choose a reason for hiding this comment

Uh oh!

LeonarddeR Jun 7, 2018

Choose a reason for hiding this comment

Uh oh!

derekriemer commented Jun 21, 2018

Uh oh!

ThomasStivers commented Jun 21, 2018

Uh oh!

feerrenrut commented Aug 6, 2018

Uh oh!

dpy013 commented May 22, 2019

Uh oh!

feerrenrut commented Apr 1, 2020

Uh oh!

josephsl commented May 6, 2020

Uh oh!

josephsl commented May 6, 2020

Uh oh!

feerrenrut commented May 6, 2020

Uh oh!

josephsl commented May 6, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

feerrenrut commented Aug 3, 2020

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

josephsl commented Jun 1, 2018 via email •

edited by feerrenrut

Loading

josephsl commented May 6, 2020 •

edited

Loading