Wordsmithing on manpage env Methods section #4579
Conversation
Signed-off-by: Mats Wichmann <mats@linux.com>
mwichmann
changed the title
|
Here is the converted-to-txt before and after - just the affected section, since it's localized. |
| and ellipses (<literal>...</literal>) indicate possible repetition. | ||
| Positional vs. keyword arguments are usually detailed | ||
| in the following text, not in the signature itself. | ||
| The &Python; positional-only (<literal>/</literal>) |
There was a problem hiding this comment.
I'd remove this bit The Python positional-only (/) and keyword-only (*) markers are not used. We never refer to using that notation anywhere, so I think no need to say it's not needed here, and for the python neophyte it might just cause confusion.
There was a problem hiding this comment.
I can demote it to a comment - want to keep a placeholder since it's possible the "not used" could change in future - there are some functions we can't correctly describe in the synopsis without using more Pythonic syntax, and have to leave to prose.
It came up for me because when I was working on that, the Python doc folks had just decided to reverse a previous policy of not using those special markers because "it might be confusing", in favor of being able to provide a more correct synopsis. Python docs, of course, are intended for Python users and we still suggest you don't need to know (much) Python so it's not quite the same. Though I still have a preference for having the manpage describe things "completely", which includes the synopsis of an official interface.
This is the first part of a possible series aiming to "tighten up" wording in the manpage. This PR covers only the section on Environment Methods and Global Functions, and actually doesn't make it "shorter", but hoping it's still an improvement.
Doc-only change, no code/tests.
Contributor Checklist:
CHANGES.txt(and read theREADME.rst)