Add documentation for new `dotspacemacs-default-variable`

README.md

@@ -362,13 +362,18 @@ the quick start guide [here](#configuration).
 Install the default font supported by Spacemacs or choose a fixed witdh font.
 More information in the [font section][] of the documentation.
 
-4. **Why the powerline has no arrows in terminal even with a patched font ?**
+4. **The powerline separators are ugly, how can I fix them ?**
+Use the property `:powerline-offset` of the variable
+`dotspacemacs-default-font`. More information in the [font section][]
+of the documentation.
+
+5. **Why the powerline has no arrows in terminal even with a patched font ?**
 Emacs powerline implementation does not use patched fonts. There exist currently
 no mode-lines in Emacs that support patched font.
 The corresponding feature request for the powerline can be found
 [here][pw-patched-fonts].
 
-5. **The powerline separators have no anti-aliasing, what can I do ?**
+6. **The powerline separators have no anti-aliasing, what can I do ?**
 Emacs powerline uses XMP images to draw the separators. Enabling anti-aliasing
 may not be a trivial task so unfortunately you'll have to live with it.
 Nevertheless it exists a [large number of different separators][powerline-seps]

doc/DOCUMENTATION.md

@@ -838,16 +838,31 @@ display ASCII characters instead (may be useful in terminal).
 The default font used by `Spacemacs` is [source code pro][] by Adobe. It is
 recommended to install it on your system.
 
-Basic font support is provided in `Spacemacs`, you can change the font and
-its size using the function `spacemacs/set-font` in the `dotspacemacs/config`
-function of your `~/.spacemacs`.
+To change the default font set the variable `dotspacemacs-default-font` in
+your `.spacemacs` file.
+
+By default its value is:
 
 ```elisp
-(defun dotspacemacs/config ()
-  (spacemacs/set-font "DejaVu Sans Mono" 10)
-)
+(setq-default dotspacemacs-default-font '("Source Code Pro"
+                                          :size 13
+                                          :weight normal
+                                          :width normal
+                                          :powerline-offset 2))
 ```
 
+The properties should be pretty straightforward, it is possible to set any
+valid property of a [font-spec][].
+
+The special property `:powerline-offset` is for quick tweaking of the
+mode-line height in order to avoid crappy rendering of the separators like on
+the following screenshot (in this extreme case bump the offset to `+8` or more
+but most of the time `2` or `4` is alright).
+
+_Ugly separators_
+
+![ugly-separators](img/crappy-powerline-separators.png)
+
 # Commands
 
 Every sequences must be performed in `normal` mode.
@@ -2034,6 +2049,7 @@ developers to elisp hackers!
 [golden-ratio]: https://github.com/roman/golden-ratio.el
 [solarized-theme]: https://github.com/bbatsov/solarized-emacs
 [powerline]: https://github.com/milkypostman/powerline
+[font-spec]: http://www.gnu.org/software/emacs/manual/html_node/elisp/Low_002dLevel-Font.html
 [diminish]: http://www.emacswiki.org/emacs/DiminishedModes
 [auto-complete]: https://github.com/auto-complete
 [auto-highlight]: https://github.com/emacsmirror/auto-highlight-symbol