Guide to writing Rockbox Skins
------------------------------

1 Introduction
----------------
    Rockbox has an ever-evolving themeing engine which allows you to
    theme most of the major screens. Blaa blaa

1 The basics
--------------

    Rockbox skins are simple text files a different extension depending
    on which type of skin the file should be loaded to (i.e *.wps* for the
    WPS, *.sbs* for the main menus and browsers, etc).

    For the sake of simplicity all explanations assume we are talking about
    the WPS, but just about all tags work equally well in any screen (with
    some obvious exceptions.)

1.1 Tags
----------

    The entire system is built around the idea of *tags*. Tags in skins
    are a % followed by one or more letters (case sensitive) which are used
    as placeholders for actual data (usually text being displayed).

    For example::
        %ia - %it
    Will display the current track's artist (%ia) a - and the current tracks
    title (%it).

    Tags can also have parameters (%xd(foo, 1) ) which are simply comma
    seperated (with spaces between items being optional, however *strongly*
    recommended for readability.)

    Finally, some characters are special (i.e %) so they need to be 'escaped'
    to display. %% will display % on the screen.

    Any other text which the parser doesn't recognise as tags will siply be
    displayed on the screen as static text.

1.2 Lines
-----------

    Each line in the skin file is equivilant to a line on the display.
    A *very* limited set of tags will break this behaviour by forcing the
    next line to show up on the current line, but this can be mostly ignored.

    Lines can also swap between various sets of tags (or text) using *sublines*.

    Sublines are simply sets of tags seperated by a semi-colon (;).
    Each subline will be displayed for 2 seconds unless the *timeout* tag
    is used to change that value. (%t(timeout)).

    Lines by default are static. If the line doesn't fit in the display
    it will not scroll unless the %s tag is used to tell it to scroll.

1.2.1 Text alignment
--------------------

    Text is always drawn from the left of the display however tags are provided
    to position the text on the left, middle or right of the display.

    %al

1.3 Conditionals
------------------

    Most tags can have more than one value. %ia (current track artist)
    comes from the file which may not have that value set. When that happens
    %ia will show nothing, so you could end up with a line like::
        01 - - Some song!
    To only display a tag if the tag has a value we use conditionals.
    Conditionals are in the form::
        %?xx<values>
    where xx is the tag name and values is a pipe (|) seperated list of
    lines (possibly including sublines) to display depending on the value
    of the tag. For text tags the "value" is either "has text" or "no text/blank".
    Examples::
        %?ia<%ia>
    Will only display the track artist if it is avialable.

        %?ia<%ia|No artist>
    Will display "No artist" if it isnt available.

        %?mm<Off|All|One|Shuffle|A-B>
    Will show the text representation for each of the repeat modes.

    This syntax can be difficult to read when the number of options is
    more than a few so the *%if()* tag is an alternative::
        %?if(%mm, >=, 1)<Repeat enabled>
    will display "Repeat enabled" if any repeat mode is enabled.

    Conditionals can of course be nested::
        %?ia<%?it<%ia - %it|%ia>|%fm;%fb>
    Will display "Artist - Title" of both are present, or just Artist if
    artist is present but title isnt. If neither are present the line will
    alternate between the filename and the files bitrate.

2.0 Viewports
-------------

    Normally the skin will cover the entire display and each line in the
    file represents the equivilant line in the display. Using viewports
    allows you to position the text lines anywhere on the screen.

    By default every skin has an initial viewport which covers the full
    screen and uses the font specified in the settings. This viewport will
    not draw anything if any other viewports are specified.

2.1 Declaring Viewports
-----------------------

    ::
        %V(x, y, width, height, font id)

    Where:
        *x* is the x pixel of the rectangle to draw in.
        *y* is the y pixel of the rectangle to draw in.
        *width* is the width of the rectangle.
        *height* is the height of the rectangle.
        *font id* is the font number to use for the viepworts text (1 means UI font).

    For example::
        %V(0, 100, 50, 50, 1)
    will create a viewport with the top left corner at (0,100) and bottom
    right corner at (50, 150).

    Once a viewport is declared all lines following it (untill the next viewport)
    will be drawn in this rectangle.

2.2 Conditional Viewports
-------------------------

    You may want to display