`, where the last part can be omitted here as it defaults
+to `replace` what is the one we need for icon packs.
+
+### replace one icon by another
+
+Now assume we want to replace the save icon because a floppy-disk is really nothing people today know and might wonder what this strange quadratic thing should actually
+mean to them and today a downwards arrow is more common (even though for demonstration purpose our icon looks quite ugly so it is easily spotted as being replaced).
+
+1. We first need to know the bundle that provides this what in this case is the `org.eclipse.ui` so our pattern for matching this bundle would be `org\.eclipse\.ui`,
+what would only match this single bundle. If an icon has to be replaced in multiple bundles we can either use a less narrow pattern or use two different rules.
+2. Then one needs to find the icon to replace in this case it is `icons/full/etool16/save_edit.png`, as before we could use an exact match or we can use a more
+generic form to possibly match multiple path. In the example we use `icons/.*/save_edit.png`, please note that you even can replace a gif file by a png or whatever
+fileformat fits your needs. The code will still see the old name so this might still be used with care if the caller maybe make decisions based on the extension!
+3. Of course we need our replacement resource that will be used and we put it in as the last instruction as we are using the default replace tranformer that just keeps
+the provided resource as a replacement for the original.
+
+The full line then looks like this:
+
+```
+org\.eclipse\.ui,icons/.*/save_edit.png,/myicons/saveme.png
+```
+
+### replace multiple icons
+
+A transformer rules file can contain as many lines as you want and you can replace also icons from as many bundles as you like in the same icon pack.
+
+## Running the example
+
+If you want to run the example, make sure that you add the following to your run configuration (or extend an existing configuration):
+
+```
+-Dosgi.framework.extensions=org.eclipse.equinox.transforms.hook
+```
+
+this enables the equinox transforms hook extension also make sure that at least version `1.4.200` is used as it includes the required enhancements
+used in this example.
+
+Also make sure the example is included in the launch e.g. add it to an existing feature of your product / launch configuration.
+
+If everything worked well, you should see your new save icon in the toolbar like this:
+
+
+
+## Future enhancements
+
+This example is currently only a very bare example, everyone is encouraged to help enhancing it and sharing ideas how this can be made more comfortable,
+also there is currently no tooling around this so any help is appreciated.
+
+Here is an (incomplete) list of things that might be useful in future versions:
+
+1. supporting capture groups in a transform instruction to match a large amount of icon with one line and also support `@2x` variants more easily (currently it requires a duplicate line)
+2. having a way to exactly match a bundle without the need to escape special chars like `.` and supporting simple ant style glob pattern
+3. some tooling that allows to select a bundle and generate a list of icon replacements automatically
+4. support systemproperty or variable placeholders to support for example a theming system
+5. ...
\ No newline at end of file
diff --git a/examples/org.eclipse.ui.examples.iconpack/about.html b/examples/org.eclipse.ui.examples.iconpack/about.html
new file mode 100644
index 00000000000..164f781a8fd
--- /dev/null
+++ b/examples/org.eclipse.ui.examples.iconpack/about.html
@@ -0,0 +1,36 @@
+
+
+
+
+About
+
+
+ About This Content
+
+ November 30, 2017
+ License
+
+
+ The Eclipse Foundation makes available all content in this plug-in
+ ("Content"). Unless otherwise indicated below, the Content
+ is provided to you under the terms and conditions of the Eclipse
+ Public License Version 2.0 ("EPL"). A copy of the EPL is
+ available at http://www.eclipse.org/legal/epl-2.0.
+ For purposes of the EPL, "Program" will mean the Content.
+
+
+
+ If you did not receive this Content directly from the Eclipse
+ Foundation, the Content is being redistributed by another party
+ ("Redistributor") and different terms and conditions may
+ apply to your use of any object code in the Content. Check the
+ Redistributor's license that was provided with the Content. If no such
+ license exists, contact the Redistributor. Unless otherwise indicated
+ below, the terms and conditions of the EPL still apply to any source
+ code in the Content and such source code may be obtained at http://www.eclipse.org.
+
+
+
+
\ No newline at end of file
diff --git a/examples/org.eclipse.ui.examples.iconpack/build.properties b/examples/org.eclipse.ui.examples.iconpack/build.properties
new file mode 100644
index 00000000000..10a6e4470b9
--- /dev/null
+++ b/examples/org.eclipse.ui.examples.iconpack/build.properties
@@ -0,0 +1,6 @@
+bin.includes = META-INF/,\
+ myicons/,\
+ about.html,\
+ transform.txt
+
+src.includes = about.html
\ No newline at end of file
diff --git a/examples/org.eclipse.ui.examples.iconpack/forceQualifierUpdate.txt b/examples/org.eclipse.ui.examples.iconpack/forceQualifierUpdate.txt
new file mode 100644
index 00000000000..8ad7a91157b
--- /dev/null
+++ b/examples/org.eclipse.ui.examples.iconpack/forceQualifierUpdate.txt
@@ -0,0 +1 @@
+# To force a version qualifier update add the bug here
\ No newline at end of file
diff --git a/examples/org.eclipse.ui.examples.iconpack/myicons/saveme.png b/examples/org.eclipse.ui.examples.iconpack/myicons/saveme.png
new file mode 100644
index 00000000000..0f957d8a2e1
Binary files /dev/null and b/examples/org.eclipse.ui.examples.iconpack/myicons/saveme.png differ
diff --git a/examples/org.eclipse.ui.examples.iconpack/myicons/saveme@2x.png b/examples/org.eclipse.ui.examples.iconpack/myicons/saveme@2x.png
new file mode 100644
index 00000000000..93a325b47a8
Binary files /dev/null and b/examples/org.eclipse.ui.examples.iconpack/myicons/saveme@2x.png differ
diff --git a/examples/org.eclipse.ui.examples.iconpack/replaced_icon.png b/examples/org.eclipse.ui.examples.iconpack/replaced_icon.png
new file mode 100644
index 00000000000..fc7bd95c030
Binary files /dev/null and b/examples/org.eclipse.ui.examples.iconpack/replaced_icon.png differ
diff --git a/examples/org.eclipse.ui.examples.iconpack/transform.txt b/examples/org.eclipse.ui.examples.iconpack/transform.txt
new file mode 100644
index 00000000000..2008dd8491c
--- /dev/null
+++ b/examples/org.eclipse.ui.examples.iconpack/transform.txt
@@ -0,0 +1,4 @@
+org\.eclipse\.ui,icons/.*/save_edit.png,/myicons/saveme.png
+org\.eclipse\.ui,icons/.*/save_edit@2x.png,/myicons/saveme@2x.png
+
+