docs: Improve Tag-Expressions v2 description

* Add Tag-Expressions v1 END-OF-LIFE support
* Describe "{config.tags}" placeholder for --tags option on command-line
* Descripe "tag_expression_protocol" parameter in config-file

CLEANUP:

* Use "https:" instead of "http:" URL prefix where possible
* Gherkin v6 aliases: Use table (was: unnumbered-list)

docs/_common_extlinks.rst

@@ -9,15 +9,13 @@
 .. _`C++ scope guard`:  https://en.wikibooks.org/wiki/More_C++_Idioms/Scope_Guard
 
 .. _Cucumber:   https://cucumber.io/
-.. _Lettuce:    http://lettuce.it/
-
-.. _Selenium:   http://docs.seleniumhq.org/
+.. _Selenium:   https://docs.seleniumhq.org/
 
 .. _PyCharm:        https://www.jetbrains.com/pycharm/
-.. _Eclipse:        http://www.eclipse.org/
+.. _Eclipse:        https://www.eclipse.org/
 .. _VisualStudio:   https://www.visualstudio.com/
 
 .. _`PyCharm BDD`: https://blog.jetbrains.com/pycharm/2014/09/feature-spotlight-behavior-driven-development-in-pycharm/
-.. _`Cucumber-Eclipse`: http://cucumber.github.io/cucumber-eclipse/
+.. _`Cucumber-Eclipse`: https://cucumber.github.io/cucumber-eclipse/
 
-.. _ctags:      http://ctags.sourceforge.net/
+.. _ctags:      https://ctags.sourceforge.net/

docs/_content.tag_expressions_v2.rst

@@ -1,40 +1,74 @@
 Tag-Expressions v2
 -------------------------------------------------------------------------------
 
-:pypi:`cucumber-tag-expressions` are now supported and supersedes the old-style
-tag-expressions (which are deprecating). :pypi:`cucumber-tag-expressions` are much
-more readable and flexible to select tags on command-line.
+Tag-Expressions v2 are based on :pypi:`cucumber-tag-expressions` with some extensions:
+
+* Tag-Expressions v2 provide `boolean logic expression`
+  (with ``and``, ``or`` and ``not`` operators and parenthesis for grouping expressions)
+* Tag-Expressions v2 are far more readable and composable than Tag-Expressions v1
+* Some boolean-logic-expressions where not possible with Tag-Expressions v1
+* Therefore, Tag-Expressions v2 supersedes the old-style tag-expressions.
+
+EXAMPLES:
 
 .. code-block:: sh
 
     # -- SIMPLE TAG-EXPRESSION EXAMPLES:
+    # EXAMPLE 1: Select features/scenarios that have the tags: @a and @b
     @a and @b
-    @a or  @b
+
+    # EXAMPLE 2: Select features/scenarios that have the tag: @a or @b
+    @a or @b
+
+    # EXAMPLE 3: Select features/scenarios that do not have the tag: @a
     not @a
 
     # -- MORE TAG-EXPRESSION EXAMPLES:
     # HINT: Boolean expressions can be grouped with parenthesis.
+    # EXAMPLE 4: Select features/scenarios that have the tags: @a but not @b
     @a and not @b
+
+    # EXAMPLE 5: Select features/scenarios that have the tags: (@a or @b) but not @c
     (@a or @b) and not @c
 
-Example:
+COMMAND-LINE EXAMPLE:
 
 .. code-block:: sh
 
     # -- SELECT-BY-TAG-EXPRESSION (with tag-expressions v2):
     # Select all features / scenarios with both "@foo" and "@bar" tags.
     $ behave --tags="@foo and @bar" features/
 
+    # -- EXAMPLE: Use default_tags from config-file "behave.ini".
+    # Use placeholder "{config.tags}" to refer to this tag-expression.
+    # HERE: config.tags = "not (@xfail or @not_implemented)"
+    $ behave --tags="(@foo or @bar) and {config.tags}" --tags-help
+    ...
+    CURRENT TAG_EXPRESSION: ((foo or bar) and not (xfail or not_implemented))
+
+    # -- EXAMPLE: Uses Tag-Expression diagnostics with --tags-help option
+    $ behave --tags="(@foo and @bar) or @baz" --tags-help
+    $ behave --tags="(@foo and @bar) or @baz" --tags-help --verbose
 
 .. seealso::
 
     * https://docs.cucumber.io/cucumber/api/#tag-expressions
+    * :pypi:`cucumber-tag-expressions` (Python package)
 
 
 Tag Matching with Tag-Expressions
 -------------------------------------------------------------------------------
 
-The new tag-expressions also support **partial string/tag matching** with wildcards.
+Tag-Expressions v2 support **partial string/tag matching** with wildcards.
+This supports tag-expressions:
+
+=================== ========================
+Tag Matching Idiom  Tag-Expression Example
+=================== ========================
+``tag-starts-with`` ``@foo.*`` or ``foo.*``
+``tag-ends-with``   ``@*.one`` or ``*.one``
+``tag-contains``    ``@*foo*`` or ``*foo*``
+=================== ========================
 
 .. code-block:: gherkin
 
@@ -69,9 +103,43 @@ that start with "@foo.":
 
     # -- HINT: Only Alice.1 and Alice.2 are matched (not: Alice.3).
 
-.. hint::
+.. note::
 
     * Filename matching wildcards are supported.
       See :mod:`fnmatch` (Unix style filename matching).
 
     * The tag matching functionality is an extension to :pypi:`cucumber-tag-expressions`.
+
+
+Select the Tag-Expression Version to Use
+-------------------------------------------------------------------------------
+
+The tag-expression version, that should be used by :pypi:`behave`,
+can be specified in the :pypi:`behave` config-file.
+
+This allows a user to select:
+
+* Tag-Expressions v1 (if needed)
+* Tag-Expressions v2 when it is feasible
+
+EXAMPLE:
+
+.. code-block:: ini
+
+    # -- FILE: behave.ini
+    # SPECIFY WHICH TAG-EXPRESSION-PROTOCOL SHOULD BE USED:
+    #   SUPPORTED VALUES: v1, v2, auto_detect
+    #   CURRENT DEFAULT:  auto_detect
+    [behave]
+    tag_expression_protocol = v1    # -- Use Tag-Expressions v1.
+
+
+Tag-Expressions v1
+-------------------------------------------------------------------------------
+
+Tag-Expressions v1 are becoming deprecated (but are currently still supported).
+Use **Tag-Expressions v2** instead.
+
+.. note::
+
+    Tag-Expressions v1 support will be dropped in ``behave v1.4.0``.

docs/new_and_noteworthy_v1.2.7.rst

@@ -36,11 +36,16 @@ A Rule (or: business rule) allows to group multiple Scenario(s)/Example(s)::
         Scenario*           #< CARDINALITY: 0..N (many)
         ScenarioOutline*    #< CARDINALITY: 0..N (many)
 
-Gherkin v6 keyword aliases::
+Gherkin v6 keyword aliases:
+
+==================  =================== ======================
+Concept             Preferred Keyword   Alias(es)
+==================  =================== ======================
+Scenario            Example             Scenario
+Scenario Outline    Scenario Outline    Scenario Template
+Examples            Examples            Scenarios
+==================  =================== ======================
 
-    | Concept          | Preferred Keyword | Alias(es)          |
-    | Scenario         | Example           | Scenario           |
-    | Scenario Outline | Scenario Outline  | Scenario Template  |
 
 Example: