[docs] argparse doc example not especially helpful

[Sandro Tosi]

Hello Tyler,
sorry for this very late reply.

Would you like to provide some code examples for your proposal? That
would help us a lot in improving the doc.

Regards,
Sandro

On Wed, Mar 16, 2011 at 07:39, Tyler J. Barth <tyler.j.barth at gmail.com> wrote:
> 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
>
>
>
> _______________________________________________
> docs mailing list
> docs at python.org
> http://mail.python.org/mailman/listinfo/docs
>
>



-- 
Sandro Tosi (aka morph, morpheus, matrixhasu)
My website: http://matrixhasu.altervista.org/
Me at Debian: http://wiki.debian.org/SandroTosi