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.

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

How to style expos-only members [Was: Restyle expos-only member basic-formatting-string::str] #4702

Open
tkoeppe opened this issue Jun 17, 2021 · 15 comments

Comments

@tkoeppe
Copy link
Contributor

tkoeppe commented Jun 17, 2021

See #4680 (comment)

We should style the exposition-only member str of basic-formatting-string in regular upright font, as we typically do for expos-only members. We should also rename it to str_, as we do for private expos-only members.

@jensmaurer
Copy link
Member

jensmaurer commented Jun 17, 2021

The private ranges members are all styled \exposid.

And, outside of ranges, we have a fair amount of member names not ending in _.

Personally, I think all exposition-only member names should be italics, and we should find a better / more pronounceable way of creating a new namespace, other than appending _. (In ranges, we occasionally have "current" and "current_", and they mean different things.)

@jensmaurer jensmaurer added the decision-required A decision of the editorial group (or the Project Editor) is required. label Jun 17, 2021
@tkoeppe
Copy link
Contributor Author

tkoeppe commented Jun 17, 2021

Do you have a sense of how many non-ranges private members there are?

@tkoeppe tkoeppe changed the title Restyle expos-only member basic-formatting-string::str How to style expos-only members [Was: Restyle expos-only member basic-formatting-string::str] Jun 17, 2021
@tkoeppe
Copy link
Contributor Author

tkoeppe commented Jun 17, 2021

Changing the issue to decide the general style first.

@jensmaurer
Copy link
Member

Do you have a sense of how many non-ranges private members there are?

Rough estimate, counting the \expos markers (ignoring \exposid):

$ grep -w expos *.tex | grep -v ranges.tex | wc -l
275

In other words, oodles of stuff.

@tkoeppe
Copy link
Contributor Author

tkoeppe commented Jun 17, 2021

OK, thanks. I feel like we're not going to resolve this for this mailing. Maybe for the next pre-meeting mailing!

@jensmaurer
Copy link
Member

jensmaurer commented Jun 18, 2021

Editorial meeting 2021-06-18: Consistent, global rule: All private data members have a _ suffix. All exposition-only names (including private data members) are styled with \exposid{...}.

The presence of the _ suffix is saddening, but we don't have a better idea right now.

@jensmaurer jensmaurer removed the decision-required A decision of the editorial group (or the Project Editor) is required. label Jun 18, 2021
@Dani-Hub
Copy link
Member

Re @tkoeppe :

Do you have a sense of how many non-ranges private members there are?

In N4885 there are 51 occurrences within Clause [ranges], specifically the following ones:
subrange: 2
single_view: 1
iota_view: 2
iota_view<W, Bound>::iterator: 1
iota_view<W, Bound>::sentinel: 1
basic_istream_view: 2
basic_istream_view<Val, CharT, Traits>::iterator: 1
ref_view: 1
filter_view: 2
filter_view<V, Pred>::iterator: 2
filter_view<V, Pred>::sentinel: 1
transform_view: 2
transform_view<V, F>::iterator: 2
transform_view<V, F>::sentinel: 1
take_view: 2
take_view::sentinel: 1
take_while_view: 2
take_while_view<V, Pred>::sentinel: 2
drop_view: 2
drop_while_view: 2
join_view: 2
join_view::iterator: 3
join_view::sentinel: 1
split_view: 3
split_view<V, Pattern>::outer-iterator: 2
split_view<V, Pattern>::outer-iterator ::value_type: 1
split_view<V, Pattern>::inner-iterator: 2
common_view: 1
reverse_view: 1
elements_view: 1
elements_view<V, N>::iterator: 1
elements_view<V, N>::sentinel: 1

@tkoeppe
Copy link
Contributor Author

tkoeppe commented Jun 18, 2021

Thanks, Daniel! Unfortunately that seems to mean that we have a lot more "old" private members that we now need to update to the new style :-S

@JohelEGP
Copy link
Contributor

Editorial meeting 2021-06-18: Consistent, global rule: All private data members have a _ suffix. All exposition-only names (including private data members) are styled with \exposid{...}.

The presence of the _ suffix is saddening, but we don't have a better idea right now.

Non-static only?

static constexpr bool @\exposidnc{ref-is-glvalue}@ = // \expos

@JohelEGP
Copy link
Contributor

The following Clauses are known to follow the rule (or not):

  • [ranges]

@W-E-Brown
Copy link
Contributor

FWIW, I believe this is an incredibly silly de minimis issue to have spent any time on. However, since we have/are, ...

I find that appending a useless trailing underscore to be an especially egregious waste of time. Moreover, such an emendation sends an entirely unintended message to readers, namely, that the Standard Library recommends the consistent use of trailing underscores for all such exposition-only member names. Since I can find no such policy or recommendation from WG21 (or even from LWG), I (1) object on the grounds that this is not a purely editorial change and (2) request reversion to status quo ante.

@jensmaurer
Copy link
Member

For [ranges], nothing was changed; the incoming papers generally had italics private data members with trailing underscores. Worse, sometimes we use current_ and current to mean different things (the latter is a meta-macro).

The most important thing about private data members is that their names are not in any way reserved by the standard library and e.g. a user is allowed to #define a macro with that name. Styling them in an non-utterable way (e.g. italics) seems to help in conveying such a notation. See also our exposition-only concept names.

@jensmaurer jensmaurer added the decision-required A decision of the editorial group (or the Project Editor) is required. label Aug 17, 2021
@jensmaurer jensmaurer removed the decision-required A decision of the editorial group (or the Project Editor) is required. label Nov 19, 2021
@tkoeppe
Copy link
Contributor Author

tkoeppe commented Nov 19, 2021

@W-E-Brown: The status quo ante is not consistent across the standard, and something we want to improve. We will necessarily have to touch a fair number of places in the standard, no matter which way we go. Marking expos-only members up in the source seems helpful, regardless of how we style them, so that part of the work would need to get done no matter what.

Have you got any concrete objections to any particular style? Otherwise, we seem to have a strong preference for italics and kebab-case (like all exposition-only names), and a mild preference for the trailing underscore based on partial existing practice.

I'm inclined to use that throughout unless we have good reasons to prefer something else. But please do note that the ranges library would be ambiguous without the trailing underscore, so alternative proposals would have to provide an alternative disambiguation.

@tkoeppe
Copy link
Contributor Author

tkoeppe commented Nov 19, 2021

Editorial meeting: we would like to continue the direction we decided at the previous meeting, but would like to achieve consensus among the editors.

@W-E-Brown
Copy link
Contributor

W-E-Brown commented Nov 20, 2021 via email

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

5 participants