[PATCH v2 04/14] doc: mkimage: Regularize option documentation
Heinrich Schuchardt
xypron.glpk at gmx.de
Thu Jun 16 12:00:05 CEST 2022
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.
Best regards
Heinrich
> 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,
More information about the U-Boot
mailing list