This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Documentation for argparse, missed opportunity
Type: enhancement Stage: resolved
Components: Documentation Versions:
process
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: docs@python Nosy List: berkbayraktar, docs@python, eric.smith, paul.j3, rhettinger
Priority: normal Keywords:

Created on 2021-04-21 08:54 by berkbayraktar, last changed 2022-04-11 14:59 by admin. This issue is now closed.

Messages (3)
msg391501 - (view) Author: berkbayr (berkbayraktar) Date: 2021-04-21 08:54
In the API reference page for argparse, the following example is used for formatter_class:

...     formatter_class=argparse.RawDescriptionHelpFormatter,
...     description=textwrap.dedent('''\
...         Please do not mess up this text!
...         --------------------------------
...             I have indented it
...             exactly the way
...             I want it
...         '''))

I propose the example would be vastly improved by the following change:

...         Please do not mess up this text!
...         --------------------------------
...             I have indented it
...             exactly the way
...             I intended 
...         '''))
msg391517 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2021-04-21 12:22
If we're trying to be poetic, I think the last line should be "I intended it".
msg391541 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2021-04-21 19:04
It's a cute suggestion but I think it would be a distraction that makes the docs slightly worse.  The example "works" because the eye has to search to see what makes the text special, the indentation.  If you add a second special but irrelevant text feature, it makes it less likely that the first will succeed.

Thanks for the cute and entertaining submission, but I'll decline because clarity comes first.
History
Date User Action Args
2022-04-11 14:59:44adminsetgithub: 88070
2021-04-21 19:04:40rhettingersetstatus: open -> closed
resolution: rejected
messages: + msg391541

stage: resolved
2021-04-21 12:22:05eric.smithsetnosy: + eric.smith
messages: + msg391517
2021-04-21 09:02:16xtreaksetnosy: + rhettinger, paul.j3
2021-04-21 08:54:18berkbayraktarcreate