diff --git a/README.md b/README.md index b7886240b..686ba1fe9 100644 --- a/README.md +++ b/README.md @@ -3,11 +3,11 @@ ***

Spacemacs

-philosophy +philosophy | -for whom? +for whom? | -screenshots +screenshots | documentation | @@ -64,40 +64,36 @@ # Introduction +Spacemacs is a new way of experiencing Emacs -- it's a sophisticated and +polished set-up, focused on ergonomics, mnemonics and consistency. -Spacemacs is a new way to experience Emacs -- a sophisticated and -polished set-up focused on ergonomics, mnemonics and consistency. +Just clone and launch it, then press the space bar to explore the interactive +list of carefully-chosen key bindings. You can also press the home buffer's +`[?]` button for some great first key bindings to try. -Just clone it, launch it, then press the space bar to explore the -interactive list of carefully-chosen key bindings. You can also press -the home buffer's `[?]` button for some great first key bindings to -try. +Spacemacs can be used naturally by both Emacs and Vim users -- you can even mix +the two editing styles. Being able to quickly switch between input styles, makes +Spacemacs a great tool for pair-programming. -Spacemacs can be used naturally by both Emacs and Vim users -- you can -even mix the two editing styles. Switching easily between input styles -makes Spacemacs a great tool for pair-programming. - -Spacemacs is currently in beta, and contributions are very welcome. +Spacemacs is currently in beta, and any contributions are very welcome. ![spacemacs_python](doc/img/spacemacs-python.png) # Features - -- **Great documentation:** access documentation in Emacs with +- **Great documentation:** access the Spacemacs documentation with SPC h SPC. - **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. +- **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. +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]. # Documentation - Comprehensive documentation is available for each layer by pressing SPC h SPC. @@ -105,7 +101,6 @@ You can also check the [general documentation][DOCUMENTATION.org], [quick start guide][QUICK_START.org] and the [FAQ][FAQ.org]. # Getting Help - If you need help, ask your question in the [Gitter Chat][] and a member of the community will help you out. @@ -113,38 +108,43 @@ If you prefer IRC, connect to the [Gitter Chat IRC server][] and join the `#syl20bnr/spacemacs` channel. # Prerequisites - Spacemacs is an extension of a popular text editor called Emacs. Thus you need to first install base Emacs and then download the Spacemacs extension files with Git. ## Emacs - -Spacemacs requires Emacs 24.4 or above. The development version of Emacs (at the -time of writing, this is 25.2) is not *officially* supported, but should -nevertheless be expected to work. +Spacemacs requires Emacs 24.4 or above. The development version of Emacs is not +*officially* supported, but it should nevertheless be expected to work. Some modes require third-party tools that you'll have to install via your favorite package manager. ### Linux distros +Install the `emacs` package with your linux distributions package manager. -Install Emacs from the package manager of your Linux distribution. +Do not install the `xemacs` package. It's not supported by Spacemacs. XEmacs is +an old fork of Emacs, but it's development has stopped. The X in its name is +unrelated to X11. -You should install the "emacs" package, not the "xemacs" package. -XEmacs is an old fork of Emacs. The X in its name is unrelated to X11. -Both Emacs and XEmacs have graphical support. +Emacs has graphical support. -**Note:** Ubuntu LTS 12.04 and 14.04 repositories have only Emacs 24.3 -available. You have to [build from source][build_source] Emacs 24.4 or greater, -as Spacemacs won't work with 24.3. The same may be true for other distributions -as well. +**Note:** The Ubuntu LTS 12.04 and 14.04 repositories only have Emacs version +24.3 available. Version 24.4 or greater needs to be [built from source][build_source]. +This might also be true for other linux distributions. ### macOS - -The recommended way of installing Emacs on macOS is using [Homebrew][], a +The recommended way of installing Emacs on macOS is using [Homebrew][]. It's a package manager for macOS. Once Homebrew is installed, run the following -commands in terminal to install both Emacs and the default Source Code Pro font: +commands in the terminal to install both Emacs and the default Source Code Pro +font: + +*Note*: if you want the title bar to match your themes background color, use +this command: + +``` sh +brew install emacs-plus --HEAD --with-natural-title-bar +``` +instead of `brew install emacs-plus` below: ```sh brew tap d12frosted/emacs-plus @@ -155,55 +155,50 @@ brew cask install font-source-code-pro ``` *Note:* these Homebrew commands will install GNU Emacs, and link it to your -`/Applications` directory. You still need to run the `git clone` mentioned at -the start of this file. That will populate your `~/.emacs.d` directory, which is -what transforms a regular GNU Emacs into Spacemacs. +`/Applications` directory. You still need to run the following command: +```sh + git clone https://github.com/syl20bnr/spacemacs ~/.emacs.d +``` +It populates your `~/.emacs.d` directory, so that the regular GNU Emacs +transforms into Spacemacs. *Note:* the proposed `emacs-plus` tap is identical to the `emacs` formulae, it -just builds GNU Emacs with support of several features by default along with -providing Spacemacs icon. -See [emacs-plus](https://github.com/d12frosted/homebrew-emacs-plus) for more -information. +just builds GNU Emacs with support for several features by default, including +the Spacemacs icon. See [emacs-plus][] for more information. -*Note*: to have the title bar match your theme background color, -consider using instead: +*Note:* after completing the Spacemacs [install process](#install), then +it's also recommended to add the [osx layer][] to your [dotfile][]. Installation +instructions are available in the documentation for the [osx layer][]. -``` sh -brew install emacs-plus --HEAD --with-natural-title-bar -``` - -*Note:* after you have completed the [install process](#install) below, it is -also recommended to add the [osx layer][] to your [dotfile][]. Install -instructions are available in the [osx layer][] documentation. - -*Note:* if the powerline separators on the spaceline are a different (less -saturated) color than the rest of the line, you can add following snippet to -`dotspacemacs/user-config` in your `.spacemacs` file. +*Note:* if the powerline separators on the spaceline have a different (less +saturated) color than the rest of the line, then you can add the following +snippet to the `dotspacemacs/user-config` section in your `~/.spacemacs` file. ```elisp (setq ns-use-srgb-colorspace nil) ``` -Keep in mind that this is not ideal solution as it affects all colours in Emacs. -Another option is to use different powerline separator. For example, `alternate` -and `bar` diminish the difference. And using `utf-8` separator makes it go -away completely without the need to change colour space. In order to change -powerline separator put following snippet in `dotspacemacs/user-config`. +Keep in mind that this is not an ideal solution as it affects all colours in +Emacs. Another option is to change the powerline separators. For example to +`alternate` or `bar`, they diminish the color difference. Or change them to +`utf-8`, which makes them go away completely, without having to change colour +space. In order to change the powerline separators, put the following snippet in +the `dotspacemacs/user-config` section of your `~/.spacemacs` file. ```eslip (setq powerline-default-separator 'utf-8) ``` -For more information about powerline separators, please refer to appropriate -section in [Documentation][DOCUMENTATION.org]. +For more information about powerline separators, please refer to the +[powerline documentation][] ### Windows - You can download good quality builds from the [emacs-w64 project][emacs-for-windows]. It is recommended to install the most recent [stable build][emacs-for-windows-stable]. -Be sure to declare an environment variable named `HOME` pointing to your user -directory `C:\Users\`. Then you can clone Spacemacs in this directory. +Be sure to declare an environment variable named `HOME` that's pointing to your +user directory `C:\Users\`. Then you can clone Spacemacs into that +directory. Sometimes you'll get the following error when you first start Emacs: @@ -219,13 +214,11 @@ To fix it change the owner of the directory `~/.emacs.d/server`: Source: [Stack Overflow][so-server-unsafe] -For efficient searches we recommend to install `pt` ([the platinum searcher][]). +For efficient searches we recommend installing `pt` ([the platinum searcher][]). `pt` version 1.7.7 or higher is required. # Install - ## Default installation - 1. If you have an existing Emacs configuration, back it up first by running the following code in your terminal: @@ -235,9 +228,9 @@ For efficient searches we recommend to install `pt` ([the platinum searcher][]). mv .emacs .emacs.bak ``` - Don't forget to backup and *remove* `~/.emacs` file otherwise Spacemacs - **WILL NOT** load since that file prevents Emacs from loading the proper - initialization file. + Don't forget to backup and *remove* the `~/.emacs` file. Otherwise Spacemacs + **WILL NOT** be able to load. Because that file prevents Emacs from loading + the proper initialization file. 2. Clone the repository with [Git][]: @@ -247,15 +240,15 @@ For efficient searches we recommend to install `pt` ([the platinum searcher][]). `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 + fork Spacemacs safely, use the `develop` branch where you'll handle updates manually. **Note for Windows users** - If you use windows, you have to modify the git command by inserting the - correct path to your .emacs.d folder. The dot before the folder means that it - is hidden, so you'll have to search for hidden files to find the folder. When - you have found the folder, substitute the original path with the correct one. - The proper code would look something like this: + If you use windows, then you'll have to modify the git command by inserting + the correct path to your `.emacs.d` folder. The dot before the folder means + that it's hidden. You'll have to search for hidden files to find the folder. + When you have found the folder, substitute the original path with the correct + one. The proper code would look something like this: ```sh git clone https://github.com/syl20bnr/spacemacs /path/to/your/.emacs.d @@ -263,57 +256,84 @@ For efficient searches we recommend to install `pt` ([the platinum searcher][]). 3. Install the default fonts - The default font used by Spacemacs is [Source Code Pro][] by Adobe. It is - recommended to install it to ensure correct visual representation. Also a - "Fallback font" for nicer-looking symbols in the modeline (bottom bar) is - recommended. These depend on the system: + It's recommended to install [Source Code Pro][] by Adobe, as the default + font. It ensures that, for example the symbols on the modeline (bottom bar) + looks correct. It's also recommended to use a "Fallback font". These + depend on the system: - GNU/Linux: *NanumGothic* (package named *fonts-nanum* on Debian, for example) - macOS: *Arial Unicode MS* - Windows: *MS Gothic* or *Lucida Sans Unicode* - If the modeline doesn't look as great as in the pictures, make sure you have - the correct fallback font installed. + If the modeline doesn't look similar to the + [picture at the top of this page](#introduction), then make sure you have the + correct fallback font installed. - If you are running in terminal you'll also need to change font settings of - your terminal. + If you're running in a terminal then you'll also need to change the terminals + font settings. -4. Launch Emacs. Spacemacs will automatically install the packages it requires. - Finally, restart Emacs to complete the installation. +4. Launch Emacs, and answer three questions in the: Dotfile wizard installer + ``` + What is your preferred editing style? + -> Among the stars aboard the Evil flagship (vim) + On the planet Emacs in the Holy control tower (emacs) -**Note:** If you get an error regarding package downloads then you may try to - disable the HTTPS protocol by starting Emacs with + What distribution of spacemacs would you like to start with? + -> The standard distribution, recommended (spacemacs) + A minimalist distribution that you can build on (spacemacs-base) + + What type of completion framework do you want? + -> A heavy one but full-featured (helm) + A lighter one but still very powerful (ivy) + None (not recommended) + ``` + If your new to Emacs and Spacemacs, then it's fine to just accept the default + choices: + ``` + editing style: vim + distribution: spacemacs + completion framework: helm + ``` + + It's easy to try the other choices later, without having to reinstall + Spacemacs. They can be changed in the dotfile `~/.spacemacs`. + + After answering the third question, then Spacemacs starts downloading and + installing the packages it requires. When the packages have been installed. + Restart Emacs to complete the installation. + +**Note:** If you get an error regarding package downloads, then you can try to + disable the HTTPS protocol by starting Emacs with the `--insecure` argument: ```sh emacs --insecure ``` - Or you can set the `dotspacemacs-elpa-https` to `nil` in your dotfile - `~/.spacemacs` 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 re-installed. + Or you can set the `dotspacemacs-elpa-https` variable to `nil` in your + dotfile `~/.spacemacs`. That will remove the need to start Emacs with the + `--insecure` argument. You may also want to clear out your `.emacs.d/elpa` + directory before doing this, so that any corrupted packages you may have + downloaded will be re-installed. **Note:** `error: Package 'package-build-' is unavailable` may occur due to heavy network taffic. You can fix it by setting the - `dotspacemacs-elpa-timeout` to `70` in your dotfile. + `dotspacemacs-elpa-timeout` variable to `70` in your dotfile. **Note:** `Warning (bytecomp)` and other compilation warnings are perfectly - normal. If curious, you can find out why these occur [here](https://github.com/quelpa/quelpa/issues/90#issuecomment-137982713). + normal. If your curious, you can find out why these occur +[here][compilation-warnings]. If the mode-line turns red then be sure to consult the [FAQ][FAQ.org]. ## Alternative installations - -It may be useful to clone Spacemacs outside Emacs dotdirectory `~/.emacs.d` so -you can try Spacemacs without replacing completely your own configuration. -There is currently two possibilities to support alternative location for -Spacemacs configuration. +There are currently, two supported, alternative locations, for a Spacemacs +configuration. ### Modify HOME environment variable - -This solution is ideal to quickly try Spacemacs without compromising your -existing configuration. +This solution is ideal for quickly trying Spacemacs without compromising your +existing configuration. Clone Spacemacs outside the Emacs dotdirectory +`~/.emacs.d` and modify the HOME environment variable. ```sh mkdir ~/spacemacs @@ -321,14 +341,13 @@ git clone https://github.com/syl20bnr/spacemacs.git ~/spacemacs/.emacs.d HOME=~/spacemacs emacs ``` -Note: If you're on Fish shell, you will need to modify the last command to: `env -HOME=$HOME/spacemacs emacs` +Note: If you're using the Fish shell, then you'll 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`: +If you've cloned Spacemacs into `~/.emacs.d/spacemacs/`, then drop the following +lines in the `~/.emacs.d/init.el` file: ```elisp (setq spacemacs-start-directory "~/.emacs.d/spacemacs/") @@ -336,34 +355,32 @@ Say you cloned Spacemacs in `~/.emacs.d/spacemacs/` then drop these lines in ``` ## Spacemacs logo - For Ubuntu users, follow this guide to [change the logo in Unity][cpaulik-unity-icon]. For Mac users, you need to [download the .icns version of the logo][icon-repository], -then [change the logo on Dock][icon-mac-instructions]. +then [change the logo on the Dock][icon-mac-instructions]. # Update - -Spacemacs has a built-in notification of a 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. +Spacemacs shows a notification when a new version is available (only when you +are on the default `master` branch). If you are on the `develop` branch then +you'll have to update the Spacemacs repository manually. ## Automatic update (on master branch) +When a new version is available then a little arrow appears in the mode-line. -When a new version is available a 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 mean that your -current version is older. +Its color depends on the number of versions that have been released since your +last update. Green means that you have a recent version, orange and red means +that you have an older version. ![powerline_update](doc/img/powerline-update.png) -Click on the arrow to update Spacemacs to the last version. +Click on the arrow to update Spacemacs to the latest version. ## Manual update (on master branch) - -(Remove the angle brackets when typing the lines below into your shell.) +Remove the `<` and `>` angle brackets when you're typing the lines below into +your shell. And replace the text: "tag version which you are updating to" with a +tagged version. This page lists the [latest tags][] ```sh git fetch @@ -371,33 +388,27 @@ git reset --hard ``` ## On develop branch - -1. Update Emacs packages by clicking (press `RET`) on the `[Update Packages]` - link of the starting page. - -2. Close Emacs and update the git repository: +1. Close Emacs and update the git repository: ```sh git pull --rebase ``` -3. Restart Emacs to complete the upgrade. +2. Restart Emacs to complete the upgrade. ## Revert to a specific version - -To revert to a specific version you just have to checkout the corresponding -branch, for instance to revert to the last `0.103`: +To revert to a specific version, just checkout the corresponding branch. For +instance to revert to version `0.200`, type the following command: ```sh - git checkout origin/release-0.103 + git checkout origin/release-0.200 ``` -**After you update, either manually, or automatically, you are advised to update - your packages by clicking the `[Update Packages]` button on the Spacemacs Home - Buffer.** +**After updating Spacemacs (either manually or automatically), then you also +should check if any updates are available for your packages. On the Spacemacs +Home Buffer `SPC b h`, click (press `RET`) on the `[Update Packages]` button.** # Quotes - [Quote][quote01] by [ashnur](https://github.com/ashnur): «I feel that spacemacs is an aircraft carrier and I am playing table tennis @@ -410,9 +421,8 @@ branch, for instance to revert to the last `0.103`: That is all» # Contributions - -Spacemacs is a community-driven project, it needs _you_ to keep it up to -date and propose great and useful configuration for all the things! +Spacemacs is a community-driven project, it needs _you_ to keep it up to date +and to propose great and useful configurations for all the things! Before contributing be sure to consult the [contribution guidelines][CONTRIBUTING.org] and [conventions][CONVENTIONS.org]. @@ -422,13 +432,11 @@ Here is a throughput graph of the repository for the last few weeks: [![Throughput Graph](https://graphs.waffle.io/syl20bnr/spacemacs/throughput.svg)](https://waffle.io/syl20bnr/spacemacs/metrics) # Communities - - [Gitter Chat] - [Stack Exchange] - [Reddit] # License - The license is GPLv3 for all parts specific to Spacemacs, this includes: - the initialization and core files - all the layer files @@ -440,18 +448,17 @@ For the packages shipped in this repository, you can refer to the files header. [Creative Commons Attribution-ShareAlike 4.0 International License.](http://creativecommons.org/licenses/by-sa/4.0/) # Supporting Spacemacs - The best way to support Spacemacs is to contribute to it either by reporting bugs, helping the community on the [Gitter Chat][] or sending pull requests. You can show your love for the project by getting cool Spacemacs t-shirts, mugs and more in the [Spacemacs Shop][]. -If you want to show your support financially you can contribute -to [Bountysource][] or buy a drink for the maintainer by clicking on -the [Paypal badge](#top). +If you want to show your support financially, then you can contribute to +[Bountysource][], or buy a drink for the maintainer by clicking on the +[Paypal badge](#top). -If you used spacemacs in a project and you want to show that fact, you can use +If you used spacemacs in a project, and you want to show that fact, you can use the spacemacs badge: [![Built with Spacemacs](https://cdn.rawgit.com/syl20bnr/spacemacs/442d025779da2f62fc86c2082703697714db6514/assets/spacemacs-badge.svg)](http://spacemacs.org) - For Markdown: @@ -481,19 +488,23 @@ Thank you! [QUICK_START.org]: http://spacemacs.org/doc/QUICK_START [FAQ.org]: http://spacemacs.org/doc/FAQ [VIMUSERS.org]: http://spacemacs.org/doc/VIMUSERS -[dotfile]: http://spacemacs.org/doc/DOCUMENTATION#orgheadline45 +[dotfile]: http://spacemacs.org/doc/DOCUMENTATION#dotfile-configuration [osx layer]: http://spacemacs.org/layers/+os/osx/README.html [Gitter Chat]: https://gitter.im/syl20bnr/spacemacs [Gitter Chat IRC server]: https://irc.gitter.im/ [Homebrew]: http://brew.sh +[emacs-plus]: https://github.com/d12frosted/homebrew-emacs-plus +[powerline documentation]: http://spacemacs.org/doc/DOCUMENTATION.html#powerline-separators [emacs-for-windows]: http://emacsbinw64.sourceforge.net/ [emacs-for-windows-stable]: https://sourceforge.net/projects/emacsbinw64/files/release/ [the platinum searcher]: https://github.com/monochromegane/the_platinum_searcher [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 +[compilation-warnings]: https://github.com/quelpa/quelpa/issues/90#issuecomment-137982713 [cpaulik-unity-icon]: http://splendidabacus.com/posts/2015/03/spacemacs-unity-icon/ [icon-mac-instructions]: http://www.idownloadblog.com/2014/07/16/how-to-change-app-icon-mac/ +[latest tags]: https://github.com/syl20bnr/spacemacs/tags [icon-repository]: https://github.com/nashamri/spacemacs-logo [Stack Exchange]: http://emacs.stackexchange.com/questions/tagged/spacemacs [Reddit]: https://www.reddit.com/r/spacemacs