[cmd] Notation for "mandatory" and "optional" parameters in "help shell_cmd" output

Wolfgang Denk wd at denx.de
Sun Mar 1 17:39:13 CET 2020

Dear Adarsh Babu Kalepalli,

In message <CAJgxa7dAF5+gu1F2JMKrYs2YEKg-Xw6hzyOKDKNH2ktTyDoFCw at mail.gmail.com> you wrote:
> When we type "help shell_command" at u-boot console.
> The syntax for the command usage is displayed.
> In most of the cases I noticed parameters enclosed in '[]' or/and '<>'
> or just the sub-command string is provided.
> From the help of most of the commands, and on using them I observed that
> parameters enclosed in
>                 -'[]' could be optional
>                 -'<>' could be mandatory
> In some cases, the mandatory parameters were not enclosed in "<>" .
> For ex.
>             env ask name [message] [size] - ask for environment variable
>             env edit name - edit environment variable
>             env exists name - tests for existence of variable
> in the above case "name" seems to be a mandatory parameter.
> Could you please let me know the notation we follow to indicate the
> mandatory and optional input parameters for shell commands in their syntax
> (displayed through help) ??

In general we try to follow the SYNOPSIS style of UNIX™ man pages,
see [1]:

        For commands, this shows the syntax of the command and its
        arguments (including options); boldface is used for as-is
        text and italics are used to indicate replaceable arguments.
        Brackets ([]) surround optional arguments, vertical bars (|)
        separate choices, and ellipses (...) can be repeated.

Only we don't have bold or italic fonts, so bold is often omitted
and in some cases we may write <italics>.

But note that these texts have been written buy a large number of
developers, so don't expect strict consistency.  But as usual:
patches for cleanup are always welcome.

Best regards,

Wolfgang Denk

DENX Software Engineering GmbH,      Managing Director: Wolfgang Denk
HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany
Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: wd at denx.de
"I like your game but we have to change the rules."

More information about the U-Boot mailing list