bmap-flasher: imrove docs some more and have less duplication

Add some more documentation and use own docstring for 'bmap-flasher -h',
instead of duplicating the text.

Change-Id: I3afc50d72b661b2200307c3b275fbb15940d6f69
Signed-off-by: Artem Bityutskiy <artem.bityutskiy@intel.com>

diff --git a/BmapFlasher.py b/BmapFlasher.py
index e2b8241..6c6a8dc 100644 (file)
--- a/BmapFlasher.py
+++ b/BmapFlasher.py
@@ -7,6 +7,15 @@ then written to the block device. The rest of the blocks are not required to be
 copied. And usually image files have a lot of useless blocks (i.e., the blocks
 which are not used in the internal file-system of the image), so flashing with
 bmap is usually much faster than copying entire image to the block device.
+
+For example, you may have a 4GiB image file, which contains only 100MiB of user
+data. In this case, with the bmap file you will write only a little bit more
+than 100MiB of data from the image file to the block device. This is a lot
+faster than writing the entire 4GiB image. We say that it is a bit more than
+100MiB because there are also file-system meta-data, partition table, etc. The
+bmap fail is quite human-readable and contains a lot of commentaries. But
+essentially, it is an XML document which contains list of blocks in the image
+file which have to be copied to the block device.
 """
 
 import os

diff --git a/bmap-flasher b/bmap-flasher
index 33fd966..9cb4684 100755 (executable)
--- a/bmap-flasher
+++ b/bmap-flasher
@@ -4,6 +4,7 @@
 # License: GPLv2
 # Author: Artem Bityutskiy <artem.bityutskiy@linux.intel.com>
 
+# Note! We use the below docstring for the program help text as well.
 """
 Write raw image file to the target block device using the block map file (AKA
 bmap). The bmap contains list of blocks which have to be read from the image
@@ -12,6 +13,15 @@ required to be copied. And usually image files have a lot of useless blocks
 (i.e., the blocks which are not used in the internal file-system of the image),
 so flashing with bmap is usually much faster than copying entire image to the
 block device.
+
+For example, you may have a 4GiB image file, which contains only 100MiB of user
+data. In this case, with the bmap file you will write only a little bit more
+than 100MiB of data from the image file to the block device. This is a lot
+faster than writing the entire 4GiB image. We say that it is a bit more than
+100MiB because there are also file-system meta-data, partition table, etc. The
+bmap fail is quite human-readable and contains a lot of commentaries. But
+essentially, it is an XML document which contains list of blocks in the image
+file which have to be copied to the block device.
 """
 
 VERSION = "0.1.0"
@@ -27,25 +37,8 @@ import BmapFlasher
 def parse_arguments():
     """ A helper function which parses the input arguments. """
 
-    # The program description
-    text = "Flash an image file to a block device using the block map "       \
-           "(bmap). Although the bmap is optional, it generally improves "    \
-           "flashing speed a lot because with bmap you end up writing only "  \
-           "those parts of the image file to the block device, which "        \
-           "actually contain useful data. And you do not write useless data " \
-           "there. For example, you may have a 4GiB image file, which "       \
-           "contains only 100MiB of user data. In this case, with the bmap "  \
-           "file you will write only a little bit more than 100MiB of data "  \
-           "from the image file to the block device. Which is a lot faster "  \
-           "than writing the entire 4GiB image. We say that it is a bit "     \
-           "more than 100MiB because there are also file-system meta-data, "  \
-           "partition table, etc. The bmap fail is quite human-readable and " \
-           "you may take at it. It is an XML document which contains list "   \
-           "of blocks in the image file which have to be copied to the "      \
-           "block device. There are also nice commentaries which make it "    \
-           "easy to understand the bmap file contents."
-
-    parser = argparse.ArgumentParser(description = text, prog = 'bmap-flasher')
+    parser = argparse.ArgumentParser(description = __doc__,
+                                     prog = 'bmap-flasher')
 
     # The first command-line argument - block device node
     text = "The block device node to flash the image to."