cmd module should sort misc help topics

[samwyse]

BPO	23059
Nosy	@terryjreedy

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2014-12-15.21:02:49.077>
labels = ['type-feature', 'library']
title = 'cmd module should sort misc help topics'
updated_at = <Date 2014-12-19.21:45:41.470>
user = 'https://bugs.python.org/samwyse'

bugs.python.org fields:

activity = <Date 2014-12-19.21:45:41.470>
actor = 'terry.reedy'
assignee = 'none'
closed = False
closed_date = None
closer = None
components = ['Library (Lib)']
creation = <Date 2014-12-15.21:02:49.077>
creator = 'samwyse'
dependencies = []
files = []
hgrepos = []
issue_num = 23059
keywords = []
message_count = 2.0
messages = ['232680', '232948']
nosy_count = 2.0
nosy_names = ['terry.reedy', 'samwyse']
pr_nums = []
priority = 'normal'
resolution = None
stage = 'test needed'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue23059'
versions = ['Python 3.5']

[samwyse]

I've discovered that do_help method of cmd.Cmd prints the documented and undocumented commands in sorted order, but does not sort the miscellaneous topics. This would be an easy fix, just change "self.print_topics(self.misc_header, help.keys(),15,80)" to use "sorted(help.keys())".

[terryjreedy]

cmd.Cmd has a documented do_help(self, arg) method (written in 2000). If arg is '', it prints

1. Documented commands (do_x with help_x or do_x.__doc__ != ''), sorted
2. Other help topics (help_y with no do_y), unsorted
3. Undocumented commands (do_ without no help_x and no do_x.__doc__), sorted

The dict called 'help' (which should be a set, and might better be called 'topics') ends up with a member for each help_y topic without a do_y command. Not sorting the keys is at least a design bug. Leaving users aside, it makes do_help unpredictable and hard to test. Our test.test_cmd omits misc help topics. In verbose mode, it prints

Trying:
mycmd.do_help("")
Expecting:
<BLANKLINE>
Documented commands (type help <topic>):
========================================
add help

Undocumented commands:
======================
exit shell
<BLANKLINE>
ok

As near as I can tell, text_cmd would still pass if Misc topics were removed and never printed. Topics can only be added to the test above is they are dependably ordered (ie, sorted).

---
This '?' or 'help' case is also not properly documented, but should be. 3.4 cmd.__doc__ has this mishmash:

"With no arguments, it lists all topics with defined help_ functions, broken into up to three topics; documented commands, miscellaneous help topics, and undocumented commands."

3.4 doc says "With no argument, do_help() lists all available help topics (that is, all commands with corresponding help_*() methods or commands that have docstrings), and also lists any undocumented commands."