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

[Heinrich Schuchardt]

On 6/20/22 02:07, AKASHI Takahiro wrote:
> 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?

env is a separate command. So it needs its own man-page.

> 
>> +    printenv -e [-guid guid][-n] [name]
>                                 ^
>                             space    [name ...]

Do you mean by space:

%s/[-guid guid][-n]/[-guid guid] [-n]/

Best regards

Heinrich

> "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
>>