[PATCH v3 01/14] doc: mkimage: Use standard style for synopsis

[Simon Glass]

On Sat, 25 Jun 2022 at 11:12, Sean Anderson <seanga2 at gmail.com> wrote:
>
> The synopsis section is a bit messy. As an example, "uimage file name" is
> printed in italics, bold, and roman (depending on the line). This cleans
> things up and converts the synopsis section to use standard style. The
> .SY/.YS macros set up appropriate formatting for command synopsis sections
> (such as disabling hyphenation and setting a hanging indent). All parts of
> the synopsis now use the following style:
>
> - Bold for parts of the command which should be typed in by the user (such
>   as the program name and flags)
> - Italic for parts which should be replaced (such as uimage-file-name)
> - Roman for parts which should not be typed at all (such as brackets)
>
> Multi-word variables now use hyphens to connect their words instead of
> spaces. This makes it clearer that all the words are part of the same
> variable. Additionally, "option ..." is used to denote where other options
> may be specified, as this appears to be standard style.
>
> In addition to the above style changes, this also makes some changes to
> content. The use of the term "legacy" has been removed, since this simply
> refers to any non-FIT image type. Additionally, wording like "uimage file
> name" has been replaced with "image-file-name" to better reflect that
> images may or may not be uImages. Lastly, the "auto" value for -f is
> documented in the synopsis.
>
> Signed-off-by: Sean Anderson <seanga2 at gmail.com>
> ---
>
> Changes in v3:
> - Document the various content changes in the commit message
> - Fix typo in commit message
> - Remove "legacy" wording from synopsis
> - Reorder "legacy" synopsis first
>
> Changes in v2:
> - Fix spacing for -F
>
>  doc/mkimage.1 | 27 +++++++++++++++++++--------
>  1 file changed, 19 insertions(+), 8 deletions(-)

Reviewed-by: Simon Glass <sjg at chromium.org>