[docs] argparse doc example not especially helpful

[Tyler J. Barth]

I propose an improvement to the documentation for argparse (http://docs.python.org/library/argparse.html)

I posit that the example 15.4.1 is not immediately helpful for the majority of people coming to docs.python.org to figure out how to use argparse. Though the use of argparse features to effortlessly sum and max the input integers is clever (and demonstrates many advanced features), I think most people arriving on that page want to know how to do three things:
-Read in a file ("input.txt")
-Read in a boolean switch ("-bar", use bar mode or not)
-Read in a value for a switch ("-foo 6", set variable foo to 6)

Of course, by hunting through the rest of the documentation you can learn how to do all of these basic tasks and more (much, much more).

The clever sum and max example doesn't help elucidate how to perform these simple parses, and by using advanced features actually confuses new users.

"argparse" has much more power than most people need, and I think it is fair to say that it's power obscures how to do the most common tasks. However, because "optparse" is deprecated and we all probably want to discourage people from rolling their own argument parsers every time they make a new simple program, I think there is value in making the "common case" more prominent in the example. 

It would encourage adoption of argparse so that when users's programs eventually increase in complexity and they do want to expand functionality, they would have the full power of argparse at their disposal.

In summary, my suggestion is:
-Expand example 15.4.1 to include the most common use cases
-Consider splitting the "clever" example into a different section to avoid confusing new users.

Sincerely,
Tyler Barth



-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20110316/e238b134/attachment-0001.html>