Update to CUSTOM_WPS. Now has an If/Else ability. Also updated the docs

git-svn-id: svn://svn.rockbox.org/rockbox/trunk@1990 a1c6a512-1295-4272-9138-f99709370657

docs/CUSTOM_WPS_FORMAT

@@ -1,46 +1,78 @@
 Custom WPS Display
 wps.config File Format Specifications
 
-Description
------------
-The Custom WPS Display is used on the Rockbox Player ONLY as a means 
-to customize the WPS to the user's likings. 
-The first line of the 2 line display is the customized line (scrolling).
-The second line is always the time display. (Elapsed & Total Time).
-The second line is not able to be customized.
-All characters not preceded by % are displayed as typed.
+
+Description / General Info
+--------------------------
+* The Custom WPS Display is used on the Rockbox Player ONLY, as a means 
+  to customize the WPS to the user's likings.
+* Plans to implement this feature into the recorder are in progress.
+* The first line of the 2 line display is the customized line (scrolling).
+* The second line is always the time display. (Elapsed & Total Time).
+* The second line is not able to be customized.
+* Any CR's, LF's, or CR/LF's (Commonly known as Newline/Return/Enter) in 
+  the wps.config file will be treated as spaces. IE: Don't use them.
+* After editing the wps.config file, you may need to reboot your Rockbox.
+* All tags except for %%, %?, and %: contain 3 characters (%xx). Remember
+  to type the tags correctly, or you will get unexpected output, or even
+  possibly no output at all.
+* All characters not preceded by % are displayed as typed.
+
 
 File Location
 -------------
 The configuration file must be located in the root folder of the
 device and must be named wps.config (lowercase)
 
+
 Tags
 ----
-%t : ID3 Title
-%a : ID3 Artist
-%n : ID3 Track Number
-%u : ID3 Album
-%c : Conditional Title/Filename
-       Displays "Artist - Title" *or*
-       Displays Filename if no ID3 Artist/Title
-%h : Conditional Title/Filename
-       Displays "Title - Artist" *or*
-       Displays Filename if no ID3 Artist/Title
-%b : File Bitrate
-%f : File Frequency
-%p : File Path
-%m : File Name
-%s : File Size (In Kilobytes)
-%i : Playlist Position
-%l : Playlist Total Entries
-%e : Elapsed Track Time
-%o : Total Track Time
-%% : Displays a %
+ID3 Info Tags:
+  %it : ID3 Title
+  %ia : ID3 Artist
+  %in : ID3 Track Number
+  %id : ID3 Album
+File Info Tags:
+  %fc : Conditional Title/Filename
+        Displays "Artist - Title" *or*
+        Displays Filename if no ID3 Artist/Title
+  %fd : Conditional Title/Filename
+        Displays "Title - Artist" *or*
+        Displays Filename if no ID3 Artist/Title
+  %fb : File Bitrate
+  %ff : File Frequency
+  %fp : File Path
+  %fn : File Name
+  %fs : File Size (In Kilobytes)
+Playlist/Song Info Tags:
+  %pp : Playlist Position
+  %pe : Playlist Total Entries
+  %pc : Current Time In Song
+  %pt : Total Track Time
+Other Tags:
+  %% : Displays a %
+Conditional ID3/File Tags (If/Else block):
+  The following two tags are completely optional, and meant only for those
+    that wish to go crazy with customization. It lets you specify what to
+    do when it finds an ID3 tag, and also when it doesn't find one. It can
+    be placed anywhere within the wps.config file.  
+  The first condition of the If/Else block is what to do when it DOES find
+    valid ID3 tags. The second condition is what to do when there are no
+    valid ID3 tags available.
+  %? : Start/End an If/Else block
+  %: : Seperator between If and Else
+  Example:
+    To display "Title - Artist" if there is ID3 available, or "Filename"
+    if there is no ID3, the following string would be used:
+      %?%it - %ia%:%fn%?
+    Yes, you are not going crazy (although I may be)... This *IS* more
+    confusing then Perl :-)
 
-Example wps.config File
+
+Example wps.config File (Without If/Else)
 -----------------------
-%i/%l: %c * %sKB
+%pp/%pe: %fc * %fsKB
+
 
 Example Output
 --------------
@@ -53,5 +85,8 @@ File Size:              3500
 Elapsed Track Time:     2:23
 Total Track Time:       3:01
 The output of this on the player would be:
-5/10: My Song.mp3 * 3500KB
-2:23/3:01
+ ---------------------------
+| 5/10: My Song.mp3 * 3500KB|
+| 2:23/3:01                 |
+ ---------------------------
+Of course, the whole first line wouldn't fit, so it scrolls it.