[issue17158] help() module searcher text improvement

[Terry J. Reedy]

Changes by Terry J. Reedy :


--
assignee:  -> terry.reedy

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17158] help() module searcher text improvement

[Roundup Robot]

Roundup Robot added the comment:

New changeset 4f84fe5a997b by Terry Jan Reedy in branch 'default':
Closes #17158: Add 'symbols' to help() welcome message; clarify 'modules spam'
http://hg.python.org/cpython/rev/4f84fe5a997b

--
nosy: +python-dev
resolution:  -> fixed
stage: patch review -> committed/rejected
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17158] help() module searcher text improvement

[Senthil Kumaran]

Senthil Kumaran added the comment:

The patch looks good to me. This change is helpful and definitely an 
improvement over the existing text. Please go ahead with committing it, Terry. 
Thanks.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17158] help() module searcher text improvement

[Terry J. Reedy]

Terry J. Reedy added the comment:

Looking further at the pydoc code, I see that "Here is a list. Enter any listed 
item to get more help", with both sentences printed before the list, is normal. 
Having a post-list prompt for the list of all modules is the exception. So I 
would no longer make the change proposed in my first patch and would instead 
look to rewording along the line Senthil suggested.

listmodules(key) calls apropos(key) after printing the header. That function in 
turn creates a ModuleScanner and calls .run with a callback. So making the 
prompt conditional on whether or not anything is found would require 
modification of ModuleScanner.run(), apropos(), and listscanner(). As indicated 
by my first patch, I agree with Senthil that it is not worth the effort when a 
better prompt should do.

A deeper problem is this: the prompt "Enter any listed item to get more help." 
is only valid if one asks for the list in help mode, at the "help> " prompt. If 
one asks for the list at the normal interpreter ">>> " prompt with 
"help('xxx')", as described in the original post, then entering the name of the 
listed item at the next ">>> " prompt is wrong. One should instead wrap the 
text with "help('" and "')", or enter help() mode first. However, I have not 
yet discovered a way to detect the context of the list request so that the 
prompt could be modified.

The Welcome text could also use a couple of changes.
1. It does not mention the new symbol help.
"To get a list of available modules, keywords, or topics, type "modules", 
"keywords", or "topics".
should include symbols and "symbols".
2. This: '''to list the modules whose summaries contain a given word
such as "spam",'''
is more accurately written as this:
'''to list the modules whose name or summary contain a
given string such as "spam",'''

Attached is a second patch with the easy fixes, without touching the 
context-prompt issue.

A possible commit message: Add 'symbols' to help welcome message; clarify 
'modules spam' messages.

--
Added file: http://bugs.python.org/file29037/Issue17158-b.diff

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17158] help() module searcher text improvement

[Senthil Kumaran]

Senthil Kumaran added the comment:

You will stumble on that message, only if you give help("module
") and note that  could be any module in the
PYTHONPATH.
We can change to show the text only if the module is a valid module,
but I think, it is costly do that computation for help text. A better
approach would be:
Modules matching the keyword: 

The output can be a list or None.

If you will like to work on a patch, the changes will be in listmodule
function in Lib/pydoc.py

--
nosy: +orsenthil
title: help() module searcher text is misleading -> help() module searcher text 
improvement

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue17158] help() module searcher text improvement

[Ramchandra Apte]

New submission from Ramchandra Apte:

help("modules spam") prints out "Here is a list of matching modules.  Enter any 
module name to get more help." before it has even found the modules. This gives 
the impression that it has found the modules yet it hasn't printed the modules 
yet. I would suggest that it prints "Searching for the matching modules..." 
without the newline and then once the matching modules have been found prints 
"done." (End result will have "Searching for the matchine modules... done." 
Then it should print "Here is a list of matching modules. Enter any ..."

--
components: Interpreter Core
messages: 181671
nosy: ramchandra.apte
priority: normal
severity: normal
status: open
title: help() module searcher text improvement
type: enhancement
versions: Python 3.3, Python 3.4

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com