[Documentation][2234]update_zos_replace_documentation

[AndreMarcel99]

SUMMARY

Update zos_replace documentation

Fixes #2234

ISSUE TYPE

• Documentation Pull Request

[ddimatos]

Hi, I recommended 3 large changes which might overlap with current PR comments, I can come back and do another review once we have incorporated all feedback. Thanks for working on this and providing a better user experience @AndreMarcel99

[ddimatos]

Since there are pending reviews, I can not multi select the entire section of text for after so I am going to offer my rewrite that also updates the URL so there is no version embedded, also makes the latest Ansible markup O(...) and other things like B(bold). This is for the entire after section of text.

  - A regular expression that if specified, determines which content will be replaced or removed B(after) the match.
  - Option O(after) is the start position from where the module will seek to match the O(regexp) pattern. When a pattern is matched, occurrences are substituted with the value set for O(replace).
  - If option O(after) is not set, the module will search from the beginning of the O(target).
  - Option O(after) is a regular expression as described in the L(Python library,https://docs.python.org/3/library/re.html).
  - Option O(after) can be used in combination with O(before). When combined with O(before), patterns are replaced or removed from O(after) until the value set for O(before).
  - Option O(after) can be interpreted as a literal string instead of a regular expression by setting option I(literal=after).

[ddimatos]

Since there are pending reviews, I can not multi select the entire section of text for before so I am going to offer my rewrite that also updates the URL so there is no version embedded, also makes the latest Ansible markup O(...) and other things like B(bold). This is for the entire before section of text.

  - A regular expression that if specified, determines which content will be replaced or removed B(before) the match.
  - Option O(before) is the end position from where the module will seek to match the O(regexp) pattern. When a pattern is matched, occurrences are substituted with the value set for O(replace).
  - If option O(before) is not set, the module will search to the end of the O(target).
  - Option O(before) is a regular expression as described in the L(Python library,https://docs.python.org/3/library/re.html).
  - Option O(before) can be used in combination with O(after). When combined with O(after), patterns are replaced or removed from O(after) until the value set for O(before).
  - Option O(before) can be interpreted as a literal string instead of a regular expression by setting option I(literal=before).

[ddimatos]

Since there are pending reviews, I can not multi select the entire section of text for literal so I am going to offer my rewrite that also updates the URL so there is no version embedded, also makes the latest Ansible markup O(...) and other things like B(bold). This is for the entire literal section of text.

  - If specified, it enables the module to interpret options O(after), O(before) and O(regex) as a literal rather than a regular expression.
  - Option O(literal) uses any combination of V(after), V(before) and V(regexp).
  - To interpret one option as a literal, use O(literal=regexp), O(literal=after) or O(literal=before).
  - To interpret multiple options as a literal, use a list such as C(['after', 'before']) or C(['regex', 'after', 'before'])

[ddimatos]

I can't comment on this section because its not part of the DIFF for this PR, but this section needs some updates.
Here are some suggestions:

From:

  backup:
    description:
      - Specifies whether a backup of the destination should be created before
        editing the source I(target).
      - When set to C(true), the module creates a backup file or data set.
      - The backup file name will be returned if I(backup) is C(true)
        on either success or failure of module execution such that data can be retrieved.
    required: false
    type: bool
    default: false
  backup_name:
    description:
      - Specify the USS file name or data set name for the destination backup.
      - If I(src) is a USS file or path, backup_name must be a file
        or path name, and it must be an absolute path name.
      - If the source is an MVS data set, I(backup_name) must be an MVS
        data set name, and the data set must B(not) be preallocated.
      - If it is a Generation Data Set (GDS), use a relative positive name, e.g., I(SOME.CREATION(+1)).
      - If I(backup_name) is not provided, a default name will
        be used. If the source is a USS file or path, the name of the backup
        file will be the source file or path name appended with a
        timestamp, e.g. C(/path/file_name.2020-04-23-08-32-29-bak.tar).

To:

  backup:
    description:
      - Specifies whether a backup of the destination should be created before
        editing the C(target).
      - When set to C(true), the module creates a backup file or data set.
      - The backup file name will be returned if I(backup) is C(true)
        on either success or failure of module execution such that data can be retrieved.
    required: false
    type: bool
    default: false
  backup_name:
    description:
      - Specify the USS file name or data set name for the destination backup.
      - If C(backup_name) is a file, it must be an absolute path with file name.
      - If C(backup_name) is an MVS data set, it must be an MVS
        data set name and the data set must B(not) be allocated.
      - If C(backup_name) is a Generation Data Set (GDS), use a relative positive name, e.g., I(SOME.CREATION(+1)).
      - If C(backup_name) is not provided, the backup will be written to a file and archived appending a timestamp to the archive, e.g., C(/path/file_name.2020-04-23-08-32-29-bak.tar).