Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[filesystems] uses of "respectively" in wording is incorrect #1541

Open
burblebee opened this issue Mar 15, 2017 · 5 comments
Open

[filesystems] uses of "respectively" in wording is incorrect #1541

burblebee opened this issue Mar 15, 2017 · 5 comments

Comments

@burblebee
Copy link
Contributor

[filesystems] has awkward wording like the following:

  • "Effects: Equivalent to pathobject = p, then refresh() or refresh(ec), respectively. If an error occurs the value of any cached attributes is unspecified."
  • "Returns: exists(this->status()) or exists(this->status(ec)), respectively."

In both cases, the use of respectively is wrong and adds nothing.
From http://www.wordforword.se/download/Respect.pdf:
"The use of respectively in English requires parallelism. In other words, there must
be a direct one-to-one correspondence.
Examples:
The values of X and Y were found to be 21.7 and 56.9, respectively."

Removing "respectively" would fix the English, but it doesn't address the problem that the author was trying to solve by adding "respectively" in the first place.

Comments from Jonathan:

It's because there are two overloads. The first one does refresh() and the second one (which has the ec parameter) does refresh(ec).

It could be reworded as "then, for the first overload, refresh(), for the second overload, refresh(ec)" but it should be done throughout 30.10 (it might fix some overfull hboxes though).

I think that would be a definite improvement.
burblebee referenced this issue Mar 15, 2017
@zygoloid
P0317R1 Directory Entry Caching for Filesystem
221d52e 
Also fixes LWG2663, LWG2677.

[directory_entry.obs]: nonexistent "file_status" in description of
is_directory replaced by intended "status". Introductory sentence
rephrased to avoid conflating functions with function calls and to avoid
suggesting that namespace members are not members.

[directory_entry.mods]: replace "then" with "followed by" to prevent
invasion of the right margin.
@jwakely
Copy link
Member

jwakely commented Mar 15, 2017

I dispute both "is wrong" and "adds nothing".

There is a one-to-one correspondence: there are two overloads and two different effects.

It definitely doesn't add nothing, because without it it isn't clear which form of refresh() is called (it would be possible for both to call refresh() i.e. the second one would ignore its ec parameter, or it would be possible for the first to create a local error_code variable and call refresh(ec)). The difference is normative and observable.

@jensmaurer
Copy link
Member

I do agree we should establish some correspondence between the ec and non-ec overloads, but I'm dubious whether we can achieve that by randomly dropping "respectively" into the sentence, without a clear connection to the two overloads at the top of the \itemdecl. That said, I don't have a specific suggestion for improvement.

@jensmaurer jensmaurer added the decision-required A decision of the editorial group (or the Project Editor) is required. label Mar 21, 2017
@jwakely
Copy link
Member

jwakely commented Nov 7, 2017

There are some bogus uses of "respectively" in Clause 28, and in [fs.path.construct] p3, but the ones in [fs.op.funcs] are OK, IMHO.

@jensmaurer
Copy link
Member

[alg.fill] complexity has three cases for four overloads.

@jensmaurer
Copy link
Member

Editorial meeting consensus: Having n overloads and giving n cases with respectively is fine. Other situations we found are not fine.

@jensmaurer jensmaurer removed the decision-required A decision of the editorial group (or the Project Editor) is required. label Nov 7, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
3 participants
@jwakely @burblebee @jensmaurer