Skip to content

doc: mkimage: Rework and refactor the man page; add long options

Sean Anderson u-boot 3 versions – In review

Get series with b4
b4 am [email protected]

Versions newest first · linked by author and title

  1. v3 Latest14 patches 14 repliesIn review
  2. v214 patches 8 repliesSuperseded
  3. v112 patches 1 replySuperseded

Changes in v3 from the cover letter

- Clarify intent in commit message
- Document option defaults
- Document the various content changes in the commit message
- Fix typo in commit message
- Note that "legacy" images are only legacy for U-Boot. In particular, mkimage supports many other image formats using the same syntax which are decidedly not "legacy."
- Remove "legacy" wording from synopsis
- Remove usage of "legacy" in section headings
- Reorder "legacy" synopsis first
- Use multiple .BRs for the -f auto option list

Patches in v3 No applies recorded yet

#Subject and filesSizeRepliesApplied
1/14doc: mkimage: Use standard style for synopsisdoc/mkimage.1+19 -81 reply
2/14doc: mkimage: Use empty request instead of blank linesdoc/mkimage.1+54 -541 reply
3/14doc: mkimage: Reformat examplesdoc/mkimage.1+67 -491 reply
4/14doc: mkimage: Regularize option documentationdoc/mkimage.1+36 -361 reply
5/14doc: mkimage: Use subsection macrodoc/mkimage.1+3 -51 reply
6/14doc: mkimage: Rearrange/remove some optionsdoc/mkimage.1+29 -331 reply
7/14doc: mkimage: Use correct capitalization for NAMEdoc/mkimage.1+1 -11 reply
8/14doc: mkimage: Edit options for style and consistencydoc/mkimage.1+205 -681 reply
9/14doc: mkimage: Add BUGS sectiondoc/mkimage.1+5 -21 reply
10/14doc: mkimage: Add SEE ALSO sectiondoc/mkimage.1+8 -01 reply
11/14doc: mkimage: Remove AUTHORS sectiondoc/mkimage.1+6 -61 reply
12/14mkimage: Add long optionsdoc/mkimage.1 tools/mkimage.c+109 -21 reply
13/14doc: mkimage: Further document -o and -Rdoc/mkimage.1+236 -341 reply
14/14doc: Add man page for dumpimagedoc/dumpimage.1+103 -01 reply

Reviews trailers per patch

All 14 patches have a Reviewed-by or Acked-by.

PatchSimon Glass
1/14R-b
2/14R-b
3/14R-b
4/14R-b
5/14R-b
6/14R-b
7/14R-b
8/14R-b
9/14R-b
10/14R-b
11/14R-b
12/14R-b
13/14R-b
14/14R-b

Trailers given in replies are filled; those carried in the patches from earlier versions are outlined with dashes.

Read the v3 thread

Cover letter [PATCH v3 00/14] doc: mkimage: Rework and refactor the man page; add long options

This gives a facelift for the mkimage man page, bringing it in line with the style perscribed by man-pages(7) and groff_man_style(7). I have tried to remove typographical and grammatical errors and inconsistencies wherever possible. The man page now both looks and feels closer to other Linux man pages. As a bonus, I also added a man page for dumpimage in the same style.

To address the impending exhaustion of short options, this also adds long options for each short option.

Changes in v3:
- Clarify intent in commit message
- Document option defaults
- Document the various content changes in the commit message
- Fix typo in commit message
- Note that "legacy" images are only legacy for U-Boot. In particular, mkimage supports many other image formats using the same syntax which are decidedly not "legacy."
- Remove "legacy" wording from synopsis
- Remove usage of "legacy" in section headings
- Reorder "legacy" synopsis first
- Use multiple .BRs for the -f auto option list

Changes in v2:
- Add long options
- Better document multi images
- Document -h and -V
- Ensure comments are requests
- Escape minus signs in examples
- Fix -B not being bolded in the description for -R
- Fix extra quote in -E synopsis
- Fix spacing for -F
- Further document -o and -R
- Indent things more robustly
- Italicize parameter for -d
- Make lists of valid algos bold
- Rearrange more options
- Remove spaces around pipes
- Rename first subsection to "General options"
- Use escape-sequences for options width all three of B/I/R. This renders better with mandoc.
- Use paired quotation marks

Sean Anderson (14):
doc: mkimage: Use standard style for synopsis
doc: mkimage: Use empty request instead of blank lines
doc: mkimage: Reformat examples
doc: mkimage: Regularize option documentation
doc: mkimage: Use subsection macro
doc: mkimage: Rearrange/remove some options
doc: mkimage: Use correct capitalization for NAME
doc: mkimage: Edit options for style and consistency
doc: mkimage: Add BUGS section
doc: mkimage: Add SEE ALSO section
doc: mkimage: Remove AUTHORS section
mkimage: Add long options
doc: mkimage: Further document -o and -R
doc: Add man page for dumpimage

 doc/dumpimage.1 | 103 +++++
 doc/mkimage.1   | 977 +++++++++++++++++++++++++++++++++++-------------
 tools/mkimage.c |  45 ++-
 3 files changed, 854 insertions(+), 271 deletions(-)
 create mode 100644 doc/dumpimage.1
Signature · 1 line
2.35.1