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

Revise problematic stable labels #1498

Closed
tkoeppe opened this issue Mar 2, 2017 · 10 comments
Closed

Revise problematic stable labels #1498

tkoeppe opened this issue Mar 2, 2017 · 10 comments
Milestone

Comments

@tkoeppe
Copy link
Contributor

tkoeppe commented Mar 2, 2017

Some of our stable labels are obnoxious (string.op+), debatable (reverse.iter.op!=), downright ridiculous (istreambuf.iterator::op*), or simply comical (move.iter.op.+).

We should review all our stable labels and change those that use unnecessarily special characters. Changing labels requires informing @Dani-Hub of the changes, so we should try and do all the work in one go.

We ought to be able to get a list of all labels from the "Cross references" glossary, but beware that certain special characters may have broken the indexing and thus don't even show up; check the glossary log separately.

@tkoeppe tkoeppe added this to the C++20 milestone Mar 2, 2017
@jensmaurer
Copy link
Member

string.op+ is gone already, but needs fixing for string.op+=.
reverse.iter.* should have its sub-subsections removed (there are >5 subsections on a single page).
istreambuf.iterator::op* is already fixed.
move.iter.* should have its sub-subsections removed (there are >5 subsections on a single page).

@godbyk
Copy link
Contributor

godbyk commented Nov 8, 2017

Here is the list of labels containing characters other than letters, numbers, underscore, period, or hyphen:

back.insert.iter.op*
back.insert.iter.op++
back.insert.iter.op=
front.insert.iter.op*
front.insert.iter.op++
front.insert.iter.op=
insert.iter.op*
insert.iter.op++
insert.iter.op=
ios::Init
ios::failure
ios::fmtflags
ios::iostate
ios::openmode
ios::seekdir
istream::sentry
move.iter.op.+
move.iter.op.+=
move.iter.op.-=
move.iter.op=
ostream::sentry
reverse.iter.op!=
reverse.iter.op+
reverse.iter.op++
reverse.iter.op+=
reverse.iter.op-=
reverse.iter.op<
reverse.iter.op<=
reverse.iter.op=
reverse.iter.op==
reverse.iter.op>
reverse.iter.op>=
string.op!=
string.op+
string.op+=
string.op<
string.op<=
string.op>
string.op>=
string.operator==

Once we've fixed the labels, we could add a CI test to check for these issues in the future.

1 similar comment
@godbyk
Copy link
Contributor

godbyk commented Nov 8, 2017

Here is the list of labels containing characters other than letters, numbers, underscore, period, or hyphen:

back.insert.iter.op*
back.insert.iter.op++
back.insert.iter.op=
front.insert.iter.op*
front.insert.iter.op++
front.insert.iter.op=
insert.iter.op*
insert.iter.op++
insert.iter.op=
ios::Init
ios::failure
ios::fmtflags
ios::iostate
ios::openmode
ios::seekdir
istream::sentry
move.iter.op.+
move.iter.op.+=
move.iter.op.-=
move.iter.op=
ostream::sentry
reverse.iter.op!=
reverse.iter.op+
reverse.iter.op++
reverse.iter.op+=
reverse.iter.op-=
reverse.iter.op<
reverse.iter.op<=
reverse.iter.op=
reverse.iter.op==
reverse.iter.op>
reverse.iter.op>=
string.op!=
string.op+
string.op+=
string.op<
string.op<=
string.op>
string.op>=
string.operator==

Once we've fixed the labels, we could add a CI test to check for these issues in the future.

@jensmaurer
Copy link
Member

reverse.iter is addressed by #1832.

@Quuxplusone
Copy link
Contributor

Quuxplusone commented Feb 8, 2018

If labels change, please inform @Dani-Hub and @mclow of the changes (as mclow mentioned in a comment on #1832; I mention it here for visibility).

Here is a shell one-liner (tested only with BSD sed, not GNU sed) for extracting all the stable names from the source code:

git grep '^[^%]*\\rSec.\[[^{]*\]{.*}' | grep -o '\[[^{]*\]' | sort | sed 's/^.\(.*\).$/\1/'

You can pipe this through grep '[^a-z0-9.]' to get the current list of names that are IMHO troublesome.

Related to stable-name changes, I have also noticed that there is a very large number of conventions for naming sections that ought to be similarly named:

git grep 'rSec.\[.*\]{.*onstructor.*}' | grep -o '\[.*\]' > constructor-related-section-names.txt
grep -o '\.[^.]*\]' constructor-related-section-names.txt | sort | uniq -c

   3 .alloc]
   7 .cnstr]
  50 .cons]
   5 .const]
   1 .constr]
   2 .construct]
   2 .constructors]
  12 .ctor]
   1 .des]
   1 .functions]
   1 .init]
   1 .slice]

The surprising results here come from constexpr.functions and class.inhctor.init (false positives), ostream.iterator.cons.des and cons.slice (yuck!), and queue.cons.alloc etc. (debatable). The rest are not-horrible-but-unfortunate and would in an ideal world use a standard naming convention.

See also

git grep 'rSec.\[.*\]{.*estructor.*}' | grep -o '\[.*\]' > destructor-related-section-names.txt
git grep 'rSec.\[.*\]{.*\(ssignment\|operator=[^=]\).*}' | grep -o '\[.*\]' > assignment-related-section-names.txt

@jensmaurer
Copy link
Member

Remaining offenders:

ios::fmtflags
ios::Init
ios::iostate
ios::openmode
ios::seekdir
istream::sentry
ostream::sentry
string.op<=
string.op<
string.op>=
string.op>
string.op!=
string.op+=
string.op+
string.operator==```

@jensmaurer
Copy link
Member

Remaining offenders:

class.mfct.non-static
ios::failure
ios::fmtflags
ios::Init
ios::iostate
ios::openmode
ios::seekdir
istream::sentry
ostream::sentry

@jensmaurer
Copy link
Member

"class.mfct.non-static" is the only remaining questionable label (due to the hyphen), but that seems acceptable.

@Quuxplusone
Copy link
Contributor

class.mfct.non-static is the only remaining questionable label (due to the hyphen)

Peanut gallery asks: Why not fix that one by the same mechanism as we fixed all the other ones? (I suggest class.mfct.nonstatic as the obvious spelling.)

@jensmaurer
Copy link
Member

@Quuxplusone, we have lots of stable labels with underscores in them, which look a lot more dreadful than the hyphen we have here. Those underscores are addressed in #2609.

Eelis added a commit to Eelis/cxxdraft-htmlgen that referenced this issue Jul 27, 2020
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

4 participants