Documentation spelling and textual updates

Author: ronaldtse

README.adoc

@@ -35,7 +35,7 @@ Upcoming supported platforms:
 
 == link:docs/cli-usage.adoc[Using CLI tool]
 
-== link:docs/c-usage.adoc[Using RNP’s C API in your projects]
+== link:docs/c-usage.adoc[Using the RNP C API in your projects]
 
 == Versioning
 

cmake/info.cmake

@@ -34,7 +34,7 @@ A set of OpenPGP tools for encrypting, decrypting, signing, and \
 verifying files.
 ]=]
 )
-set(PACKAGE_DESCRIPTION_SHORT "Freely licensed PGP implementation")
+set(PACKAGE_DESCRIPTION_SHORT "Freely-licensed OpenPGP PGP implementation")
 set(PACKAGE_LICENSE "BSD")
 
 set(RPM_RELEASE_NUM 1)

docs/c-usage.adoc

@@ -1,101 +1,129 @@
-= Using RNP’s C APIs
+= Using the RNP C API
 
-If you’re a developer and wish to use the RNP library in your projects,
-you can use the examples below to see how it may be done.
+This document is for developers who wish to use RNP as a library in C.
 
-== Samples
+Examples are given below to demonstrate such usage.
+
+== Examples
 
 [TIP]
-.Where to find the examples
+.Location of examples
 ====
-Find the source code for these examples
-under `https://github.com/rnpgp/rnp/blob/master/src/examples/[src/examples]`.
+The source code of these examples can be found under
+`https://github.com/rnpgp/rnp/blob/master/src/examples/[src/examples]`.
 
-If you’re building from source, the examples are built together with the RNP library
-and are available in `src/examples` directory of your build folder.
+If you are planning to build from source, these examples are built
+together with the RNP library and will be available under `src/examples`
+within your build folder.
 ====
 
 [TIP]
 ====
-All samples below use APIs exposed via header file
-`https://github.com/rnpgp/rnp/blob/master/include/rnp/rnp.h[include/rnp/rnp.h]`,
-check it out for more documentation.
+All samples below use APIs exposed via the header file
+`https://github.com/rnpgp/rnp/blob/master/include/rnp/rnp.h[include/rnp/rnp.h]`.
+For further details please refer to the file directly.
 ====
 
-Following sample applications are available:
+The following example applications are available:
+
+`generate`:: Demonstrates generating keys, save/load of keyrings, exporting keys.
 
-`generate`:: Includes code which shows how to generate keys, save/load keyrings, export keys.
+`encrypt`:: Demonstrates how to encrypt a file using a password and/or key.
 
-`encrypt`:: Includes code which shows how to encrypt file, using the password and/or key.
+`decrypt`:: Demonstrates how to decrypt OpenPGP data using a key and/or password.
 
-`decrypt`:: This one shows how to decrypt OpenPGP data, using the key or password.
+`sign`:: Demonstrates how to sign messages, using one or more keys from a loaded keyring.
 
-`sign`:: Shows how to sign messages, using the key(s) from loaded keyring.
+`verify`:: Demonstrates how to verify signed messages using dynamic keys fetching
+  (using a sample key provider implementation).
 
-`verify`:: Shows how to verify signed messages using dynamic keys fetching (sample key provider implementation).
+`dump`:: Demonstrates how to dump OpenPGP packet information.
 
-`dump`:: Shows how to dump OpenPGP packet information.
 
-=== https://github.com/rnpgp/rnp/blob/master/src/examples/generate.c[generate.c]
+=== generate.c
+
+Location: https://github.com/rnpgp/rnp/blob/master/src/examples/generate.c
 
 This example is composed from 2 functions:
 
- * `ffi_generate_keys()`: this shows how to generate and save different key types
-   (RSA and EDDSA/Curve25519) using the JSON key description.
-   This also demonstrates the usage of password provider.
+* `ffi_generate_keys()`: Demonstrates how to generate and save different key types
+   (RSA and EDDSA/Curve25519) using JSON key description.
+   Also demonstrates usage of the password provider.
 +
 Keyrings will be saved to files `pubring.pgp` and `secring.pgp` in the current directory.
 You can use `rnp --list-packets pubring.pgp` to check the properties of the generated key(s).
 
- * `ffi_output_keys()`: This shows how to load keyrings,
-   search for the keys (in helper functions `ffi_print_key()`/`ffi_export_key()`),
-   and export them to memory or file in armored format.
+* `ffi_output_keys()`: Demonstrates how to load keyrings,
+   search for keys (in helper functions `ffi_print_key()`/`ffi_export_key()`),
+   and how to export them to memory or file in armored format.
+
+=== encrypt.c
+
+Location: https://github.com/rnpgp/rnp/blob/master/src/examples/encrypt.c
+
+This code example does the following:
+
+* first loads a public keyring (`pubring.pgp`) (created by the `generate.c` example)
+* then creates an encryption operation structure and
+* configures it with various options (including the setup of password encryption and public-key encryption).
 
-=== https://github.com/rnpgp/rnp/blob/master/src/examples/encrypt.c[encrypt.c]
+The result is the encrypted and armored (for easier reading) message
+`RNP encryption sample message`.
 
-This code sample first loads public keyring (`pubring.pgp`) (created by the “generate.c” example),
-then creates encryption operation structure and configures it with various options
-(including the setup of password encryption and public-key encryption).
+This message is saved to the file `encrypted.asc` in current directory.
 
-The result is the encrypted and armored (for easier reading) message `RNP encryption sample message`.
-It is saved to the file `encrypted.asc` in current directory.
+What you can do after:
 
-You can investigate it via the `rnp --list-packets encrypted.asc` command.
-Also, you may want to decrypt saved file via `rnp --keyfile secring.pgp -d encrypted.asc`.
+* Inspect the message with `rnp --list-packets encrypted.asc`.
+* Decrypt the saved file via `rnp --keyfile secring.pgp -d encrypted.asc`.
 
-=== https://github.com/rnpgp/rnp/blob/master/src/examples/decrypt.c[decrypt.c]
+=== decrypt.c
 
-This example uses keyrings generated in the “generate.c” sample to decrypt messages
-encrypted by the “encrypt.c” sample.
+Location: https://github.com/rnpgp/rnp/blob/master/src/examples/decrypt.c
 
-It shows how to decrypt message with password or with a key
-and implements custom password provider for decryption or key password.
+This example uses keyrings generated from the `generate.c` example
+to decrypt messages encrypted by the `encrypt.c` example.
 
-Decrypted message is saved to the memory and then printed to the stdout.
+This example demonstrates how to decrypt message with a password or with a key,
+and implements a custom password provider for decryption via key or key password.
 
-=== https://github.com/rnpgp/rnp/blob/master/src/examples/sign.c[sign.c]
+The decrypted message is saved to memory and then printed to the `stdout`.
 
-This sample uses keyrings generated in the preceding “generate.c” sample.
+=== sign.c
 
-This sample configures signing context and signs the message, saving it to the `signed.asc` file.
-Attached signature is used, i.e. the data is encapsulated into the resulting message.
+Location: https://github.com/rnpgp/rnp/blob/master/src/examples/sign.c
 
-You can investigate the signed message by issuing `rnp --list-packets signed.asc` command.
-To verify message, use `rnp --keyfile pubring.pgp -v signed.asc`.
+This example uses keyrings generated in the preceding `generate.c` example.
 
-=== https://github.com/rnpgp/rnp/blob/master/src/examples/verify.c[verify.c]
+It demonstrates configuration of a signing context, signing of the message,
+and the saving of the detached signature to the `signed.asc` file.
 
-This example uses keyrings generated in the “generate.c” sample.
+Then the attached signature is used: i.e. the data is encapsulated into
+the resulting message.
+
+What you can do after:
+
+* Inspect the signed message with `rnp --list-packets signed.asc`.
+* Verify the message with `rnp --keyfile pubring.pgp -v signed.asc`.
+
+=== verify.c
+
+Location: https://github.com/rnpgp/rnp/blob/master/src/examples/verify.c[
+
+This example uses keyrings generated in the `generate.c` example.
 
 However, instead of loading the whole keyring, it implements dynamic key fetching
 via custom key provider (see function `example_key_provider`).
 
-After verification this sample outputs the verified embedded message
-and all signatures with signing key ids and statuses.
+After verification, it outputs the verified embedded message
+and all signatures to `stdout` (with signing key IDs and statuses).
+
+=== dump.c
 
-=== https://github.com/rnpgp/rnp/blob/master/src/examples/dump.c[dump.c]
+Location: https://github.com/rnpgp/rnp/blob/master/src/examples/dump.c[
 
-This example dumps OpenPGP packet information from the input stream (stdin or filename), 
-tuned with flags passed via command line interface.
+This example dumps OpenPGP packet information from the input stream
+(via `stdin` or filename), tuned with flags passed via the
+command-line interface.
 
-Resulting human-readable text or JSON is dumped to stdout.
+The resulting human-readable text or JSON is printed to `stdout`.

docs/cli-usage.adoc

@@ -1,8 +1,8 @@
-= Using the RNP command-line tool
+= Using the RNP command-line interface
 
-== Generating an RSA Private Key
+== Generating an RSA private key
 
-By default `rnpkeys  --generate-key` will generate 2048-bit RSA key.
+By default, `rnpkeys  --generate-key` generates a 2048-bit RSA key.
 
 [source,console]
 ----
@@ -17,9 +17,13 @@ rnpkeys --generate-key --homedir=${keydir}
 rnpkeys: generated keys in directory ${keydir}/6ed2d908150b82e7
 ----
 
-In case you're curious, `6ed2d...` is the key fingerprint.
+NOTE: Here `6ed2d...` is the key fingerprint.
 
-In order to use fully featured key pair generation ``--expert`` flag should be used. With this flag added to  ``rnpkeys --generate-key`` user has a possibility to generate keypair for any supported algorithm and/or key size.
+In order to use fully-featured key-pair generation, the `--expert` flag
+should be used.
+
+With this flag added to `rnpkeys --generate-key`, the user will be
+able to generate a key-pair for any supported algorithm and/or key size.
 
 Example:
 
@@ -51,7 +55,7 @@ Repeat password for d45592277b75ada1:
 ----
 
 
-== Listing Keys
+== Listing keys
 
 [source,console]
 ----
@@ -69,7 +73,7 @@ rnpkeys --list-keys --homedir=${keyringdir}
 ----
 
 
-== Signing a File
+== Signing a file
 
 
 === Signing in binary format
@@ -84,7 +88,7 @@ rnp --sign --homedir=${keyringdir} ${filename}
 Creates `${filename}.gpg` which is an OpenPGP message that includes the
 message together with the signature as a 'signed message'.
 
-This type of file can be verified by:
+This type of file can be verified with:
 
 * `rnp --verify --homedir=${keyringdir} ${filename}.gpg`
 
@@ -101,12 +105,12 @@ rnp --sign --detach --homedir=${keyringdir} ${filename}
 Creates `${filename}.sig` which is an OpenPGP message in binary
 format, that only contains the signature.
 
-This type of file can be verified by:
+This type of file can be verified with:
 
 * `rnp --verify --homedir=${keyringdir} ${filename}.sig`
 
 
-=== Signing in Armored (ASCII-Armored) format
+=== Signing in armored ("`ASCII-armored`") format
 
 [source,console]
 ----
@@ -116,21 +120,23 @@ rnp --sign --armor --homedir=${keyringdir} ${filename}
 =>
 
 Creates `${filename}.asc` which is an OpenPGP message in ASCII-armored
-format, including the message together with the signature as a 'signed
-message'.
+format, including the message together with the signature as a
+"`signed message`".
 
-This type of file can be verified by:
+This type of file can be verified with:
 
 * `rnp --verify --homedir=${keyringdir} ${filename}.asc`
 
 
 === Other options
 
-* `--clearsign` option will append a separate PGP Signaure to the end of
-  the message (the new output)
+`--clearsign`::
+appends a separate OpenPGP signature to the end of the newly
+signed message.
 
-* `--detach` option will append a separate PGP Signaure to the end of
-  the message (the new output)
+`--detach`::
+saves the OpenPGP signature in a separate file from the newly
+signed message.
 
 
 == Encrypt
@@ -143,7 +149,7 @@ rnp --encrypt --homedir=${keyringdir} ${filename}
 
 =>
 
-Creates `${filename}.gpg`.
+Creates `${filename}.gpg`, which is an encrypted OpenPGP message.
 
 
 == Decrypt
@@ -155,12 +161,14 @@ rnp --decrypt --homedir=${keyringdir} ${filename}.gpg
 
 =>
 
-Creates `${filename}`.
+Creates `${filename}`, the decrypted form of the `${filename}.gpg`
+encrypted OpenPGP message.
 
 
-== Check binary version
+== Check version
 
 The output of `rnp --version` contains the `git` hash of the version
-the binary was built from, which value is generated when `cmake` runs.
+the binary was built from, of which value is generated when `cmake` runs.
 
-Consequently, a release tarball generated with `make dist` will contain this hash version.
+Consequently, a release tarball generated with `make dist` will
+contain this hash version.

docs/develop.adoc

@@ -55,7 +55,7 @@ A good example of using a branch would be:
 
 Branch names may vary but should be somewhat descriptive, with words
 separated by hyphens. It is also helpful to start the branch name with
-your github username, to make it clear who created the branch and
+your GitHub username, to make it clear who created the branch and
 prevent naming conflicts.
 
 Remember that branch names may be preserved permanently in the commit
@@ -459,6 +459,6 @@ Platforms:
 
 * RHEL/CentOS: @dewyatt
 * BSD:
-* Windows:
-* macOS / iOS / homebrew: @ni4
+* Windows: @rrrooommmaaa
+* macOS / iOS / Homebrew: @ni4
 * Debian: @zgyarmati

docs/develop/packaging.adoc

@@ -61,7 +61,7 @@ make package
 
 === 5. Check and Install the RPM
 
-It may be helpful to run rpmlint on the RPM and note new warnings or errors.
+It may be helpful to run `rpmlint` on the RPM and note new warnings or errors.
 
 [source,console]
 --