CppCoreGuidelines icon indicating copy to clipboard operation
CppCoreGuidelines copied to clipboard

Is a rule's header's HTML anchor name still a valid `tag` inside `gsl::suppress`?

Open dmitrykobets-msft opened this issue 3 years ago • 2 comments

The specification In.force: Enforcement allows for [[gsl::suppress(Rh-public)]], where Rh-public is the HTML anchor name for C.134. Is this type of tag still supported? Is there potential for confusion if the guidelines ever move away from their current HTML/Markdown format?

Note that currently the only way to find the appropriate anchor name for a given rule when viewing the rendered HTML is to inspect the webpage and navigate through its elements.

Update: On the github pages, clicking on the anchor button next to a title will sometimes generate a different anchor name than the "intended" anchor name image

  • will give http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#i13-do-not-pass-an-array-as-a-single-pointer as opposed to http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Ri-array

dmitrykobets-msft avatar Feb 17 '23 19:02 dmitrykobets-msft

See also #2046

hsutter avatar Jul 27 '23 16:07 hsutter

Editors call: The HTML tags are an implementation detail, but the names should also be visible to the reader. We'll address this together with #2046.

hsutter avatar Jul 27 '23 16:07 hsutter

Editors call: Sorry for the lag on this. The answer is that.

  • Item numbers are for users, and users should suppress by item number. For example for I.13, the user would suppress using [[gsl::suppress("I.13")]])... note that the tag will now be a string literal.

  • Anchors are for tools, and tools should link by the anchor name. For example for I.13, the tool should link to "Ri-array" using https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Ri-array.

hsutter avatar Feb 15 '24 21:02 hsutter