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

[Sean Anderson <seanga2@gmail.com>]

On 6/16/22 5:45 AM, Heinrich Schuchardt wrote:
> 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@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'?

This is the original synopsis. I have kept it as-is. -T type is
necessary for some types which are not autodetected, e.g. pblimage.

>> +.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.

Sure.

>> +.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.

Will mention.

>> +.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

That's why it's not in italics/bold.

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

I agree. I will remove it.

>> +.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

I believe this is covered by the "legacy" mode.

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

But perhaps it would be better to list "legacy" mode as

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

--Sean