Doc cleanup regarding path=fd, dir_fd, follow_symlinks, etc

[larryhastings]

BPO	16024
Nosy	@birkenfeld, @vstinner, @larryhastings, @csabella
PRs	bpo-16024: Doc cleanup regarding path_fd, dir_fd, follow_symlinks #5505
Files	lch.supports_set.doc.cleanup.1.diff: First draft at a patch. Doc-only change, docs build clean. lch.supports_set.doc.cleanup.1-revised.diff: Revised .diff file

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/larryhastings'
closed_at = <Date 2019-05-06.12:40:04.397>
created_at = <Date 2012-09-24.15:29:58.700>
labels = ['type-feature', '3.8', 'docs']
title = 'Doc cleanup regarding path=fd, dir_fd, follow_symlinks, etc'
updated_at = <Date 2019-05-06.12:40:04.396>
user = 'https://github.com/larryhastings'

bugs.python.org fields:

activity = <Date 2019-05-06.12:40:04.396>
actor = 'larry'
assignee = 'larry'
closed = True
closed_date = <Date 2019-05-06.12:40:04.397>
closer = 'larry'
components = ['Documentation']
creation = <Date 2012-09-24.15:29:58.700>
creator = 'larry'
dependencies = []
files = ['27276', '30255']
hgrepos = []
issue_num = 16024
keywords = ['patch']
message_count = 9.0
messages = ['171155', '174705', '189186', '189216', '189639', '189646', '311530', '341495', '341496']
nosy_count = 6.0
nosy_names = ['georg.brandl', 'vstinner', 'larry', 'Arfrever', 'kkvr05', 'cheryl.sabella']
pr_nums = ['5505']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue16024'
versions = ['Python 3.8']

[larryhastings]

You know how you start pulling on a thread and before you notice you've unraveled the whole sweater? I meant to do a simple *one line* fix on the docs and wound up with a nearly-300-line diff. I claim it's all an improvement, though I'm willing to change it if there's something you don't like.

Definite improvements:

• supports_fd et al are :class:`set` objects, not :class:`~collections.Set`. Those are different.
• Linked to the "specifying a file descriptor" section in os from the relevant discussion in what's new.
• "Availability: Unix" goes above :versionadded.

Avowed improvements:

• supports_* now explicitly mention what values are permitted for their parameters.
• Lots of rewriting/munging in an effort to improve readability and precision.
• A couple places where "it's" read better than "it is".

LGTU?

[akuchling]

Patch looks good with two small changes.

• "for consistency's sakes" is used in 2 places; this should be "sake", not the plural "sakes".

• "Normally the *path* argument specified to functions": 'specified to' sounds wrong, and IMHO would be better as 'provided to' or 'passed to'.

The last hunk in the patch to 3.3.rst, but the new text still seems an improvement.

[kkvr05]

Adding a revision of the .diff file according to akuchling's comment.

[akuchling]

Kaleb Robertson's changes look good. Larry, do you want to go ahead and commit this?

[larryhastings]

I would, but I can't get it to apply cleanly, either to tip or to historical revisions back in Sepember. Kaleb, what revision is the branch that you generated the diff from?

[larryhastings]

p.s. Thanks for reviving the patch. I forgot about this one!

[csabella]

Larry,

I've made a pull request for your patch. It seemed like most of the original text was still in place, so I thought you might still want these changes. You had also made changes to the What's New, but I didn't include those changes.

[larryhastings]

New changeset e152169 by larryhastings (Cheryl Sabella) in branch 'master':
bpo-16024: Doc cleanup regarding path_fd, dir_fd, follow_symlinks (GH-5505)
e152169

[larryhastings]

At last! Thanks for reviving it, Cheryl!