[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