Finding a guideline by a word in its title

[rico-chet]

Here's an issue I encountered recently:

I and a colleague of mine were enabling clang-tidy for our code base using modernize-use-override as the check to verify that it works.

While committing the emerging code changes, we wanted to mention and link to the according core guideline. So I went to the web page, searched for override and found 60 matches, which was too much. I wanted to search in guideline titles, but couldn't, as they are inline with text and aren't extracted to a table of contents (TOC).

Scrolling the document using mouse wheel was too slow, dragging the slider too fast. In the end, we found the guideline but this was a frustrating experience, and it's not a great advertisement for the guidelines.

[scraimer]

You could grep for the titles in the markdown document. Here's a one-liner that greps for "override":

curl https://github.com/isocpp/CppCoreGuidelines/raw/master/CppCoreGuidelines.md -sL | grep -ie '###.*override'

As of this writing, it returns exactly two topic: C.128 and C.140

Not a great solution, but it should give you some reprieve until someone (perhaps you?) builds a better method.

[rico-chet]

OK, guess I will need to add this as a plug-in to my bash-it.

As for a great solution, I am a fan of AsciiDoc and don't feel like participating in attempts to fix Markdown. Since these guidelines' committee decided against a nice format in favor of Markdown (https://github.com/isocpp/CppCoreGuidelines/issues/154#issuecomment-160739774), I believe there will be some resistance to re-viewing this topic. And I don't have enough stakes in here to drive the topic forward.

[rico-chet]

You will find my code referencing this issue linked above. It caches the guidelines to speed up things quite a bit.

Here are the results:

❯ cppcgl-find-rule override
C.128: Virtual functions should specify exactly one of `virtual`, `override`, or `final`
C.140: Do not provide different default arguments for a virtual function and an overrider

❯ cppcgl-find-rule '\<out\>'
F.17: For "in-out" parameters, pass by reference to non-`const`
F.20: For "out" output values, prefer return values to output parameters
F.21: To return multiple "out" values, prefer returning a struct or tuple