[v5,4/6] sysinfo: Add documentation

Add documentation for the sysinfo command with examples.

Reviewed-by: Marek Vasut <marek.vasut+renesas@mailbox.org>
Signed-off-by: Detlev Casanova <detlev.casanova@collabora.com>
---
 doc/usage/cmd/sysinfo.rst | 56 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)
 create mode 100644 doc/usage/cmd/sysinfo.rst

Hi Detlev,

On Mon, 2 Oct 2023 at 09:22, Detlev Casanova
<detlev.casanova@collabora.com> wrote:
>
> Add documentation for the sysinfo command with examples.
>
> Reviewed-by: Marek Vasut <marek.vasut+renesas@mailbox.org>
> Signed-off-by: Detlev Casanova <detlev.casanova@collabora.com>
> ---
>  doc/usage/cmd/sysinfo.rst | 56 +++++++++++++++++++++++++++++++++++++++
>  1 file changed, 56 insertions(+)
>  create mode 100644 doc/usage/cmd/sysinfo.rst

Reviewed-by: Simon Glass <sjg@chromium.org>
>
> diff --git a/doc/usage/cmd/sysinfo.rst b/doc/usage/cmd/sysinfo.rst
> new file mode 100644
> index 00000000000..1660b2aa1a6
> --- /dev/null
> +++ b/doc/usage/cmd/sysinfo.rst
> @@ -0,0 +1,56 @@
> +.. SPDX-License-Identifier: GPL-2.0+:
> +
> +sysinfo command
> +===============
> +
> +Synopis
> +-------
> +
> +::
> +
> +    sysinfo id <varname>

[<varname>]

I think, since the params are optional?

> +    sysinfo model <varname>
> +    sysinfo revision <varname>
> +
> +Description
> +-----------
> +
> +The `sysinfo` command is used to show information about the running system
> +
> +The `sysinfo id` command prints or sets an environment variable to the board id
> +as an hex value.
> +
> +    varname
> +        an optional environment variable to store the board id into.
> +
> +The `sysinfo model` command prints or sets an environment variable to the board
> +model name as a string value.
> +
> +    varname
> +        an optional environment variable to store the board model name into.
> +
> +The `sysinfo revision` command prints or sets an environment variable to the
> +board revision in the <MAJOR>.<MINOR> format, where MINOR and MINOR are int
> +values.
> +
> +    varname
> +        an optional environment variable to store the board revision into.
> +
> +Examples
> +--------
> +
> +::
> +
> +    => sysinfo id
> +    0x0b
> +    => sysinfo model
> +    Renesas Starter Kit Premier board rev 2.1
> +    => sysinfo revision varname
> +    => env print varname
> +    2.1
> +
> +Return value
> +------------
> +
> +The return value $? is set to 0 (true) if the command succeeded. If an
> +error occurs, the return value $? is set to 1 (false).
> --
> 2.41.0
>

Regards.

Simon

On 10/2/23 17:20, Detlev Casanova wrote:
> Add documentation for the sysinfo command with examples.
>
> Reviewed-by: Marek Vasut <marek.vasut+renesas@mailbox.org>
> Signed-off-by: Detlev Casanova <detlev.casanova@collabora.com>
> ---
>   doc/usage/cmd/sysinfo.rst | 56 +++++++++++++++++++++++++++++++++++++++

Thank you for providing a man-page.

Unfortunately this does not build:
usage/cmd/sysinfo.rst:document isn't included in any toctree

Please, add sysinfo to doc/usage/index.rst.

Please, use run 'make htmldocs' before resubmitting.

>   1 file changed, 56 insertions(+)
>   create mode 100644 doc/usage/cmd/sysinfo.rst
>
> diff --git a/doc/usage/cmd/sysinfo.rst b/doc/usage/cmd/sysinfo.rst
> new file mode 100644
> index 00000000000..1660b2aa1a6
> --- /dev/null
> +++ b/doc/usage/cmd/sysinfo.rst
> @@ -0,0 +1,56 @@
> +.. SPDX-License-Identifier: GPL-2.0+:
> +
> +sysinfo command
> +===============
> +
> +Synopis

%s/Synopis/Synopsis/

> +-------
> +
> +::
> +
> +    sysinfo id <varname>
> +    sysinfo model <varname>
> +    sysinfo revision <varname>
> +
> +Description
> +-----------
> +
> +The `sysinfo` command is used to show information about the running system
> +
> +The `sysinfo id` command prints or sets an environment variable to the board id
> +as an hex value.

%s/an hex/a hexadecimal/

> +
> +    varname
> +        an optional environment variable to store the board id into.
> +
> +The `sysinfo model` command prints or sets an environment variable to the board
> +model name as a string value.
> +
> +    varname
> +        an optional environment variable to store the board model name into.

If varname were optional, the synopsis would be

sysinfo model [varname]

> +
> +The `sysinfo revision` command prints or sets an environment variable to the
> +board revision in the <MAJOR>.<MINOR> format, where MINOR and MINOR are int
> +values.
> +
> +    varname
> +        an optional environment variable to store the board revision into.
> +
> +Examples
> +--------
> +
> +::
> +
> +    => sysinfo id
> +    0x0b
> +    => sysinfo model
> +    Renesas Starter Kit Premier board rev 2.1
> +    => sysinfo revision varname
> +    => env print varname
> +    2.1

This is too much hassle to print the information.

We should make the parameters optional:

'sysinfo' should print all information.
'sysinfo revision' should print the revision.


> +
> +Return value
> +------------
> +
> +The return value $? is set to 0 (true) if the command succeeded. If an
> +error occurs, the return value $? is set to 1 (false).

Please, use the same tense:

%s/succeeded/succeeds/

Best regards

Heinrich