es-progress · semseysandor · Aug 18, 2024 · Aug 18, 2024 · Aug 18, 2024
diff --git a/docs/bin.md b/docs/bin.md
@@ -172,13 +172,13 @@ OUTPUT             Output generated primes to this file.
 
 ## pass-man
 
-Manages a `pass` password store which is inside a `tomb`.
+Manages a `pass` password store located inside a `tomb`.
 
 Available actions:
 
 -   open: open password store in tomb
 -   close: close password store
--   generate: generate a password but not save as a pass. Useful if you just need a strong key.
+-   generate: generate a password but not save it as a pass. Useful if you just need a strong key.
 -   retrieve: get password from store
 
 **Usage**
@@ -188,7 +188,7 @@ Usage: pass-man ACTION [TARGET] [EXTRA]...
 
 Params:
 ACTION             Action to perform (open, close, generate, retrieve)
-TARGET             Path to password in password store (mandatory for 'retrieve' action)
+TARGET             Path to password in the password store (mandatory for the 'retrieve' action)
 EXTRA              Extra arguments to 'pass'
 ```
 
@@ -197,10 +197,10 @@ EXTRA              Extra arguments to 'pass'
 ## sign-kernel-modules
 
 Sign kernel modules with a Machine Owner Key (MOK).
-Some modules are not signed by Ubuntu so kernel won't load them.
+Some modules are not signed by Ubuntu, so kernel won't load them.
 After signing they can be loaded with `modprobe`.
 
-For this you need a MOK key and certificate and it needs to be enrolled in EFI:
+You need a MOK key and certificate, which must be enrolled in EFI:
 
 1. Generate MOK key
     ```bash
@@ -214,7 +214,7 @@ For this you need a MOK key and certificate and it needs to be enrolled in EFI:
     ```bash
     mokutil --import MOK_CERT
     ```
-1. Reboot and perform enrolling
+1. :red_circle: Reboot and complete the enrollment
 
 **Usage**
 

diff --git a/docs/index.md b/docs/index.md
@@ -5,13 +5,13 @@ Welcome! :cowboy_hat_face:
 Here you can find the documentation for [_ES-Progress Bash Library_](https://github.com/es-progress/shell){target=\_blank}.
 It aims to provide comprehensive guidance on using this library.
 
-The library consists of standalone shell scripts, referred to as "binaries" (`bin/`) here :wink: and various shell functions (`lib/`).
-Certain functions are designed for interactive use on the command-line, while others make more sense sourced in scripts.
+The library consists of standalone shell scripts, referred to here as "binaries" (`bin/`) :wink: and various shell functions (`lib/`).
+Certain functions are designed for interactive use on the command line, while others are better suited for sourcing in scripts.
 It was written with Bash in mind therefore portability was not a requirement.
 
 First, check the [Installation instructions](install.md).
-Though most of the "binaries" are intended for standalone use which you can simply download and run,
-some of them use functions from the function library (`lib/`) and bootstrapping may not be trivial and require additional setup.
+Though most of the "binaries" are intended for standalone use and can be simply downloaded and run,
+some of them use functions from the function library (`lib/`), so bootstrapping may not be trivial and require additional setup.
 
 Then you can find the reference documentation for each script and function.
 

diff --git a/docs/install.md b/docs/install.md
@@ -1,32 +1,32 @@
 # Installation
 
-Library functions are organized by category into smaller files (`lib/*.sh`) so they're easier to manage.
-Usually functions use each other, so this makes using them a bit harder as several files need to be sourced in order to define all functions.
+Library functions are organized by category into smaller files (`lib/*.sh`), so they're easier to manage.
+Functions often depend on each other, making it necessary to source several files to define all functions.
 
-Yet it's possible to include only the lib files you need in a script, it's generally easier to load them all.
+Yet it's possible to include only the necessary lib files in a script, it's generally easier to load them all.
 For this purpose there is a loader (`lib/_loader.sh`). Simply source this file, and it will automatically source all other libraries.
 
-In supplied scripts (`bin/`) loader is referenced by an environment variable (`ES_SHELL_LOADER`).
-It's recommended to use this env var in your scripts also.
+In the supplied scripts (`bin/`), the loader is referenced by an environment variable (`ES_SHELL_LOADER`).
+It's recommended to use this env var in your scripts as well.
 
-For detailed instructions on using the loader check [Reference](lib/_loader.md).
+For detailed instructions on using the loader, check [Reference](lib/_loader.md).
 
 **Installation steps**
 
 1. Clone Git repository
     ```bash
     git clone https://github.com/es-progress/shell.git SHELL_DIR
     ```
-1. Set `ES_SHELL_LOADER` to point to `lib/_loader.sh`. Best to put this in your `.bashrc`.
+1. Set `ES_SHELL_LOADER` to point to `lib/_loader.sh`. It's best to add this to your `.bashrc`.
     ```bash
     export ES_SHELL_LOADER="SHELL_DIR/lib/_loader.sh"
     ```
-1. (Optional) Add `bin` to your `PATH` so you can run scripts just by name
+1. (Optional) Add `bin` to your `PATH` to run scripts by name
     ```bash
     PATH="SHELL_DIR/bin:${PATH}"
     ```
 
 !!! tip
 
-    Source loader in your `.bashrc` and all functions are ready to use in your terminal.
-    Actually some of them are meant for interactive use on the command line!
+    Source loader in your `.bashrc` and all functions will be ready to use in your terminal.
+    In fact, some of them are for interactive use on the command line!
diff --git a/docs/lib/_loader.md b/docs/lib/_loader.md
@@ -1,10 +1,10 @@
 # Loader
 
-Helper to bootstrap libraries. This file sources all library files so functions will be defined and available.
+A helper to bootstrap libraries. This file sources all library files so functions will be defined and available.
 Basically, you need to source this file in any script where you want to use library functions.
 
 Also, you can extend this loader to load your local library files too!
-Create your loader script that sources the local libraries and just point `ES_SHELL_LOADER_LOCAL` environment variable to it (e.g. `ES_SHELL_LOADER_LOCAL=$HOME/.local/lib/myloader.sh`), and they will be sourced.
+Create your loader script that sources the local libraries and just point `ES_SHELL_LOADER_LOCAL` environment variable to it (e.g. `ES_SHELL_LOADER_LOCAL=$HOME/.local/lib/my_loader.sh`), and they will be sourced.
 
 **Usage in scripts**
 
@@ -20,8 +20,8 @@ check-root
 error-exit "Nothing to do"
 ```
 
-If you do the envvar way, you need to set `/path/to/shell/lib/_loader.sh` in `ES_SHELL_LOADER`.
-You can do this in `.bashrc` or just when running a script:
+If you use the envvar method, you need to set `/path/to/shell/lib/_loader.sh` in `ES_SHELL_LOADER`.
+You can do this in your `.bashrc` or when running a script:
 
 ```bash
 ES_SHELL_LOADER=/path/to/lib/_loader.sh backup

diff --git a/docs/lib/analytics.md b/docs/lib/analytics.md
@@ -6,8 +6,8 @@ Functions for statistics and analysis.
 
 ## anal-disk-usage
 
-Analyze disk usage. Displays the disk space used by each sub-directory in any directory in ascending order.
-Additionally, it reports the percentage of total size occupied by each sub-directory.
+Analyze disk usage. Display the disk space used by each subdirectory in any directory in ascending order.
+Additionally, it reports the percentage of the total size occupied by each sub-directory.
 
 **Usage**
 

diff --git a/docs/lib/certificate.md b/docs/lib/certificate.md
@@ -1,17 +1,17 @@
 # Certificate
 
-Functions for managing X509 certificates & keys. Essentially, it serves as a wrapper for `openssl`.
+Functions for managing X509 certificates & keys. It essentially serves as a wrapper for `openssl`.
 
-These functions offer a way to set up your own Certificate Authority (CA) and issue X509 certificates on your behalf which is useful for TLS (Transport Layer Security).
-Then only your Root CA certificate needs to be trusted by clients and all your issued certificates will be trusted too.
-It may not be trusted by anyone except you. So it can't be used for public sites, but it's great for internal use and Dev/CI environments.
+These functions offer a way to set up your own Certificate Authority (CA) and issue [X509 Certificates](https://en.wikipedia.org/wiki/X.509){target=\_blank} (a standard defining the format of public key certificates) on your behalf which are useful for TLS (Transport Layer Security).
+Only your Root CA certificate needs to be trusted by clients, and all your issued certificates will be trusted too.
+It may not be trusted by anyone except you. So it can't be used for public sites. However, it's great for internal use and Dev/CI environments.
 
 ---
 
 ## cert-create
 
-Create an X509 certificate. This combines `csr-create` and `csr-sign`.
-Use subject to insert any details about the site.
+Create an X509 certificate by combining `csr-create` and `csr-sign`.
+Use the subject to insert any details about the site.
 
 Subject example: `/C=CountryCode/ST=State/L=City/O=Your Company/CN=Your site URL`.
 
@@ -33,7 +33,7 @@ VALIDITY           Certificate validity in days
 
 ## cert-key
 
-Create a 4096 bit RSA private key.
+Create a 4096-bit RSA private key.
 
 **Usage**
 
@@ -50,7 +50,7 @@ EXTRA              Optional extra params to 'openssl-genpkey'
 ## cert-selfsigned
 
 Create self-signed certificate. This could be used as a Root CA certificate.
-Use subject to insert any details about the certificate.
+Use the subject to insert any details about the certificate.
 
 Subject example: `/C=CountryCode/ST=State/L=City/O=ACME Company/CN=ACME Root CA`.
 
@@ -88,7 +88,7 @@ EXTRA              Optional extra params to 'openssl-x509'
 ## csr-create
 
 Create a Certificate Signing Request (CSR).
-Use subject to insert any details about the site.
+Use the subject to insert any details about the site.
 
 Subject example: `/C=CountryCode/ST=State/L=City/O=Your Company/CN=Your site URL`.
 

diff --git a/docs/lib/db.md b/docs/lib/db.md
@@ -1,13 +1,13 @@
 # Database
 
-Functions for managing MySQL databases, including data export, structure export, querying, and more.
+Functions for managing MySQL databases (DB), including data export, structure export, querying, and more.
 
 ---
 
 ## db-dump-data-db
 
-Dump full DB. Only data (each record on a separate row) is exported with no table structures.
-This can be valuable for debugging as it enables readable diffs for changes in data.
+Dump the full DB. Only data (each record on a separate row) are exported with no table structures.
+This can be valuable for debugging, as it enables readable diffs for changes in data.
 
 **Usage**
 
@@ -23,7 +23,7 @@ EXTRA              Optional extra params to 'mysqldump'
 
 ## db-dump-data-tables
 
-Dump specific tables from DB. Only data (each record on a separate row) is exported with no table structures.
+Dump specific tables from the DB. Only data (each record on a separate row) are exported with no table structures.
 This could be useful for debugging as it allows a readable diff for changes in data. Also for export-change-import operations.
 
 **Usage**
@@ -40,7 +40,7 @@ TABLE              Tables to export
 
 ## db-dump-full-db
 
-Dump full DB (data in compact form + table structures). This could be used for backups and migrations.
+Dump the full DB (data in compact form + table structures). This could be used for backups and migrations.
 
 **Usage**
 

diff --git a/docs/lib/dev.md b/docs/lib/dev.md
@@ -6,7 +6,7 @@ This section provides a range of utilities and functions to assist in the develo
 
 ## build-mkdocs
 
-Build an MkDocs site (like this one :smiley:).
+Build an [MkDocs](https://www.mkdocs.org){target=\_blank} site (like this one :smiley:).
 The generated site's permissions and group are changed for serving through Apache (`www-data`).
 
 **Usage**
@@ -24,8 +24,8 @@ EXTRA              Optional extra params to 'mkdocs build'
 
 ## bump-version
 
-Function to increment (increase by one) the version-number if semantic versioning is used.
-If the major or minor version is bumped then the less important parts will be reset.
+Function to increment (increase by one) the version number if [Semantic Versioning](https://semver.org){target=\_blank} is used.
+If the major or minor version is bumped, the less important parts will be reset.
 E.g. `1.2.3` becomes `2.0.0` after bumping major version.
 
 **Usage**
@@ -43,9 +43,9 @@ PART               Which part of the version to increase (major, minor, patch)
 
 ## debug-tunnel-open
 
-Open an SSH tunnel to a remote XDebug host. This way you can debug remote PHP applications.
+Open an SSH tunnel to a remote [XDebug](https://xdebug.org){target=\_blank} host, allowing you to debug remote PHP applications.
 This can be very handy to track down nasty bugs on production servers.
-Though it's generally true that never debug in production environment, in some cases - if used correctly - this can save so much time...
+Though it's generally advised to never debug in production environment, in some cases - if used correctly - this can save so much time...
 
 **Usage**
 

diff --git a/docs/lib/error.md b/docs/lib/error.md
@@ -6,7 +6,7 @@ Functions for handling errors.
 
 ## Error codes
 
-The following variables contain error codes that are exported so they can be used in other scripts as environment vars to indicate error reasons.
+The following variables contain error codes that are exported so they can be used in other scripts as environment variables to indicate error reasons.
 
 ```
 _E_ABORT           Program aborted
@@ -25,7 +25,7 @@ exit "${_E_ABORT}"
 ## abort
 
 Print error message ("aborted") and exit program with `_E_ABORT` exit code.
-Use this in standalone scripts. If used on the commandline it exits your shell.
+Use this in standalone scripts. If used on the command line it exits your shell.
 
 **Usage**
 

diff --git a/docs/lib/files.md b/docs/lib/files.md
@@ -21,8 +21,8 @@ FILE               File to check
 
 ## dir-parents
 
-Get all parent directory of a dir. By default, return parents as a space-separated string.
-The separator character can be specified if whitespace contained dirs are a concern.
+Retrieve all parent directories of a dir. By default, return parents as a space-separated string.
+The separator character can be specified if directories containing whitespace are a concern.
 
 **Usage**
 

diff --git a/docs/lib/git.md b/docs/lib/git.md
@@ -18,15 +18,15 @@ ggit-adog
 
 ## ggit-base
 
-Rebase source onto target and forcefully push rebased branch to the remote repository.
+Rebase source branch onto target branch and forcefully push the rebased branch to the remote repository.
 
 **Usage**
 
 ```
 ggit-base SOURCE [TARGET] [REMOTE]
 
 Params:
-SOURCE             Branch to rebase
+SOURCE             Branch to be rebased
 TARGET             Rebase onto this branch. Defaults to 'main'.
 REMOTE             Remote repository to pull and push. Defaults to 'origin'.
 ```
@@ -43,7 +43,7 @@ Show a summarized difference: list changed files and the number of changed lines
 ggit-diff BRANCH_A BRANCH_B
 
 Params:
-BRANCH_A           Branch to compare to
+BRANCH_A           Branch to compare against
 BRANCH_B           Branch to compare with
 ```
 

diff --git a/docs/lib/github.md b/docs/lib/github.md
@@ -1,13 +1,13 @@
 # GitHub
 
-Wrapper for GitHub CLI tool: `gh`.
+Wrapper for [GitHub CLI](https://cli.github.com){target=\_blank} tool: `gh`.
 
 ---
 
 ## ghub-foreach-owner
 
-Run `gh` command for each repository of user. Useful to run any other function in this category for each repo.
-E.g. Open all repository in browser: `ghub-foreach-owner OWNER ghub-open`.
+Run a `gh` command for each repository of a user. Useful to run any other function in this category for each repo.
+E.g. Open all repository in the browser: `ghub-foreach-owner OWNER ghub-open`.
 
 **Usage**
 
@@ -25,7 +25,7 @@ ARGS               Optional extra params to COMMAND.
 
 ## ghub-foreach-topic
 
-Run `gh` command for each repository of user, filtered by topic.
+Run a `gh` command for each repository of a user, filtered by topic.
 Useful to run any other function in this category for each repo.
 E.g. Sync labels from master repo: `ghub-foreach-topic OWNER TOPIC ghub-sync-labels TEMPLATE`.
 

diff --git a/docs/lib/network.md b/docs/lib/network.md
@@ -6,7 +6,7 @@ Utilities for networking.
 
 ## dns-mail
 
-Retrieve email related DNS records: SPF, DMARC and DKIM.
+Retrieve email related DNS records: [SPF](https://en.wikipedia.org/wiki/Sender_Policy_Framework){target=\_blank} (Sender Policy Framework: a method to detect forged sender addresses), [DMARC](https://dmarc.org/){target=\_blank} (Domain-based Message Authentication, Reporting & Conformance: an email policy, and reporting protocol) and [DKIM](https://en.wikipedia.org/wiki/DomainKeys_Identified_Mail){target=\_blank} (DomainKeys Identified Mail: an authentication method to digitally sign emails).
 
 **Usage**
 
@@ -23,9 +23,9 @@ SELECTOR           DKIM selector
 ## iplocation
 
 Query [Ipstack](https://ipstack.com/){target=\_blank} for GeoIP data.
-You need an Ipstack account and an access key to query info.
+You need an Ipstack account and an access key to query information.
 This function looks for this token in an environment variable: `IPSTACK_TOKEN`.
-You can configure this in your `.bashrc` or if you're generally not happy by providing credentials in env vars, you can give token just for this command: `IPSTACK_TOKEN=yourtoken iplocation 8.8.8.8`.
+You can configure this in your `.bashrc` or if you prefer not to provide credentials in env vars, you can give token just for this command: `IPSTACK_TOKEN=yourtoken iplocation 8.8.8.8`.
 
 **Usage**