[PATCH 1/1] doc: man-page for the printenv command

[AKASHI Takahiro]

Heinrich,

Thank you.
A few nitpicks.

On Sun, Jun 19, 2022 at 02:01:17PM +0200, Heinrich Schuchardt wrote:
> Privide a man-page for the printenv command.
> 
> Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt at canonical.com>
> ---
>  doc/usage/cmd/printenv.rst | 90 ++++++++++++++++++++++++++++++++++++++
>  doc/usage/index.rst        |  1 +
>  2 files changed, 91 insertions(+)
>  create mode 100644 doc/usage/cmd/printenv.rst
> 
> diff --git a/doc/usage/cmd/printenv.rst b/doc/usage/cmd/printenv.rst
> new file mode 100644
> index 0000000000..6f1c46006b
> --- /dev/null
> +++ b/doc/usage/cmd/printenv.rst
> @@ -0,0 +1,90 @@
> +.. SPDX-License-Identifier: GPL-2.0+:
> +
> +printenv command
> +================
> +
> +Synopsis
> +--------
> +
> +::
> +
> +    printenv [-a] [name ...]

Refer to "env print" as well?

> +    printenv -e [-guid guid][-n] [name]
                               ^
                           space    [name ...]
"printenv -e" also supports multiple variable names in a command line.

> +
> +Description
> +-----------
> +
> +The printenv command is used to print environment or UEFI variables.
> +
> +\-a
> +    Print environment variables starting with a period ('.').
> +
> +\-e
> +    Print UEFI variables. Without -e environment variables are printed.
> +
> +\-guid *guid*
> +    Specify vendor GUID *guid*. If none is specified, all UEFI variables with
> +    the specified name are printed irrespective of their vendor GUID.
> +
> +\-n
> +    don't show hexadecimal dump of value
> +
> +name
> +    Variable name. If no name is provided all variables are printed.
> +    Multiple environment variable names may be specified.
> +
> +Examples
> +--------
> +
> +The following examples demonstrates the effect of the *-a* flag when displaying
> +environment variables:
> +
> +::
> +
> +    => setenv .foo bar
> +    => printenv
> +    arch=sandbox
> +    baudrate=115200
> +    board=sandbox
> +    ...
> +    stdout=serial,vidconsole
> +
> +    Environment size: 644/8188 bytes
> +    => printenv -a
> +    .foo=bar
> +    arch=sandbox
> +    baudrate=115200
> +    board=sandbox
> +    ...
> +    stdout=serial,vidconsole
> +
> +    Environment size: 653/8188 bytes
> +    =>
> +
> +The next example shows the effect of the *-n* flag when displaying an UEFI

You intend to demonstrate not only "-n" but also "-guid" here?

-Takahiro Akashi

> +variable and how to specify a vendor GUID:
> +
> +::
> +
> +    => printenv -e -guid 8be4df61-93ca-11d2-aa0d-00e098032b8c PlatformLangCodes
> +    PlatformLangCodes:
> +        8be4df61-93ca-11d2-aa0d-00e098032b8c (EFI_GLOBAL_VARIABLE_GUID)
> +        BS|RT|RO, DataSize = 0x6
> +        00000000: 65 6e 2d 55 53 00                                en-US.
> +    => printenv -e -n PlatformLangCodes
> +    PlatformLangCodes:
> +        8be4df61-93ca-11d2-aa0d-00e098032b8c (EFI_GLOBAL_VARIABLE_GUID)
> +        BS|RT|RO, DataSize = 0x6
> +    =>
> +
> +Configuration
> +=============
> +
> +UEFI variables are only supported if CONFIG_CMD_NVEDIT_EFI=y. The value of UEFI
> +variables can only be displayed if CONFIG_HEXDUMP=y.
> +
> +Return value
> +------------
> +
> +The return value $? is 1 (false) if a specified variable is not found.
> +Otherwise $? is set to 0 (true).
> diff --git a/doc/usage/index.rst b/doc/usage/index.rst
> index c03f4aef9e..cbe49244c8 100644
> --- a/doc/usage/index.rst
> +++ b/doc/usage/index.rst
> @@ -48,6 +48,7 @@ Shell commands
>     cmd/md
>     cmd/mmc
>     cmd/pinmux
> +   cmd/printenv
>     cmd/pstore
>     cmd/qfw
>     cmd/reset
> -- 
> 2.36.1
>