[U-Boot] [PATCH] Add mkimage manual

[Mike Frysinger]

On Thursday 15 October 2009 23:01:18 Nobuhiro Iwamatsu wrote:
> +mkimage \- generate kernel image for U-Boot

mkimage creates bootable U-Boot images.  there is no "kernel" restriction.

> +.SH SYNOPSIS
> +.B mkimage
> +.RB [\fIoptions\fP]
> +.SH "DESCRIPTION"
> +.B mkimage
> +can also be used to create ramdisk images for use with U-Boot, either

eh ?  mkimage doesnt create ramdisk images afaik.

> +separated from the Linux kernel image, or combined into one file.
> +mkimage encapsulates the images with a 64 byte header containing

the exact header size doesnt matter to the description

>  information about target architecture, operating system, image type,
>  compression method, entry points, time stamp, CRC32 checksums, etc.

i dont think CRC32 needs to be mentioned either ... "checksum" is fine.

> +.SH "MKIMAGE OPTIONS"

just "OPTIONS"

> +.TP
> +.BI "\-A [" "architecture" "]"
> +Set architecture.
> +You can set the following architecture.
> +.br
> +\fBalpha\fR,
> +\fBarm\fR,
> +\fBx86\fR,
> +\fBia64\fR,
> +\fBm68k\fR,
> +\fBmicroblaze\fR,
> +\fBmips\fR,
> +\fBmips64\fR,
> +\fBppc\fR,
> +\fBs390\fR,
> +\fBsh\fR,
> +\fBsparc\fR,
> +\fBsparc64\fR.

this is pretty ugly syntax -- easy to typo and hard to read.  this is why 
people do:
.BR foo ,
.BR moo ,
.BR cow ,

ignoring that, i dont think we need to list the arches.  otherwise it's just 
one more random list that needs to be updated whenever arches are 
added/removed.  better to say something like:
Pass -h as the architecture to see the list of supported architectures.

> +.BI "\-O [" "os" "]"
> +Set operating system. bootm command of u-boot changes boot method by os
>  type

same issues with this hardcoded list.

> +.BI "\-T [" "image type" "]"
> +Set image type.

and this list

> +.BI "\-C [" "compression type" "]"
> +Set compression type.

and this list

> +.BI "\-a [" "load addess" "]"
> +Set load address by hex digit.
> +.BI "\-e [" "entry point" "]"
> +Set entry point by hex digit.

"by hex digit" -> "with a hex number"

> +.BI "\-n [" "image name" "]"
> +Set image name.

be good to mention that the name is purely a human friendly description

> +.BI "\-d [" "image data file" "]"
> +See image data file.

should expand on what exactly an "image data file" is ... copying the short 
description from `mkimage -h` isnt terribly useful

> +.SH AUTHOR
> +This manual page was written by Nobuhiro Iwamatsu <iwamatsu at nigauri.org>,
> +for the Debian GNU/Linux system (but may be used by others).

was it really written for Debian GNU/Linux, or did you just copy & paste from 
some other file ?

> +Permission is granted to copy, distribute and/or modify this document
> +under the terms of the GNU General Public License, Version 2 any later
> +version published by the Free Software Foundation.

i'd stick the licensing info as a comment at the top of the file.  personally, 
i find licensing blobs in man pages to be pure noise.  anyone who cares about 
the "source" will read it and see the license info.
-mike
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 836 bytes
Desc: This is a digitally signed message part.
Url : http://lists.denx.de/pipermail/u-boot/attachments/20091015/8a181779/attachment.pgp