style/grammatical mods to the new README section.

Author: d-w-moore

README.md

@@ -132,68 +132,64 @@ required when they are placed in the environment file.
 Creating PAM or Native Credentials File (.irodsA)
 -------------------------------------------------
 
-Two free functions exist which allow the user to create encoded authentication files
-for use in the client's iRODS login environment:
-```
-irods.client_init.write_native_irodsA_file
-irods.client_init.write_pam_irodsA_file
-```
+Use of following free functions will allow the creation of encoded authentication files for use in
+the client's iRODS login environment:
+   - `irods.client_init.write_native_irodsA_file`
+   - `irods.client_init.write_pam_irodsA_file`
 
 These functions can roughly be described as duplicating the function of iinit (from iCommands),
-once a valid irods_environment.json has already been created.
+provided that a valid irods_environment.json has already been created.
 
 Each takes a cleartext password and writes an appropriately processed version of it
-into an .irodsA "password" or "secrets" in the appropriate location.
+into an .irodsA "password" (also known as "credentials" or "secrets") file in the appropriate
+location.  That location is `~/.irods/.irodsA` unless IRODS_AUTHENTICATION_FILE has been set
+in the command shell to dictate an alternative file path.
 
-That location is  ~/.irods/.irodsA) unless IRODS_AUTHENTICATION_FILE has
-been set with an alternate file path in the OS environment.
-
-As an example, for the `native` authentication scheme, it is simple to create the
-.irodsA file directly:
+As an example, here we write a native .irodsA file using the first of the two functions.  We
+pass in only the required argument, with its value determined by the input terminal via the
+Python `getpass` facility: 
 
 ```bash
 $ echo '{ "irods_user_name":"rods", ...  }'> ~/.irods/irods_environment.json
 $ python -c "import irods.client_init, getpass
 irods.client_init.write_native_irodsA_file(getpass.getpass('Enter iRODS password -> '))"
 ```
 
-If an .irodsA file already exists, it will be overwritten by default; however, if these functions'
+By default, if an .irodsA file already exists, it will be overwritten. If, however, these functions'
 overwrite parameter is set to `False`, an exception of type `irods.client_init.irodsA_already_exists`
-will be raised to warn of an older .irodsA file that might otherwise be overwritten.
+is raised to warn of any older .irodsA file that might otherwise have been overwritten.
 
-Equivalently, we can issue the following command.
+Equivalently to the above, we can issue the following command.
 
 ```bash
 $ prc_write_irodsA.py native <<<"${MY_CURRENT_IRODS_PASSWORD}"
 ```
 
-The redirect may be left off, in which case the user is prompted for the iRODS password
-and echo of the keyboard input will be suppressed.  (Regardless which technique is used,
-no password will be visible on the terminal during or after input.)
+Or the redirect may be left off, in which case the user is prompted for the iRODS password
+and echo of the keyboard input will be suppressed, in the style of iinit.  Regardless
+which technique is used, no password will be visible on the terminal during or after input.
 
 For the `pam_password` scheme, typically SSL/TLS must first be enabled to avoid sending data related
 to the password - or even sending the raw password itself - over a network connection in the clear.
 
 Thus, for `pam_password` authentication to work well, we should first ensure when setting up the
 client environment that the `irods_environment.json` file includes the appropriate
-SSL/TLS connection parameters.  If present, `iinit` can be used to verify this condition is fulfilled,
-as of course its invocation would create a valid .irodsA from merely prompting the user for their
-PAM password
+SSL/TLS connection parameters.  If present, `iinit` can be used to verify this prerequisite is
+fulfilled, as in that case its invocation would create a valid .irodsA from merely prompting the user
+for their PAM password.
 
-But if we wish to use the Python client for this purpose instead, we can run:
+Again, this can also be done either using the free function directly:
 
 ```python
 irods.client_init.write_pam_irodsA_file(getpass.getpass('Enter current PAM password -> '))
 ```
 
-Or from the Bash command shell, we simply run:
+or from the Bash command shell:
 
 ```bash
 $ prc_write_irodsA.py pam_password <<<"${MY_CURRENT_PAM_PASSWORD}"
 ```
 
-again leaving out the redirection if password prompting is preferable.
-
 As a final note, in the "pam_password" scheme the default SSL requirement can be disabled (for purposes
 of testing only):
 
@@ -209,7 +205,7 @@ home = session.collections.get('/tempZone/home/alice')
 ```
 
 Note however that in future releases of iRODS it is possible that extra SSL checking could be
-implemented server-side, at which point, the above code could not be guaranteed to work.
+implemented server-side, at which point the above code could not be guaranteed to work.
 
 Legacy (iRODS 4.2-compatible) PAM authentication
 ------------------------------------------------