On 6/16/22 5:45 AM, Heinrich Schuchardt wrote:
On 6/13/22 00:13, Sean Anderson wrote:
The synopsis section is a bit messy. As an example, "uimage file name" is
printed in italics, bold, and roman (depending on the line). This cleans
things up and converts the synopsis section to use standard style. The
.SY/.YS macros set up appropriate fomatting for command synopsis sections
nits:
%s/fomatting/formatting/
(such as disabling hyphenation and setting a hanging indent). All parts of
the synopsis now use the following style:
- Bold for parts of the command which should be typed in by the user (such
as the program name and flags)
- Italic for parts which should be replaced (such as uimage-file-name)
- Roman for parts which should not be typed at all (such as brackets)
Multi-word variables now use hyphens to connect their words instead of
spaces. This makes it clearer that all the words are part of the same
variable. Additionally, "option ..." is used to denote where other options
may be specified, as this appears to be standard style.
Signed-off-by: Sean Anderson <sean...@gmail.com>
---
Changes in v2:
- Fix spacing for -F
doc/mkimage.1 | 26 ++++++++++++++++++--------
1 file changed, 18 insertions(+), 8 deletions(-)
diff --git a/doc/mkimage.1 b/doc/mkimage.1
index 759dc2d12f..dc597272d4 100644
--- a/doc/mkimage.1
+++ b/doc/mkimage.1
@@ -3,17 +3,27 @@
.SH NAME
mkimage \- Generate image for U-Boot
.SH SYNOPSIS
-.B mkimage
-.RB [ \-T " \fItype\fP] " \-l " [\fIuimage file name\fP]"
mkimage -T script -l boot.scr
is illegal. Why did you add '-T type'?
This is the original synopsis. I have kept it as-is. -T type is
necessary for some types which are not autodetected, e.g. pblimage.
+.SY mkimage
+.OP \-T type
+.BI \-l\~ image-file-name
Replacing uimage by image seems to be correct. But you could mention it
in the commit message.
Sure.
+.YS
-.B mkimage
-.RB [\fIoptions\fP] " \-f [" "image tree source file" "]" " [" "uimage file name"
"]"
+.SY mkimage
+.RI [ option\~ .\|.\|.\&]
+.BI \-f\~ image-tree-source-file\c
+.RB | auto
Adding 'auto' is also not mentioned in the commit message.
Will mention.
+.I image-file-name
+.YS
-.B mkimage
-.RB [\fIoptions\fP] " \-F [" "uimage file name" "]"
+.SY mkimage
+.RI [ option\~ .\|.\|.\&]
+.BI \-F\~ image-file-name
+.YS
-.B mkimage
-.RB [\fIoptions\fP] " (legacy mode)"
+.SY mkimage
+.RI [ option\~ .\|.\|.\&]
+.R (legacy mode)
(legacy mode) is not an argument. So it should not appear in the synopsis
That's why it's not in italics/bold.
The last addition of an image type has commit date 2022-04-04
(IH_TYPE_SUNXI_TOC0). The term 'legacy mode' for everything that is not
FIT is misleading and should be avoided.
I agree. I will remove it.
+.YS
.SH "DESCRIPTION"
The
The following command is not covered by any entry in the synopsis:
mkimage -T script -n GRUB -d boot.txt boot.scr
The synopsis lacks an entry
I believe this is covered by the "legacy" mode.
mkimage -T type [options] image-file-name
But perhaps it would be better to list "legacy" mode as
mkimage [options...] [-T type] image-file-name
--Sean
