docs: Enhance Documentation

.github/workflows/release-prepare.yml

@@ -38,6 +38,11 @@ jobs:
           echo "prev_version=$(cat .version)" >> $GITHUB_OUTPUT
           bin/version.sh ${{ github.event.inputs.release_type }}
           echo "next_version=$(cat .version)" >> $GITHUB_OUTPUT
+      - name: Update Documentation
+        id: update-docs
+        run: |
+          echo "Update documentation for version ${{ steps.version.outputs.next_version }}"
+          bin/docs.sh
       - name: Create pull request
         id: create-pull-request
         # https://github.com/peter-evans/create-pull-request

README.md

@@ -1,6 +1,6 @@
 # lib-bash – Bash Libraries
 
-![Lib-Bash Decorative Image](img/LibBashGitHubSocialPreview.jpg)
+![Lib-Bash Decorative Image](docs/img/LibBashGitHubSocialPreview.jpg)
 
 A set of libraries to use from within your Bash scripts.
 
@@ -51,6 +51,20 @@ ${COLOR_YELLOW}This is yellow text.${COLOR_RESET}
 EOF
 ```
 
+### lib_gnucompat
+
+Utility functions and dynamically defined constants for scripts preferring
+(or requiring) GNU compatible tooling. Meant especially for systems such as
+MacOS, to prefer GNU-Tools like `coreutils` by preferring prefixed tools like
+`gsed`, `gawk`.
+
+**Usage Examples**:
+
+```bash
+echo "Hello, World!" | \
+  "${SED}" --regexp-extended "s/World/GNU/g"
+```
+
 ### lib_init
 
 Apply general recommended strictness settings for Bash scripts. Includes support

bin/doc-single.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+###
+### Script to generate Markdown documentation for a single script.
+###
+### In contrast to more sophisticated approaches, this script just generates
+### the Markdown from lines starting with three hashes (###) and the following
+### line.
+###
+### Usage:
+###
+### ```bash
+### doc-single.sh <script> > <output>
+### ```
+###
+
+set -o errexit  # abort on nonzero exit status
+set -o nounset  # abort on unbound variable
+set -o pipefail # don't hide errors within pipes
+
+function main() {
+  local script="${1?Missing script}"
+  local line
+  # Boolean flag, to signal, if the previous line was an empty documentation
+  # line. This is used to prevent multiple empty lines in the output.
+  local empty=0
+
+  while IFS= read -r line; do
+    if [[ "${line}" =~ ^"###" ]]; then
+      local content="${line:3}"
+      # If first char is a space, remove it. Do nothing, especially if
+      # the line is empty. Do not remove more than once space, as it might
+      # be intentional.
+      content="${content#"${content%%[![:space:]]*}"}"
+
+      if [[ -n "${content}" ]]; then
+        # If the previous line was an empty line, print an empty line to
+        # separate the sections.
+        if ((empty == 1)); then
+          echo
+        fi
+        empty=0
+        echo "${content}"
+      else
+        # If the line is empty, set the empty flag to true.
+        empty=1
+      fi
+    fi
+  done <"${script}"
+}
+
+main "${@}"

bin/docs.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+###
+### Script to generate Markdown documentation for all library files.
+###
+### Invokes `doc-single.sh` for each library file `lib_*.sh`. The output is
+### written to `docs/lib`. Before processing each library file, the target
+### directory is cleared and ensures that it exists.
+###
+### Usage:
+###
+### ```bash
+### doc.sh
+### ```
+###
+
+set -o errexit  # abort on nonzero exit status
+set -o nounset  # abort on unbound variable
+set -o pipefail # don't hide errors within pipes
+
+MY_PATH="$(realpath "${BASH_SOURCE[0]}")"
+SCRIPT_DIR="$(dirname "${MY_PATH}")"
+readonly MY_PATH
+readonly SCRIPT_DIR
+readonly DOC_SINGLE="${SCRIPT_DIR}/doc-single.sh"
+readonly LIB_BASH_DIR="${SCRIPT_DIR}/.."
+readonly LIB_DOCS_DIR="${SCRIPT_DIR}/../docs/lib"
+
+function main() {
+  rm -rf "${LIB_DOCS_DIR}"
+  mkdir -p "${LIB_DOCS_DIR}"
+
+  local lib
+
+  for lib in "${LIB_BASH_DIR}"/lib_*.sh; do
+    local lib_name
+    lib_name="$(basename "${lib}")"
+    local target="${LIB_DOCS_DIR}/${lib_name%.sh}.md"
+    "${DOC_SINGLE}" "${lib}" >"${target}"
+  done
+}
+
+main "${@}"

docs/README.md

@@ -0,0 +1,5 @@
+# lib-bash – Bash Libraries
+
+![Lib-Bash Decorative Image](img/LibBashGitHubSocialPreview.jpg)
+
+A set of libraries to use from within your Bash scripts.

docs/lib/lib_console.md

@@ -0,0 +1,140 @@
+
+# lib_console.sh
+
+Include for console support.
+
+**Usage**:
+
+```bash
+MY_PATH="$(realpath "${BASH_SOURCE[0]}")"
+SCRIPT_DIR="$(dirname "${MY_PATH}")"
+readonly MY_PATH
+readonly SCRIPT_DIR
+readonly LIB_BASH_DIR="${SCRIPT_DIR}/lib_bash"
+source "${LIB_BASH_DIR}/lib_console.sh"
+```
+
+## Color Constants
+
+### Foreground Colors
+
+* `COLOR_RESET`: Reset the color.
+* `COLOR_BLACK`: Black color.
+* `COLOR_RED`: Red color.
+* `COLOR_GREEN`: Green color.
+* `COLOR_YELLOW`: Yellow color.
+* `COLOR_BLUE`: Blue color.
+* `COLOR_MAGENTA`: Magenta color.
+* `COLOR_CYAN`: Cyan color.
+* `COLOR_WHITE`: White color.
+* `COLOR_GRAY`: Gray color.
+* `COLOR_LIGHT_RED`: Light red color.
+* `COLOR_LIGHT_GREEN`: Light green color.
+* `COLOR_LIGHT_YELLOW`: Light yellow color.
+* `COLOR_LIGHT_BLUE`: Light blue color.
+* `COLOR_LIGHT_MAGENTA`: Light magenta color.
+* `COLOR_LIGHT_CYAN`: Light cyan color.
+* `COLOR_LIGHT_WHITE`: Light white color.
+
+### Background Colors
+
+* `COLOR_BG_BLACK`: Black background color.
+* `COLOR_BG_RED`: Red background color.
+* `COLOR_BG_GREEN`: Green background color.
+* `COLOR_BG_YELLOW`: Yellow background color.
+* `COLOR_BG_BLUE`: Blue background color.
+* `COLOR_BG_MAGENTA`: Magenta background color.
+* `COLOR_BG_CYAN`: Cyan background color.
+* `COLOR_BG_WHITE`: White background color.
+
+## Logging
+
+All logging functions to output information to STDERR. STDERR is preferred,
+as it is not affected by the output redirection of the script, thus, the
+desired standard output can be redirected to a file or another command.
+
+### log_debug
+
+Output debug message.
+
+The function is used to output debug information. It is only printed
+if the `DEBUG` variable is set to a value greater than 0 (zero).
+
+If the standard output supports color, the debug information is printed in
+gray color. Otherwise, the debug information is printed without color.
+
+**Usage**:
+
+```bash
+log_debug "Only show if DEBUG=1 (or more)"
+grep "pattern" file.txt | log_debug
+```
+
+### log_info
+
+Output information message.
+
+The function is used to output information messages. No extra color is
+used for the information message.
+
+**Usage**:
+
+```bash
+log_info "An informational message."
+grep "pattern" file.txt | log_info
+```
+
+### log_warn
+
+Output warning message.
+
+The function is used to output warning messages. The warning message
+is printed in yellow color.
+
+**Usage**:
+
+```bash
+log_warn "A warning notice."
+grep "pattern" file.txt | log_warn
+```
+
+### log_error
+
+Output error message.
+
+The function is used to output error messages. The error message is
+printed in red color.
+
+**Usage**:
+
+```bash
+log_error "An error."
+grep "pattern" file.txt | log_error
+```
+
+### log_fatal
+
+Output a fatal error message.
+
+The function is used to output error messages. The error message is
+printed with dark red background and bright yellow color.
+
+**Usage**:
+
+```bash
+log_fatal "A fatal error."
+grep "pattern" file.txt | log_fatal
+```
+
+### ccat
+
+Alternative to `cat` that also processes colored input.
+
+**Usage**:
+
+```bash
+ccat <<EOF
+${COLOR_RED}This is red text.${COLOR_RESET}
+${COLOR_YELLOW}This is yellow text.${COLOR_RESET}
+EOF
+```

docs/lib/lib_gnucompat.md

@@ -0,0 +1,51 @@
+
+# GNU-Tools Compatibility Layer
+
+This script provides compatibility functions for GNU tools on non-GNU
+systems, such as macOS.
+
+**Usage**:
+
+```bash
+MY_PATH="$(realpath "${BASH_SOURCE[0]}")"
+SCRIPT_DIR="$(dirname "${MY_PATH}")"
+readonly MY_PATH
+readonly SCRIPT_DIR
+readonly LIB_BASH_DIR="${SCRIPT_DIR}/lib_bash"
+source "${LIB_BASH_DIR}/lib_gnucompat.sh"
+```
+
+## Tools Aliases
+
+These functions will return the corresponding GNU-tool on non-GNU systems,
+if available. Such as `gsed` on macOS, which is the GNU version of `sed`.
+
+* `SED`: GNU `sed` command
+* `AWK`: GNU `awk` command
+* `GREP`: GNU `grep` command
+* `FIND`: GNU `find` command
+* `SORT`: GNU `sort` command
+* `TAR`: GNU `tar` command
+* `DATE`: GNU `date` command
+* `XARGS`: GNU `xargs` command
+* `CUT`: GNU `cut` command
+* `HEAD`: GNU `head` command
+* `TAIL`: GNU `tail` command
+* `TR`: GNU `tr` command
+* `UNIQ`: GNU `uniq` command
+* `WC`: GNU `wc` command
+* `DIFF`: GNU `diff` command
+
+## Functions
+
+### is_gnu
+
+Signal, if the given tool is a GNU tool.
+
+**Usage**:
+
+```bash
+if ! is_gnu "sed"; then
+echo "Not a GNU tool."
+fi
+```

docs/lib/lib_init.md

@@ -0,0 +1,28 @@
+
+# lib_init.sh
+
+A file for some initial Bash Scripting best practices. It applies the
+following settings:
+
+* `errexit`: Abort on nonzero exit status
+* `nounset`: Abort on unbound variable
+* `pipefail`: Don't hide errors within pipes
+* `xtrace`: Show expanded commands if `DEBUG` is set to 2. Set to 1 for
+more verbose output.
+
+**Usage**:
+
+```bash
+MY_PATH="$(realpath "${BASH_SOURCE[0]}")"
+SCRIPT_DIR="$(dirname "${MY_PATH}")"
+readonly MY_PATH
+readonly SCRIPT_DIR
+readonly LIB_BASH_DIR="${SCRIPT_DIR}/lib_bash"
+source "${LIB_BASH_DIR}/lib_init.sh"
+```
+
+## Constants
+
+* `DEBUG`: Provide option to trigger debug output with different verbosity
+levels.
+Call with `DEBUG=2 <command>.sh <file>` to enable verbose debug output

docs/lib/lib_scriptinfo.md

@@ -0,0 +1,24 @@
+
+# lib_scriptinfo.sh
+
+Include for script information functions.
+
+**Usage**:
+
+```bash
+MY_PATH="$(realpath "${BASH_SOURCE[0]}")"
+SCRIPT_DIR="$(dirname "${MY_PATH}")"
+readonly MY_PATH
+readonly SCRIPT_DIR
+readonly LIB_BASH_DIR="${SCRIPT_DIR}/lib_bash"
+source "${LIB_BASH_DIR}/lib_scriptinfo.sh"
+```
+
+## Functions
+
+### get_script_name
+
+Get script name (without path, with extension).
+
+* **Arguments**: _None_
+* **Returns**: The script name.