classification
Title: improve 'python -h' documentation for '-c'
Type: enhancement Stage: needs patch
Components: Documentation Versions: Python 3.4, Python 3.5, Python 2.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, r.david.murray, terry.reedy, vy0123
Priority: normal Keywords:

Created on 2014-10-27 04:39 by vy0123, last changed 2015-07-21 07:56 by ethan.furman.

Messages (10)
msg230059 - (view) Author: Van Ly (vy0123) * Date: 2014-10-27 04:39
I was looking at sys.argv from the reference guide. 

The font mix and change from v.2.7.5 to v.3.5.0a0 for sentence two of sys.argv (library/sys.html#module-sys) has made the second rendering of -c look capital when in fact it isn't.

--quote: from v.3.5.0a0 at library/sys.html#module-sys
If the command was executed using the -c command line option to the interpreter, argv[0] is set to the string '-c'.
--quote--

--suggest: improve second sentence of sys.argv (v.2.7.5, v.3.5.0a0)
Call the Python interpreter with the option, -c str, and the value of argv[0] is '-c'.
--suggest--

--suggest: improve 'python -h' output
-c str : feed in a string as program (terminates option list)
--suggest--
msg230091 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-10-27 19:12
I don't understand how your suggested change would affect the font size issue (nor do I really understand it as a sentence).

For your second suggestion (which is unrelated), how about instead:

 -c str   : interpret str as a program (terminates option list)

That would make the phrasing more consistent with the text for the other options.
msg230112 - (view) Author: Van Ly (vy0123) * Date: 2014-10-28 01:54
The font choice is a matter of style beyond me. I commented on it as I saw it. The second rendering looks in Capital relative to the first rendering. The problem wasn't there in v.2.7.5. In saying that, perhaps the information would be picked up by someone knowledgeable about the style sheet.

The focus of the suggestion is in the head line about the wording. I chose 'feed' because it would align with the theme of python and pickling. 'interpret' isn't as nice a picture word.
msg230114 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-10-28 02:37
Well, again, your suggested change for sys.argv is less optimal English.  The text as is seems fine to me.

'feed' is a term generally used when there is a source separate from the command (for example, we speak about a unix pipe feeding data from one command to the next).  A command line argument is not generally spoken about as being "fed" into the command.  And the relevance of pickle in this context completely escapes me.  Interpret programs is what Python does (Python is, after all, one of the class of programs referred to as an interpreter).

I thank you for your desire to improve the python documentation, but so far your suggestions have not been improvements.  It would probably be most helpful if you stick to pointing out places where you found the documentation confusing, explain your confusion as much as you can, and leave the writing of the improvements to the native English speakers.
msg230115 - (view) Author: Van Ly (vy0123) * Date: 2014-10-28 02:57
I don't know what you mean by optimal English. As is, the English is of the native English speaker's comfy couch guides speaking to guides kind rather than guides speaking to audience wanting to be guided by. 

The suggestion I offered is imperfect and can be improved or rejected. As communication, it is shorter than the original and applies the dry principle, don't repeat yourself. Command occurs twice and the native English speaker may feel they are different in their senses. As sequence was in another suggestion for enhancement (and not a bug). 

You have your point of view which is from the internal technical guts of this language. I am approaching the language from the fun of Monty Python and imagery of a python pickled in a jar. I have done a few tutorials and read code with this reference guide as I would use a dictionary to explain words in a passage. I expect in a final stage of approval an editor ensures correctness of English to whatever the standard is.
msg230116 - (view) Author: Van Ly (vy0123) * Date: 2014-10-28 03:04
> -c str   : interpret str as a program (terminates option list)

+1 (feed is shorter)
msg230413 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2014-10-31 23:47
On Win7, current Firefox, '-c' looks the same (definitely lowercase) for 2.7,8, 3.4.2, and 3.5.0a0,

I agree both that the sys.argv entry should be left as is and that 'interpret' is better than 'feed' or the current verbiage.  I think 'cmd' should be left as is because it is more descriptive than the generic 'str' and because the latter implies to me that cmd must always (as opposed to often) be quoted, which is not true.  The result would be
  -c cmd : interpret cmd as a program (terminates option list)

For 3.5, the current line is repository\Modules\main.c: 55.  If we agree on the above, I am willing to make the patch and push it.
msg230420 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-11-01 01:42
I am hard pressed to come up with anything useful you can do with the argument to -c without quoting it.
msg230425 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2014-11-01 02:17
Semi-useful: print a numeric expression without spaces
C:\Users\Terry>python -c print(2**50)
1125899906842624

Less useful: print a string expression without spaces or double quotes
C:\Users\Terry>python -c print('*'*50)
**************************************************
msg230426 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-11-01 02:35
Ah, I see.  Those don't work in my shell, since the '*' gets interpreted as a globbing character.  I didn't know it worked on Windows.
History
Date User Action Args
2015-07-21 07:56:20ethan.furmansetnosy: - ethan.furman
2014-11-01 02:35:32r.david.murraysetmessages: + msg230426
2014-11-01 02:17:36terry.reedysetmessages: + msg230425
2014-11-01 01:42:29r.david.murraysetmessages: + msg230420
2014-10-31 23:47:49terry.reedysetversions: + Python 3.4
nosy: + terry.reedy

messages: + msg230413

stage: needs patch
2014-10-28 03:04:22vy0123setmessages: + msg230116
2014-10-28 02:58:00vy0123setmessages: + msg230115
2014-10-28 02:37:46r.david.murraysetmessages: + msg230114
title: improve sys.argv, 'python -h' documentation -> improve 'python -h' documentation for '-c'
2014-10-28 01:54:48vy0123setmessages: + msg230112
2014-10-27 19:12:52r.david.murraysetnosy: + r.david.murray
messages: + msg230091
2014-10-27 13:31:15ethan.furmansetnosy: + ethan.furman
2014-10-27 04:39:46vy0123create