gh-59330: Improve error message for dest= for positionals

[serhiy-storchaka]

Also improve the documentation. Specify how dest and metavar are derived from add_argument() positional arguments.

• Issue: argparse: positional arguments containing - in name not handled well #59330

---

📚 Documentation preview 📚: https://cpython-previews--125215.org.readthedocs.build/

[savannahostrowski]

Just one small comment about the documentation; otherwise, this LGTM!

I really like the additional error message specificity.

[savannahostrowski]

Suggested change

	By default, argparse automatically handles the internal naming and
	display names of arguments, simplifying the process without requiring
	additional configuration.
	As such, you do not need to specify the dest_ and metavar_ parameters.
	The dest_ parameter defaults to the argument name with underscores ``_``
	replacing hyphens ``-`` . The metavar_ parameter defaults to the
	upper-cased name. For example::
	By default, argparse automatically handles the internal naming and
	display names of arguments, simplifying the process without requiring
	additional configuration. As such, you do not need to specify the dest_
	and metavar_ parameters. The dest_ parameter defaults to the argument
	name with underscores ``_`` replacing hyphens ``-`` . The metavar_
	parameter defaults to the upper-cased name. For example::

[savannahostrowski]

Just removing the newline as I think that this can be one short paragraph.

[serhiy-storchaka]

This does not affect the result. For Sphinx this is the same.

I prefer to start new sentence from a new line. This will help to keep the text more readable in future without reformatting the whole paragraph. Adding or removing will only affect one sentence.

I don't know if this is already in the style guide, but I try to follow this rule.

[kuraga]

@serhiy-storchaka , of arguments or of non-positional arguments?
https://stackoverflow.com/a/20250435/556958