Replace some emacs-user-directory vars and update documentation

README.md

@@ -45,7 +45,9 @@
         - [Windows](#windows)
 - [Install](#install)
     - [Default installation](#default-installation)
-    - [Installation alongside another configuration](#installation-alongside-another-configuration)
+    - [Alternate installations](#alternate-installations)
+        - [Modify HOME environment variable](#modify-home-environment-variable)
+        - [Modify spacemacs-start-directory variable](#modify-spacemacs-start-directory-variable)
     - [Spacemacs logo](#spacemacs-logo)
 - [Update](#update)
     - [Automatic update (on master branch)](#automatic-update-on-master-branch)
@@ -220,17 +222,23 @@ For efficient searches we recommend to install `pt` ([the platinum searcher][]).
    Or you can set the `dotspacemacs-elpa-https` to `nil` in your dotfile to
    remove the need to start Emacs with `--insecure` argument. You may wish to
    clear out your `.emacs.d/elpa` directory before doing this, so that any
-   corrupted packages you may have downloaded will be reinstalled.
+   corrupted packages you may have downloaded will be re-installed.
 
 4. Restart Emacs to complete the installation.
 
 If the mode-line turns red then be sure to consult the [FAQ][FAQ.org].
 
-## Installation alongside another configuration
+## Alternate installations
 
-To try out Spacemacs (or any other Emacs configuration you desire) without
-having to go through the trouble of backing up you `~/.emacs.d` directory and
-then cloning the new configuration:
+It may be useful to clone Spacemacs outside Emacs dotdirectory `~/.emacs.d` so
+you can try Spacemacs without replacing completely our own configuration.
+There is currently two possibilities to support alternative location for
+Spacemacs configuration.
+
+### Modify HOME environment variable
+
+This solution is ideal to quickly try Spacemacs without compromising your
+existing configuration.
 
 ```sh
 mkdir ~/spacemacs
@@ -241,6 +249,17 @@ HOME=~/spacemacs emacs
 Note: If you're on Fish shell, you will need to modify the last command to: `env
 HOME=$HOME/spacemacs emacs`
 
+### Modify spacemacs-start-directory variable
+
+This solution is better suited to "embed" Spacemacs into your own configuration.
+Say you cloned Spacemacs in `~/.emacs.d/spacemacs/` then drop these lines in
+`~/.emacs.d/init.el`:
+
+```elisp
+(setq spacemacs-start-directory "~/.emacs.d/spacemacs/")
+(load-file (concat spacemacs-start-directory "init.el"))
+```
+
 ## Spacemacs logo
 
 If you are using Ubuntu and Unity then you can add the Spacemacs logo by

core/aprilfool/zemacs.el

@@ -31,7 +31,7 @@
     (ad-disable-advice 'spacemacs-buffer/insert-banner-and-buttons
                        'after 'zemacs/insert-banner-and-buttons)
     (ad-activate 'spacemacs-buffer/insert-banner-and-buttons)
-    (load-file (concat user-emacs-directory "core/core-spacemacs-buffer.el"))
+    (load-file (concat spacemacs-start-directory "core/core-spacemacs-buffer.el"))
     (setq dotspacemacs-startup-banner 'official)
     (kill-buffer)
     (insert "

core/core-documentation.el

@@ -150,7 +150,7 @@ the `spacemacs//org-heading-annotate-custom-id' function."
              (error (format "Can't find #+TITLE: in %s"
                             (buffer-file-name))))
            (insert (concat head-css-extra-readtheorg-head
-                           (f-relative user-emacs-directory
+                           (f-relative spacemacs-start-directory
                                        (file-name-directory filename))
                            head-css-extra-readtheorg-tail)))))
 

init.el

@@ -17,12 +17,12 @@
 
 (defconst spacemacs-version         "0.105.21" "Spacemacs version.")
 (defconst spacemacs-emacs-min-version   "24.4" "Minimal version of Emacs.")
+(defconst spacemacs-start-directory user-emacs-directory)
 
 (if (not (version<= spacemacs-emacs-min-version emacs-version))
     (message (concat "Your version of Emacs (%s) is too old. "
                      "Spacemacs requires Emacs version %s or above.")
              emacs-version spacemacs-emacs-min-version)
-  (defvar spacemacs-start-directory user-emacs-directory)
   (load-file (concat spacemacs-start-directory "core/core-load-paths.el"))
   (require 'core-spacemacs)
   (spacemacs/init)

layers/+spacemacs/spacemacs-org/local/space-doc/space-doc.el

@@ -347,7 +347,7 @@ Open all other links with `browse-url'."
          (concat "\\/\\/github\\.com\\/syl20bnr\\/spacemacs\\/blob"
                  "\\/[^/]+\\/\\(.*\\.org\\)\\(\\#.*\\)?")))
     (if (string-match git-url-root-regexp path)
-        (spacemacs/view-org-file (concat user-emacs-directory
+        (spacemacs/view-org-file (concat spacemacs-start-directory
                                          (match-string 1 path))
                                  (or (match-string 2 path)
                                      "^")