Support filtering on both sections and generators (#3069)

Not being able to filter generators to specific element has been regularly
causing problems. It was possible to use a dynamic section to run tests
for specific element in a generator, at least if the element had a nice
string representation, but the test case would still run once per element
in the generator.

With this change, it is possible to have the generator return only one
specific element, and do so based on the index, rather than the string
representation of the element. This enables simple debugging of tests
that fail for specific generator element.

docs/command-line.md

@@ -52,6 +52,8 @@ Click one of the following links to take you straight to that option - or scroll
 <a href="#reporting-timings">                           `    -d, --durations`</a><br />
 <a href="#input-file">                                  `    -f, --input-file`</a><br />
 <a href="#run-section">                                 `    -c, --section`</a><br />
+<a href="#path-filtering">                              `    -g, --generator-index`</a><br />
+<a href="#path-filtering">                              `    -p, --path-filter`</a><br />
 <a href="#filenames-as-tags">                           `    -#, --filenames-as-tags`</a><br />
 
 
@@ -532,45 +534,19 @@ Prints the command line arguments to stdout
 
 
 <a id="run-section"></a>
-## Specify the section to run
+<a id="path-filtering"></a>
+## Specify the section/generator element to run
 <pre>-c, --section &lt;section name&gt;</pre>
+<pre>-g, --generator-index &lt;index in generator&gt;</pre>
+<pre>-p, --path-filter &lt;path filter spec&gt;</pre>
 
-To limit execution to a specific section within a test case, use this option one or more times.
-To narrow to sub-sections use multiple instances, where each subsequent instance specifies a deeper nesting level.
+> The generator and generic path filtering was added in Catch2 vX.Y.Z
 
-E.g. if you have:
+These arguments allow you to run specific section(s) in a test case, or
+only get specific element from a generator. All the variants form a shared
+stack of filters.
 
-<pre>
-TEST_CASE( "Test" ) {
-  SECTION( "sa" ) {
-    SECTION( "sb" ) {
-      /*...*/
-    }
-    SECTION( "sc" ) {
-      /*...*/
-    }
-  }
-  SECTION( "sd" ) {
-    /*...*/
-  }
-}
-</pre>
-
-Then you can run `sb` with:
-<pre>./MyExe Test -c sa -c sb</pre>
-
-Or run just `sd` with:
-<pre>./MyExe Test -c sd</pre>
-
-To run all of `sa`, including `sb` and `sc` use:
-<pre>./MyExe Test -c sa</pre>
-
-There are some limitations of this feature to be aware of:
-- Code outside of sections being skipped will still be executed - e.g. any set-up code in the TEST_CASE before the
-start of the first section.</br>
-- At time of writing, wildcards are not supported in section names.
-- If you specify a section without narrowing to a test case first then all test cases will be executed
-(but only matching sections within them).
+[See the full documentation of path filtering for more details](filtering-execution-path.md#top)
 
 
 <a id="filenames-as-tags"></a>