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

[Heinrich Schuchardt]

On 6/13/22 00:13, Sean Anderson 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 fomatting for command synopsis sections

nits:
%s/fomatting/formatting/

> (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.
>
> Signed-off-by: Sean Anderson <seanga2 at gmail.com>
> ---
>
> Changes in v2:
> - Fix spacing for -F
>
>   doc/mkimage.1 | 26 ++++++++++++++++++--------
>   1 file changed, 18 insertions(+), 8 deletions(-)
>
> diff --git a/doc/mkimage.1 b/doc/mkimage.1
> index 759dc2d12f..dc597272d4 100644
> --- a/doc/mkimage.1
> +++ b/doc/mkimage.1
> @@ -3,17 +3,27 @@
>   .SH NAME
>   mkimage \- Generate image for U-Boot
>   .SH SYNOPSIS
> -.B mkimage
> -.RB [ \-T " \fItype\fP] " \-l " [\fIuimage file name\fP]"

mkimage -T script -l boot.scr

is illegal. Why did you add '-T type'?

> +.SY mkimage
> +.OP \-T type
> +.BI \-l\~ image-file-name

Replacing uimage by image seems to be correct. But you could mention it
in the commit message.

> +.YS
>
> -.B mkimage
> -.RB [\fIoptions\fP] " \-f [" "image tree source file" "]" " [" "uimage file name" "]"
> +.SY mkimage
> +.RI [ option\~ .\|.\|.\&]
> +.BI \-f\~ image-tree-source-file\c
> +.RB | auto

Adding 'auto' is also not mentioned in the commit message.

> +.I image-file-name
> +.YS
>
> -.B mkimage
> -.RB [\fIoptions\fP] " \-F [" "uimage file name" "]"
> +.SY mkimage
> +.RI [ option\~ .\|.\|.\&]
> +.BI \-F\~ image-file-name
> +.YS
>
> -.B mkimage
> -.RB [\fIoptions\fP] " (legacy mode)"
> +.SY mkimage
> +.RI [ option\~ .\|.\|.\&]
> +.R (legacy mode)

(legacy mode) is not an argument. So it should not appear in the synopsis

The last addition of an image type has commit date 2022-04-04
(IH_TYPE_SUNXI_TOC0). The term 'legacy mode' for everything that is not
FIT is misleading and should be avoided.

> +.YS
>
>   .SH "DESCRIPTION"
>   The
The following command is not covered by any entry in the synopsis:

mkimage -T script -n GRUB -d boot.txt boot.scr

The synopsis lacks an entry

mkimage -T type [options] image-file-name

Best regards

Heinrich