Update HACKING.md

HACKING.md

@@ -4,33 +4,38 @@ Summary

                                
                                
                                
                            
                                
                                    
                                        
                                            4  
                                            * Do not edit the CSS directly, edit the source SCSS files and process them with SASS (run 
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            5  
                                              `./parse-sass.sh` when you have the required software installed, as described below)
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            6  
                                            * To be able to use the latest/adequate version of sass, install ruby, gem, sass & bundle.
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        7 -
                                          On Fedora F20, this is done with `sudo dnf install rubygems && gem install bundle && bundle install`
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        8 -
                                          from the same directory this HACKING resides in.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        7 +
                                          On Fedora 25, this is done with `sudo dnf install rubygems && gem install bundle && bundle install`
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        8 +
                                          from the same directory this `HACKING.md` resides in.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            9  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            10  
                                            How to tweak the theme
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            11  
                                            ----------------------
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            12  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        13 -
                                        Adwaita is a complex theme, so to keep it maintainable it's written and processed in SASS. The
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        14 -
                                        generated CSS is then transformed into a gresource file during gtk build and used at runtime in a 
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        15 -
                                        non-legible or editable form.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        13 +
                                        Flat-Plat is a complex theme, so to keep it maintainable it's written and processed in SASS.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            14  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        17 -
                                        It is very likely your change will happen in the _common.scss file. That's where all the widget 
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        15 +
                                        It is very likely your change will happen in the `_common.scss` file. That's where all the widget 
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            16  
                                            selectors are defined. Here's a rundown of the "supporting" stylesheets, that are unlikely to be the 
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            17  
                                            right place for a drive by stylesheet fix:
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            18  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        21 -
                                        _colors.scss        - global color definitions. We keep the number of defined colors to a necessary minimum, 
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        22 -
                                                              most colors are derived form a handful of basics. It covers both the light variant and
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        23 -
                                                              the dark variant.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        19 +
                                        * `_colors.scss`
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            20  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        25 -
                                        _colors-public.scss - SCSS colors exported through gtk to allow for 3rd party apps color mixing.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        21 +
                                          global color definitions. We keep the number of defined colors to a necessary minimum, 
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        22 +
                                          most colors are derived form a handful of basics. It covers both the light variant and
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        23 +
                                          the dark variant.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            24  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        27 -
                                        _drawing.scss       - drawing helper mixings/functions to allow easier definition of widget drawing under
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        28 -
                                                              specific context. This is why Adwaita isn't 15000 LOC.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        25 +
                                        * `_colors-public.scss`
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        26 +
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        27 +
                                          SCSS colors exported through gtk to allow for 3rd party apps color mixing.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        28 +
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        29 +
                                        * `_drawing.scss`
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        30 +
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        31 +
                                          drawing helper mixings/functions to allow easier definition of widget drawing under
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        32 +
                                          specific context. This is why Flat-Plat isn't 15000 LOC.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        33 +
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        34 +
                                        * `_common.scss`
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        35 +
                                        
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        36 +
                                          actual definitions of style for each widget. This is where you are likely to add/remove your changes.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            37  
                                            
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        30 -
                                        _common.scss        - actual definitions of style for each widget. This is where you are likely to add/remove
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        31 -
                                                              your changes.
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        32 -
                                                              
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            38  
                                            You can read about SASS at http://sass-lang.com/documentation/. Once you make your changes to the
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        34 -
                                        _common.scss file, you can either run the ./parse-sass.sh script or keep SASS watching for changes as you
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        39 +
                                        `_common.scss` file, you can either run the `./parse-sass.sh` script or keep SASS watching for changes as you
                                        
                                        
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            40  
                                            edit. This is done by running `bundle exec sass --watch --sourcemap=none .` If sass is out of date, or is
                                        
                                        
                                            
                                            
                                            
                                            
                                        
                                    
                                
                                
                                
                            
                                
                                    
                                        
                                            41  
                                            missing, you can install it with `bundle install`.