classification
Title: Improve description of cmd module
Type: Stage: needs patch
Components: Documentation Versions:
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, eric.araujo, r.david.murray, techtonik
Priority: low Keywords:

Created on 2012-01-26 14:27 by techtonik, last changed 2012-02-03 13:55 by eric.araujo.

Messages (5)
msg152010 - (view) Author: anatoly techtonik (techtonik) Date: 2012-01-26 14:27
http://docs.python.org/library/cmd.html#

Documentation for cmd module is poor to explain the value of this module to users. Intro is too abstract - phrase "simple framework for writing line-oriented command interpreters" doesn't mean much. Perhaps word "interactive" is missing?

So, there is no part explaining the what cmd does exactly (intro fails) and no part explaining the main principle - How exactly does this framework allows to do this in a simple way? (I guess reference part under 'Cmd objects -> Cmd.cmdloop([intro]) -> p[4]` does that, but it is not the place you'd usually expect this info.

At the very least what could be done is a link to Doug's tutorial http://www.doughellmann.com/PyMOTW/cmd/
msg152013 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2012-01-26 14:37
Well, since it isn't limited to interactive use, I don't think 'interactive' is missing.

MOTW links are a more global issue that was discussion on python-dev (I forget the outcome, but I think it was "no").

I don't see anything that needs done here, but if you want to suggest a patch for consideration, feel free.
msg152014 - (view) Author: anatoly techtonik (techtonik) Date: 2012-01-26 14:40
What do you mean by saying it is not limited for interactive use? I thought it is used to provide command prompt for typing commands. What other use cases does it support?
msg152017 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2012-01-26 15:15
You can feed a cmd driven interface from stdin or via cmd.onecmd.

However, I agree that the intended and primary use case is interactive.  There wouldn't be much point in using cmd if the primary intent of your program wasn't interactive.
msg152510 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-02-03 13:54
+1 to expanding the introduction.  Do you have a phrasing suggestion?

> MOTW links are a more global issue that was discussion on python-dev (I forget the outcome,
> but I think it was "no").
IIRC it was on python-ideas, and (among other criticisms about licensing, site reliability, etc.) the strongest opinion against adding links was Alexander’s, who reviewed the PyMOTW page for datetime and was not satisfied.  So the discussion ruled out systematic addition of links for all modules, but I think that as usual a core dev is free to add a link to an external resource if they think it is useful.
History
Date User Action Args
2012-02-03 13:55:13eric.araujosettitle: cmd: no user documentation -> Improve description of cmd module
resolution: works for me ->
stage: needs patch
2012-02-03 13:54:41eric.araujosetnosy: + eric.araujo
messages: + msg152510
2012-01-26 15:15:39r.david.murraysetmessages: + msg152017
2012-01-26 14:40:43techtoniksetstatus: pending -> open

messages: + msg152014
2012-01-26 14:37:51r.david.murraysetstatus: open -> pending
priority: normal -> low

nosy: + r.david.murray
messages: + msg152013

resolution: works for me
2012-01-26 14:27:57techtonikcreate