Westley Martínez 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 http://bugs.python.org/issue11176 _______________________________________

Westley Martínez 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 http://bugs.python.org/issue11176 _______________________________________

Changes by Adam Woodbeck : ---------- nosy: +adam.woodbeck _______________________________________ Python tracker http://bugs.python.org/issue11176 _______________________________________

Changes by Tshepang Lekhonkhobe : ---------- nosy: +tshepang _______________________________________ Python tracker http://bugs.python.org/issue11176 _______________________________________

Éric Araujo 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 http://bugs.python.org/issue11176 _______________________________________

Greg Roodt 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 wrote:

David Lam 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 http://bugs.python.org/issue11176 _______________________________________

---------- _______________________________________ Python tracker http://bugs.python.org/issue11176 _______________________________________

David Lam added the comment: yup yup, go for it ---------- _______________________________________ Python tracker 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 http://bugs.python.org/issue11176 _______________________________________

Chris Jerdonek added the comment: Issue 16933 improved the "choices" examples. ---------- _______________________________________ Python tracker 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 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:

...

...

pizza_parser = argparse.ArgumentParser( ... description='Make a pizza out of ingredients and toppings', ... epilog="""Examples: Create a Python Lovers pizza using the command:: ... ./makepizz.py spam ham eggs ... """)

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 http://bugs.python.org/issue11176 _______________________________________

Change by Irit Katriel : ---------- 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 https://bugs.python.org/issue11176 _______________________________________