Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from phobos.denx.de (phobos.denx.de [85.214.62.61]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 8D52CC43334 for ; Thu, 16 Jun 2022 13:42:41 +0000 (UTC) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id 4959484368; Thu, 16 Jun 2022 15:42:39 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=u-boot-bounces@lists.denx.de Authentication-Results: phobos.denx.de; dkim=pass (2048-bit key; unprotected) header.d=gmail.com header.i=@gmail.com header.b="Bg4Ymehf"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id A36598437C; Thu, 16 Jun 2022 15:42:36 +0200 (CEST) Received: from mail-qv1-xf2b.google.com (mail-qv1-xf2b.google.com [IPv6:2607:f8b0:4864:20::f2b]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits)) (No client certificate requested) by phobos.denx.de (Postfix) with ESMTPS id C8F2884362 for ; Thu, 16 Jun 2022 15:42:32 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=seanga2@gmail.com Received: by mail-qv1-xf2b.google.com with SMTP id o16so1011851qvr.10 for ; Thu, 16 Jun 2022 06:42:32 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=subject:to:cc:references:from:message-id:date:user-agent :mime-version:in-reply-to:content-language:content-transfer-encoding; bh=HgJWRIwJTOACNUEiBuzSylES7NY9OAwZ7bW+W+Oq6iE=; b=Bg4YmehfWPxdjlK2G9pjFudGDWpE6489P8nPPyWhkd6/KsjU2TjhfPKBsuzTraS0J1 LqHPH60DPgBdGIU9IFK0HzeSLgN5uHVb2/aH6uNwgj8k1b+WHy0sY0ph+dyJXibCn2Cj N9HccczhB59bRuqlH3OfEBaGmvIZnb5Wi/jlIGmmHDFZD2VnOXtQ/U2a9HfKMxuy2gpc kVX8eVuKK3xPJ6BvaANqVlkRM7aRsmw/Wj46Fe3lBfFXTCkNrKn544ROoQ/m1WIgHIhG sA52G5Z3rD4QhI4Y9+sQYsP4oDHDuHQZYmemhuGHFNpZAp7bkc1yj9rLngnFxca45Wms nRmA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:subject:to:cc:references:from:message-id:date :user-agent:mime-version:in-reply-to:content-language :content-transfer-encoding; bh=HgJWRIwJTOACNUEiBuzSylES7NY9OAwZ7bW+W+Oq6iE=; b=hDZ9PBUdvgMuXpjKjZNVIZZANRWh5jvfitULqLzbFclgc1IogyTS8Ev9J40MZg1Jzt azphVWGgWhH/EDzEfSvyl6F/sg7PuXVrhKsFqvofgW8ZuIYTz6b54If8tnYDf5yr7hhe gmWwpQMpc8o4DWlX8OrjISHDw+r1MDPwm8/GfwGxp4V9gtKtP5bwTzXYK4K8V37V7WiP sztwbjDZ6gDE90wL2z/x1Mf0gfSyOO9erggw96SZj+nA7CzRBy7p0y7QONnFhGkCQOjk 4akg9UCrMDLn/u8Dq8oF8BormiCoqdsWtEZNWB7JRIo7/WtQJzas3639w6c+mfBNAyrK 1pkA== X-Gm-Message-State: AJIora9Ya/MOMG1kaWljpYbft08ebS+y+SHhDlXMc0xgI4Pp51aMicPA iFDbNRPoOg8uJHm1w10K2WY= X-Google-Smtp-Source: AGRyM1tA+BuSt0qaCaIXma35chFlW4AgW1CfVet+1vQK9r68PNg1QEjZcCIEv1AtyFv129PxhbtcKw== X-Received: by 2002:ac8:4e82:0:b0:305:c4a:37cd with SMTP id 2-20020ac84e82000000b003050c4a37cdmr4006768qtp.106.1655386951561; Thu, 16 Jun 2022 06:42:31 -0700 (PDT) Received: from [192.168.1.201] (pool-173-73-95-180.washdc.fios.verizon.net. [173.73.95.180]) by smtp.gmail.com with ESMTPSA id c4-20020a05620a268400b006a691904891sm1837787qkp.16.2022.06.16.06.42.30 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Thu, 16 Jun 2022 06:42:31 -0700 (PDT) Subject: Re: [PATCH v2 04/14] doc: mkimage: Regularize option documentation To: Heinrich Schuchardt , u-boot@lists.denx.de Cc: Simon Glass References: <20220612221411.1608406-1-seanga2@gmail.com> <20220612221411.1608406-5-seanga2@gmail.com> From: Sean Anderson Message-ID: <5b33cc15-e909-71f8-f494-e376e814b8c1@gmail.com> Date: Thu, 16 Jun 2022 09:42:30 -0400 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.12.0 MIME-Version: 1.0 In-Reply-To: Content-Type: text/plain; charset=utf-8; format=flowed Content-Language: en-US Content-Transfer-Encoding: quoted-printable X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.39 Precedence: list List-Id: U-Boot discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: u-boot-bounces@lists.denx.de Sender: "U-Boot" X-Virus-Scanned: clamav-milter 0.103.5 at phobos.denx.de X-Virus-Status: Clean 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 comman= d. >> However, all option arguments are mandatory. Remove these brackets. Th= is >> also removes some unnecessary quotation marks, and uses hyphens to con= nect >> words in option arguments. >> >> Signed-off-by: Sean Anderson >> --- >> >> Changes in v2: >> - Fix extra quote in -E synopsis >> >> =C2=A0 doc/mkimage.1 | 72 +++++++++++++++++++++++++-------------------= ------- >> =C2=A0 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 >> =C2=A0 (legacy mode) >> =C2=A0 .YS >> =C2=A0 . >> -.SH "DESCRIPTION" >> +.SH DESCRIPTION >> =C2=A0 The >> =C2=A0 .B mkimage >> =C2=A0 command is used to create images for use with the U-Boot boot l= oader. >> @@ -49,64 +49,64 @@ allows for more flexibility in handling images of = various types and also >> =C2=A0 enhances integrity protection of images with stronger checksums= =2E It also >> =C2=A0 supports verified boot. >> =C2=A0 . >> -.SH "OPTIONS" >> +.SH OPTIONS >> =C2=A0 . >> =C2=A0 .B List image information: >> =C2=A0 . >> =C2=A0 .TP >> -.BI "\-l [" "uimage file name" "]" >> +.BI \-l " uimage-file-name" >=20 > 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 mecha= nical removal of quotes. --Sean >> =C2=A0 mkimage lists the information contained in the header of an exi= sting U-Boot image. >> =C2=A0 . >> =C2=A0 .TP >> -.BI "\-T [" "image type" "]" >> +.BI \-T " image-type" >> =C2=A0 Parse image file as type. >> =C2=A0 Pass \-h as the image to see the list of supported image type. >> =C2=A0 Without this option image type is autodetected. >> =C2=A0 . >> =C2=A0 .TP >> -.BI "\-q" >> +.B \-q >> =C2=A0 Quiet. Don't print the image header on successful verification.= >> =C2=A0 . >> =C2=A0 .P >> =C2=A0 .B Create old legacy image: >> =C2=A0 . >> =C2=A0 .TP >> -.BI "\-A [" "architecture" "]" >> +.BI \-A " architecture" >> =C2=A0 Set architecture. Pass \-h as the architecture to see the list = of supported architectures. >> =C2=A0 . >> =C2=A0 .TP >> -.BI "\-O [" "os" "]" >> +.BI \-O " os" >> =C2=A0 Set operating system. bootm command of u-boot changes boot meth= od by os type. >> =C2=A0 Pass \-h as the OS to see the list of supported OS. >> =C2=A0 . >> =C2=A0 .TP >> -.BI "\-T [" "image type" "]" >> +.BI \-T " image-type" >> =C2=A0 Set image type. >> =C2=A0 Pass \-h as the image to see the list of supported image type. >> =C2=A0 . >> =C2=A0 .TP >> -.BI "\-C [" "compression type" "]" >> +.BI \-C " compression-type" >> =C2=A0 Set compression type. >> =C2=A0 Pass \-h as the compression to see the list of supported compre= ssion type. >> =C2=A0 . >> =C2=A0 .TP >> -.BI "\-a [" "load address" "]" >> +.BI \-a " load-address" >> =C2=A0 Set load address with a hex number. >> =C2=A0 . >> =C2=A0 .TP >> -.BI "\-e [" "entry point" "]" >> +.BI \-e " entry-point" >> =C2=A0 Set entry point with a hex number. >> =C2=A0 . >> =C2=A0 .TP >> -.BI "\-l" >> +.B \-l >> =C2=A0 List the contents of an image. >> =C2=A0 . >> =C2=A0 .TP >> -.BI "\-n [" "image name" "]" >> +.BI \-n " image-name" >> =C2=A0 Set image name to 'image name'. >> =C2=A0 . >> =C2=A0 .TP >> -.BI "\-R [" "secondary image name" "]" >> +.BI \-R " secondary-image-name" >> =C2=A0 Some image types support a second image for additional data. Fo= r these types, >> =C2=A0 use \-R to specify this second image. >> =C2=A0 .TS >> @@ -135,42 +135,42 @@ T} >> =C2=A0 .TE >> =C2=A0 . >> =C2=A0 .TP >> -.BI "\-d [" "image data file" "]" >> +.BI \-d " image-data-file" >> =C2=A0 Use image data from 'image data file'. >> =C2=A0 . >> =C2=A0 .TP >> -.BI "\-x" >> +.B \-x >> =C2=A0 Set XIP (execute in place) flag. >> =C2=A0 . >> =C2=A0 .TP >> -.BI "\-s" >> +.B \-s >> =C2=A0 Don't copy in the image data. Depending on the image type, this= may create >> =C2=A0 just the header, everything but the image data, or nothing at a= ll. >> =C2=A0 . >> =C2=A0 .TP >> -.BI "\-v" >> +.B \-v >> =C2=A0 Verbose. Print file names as they are added to the image. >> =C2=A0 . >> =C2=A0 .P >> =C2=A0 .B Create FIT image: >> =C2=A0 . >> =C2=A0 .TP >> -.BI "\-b [" "device tree file" "] >> +.BI \-b " device-tree-file" >> =C2=A0 Appends the device tree binary file (.dtb) to the FIT. >> =C2=A0 . >> =C2=A0 .TP >> -.BI "\-c [" "comment" "]" >> +.BI \-c " comment" >> =C2=A0 Specifies a comment to be added when signing. This is typically= a useful >> =C2=A0 message which describes how the image was signed or some other = useful >> =C2=A0 information. >> =C2=A0 . >> =C2=A0 .TP >> -.BI "\-D [" "dtc options" "]" >> +.BI \-D " dtc-options" >> =C2=A0 Provide special options to the device tree compiler that is use= d to >> =C2=A0 create the image. >> =C2=A0 . >> =C2=A0 .TP >> -.BI "\-E >> +.BI \-E >> =C2=A0 After processing, move the image data outside the FIT and store= a data offset >> =C2=A0 in the FIT. Images will be placed one after the other immediate= ly after the >> =C2=A0 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) >> =C2=A0 byte after the FIT. >> =C2=A0 . >> =C2=A0 .TP >> -.BI "\-B [" "alignment" "]" >> +.BI \-B " alignment" >> =C2=A0 The alignment, in hexadecimal, that external data will be align= ed to. This >> =C2=A0 option only has an effect when \-E is specified. >> =C2=A0 . >> =C2=A0 .TP >> -.BI "\-f [" "image tree source file" " | " "auto" "]" >> +.BI \-f " image-tree-source-file" >> =C2=A0 Image tree source file that describes the structure and content= s of the >> =C2=A0 FIT image. >> =C2=A0 .IP >> @@ -194,29 +194,29 @@ and -e are used to specify the image to include = in the FIT and its attributes. >> =C2=A0 No .its file is required. >> =C2=A0 . >> =C2=A0 .TP >> -.BI "\-F" >> +.B \-F >> =C2=A0 Indicates that an existing FIT image should be modified. No dtc= >> =C2=A0 compilation is performed and the \-f flag should not be given. >> =C2=A0 This can be used to sign images with additional keys after init= ial image >> =C2=A0 creation. >> =C2=A0 . >> =C2=A0 .TP >> -.BI "\-i [" "ramdisk_file" "]" >> +.BI \-i " ramdisk-file" >> =C2=A0 Appends the ramdisk file to the FIT. >> =C2=A0 . >> =C2=A0 .TP >> -.BI "\-k [" "key_directory" "]" >> +.BI \-k " key-directory" >> =C2=A0 Specifies the directory containing keys to use for signing. Thi= s directory >> =C2=A0 should contain a private key file .key for use with signi= ng and a >> =C2=A0 certificate .crt (containing the public key) for use with= verification. >> =C2=A0 . >> =C2=A0 .TP >> -.BI "\-G [" "key_file" "]" >> +.BI \-G " key-file" >> =C2=A0 Specifies the private key file to use when signing. This option= may be used >> =C2=A0 instead of \-k. >> =C2=A0 . >> =C2=A0 .TP >> -.BI "\-K [" "key_destination" "]" >> +.BI \-K " key-destination" >> =C2=A0 Specifies a compiled device tree binary file (typically .dtb) t= o write >> =C2=A0 public key information into. When a private key is used to sign= an image, >> =C2=A0 the corresponding public key is written into this file for for = run-time >> @@ -224,42 +224,42 @@ verification. Typically the file here is the dev= ice tree binary used by >> =C2=A0 CONFIG_OF_CONTROL in U-Boot. >> =C2=A0 . >> =C2=A0 .TP >> -.BI "\-G [" "key_file" "]" >> +.BI \-G " key-file" >> =C2=A0 Specifies the private key file to use when signing. This option= may be used >> =C2=A0 instead of \-k. >> =C2=A0 . >> =C2=A0 .TP >> -.BI "\-g [" "key_name_hint" "]" >> +.BI \-g " key-name-hint" >> =C2=A0 Sets the key-name-hint property when used with \-f auto. This i= s the >> =C2=A0 part of the key. The directory part is set by \-k. This option = also indicates >> =C2=A0 that the images included in the FIT should be signed. If this o= ption is >> =C2=A0 specified, \-o must be specified as well. >> =C2=A0 . >> =C2=A0 .TP >> -.BI "\-o [" "signing algorithm" "]" >> +.BI \-o " signing-algorithm" >> =C2=A0 Specifies the algorithm to be used for signing a FIT image. The= default is >> =C2=A0 taken from the signature node's 'algo' property. >> =C2=A0 . >> =C2=A0 .TP >> -.BI "\-p [" "external position" "]" >> +.BI \-p " external-position" >> =C2=A0 Place external data at a static external position. See \-E. Ins= tead of writing >> =C2=A0 a 'data-offset' property defining the offset from the end of th= e FIT, \-p will >> =C2=A0 use 'data-position' as the absolute position from the base of t= he FIT. >> =C2=A0 . >> =C2=A0 .TP >> -.BI "\-r" >> +.B \-r >> =C2=A0 Specifies that keys used to sign the FIT are required. This mea= ns that they >> =C2=A0 must be verified for the image to boot. Without this option, th= e verification >> =C2=A0 will be optional (useful for testing but not for release). >> =C2=A0 . >> =C2=A0 .TP >> -.BI "\-N [" "engine" "]" >> +.BI \-N " engine" >> =C2=A0 The openssl engine to use when signing and verifying the image.= For a complete list of >> =C2=A0 available engines, refer to >> =C2=A0 .BR engine (1). >> =C2=A0 . >> =C2=A0 .TP >> -.BI "\-t >> +.B \-t >> =C2=A0 Update the timestamp in the FIT. >> =C2=A0 .IP >> =C2=A0 Normally the FIT timestamp is created the first time mkimage is= run on a FIT, >=20