Add ubinize manpage

This patch removes the lengthy help text from the ubinize utility
that attempted to describte the file format and every minor detail,
and reformats it into a more readable man page.

Signed-off-by: David Oberhollenzer <david.oberhollenzer@sigma-star.at>

4 files changed, 153 insertions, 55 deletions

diff --git a/Makefile.am b/Makefile.am
index a3457c0..23c1940 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -22,6 +22,7 @@ noinst_SCRIPTS =
 pkglibexec_PROGRAMS =
 pkglibexec_SCRIPTS =
 dist_man1_MANS =
+dist_man8_MANS =
 
 EXTRA_DIST =
 
diff --git a/ubi-utils/Makemodule.am b/ubi-utils/Makemodule.am
index ea18235..dc68f38 100644
--- a/ubi-utils/Makemodule.am
+++ b/ubi-utils/Makemodule.am
@@ -66,8 +66,13 @@ UBI_EXTRA = \
 UBI_HEADER = \
 	ubi-utils/include ubi-utils/libubi_int.h
 
+UBI_MAN = \
+	ubi-utils/ubinize.8
+
 EXTRA_DIST += $(UBI_HEADER) $(UBI_EXTRA)
 
+dist_man8_MANS += $(UBI_MAN)
+
 sbin_PROGRAMS += $(UBI_BINS)
 
 noinst_LIBRARIES += libubi.a libubigen.a
diff --git a/ubi-utils/ubinize.8 b/ubi-utils/ubinize.8
new file mode 100644
index 0000000..baf8abf
--- /dev/null
+++ b/ubi-utils/ubinize.8
@@ -0,0 +1,136 @@
+.TH UBINIZE 8 "September 2016" "mtd-utils"
+.SH NAME
+ubinize \- a tool for generating UBI images
+.SH SYNOPSIS
+.B ubinize
+[-o filename] [-p <bytes>] [-m <bytes>] [-s <bytes>] [-O <num>] [-e <num>]
+[-x <num>] [-Q <num>] [-v] [-h] [-V] [--output=<filename>] [--peb-size=<bytes>]
+[--min-io-size=<bytes>] [--sub-page-size=<bytes>] [--vid-hdr-offset=<num>]
+[--erase-counter=<num>] [--ubi-ver=<num>] [--image-seq=<num>] [--verbose]
+[--help] [--version] ini-file
+.SH DESCRIPTION
+An UBI image may contain one or more UBI volumes which have to be defined in
+the input configuration ini-file. The ini file defines all the UBI volumes \-
+their characteristics and the contents, but it does not define the
+characteristics of the flash the UBI image is generated for. Instead, the
+flash characteristics are defined via the command-line options. Note, if not
+sure about some of the command-line parameters, do not specify them and let
+the utility use default values.
+.SH OPTIONS
+.TP
+.BR \-o , " \-\-output=\fIfile\fP"
+Specify output file
+.TP
+.BR \-p , " \-\-peb\-size=\fIbytes\fP"
+Size of the physical eraseblock of the flash this UBI image is created for
+in bytes, kilobytes (KiB), or megabytes (MiB). This parameter is mandatory.
+.TP
+.BR \-m , " \-\-min\-io-size=\fIbytes\fP"
+Minimum input/output unit size of the flash in bytes
+.TP
+.BR \-s , " \-\-sub\-page\-size=\fIbytes\fP"
+Minimum input/output unit used for UBI headers, e.g. sub-page size in case
+of NAND flash (equivalent to the minimum input/output unit size by default).
+.TP
+.BR \-O , " \-\-vid\-hdr\-offset=\fInum\fP"
+Offset if the VID header from start of the physical eraseblock (default is the
+next minimum I/O unit or sub-page after the EC header)
+.TP
+.BR \-e , " \-\-erase\-counter=\fInum\fP"
+The erase counter value to put to EC headers (default is 0).
+.TP
+.BR \-x , " \-\-ubi\-ver=\fInum\fP"
+UBI version number to put to EC headers (default is 1).
+.TP
+.BR \-Q , " \-\-image\-seq=\fInum\fP"
+32-bit UBI image sequence number to use (by default a random number is picked).
+.TP
+.BR \-v , " \-\-verbose"
+Be verbose.
+.TP
+.BR \-h , " \-\-help"
+Print a help message and exit.
+.TP
+.BR \-V , " \-\-version"
+Print program version and exit.
+.SH EXAMPLE
+ubinize -o ubi.img -p 16KiB -m 512 -s 256 cfg.ini
+
+Create UBI image \fIubi.img\fP as described by configuration file
+\fIcfg.ini\fP.
+
+A physical erase block on the flash is \fI16KiB\fP in size and has \fI512\fP
+byte pages with \fI256\fP byte sub-pages.
+.SH INI-FILE FORMAT
+The input configuration ini-file describes all the volumes which have to
+be included to the output UBI image. Each volume is described in its own
+section which may be named arbitrarily. The section consists on
+"key=value" pairs, for example:
+.PP
+.in +4n
+.nf
+[jffs2\-volume]
+mode=ubi
+image=../jffs2.img
+vol_id=1
+vol_size=30MiB
+vol_type=dynamic
+vol_name=jffs2_volume
+vol_flags=autoresize
+vol_alignment=1
+.fi
+.in
+
+This example configuration file tells the utility to create an UBI image
+with one volume with ID 1, volume size 30MiB, the volume is dynamic, has
+name \fIjffs2_volume\fP, \fIautoresize\fP volume flag, and alignment 1.
+
+The \fBimage=../jffs2.img\fP line tells the utility to take the contents of
+the volume from the \fB../jffs2.img\fP file. The size of the image file has
+to be less or equivalent to the volume size (30MiB).
+
+The \fBmode=ubi\fP line is mandatory and just tells that the section describes
+an UBI volume \- other section modes may be added in the future.
+
+Notes:
+.IP \[bu] 4
+Size in vol_size might be specified kilobytes (KiB), megabytes (MiB),
+gigabytes (GiB) or bytes (no modifier).
+.IP \[bu]
+If "vol_size" key is absent, the volume size is assumed to be
+equivalent to the size of the image file (defined by "image" key).
+.IP \[bu]
+If the "image" is absent, the volume is assumed to be empty
+.IP \[bu]
+Volume alignment must not be greater than the logical eraseblock size.
+.IP \[bu]
+One ini file may contain arbitrary number of sections, the utility will
+put all the volumes which are described by these section to the output
+UBI image file.
+.SH AUTHORS
+.nf
+Man page written by David Oberhollenzer, based on the help text of
+the ubinize utility written by Artem Bityutskiy and Oliver Lohmann.
+.fi
+.SH REPORTING BUGS
+Report mtd-utils bugs to the Linux mtd mailing list.
+.TP
+Linux mtd mailing list: <linux-mtd@lists.infradead.org>
+.TP
+Linux mtd home page: <http://www.linux-mtd.infradead.org/>
+.SH AVAILABILITY
+The ubinize command is part of the mtd-utils package and is available from
+ftp://ftp.infradead.org/pub/mtd-utils/.
+.SH COPYRIGHT
+Copyright \(co International Business Machines Corp., 2006
+.br
+Copyright \(co 2008 Nokia Corporation
+.br
+Copyright \(co 2016 sigma star gmbh
+
+License GPLv2: GNU GPL version 2 <http://gnu.org/licenses/gpl2.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.SH SEE ALSO
+.BR mkfs.jffs2 (1)
diff --git a/ubi-utils/ubinize.c b/ubi-utils/ubinize.c
index 60bbd9a..b5ebadc 100644
--- a/ubi-utils/ubinize.c
+++ b/ubi-utils/ubinize.c
@@ -39,15 +39,6 @@
 #include "common.h"
 #include "ubiutils-common.h"
 
-static const char doc[] = PROGRAM_NAME " version " VERSION
-" - a tool to generate UBI images. An UBI image may contain one or more UBI "
-"volumes which have to be defined in the input configuration ini-file. The "
-"ini file defines all the UBI volumes - their characteristics and the "
-"contents, but it does not define the characteristics of the flash the UBI "
-"image is generated for. Instead, the flash characteristics are defined via "
-"the command-line options. Note, if not sure about some of the command-line "
-"parameters, do not specify them and let the utility use default values.";
-
 static const char optionsstr[] =
 "-o, --output=<file name>     output file name\n"
 "-p, --peb-size=<bytes>       size of the physical eraseblock of the flash\n"
@@ -72,49 +63,13 @@ static const char optionsstr[] =
 "                             (by default a random number is picked)\n"
 "-v, --verbose                be verbose\n"
 "-h, --help                   print help message\n"
-"-V, --version                print program version";
+"-V, --version                print program version\n\n";
 
 static const char usage[] =
-"Usage: " PROGRAM_NAME " [-o filename] [-p <bytes>] [-m <bytes>] [-s <bytes>] [-O <num>] [-e <num>]\n"
-"\t\t[-x <num>] [-Q <num>] [-v] [-h] [-V] [--output=<filename>] [--peb-size=<bytes>]\n"
-"\t\t[--min-io-size=<bytes>] [--sub-page-size=<bytes>] [--vid-hdr-offset=<num>]\n"
-"\t\t[--erase-counter=<num>] [--ubi-ver=<num>] [--image-seq=<num>] [--verbose] [--help]\n"
-"\t\t[--version] ini-file\n"
-"Example: " PROGRAM_NAME " -o ubi.img -p 16KiB -m 512 -s 256 cfg.ini - create UBI image\n"
-"         'ubi.img' as described by configuration file 'cfg.ini'";
-
-static const char ini_doc[] = "INI-file format.\n"
-"The input configuration ini-file describes all the volumes which have to\n"
-"be included to the output UBI image. Each volume is described in its own\n"
-"section which may be named arbitrarily. The section consists on\n"
-"\"key=value\" pairs, for example:\n\n"
-"[jffs2-volume]\n"
-"mode=ubi\n"
-"image=../jffs2.img\n"
-"vol_id=1\n"
-"vol_size=30MiB\n"
-"vol_type=dynamic\n"
-"vol_name=jffs2_volume\n"
-"vol_flags=autoresize\n"
-"vol_alignment=1\n\n"
-"This example configuration file tells the utility to create an UBI image\n"
-"with one volume with ID 1, volume size 30MiB, the volume is dynamic, has\n"
-"name \"jffs2_volume\", \"autoresize\" volume flag, and alignment 1. The\n"
-"\"image=../jffs2.img\" line tells the utility to take the contents of the\n"
-"volume from the \"../jffs2.img\" file. The size of the image file has to be\n"
-"less or equivalent to the volume size (30MiB). The \"mode=ubi\" line is\n"
-"mandatory and just tells that the section describes an UBI volume - other\n"
-"section modes may be added in the future.\n"
-"Notes:\n"
-"  * size in vol_size might be specified kilobytes (KiB), megabytes (MiB),\n"
-"    gigabytes (GiB) or bytes (no modifier);\n"
-"  * if \"vol_size\" key is absent, the volume size is assumed to be\n"
-"    equivalent to the size of the image file (defined by \"image\" key);\n"
-"  * if the \"image\" is absent, the volume is assumed to be empty;\n"
-"  * volume alignment must not be greater than the logical eraseblock size;\n"
-"  * one ini file may contain arbitrary number of sections, the utility will\n"
-"    put all the volumes which are described by these section to the output\n"
-"    UBI image file.";
+"Usage: " PROGRAM_NAME " [options] <ini-file>\n\n"
+"Generate UBI images. An UBI image may contain one or more UBI volumes which\n"
+"have to be defined in the input configuration ini-file. The flash\n"
+"characteristics are defined via the command-line options.\n\n";
 
 static const struct option long_options[] = {
 	{ .name = "output",         .has_arg = 1, .flag = NULL, .val = 'o' },
@@ -227,10 +182,10 @@ static int parse_opt(int argc, char * const argv[])
 			break;
 
 		case 'h':
-			ubiutils_print_text(stdout, doc, 80);
-			printf("\n%s\n\n", ini_doc);
-			printf("%s\n\n", usage);
-			printf("%s\n", optionsstr);
+			fputs(usage, stdout);
+			fputs(optionsstr, stdout);
+			printf("For more information see `man 8 %s`\n\n",
+				PROGRAM_NAME);
 			exit(EXIT_SUCCESS);
 
 		case 'V':
@@ -238,7 +193,8 @@ static int parse_opt(int argc, char * const argv[])
 			exit(EXIT_SUCCESS);
 
 		default:
-			fprintf(stderr, "Use -h for help\n");
+			fputs(usage, stderr);
+			fputs("Use -h for help\n\n", stderr);
 			return -1;
 		}
 	}