docs: Document cargo script

Author: epage

src/doc/man/cargo-run.md

@@ -22,6 +22,9 @@ Unlike {{man "cargo-test" 1}} and {{man "cargo-bench" 1}}, `cargo run` sets the
 working directory of the binary executed to the current working directory, same 
 as if it was executed in the shell directly.
 
+When running scripts, the process' [arg0](../../std/env/fn.args.html) will be set to the
+script's path on a best-effort basis.
+
 ## OPTIONS
 
 {{> section-options-package }}

src/doc/man/cargo.md

@@ -7,6 +7,7 @@ cargo --- The Rust package manager
 ## SYNOPSIS
 
 `cargo` [_options_] _command_ [_args_]\
+`cargo` [_options_] _script_ [_args_]\
 `cargo` [_options_] `--version`\
 `cargo` [_options_] `--list`\
 `cargo` [_options_] `--help`\
@@ -19,12 +20,25 @@ available at <https://rust-lang.org>.
 
 _command_ may be one of:
 - built-in commands, see below
+- [script](#scripts)
 - [aliases]
 - [external tools]
 
 [aliases]: ../reference/config.html#alias
 [external tools]: ../reference/external-tools.html#custom-subcommands
 
+## SCRIPTS
+
+A _script_ is distinguished from a _command_ or _alias_ by having path separators present or a `.rs` extension.
+These are Rust source files with an optional [manifest] embedded in the frontmatter.
+
+`cargo` _script_ operate on system or user level, not project level.
+This means that the local [configuration discovery] is ignored.
+Instead, the configuration discovery begins at `$CARGO_HOME/config.toml`.
+
+[manifest]: ../reference/manifest.html
+[configuration discovery]: ../reference/config.html#hierarchical-structure
+
 ## COMMANDS
 
 ### Build Commands
@@ -248,7 +262,11 @@ stable yet and may be subject to change.
        mkdir foo && cd foo
        cargo init .
 
-6. Learn about a command's options and usage:
+6. Run a script
+
+       cargo task.rs --action
+
+7. Learn about a command's options and usage:
 
        cargo help clean
 

src/doc/man/generated_txt/cargo-add.txt

@@ -164,8 +164,9 @@ OPTIONS
 
    Manifest Options
        --manifest-path path
-           Path to the Cargo.toml file. By default, Cargo searches for the
-           Cargo.toml file in the current directory or any parent directory.
+           Path to the Cargo.toml or cargo script file. By default, Cargo
+           searches for the Cargo.toml file in the current directory or any
+           parent directory.
 
        -p spec, --package spec
            Add dependencies to only the specified package.

src/doc/man/generated_txt/cargo-bench.txt

@@ -335,8 +335,9 @@ OPTIONS
 
    Manifest Options
        --manifest-path path
-           Path to the Cargo.toml file. By default, Cargo searches for the
-           Cargo.toml file in the current directory or any parent directory.
+           Path to the Cargo.toml or cargo script file. By default, Cargo
+           searches for the Cargo.toml file in the current directory or any
+           parent directory.
 
        --ignore-rust-version
            Ignore rust-version specification in packages.

src/doc/man/generated_txt/cargo-build.txt

@@ -259,8 +259,9 @@ OPTIONS
 
    Manifest Options
        --manifest-path path
-           Path to the Cargo.toml file. By default, Cargo searches for the
-           Cargo.toml file in the current directory or any parent directory.
+           Path to the Cargo.toml or cargo script file. By default, Cargo
+           searches for the Cargo.toml file in the current directory or any
+           parent directory.
 
        --ignore-rust-version
            Ignore rust-version specification in packages.

src/doc/man/generated_txt/cargo-check.txt

@@ -253,8 +253,9 @@ OPTIONS
 
    Manifest Options
        --manifest-path path
-           Path to the Cargo.toml file. By default, Cargo searches for the
-           Cargo.toml file in the current directory or any parent directory.
+           Path to the Cargo.toml or cargo script file. By default, Cargo
+           searches for the Cargo.toml file in the current directory or any
+           parent directory.
 
        --ignore-rust-version
            Ignore rust-version specification in packages.

src/doc/man/generated_txt/cargo-clean.txt

@@ -104,8 +104,9 @@ OPTIONS
 
    Manifest Options
        --manifest-path path
-           Path to the Cargo.toml file. By default, Cargo searches for the
-           Cargo.toml file in the current directory or any parent directory.
+           Path to the Cargo.toml or cargo script file. By default, Cargo
+           searches for the Cargo.toml file in the current directory or any
+           parent directory.
 
        --locked
            Asserts that the exact same dependencies and versions are used as

src/doc/man/generated_txt/cargo-doc.txt

@@ -228,8 +228,9 @@ OPTIONS
 
    Manifest Options
        --manifest-path path
-           Path to the Cargo.toml file. By default, Cargo searches for the
-           Cargo.toml file in the current directory or any parent directory.
+           Path to the Cargo.toml or cargo script file. By default, Cargo
+           searches for the Cargo.toml file in the current directory or any
+           parent directory.
 
        --ignore-rust-version
            Ignore rust-version specification in packages.

src/doc/man/generated_txt/cargo-fetch.txt

@@ -81,8 +81,9 @@ OPTIONS
 
    Manifest Options
        --manifest-path path
-           Path to the Cargo.toml file. By default, Cargo searches for the
-           Cargo.toml file in the current directory or any parent directory.
+           Path to the Cargo.toml or cargo script file. By default, Cargo
+           searches for the Cargo.toml file in the current directory or any
+           parent directory.
 
        --locked
            Asserts that the exact same dependencies and versions are used as

src/doc/man/generated_txt/cargo-fix.txt

@@ -327,8 +327,9 @@ OPTIONS
 
    Manifest Options
        --manifest-path path
-           Path to the Cargo.toml file. By default, Cargo searches for the
-           Cargo.toml file in the current directory or any parent directory.
+           Path to the Cargo.toml or cargo script file. By default, Cargo
+           searches for the Cargo.toml file in the current directory or any
+           parent directory.
 
        --ignore-rust-version
            Ignore rust-version specification in packages.