Updated documentation to describe config file format.

This it what we finally agreed upon.

Change-Id: I9dd859d5932328a2174b76331178a7c61ed01b5d

BUG=chromium-os:781
TEST=none (documenation only)

Review URL: http://codereview.chromium.org/5743001

user_tools/README_recovery.txt

@@ -12,47 +12,73 @@ steps.
 3. Ask the user to select a USB drive, and write the recovery image to it.
 
 
+
+
 Here's the format of the config file:
 
-The config file is a text file containing at least two paragraphs or
-stanzas, which are separated by at least one blank line. Lines beginning
-with '#' are completely ignored and do not count as blank lines. Non-blank
-lines must consist of a non-blank key and non-blank value separated by a '='
-with no spaces on either side. The key may not contain whitespace. The value
-may contain spaces, but all trailing whitespace is discarded.
+The config file is a machine-generated, human-readable text file containing
+at least two paragraphs or stanzas, which are separated by at least one
+blank line.
+
+* Each line in the file ends with "\n" (LF), not "\r\n" (CRLF).
+
+* The file shall not contain any tab characters.
+
+* Lines beginning with '#' are completely ignored and do not count as blank
+  lines.
+
+* Non-blank lines must consist of a non-blank key and non-blank value
+  separated by a '=' with no spaces on either side. The key may not contain
+  whitespace. The value may contain spaces, but all trailing whitespace is
+  discarded.
+
+* The first stanza must contain a key named "recovery_tool_version'. Its
+  value must match the version of the recovery tool. If the value does not
+  match, then the key 'recovery_tool_update', if it exists in the first
+  stanza, should contain a string to display to the user. Regardless, if the
+  version doesn't match, the recovery tool should exit.
+
+* The first stanza MAY have platform-specific keys such as
+  'recovery_tool_linux_version'. If present, this key is used instead of the
+  'recovery_tool_version' key to determine the required recovery tool
+  version.
+
+* The current recovery_tool_version value is 0.9.1
+
+* The archive shall be in ZIP format.
 
-The first stanza must contain a key named "recovery_tool_version'. Its value
-must match the version of the recovery tool. If the value does not match,
-then the key 'recovery_tool_update', if it exists in the first stanza,
-should contain a string to display to the user. Regardless, if the version
-doesn't match, the recovery tool should exit.
 
 The second and remaining stanzas describe recovery images to put on the USB
-drive.
+drive. Each image stanza must contain, in this order:
 
-For recovery_tool_version=1.0, each image stanza must contain:
+* One and only one of each of these keys:
 
-* One and only one of these keys:
+   name           - string to show to the user
+   zipfilesize    - size in bytes of the zipfile
+   file           - the name of the file to extract from the zipfile
+   filesize       - size in bytes of the extracted, uncompressed file
+   channel        - the channel for this image ("beta-channel",
+                    "dev-channel", "pilot-channel", etc.)
 
-   display_name    - string to show to the user
-   file            - the name of the file to extract from the tarball
-   size            - size in bytes of the tarball
+* Zero or more of these keys:
 
-* One or more of these keys:
-
-   url             - where to find the tarball to download
+   hwid           - the HWID of the device which can use this image (no
+                    entry means "any device")
 
 * One or both of these keys:
 
-   md5             - md5sum of the tarball
-   sha1            - sha1sum of the tarball
+   md5            - md5sum of the zipfile
+   sha1           - sha1sum of the zipfile
 
-* Any other keys are informational only and are not used by the recovery tool.
+* One or more of these keys:
+
+   url            - where to find the zipfile to download
 
 
+Any other keys are informational only and are not used by the recovery tool.
 
-NOTE: This is still in flux. Possible additional keys are
+If more than one url is provided, then they should be tried, in turn, until
+one succeeds.
 
-  hwid
-  name
-  channel
+At a minimum, the user shall be shown the name, channel, and all hwid values
+for each image.