doc: mentions of addenv seemed lacking (JuliaLang#40539)

Co-authored-by: akaysh <[email protected]> Co-authored-by: Sacha Verweij <[email protected]> Co-authored-by: akaysh <[email protected]> Co-authored-by: Sacha Verweij <[email protected]>
inkydragon · Apr 28, 2021 · e9b22ce · e9b22ce
1 parent bbaca9d
commit e9b22ce
Show file tree

Hide file tree

Showing 3 changed files with 36 additions and 6 deletions.
diff --git a/base/cmd.jl b/base/cmd.jl
@@ -63,7 +63,7 @@ while changing the settings of the optional keyword arguments:
  array or tuple of `"var"=>val` pairs. In order to modify (rather than replace) the
  existing environment, initialize `env` with `copy(ENV)` and then set `env["var"]=val` as
  desired. To add to an environment block within a `Cmd` object without replacing all
- elements, use `addenv()` which will return a `Cmd` object with the updated environment.
+ elements, use [`addenv()`](@ref) which will return a `Cmd` object with the updated environment.
 * `dir::AbstractString`: Specify a working directory for the command (instead
  of the current directory).
 
@@ -236,9 +236,11 @@ Set environment variables to use when running the given `command`. `env` is eith
 dictionary mapping strings to strings, an array of strings of the form `"var=val"`, or
 zero or more `"var"=>val` pair arguments. In order to modify (rather than replace) the
 existing environment, create `env` through `copy(ENV)` and then setting `env["var"]=val`
-as desired, or use `addenv`.
+as desired, or use [`addenv`](@ref).
 
 The `dir` keyword argument can be used to specify a working directory for the command.
+
+See also [`Cmd`](@ref), [`addenv`](@ref), [`ENV`](@ref), [`pwd`](@ref).
 """
 setenv(cmd::Cmd, env; dir="") = Cmd(cmd; env=byteenv(env), dir=dir)
 setenv(cmd::Cmd, env::Pair{<:AbstractString}...; dir="") =
@@ -248,10 +250,12 @@ setenv(cmd::Cmd; dir="") = Cmd(cmd; dir=dir)
 """
  addenv(command::Cmd, env...; inherit::Bool = true)
 
-Merge new environment mappings into the given `Cmd` object, returning a new `Cmd` object.
+Merge new environment mappings into the given [`Cmd`](@ref) object, returning a new `Cmd` object.
 Duplicate keys are replaced. If `command` does not contain any environment values set already,
 it inherits the current environment at time of `addenv()` call if `inherit` is `true`.
 
+See also [`Cmd`](@ref), [`setenv`](@ref), [`ENV`](@ref).
+
 !!! compat "Julia 1.6"
  This function requires Julia 1.6 or later.
 """

diff --git a/doc/src/base/base.md b/doc/src/base/base.md
@@ -307,6 +307,7 @@ Base.ignorestatus
 Base.detach
 Base.Cmd
 Base.setenv
+Base.addenv
 Base.withenv
 Base.pipeline(::Any, ::Any, ::Any, ::Any...)
 Base.pipeline(::Base.AbstractCmd)

diff --git a/doc/src/manual/running-external-programs.md b/doc/src/manual/running-external-programs.md
@@ -376,11 +376,36 @@ saturated throughput.
 We strongly encourage you to try all these examples to see how they work.
 
 ## `Cmd` Objects
-The syntax introduced above creates objects of type [`Cmd`](@ref). Such object may also be constructed directly:
+The backtick syntax create an object of type [`Cmd`](@ref). Such object may also be constructed directly from
+an existing `Cmd` or list of arguments:
 
 ```julia
 run(Cmd(`pwd`, dir=".."))
+run(Cmd(["pwd"], detach=true, ignorestatus=true))
 ```
 
-This way, they may be customized with the `dir` keyword to set the working directory,
-`detach` keyword to run the command in a new process group, and `env` keyword to set environment variables.
+This allows you to specify several aspects of the `Cmd`'s execution environment via keyword arguments. For
+example, the `dir` keyword provides control over the `Cmd`'s working directory:
+
+```jldoctest
+julia> run(Cmd(`pwd`, dir="/"));
+/
+```
+
+And the `env` keyword allows you to set execution environment variables:
+
+```jldoctest
+julia> run(Cmd(`sh -c "echo foo \$HOWLONG"`, env=("HOWLONG" => "ever!",)));
+foo ever!
+```
+
+See `[`Cmd`](@ref)` for additional keyword arguments. The [`setenv`](@ref) and [`addenv`](@ref) commands
+provide another means for replacing or adding to the `Cmd` execution environment variables, respectively:
+
+```jldoctest
+julia> run(setenv(`sh -c "echo foo \$HOWLONG"`, ("HOWLONG" => "ever!",)));
+foo ever!
+
+julia> run(addenv(`sh -c "echo foo \$HOWLONG"`, "HOWLONG" => "ever!"));
+foo ever!
+```