From fdc489572a84735375750015b344cc80aefdcb84 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nikolai=20Myllym=C3=A4ki?= Date: Mon, 2 Jan 2017 07:17:22 +0200 Subject: [PATCH] Improved link formatting, minor text edits Also fixed a broken link --- doc/BEGINNERS_TUTORIAL.org | 77 ++++++++++++++++++-------------------- 1 file changed, 37 insertions(+), 40 deletions(-) diff --git a/doc/BEGINNERS_TUTORIAL.org b/doc/BEGINNERS_TUTORIAL.org index 7e603e921771..05af79bd6f9a 100644 --- a/doc/BEGINNERS_TUTORIAL.org +++ b/doc/BEGINNERS_TUTORIAL.org @@ -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]] @@ -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: @@ -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 @@ -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. @@ -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 @@ -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 @@ -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 @@ -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 @@ -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. @@ -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 @@ -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! @@ -233,19 +233,18 @@ 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. @@ -253,10 +252,9 @@ 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 @@ -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.