Clarify behavior of --skip-tags, --list-tasks, and --list-tags. (#60492)

docs/docsite/rst/user_guide/playbooks_tags.rst

@@ -5,11 +5,6 @@ If you have a large playbook, it may become useful to be able to run only
 a specific part of it rather than running *everything* in the playbook.
 Ansible supports a "tags:" attribute for this reason.
 
-When you execute a playbook, you can filter tasks based on tags in two ways:
-
-- On the command line, with the ``--tags`` or ``--skip-tags`` options
-- In Ansible configuration settings, with the ``TAGS_RUN`` and ``TAGS_SKIP`` options
-
 Tags can be applied to *many* structures in Ansible (see "tag inheritance",
 below), but its simplest use is with individual tasks. Here is an example
 that tags two tasks with different tags::
@@ -29,7 +24,14 @@ that tags two tasks with different tags::
       tags:
       - configuration
 
-If you wanted to just run the "configuration" and "packages" part of a very long playbook, you can use the ``--tags`` option on the command line::
+When you execute a playbook, you can filter tasks based on tags in two ways:
+
+- On the command line, with the ``--tags`` or ``--skip-tags`` options
+- In Ansible configuration settings, with the ``TAGS_RUN``
+  and ``TAGS_SKIP`` options
+
+For example, if you wanted to just run the "configuration" and "packages" part
+of a very long playbook, you can use the ``--tags`` option on the command line::
 
     ansible-playbook example.yml --tags "configuration,packages"
 
@@ -38,8 +40,15 @@ tasks, you can use the ``--skip-tags`` command-line option::
 
     ansible-playbook example.yml --skip-tags "packages"
 
+You can see which tasks will be executed with ``--tags`` or ``--skip-tags`` by
+combining it with ``--list-tasks``::
+
+    ansible-playbook example.yml --tags "configuration,packages" --list-tasks
+
 .. warning::
-    * Fact gathering is tagged with 'always' by default. It is ONLY skipped if you apply a tag and then use a different tag in ``--tags`` or the same tag in ``--skip-tags``.
+    * Fact gathering is tagged with 'always' by default. It is ONLY skipped if
+      you apply a tag and then use a different tag in ``--tags`` or the same
+      tag in ``--skip-tags``.
 
 .. _tag_reuse:
 
@@ -129,14 +138,16 @@ Tags are applied *down* the dependency chain. In order for a tag to be
 inherited to a dependent role's tasks, the tag should be applied to the
 role declaration or static import, not to all the tasks within the role.
 
-There is no way to 'import only these tags'; you probably want to split into smaller roles/includes if you find yourself looking for such a feature.
+There is no way to 'import only these tags'; you probably want to split
+into smaller roles/includes if you find yourself looking for such a feature.
 
-The above information does not apply to `include_tasks` or other dynamic includes,
-as the attributes applied to an include, only affect the include itself.
+The above information does not apply to `include_tasks` or other dynamic
+includes, as the attributes applied to an include, only affect the include
+itself.
 
 You can see which tags are applied to tasks, roles, and static imports
 by running ``ansible-playbook`` with the ``--list-tasks`` option. You can
-display all tags applied to the tasks with the ``--list-tags`` option.
+display all tags available with the ``--list-tags`` option.
 
 .. note::
     The above information does not apply to `include_tasks`, `include_roles`,
@@ -175,7 +186,8 @@ Role tasks file::
 Special Tags
 ````````````
 
-There is a special ``always`` tag that will always run a task, unless specifically skipped (``--skip-tags always``)
+There is a special ``always`` tag that will always run a task, unless
+specifically skipped (``--skip-tags always``)
 
 Example::
 
@@ -192,7 +204,8 @@ Example::
 
 .. versionadded:: 2.5
 
-Another special tag is ``never``, which will prevent a task from running unless a tag is specifically requested.
+Another special tag is ``never``, which will prevent a task from running unless
+a tag is specifically requested.
 
 Example::
 
@@ -200,10 +213,12 @@ Example::
       - debug: msg="{{ showmevar }}"
         tags: [ never, debug ]
 
-In this example, the task will only run when the ``debug`` or ``never`` tag is explicitly requested.
+In this example, the task will only run when the ``debug`` or ``never`` tag
+is explicitly requested.
 
 
-There are another 3 special keywords for tags: ``tagged``, ``untagged`` and ``all``, which run only tagged, only untagged
+There are another 3 special keywords for tags: ``tagged``, ``untagged`` and
+``all``, which run only tagged, only untagged
 and all tasks respectively.
 
 By default, Ansible runs as if ``--tags all`` had been specified.