From: Sean Anderson <seanga2@gmail.com>
To: Heinrich Schuchardt <xypron.glpk@gmx.de>, u-boot@lists.denx.de
Cc: Simon Glass <sjg@chromium.org>
Subject: Re: [PATCH v2 04/14] doc: mkimage: Regularize option documentation
Date: Thu, 16 Jun 2022 09:42:30 -0400 [thread overview]
Message-ID: <5b33cc15-e909-71f8-f494-e376e814b8c1@gmail.com> (raw)
In-Reply-To: <eedfcd07-33b5-1a0c-00f7-d2b0a379428c@gmx.de>
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@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,
>
next prev parent reply other threads:[~2022-06-16 13:42 UTC|newest]
Thread overview: 23+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-06-12 22:13 [PATCH v2 00/14] doc: mkimage: Rework and refactor the man page; add long options Sean Anderson
2022-06-12 22:13 ` [PATCH v2 01/14] doc: mkimage: Use standard style for synopsis Sean Anderson
2022-06-16 9:45 ` Heinrich Schuchardt
2022-06-16 13:40 ` Sean Anderson
2022-06-12 22:13 ` [PATCH v2 02/14] doc: mkimage: Use empty request instead of blank lines Sean Anderson
2022-06-12 22:14 ` [PATCH v2 03/14] doc: mkimage: Reformat examples Sean Anderson
2022-06-12 22:14 ` [PATCH v2 04/14] doc: mkimage: Regularize option documentation Sean Anderson
2022-06-16 10:00 ` Heinrich Schuchardt
2022-06-16 13:42 ` Sean Anderson [this message]
2022-06-12 22:14 ` [PATCH v2 05/14] doc: mkimage: Use subsection macro Sean Anderson
2022-06-16 10:08 ` Heinrich Schuchardt
2022-06-16 13:45 ` Sean Anderson
2022-06-12 22:14 ` [PATCH v2 06/14] doc: mkimage: Rearrange/remove some options Sean Anderson
2022-06-12 22:14 ` [PATCH v2 07/14] doc: mkimage: Use correct capitalization for NAME Sean Anderson
2022-06-12 22:14 ` [PATCH v2 08/14] doc: mkimage: Edit options for style and consistency Sean Anderson
2022-06-12 22:14 ` [PATCH v2 09/14] doc: mkimage: Add BUGS section Sean Anderson
2022-06-12 22:14 ` [PATCH v2 10/14] doc: mkimage: Add SEE ALSO section Sean Anderson
2022-06-12 22:14 ` [PATCH v2 11/14] doc: mkimage: Remove AUTHORS section Sean Anderson
2022-06-12 22:14 ` [PATCH v2 12/14] mkimage: Add long options Sean Anderson
2022-06-12 22:14 ` [PATCH v2 13/14] doc: mkimage: Further document -o and -R Sean Anderson
2022-06-12 22:14 ` [PATCH v2 14/14] doc: Add man page for dumpimage Sean Anderson
2022-06-16 11:50 ` Heinrich Schuchardt
2022-06-16 13:47 ` Sean Anderson
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=5b33cc15-e909-71f8-f494-e376e814b8c1@gmail.com \
--to=seanga2@gmail.com \
--cc=sjg@chromium.org \
--cc=u-boot@lists.denx.de \
--cc=xypron.glpk@gmx.de \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).