SVG images have a dual purpose, providing an accurate representation of the
tablets and also providing the size and location of the various controls on
the device that can be queried by various applications that may need it.

To allow applications to identify each control in the SVG and also apply a
CSS if desired, the following naming convention applies:

* Buttons

Each button ID in the SVG is built of the string "Button" with ID of the
button between 'A' and 'Z':

    id="ButtonA"
    id="ButtonB"
    ...
    id="ButtonZ"

The SVG class must contain the button ID of the button between 'A' and 'Z'
and the more generic class "Button"

    class="A Button"
    class="B Button"
    ...
    class="Z Button"

If the button is a mode-switch button as well, the class list should also
contain "ModeSwitch":

    class="I ModeSwitch Button"

This would allow to modify the appearance of all the buttons at once via a CSS,
yet allowing to customize the appearance of single buttons by using the button
ID.

* Touch Rings/Strips

Touch rings use the following convention:

 - First touch ring:

    id="Ring"
    class="Ring TouchRing"

 - Second touch ring:

    id="Ring2"
    class="Ring2 TouchRing"

 - First touch strip:

    id="Strip"
    class="Strip TouchStrip"

 - Second touch strip:

    id="Strip2"
    class="Strip2 TouchStrip"

Note: Additional "fake" buttons (ie actual controls not found on the real
device) can be added to touch controls to help showing the type of action
expected on the control, like for example circular motion on a touch ring
or vertical motion on a touch strip.

These controls can be named:

 - First touch ring, rotating clockwise:

    id="RingCW"
    class="RingCW Button"

 - First touch ring, rotating counter clockwise:

    id="RingCCW"
    class="RingCCW Button"

 - Second touch ring, rotating clockwise:

    id="Ring2CW"
    class="Ring2CW Button"

 - Second touch ring, rotating counter clockwise:

    id="Ring2CCW"
    class="Ring2CCW Button"

 - First touch strip, moving up:

    id="StripUp"
    class="StripUp Button"

 - First touch strip, moving down:

    id="StripDown"
    class="StripDown Button"

 - Second touch strip, moving up:

    id="Strip2Up"
    class="Strip2Up Button"

 - Second touch strip, moving down:

    id="Strip2Down"
    class="Strip2Down Button"

The use of those "fake" buttons is left at the discretion of the designer
and is not mandatory nor enforced.

* Labels

The role of the labels in the SVG is to give applications an indication on
where to place the caption for each button. The actual content of the text
in the SVG image may not be relevant, what matters is the actual location.

Applications should hide the labels (using CSS) or replace the text with an
appropriate caption.

 - Button labels

Each button's label ID in the SVG is made of the string "Label" with ID of the
button to which it applies, between 'A' and 'Z'.

Class includes both the button ID and the string "Label".

    id="LabelA"
    class="A Label"

For the special case of mode-switch buttons, the class also list "ModeSwitch":

    id="LabelI"
    class="I ModeSwitch Label"

 - Touchring button labels

Touch-rings and touch-strips generate Up and Down events, therefore 2 different
labels are needed for each touch-ring/touch-strip control.

    id="LabelRingCCW"
    class="RingCCW Ring Label"

  and

    id="LabelRingCW"
    class="RingCW Ring Label"

The second touch-ring button is identified by "Ring2" in place of "Ring":

    id="LabelRing2CCW"
    class="Ring2CCW Ring2 Label"

  and

    id="LabelRingCW"
    class="Ring2CW Ring2 Label"

Touchstrips button follow the same naming scheme, using "Strip" and "Strip2"
to name the first and second touch-strip.

    id="LabelStripUp"
    class="StripUp Strip Label"

  and

    id="LabelStripDown"
    class="StripDown Strip Label"

Second touch-strip:

    id="LabelStrip2Up"
    class="Strip2Up Strip2 Label"

  and

    id="LabelRingCW"
    class="Strip2Down Strip2 Label"

 - Caption leader lines

To match the buttons with their corresponding labels, the SVG must also
provide a leader line for each label in the form of a line that links
each button and its label.

Each leader line follows the same naming convention as the labels, using
the special name "Leader" in place of "Label", ie:

    id="LeaderA"
    class="A Leader"

Touch-rings and touch-strips have 2 different labels and therefore 2 leader
lines.

    id="LeaderRingCCW"
    class="RingCCW Ring Leader"

  and

    id="LeaderRingCW"
    class="RingCW Ring Leader"

The second touch-ring button is identified by "Ring2" in place of "Ring":

    id="LeaderRing2CCW"
    class="Ring2CCW Ring2 Leader"

  and

    id="LeaderRingCW"
    class="Ring2CW Ring2 Leader"

Touchstrips button follow the same naming scheme, using "Strip" and "Strip2"
to name the first and second touch-strip.

    id="LeaderStripUp"
    class="StripUp Strip Leader"

  and

    id="LeaderStripDown"
    class="StripDown Strip Leader"

Second touch-strip:

    id="LeaderStrip2Up"
    class="Strip2Up Strip2 Leader"

  and

    id="LeaderStrip2Down"
    class="Strip2Down Strip2 Leader"

* Tips For Creating New Layouts

Layouts use very simple SVG rules. WISIWYG editors such as Inkscape are
very convenient to design new layouts but usually produce a much more
complex SVG markup so files that are produced with those editors should
be cleaned. To help with this task, there is a script called clean_svg.py
in the tools folder.
Besides cleaning the markup and removing editor specific tags, clean_svg.py
also automates the naming of the elements.

  * Automatic Naming with Inkscape and clean_svg.py

  On Inkscape, be sure to group the button, leader and label elements
  and assign the group's ID to the desired logical name. E.g.: Assigning
  "A" to the group's ID and running the clean_svg.py script with that
  SVG, will assign "ButtonA"/"B Button" to the ID and class of the first
  rect/circle element found in the group; it also analogously assigns the ID and class of the first path and text elements found in that group.

clean_svg.py needs two arguments, the SVG file path and the name of
the tablet, e.g.:

  ./clean_svg.py /path/to/svg_file.svg "My Brand New Tablet Name"
