diff --git a/README.md b/README.md index c860115fc8ab..3ddc49346d00 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ -[![Gitter](https://badges.gitter.im/Join Chat.svg)](https://gitter.im/syl20bnr/spacemacs?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [![Build Status](https://travis-ci.org/syl20bnr/spacemacs.svg)](https://travis-ci.org/syl20bnr/spacemacs) [![Buy A Drink](https://img.shields.io/badge/Paypal-Buy%20a%20Drink-blue.svg)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=ESFVNPKP4Y742)[![Twitter][]](http://www.twitter.com/spacemacs) +[![Gitter](https://badges.gitter.im/Join Chat.svg)](https://gitter.im/syl20bnr/spacemacs?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [![Build Status](https://travis-ci.org/syl20bnr/spacemacs.svg)](https://travis-ci.org/syl20bnr/spacemacs) [![Buy A Drink](https://img.shields.io/badge/Paypal-Buy%20a%20Drink-blue.svg)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=ESFVNPKP4Y742) [![Recommend Spacemacs](https://img.shields.io/badge/Slant-Recommend-ff69b4.svg)](http://www.slant.co/topics/12/~what-are-the-best-programming-text-editors)][![Twitter][]](http://www.twitter.com/spacemacs) ***

Spacemacs

@@ -30,11 +30,8 @@ - [Introduction](#introduction) - [Features](#features) - - [Batteries Included](#batteries-included) - - [Nice UI](#nice-ui) - - [Excellent ergonomics](#excellent-ergonomics) - - [Convenient and Mnemonic Key Bindings](#convenient-and-mnemonic-key-bindings) - - [Great [Documentation][DOCUMENTATION.org]](#great-documentationdocumentationorg) +- [Documentation](#documentation) +- [Getting Help](#getting-help) - [Prerequisites](#prerequisites) - [Emacs](#emacs) - [Linux distros](#linux-distros) @@ -43,141 +40,86 @@ - [Install](#install) - [Spacemacs logo](#spacemacs-logo) - [Update](#update) - - [Update notification](#update-notification) - - [Rollback](#rollback) -- [Configuration](#configuration) - - [Configuration layers](#configuration-layers) - - [Dotfile (.spacemacs)](#dotfile-spacemacs) - - [Dotdirectory (~/.spacemacs.d)](#dotdirectory-spacemacsd) -- [Learning Spacemacs](#learning-spacemacs) - - [Editing Styles](#editing-styles) - - [The leader keys](#the-leader-keys) - - [Evil-tutor](#evil-tutor) - - [Universal argument](#universal-argument) - - [Configuration layers and Package discovery](#configuration-layers-and-package-discovery) - - [Key bindings discovery](#key-bindings-discovery) - - [Describe functions](#describe-functions) -- [How-To's](#how-tos) + - [Automatic update](#automatic-update) + - [On develop branch](#on-develop-branch) - [Contributions](#contributions) - [License](#license) -- [Special Credits](#special-credits) - [Supporting Spacemacs](#supporting-spacemacs) -- [FAQ](#faq) - - [Common](#common) - - [Windows](#windows) - - [OS X](#os-x) # Introduction -_You are a Vim user ?_ +Spacemacs is a proposition of a complete new experience for Emacs focused +on ergonomics, mnemonics and consistency. -You do not need to know Emacs to use Spacemacs! +Clone it, launch it then press the space bar and let you guided by the built-in +interactive list of key-bindings. You can also press the `[?]` button on the +home buffer for the first essential key bindings to know. -_You are an Emacs user ?_ - -You do not need to know Vim to use Spacemacs! - -Since version 0.101.0 and later Spacemacs totally abolishes the frontiers -between Vim and Emacs. The user can now choose his/her preferred editing -style and enjoy all the Spacemacs features. - -Even better, it is possible to dynamically switch between the two -styles _seamlessly_ which makes it possible for programmers with different -styles to do seat pair programming using the _same_ editor. - -Since switching between the two styles is so simple, Spacemacs is the perfect -setup to learn the "other way" or even crazier, to get the best of both -worlds by developing your own hybrid style. - -Spacemacs is also a user-friendly and well-documented Emacs kit that -integrates the best Emacs packages out there. It uses [Evil Mode][] to combine -the ergonomic editing features of Vim and Emacs with the flexibility of a -lisp powered engine. - -If you are already an experienced Emacs user, you will appreciate the elegantly -customized system and carefully curated, tightly integrated, set of packages. +Spacemacs can be used by Emacs or Vim users flawlessly, it is even possible +to mix the two styles. You can switch between any style at any moment which +make it a very good tool for pair-programming. Spacemacs is currently in beta, and contributions are very welcome. # Features -## Batteries Included - -Spacemacs integrates hundreds of ready-to-use packages thanks to a -community-driven approach. - -Those packages are grouped in [layers][] and their configuration follow a set -of rules gathered in [CONVENTIONS.org][]. - -**[Visit the Documentation][DOCUMENTATION.org]** - -## Nice UI - -Spacemacs looks good. It ships with quality themes and a beautiful mode-line. - -![spacemacs_python](doc/img/spacemacs-python.png) - -## Excellent ergonomics +- **Great documentation:** Access documentation in Emacs with +SPC f e h +- **Beautiful GUI:** you'll love the distraction free UI and its functional +mode-line. +- **Excellent ergonomics:** all the key bindings are accessible by pressing +the space bar or alt-m. +- **Mnemonic key bindings:** commands have mnemonic prefixes like +SPC b for all the buffer commands or SPC p for the +project commands. +- **Batteries included:** discover hundreds of ready-to-use packages nicely +organised in configuration layers following a set of +[conventions][CONVENTIONS.org]. -Spacemacs is designed around the [Evil Mode][] and a leader key. All the -packages are customized to integrate seamlessly with Evil. +# Documentation -Spacemacs also define micro-states to group related commands. These -micro-states reduce the keystrokes needed to issue repetitive commands and -reduce the number of keyboard bindings to learn. +A comprehensive documentation is available for each layer by pressing +SPC f e h. -## Convenient and Mnemonic Key Bindings +To go to the general documentation [click here][DOCUMENTATION.org]. -`Spacemacs` organizes key bindings into mnemonic groups. For example, commands -to operate on the buffer are prefixed by ` b`, and commands to operate on -the project are under ` p`. +You can also check the [Quick Start guide][QUICK_START.org] and the +[FAQ][FAQ.org]. -### Great [Documentation][DOCUMENTATION.org] - -Most of Spacemacs' features, key bindings, and configuration options -are extensively documented. +# Getting Help If you need help, ask your question in the [Gitter Chat][] and a member of the community will help you out. -Tip: Run `SPC h d s` (it gathers info about your Spacemacs setup and copies to -your clipboard) and then paste into the Gitter chat so that others know the -basic info about your setup necessary to help diagnose any issues you may be -facing. - If you prefer IRC, connect to the [Gitter Chat IRC server][] and join the `#syl20bnr/spacemacs` channel. - # Prerequisites ## Emacs -`Spacemacs` is tested with Emacs 24.3 and 24.4 and therefore should boot -on all the major OSes where these versions are installable. +`Spacemacs` is operational with Emacs 24.3 but Emacs 24.4 and above are +recommended to enjoy the full experience. Some modes require third-party tools that you'll have to install via your favorite package manager. ### Linux distros -Install Emacs from the package manager of your favorite Linux distribution. +Install Emacs from the package manager of your Linux distribution. ### OS X -The recommended version for OS X is [emacs-mac-port][]. It can be installed -via [homebrew][] with the following commands: +We recommend the homebrew [emacs-mac-port][] formula: ```sh $ brew tap railwaycat/emacsmacport $ brew install emacs-mac --with-spacemacs-icon # OR, brew cask install emacs-mac ``` -(The `with-spacemacs-icon` option uses the official spacemacs logo for the app bundle.) -The default key handling is different from the official OS X port. To correct -this you can add the [osx layer][] to your [dotfile][] layer list: +It is also recommended to add the [osx layer][] to your [dotfile][]: ```elisp (setq-default dotspacemacs-configuration-layers '(osx)) @@ -192,9 +134,8 @@ Details can be found on the emacs-mac-port [README][emacs-mac-port-server]. Good quality builds can be found [on this page][emacs-for-windows]. It is recommended to install the most stable build. -Be sure to declare a environment variable named `HOME` and pointing to -your user directory `C:\Users\`. Then you can clone Spacemacs -in this directory. +Be sure to declare a environment variable named `HOME` pointing to your user +directory `C:\Users\`. Then you can clone Spacemacs in this directory. Sometimes you'll get the following error when you first start Emacs: @@ -215,44 +156,59 @@ For efficient searches we recommend to install `pt` ([the platinum searcher][]). # Install -1. If you have an existing Emacs configuration, back it up: +1. If you have an existing Emacs configuration, back it up first: ```sh cd ~ mv .emacs.d .emacs.bak ``` -2. Clone this repository _with its submodules_: +2. Clone the repository: ```sh git clone --recursive https://github.com/syl20bnr/spacemacs ~/.emacs.d ``` - `master` is the stable branch and is regularly updated. Switch to the `develop` - branch if you want to use the bleeding-edge version. +`master` is the stable branch and it is _immutable_, **DO NOT** make any +modification to it or you will break the update mechanism. If you want to +fork Spacemacs safely use the `develop` branch where you handle the update +manually. 3. Launch Emacs. Spacemacs will automatically install the packages it requires. 4. Restart Emacs to complete the installation. -If the mode-line turns red then be sure to visit the [troubleshooting][troubleshoot] -guide and consult the [FAQ](#faq). +If the mode-line turns red then be sure to visit the +[troubleshooting][troubleshoot] guide and consult the [FAQ](#faq). ## Spacemacs logo If you are using Ubuntu and Unity then you can add the Spacemacs logo by following the instructions [here][cpaulik-unity-icon]. -If you're on a mac and didn't install emacs with the spacemacs logo, you can apply -it to the app bundle after installation. An .icns version of the logo by [Nasser -Alshammari](http://www.nass3r.com) is [available from his github](https://github.com/nashamri/spacemacs-logo). -You can paste this into the app bundle to get the spacemacs logo on your emacs. -[More detailed instructions](http://www.idownloadblog.com/2014/07/16/how-to-change-app-icon-mac/) -if you've not done this before. +If you're on a mac follow [these instructions][icon-mac-instructions]. You can +find an .icns version of the logo by [Nasser Alshammari](http://www.nass3r.com) +in [his repository][icon-repository]. # Update -Spacemacs currently requires manual updates using the following procedure: +Spacemacs has a built-in notification of new version when you are on the +`master` branch. If you are on the `develop` branch then you'll have to +update Spacemacs manually by updating your repository. + +## Automatic update + +When a new version is available an little arrow appears in the mode-line. + +Its color depends on the number of versions available since your last update. +Green means that your current version is recent, orange and red that your +current version is older. + +[[file:doc/img/powerline-update.png]] + +Click on the arrow to update Spacemacs to the last version. + +## On develop branch 1. Update Emacs packages by clicking (press `RET`) on the `[Update]` link of the starting page. @@ -261,198 +217,17 @@ the starting page. ```sh git pull --rebase - git submodule sync; git submodule update ``` 3. Restart Emacs to complete the upgrade. -## Update notification - -For convenience an indicator is displayed in the mode-line whenever a new -version of `Spacemacs` is available. - - Symbol | Description -:------------------------------------:|---------------------------------- -![git-new](doc/img/update-green.png) | < 3 releases behind -![git-del](doc/img/update-orange.png) | < 5 releases behind -![git-mod](doc/img/update-red.png) | >= 5 releases behind - -**Note:** -A feature allowing update by merely clicking on the indicator will be implemented _soon_! - -## Rollback - -Should anything go wrong during an update, you can rollback ELPA packages to a -previous version. Click (press `RET`) on the `[Rollback]` link of the startup -page, choose a rollback slot. - -Rollback slot names are dates with the following format `YYYY-MM-DD_HH.MM.SS`. -The date corresponds to the date of an update. The most recent slots are -listed first. - -# Configuration - -`Spacemacs` divides its configuration into self-contained units called -[configuration layers][config]. These layers are stacked on top of each other -to achieve a custom configuration. - -By default `Spacemacs` uses the dotfile `~/.spacemacs` to control which layers -to load. Within this file you may also generally configure certain features. - -## Configuration layers - -A configuration layer is a directory containing at least the following files: - -- `packages.el`: Defines and configures packages to be downloaded from Emacs -package repositories using `package.el` -- `extensions.el`: Configures packages which cannot be downloaded with - `package.el` such as built-in Emacs features and git submodules. - -If you already have your own `Emacs` configuration you can move it to your -own layer. - -The following command creates a layer in the `private` directory: - - : configuration-layer/create-layer RET - -Any configuration layers you create must be explicitly loaded in `~/.spacemacs`. - -**Note:** For your privacy, the contents of the `private` directory are not -under source control. See the documentation for a discussion on how to -[manage your private configuration][manage_config]. - -## Dotfile (.spacemacs) - -As mentioned `.spacemacs` controls which configuration layers to load and -is also a means to customizing `Spacemacs`. - -The following command will create a `.spacemacs` file in your home directory: - - : dotspacemacs/install RET - -...to open the installed dotfile: - - f e d - -...to load some configuration layers using the variable -`dotspacemacs-configuration-layers`: - -```elisp -;; List of configuration layers to load. -dotspacemacs-configuration-layers '(auto-completion smex) -``` - -Some configuration layers support configuration variables to expose granular -control over layer-specific features, [git layer][] being one such example. -Variables can be directly set within `dotspacemacs-configuration-layers` like so: - -```elisp -;; List of configuration layers to load. -dotspacemacs-configuration-layers '(auto-completion - (git :variables - git-magit-status-fullscreen t) - smex) -``` - -At anytime you can apply the changes made to the dotfile or layers -_without restarting_ `Spacemacs` by pressing SPC f e R. - -The [comments in this file][dotfile template] contain further information about -how to customize `Spacemacs`. See the [dotfile configuration][dotfile] section of -the documentation for more details. - -## Dotdirectory (~/.spacemacs.d) - -Like `Emacs`, Spacemacs initialization can also be contained in an `init.el` file -in a special directory `~/.spacemacs.d`. The contents of the dotfile should be -then copied in the `init.el` file. - -# Learning Spacemacs - -## Editing Styles - -Spacemacs can be used by Vim users or Emacs users by setting the -`dotspacemacs-editing-style` variable to `'vim` or `'emacs` in the dotfile -`~/.spacemacs`. - -## The leader keys - -`Spacemacs` key bindings use a leader key which is by default bound to -SPC (space bar) in `vim` editing style and M-m in -`emacs` style. - -You can change it by setting the variable `dotspacemacs-leader-key` if -you use the `vim` style or `dotspacemacs-emacs-leader-key` if you use -the `emacs` style (these variables must be set in the file `~/.spacemacs`). - -For simplicity the documentation always refers to the leader key as -SPC. - -There is secondary leader key called the major-mode leader key which is -set to , by default. This key is a shortcut for SPC m -where all the major-mode specific commands are bound. - -## Evil-tutor - -If you are willing to learn the Vim key bindings (highly recommended since -you can benefit from them even in `emacs` style), press SPC h T -to begin an Evil-adapted Vimtutor. - -## Universal argument - -In `vim` editing style the universal argument defaults to ` u` -instead of `C-u` because the latter is used to scroll up as in Vim. - -## Configuration layers and Package discovery - -By using `helm-spacemacs` with SPC f e h you can quickly search -for a package and get the name of the layers using it. - -You can also easily go to the `README.org` of a layer or go to the initialization -function of a package. - -## Key bindings discovery - -Thanks to [which-key][], whenever a prefix command is pressed (like `SPC`) -a buffer appears after one second listing the possible keys for this prefix. - -It is also possible to search for specific key bindings by pressing: - - SPC ? - -To narrow the bindings list to those prefixed with `SPC`, -type a pattern like this regular expression: - - SPC\ b - -which would list all `buffer` related bindings. - -## Describe functions - -`Describe functions` are powerful Emacs introspection commands to get information -about functions, variables, modes etc. These commands are bound thusly: - -Key Binding | Description ---------------|------------------------------------------------------------------ -` h d f` | describe-function -` h d k` | describe-key -` h d m` | describe-mode -` h d v` | describe-variable - -# How-To's - -Some quick `how-to's` are compiled in the [HOWTOs.org][] file. - # Contributions -`Spacemacs` needs _you_! +`Spacemacs` is a community-driven project, it needs _you_ to keep it up to +date and propose useful and complete configuration! -We especially need to create more configuration layers that, for instance, bring -support for new languages. - -If you are ready to contribute please begin by consulting the -[contribution guidelines][CONTRIBUTE.org] and [conventions][CONVENTIONS.org], -thanks! +Before contributing be sure to consult the +[contribution guidelines][CONTRIBUTE.org] and [conventions][CONVENTIONS.org]. # License @@ -461,10 +236,10 @@ The license is GPLv3 for all parts specific to `Spacemacs`, this includes: - all the layer files. - the documentation -# Special Credits +For the packages shipped in this repository you can refer to the files header. -[Spacemacs logo][] by [Nasser Alshammari][] -released under a Creative Commons license. +[Spacemacs logo][] by [Nasser Alshammari][] released under a Creative Commons +license. # Supporting Spacemacs @@ -476,100 +251,26 @@ maintainer by clicking on the [Paypal badge](#top). Thank you ! -# FAQ - -## Common - -1. **Which version of Spacemacs am I running ?** -The version is displayed on the upper right corner of the loading screen. -You may also just type SPC f e v. - -2. **What is the official pronunciation of Spacemacs ?** -As it is written, that is _space_ then _macs_. - -3. **Why are packages installed with `package-install` automatically deleted by -Spacemacs when it boots ?** -To declare new packages you have to create a new configuration layer, see -the [quick start guide](#configuration). - -4. **The Spacemacs banner is ugly, what should I do ?** -Install the default font supported by Spacemacs or choose a fixed width font. -More information in the [font section][] of the documentation. - -5. **The powerline separators are ugly, how can I fix them ?** -Use the property `:powerline-scale` of the variable -`dotspacemacs-default-font`. See [font section][] documentation for more details. - -6. **The powerline separators have no anti-aliasing, what can I do ?** -Emacs powerline uses XMP images to draw the separators in a graphical -environment. You can have anti-aliasing if you use the `utf8` separator. -Note that by default the `utf8` separator is used in a terminal. -See the powerline section in the [documentation][powerline-doc]. - -7. **Why is after-init-hook not executed ?** -Don't launch Spacemacs with `emacs -q -l init.el` command. This command will -run the hooked function in `after-init-hook` before the evaluation of the -passed `-l init.el` file. - -## Windows - -1. **Why do the fonts look crappy on Windows ?** -You can install [MacType][] on Windows to get very nice looking fonts. It is -also recommended to disable smooth scrolling on Windows. - -2. **Why is there no Spacemacs logo in the startup buffer ?** -A GUI build of emacs supporting image display is required. -You can follow the instructions [here][Windows Image Support]. Alternatively you -can download binaries of emacs with image support -included such as [this one][emacs-for-windows]. - -## OS X - -1. **Why are the powerline colors not correct on OS X ?** -This is a [known issue][powerline-srgb-issue] as of Emacs 24.4 due to -`ns-use-srgb-colorspace` defaulting to true. It is recommended to use -the [emacs-mac-port][] build. See the [install OSX section][] for more -details. - [Twitter]: http://i.imgur.com/tXSoThF.png [CONTRIBUTE.org]: doc/CONTRIBUTE.org [CONVENTIONS.org]: doc/CONVENTIONS.org [DOCUMENTATION.org]: doc/DOCUMENTATION.org +[QUICK_START.org]: doc/QUICK_START.org +[FAQ.org]: doc/FAQ.org [HOWTOs.org]: doc/HOWTOs.org [VIMUSERS.org]: doc/VIMUSERS.org -[config]: doc/DOCUMENTATION.org#configuration-layers [dotfile]: doc/DOCUMENTATION.org#dotfile-configuration -[manage_config]: doc/DOCUMENTATION.org#managing-private-configuration-layers -[using_package_buf]: doc/DOCUMENTATION.org#using-the-package-list-buffer [troubleshoot]: doc/DOCUMENTATION.org#troubleshoot -[contrib layers]: doc/DOCUMENTATION.org#using-configuration-layers -[Git support]: contrib/!source-control/git/README.org -[git layer]: contrib/!source-control/git -[ace-jump]: doc/DOCUMENTATION.org#vim-motions-with-ace-jump-mode -[project management]: doc/DOCUMENTATION.org#project-management -[Evil Mode]: doc/DOCUMENTATION.org#evil -[private]: ./private -[layers]: ./contrib -[font section]: doc/DOCUMENTATION.org#font -[powerline-seps]: doc/DOCUMENTATION.org#powerline-separators -[FAQ]: https://github.com/syl20bnr/spacemacs#faq -[dotfile template]: ./core/templates/.spacemacs.template -[install OSX section]: https://github.com/syl20bnr/spacemacs#os-x [osx layer]: contrib/osx/README.org -[which-key]: https://github.com/justbur/emacs-which-key -[evil-nerd-commenter]: https://github.com/redguardtoo/evil-nerd-commenter [Gitter Chat]: https://gitter.im/syl20bnr/spacemacs [Gitter Chat IRC server]: https://irc.gitter.im/ -[MacType]: https://code.google.com/p/mactype/ [emacs-mac-port]: https://github.com/railwaycat/homebrew-emacsmacport [emacs-mac-port-server]: https://github.com/railwaycat/emacs-mac-port/blob/master/README-mac#L210-L213 -[homebrew]: https://github.com/Homebrew/homebrew [emacs-for-windows]: http://emacsbinw64.sourceforge.net/ [the platinum searcher]: https://github.com/monochromegane/the_platinum_searcher -[powerline-srgb-issue]: https://github.com/milkypostman/powerline/issues/54 -[powerline-doc]: doc/DOCUMENTATION.org#powerline-separators [so-server-unsafe]: http://stackoverflow.com/questions/885793/emacs-error-when-calling-server-start [Spacemacs logo]: https://github.com/nashamri/spacemacs-logo [Nasser Alshammari]: https://github.com/nashamri [cpaulik-unity-icon]: http://splendidabacus.com/posts/2015/03/spacemacs-unity-icon/ -[Windows Image Support]: http://stackoverflow.com/questions/2650041/emacs-under-windows-and-png-files +[icon-mac-instructions]: http://www.idownloadblog.com/2014/07/16/how-to-change-app-icon-mac/ +[icon-repository]: https://github.com/nashamri/spacemacs-logo diff --git a/doc/FAQ.org b/doc/FAQ.org new file mode 100644 index 000000000000..6671c5888e0f --- /dev/null +++ b/doc/FAQ.org @@ -0,0 +1,61 @@ +* FAQ :TOC@4: + - [[#common][Common]] + - [[#which-version-of-spacemacs-am-i-running-][Which version of Spacemacs am I running ?]] + - [[#what-is-the-official-pronunciation-of-spacemacs-][What is the official pronunciation of Spacemacs ?]] + - [[#why-are-packages-installed-with-package-install-automatically-deleted-by-spacemacs-when-it-boots-][Why are packages installed with =package-install= automatically deleted by Spacemacs when it boots ?]] + - [[#the-spacemacs-banner-is-ugly-what-should-i-do-][The Spacemacs banner is ugly, what should I do ?]] + - [[#the-powerline-separators-are-ugly-how-can-i-fix-them-][The powerline separators are ugly, how can I fix them ?]] + - [[#the-powerline-separators-have-no-anti-aliasing-what-can-i-do-][The powerline separators have no anti-aliasing, what can I do ?]] + - [[#why-is-after-init-hook-not-executed-][Why is after-init-hook not executed ?]] + - [[#windows][Windows]] + - [[#why-do-the-fonts-look-crappy-on-windows-][Why do the fonts look crappy on Windows ?]] + - [[#why-is-there-no-spacemacs-logo-in-the-startup-buffer-][Why is there no Spacemacs logo in the startup buffer ?]] + - [[#os-x][OS X]] + - [[#why-are-the-powerline-colors-not-correct-on-os-x-][Why are the powerline colors not correct on OS X ?]] + +** Common +*** Which version of Spacemacs am I running ? +The version is displayed on the upper right corner of the loading screen. +You may also just type ~SPC f e v~. + +*** What is the official pronunciation of Spacemacs ? +As it is written, that is _space_ then _macs_. + +*** Why are packages installed with =package-install= automatically deleted by Spacemacs when it boots ? +To declare new packages you have to create a new configuration layer, see +the [[file:QUICK_START.org][quick start guide]]. + +*** The Spacemacs banner is ugly, what should I do ? +Install the default font supported by Spacemacs or choose a fixed width font. +More information in the font section of the [[file:DOCUMENTATION.org][documentation]]. + +*** The powerline separators are ugly, how can I fix them ? +Use the property =:powerline-scale= of the variable +=dotspacemacs-default-font=. See font section of the [[file:DOCUMENTATION.org][documentation]] for more details. + +*** The powerline separators have no anti-aliasing, what can I do ? +Emacs powerline uses XMP images to draw the separators in a graphical +environment. You can have anti-aliasing if you use the =utf8= separator. +Note that by default the =utf8= separator is used in a terminal. +See the powerline section in the font section of the [[file:DOCUMENTATION.org][documentation]]. + +*** Why is after-init-hook not executed ? +Don't launch Spacemacs with =emacs -q -l init.el= command. This command will +run the hooked function in =after-init-hook= before the evaluation of the +passed =-l init.el= file. + +** Windows +*** Why do the fonts look crappy on Windows ? +You can install [[https://code.google.com/p/mactype/][MacType]] on Windows to get very nice looking fonts. It is +also recommended to disable smooth scrolling on Windows. + +*** Why is there no Spacemacs logo in the startup buffer ? +A GUI build of emacs supporting image display is required. +You can follow the instructions [[http://stackoverflow.com/questions/2650041/emacs-under-windows-and-png-files][here]]. Alternatively you can download binaries +of emacs with image support included such as [[http://emacsbinw64.sourceforge.net/][this one]]. + +** OS X +*** Why are the powerline colors not correct on OS X ? +This is a [[https://github.com/milkypostman/powerline/issues/54][known issue]] as of Emacs 24.4 due to =ns-use-srgb-colorspace= +defaulting to true. It is recommended to use the [[github.com/railwaycat/homebrew-emacsmacport][emacs-mac-port]] build. +See the install section in the [[file:../README.md][README]] for more details. diff --git a/doc/QUICK_START.org b/doc/QUICK_START.org new file mode 100644 index 000000000000..f08063160989 --- /dev/null +++ b/doc/QUICK_START.org @@ -0,0 +1,159 @@ +* Configuration :TOC@4: + - [[#configuration-layers][Configuration layers]] + - [[#dotfile-spacemacs][Dotfile (.spacemacs)]] + - [[#dotdirectory-spacemacsd][Dotdirectory (~/.spacemacs.d)]] + - [[#learning-spacemacs][Learning Spacemacs]] + - [[#editing-styles][Editing Styles]] + - [[#the-leader-keys][The leader keys]] + - [[#evil-tutor][Evil-tutor]] + - [[#universal-argument][Universal argument]] + - [[#configuration-layers-and-package-discovery][Configuration layers and Package discovery]] + - [[#key-bindings-discovery][Key bindings discovery]] + - [[#describe-functions][Describe functions]] + - [[#how-tos][How-To's]] + +** Configuration layers +Spacemacs divides its configuration into self-contained units called +=configuration layers=. These layers are stacked on top of each other +to achieve a custom configuration. + +By default Spacemacs uses a dotfile called =~/.spacemacs= to control which +layers to load. Within this file you can also configure certain features. + +A configuration layer is a directory containing at least a =packages.el= +file which defines and configures packages to be downloaded from Emacs +package repositories using the =package.el= built-in feature of Emacs. + +If you already have your own =Emacs= configuration you can move it to your +own layer. + +The following command creates a layer in the =private= directory: + +#+BEGIN_SRC + : configuration-layer/create-layer RET +#+END_SRC + +Any configuration layers you create must be explicitly loaded in =~/.spacemacs=. + +Note: For your privacy, the contents of the =private= directory are not +under source control. See the section on private configuration management in +the [[file:DOCUMENTATION.org][documentation]]. + +** Dotfile (.spacemacs) +As mentioned =.spacemacs= controls which configuration layers to load and +is also a means to customizing Spacemacs. + +The following command will create a =.spacemacs= file in your home directory: + +#+BEGIN_EXAMPLE + : dotspacemacs/install RET +#+END_EXAMPLE + +To open the installed dotfile: + +#+BEGIN_EXAMPLE + f e d +#+END_EXAMPLE + +To load some configuration layers using the variable +=dotspacemacs-configuration-layers=: + +#+BEGIN_SRC elisp +;; List of configuration layers to load. +dotspacemacs-configuration-layers '(auto-completion smex) +#+END_SRC + +Some configuration layers support configuration variables to expose granular +control over layer-specific features, [[file:../layers/+source-control/git/README.org][git layer]] being one such example. +Variables can be directly set within =dotspacemacs-configuration-layers= like so: + +#+BEGIN_SRC elisp +;; List of configuration layers to load. +dotspacemacs-configuration-layers '(auto-completion + (git :variables + git-magit-status-fullscreen t) + smex) +#+END_SRC + +At anytime you can apply the changes made to the dotfile or layers +_without restarting_ Spacemacs by pressing ~SPC f e R~. + +The [[file:../core/templates/.spacemacs.template][dotfile template]] contain further information about how to customize +Spacemacs. See the dotfile configuration section of the [[file:DOCUMENTATION.org][documentation]] for +more details. + +** Dotdirectory (~/.spacemacs.d) +Like =Emacs=, Spacemacs initialization can also be contained in an =init.el= file +in a special directory =~/.spacemacs.d=. The contents of the dotfile should be +then copied in the =init.el= file. + +** Learning Spacemacs +*** Editing Styles +Spacemacs can be used by Vim users or Emacs users by setting the +=dotspacemacs-editing-style= variable to =vim=, =emacs= or even =hybrid= +in the dotfile =~/.spacemacs=. + +*** The leader keys +=Spacemacs= key bindings use a leader key which is by default bound to +~SPC~ (space bar) in =vim= or =hybrid= editing styles and ~M-m~ in =emacs= +style. + +You can change it by setting the variable =dotspacemacs-leader-key= if +you use the =vim= style or =dotspacemacs-emacs-leader-key= if you use +the =emacs= style (these variables must be set in the file =~/.spacemacs=). + +For simplicity the documentation always refers to the leader key as +~SPC~. + +There is secondary leader key called the major-mode leader key which is +set to ~,~ by default. This key is a shortcut for ~SPC m~ +where all the major-mode specific commands are bound. + +*** Evil-tutor +If you are willing to learn the Vim key bindings (highly recommended since +you can benefit from them even in =emacs= style), press ~SPC h T~ +to begin an Evil-adapted Vimtutor. + +*** Universal argument +In =vim= editing style the universal argument defaults to ~SPC u~ +instead of ~C-u~ because the latter is used to scroll up as in Vim. + +*** Configuration layers and Package discovery +By using =helm-spacemacs= with ~SPC f e h~ you can quickly search +for a package and get the name of the layers using it. + +You can also easily go to the =README.org= of a layer or go to the initialization +function of a package. + +*** Key bindings discovery +Thanks to [[https://github.com/justbur/emacs-which-key][which-key]], whenever a prefix command is pressed (like ~SPC~) +a buffer appears after one second listing the possible keys for this prefix. + +It is also possible to search for specific key bindings by pressing: + +#+BEGIN_EXAMPLE + SPC ? +#+END_EXAMPLE + +To narrow the bindings list to those prefixed with =SPC=, +type a pattern like this regular expression: + +#+BEGIN_EXAMPLE + SPC\ b +#+END_EXAMPLE + +which would list all =buffer= related bindings. + +*** Describe functions +=Describe functions= are powerful Emacs introspection commands to get information +about functions, variables, modes etc. These commands are bound thusly: + +| Key Binding | Description | +|-------------+-------------------| +| ~SPC h d f~ | describe-function | +| ~SPC h d k~ | describe-key | +| ~SPC h d m~ | describe-mode | +| ~SPC h d v~ | describe-variable | + +** How-To's +Some quick =how-to's= are compiled in the [[file:HOWTOs.org][HOWTOs.org]] file.