Clarify docs re mode's octal representation (#44410)

* Clarify docs re mode's octal representation

I changed the language about how to use mode to make it more obvious
that using "01777" is not a typo, because the leading zero is not meant
to reflect the way that number might have been given on a command line.
See also: issues #5409 #9196 #11385 #13115 #18952 #23491 #23521

lib/ansible/modules/files/copy.py

@@ -60,9 +60,9 @@ options:
   mode:
     description:
       - "Mode the file or directory should be. For those used to I(/usr/bin/chmod) remember that
-        modes are actually octal numbers.  You must either specify the leading zero so that
+        modes are actually octal numbers. You must either add a leading zero so that Ansible's
-        Ansible's YAML parser knows it is an octal number (like C(0644) or C(01777)) or quote it
+        YAML parser knows it is an octal number (like C(0644) or C(01777)) or quote it
-        (like C('644') or C('0644') so Ansible receives a string and can do its own conversion from
+        (like C('644') or C('1777')) so Ansible receives a string and can do its own conversion from
         string into number.  Giving Ansible a number without following one of these rules will end
         up with a decimal number which will have unexpected results.  As of version 1.8, the mode
         may be specified as a symbolic mode (for example, C(u+rwx) or C(u=rw,g=r,o=r)).  As of

lib/ansible/modules/files/file.py

@@ -103,11 +103,12 @@ options:
 '''
 
 EXAMPLES = '''
-# change file ownership, group and mode. When specifying mode using octal numbers, first digit should always be 0.
+# change file ownership, group and mode
 - file:
     path: /etc/foo.conf
     owner: foo
     group: foo
+    # when specifying mode using octal numbers, add a leading 0
     mode: 0644
 - file:
     path: /work

lib/ansible/modules/files/template.py

@@ -98,9 +98,9 @@ options:
   mode:
     description:
       - "Mode the file or directory should be. For those used to I(/usr/bin/chmod) remember that
-        modes are actually octal numbers.  You must either specify the leading zero so that
+        modes are actually octal numbers.  You must either add a leading zero so that Ansible's
-        Ansible's YAML parser knows it is an octal number (like C(0644) or C(01777)) or quote it
+        YAML parser knows it is an octal number (like C(0644) or C(01777)) or quote it
-        (like C('644') or C('0644') so Ansible receives a string and can do its own conversion from
+        (like C('644') or C('1777')) so Ansible receives a string and can do its own conversion from
         string into number.  Giving Ansible a number without following one of these rules will end
         up with a decimal number which will have unexpected results.  As of version 1.8, the mode
         may be specified as a symbolic mode (for example, C(u+rwx) or C(u=rw,g=r,o=r)).  As of

lib/ansible/utils/module_docs_fragments/files.py

@@ -27,8 +27,8 @@ options:
   mode:
     description:
       - "Mode the file or directory should be. For those used to I(/usr/bin/chmod) remember that modes are actually octal numbers.
-        You must either specify the leading zero so that Ansible's YAML parser knows it is an octal
+        You must either add a leading zero so that Ansible's YAML parser knows it is an octal
-        number (like C(0644) or C(01777)) or quote it (like C('644') or C('0644') so Ansible
+        number (like C(0644) or C(01777)) or quote it (like C('644') or C('1777')) so Ansible
         receives a string and can do its own conversion from string into number.  Giving Ansible a number
         without following one of these rules will end up with a decimal number which will have unexpected results.
         As of version 1.8, the mode may be specified as a symbolic mode (for example, C(u+rwx) or C(u=rw,g=r,o=r))."