[issue11176] give more meaningful argument names in argparse documentation

New submission from Steven Bethard <steven.bethard@gmail.com>: Suggestion from a personal email: I personally am not keen on the foo/bar/baz examples. I know that you're trying to be generic but IMO it would be much easier to understand if you used meaningful names. Also, I think that the very first example you give (which does use meaningful names:-) is too clever. I'd suggest using something simpler: in fact I'd use exactly the same example that optparse uses (--file && --quiet) since that is easy to understand and relate to straight away, and maybe add a --line option that takes a list of ints (ostensibly line numbers of lines to extract from the file) if you want to show that argparse leaves optparse in the dust. And you can always show how to get actual file objects later on. ---------- assignee: docs@python components: Documentation messages: 128302 nosy: bethard, docs@python priority: normal severity: normal stage: needs patch status: open title: give more meaningful argument names in argparse documentation type: feature request versions: Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

Westley Martínez <anikom15@gmail.com> added the comment: I agree; it's too artsy. I'll see if I can come up with a relevant and clever alternative. ---------- nosy: +anikom15 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

Éric Araujo <merwok@netwok.org> added the comment: Hi Westley! Do you still have time to work on this? ---------- keywords: +easy nosy: +eric.araujo versions: +Python 2.7, Python 3.2 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

Westley Martínez <anikom15@gmail.com> added the comment: I worked on this some time ago; the problem was the size of the documentation, i.e. it was difficult to stay consistent. Do I have time for this? Yes, but I wouldn't get it done anytime soon, and the results could be anywhere from good to bad. As it stands, the documentation is fairly good, so I don't think it's imperative to fix it. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

Éric Araujo <merwok@netwok.org> added the comment:
---------- assignee: docs@python -> eric.araujo _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

Changes by Adam Woodbeck <adam.woodbeck@gmail.com>: ---------- nosy: +adam.woodbeck _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

Changes by Marc Sibson <sibson@gmail.com>: ---------- nosy: +marcs _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

Changes by Tshepang Lekhonkhobe <tshepang@gmail.com>: ---------- nosy: +tshepang _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

Greg Roodt <groodt@gmail.com> added the comment: Is this still an issue? If so, I've created a simpler first example as suggested below. If we decide these docs still need a bit more work, I can also continue to provide better examples than the "foo bar" ones. ---------- keywords: +patch nosy: +groodt Added file: http://bugs.python.org/file26284/argparse_simple_example.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

Éric Araujo <merwok@netwok.org> added the comment: Yep, this is still open. Thanks for the patch, I did a review (if you did not get a mail, follow the link in the list of files). ---------- assignee: eric.araujo -> nosy: +ezio.melotti, sandro.tosi _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

David Lam <d@dlam.me> added the comment: haha wow, I was working on this bug too! maybe we can work on the final patch together I got through about 2/3's of the docs, so I thought it might help to upload what I got so far. I basically just made stuff up so I'm totally winning to change anything (or everything) I made a little effort to make the examples mildly amusing, since novelty sorta helps in retention. So one of the recurring examples I used involves that of a pizza-making-program... hopefully this helps in some way! ---------- nosy: +dlam Added file: http://bugs.python.org/file26325/issue11165-doc-fix-up-to-section-15.4.4.dif... _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

Greg Roodt <groodt@gmail.com> added the comment: Hi David Ok, I like the idea of working on a solution together. I like your idea of the pizza-making more than the current "foo bar" examples. Should we collaborate outside of the bug tracker? Greg On 9 July 2012 07:11, David Lam <report@bugs.python.org> wrote:
---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

Greg Roodt <groodt@gmail.com> added the comment: I've made the minor edits required after the review to my simplification of the first example. David, perhaps we combine our efforts? Use my simple first example to explain the very basics, then continue the explanation with the pizza example? Im happy either way, I quite like your example using the system dictionary. ---------- Added file: http://bugs.python.org/file26334/1176_minor_edits.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

David Lam <d@dlam.me> added the comment: yup yup, go for it ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

Steven Bethard <steven.bethard@gmail.com> added the comment: Thanks for working on this! I think keeping the first example as simple is possible is probably a good idea. And I didn't have time to read through the whole patch, but as far as I went, the pizza examples looked great. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

David Lam added the comment: here's a patch that covers all but one of the foo/bar/baz examples it also has fixes for the sample code near the beginning from the review Ezio did the one example I didn't do was the "Arguments containing -" part. I guess it felt like changing the names in that example would distract from what it was trying to illustrate there Anyways, I tried to proofread it so hopefully it reads okay, enjoy enjoy ^^ ---------- Added file: http://bugs.python.org/file27030/issue11176.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

Chris Jerdonek added the comment: Also see this e-mail to docs@: http://mail.python.org/pipermail/docs/2012-December/012028.html
---------- nosy: +chris.jerdonek _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

Chris Jerdonek added the comment: Issue 16933 improved the "choices" examples. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

Westley Martínez added the comment: I've skimmed through the patches. Good job kids. This is much better than it was before. No more of that silly command-line calculator or the foobar nonsense that sounds drier than the POSIX standard. Is there anything else that needs to be done? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

Georg Brandl added the comment:
Also see this e-mail to docs@: http://mail.python.org/pipermail/docs/2012-December/012028.html
No, please don't see this e-mail. It's not worth it. The poster clearly has no clue whatsoever about either a) common placeholders, or b) manners. I don't want to claim that foo/bar/etc. are superior to a well-thought-out example (which takes time to come up with), but they are certainly better than no example at all. ---------- nosy: +georg.brandl _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

Mark Lawrence added the comment: If we've got some meaningful changes can we please get them committed. However I'd like to state that with over 4000 issues open we've got better things to do than change docs because somebody doesn't like the use of foo, bar and baz in examples. ---------- nosy: +BreamoreBoy _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

Steve added the comment: I came here to file a bug against the argparse documentation because reading through the documentation I didn't realize a good usecase for the `epilog` argument to the `ArgumentParser()` class until I started noticing that some commandline tools end with examples of usage. I found this bug and so thought it would be better to just leave a comment here instead. I glaced through the submitted patches and noticed that the pizza making example has `epilog="Remember: select a good combination to ensure maximum tastiness` ...which while good, still might not immediately convey the usefulness of the epilog parameter (just IMHO). I think, the example would be better served by something like:
Of course this example would then also require passing a formatter_class argument to handle the wrapping ...but in essence the point of my comment is that the examples might be more useful if a 'real-world' usage is demonstrated. ---------- nosy: +lonetwin _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

Change by Mark Lawrence <breamoreboy@gmail.com>: ---------- nosy: -BreamoreBoy _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue11176> _______________________________________

Change by Irit Katriel <iritkatriel@yahoo.com>: ---------- title: give more meaningful argument names in argparse documentation -> [doc] give more meaningful argument names in argparse documentation versions: +Python 3.10, Python 3.8, Python 3.9 -Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue11176> _______________________________________

Westley Martínez <anikom15@gmail.com> added the comment: I agree; it's too artsy. I'll see if I can come up with a relevant and clever alternative. ---------- nosy: +anikom15 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

Éric Araujo <merwok@netwok.org> added the comment: Hi Westley! Do you still have time to work on this? ---------- keywords: +easy nosy: +eric.araujo versions: +Python 2.7, Python 3.2 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

Westley Martínez <anikom15@gmail.com> added the comment: I worked on this some time ago; the problem was the size of the documentation, i.e. it was difficult to stay consistent. Do I have time for this? Yes, but I wouldn't get it done anytime soon, and the results could be anywhere from good to bad. As it stands, the documentation is fairly good, so I don't think it's imperative to fix it. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

Éric Araujo <merwok@netwok.org> added the comment:
---------- assignee: docs@python -> eric.araujo _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

Changes by Adam Woodbeck <adam.woodbeck@gmail.com>: ---------- nosy: +adam.woodbeck _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

Changes by Marc Sibson <sibson@gmail.com>: ---------- nosy: +marcs _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

Changes by Tshepang Lekhonkhobe <tshepang@gmail.com>: ---------- nosy: +tshepang _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

Greg Roodt <groodt@gmail.com> added the comment: Is this still an issue? If so, I've created a simpler first example as suggested below. If we decide these docs still need a bit more work, I can also continue to provide better examples than the "foo bar" ones. ---------- keywords: +patch nosy: +groodt Added file: http://bugs.python.org/file26284/argparse_simple_example.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

Éric Araujo <merwok@netwok.org> added the comment: Yep, this is still open. Thanks for the patch, I did a review (if you did not get a mail, follow the link in the list of files). ---------- assignee: eric.araujo -> nosy: +ezio.melotti, sandro.tosi _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

David Lam <d@dlam.me> added the comment: haha wow, I was working on this bug too! maybe we can work on the final patch together I got through about 2/3's of the docs, so I thought it might help to upload what I got so far. I basically just made stuff up so I'm totally winning to change anything (or everything) I made a little effort to make the examples mildly amusing, since novelty sorta helps in retention. So one of the recurring examples I used involves that of a pizza-making-program... hopefully this helps in some way! ---------- nosy: +dlam Added file: http://bugs.python.org/file26325/issue11165-doc-fix-up-to-section-15.4.4.dif... _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

Greg Roodt <groodt@gmail.com> added the comment: Hi David Ok, I like the idea of working on a solution together. I like your idea of the pizza-making more than the current "foo bar" examples. Should we collaborate outside of the bug tracker? Greg On 9 July 2012 07:11, David Lam <report@bugs.python.org> wrote:
---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

Greg Roodt <groodt@gmail.com> added the comment: I've made the minor edits required after the review to my simplification of the first example. David, perhaps we combine our efforts? Use my simple first example to explain the very basics, then continue the explanation with the pizza example? Im happy either way, I quite like your example using the system dictionary. ---------- Added file: http://bugs.python.org/file26334/1176_minor_edits.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

David Lam <d@dlam.me> added the comment: yup yup, go for it ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

Steven Bethard <steven.bethard@gmail.com> added the comment: Thanks for working on this! I think keeping the first example as simple is possible is probably a good idea. And I didn't have time to read through the whole patch, but as far as I went, the pizza examples looked great. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

David Lam added the comment: here's a patch that covers all but one of the foo/bar/baz examples it also has fixes for the sample code near the beginning from the review Ezio did the one example I didn't do was the "Arguments containing -" part. I guess it felt like changing the names in that example would distract from what it was trying to illustrate there Anyways, I tried to proofread it so hopefully it reads okay, enjoy enjoy ^^ ---------- Added file: http://bugs.python.org/file27030/issue11176.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

Chris Jerdonek added the comment: Also see this e-mail to docs@: http://mail.python.org/pipermail/docs/2012-December/012028.html
---------- nosy: +chris.jerdonek _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

Chris Jerdonek added the comment: Issue 16933 improved the "choices" examples. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

Westley Martínez added the comment: I've skimmed through the patches. Good job kids. This is much better than it was before. No more of that silly command-line calculator or the foobar nonsense that sounds drier than the POSIX standard. Is there anything else that needs to be done? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

Georg Brandl added the comment:
Also see this e-mail to docs@: http://mail.python.org/pipermail/docs/2012-December/012028.html
No, please don't see this e-mail. It's not worth it. The poster clearly has no clue whatsoever about either a) common placeholders, or b) manners. I don't want to claim that foo/bar/etc. are superior to a well-thought-out example (which takes time to come up with), but they are certainly better than no example at all. ---------- nosy: +georg.brandl _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

Mark Lawrence added the comment: If we've got some meaningful changes can we please get them committed. However I'd like to state that with over 4000 issues open we've got better things to do than change docs because somebody doesn't like the use of foo, bar and baz in examples. ---------- nosy: +BreamoreBoy _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

Steve added the comment: I came here to file a bug against the argparse documentation because reading through the documentation I didn't realize a good usecase for the `epilog` argument to the `ArgumentParser()` class until I started noticing that some commandline tools end with examples of usage. I found this bug and so thought it would be better to just leave a comment here instead. I glaced through the submitted patches and noticed that the pizza making example has `epilog="Remember: select a good combination to ensure maximum tastiness` ...which while good, still might not immediately convey the usefulness of the epilog parameter (just IMHO). I think, the example would be better served by something like:
Of course this example would then also require passing a formatter_class argument to handle the wrapping ...but in essence the point of my comment is that the examples might be more useful if a 'real-world' usage is demonstrated. ---------- nosy: +lonetwin _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11176> _______________________________________

Change by Mark Lawrence <breamoreboy@gmail.com>: ---------- nosy: -BreamoreBoy _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue11176> _______________________________________

Change by Irit Katriel <iritkatriel@yahoo.com>: ---------- title: give more meaningful argument names in argparse documentation -> [doc] give more meaningful argument names in argparse documentation versions: +Python 3.10, Python 3.8, Python 3.9 -Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue11176> _______________________________________
participants (13)
-
Adam Woodbeck
-
Chris Jerdonek
-
David Lam
-
Georg Brandl
-
Greg Roodt
-
Irit Katriel
-
Marc Sibson
-
Mark Lawrence
-
Steve
-
Steven Bethard
-
Tshepang Lekhonkhobe
-
Westley Martínez
-
Éric Araujo