Docsite: fix user_guide/playbooks_error_handling (#71771)

docs/docsite/rst/user_guide/playbooks_error_handling.rst

@@ -16,36 +16,36 @@ Ignoring failed commands
 
 By default Ansible stops executing tasks on a host when a task fails on that host. You can use ``ignore_errors`` to continue on in spite of the failure::
 
-    - name: this will not count as a failure
-      command: /bin/false
+    - name: Do not count this as a failure
+      ansible.builtin.command: /bin/false
       ignore_errors: yes
 
-The ``ignore_errors`` directive only works when the task is able to run and returns a value of 'failed'. It will not make Ansible ignore undefined variable errors, connection failures, execution issues (for example, missing packages), or syntax errors.
+The ``ignore_errors`` directive only works when the task is able to run and returns a value of 'failed'. It does not make Ansible ignore undefined variable errors, connection failures, execution issues (for example, missing packages), or syntax errors.
 
 Ignoring unreachable host errors
 ================================
 
 .. versionadded:: 2.7
 
-You may ignore task failure due to the host instance being 'UNREACHABLE' with the ``ignore_unreachable`` keyword. Ansible ignores the task errors, but continues to execute future tasks against the unreachable host. For example, at the task level::
+You can ignore a task failure due to the host instance being 'UNREACHABLE' with the ``ignore_unreachable`` keyword. Ansible ignores the task errors, but continues to execute future tasks against the unreachable host. For example, at the task level::
 
-    - name: this executes, fails, and the failure is ignored
-      command: /bin/true
+    - name: This executes, fails, and the failure is ignored
+      ansible.builtin.command: /bin/true
       ignore_unreachable: yes
 
-    - name: this executes, fails, and ends the play for this host
-      command: /bin/true
+    - name: This executes, fails, and ends the play for this host
+      ansible.builtin.command: /bin/true
 
 And at the playbook level::
 
     - hosts: all
       ignore_unreachable: yes
       tasks:
-      - name: this executes, fails, and the failure is ignored
-        command: /bin/true
+      - name: This executes, fails, and the failure is ignored
+        ansible.builtin.command: /bin/true
 
-      - name: this executes, fails, and ends the play for this host
-        command: /bin/true
+      - name: This executes, fails, and ends the play for this host
+        ansible.builtin.command: /bin/true
         ignore_unreachable: no
 
 .. _resetting_unreachable:
@@ -84,21 +84,21 @@ Ansible lets you define what "failure" means in each task using the ``failed_whe
 You may check for failure by searching for a word or phrase in the output of a command::
 
     - name: Fail task when the command error output prints FAILED
-      command: /usr/bin/example-command -x -y -z
+      ansible.builtin.command: /usr/bin/example-command -x -y -z
       register: command_result
       failed_when: "'FAILED' in command_result.stderr"
 
 or based on the return code::
 
     - name: Fail task when both files are identical
-      raw: diff foo/file1 bar/file2
+      ansible.builtin.raw: diff foo/file1 bar/file2
       register: diff_cmd
       failed_when: diff_cmd.rc == 0 or diff_cmd.rc >= 2
 
 You can also combine multiple conditions for failure. This task will fail if both conditions are true::
 
     - name: Check if a file exists in temp and fail task if it does
-      command: ls /tmp/this_should_not_be_here
+      ansible.builtin.command: ls /tmp/this_should_not_be_here
       register: result
       failed_when:
         - result.rc == 0
@@ -111,7 +111,7 @@ If you want the task to fail when only one condition is satisfied, change the ``
 If you have too many conditions to fit neatly into one line, you can split it into a multi-line yaml value with ``>``::
 
     - name: example of many failed_when conditions with OR
-      shell: "./myBinary"
+      ansible.builtin.shell: "./myBinary"
       register: ret
       failed_when: >
         ("No such file or directory" in ret.stdout) or
@@ -127,17 +127,19 @@ Ansible lets you define when a particular task has "changed" a remote node using
 
     tasks:
 
-      - shell: /usr/bin/billybass --mode="take me to the river"
+      - name: Report 'changed' when the return code is not equal to 2 
+        ansible.builtin.shell: /usr/bin/billybass --mode="take me to the river"
         register: bass_result
         changed_when: "bass_result.rc != 2"
 
-      # this will never report 'changed' status
-      - shell: wall 'beep'
+      - name: This will never report 'changed' status
+        ansible.builtin.shell: wall 'beep'
         changed_when: False
 
 You can also combine multiple conditions to override "changed" result::
 
-    - command: /bin/fake_command
+    - name: Combine multiple conditions to override 'changed' result
+      ansible.builtin.command: /bin/fake_command
       register: result
       ignore_errors: True
       changed_when:
@@ -149,11 +151,11 @@ See :ref:`controlling_what_defines_failure` for more conditional syntax examples
 Ensuring success for command and shell
 ======================================
 
-The :ref:`command <command_module>` and :ref:`shell <shell_module>` modules care about return codes, so if you have a command whose successful exit code is not zero, you may wish to do this::
+The :ref:`command <command_module>` and :ref:`shell <shell_module>` modules care about return codes, so if you have a command whose successful exit code is not zero, you can do this::
 
     tasks:
-      - name: run this command and ignore the result
-        shell: /usr/bin/somecommand || /bin/true
+      - name: Run this command and ignore the result
+        ansible.builtin.shell: /usr/bin/somecommand || /bin/true
 
 
 Aborting a play on all hosts
@@ -181,25 +183,26 @@ You can use this feature when all tasks must be 100% successful to continue play
 
     ---
     - hosts: load_balancers_dc_a
-      any_errors_fatal: True
+      any_errors_fatal: true
 
       tasks:
-        - name: 'shutting down datacenter [ A ]'
-          command: /usr/bin/disable-dc
+        - name: Shut down datacenter 'A'
+          ansible.builtin.command: /usr/bin/disable-dc
 
     - hosts: frontends_dc_a
 
       tasks:
-        - name: 'stopping service'
-          command: /usr/bin/stop-software
-        - name: 'updating software'
-          command: /usr/bin/upgrade-software
+        - name: Stop service
+          ansible.builtin.command: /usr/bin/stop-software
+
+        - name: Update software
+          ansible.builtin.command: /usr/bin/upgrade-software
 
     - hosts: load_balancers_dc_a
 
       tasks:
-        - name: 'Starting datacenter [ A ]'
-          command: /usr/bin/enable-dc
+        - name: Start datacenter 'A'
+          ansible.builtin.command: /usr/bin/enable-dc
 
 In this example Ansible starts the software upgrade on the front ends only if all of the load balancers are successfully disabled.