Skip to content

Commit

Permalink
Improved link formatting, minor text edits
Browse files Browse the repository at this point in the history
Also fixed a broken link
  • Loading branch information
Nikolai Myllymäki authored and syl20bnr committed Apr 2, 2017
1 parent f106fcc commit fdc4895
Showing 1 changed file with 37 additions and 40 deletions.
77 changes: 37 additions & 40 deletions doc/BEGINNERS_TUTORIAL.org
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@
- [[#adding-language-support-and-other-features-using-layers][Adding language support and other features: using layers]]
- [[#changing-the-colour-theme][Changing the colour theme]]
- [[#starting-maximized][Starting maximized]]
- [[#quitting-restarting][Quitting (restarting)]]
- [[#quitting][Quitting]]
- [[#additional-features-tips-and-troubleshooting][Additional features, tips and troubleshooting]]
- [[#org-mode][Org mode]]
- [[#version-control---the-intelligent-way][Version control - the intelligent way]]
Expand All @@ -29,21 +29,19 @@

* Why Spacemacs?
- Unparallelled text and structure editing for all types of writing tasks:
creative writing, blogging, note-taking, todo-lists, scientific papers...
creative writing, blogging, note-taking, todo-lists, scientific papers...
- Powerful modes for programming in dozens of programming languages
- Deeply customizable yet beginner-friendly

* Install
Spacemacs is a beginner-friendly and powerful extension of a popular text
editor called Emacs. To install Spacemacs you need to first install base Emacs
and then download and install the Spacemacs extension files, which is easiest
done by using a program called Git. The steps are easy and outlined below.
and then download the Spacemacs extension files, which is most easily done by
using a program called Git. The steps are easy and outlined below.

** 1. Install Emacs
Follow the instructions in https://github.com/syl20bnr/spacemacs#prerequisites.
** 1. [[https://github.com/syl20bnr/spacemacs#prerequisites][Install Emacs]]

** 2. Install Git
Go to https://git-scm.com/downloads and install Git on your platform.
** 2. [[https://git-scm.com/downloads][Install Git]]

** 3. Install Spacemacs
Open a terminal or command prompt, paste the following code to it:
Expand Down Expand Up @@ -71,7 +69,7 @@ The default font used by Spacemacs is Source Code Pro by Adobe. It is
recommended to [[https://github.com/adobe-fonts/source-code-pro][install]] it on your system to ensure correct visual
representation.

** 5. Open Spacemacs and choose default editing style
** 5. Open Spacemacs and choose default editing style
Open Spacemacs by clicking the Emacs icon in your applications menu. The first
time Spacemacs launches, it will load and install packages and prompt you for
your preferred editing style. You have two options: Vim ("Among the stars aboard
Expand All @@ -87,12 +85,12 @@ so if modal editing does not sweep you away, you can switch to the Emacs style
later.

Next, you will be prompted for the distribution you would like to start with.
The standard distribution is recommended, press enter to select it.
The standard distribution is recommended, press enter to select it.

Now Spacemacs will download and install required packages. This will take some
minutes depending on your connection. After everything is installed (you will
see the text "n packages loaded in x s" appear in the list under the Spacemacs
logo), restart Spacemacs.
logo), restart Spacemacs.

Now your installation process is complete, congratulations! For troubleshooting,
see the last section.
Expand All @@ -105,7 +103,7 @@ modifier keys are:

~SPC~ = ~Space~, used as the leader key in Vim editing style.
~C-~ = ~Ctrl~
~M-~ (for "meta") = ~Alt~
~M-~ (for "meta") = ~Alt~
~S-~ = ~Shift~

The modifier keys can be used either in a sequence or as key chords by pressing
Expand All @@ -124,7 +122,7 @@ the commands that begin with ~SPC~.
(Note: Other modifier keys such as ~Super~, notated with a small-case ~s-~, can
be set up but this is rarely necessary in Spacemacs).

** Modal text editing - why and how?
** Modal text editing - why and how?
Writing (or programming) is typically not a simple linear process of adding
words and lines until finished. At least as important part of the work consists
of editing the text: deleting and rewriting parts, moving sentences around or
Expand All @@ -135,7 +133,7 @@ the line in question, clicking on the line and then deleting it by pressing
backspace repeatedly. This is slow and inefficient, both because you have to
take your hands from your keyboard and because repeatedly pressing backspace
takes time. The more time you spend pressing keys, the more time and energy is
wasted.
wasted.

To speed up editing, many editors use key chords for common editing tasks:
~Control-c~ for copying and so on. However, these types of shortcuts tend to
Expand All @@ -157,11 +155,11 @@ You might have noticed that this was achieved entirely without moving your
fingers from your home row (the row where your fingers lie in rest when
touch-typing) and without using modifier keys.

** Start the Vim tutorial
** Start the Vim tutorial
The modal editing features of Spacemacs originate from a text editor called Vi,
and thus the modal editing tutorial is called eVIl tutor. Press ~SPC h T~ (that
is, the spacebar followed by ~h~ and ~T~) to familiarize yourself with
modal editig.
is, the spacebar followed by ~h~ and ~T~) to familiarize yourself with
modal editig.

** Using the spacebar to launch commands
Now that you are familiar with writing and editing text it is time to put the
Expand All @@ -172,7 +170,7 @@ Spacemacs.

** Buffers, windows and frames
Because Emacs (the extension of which Spacemacs is) was developed in the 80's
before the advent of modern graphical user interfaces, Emacs has
before the advent of modern graphical user interfaces, Emacs has
a different name of what we normally call "windows": in Emacs these are
called "frames". A frame is what pops up when you launch Spacemacs from your
desktop shortcut. A frame contains windows and buffers.
Expand Down Expand Up @@ -205,7 +203,8 @@ not the scratch buffer, so the buffer is still open beneath the surface. You can
quickly switch between the current buffer and the last with ~SPC TAB~: use this
a couple of times to switch between the tutorial and the scratch buffer. ~SPC b~
has more options for switching between buffers, for example ~SPC b b~ opens a
searchable list of all currently open buffers.
searchable list of all currently open buffers and ~SPC b d~ closes the current
buffer.

* Configuring Spacemacs
** Adding language support and other features: using layers
Expand All @@ -219,8 +218,9 @@ the window vertically to view both this tutorial and the dotfile simultaneously
(~SPC w /~). Open the dotfile by pressing ~SPC f e d~. Navigate to the line
starting with "dotspacemacs-configuration-layers". The following lines have
further instructions: uncomment org and git layers if you want to be
familiarized with them. More languages and layers can be found at
https://github.com/syl20bnr/spacemacs/tree/master/layers.
familiarized with them. More layers for different languages and tools can be
found on [[https://github.com/syl20bnr/spacemacs/tree/master/layers][github]] or by pressing ~SPC h SPC~. The added layers will be installed
upon restart of Spacemacs.

Mac users: add the osx layer to use the OS X keybindings!

Expand All @@ -233,30 +233,28 @@ activate them by writing their names in the dotspacemacs-themes list.
Editing the dotspacemacs-maximized-at-startup variable from nil to t will start
Spacemacs maximized.

** Quitting (restarting)
** Quitting
Save the changes you've made to the dotfile with ~SPC f s~ and then quit emacs
by ~SPC q q~. You can return to this tutorial by clicking it on the home screen!

* Additional features, tips and troubleshooting
** Org mode
Org mode is one of the best features of Spacemacs and enough reason to warrant
its use. Org mode's official description tells that it is "for
keeping notes, maintaining todo lists, planning projects, and authoring
documents with a fast and effective plain-text system", but this gives only a
small inkling of its versatility. If you do any kind of writing at all, chances
are that Org mode will make it easier and more fun. This tutorial was written in
Org mode.
its use. Org mode's official description tells that it is "for keeping notes,
maintaining todo lists, planning projects, and authoring documents with a fast
and effective plain-text system", but this gives only a small inkling of its
versatility. If you do any kind of writing at all, chances are that Org mode
will make it easier and more fun. This tutorial was written in Org mode.

Install the Org layer and open this tutorial. Press ~S-TAB~ repeatedly and
observe that this cycles the visibility of the contents of different headlines.
Press t in normal mode and observe that you can add TODO tags on headlines.
Press ~M-k~ or ~M-j~ in normal mode and see how you can quickly move parts of
the document around.

This is not even scratching the surface of Org mode, so you should look into
[[../layers/%2Bemacs/org][org layer]] for more
information. Googling for Org mode tutorials is also very helpful in finding out
the most useful features of it!
This is not even scratching the surface of Org mode, so you should look into its
[[https://github.com/syl20bnr/spacemacs/blob/master/layers/%252Bemacs/org/README.org][documentation]] for more information. Googling for Org mode tutorials is also very
helpful in finding out the most useful features of it!

** Version control - the intelligent way
Version control means keeping track of the changes and edits you have made to
Expand All @@ -280,22 +278,21 @@ commited: press c and c again. Two windows pop up: one showing the changes
you've made since the last edit (in this case, the whole document) and another
prompting for a commit message. Write "Initial commit", press ESC to exit back
to normal mode and press ~, c~ confirm and quit the commit
message. To abort, press ~, a~.
message. To abort, press ~, a~.

Now you know how to make a commit. The commits are saved in
the (hidden) .git folder in the same folder the tracked file(s) are in. You can
make further commits the same way.

** Daemon mode and instant startup (Linux)
** Daemon mode and instant startup (Linux)
Emacs can be used in daemon mode: a daemon runs in the background and launches
clients. This way new frames launch instantly without delay.
https://www.emacswiki.org/emacs/EmacsAsDaemon tells more about the daemon
and how to set it to launch automatically on startup.
clients. This way new frames launch instantly without delay. [[https://www.emacswiki.org/emacs/EmacsAsDaemon][Emacswiki]] tells
more about the daemon and how to set it to launch automatically on startup.

** Swap caps lock and esc keys on your keyboard
This is useful outside of Spacemacs as well!

** FAQ and troubleshooting
For troubleshooting, please refer to the FAQ by pressing ~SPC f e f~ or [[https://github.com/syl20bnr/spacemacs/blob/master/doc/FAQ.org][online]].
More help is found under ~SPC h~, and with ~SPC h ~SPC~ you can access Spacemacs
documentation, including this tutorial.
More help is found under ~SPC h~, and with ~SPC h ~SPC~ you can access the
complete Spacemacs documentation, including this tutorial.

0 comments on commit fdc4895

Please sign in to comment.