directory

- reverse the order of new_directory_list returned from split_pre_existing_dir in copy module

Use common file argument system previously implemented by @sivel for rax modules on the file modules as well (copy/file/template).
Application to other cloud providers would make very good sense.

passed via this paramter is not passed via shell and so all shell features
will not work.

Closes GH-6194.

These changes pass attribute modifications through to new directories during a recursive copy with an addition allowing for the directory mode to be set independantly.

Update copy documentation to reference synchronize module

raise errors when omitted, updated changelog with new modules.

If src param to copy is a directory, all files under it are collected
and pushed one by one to target. Source dir path handled in a way
simalar to rsync: if it ends with slash, only inside contents of
directory are copied to destination, otherwise the dir itself is
copied (with all contents of course). Original idea and implementation
by https://github.com/ansible/ansible/pull/1809 . Rewritten to address
review comments and simplify/correct logic.

This clarifies the validate command argument and makes it clear that if
it is present, it must include the '%s' argument for the path to the
temporary file to validate.

visudo requires the -f option to check any other file than the default.
I've added this to the example ansible tasks.

  Migrated all examples: in DOCUMENTATION=''' string to standalone EXAMPLES=''' string
  Added deprecation warning to moduledev.rst and remove deprecated example from it
  Fixed up a few typos and uppercased some acronyms.
  add consistency to how EXAMPLES are formatted

removed return code as it doesn't make sense anymore
Signed-off-by: Brian Coca <briancoca+dev@gmail.com>

step
Signed-off-by: Brian Coca <briancoca+dev@gmail.com>

Added 'validate' feature to copy and template modules, now you can add a check to force copy to fail if the check fails.
had to add entry in file for it to accept as a option even though file itself ignores it.
Signed-off-by: Brian Coca <briancoca+dev@gmail.com>

Ensure that when transferring a file to a directory the name of the file is the correct basename and not 'source'.

Fixes #2388.

Signed-off-by: Brian Coca <briancoca+dev@gmail.com>