[PATCH v8 04/12] tools: mkeficapsule: add man page

[Heinrich Schuchardt]

On 1/7/22 03:31, AKASHI Takahiro wrote:
> On Thu, Jan 06, 2022 at 08:26:03PM +0100, Heinrich Schuchardt wrote:
>> On 1/6/22 11:25, AKASHI Takahiro wrote:
>>> Heinrich,
>>>
>>> On Sat, Jan 01, 2022 at 11:02:52PM +0100, Heinrich Schuchardt wrote:
>>>> On 12/20/21 06:02, AKASHI Takahiro wrote:
>>>>> Add a man page for mkeficapsule command.
>>>>>
>>>>> Signed-off-by: AKASHI Takahiro <takahiro.akashi at linaro.org>
>>>>> Reviewed-by: Simon Glass <sjg at chromium.org>
>>>>> Acked-by: Ilias Apalodimas <ilias.apalodimas at linaro.org>
>>>>> ---
>>>>>     MAINTAINERS        |  1 +
>>>>>     doc/mkeficapsule.1 | 95 ++++++++++++++++++++++++++++++++++++++++++++++
>>>>>     2 files changed, 96 insertions(+)
>>>>>     create mode 100644 doc/mkeficapsule.1
>>>>>
>>>>> diff --git a/MAINTAINERS b/MAINTAINERS
>>>>> index e718ad213553..93ef5e297acc 100644
>>>>> --- a/MAINTAINERS
>>>>> +++ b/MAINTAINERS
>>>>> @@ -723,6 +723,7 @@ S:	Maintained
>>>>>     T:	git https://source.denx.de/u-boot/custodians/u-boot-efi.git
>>>>>     F:	doc/api/efi.rst
>>>>>     F:	doc/develop/uefi/*
>>>>> +F:	doc/mkeficapsule.1
>>>>>     F:	doc/usage/bootefi.rst
>>>>>     F:	drivers/rtc/emul_rtc.c
>>>>>     F:	include/capitalization.h
>>>>> diff --git a/doc/mkeficapsule.1 b/doc/mkeficapsule.1
>>>>> new file mode 100644
>>>>> index 000000000000..837e09ab451e
>>>>> --- /dev/null
>>>>> +++ b/doc/mkeficapsule.1
>>>>> @@ -0,0 +1,95 @@
>>>>
>>>> Please, provide copyright information. Cf.
>>>> https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/man7/fanotify.7.
>>>
>>> OK
>>>
>>>>> +.TH MAEFICAPSULE 1 "May 2021"
>>>>> +
>>>>> +.SH NAME
>>>>> +mkeficapsule \- Generate EFI capsule file for U-Boot
>>>>> +
>>>>> +.SH SYNOPSIS
>>>>> +.B mkeficapsule
>>>>> +.RB [\fIoptions\fP] " \fIcapsule-file\fP"
>>>>
>>>> .RI [ options ] " capsule-file
>>>
>>> I don't have any strong preference for those notations,
>>> but I simply followed the existing format used in doc/kwboot.1
>>> and doc/mkimage.1 which are the only two instances of
>>> man pages in the U-Boot source.
>>>
>>> So I'd like to see guidelines/rules for U-Boot first.
>>
>> See man 7 man-pages:
>>
>> "The preferred way to write this in the source file is:
>>
>>             .BR fcntl ()
>>
>> (Using  this  format,  rather  than the use of "\fB...\fP()" makes it
>> easier to write tools that parse man page source files.)"
>
> Well, the sentence that you cited here has a precedent one:
>
>      Any reference to the subject of the current manual page should be writ-
>      ten  with  the  name in bold followed by a pair of parentheses in Roman
>      (normal) font.
>
> I doubt it is a general requirement.

It is.

>
>>>
>>>>> +
>>>>> +.SH "DESCRIPTION"
>>>>> +The
>>>>> +\fBmkeficapsule\fP
>>>>
>>>> .B mkeficapsule
>>>
>>> ditto
>>> I can find a use of "\fB" (and others) also in your reference:
>>>> https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/man7/fanotify.7.
>>>
>>>>> +command is used to create an EFI capsule file for use with the U-Boot
>>>>> +EFI capsule update.
>>>>> +A capsule file may contain various type of firmware blobs which
>>>>> +are to be applied to the system and must be placed in the specific
>>>>> +directory on the UEFI system partition. An update will be automatically
>>>>> +executed at next reboot.
>>
>> Starting sentences in new lines makes future edits easier.
>
> ? I don't know what you are referring to here.

Starting a new line at a period looks like this:

A capsule file may contain various type of firmware blobs which
are to be applied to the system and must be placed in the specific
directory on the UEFI system partition.
An update will be automatically executed at next reboot.

>
>>>>> +
>>>>> +Optionally, a capsule file can be signed with a given private key.
>>>>> +In this case, the update will be authenticated by verifying the signature
>>>>> +before applying.
>>>>> +
>>>>> +\fBmkeficapsule\fP supports two different format of image files:
>>>>
>>>> .B mkeficapsule
>>>> supports two different format of image files:
>>>>
>>>>> +.TP
>>>>> +.I raw image
>>>>> +format is a single binary blob of any type of firmware.
>>>>> +
>>>>> +.TP
>>>>> +.I FIT (Flattened Image Tree) image
>>>>> +format
>>>>> +is the same as used in the new \fIuImage\fP format and allows for
>>>>
>>>> is the same as used in the new
>>>> .I uImage
>>>> format and allows for
>>>>
>>>> But why would you use italics for uImage? It is neither a command nor a
>>>> parameter.
>>>
>>> I don't know, but will drop the decoration here.
>>>
>>>> Please, rework the man page to avoid escape sequences.
>>>>
>>>> Best regards
>>>>
>>>> Heinrich
>>>>
>>>>> +multiple binary blobs in a single capsule file.
>>>>> +This type of image file can be generated by \fBmkimage\fP.
>>>>> +
>>>>> +.SH "OPTIONS"
>>>>> +One of \fB--fit\fP or \fB--raw\fP option must be specified.
>>>>> +
>>>>> +.TP
>>>>> +.BI "-f, --fit \fIfit-image-file\fP"
>>>>> +Specify a FIT image file
>>>>> +
>>>>> +.TP
>>>>> +.BI "-r, --raw \fIraw-image-file\fP"
>>>>> +Specify a raw image file
>>>>> +
>>>>> +.TP
>>>>> +.BI "-i, --index \fIindex\fP"
>>>>> +Specify an image index
>>>>> +
>>>>> +.TP
>>>>> +.BI "-I, --instance \fIinstance\fP"
>>>>> +Specify a hardware instance
>>>>> +
>>>>> +.TP
>>>>> +.BI "-h, --help"
>>>>> +Print a help message
>>>>> +
>>>>> +.TP 0
>>>>> +.B With signing:
>>>>> +
>>>>> +\fB--private-key\fP, \fB--certificate\fP and \fB--monotonic-count\fP are
>>>>> +all mandatory.
>>>>> +
>>>>> +.TP
>>>>> +.BI "-p, --private-key \fIprivate-key-file\fP"
>>>>> +Specify signer's private key file in PEM
>>>>> +
>>>>> +.TP
>>>>> +.BI "-c, --certificate \fIcertificate-file\fP"
>>>>> +Specify signer's certificate file in EFI certificate list format
>>>>> +
>>>>> +.TP
>>>>> +.BI "-m, --monotonic-count \fIcount\fP"
>>>>> +Specify a monotonic count which is set to be monotonically incremented
>>>>> +at every firmware update.
>>>>> +
>>>>> +.TP
>>>>> +.BI "-d, --dump_sig"
>>>>> +Dump signature data into *.p7 file
>>>>> +
>>>>> +.PP
>>>>> +.SH FILES
>>>>> +.TP
>>>>> +.BI "\fI/EFI/UpdateCapsule\fP"
>>>>> +The directory in which all capsule files be placed
>>>>> +
>>>>> +.SH SEE ALSO
>>>>> +.B mkimage
>>>>> +
>>>>> +.SH AUTHORS
>>>>> +Written by AKASHI Takahiro <takahiro.akashi at linaro.org>
>>>>
>>>> man man-pages discourages using an AUTHORS paragraph.
>>>
>>> ditto
>>> I see AUTHORS sections in doc/kwboot.1 and doc/mkimage.1.
>>
>> See man 7 man-pages:
>>
>> "AUTHORS          [Discouraged]"
>>
>> Your name can be placed in the copyright message.
>
> My point is:
>>> ditto
>>> I see AUTHORS sections in doc/kwboot.1 and doc/mkimage.1.

Don't copy bad templates.

>
> and so
>
>>> So I'd like to see guidelines/rules for U-Boot first.
>
> -Takahiro Akashi

The rule is simple. Kick that AUTHORS section out.

Best regards

Heinrich

>
>> Best regards
>>
>> Heinrich
>>
>>>
>>>
>>>> Please, put the information into copyright header.
>>>>
>>>> Best regards
>>>>
>>>> Heinrich
>>>>
>>>>> +
>>>>> +.SH HOMEPAGE
>>>>> +http://www.denx.de/wiki/U-Boot/WebHome
>>>
>>> For instance, no reference to "HOMEPAGE" in "man man-pages"
>>> but doc/mkimage.1 has one.
>>>
>>> -Takahiro Akashi
>>>
>>>>
>>>>
>>>>
>>>>
>>