[issue13875] cmd: no user documentation
New submission from anatoly techtonik <techtonik@gmail.com>: 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/ ---------- assignee: docs@python components: Documentation messages: 152010 nosy: docs@python, techtonik priority: normal severity: normal status: open title: cmd: no user documentation _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13875> _______________________________________
R. David Murray <rdmurray@bitdance.com> added the comment: 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. ---------- nosy: +r.david.murray priority: normal -> low resolution: -> works for me status: open -> pending _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13875> _______________________________________
anatoly techtonik <techtonik@gmail.com> added the comment: 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? ---------- status: pending -> open _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13875> _______________________________________
R. David Murray <rdmurray@bitdance.com> added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13875> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: +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.
---------- nosy: +eric.araujo _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13875> _______________________________________
Changes by Éric Araujo <merwok@netwok.org>: ---------- resolution: works for me -> stage: -> needs patch title: cmd: no user documentation -> Improve description of cmd module _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue13875> _______________________________________
Change by Irit Katriel <iritkatriel@yahoo.com>: ---------- versions: +Python 3.10, Python 3.8, Python 3.9 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue13875> _______________________________________
participants (4)
-
anatoly techtonik -
Irit Katriel
-
R. David Murray
-
Éric Araujo