Merge branch 'mirage2-contribution' of https://github.com/atmire/DSpace into mirage2-contribution

dspace-xmlui-mirage2/readme.md

@@ -70,7 +70,7 @@ Afterwards the command `grunt --version` should show the grunt-cli version numbe
 
 ### Ruby ###
 
-For the same reasons as with Node, we’d advise using ruby via [RVM](http://rvm.io/)  (Ruby Version Manager). Even on OS X, which comes with a version of ruby preinstalled, you can save yourself a lot of hassle by using RVM instead. (In most cases there is no need to uninstall the system ruby first). Note that `*you need sudo rights to perform the RVM installation`*. You won't need sudo again to use RVM, ruby or gem later on
+For the same reasons as with Node, we’d advise using ruby via [RVM](http://rvm.io/)  (Ruby Version Manager). Even on OS X, which comes with a version of ruby preinstalled, you can save yourself a lot of hassle by using RVM instead. (In most cases there is no need to uninstall the system ruby first). Note that `you need sudo rights to perform the RVM installation`. You won't need sudo again to use RVM, ruby or gem later on
 
 
 ### Note: ###
@@ -165,9 +165,7 @@ Then you can install compass:
 
 Afterwards the command `compass` should show a help message.
 
-# The Theme #
-
-Unpack the theme to your `src/dspace/modules/xmlui/src/main/webapp/themes` folder.
+# Enabling the theme #
 
 Add the following to the `<themes>` section of  `src/dspace/config/xmlui.xconf`, replacing the currently active theme.
 
@@ -181,8 +179,14 @@ Furthermore uncomment the Mirage2 aspect to get the messages.
     <aspect name="Mirage2" path="resource://aspects/Mirage2/" /> 
 ```
 
+Now, if you run `mvn package -Dmirage2.on=true` in the dspace project root, bower will download all Mirage 2 dependencies, and grunt will trigger a number of plugins to preprocess, concatenate and minify all the theme's resources. 
 
-Now, if you run `mvn package` in the dspace project root, bower will download all Mirage 2 dependencies, and grunt will trigger a number of plugins to preprocess, concatenate and minify all the theme's resources. 
+
+# Customizing the theme #
+
+To create your own, customized version of Mirage 2, you can't do so in `src/dspace/modules/xmlui/src/main/webapp/themes`. Because of its build process, Mirage 2 works a little different. There is a separate module called `xmlui-mirage2` in `src/dspace/modules/`. Any theme you put in that module will be considered a Mirage 2 based theme, and its theme folder only needs to contain the files that differ from the vanilla Mirage 2.
+
+To get you started the module already contains a Mirage 2 folder containing nothing but the `_styles.scss` file. You can copy other files you want to modify to that folder as you go.
 
 # Production and development builds #
 
@@ -190,7 +194,7 @@ You can use maven profiles to have grunt build the theme in production or develo
 
 In production mode, grunt will concatenate and minify all javascript files referenced in the `Mirage2/scripts.xml` file (for more details see the javascript section of this document) in to a single `theme.js` file, to improve the performance of the theme. In development mode all javascript files will be separate and untouched, to make debugging easier.
 
-Similarly for CSS, compass will compile the CSS either using `Mirage2/config-dev.rb` or `Mirage2/config-prod.rb`. Both will yield a single css file: main.css, but the dev version won't be minified and will contain the scss file name and line number as a comment above each CSS rule.
+Similarly for CSS, compass will compile the CSS either using `Mirage2/config-dev.rb` or `Mirage2/config-prod.rb`. Both will yield a single css file: `main.css`, but the dev version won't be minified and will contain the scss file name and line number as a comment above each CSS rule.
 
 By default grunt will build the javascript and CSS in production mode. Use the `mirage2_dev` maven profile, or run grunt with the `dev` task to build the theme in development mode.
 
@@ -212,7 +216,7 @@ When working with a DRI that has been changed by the preprocess XSLs, it is ofte
 
 Mirage 2 contains two color schemes to choose from. The classic Mirage color scheme or the standard Bootstrap color scheme. By default grunt will build CSS to get the classic Mirage color scheme. However, by activating the `mirage2_bootstrap_color_scheme` maven profile, this can be changed to get the standard Bootstrap color scheme. 
 
-The stylesheets are written in [SASS](http://sass-lang.com/). You can find them in the folder `Mirage2/styles`. Each color scheme has its own subfolder, and a `_main.scss`  file that imports all others. These files will import the Compass library first. Next, all Bootstrap scss files and finally the DSpace specific files. Both color schemes also import the file `_style.scss`. It is empty by default, and is meant to add your own style. Note that CSS is also valid SCSS, so if you don't want to learn SASS, just add plain old CSS to that file and it will work just fine.   
+The stylesheets are written in [SASS](http://sass-lang.com/). You can find them in the folder `Mirage2/styles`. Each color scheme has its own subfolder, and a `_main.scss`  file that imports all others. These files will import the Compass library first. Next, all Bootstrap scss files and finally the DSpace specific files. Both color schemes also import the file `_style.scss`. It contains some example SCSS by default, and is meant to add your own style. Note that CSS is also valid SCSS, so if you don't want to learn SASS, just add plain old CSS to that file and it will work just fine.   
 
 The goal of the standard Bootstrap color scheme was to add as little extra style on top of Bootstrap as possible and instead force ourselves to solve most issues in XSL; by creating the right HTML structure and adding the right bootstrap CSS classes. But try as we might, a few additional style rules were still needed. Those can be found in `shared/_dspace-bootstrap-tweaks.scss`, most of it is limited to styles to improve the sidebar behavior on mobile devices.
 
@@ -222,13 +226,13 @@ Take a look at [bootstrap's own variables file](https://github.com/twbs/bootstra
 
 If you want to base your theme on an existing Bootstrap theme (like the ones at [bootswatch.com](http://bootswatch.com)) you can do so by using the standard Bootstrap color scheme and replacing the import of Bootstrap in `bootstrap_color_scheme/_main.scss`:
 
-```scss
+```less
     @import "../vendor/bootstrap-sass-official/vendor/assets/stylesheets/bootstrap";
 ```
 
 with an import of just its `_variables.sccs` file (those variables need to be defined, because they are used in `_dspace-bootstrap-tweaks.scss`):
 
-```scss
+```less
     @import "../vendor/bootstrap-sass-official/vendor/assets/stylesheets/bootstrap/_variables";
 ```
 
@@ -255,3 +259,19 @@ The theme also comes with built in support for [CoffeeScript](http://coffeescrip
 Mirage 2’s dependencies are specified in the file `Mirage2/bower.json`. Dependencies in this file should be specified according to the rules in the [Bower documentation](http://bower.io/|). Note that Bower only downloads the dependencies, nothing more. So if you add other dependencies, you'll still have to reference them. That means if it’s a CSS file, import it in `Mirage2/styles/_style.scss`, if it's a javascript file, add it to `Mirage2/scripts.xml`.
 
 We've used the the `latest` keyword to specify dependency versions in `bower.json` wherever possible because that ensures you're starting with up to date versions when creating a new theme. However once your theme is going in to production, we strongly recommend replacing `latest` with the actual version numbers being used at that moment. That way your production build won't break when a version of a dependency is released that isn't backwards compatible.
+
+# Multiple themes #
+
+Any folder you create in `src/dspace/modules/xmlui-mirage2/src/main/webapp/themes` will be interpreted as a Mirage2 based theme. This means that if I create two folders called 'Red' and 'Green' in that directory, and create the file `styles/_style.scss` in both folders with the contents 
+```css
+body {
+  background-color: red;
+}
+```
+and
+```css
+body {
+  background-color: green;
+}
+```
+respectively and run `mvn package -Dmirage2.on=true`, two themes will be created called 'Red' and 'Green', with the only difference being the background color of `<body>`