TakeV
/
spacemacs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update README.md: links/rewrites/missing words/etc

This commit is contained in:
duianto 2017-04-22 18:35:00 +02:00 committed by syl20bnr
parent 8131ed977a
commit c0c18cd185
1 changed files with 161 additions and 150 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

311
README.md
View File

@ -3,11 +3,11 @@
***
<p align="center"><img src="/doc/img/title2.png" alt="Spacemacs"/></p>
<p align="center">
<b><a href="http://spacemacs.org/doc/DOCUMENTATION#orgheadline5">philosophy</a></b>
<b><a href="http://spacemacs.org/doc/DOCUMENTATION#core-pillars">philosophy</a></b>
|
<b><a href="http://spacemacs.org/doc/DOCUMENTATION#orgheadline8">for whom?</a></b>
<b><a href="http://spacemacs.org/doc/DOCUMENTATION#who-can-benefit-from-this">for whom?</a></b>
|
<b><a href="http://spacemacs.org/doc/DOCUMENTATION#orgheadline7">screenshots</a></b>
<b><a href="http://spacemacs.org/doc/DOCUMENTATION#screenshots">screenshots</a></b>
|
<b><a href="http://spacemacs.org/doc/DOCUMENTATION.html">documentation</a></b>
|
@ -64,40 +64,36 @@
<!-- markdown-toc end -->
# 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
<kbd>SPC h SPC</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>.
- **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.
<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].
# Documentation
Comprehensive documentation is available for each layer by pressing
<kbd>SPC h SPC</kbd>.
@ -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\<username>`. 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\<username>`. 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 <tag version which you are updating to>
```
## 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