Repository: nvaccess/nvda

Issue:
Odd and possibly confusing key describer message for tab in Word

### Steps to reproduce:

1. Open a document in MS Word.
2. Press NVDA+1 to enter key describer mode.
3. Press tab.

### Actual behavior:

The following message is spoken:

>		A script for the tab key which:
>		* if in a table, announces the newly selected cell or new cell where the caret is, or 
>		* If not in a table, announces the distance of the caret from the left edge of the document, and any remaining text on that line.

### Expected behavior:

1. I would not expect the help message  to start with "A script for the tab key which:". Since every key calls a script of some sort, this is redundant. Further, since it is not usually spoken as such, it could potentially confuse users.
2. Shouldn't the help message mention that the key actually inserts a tab? It is unusual for a text entry key to be overloaded like this, so it seems to me it warrants further clarity about what happens when you press it.
3. And what's with "and any remaining text on that line."? more on that below.

### System configuration

Windows 10, 1903 64bit
NVDA installed or run from installer.
Multiple versions from 2019.1.1 through nvda_snapshot_threshold_py3_staging-18066,131ed840

#### Name and version of other software in use when reproducing the issue:

Microsoft Word 2019

### Suggested Change

I suggest altering the help message to something more along these lines:

> Inserts a tab, and announces the distance of the caret from the left edge of the document, and any remaining text on that line. If in a table, announces the newly selected cell or new cell where the caret is.

#### Further Thoughts

The above not withstanding, I consider this statement to be less than perfectly clear:

> announces the distance of the caret from the left edge of the document, and any remaining text on that line. 

Does it mean that it announces the remaining text on that line? If so, it doesn't.
In fact, it announces exactly the same thing, irrespective of whether there is text to the right of the entered tab.


Discussion:
And now, for speculation: I suspect that this was not supposed to be a help 
message at all, but was intended as in-line Python documentation. Both from the 
way it's written, and the two tabs preceding each line.

Regardless though, it is the help message, and as such in my opinion it needs 
some help.


Resolving patch:
diff --git a/source/NVDAObjects/window/winword.py b/source/NVDAObjects/window/winword.py
--- a/source/NVDAObjects/window/winword.py
+++ b/source/NVDAObjects/window/winword.py
@@ -17,7 +17,7 @@
 import sayAllHandler
 import eventHandler
 import braille
-import scriptHandler
+from scriptHandler import script
 import languageHandler
 import ui
 import NVDAHelper
@@ -1378,6 +1378,7 @@ def script_toggleChangeTracking(self, gesture):
 			# Translators: a message when toggling change tracking in Microsoft word
 			ui.message(_("Change tracking off"))
 	
+	@script(gestures=["kb:tab", "kb:shift+tab"])
 	def script_tab(self,gesture):
 		"""
 		A script for the tab key which:
@@ -1483,8 +1484,6 @@ def initOverlayClass(self):
 		"kb:control+2":"changeLineSpacing",
 		"kb:control+5":"changeLineSpacing",
 		"kb:control+shift+e": "toggleChangeTracking",
-		"kb:tab": "tab",
-		"kb:shift+tab": "tab",
 		"kb:control+pageUp": "caret_moveByLine",
 		"kb:control+pageDown": "caret_moveByLine",
 	}


Test patch: