es-progress · semseysandor · Sep 23, 2023 · Sep 23, 2023 · Sep 23, 2023
diff --git a/docs/bin.md b/docs/bin.md
@@ -1,14 +1,14 @@
 # Bin
 
-Various shell scripts that can be used as "binaries".
+Various scripts that can be used as "binaries".
 
 ---
 
 ## backup
 
 A wrapper for `rsync`.
-Backups source directory to a different filesystem (drive) as backing up on the same drive sort of defies the goal of backup.
-In archive mode backups are compressed to save disk space.
+Backups source directory to a different file system (drive) as backing up on the same drive sort of defies the goal of backup.
+In archive mode, backups are compressed to save disk space.
 This compression is done by `pigz` which creates standard `gzip` files but spreads the work over multiple processors and cores when compressing so it can utilize modern hardware.
 
 Modes:

diff --git a/docs/index.md b/docs/index.md
@@ -1,16 +1,17 @@
 # Introduction
 
-Hi! :cowboy_hat_face:
+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.
 
-This library consist of standalone shell scripts, called "binaries" (`bin/`) here :wink: and various shell functions (`lib/`).
-Certain functions are useful for interactive use on the command-line, while others makes more sense sourced in scripts.
+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.
 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 library ("lib") and bootstrapping may not be trivial.
+some of them use functions from the function library (`lib/`) and 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
@@ -4,14 +4,14 @@ Library functions are organized by category into smaller files (`lib/*.sh`) so t
 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.
 
 Yet it's possible to include only the lib files you need in a script, it's generally easier to load them all.
-For this purpose there is a loader: (`lib/_loader.sh`). Just source this file and it will source all other libraries.
+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.
 
-For details on how to use loader check [Reference](lib/_loader.md).
+For detailed instructions on using the loader check [Reference](lib/_loader.md).
 
-## Installation steps
+**Installation steps**
 
 1. Clone this repo
     ```

diff --git a/docs/lib/_loader.md b/docs/lib/_loader.md
@@ -1,15 +1,15 @@
 # Loader
 
-Helper to bootstrap libraries. This file sources all library files so functions will get defined and be available.
-Basically you need to source this file in any script where you want to use library functions.
+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.
 
 **Usage in scripts**
 
 ```
 # Source loader
 . /path/to/shell/lib/_loader.sh
 
-# Or use the envvar (recommended for maintainabilty & portability)
+# Or use the envvar (recommended for maintainability & portability)
 . "${ES_SHELL_LOADER}"
 
 # Now functions are defined

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. Prints the disk space used by each sub-directory in any directory in ascending order.
-Also reports how many percent each sub-directory's size takes up in total size.
+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.
 
 **Usage**
 

diff --git a/docs/lib/certificate.md b/docs/lib/certificate.md
@@ -1,10 +1,10 @@
 # Certificate
 
-Functions for managing X509 certificates & keys. Basically a wrapper for `openssl`.
+Functions for managing X509 certificates & keys. Essentially, it serves as a wrapper for `openssl`.
 
-With these functions you can setup your own Certificate Authority (CA) and issue X509 certificates on your behalf which is useful for TLS.
+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.
-Probably it won't be trusted by anybody except you so it can't be used for public sites, but it's great for internal use and Dev/CI environments.
+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.
 
 ---
 

diff --git a/docs/lib/db.md b/docs/lib/db.md
@@ -1,21 +1,21 @@
-# DataBase
+# Database
 
-Functions for MySQL databases.
+Functions for managing MySQL databases, 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 could be useful for debugging as it allows a readable diff for changes in data.
+This can be valuable for debugging as it enables readable diffs for changes in data.
 
 **Usage**
 
 ```
 db-dump-data-db DB [EXTRA]...
 
 Params:
-DB                 DataBase name
+DB                 Database name
 EXTRA              Optional extra params to 'mysqldump'
 ```
 
@@ -32,7 +32,7 @@ This could be useful for debugging as it allows a readable diff for changes in d
 db-dump-data-tables DB TABLE...
 
 Params:
-DB                 DataBase name
+DB                 Database name
 TABLE              Tables to export
 ```
 
@@ -48,23 +48,23 @@ Dump full DB (data in compact form + table structures). This could be used for b
 db-dump-full-db DB [EXTRA]...
 
 Params:
-DB                 DataBase name
+DB                 Database name
 EXTRA              Optional extra params to 'mysqldump'
 ```
 
 ---
 
 ## db-dump-full-tables
 
-Dump specific tables from DB. Data (in compact form) and table structure is exported also.
+Dump specific tables from DB. Data in compact form and table structure is exported also.
 
 **Usage**
 
 ```
 db-dump-full-tables DB TABLE...
 
 Params:
-DB                 DataBase name
+DB                 Database name
 TABLE              Tables to export
 ```
 
@@ -80,7 +80,7 @@ Dump full DB structure. No data exported.
 db-dump-structure-db DB [EXTRA]...
 
 Params:
-DB                 DataBase name
+DB                 Database name
 EXTRA              Optional extra params to 'mysqldump'
 ```
 
@@ -96,7 +96,7 @@ Dump specific table structures from DB. No data exported.
 db-dump-structure-tables DB TABLE...
 
 Params:
-DB                 DataBase name
+DB                 Database name
 TABLE              Tables to export
 ```
 
@@ -112,14 +112,14 @@ Base wrapper for `mysqldump`. The other specific dumper functions add parameters
 db-dump-wrapper PARAMS...
 
 Params:
-PARAMS             Params to 'mysqldump'
+PARAMS             Parameters to 'mysqldump'
 ```
 
 ---
 
 ## db-list-tables
 
-List all tables in a DataBase, each table on a new line for easy further processing.
+List all tables in a Database, each table on a new line for easy further processing.
 Tables can be filtered by pattern where SQL style wildcards are allowed.
 
 **Usage**
@@ -128,7 +128,7 @@ Tables can be filtered by pattern where SQL style wildcards are allowed.
 db-list-tables DB PATTERN
 
 Params:
-DB                 DataBase name
+DB                 Database name
 PATTERN            Pattern to filter tables.
                    SQL wildcards are allowed, e.g. '%cache%'.
 ```
@@ -137,15 +137,15 @@ PATTERN            Pattern to filter tables.
 
 ## db-query
 
-Run single queries on a DataBase.
+Execute single queries on a database.
 
 **Usage**
 
 ```
 db-query DB QUERY [EXTRA]...
 
 Params:
-DB                 DataBase name
+DB                 Database name
 QUERY              Query to execute
 EXTRA              Optional extra params to 'mysql'
 ```
@@ -155,7 +155,7 @@ EXTRA              Optional extra params to 'mysql'
 ## db-replace
 
 Replace all occurences of a string in a Database table. This is basically an ETL (extract-transform-load) operation.
-Table is dumped first, then `sed` substition and changed data imported finally. Import means dropping and recreating table with new data.
+Table is dumped first, then `sed` substitution and changed data imported finally. Import means dropping and recreating table with new data.
 
 Basic Regular Expressions (BRE; no `-r` switch) is used for `sed` so `+`, `?,` and `(`, `)` treated literal.
 Delimiter for `sed` substition command can be changed as well, it defaults to `@` so strings can't contain `@` character.
@@ -167,7 +167,7 @@ If your string contains that character you can select a different delimiter that
 db-replace DB TABLE SEARCH REPLACE [DELIMITER]
 
 Params:
-DB                 DataBase name
+DB                 Database name
 TABLE              Table name
 SEARCH             Search string
 REPLACE            Replace string

diff --git a/docs/lib/dev.md b/docs/lib/dev.md
@@ -1,13 +1,13 @@
 # Development Tools
 
-Tools and utilities for development.
+This section provides a range of utilities and functions to assist in the development process.
 
 ---
 
 ## build-mkdocs
 
-Build an `mkdocs` site (like this one :smiley:).
-Generated site's permission and group changed for serving through Apache (`www-data`).
+Build an MkDocs 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 bump (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 nulled as in common sense.
+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.
 E.g. `1.2.3` becomes `2.0.0` after bumping major version.
 
 **Usage**
@@ -75,7 +75,7 @@ REMOTE             Remote host
 
 ## ppretty-php
 
-Pretty-prints a serialized PHP object/array. Can accept serial string from stdin also so it's great to use in a pipe.
+Pretty prints a serialized PHP object/array. Can accept serial string from stdin also so it's great to use in a pipe.
 
 **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 holds error codes that are exported so they can be used in other scripts as environment vars to indicate error causes.
+The following variables contain error codes that are exported so they can be used in other scripts as environment vars to indicate error reasons.
 
 ```
 _E_ABORT           Program aborted

diff --git a/docs/lib/files.md b/docs/lib/files.md
@@ -6,7 +6,7 @@ Functions for managing files and querying the filesystem.
 
 ## dir-file
 
-Get directory of a file.
+Get the directory of a file.
 
 **Usage**
 
@@ -21,7 +21,7 @@ FILE               File to check
 
 ## dir-parents
 
-Get all parent directory of a dir. By default return parents as a space separated string.
+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.
 
 **Usage**
@@ -50,7 +50,7 @@ dir-script
 
 ## give
 
-Recursively set group ownership and remove all world permissions on directories.
+Recursively set group ownership and remove all world (public) permissions on directories.
 
 **Usage**
 

diff --git a/docs/lib/git.md b/docs/lib/git.md
@@ -18,7 +18,7 @@ ggit-adog
 
 ## ggit-base
 
-Rebase source onto target and force-push rebased branch to remote.
+Rebase source onto target and forcefully push rebased branch to the remote repository.
 
 **Usage**
 
@@ -35,7 +35,7 @@ REMOTE             Remote repository to pull and push. Defaults to 'origin'.
 
 ## ggit-diff
 
-Show only a summarized diff: list changed files and number of changed lines.
+Show a summarized difference: list changed files and the number of changed lines.
 
 **Usage**
 
@@ -67,7 +67,7 @@ COMMITS            Numer of commits to go back from HEAD
 
 ## ggit-merge
 
-Merge source branch into target branch. This includes several steps:
+Merge the source branch into the target branch (performs a fast-forward merge). This includes several steps:
 
 1. Checkout _source_ branch and pull remote changes from remote repo
 1. Checkout _target_ branch and pull remote changes from remote repo
@@ -105,7 +105,7 @@ SHA                Create patch from this commit specified by SHA
 
 ## ggit-pull
 
-Pull local branch from remote. Also update submodules.
+Pull the local branch from the remote repository, also updating any submodules.
 
 **Usage**
 

diff --git a/docs/lib/github.md b/docs/lib/github.md
@@ -74,7 +74,7 @@ ghub-issue REPO [EXTRA]...
 Params:
 REPO               GitHub repository, given as "owner/repo-name".
                    Default to repository in current working dir.
-EXTRA              Optional extra params to 'gh'
+EXTRA              Optional extra parameters to 'gh'
 ```
 
 ---
@@ -114,7 +114,7 @@ EXTRA              Optional extra params to 'gh'
 
 ## ghub-pr
 
-Create PR in browser for current repository (repo in working dir).
+Create PR (pull request) in browser for current repository (repo in working dir).
 
 **Usage**
 
@@ -163,7 +163,7 @@ EXTRA              Optional extra params to 'gh'
 
 ## ghub-repo-template
 
-Create new private repository from template repo.
+Create new private repository from GitHub template repository.
 
 **Usage**
 
@@ -231,7 +231,7 @@ EXTRA              Optional extra params to 'gh'
 
 ## ghub-sync-labels
 
-Sync labels from template repo to target repo.
+Sync labels from template repository to target repository.
 Non-existent labels will be created, extra ones deleted, different ones updated to match template.
 After this operation labels will the same as the template. Matching is based on label name.