chore: update docs

Cargo.toml

@@ -3,7 +3,7 @@ name = "argc"
 version = "1.16.0"
 edition = "2021"
 authors = ["sigoden <[email protected]>"]
-description = "A bash cli framework, also a task management & automation tool"
+description = "A bash cli framework, also a bash-based command runner"
 license = "MIT OR Apache-2.0"
 homepage = "https://github.com/sigoden/argc"
 repository = "https://github.com/sigoden/argc"

README.md

@@ -3,43 +3,45 @@
 [![CI](https://github.com/sigoden/argc/actions/workflows/ci.yaml/badge.svg)](https://github.com/sigoden/argc/actions/workflows/ci.yaml)
 [![Crates](https://img.shields.io/crates/v/argc.svg)](https://crates.io/crates/argc)
 
-Argc is a powerful Bash framework that simplifies building command-line interfaces (CLIs) and automating tasks. It lets you define your CLI through comments, focusing on your core logic without dealing with argument parsing, usage text, error messages, and other boilerplate code.
+Argc is a powerful Bash framework that simplifies building full-featured CLIs. It lets you define your CLI through comments, focusing on your core logic without dealing with argument parsing, usage text, error messages, and other boilerplate code.
 
 ![demo](https://user-images.githubusercontent.com/4012553/228990851-fee5649f-aa24-4297-a924-0d392e0a7400.gif)
 
 ## Features
 
 - **Effortless Argument Parsing:**
-  - Handles positional and optional arguments, flags, commands, and subcommands.
-  - Validates and extracts user input for robust error handling.
+  - Handles flags, options, positional arguments, and subcommands.
+  - Validates user input for robust error handling.
+  - Generates information-rich usage text.
+  - Maps arguments to corresponding variables.
 - **Standalone Bash Script Creation:**
-  - Build a single executable script without depending on Argc itself.
+  - Build a bash script that incorporates all functionalities without depending on Argc itself.
 - **Cross-shell Autocompletion:**
   - Generate autocompletion scripts for various shells (bash, zsh, fish, powershell, etc.).
 - **Man Page Generation:**
   - Automatically create comprehensive man page documentation for your script.
 - **Environment Variable Integration:**
   - Define, validate, and bind environment variables to options and positional arguments.
 - **Task Automation:**
-  - An ideal task runner for Bash, allowing you to automate tasks using Argcfile.sh.
+  - An Bash-based command runner that automates tasks via Argcfile.sh.
 - **Cross-Platform Compatibility:**
   - Seamlessly run your Argc-based scripts on macOS, Linux, Windows, and BSD systems.
 
 ## Install
 
-### With cargo
+### Package Managers
 
-```
-cargo install argc
-```
+- **Rust Developers:** `cargo install argc`
+- **Homebrew/Linuxbrew Users:** `brew install argc`
+- **Pacman Users**: `yay -S argc`
 
-### Binaries on macOS, Linux, Windows
+#### Pre-built Binaries
 
-Download from [Github Releases](https://github.com/sigoden/argc/releases), unzip and add argc to your $PATH.
+Alternatively, download pre-built binaries for macOS, Linux, and Windows from [GitHub Releases](https://github.com/sigoden/argc/releases), extract it, and add the `argc` binary to your `$PATH`.
 
 ### GitHub Actions
 
-[extractions/setup-crate](https://github.com/marketplace/actions/setup-crate) can be used to install just in a GitHub Actions workflow.
+[extractions/setup-crate](https://github.com/marketplace/actions/setup-crate) can be used to install argc in a GitHub Actions workflow.
 
 ```yaml
 - uses: extractions/setup-crate@v1
@@ -78,6 +80,7 @@ echo val: ${argc_val[@]}
 ```
 
 Run the script with some sample arguments:
+
 ```sh
 ./example.sh -F --bar=xyz --baz a --baz b v1 v2
 ```
@@ -127,9 +130,11 @@ Comment tags are standard Bash comments prefixed with `@` and a specific tag. Th
 
 See [specification](https://github.com/sigoden/argc/blob/main/docs/specification.md) for the grammar and usage of all the comment tags.
 
-## Build
+## Argc-build
+
+Generate an independent bash script that incorporates all functionalities typically available when the `argc` command is present.
 
-Build a standalone bash script without argc dependency.
+The generated script removes the `argc` dependency, enhances compatibility, and enables deployment in a wider range of environments.
 
 ```
 argc --argc-build <SCRIPT> [OUTPATH]
@@ -138,27 +143,24 @@ argc --argc-build <SCRIPT> [OUTPATH]
 ```sh
 argc --argc-build ./example.sh build/
 
-./build/example.sh -h       # Run the script without argc dependency
+./build/example.sh -h     # The script's functionality does not require the `argc` dependency
 ```
 
 ## Argcscript
 
-Argc will automatically find and run `Argcfile.sh` unless the `--argc-*` options are used to change this behavior.
+Argc is a also command runner built for those who love the efficiency and flexibility of Bash scripting.
 
-Argcfile is to argc what Makefile is to make. 
+Similar to how Makefile define commands for the `make` tool, Argcscript uses an `Argcfile.sh` to store your commands, referred to as "recipes".
 
-What is the benefit?
-- Can enjoy convenient shell autocompletion.
-- Can be called in any subdirectory without locating the script file every time.
-- Serve as a centralized entrypoint/documentation for executing project bashscripts.
+**Why Choose Argc for Your Projects?**
 
-Argc is a [task runner](https://github.com/sigoden/argc/blob/main/docs/task-runner.md).
+- **Leverage Bash Skills:** No need to learn a new language, perfect for Bash aficionados.
+- **GNU Toolset Integration:** Utilize familiar tools like awk, sed, grep, find, and others.
+- **Environment variables Management**: Load dotenv, document, and validate environment variables effortlessly.
+- **Powerful Shell Autocompletion:** Enjoy autocomplete suggestions for enhanced productivity.
+- **Cross-Platform Compatibility::** Works seamlessly across Linux, macOS, Windows, and BSD systems.
 
-You can run `argc --argc-create` to quickly create a boilerplate argcscript.
-
-```
-argc --argc-create [TASKS]...
-```
+See [command runner](https://github.com/sigoden/argc/blob/main/docs/command-runner.md) for more details.
 
 ![argcscript](https://github.com/sigoden/argc/assets/4012553/707a3b28-5416-47f1-9d19-788f0135971a)
 

docs/task-runner.md → docs/command-runner.md

@@ -1,34 +1,44 @@
-# Task runner
+# Command runner
 
-Argc is an ideal task runner for automating complex tasks, especially for users familiar with Bash.
+Argc is a also command runner built for those who love the efficiency and flexibility of Bash scripting.
 
-## Why Choose Argc?
+This document explains how to effectively use `argc` as a command runner.
 
-- **Leverage Bash Skills:** No need to learn a new language, perfect for Bash aficionados.
-- **GNU Toolset Integration:** Utilize familiar tools like awk, sed, grep, and find within your tasks.
-- **Environment variables Management**: Load dotenv, document, and validate environment variables effortlessly.
-- **Powerful Shell Autocompletion:** Enjoy autocomplete suggestions for enhanced productivity.
-- **Cross-Platform Compatibility::** Works seamlessly across Linux, macOS, Windows, and BSD systems.
+## Create an Argcfile.sh 
 
-## Defining Tasks
+Commands, called recipes, are stored in a file called argcfile .
 
-A task is a regular shell function with a `# @cmd` comment tag above it.
-
-### Create an Argcfile.sh 
-
-Use `--argc-create` to quickly generate an Argcfile.sh for your project.
+Use `--argc-create` to quickly generate an `Argcfile.sh` for your project.
 
 ```sh
 argc --argc-create build test
 ```
 
-This creates a basic Argcfile.sh with sample `build` and `test` tasks.
+This creates a basic Argcfile.sh with sample `build` and `test` recipes.
 
-Here's what Argcfile.sh looks like:
+```sh
+#!/usr/bin/env bash
 
-## Handling dependencies
+set -e
 
-Since task are functions, manage dependencies by calling them sequentially within other functions.
+# @cmd
+build() {
+    echo To implement command: build
+}
+
+# @cmd
+test() {
+    echo To implement command: test
+}
+
+eval "$(argc --argc-eval "$0" "$@")"
+```
+
+A recipe is a regular shell function with a `@cmd` comment tag above it.
+
+## Handle dependencies
+
+Since recipe are functions, manage dependencies by calling them sequentially within other functions.
 
 ```sh
 # @cmd
@@ -47,7 +57,7 @@ after() {
 }
 ```
 
-This example demonstrates how the `current` task calls both `before` and `after` tasks.
+This example demonstrates how the `current` recipe calls both `before` and `after` recipes.
 
 ```
 $ argc current
@@ -56,9 +66,9 @@ current
 after
 ```
 
-### Organizing Tasks
+## Organize Recipes
 
-Organize related tasks into groups for better readability.
+Organize related recipes into groups for better readability.
 
 ```sh
 # @cmd
@@ -71,9 +81,7 @@ test-bin() { :; }
 
 > Valid group formats include: `foo:bar` `foo.bar` `foo@bar`.
 
-## Running Tasks
-
-### Default task recipe
+## Set default recipe
 
 When invoked without a specific recipe, Argc displays available recipes.
 
@@ -126,20 +134,21 @@ test() {
 }
 ```
 
-Now you can run the `test` task using the alias `t`:
+Now you can run the `test` recipe using the alias `t`:
 ```
 $ argc t
 ```
 
-### Positional arguments
+## Access positional arguments
 
 Accessed through shell positional variables (`$1`, `$2`, `$@`, `$*` etc.).
 
 ```sh
 # @cmd
 build() {
   echo $1 $2
-  echo "$@"
+  echo $@
+  echo $*
 }
 ```
 
@@ -149,12 +158,12 @@ foo bar
 foo bar
 ```
 
-### Flag/option arguments
+## Access Flag/option arguments
 
-Define and use flags and options for more control.
+Define and use flags/options for more control.
 
 ```sh
-# @cmd  A simple task
+# @cmd  A simple command
 # @flag -f --flag   A flag parameter
 # @option -option   A option parameter
 # @arg arg          A positional parameter
@@ -167,9 +176,9 @@ cmd() {
 
 ```
 $ argc cmd -h
-A simple task
+A simple command
 
-USAGE: test cmd [OPTIONS] [ARG]
+USAGE: Argcfile.sh cmd [OPTIONS] [ARG]
 
 ARGS:
   [ARG]  A positional parameter
@@ -185,9 +194,7 @@ option:  foo
 arg:     README.md
 ```
 
-## Environment variable
-
-### Loading dotenv
+## Load environment variables from dotenv file
 
 Use `@meta dotenv` to load environment variables from a `.env` file.
 
@@ -196,7 +203,7 @@ Use `@meta dotenv` to load environment variables from a `.env` file.
 # @meta dotenv .env.local                         # Load .env.local
 ```
 
-### Documentation and Validation
+## Document and Validate environment variables
 
 Define environment variables using `@env`.
 
@@ -250,7 +257,7 @@ $ tree /tmp/project
 └── src
 ```
 
-The code of build task as follows:
+The code of build recpie as follows:
 
 ```sh
 # @cmd

src/bin/argc/completions/completion.sh

@@ -3,7 +3,7 @@
 # @describe An elegant command-line argument parser - https://github.com/sigoden/argc
 
 # @option --argc-eval~ <FILE> <ARGS>                                Use `eval "$(argc --argc-eval "$0" "$@")"`
-# @option --argc-create~ <TASKS>                                    Create a boilerplate argcfile
+# @option --argc-create~ <RECEIPES>                                 Create a boilerplate argcfile
 # @option --argc-build <FILE> <OUTPATH?>                            Generate bashscript without argc dependency
 # @option --argc-mangen <FILE> <OUTDIR>                             Generate man pages
 # @option --argc-completions~[`_choice_completion`] <SHELL> <CMDS>  Generate shell completion scripts

src/bin/argc/main.rs

@@ -267,7 +267,7 @@ fn get_argc_help() -> String {
 
 USAGE:
     argc --argc-eval <SCRIPT> [ARGS]...             Use `eval "$(argc --argc-eval "$0" "$@")"`
-    argc --argc-create [TASKS]...                   Create a boilerplate argcfile
+    argc --argc-create [RECIPES]...                 Create a boilerplate argcfile
     argc --argc-build <SCRIPT> [OUTPATH]            Generate bashscript without argc dependency
     argc --argc-mangen <SCRIPT> <OUTDIR>            Generate man pages
     argc --argc-completions <SHELL> [CMDS]...       Generate shell completion scripts