[PATCH v2 04/14] doc: mkimage: Regularize option documentation

[Sean Anderson]

On 6/16/22 6:00 AM, Heinrich Schuchardt wrote:
> On 6/13/22 00:14, Sean Anderson wrote:
>> Square brackets are commonly used to denote optional parts of a command.
>> However, all option arguments are mandatory. Remove these brackets. This
>> also removes some unnecessary quotation marks, and uses hyphens to connect
>> words in option arguments.
>>
>> Signed-off-by: Sean Anderson <seanga2 at gmail.com>
>> ---
>>
>> Changes in v2:
>> - Fix extra quote in -E synopsis
>>
>>   doc/mkimage.1 | 72 +++++++++++++++++++++++++--------------------------
>>   1 file changed, 36 insertions(+), 36 deletions(-)
>>
>> diff --git a/doc/mkimage.1 b/doc/mkimage.1
>> index 1015e21576..4074715fe5 100644
>> --- a/doc/mkimage.1
>> +++ b/doc/mkimage.1
>> @@ -25,7 +25,7 @@ mkimage \- Generate image for U-Boot
>>   (legacy mode)
>>   .YS
>>   .
>> -.SH "DESCRIPTION"
>> +.SH DESCRIPTION
>>   The
>>   .B mkimage
>>   command is used to create images for use with the U-Boot boot loader.
>> @@ -49,64 +49,64 @@ allows for more flexibility in handling images of various types and also
>>   enhances integrity protection of images with stronger checksums. It also
>>   supports verified boot.
>>   .
>> -.SH "OPTIONS"
>> +.SH OPTIONS
>>   .
>>   .B List image information:
>>   .
>>   .TP
>> -.BI "\-l [" "uimage file name" "]"
>> +.BI \-l " uimage-file-name"
> 
> You have renamed this in the synopsis to image-file-name. Please, keep
> the argument names consistent.

This is fixed in patch 6. I have tried to keep this patch to just a mechanical removal of quotes.

--Sean

>>   mkimage lists the information contained in the header of an existing U-Boot image.
>>   .
>>   .TP
>> -.BI "\-T [" "image type" "]"
>> +.BI \-T " image-type"
>>   Parse image file as type.
>>   Pass \-h as the image to see the list of supported image type.
>>   Without this option image type is autodetected.
>>   .
>>   .TP
>> -.BI "\-q"
>> +.B \-q
>>   Quiet. Don't print the image header on successful verification.
>>   .
>>   .P
>>   .B Create old legacy image:
>>   .
>>   .TP
>> -.BI "\-A [" "architecture" "]"
>> +.BI \-A " architecture"
>>   Set architecture. Pass \-h as the architecture to see the list of supported architectures.
>>   .
>>   .TP
>> -.BI "\-O [" "os" "]"
>> +.BI \-O " os"
>>   Set operating system. bootm command of u-boot changes boot method by os type.
>>   Pass \-h as the OS to see the list of supported OS.
>>   .
>>   .TP
>> -.BI "\-T [" "image type" "]"
>> +.BI \-T " image-type"
>>   Set image type.
>>   Pass \-h as the image to see the list of supported image type.
>>   .
>>   .TP
>> -.BI "\-C [" "compression type" "]"
>> +.BI \-C " compression-type"
>>   Set compression type.
>>   Pass \-h as the compression to see the list of supported compression type.
>>   .
>>   .TP
>> -.BI "\-a [" "load address" "]"
>> +.BI \-a " load-address"
>>   Set load address with a hex number.
>>   .
>>   .TP
>> -.BI "\-e [" "entry point" "]"
>> +.BI \-e " entry-point"
>>   Set entry point with a hex number.
>>   .
>>   .TP
>> -.BI "\-l"
>> +.B \-l
>>   List the contents of an image.
>>   .
>>   .TP
>> -.BI "\-n [" "image name" "]"
>> +.BI \-n " image-name"
>>   Set image name to 'image name'.
>>   .
>>   .TP
>> -.BI "\-R [" "secondary image name" "]"
>> +.BI \-R " secondary-image-name"
>>   Some image types support a second image for additional data. For these types,
>>   use \-R to specify this second image.
>>   .TS
>> @@ -135,42 +135,42 @@ T}
>>   .TE
>>   .
>>   .TP
>> -.BI "\-d [" "image data file" "]"
>> +.BI \-d " image-data-file"
>>   Use image data from 'image data file'.
>>   .
>>   .TP
>> -.BI "\-x"
>> +.B \-x
>>   Set XIP (execute in place) flag.
>>   .
>>   .TP
>> -.BI "\-s"
>> +.B \-s
>>   Don't copy in the image data. Depending on the image type, this may create
>>   just the header, everything but the image data, or nothing at all.
>>   .
>>   .TP
>> -.BI "\-v"
>> +.B \-v
>>   Verbose. Print file names as they are added to the image.
>>   .
>>   .P
>>   .B Create FIT image:
>>   .
>>   .TP
>> -.BI "\-b [" "device tree file" "]
>> +.BI \-b " device-tree-file"
>>   Appends the device tree binary file (.dtb) to the FIT.
>>   .
>>   .TP
>> -.BI "\-c [" "comment" "]"
>> +.BI \-c " comment"
>>   Specifies a comment to be added when signing. This is typically a useful
>>   message which describes how the image was signed or some other useful
>>   information.
>>   .
>>   .TP
>> -.BI "\-D [" "dtc options" "]"
>> +.BI \-D " dtc-options"
>>   Provide special options to the device tree compiler that is used to
>>   create the image.
>>   .
>>   .TP
>> -.BI "\-E
>> +.BI \-E
>>   After processing, move the image data outside the FIT and store a data offset
>>   in the FIT. Images will be placed one after the other immediately after the
>>   FIT, with each one aligned to a 4-byte boundary. The existing 'data' property
>> @@ -179,12 +179,12 @@ A 'data-offset' of 0 indicates that it starts in the first (4-byte aligned)
>>   byte after the FIT.
>>   .
>>   .TP
>> -.BI "\-B [" "alignment" "]"
>> +.BI \-B " alignment"
>>   The alignment, in hexadecimal, that external data will be aligned to. This
>>   option only has an effect when \-E is specified.
>>   .
>>   .TP
>> -.BI "\-f [" "image tree source file" " | " "auto" "]"
>> +.BI \-f " image-tree-source-file"
>>   Image tree source file that describes the structure and contents of the
>>   FIT image.
>>   .IP
>> @@ -194,29 +194,29 @@ and -e are used to specify the image to include in the FIT and its attributes.
>>   No .its file is required.
>>   .
>>   .TP
>> -.BI "\-F"
>> +.B \-F
>>   Indicates that an existing FIT image should be modified. No dtc
>>   compilation is performed and the \-f flag should not be given.
>>   This can be used to sign images with additional keys after initial image
>>   creation.
>>   .
>>   .TP
>> -.BI "\-i [" "ramdisk_file" "]"
>> +.BI \-i " ramdisk-file"
>>   Appends the ramdisk file to the FIT.
>>   .
>>   .TP
>> -.BI "\-k [" "key_directory" "]"
>> +.BI \-k " key-directory"
>>   Specifies the directory containing keys to use for signing. This directory
>>   should contain a private key file <name>.key for use with signing and a
>>   certificate <name>.crt (containing the public key) for use with verification.
>>   .
>>   .TP
>> -.BI "\-G [" "key_file" "]"
>> +.BI \-G " key-file"
>>   Specifies the private key file to use when signing. This option may be used
>>   instead of \-k.
>>   .
>>   .TP
>> -.BI "\-K [" "key_destination" "]"
>> +.BI \-K " key-destination"
>>   Specifies a compiled device tree binary file (typically .dtb) to write
>>   public key information into. When a private key is used to sign an image,
>>   the corresponding public key is written into this file for for run-time
>> @@ -224,42 +224,42 @@ verification. Typically the file here is the device tree binary used by
>>   CONFIG_OF_CONTROL in U-Boot.
>>   .
>>   .TP
>> -.BI "\-G [" "key_file" "]"
>> +.BI \-G " key-file"
>>   Specifies the private key file to use when signing. This option may be used
>>   instead of \-k.
>>   .
>>   .TP
>> -.BI "\-g [" "key_name_hint" "]"
>> +.BI \-g " key-name-hint"
>>   Sets the key-name-hint property when used with \-f auto. This is the <name>
>>   part of the key. The directory part is set by \-k. This option also indicates
>>   that the images included in the FIT should be signed. If this option is
>>   specified, \-o must be specified as well.
>>   .
>>   .TP
>> -.BI "\-o [" "signing algorithm" "]"
>> +.BI \-o " signing-algorithm"
>>   Specifies the algorithm to be used for signing a FIT image. The default is
>>   taken from the signature node's 'algo' property.
>>   .
>>   .TP
>> -.BI "\-p [" "external position" "]"
>> +.BI \-p " external-position"
>>   Place external data at a static external position. See \-E. Instead of writing
>>   a 'data-offset' property defining the offset from the end of the FIT, \-p will
>>   use 'data-position' as the absolute position from the base of the FIT.
>>   .
>>   .TP
>> -.BI "\-r"
>> +.B \-r
>>   Specifies that keys used to sign the FIT are required. This means that they
>>   must be verified for the image to boot. Without this option, the verification
>>   will be optional (useful for testing but not for release).
>>   .
>>   .TP
>> -.BI "\-N [" "engine" "]"
>> +.BI \-N " engine"
>>   The openssl engine to use when signing and verifying the image. For a complete list of
>>   available engines, refer to
>>   .BR engine (1).
>>   .
>>   .TP
>> -.BI "\-t
>> +.B \-t
>>   Update the timestamp in the FIT.
>>   .IP
>>   Normally the FIT timestamp is created the first time mkimage is run on a FIT,
>