Rewrite README.md to make it lighter
And move some parts to QUICK_START.org and FAQ.org
This commit is contained in:
syl20bnr
parent
b45bc11851
commit
2ab7a2a60f
455
README.md
455
README.md
|
|
@ -1,5 +1,5 @@
|
|||
<a name="top"></a>
|
||||
[](https://gitter.im/syl20bnr/spacemacs?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [](https://travis-ci.org/syl20bnr/spacemacs) [](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=ESFVNPKP4Y742)[![Twitter][]](http://www.twitter.com/spacemacs)
|
||||
[](https://gitter.im/syl20bnr/spacemacs?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [](https://travis-ci.org/syl20bnr/spacemacs) [](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=ESFVNPKP4Y742) [](http://www.slant.co/topics/12/~what-are-the-best-programming-text-editors)][![Twitter][]](http://www.twitter.com/spacemacs)
|
||||
***
|
||||
<p align="center"><img src="/doc/img/title2.png" alt="Spacemacs"/></p>
|
||||
<p align="center">
|
||||
|
|
@ -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)
|
||||
|
||||
<!-- markdown-toc end -->
|
||||
|
||||
# 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
|
||||
- **Great documentation:** Access documentation in Emacs with
|
||||
<kbd>SPC f e h</kbd>
|
||||
- **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 <kbd>space bar</kbd> or <kbd>alt-m</kbd>.
|
||||
- **Mnemonic key bindings:** commands have mnemonic prefixes like
|
||||
<kbd>SPC b</kbd> for all the buffer commands or <kbd>SPC p</kbd> 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 integrates hundreds of ready-to-use packages thanks to a
|
||||
community-driven approach.
|
||||
# Documentation
|
||||
|
||||
Those packages are grouped in [layers][] and their configuration follow a set
|
||||
of rules gathered in [CONVENTIONS.org][].
|
||||
A comprehensive documentation is available for each layer by pressing
|
||||
<kbd>SPC f e h</kbd>.
|
||||
|
||||
**[Visit the Documentation][DOCUMENTATION.org]**
|
||||
To go to the general documentation [click here][DOCUMENTATION.org].
|
||||
|
||||
## Nice UI
|
||||
You can also check the [Quick Start guide][QUICK_START.org] and the
|
||||
[FAQ][FAQ.org].
|
||||
|
||||
Spacemacs looks good. It ships with quality themes and a beautiful mode-line.
|
||||
|
||||
|
||||
|
||||
## Excellent ergonomics
|
||||
|
||||
Spacemacs is designed around the [Evil Mode][] and a leader key. All the
|
||||
packages are customized to integrate seamlessly with Evil.
|
||||
|
||||
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.
|
||||
|
||||
## Convenient and Mnemonic Key Bindings
|
||||
|
||||
`Spacemacs` organizes key bindings into mnemonic groups. For example, commands
|
||||
to operate on the buffer are prefixed by `<SPC> b`, and commands to operate on
|
||||
the project are under `<SPC> p`.
|
||||
|
||||
### 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\<username>`. Then you can clone Spacemacs
|
||||
in this directory.
|
||||
Be sure to declare a environment variable named `HOME` pointing to your user
|
||||
directory `C:\Users\<username>`. 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
|
||||
:------------------------------------:|----------------------------------
|
||||
 | < 3 releases behind
|
||||
 | < 5 releases behind
|
||||
 | >= 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:
|
||||
|
||||
<SPC> : 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:
|
||||
|
||||
<SPC> : dotspacemacs/install RET
|
||||
|
||||
...to open the installed dotfile:
|
||||
|
||||
<SPC> 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 <kbd>SPC f e R</kbd>.
|
||||
|
||||
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
|
||||
<kbd>SPC</kbd> (space bar) in `vim` editing style and <kbd>M-m</kbd> 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
|
||||
<kbd>SPC</kbd>.
|
||||
|
||||
There is secondary leader key called the major-mode leader key which is
|
||||
set to <kbd>,</kbd> by default. This key is a shortcut for <kbd>SPC m</kbd>
|
||||
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 <kbd>SPC h T</kbd>
|
||||
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 <kbd>SPC f e h</kbd> 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
|
||||
--------------|------------------------------------------------------------------
|
||||
`<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 [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 <kbd>SPC f e v</kbd>.
|
||||
|
||||
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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
<SPC> : 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
|
||||
<SPC> : dotspacemacs/install RET
|
||||
#+END_EXAMPLE
|
||||
|
||||
To open the installed dotfile:
|
||||
|
||||
#+BEGIN_EXAMPLE
|
||||
<SPC> 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.
|
||||
Loading…
Reference in New Issue