Updated with new tags

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

docs/CUSTOM_WPS_FORMAT

@@ -1,7 +1,6 @@
 Custom WPS Display
 wps.config File Format Specifications
 
-
 Description / General Info
 --------------------------
 * The Custom WPS Display is used on both the Rockbox Player and Recorder, 
@@ -10,89 +9,71 @@ Description / General Info
 * The file may be 2 lines long for the Player, and 6 lines for the Recorder.
 * The line that has the time displayed on it MUST NOT be the line that
   is scrolled, or the time will not be updated.
-* 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
+The configuration file must be located in the /.rockbox folder of the
 device and must be named wps.config (lowercase)
 
-
 Tags
 ----
 ID3 Info Tags:
-  %it : ID3 Title
   %ia : ID3 Artist
+  %it : ID3 Track Title
   %in : ID3 Track Number
-  %id : ID3 Album
+  %id : ID3 Album Name
+
 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
+  %fb : File Bitrate (in kbps)
+  %ff : File Frequency (in Hz)
   %fp : File Path
   %fn : File Name
+  %fm : File Name (without extension)
   %fs : File Size (In Kilobytes)
+  %fv : "(vbr)" if variable bit rate or "" if constant bit rate
+  %d1 : First directory from end of file path.
+  %d2 : Second directory from end of file path.
+  %d2 : Third directory from end of file path.
+
+Example for the the %dN commands: If the path is "/Rock/Kent/Isola/11 -
+747.mp3", %d1 is "Isola", %d2 is "Kent"... You get the picture.
+
 Playlist/Song Info Tags:
   %pb : Progress Bar (Player ONLY)
         This will display a 1 character "cup" that empties as the song goes
         forward.
   %pp : Playlist Position
-  %pe : Playlist Total Entries
+  %pe : Total Number of Playlist Entries
   %pc : Current Time In Song
   %pr : Remaining Time In Song
   %pt : Total Track Time
+
+Conditional Tags (If/Else block):
+  %?xx<|> : Conditional: if the tag specified by "xx" has a value, the 
+            text between the "<" and the "|" is displayed, else the text
+            between the "|" and the ">" is displayed. 
+            The else part is optional, so the "|" does not have to be
+            specified if no else part is desired. The conditionals nest, 
+            so the text in the if and else part can contain all % 
+            commands, including conditionals.
+
 Other Tags:
-  %% : Displays a %
-  %s : Define the line to scroll
-       This MUST be the first tag in the line you want to scroll. It can
-       ONLY be used for one line. Currently, this feature only works in
-       the PLAYER.
-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 :-)
+  %%  : Display a '%'
+  %<  : Display a '<'
+  %|  : Display a '|'
+  %>  : Display a '>'
+  %s  : Indicate that the line should scroll. Can occur anywhere in 
+        a line (given that the text is displayed; see conditional 
+        below). Only the first line with a %s will actually scroll.
+        %s is ignored if combined with %pb, %pc or %pr on the same
+        line (the result wouldn't be good anyway).
 
+Example wps.config
+------------------
+%s%?in<%in - >%?it<%it|%fn> %?ia<[%ia%?id<, %id>]>
+%pb%pc/%pt
 
-Example wps.config File (Without If/Else)
------------------------
-%s%pp/%pe: %fc * %fsKB
-%pc/%pt
-
-
-Example Output
---------------
-ID3 Title:              None
-ID3 Artist:             None
-Playlist Position:      5
-Playlist Total Entries: 10
-Filename:               My Song.mp3
-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                 |
- ---------------------------
-Of course, the whole first line wouldn't fit, so it scrolls it.
+That is, "tracknum - title [artist, album]", where most fields are only
+displayed if available. Could also be rendered as "filename" or
+"tracknum - title [artist]".